Files
CRM_Montzar/.cursor/skills/antd-system-architect/SKILL.md
T
MahdiandCursor 4abab55a6b feat(web): migrate CRM screens to Ant Design Vue with central theme
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>
2026-10-18 19:39:59 +03:30

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/web view/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

  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