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>
87 lines
5.4 KiB
Markdown
87 lines
5.4 KiB
Markdown
---
|
|
name: antd-system-architect
|
|
description: >-
|
|
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/web` view/page to Ant Design Vue 4
|
|
- Extending [`apps/web/src/theme/antdTheme.ts`](../../../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`](../../rules/antd-strict-governance.mdc).
|
|
|
|
## Non-negotiables
|
|
|
|
1. **One page per migration** — never batch unrelated views.
|
|
2. **Do not edit** `apps/web/src/components/ui/**` during Ant migration work.
|
|
3. **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 official `ant-design-vue` controls. No raw `<input>`, `<select>`, `<textarea>`, or `<button>` (and no `UiInput` / `UiSelect` / `UiButton` / `UiField` / `UiTextarea`) may remain in the View or those children. Prefer Ant natives (`a-select` multiple/tags, `a-time-picker`, …); for Jalali/domain pickers, convert the child file to Ant chrome (`a-input` + `a-popover`, etc.).
|
|
4. **No manual look CSS** on migrated pages (no new scoped colors/spacing/radius/shadows for chrome).
|
|
5. **24-column Ant grid** (`a-row` / `a-col`) for page layout.
|
|
6. **Theme only in** `apps/web/src/theme/antdTheme.ts`.
|
|
7. **Default control height is 36** via token `controlHeight: 36`. Do **not** pass `size` / `:size` on buttons, inputs, selects, or similar controls; do **not** set per-component `controlHeight*` in the theme `components` map.
|
|
8. **Auto-import** `<a-*>` via `AntDesignVueResolver({ importStyle: false })` — no per-file style imports. Root uses `StyleProvider` with `hash-priority="high"` so legacy `main.css` cannot override Ant.
|
|
9. **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
|
|
|
|
1. Confirm the **single** route/view the user named.
|
|
2. Inventory current UI: legacy `Ui*`, `.btn`/`.field`, `.crm-*`, custom tables.
|
|
3. List all imported children that contain controls; convert them in the same pass (except `components/ui/**`).
|
|
4. Replace with Ant equivalents:
|
|
- Button → `a-button` (**no** `size` prop)
|
|
- Input/Select/Form field → `a-form` + `a-form-item` + `a-input` / `a-select` / … (**no** `size`)
|
|
- Modal/Drawer → `a-modal` / `a-drawer`
|
|
- Table → `a-table` (columns via Ant API)
|
|
- Page chrome → `a-card`, title + `a-space`, layout via `a-row`/`a-col`
|
|
- Icons → `@ant-design/icons-vue`
|
|
5. Remove page-local CSS that only existed to skin the old controls.
|
|
6. Keep business logic, API calls, and router behavior intact.
|
|
7. Grep-verify zero hits for `<input|<select|<textarea|<button|UiInput|UiSelect|UiField|UiTextarea|UiButton` in the View + converted children.
|
|
8. Run `npm run build -w @mento/web` (or at least `vue-tsc -b` in `apps/web`).
|
|
9. Smoke-check that **other** routes still render with legacy UI unchanged.
|
|
|
|
## Theme extension rules
|
|
|
|
- Change tokens in `antdTheme.ts` only when the user asks or when a migrated page proves a missing token.
|
|
- Keep `controlHeight: 36` as the single source for control sizing; let Ant derive SM/LG.
|
|
- Prefer `token` and limited `components.Card` / `components.Form` overrides — never per-control `controlHeight` forks.
|
|
- Do not duplicate `ThemeConfig` objects inside views.
|
|
|
|
## Anti-patterns (reject)
|
|
|
|
- Importing both `UiButton` and `a-button` on the same migrated page
|
|
- Adding `ant-design-vue/dist/reset.css` “to fix spacing”
|
|
- Editing `components/ui` to “look more like Ant”
|
|
- `size="small|middle|large"` on Ant controls
|
|
- Multi-page visual refactors in one PR
|
|
- Custom CSS overriding `.ant-btn` / `.ant-input` selectors
|
|
|
|
## 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
|