Adopt ant-design-vue and a shared antdTheme for leads, pipeline, invoices, and shared form controls under strict single-page governance. Co-authored-by: Cursor <cursoragent@cursor.com>
5.4 KiB
5.4 KiB
name, description
| name | description |
|---|---|
| antd-system-architect | Architect and migrate Montact web UI to Ant Design Vue v4 under strict governance: single-page lock, no manual CSS, no manual size props, default controlHeight 36, 24-column grid, central antdTheme, isolated from legacy components/ui. Use when migrating a page to Ant Design, adding Ant components, editing antdTheme, or reviewing Ant PRs. |
Ant Design Vue System Architect (Montact)
When to use
- Migrating any
apps/webview/page to Ant Design Vue 4 - Extending
apps/web/src/theme/antdTheme.ts - Touching Ant ConfigProvider / vite Ant auto-import
- Reviewing whether a change violates isolation from legacy UI
Also read and obey .cursor/rules/antd-strict-governance.mdc.
Non-negotiables
- One page per migration — never batch unrelated views.
- Do not edit
apps/web/src/components/ui/**during Ant migration work. - Child components of the View are in scope (mandatory) — هنگام بازنویسی یک صفحه (View)، ایجنت موظف است علاوه بر خود فایل View، تمام کامپوننتهای فرزندی را که در آن View ایمپورت شدهاند و حاوی اینپوت/سلکت/دکمه هستند نیز بازبینی کرده و درون آنها را به کامپوننتهای رسمی
ant-design-vueتبدیل کند. هیچ تگ<input>,<select>,<textarea>,<button>خامی نباید در صفحه یا کامپوننتهای فرزندِ مصرفی آن باقی بماند. When rewriting a View, also open every imported child that renders inputs/selects/buttons and convert them to officialant-design-vuecontrols. No raw<input>,<select>,<textarea>, or<button>(and noUiInput/UiSelect/UiButton/UiField/UiTextarea) may remain in the View or those children. Prefer Ant natives (a-selectmultiple/tags,a-time-picker, …); for Jalali/domain pickers, convert the child file to Ant chrome (a-input+a-popover, etc.). - No manual look CSS on migrated pages (no new scoped colors/spacing/radius/shadows for chrome).
- 24-column Ant grid (
a-row/a-col) for page layout. - Theme only in
apps/web/src/theme/antdTheme.ts. - Default control height is 36 via token
controlHeight: 36. Do not passsize/:sizeon buttons, inputs, selects, or similar controls; do not set per-componentcontrolHeight*in the themecomponentsmap. - Auto-import
<a-*>viaAntDesignVueResolver({ importStyle: false })— no per-file style imports. Root usesStyleProviderwithhash-priority="high"so legacymain.csscannot override Ant. - No global Ant reset CSS that would restyle legacy pages.
Stack facts (this repo)
| Piece | Location |
|---|---|
| Dependency | ant-design-vue ^4, @ant-design/icons-vue, unplugin-vue-components in @mento/web |
| Vite plugin | apps/web/vite.config.ts — Components + AntDesignVueResolver |
| Theme | apps/web/src/theme/antdTheme.ts (controlHeight: 36) |
| RTL + locale + theme | apps/web/src/App.vue — <a-config-provider direction="rtl" :locale="faIR" :theme="antdTheme"> |
| Legacy kit (do not touch) | apps/web/src/components/ui/*, styles/main.css utilities |
Migration workflow
- Confirm the single route/view the user named.
- Inventory current UI: legacy
Ui*,.btn/.field,.crm-*, custom tables. - List all imported children that contain controls; convert them in the same pass (except
components/ui/**). - Replace with Ant equivalents:
- Button →
a-button(nosizeprop) - Input/Select/Form field →
a-form+a-form-item+a-input/a-select/ … (nosize) - Modal/Drawer →
a-modal/a-drawer - Table →
a-table(columns via Ant API) - Page chrome →
a-card, title +a-space, layout viaa-row/a-col - Icons →
@ant-design/icons-vue
- Button →
- Remove page-local CSS that only existed to skin the old controls.
- Keep business logic, API calls, and router behavior intact.
- Grep-verify zero hits for
<input|<select|<textarea|<button|UiInput|UiSelect|UiField|UiTextarea|UiButtonin the View + converted children. - Run
npm run build -w @mento/web(or at leastvue-tsc -binapps/web). - Smoke-check that other routes still render with legacy UI unchanged.
Theme extension rules
- Change tokens in
antdTheme.tsonly when the user asks or when a migrated page proves a missing token. - Keep
controlHeight: 36as the single source for control sizing; let Ant derive SM/LG. - Prefer
tokenand limitedcomponents.Card/components.Formoverrides — never per-controlcontrolHeightforks. - Do not duplicate
ThemeConfigobjects inside views.
Anti-patterns (reject)
- Importing both
UiButtonanda-buttonon the same migrated page - Adding
ant-design-vue/dist/reset.css“to fix spacing” - Editing
components/uito “look more like Ant” size="small|middle|large"on Ant controls- Multi-page visual refactors in one PR
- Custom CSS overriding
.ant-btn/.ant-inputselectors
Done criteria
- Migrated page uses Ant components + 24-col grid
- Imported control-bearing children also Ant-pure (grep = 0)
- Controls use theme default height (no manual
size) - No new manual chrome CSS
- Legacy kit untouched
- Build/typecheck clean
- Unmigrated pages untouched in the diff