mirror of
https://github.com/zuiidea/antd-admin
synced 2026-10-28 11:24:50 +00:00
docs: harden agent UI/quality instructions
Register golden paths, YAGNI, and verify:ui in app instructions and Cursor rules. Co-authored-by: zuiidea <zuiiidea@gmail.com>
This commit is contained in:
Cursor Agent
zuiidea
@@ -0,0 +1,12 @@
|
||||
---
|
||||
description: AI-native Ant Design UI quality — theme SSOT, golden paths, local verify:ui
|
||||
alwaysApply: true
|
||||
---
|
||||
|
||||
# AI-native UI quality
|
||||
|
||||
- Prefer Ant Design. Do not add parallel UI libraries (MUI, Chakra, Mantine, etc.).
|
||||
- Intentional colors/fonts/radius live only in `src/theme/theme.config.ts` (optional `colorPrimary`). Business TSX uses `theme.useToken()` / component APIs.
|
||||
- New ListCRUD / Auth / Dashboard / Shell / Error pages must structurally align with golden paths in each app’s `.github/instructions/frontend.instructions.md`.
|
||||
- Do not extract shared modules without a third call site. Do not invent governance packages while coding features.
|
||||
- After UI changes: `pnpm check` (or `vp check --no-fmt`), then `pnpm verify:ui`. Fix the same violations at most twice, then stop.
|
||||
+3
-1
@@ -4,11 +4,13 @@ This directory contains scoped instruction files used by AI coding agents.
|
||||
|
||||
## Files
|
||||
|
||||
- `frontend.instructions.md`: UI/routes/components/style changes
|
||||
- `frontend.instructions.md`: UI/routes/components/style changes (includes golden paths and `verify:ui`)
|
||||
- `testing.instructions.md`: Playwright/MSW/test changes
|
||||
- `api.instructions.md`: API client/schema/handler changes
|
||||
- `refactor.instructions.md`: behavior-preserving cleanup and deduplication
|
||||
|
||||
UI golden paths and Ant Design/token rules live in `frontend.instructions.md`.
|
||||
|
||||
## Authoring Rules
|
||||
|
||||
- Keep each file focused on one domain.
|
||||
|
||||
@@ -13,6 +13,7 @@ Maintain strict API contracts and consistent server/client mock behavior.
|
||||
## Do
|
||||
|
||||
- Keep request/response shapes schema-driven and type-safe.
|
||||
- New endpoints and client mutations/queries must use Zod schemas at the boundary.
|
||||
- Reuse endpoint constants and shared response helpers.
|
||||
- Keep handler response envelope consistent (`code`, `data`, `message`).
|
||||
- Ensure mock handlers reflect real API behavior and error semantics.
|
||||
|
||||
+37
-8
@@ -1,8 +1,7 @@
|
||||
---
|
||||
|
||||
## applyTo: "src/\*_/_.{ts,tsx,css}"
|
||||
|
||||
description: "Use when editing React UI, route pages, components, styles, layout, i18n text, or Ant Design behavior. Keywords: frontend, component, page, ui, layout, style, antd, i18n."
|
||||
applyTo: "src/**/*.{ts,tsx,css}"
|
||||
description: "Use when editing React UI, route pages, components, styles, layout, or Ant Design behavior. Keywords: frontend, component, page, ui, layout, style, antd."
|
||||
---
|
||||
|
||||
# Frontend Instructions
|
||||
|
||||
@@ -14,9 +13,8 @@ Keep frontend changes predictable, minimal, and reusable for AI-assisted edits.
|
||||
|
||||
- Preserve existing route contracts and UI behavior unless explicitly asked.
|
||||
- Prefer reusable components and hooks over copy-paste logic.
|
||||
- Keep styles token-driven using existing theme/store patterns.
|
||||
- Keep styles token-driven using `src/theme/theme.config.ts` and `theme.useToken()`.
|
||||
- For Ant Design styling, follow this priority: component native API (`variant`/`type`/`size`/`styles`/`classNames`) -> `theme.useToken()` with inline `style` -> `className` + external CSS.
|
||||
- Keep translations compatible with Lingui macros and catalogs.
|
||||
- Follow current folder conventions under src/components and src/routes.
|
||||
|
||||
## Do Not
|
||||
@@ -24,9 +22,40 @@ Keep frontend changes predictable, minimal, and reusable for AI-assisted edits.
|
||||
- Do not introduce new UI libraries when Ant Design already covers the need.
|
||||
- Do not bypass existing theme/store abstractions with hardcoded global state.
|
||||
- Do not write CSS overrides first when props or semantic `styles` can express the same UI.
|
||||
- Do not put literal `#hex` / `rgb()` / `hsl()` colors in business TSX (use `theme.config` or tokens).
|
||||
- Do not refactor unrelated files in the same change.
|
||||
|
||||
## Golden paths
|
||||
|
||||
Classify the page archetype, open the golden path, copy file split and data flow, then replace domain schema/API/columns only.
|
||||
|
||||
| Archetype | Path |
|
||||
|-----------|------|
|
||||
| ListCRUD | `src/routes/_auth/users/` (includes `-Toolbar.tsx`, `-FormModal.tsx`) |
|
||||
| Auth | `src/routes/login/` |
|
||||
| Dashboard | `src/routes/_auth/dashboard/` |
|
||||
| Shell | `src/components/Layout/` |
|
||||
| Error | `src/components/NotFound/`, `src/components/RouteError.tsx` |
|
||||
|
||||
## Ant Design and tokens
|
||||
|
||||
- Prefer `Flex` / `Space` / `Row` / `Col` for layout intent.
|
||||
- Brand and seed tokens live only in `src/theme/theme.config.ts` (optional `colorPrimary`).
|
||||
- Menu/table chrome algorithms stay in `hooks/tokenBuilders.ts`.
|
||||
|
||||
## Div and CSS exceptions
|
||||
|
||||
- Native `div` is allowed for `ref` measure slots, scroll containers, and third-party DOM requirements.
|
||||
- New CSS files must be on the `verify:ui` allowlist (see `scripts/verify-ui.mjs`); prefer tokens over new CSS.
|
||||
|
||||
## YAGNI
|
||||
|
||||
- Do not extract a shared hook/component without a third call site.
|
||||
- Do not add parallel abstractions when an existing shell (`DataTable`, `FilterToolbar`, `FormModal`, `useResourceCRUD`) covers the need.
|
||||
|
||||
## Validation
|
||||
|
||||
- Run: `vp check --no-fmt`
|
||||
- For UI flow changes, run focused e2e where possible.
|
||||
- Run: `pnpm check` (or `vp check --no-fmt`)
|
||||
- Run: `pnpm verify:ui` (local/Agent gate; not CI in phase 1)
|
||||
- On failure: fix the same violation set at most twice, then stop and shrink scope
|
||||
- For UI flow changes, run focused e2e where possible
|
||||
|
||||
@@ -14,6 +14,7 @@ Reduce duplication while preserving behavior and public contracts.
|
||||
|
||||
- Keep refactors incremental and scoped to one concern per change.
|
||||
- Prefer extracting shared utilities/hooks/components over large rewrites.
|
||||
- Do not extract a shared module without at least three call sites.
|
||||
- Preserve existing external behavior and route/store contracts.
|
||||
- Keep diffs reviewable with minimal unrelated formatting churn.
|
||||
- Add or update lightweight comments only when logic is non-obvious.
|
||||
|
||||
@@ -71,6 +71,9 @@ These commands map to their corresponding tools. For example, `vp dev --port 300
|
||||
|
||||
- Run `vp install` after pulling remote changes and before getting started.
|
||||
- Run `vp check` and `vp test` to validate changes.
|
||||
- For UI/theme work, also run `pnpm verify:ui` (local gate; not CI).
|
||||
- On check/`verify:ui` failure, fix the same violation set at most twice, then stop and shrink scope.
|
||||
- Keep a single intent per change; do not mix unrelated refactors.
|
||||
|
||||
## AI Instruction Files
|
||||
|
||||
|
||||
+3
-1
@@ -4,12 +4,14 @@ This directory contains scoped instruction files used by AI coding agents.
|
||||
|
||||
## Files
|
||||
|
||||
- `frontend.instructions.md`: UI/routes/components/style changes
|
||||
- `frontend.instructions.md`: UI/routes/components/style changes (includes golden paths and `verify:ui`)
|
||||
- `testing.instructions.md`: Playwright/MSW/test changes
|
||||
- `api.instructions.md`: API client/schema/handler changes
|
||||
- `refactor.instructions.md`: behavior-preserving cleanup and deduplication
|
||||
- `add-resource.instructions.md`: add a new CRUD resource (manual / Agent checklist; mirror `users`)
|
||||
|
||||
UI golden paths and Ant Design/token rules live in `frontend.instructions.md`.
|
||||
|
||||
## Authoring Rules
|
||||
|
||||
- Keep each file focused on one domain.
|
||||
|
||||
@@ -13,7 +13,7 @@ Keep frontend changes predictable, minimal, and reusable for AI-assisted edits.
|
||||
|
||||
- Preserve existing route contracts and UI behavior unless explicitly asked.
|
||||
- Prefer reusable components and hooks over copy-paste logic.
|
||||
- Keep styles token-driven using existing theme/store patterns.
|
||||
- Keep styles token-driven using `src/theme/theme.config.ts` and `theme.useToken()`.
|
||||
- For Ant Design styling, follow this priority: component native API (`variant`/`type`/`size`/`styles`/`classNames`) -> `theme.useToken()` with inline `style` -> `className` + external CSS.
|
||||
- Keep translations compatible with Lingui macros and catalogs.
|
||||
- Follow current folder conventions under src/components and src/routes.
|
||||
@@ -23,9 +23,40 @@ Keep frontend changes predictable, minimal, and reusable for AI-assisted edits.
|
||||
- Do not introduce new UI libraries when Ant Design already covers the need.
|
||||
- Do not bypass existing theme/store abstractions with hardcoded global state.
|
||||
- Do not write CSS overrides first when props or semantic `styles` can express the same UI.
|
||||
- Do not put literal `#hex` / `rgb()` / `hsl()` colors in business TSX (use `theme.config`, `VITE_BRAND_PRIMARY`, or tokens).
|
||||
- Do not refactor unrelated files in the same change.
|
||||
|
||||
## Golden paths
|
||||
|
||||
Classify the page archetype, open the golden path, copy file split and data flow, then replace domain schema/API/columns only.
|
||||
|
||||
| Archetype | Path |
|
||||
|-----------|------|
|
||||
| ListCRUD | `src/routes/_auth/users/` (includes `-Toolbar.tsx`, `-FormModal.tsx`) |
|
||||
| Auth | `src/routes/login/` |
|
||||
| Dashboard | `src/routes/_auth/dashboard/` |
|
||||
| Shell | `src/components/Layout/` |
|
||||
| Error | `src/components/NotFound/`, `src/components/RouteError.tsx` |
|
||||
|
||||
## Ant Design and tokens
|
||||
|
||||
- Prefer `Flex` / `Space` / `Row` / `Col` for layout intent.
|
||||
- Brand and seed tokens live only in `src/theme/theme.config.ts` (optional `colorPrimary`; `VITE_BRAND_PRIMARY` overrides when set).
|
||||
- Menu/table chrome algorithms stay in `hooks/tokenBuilders.ts`.
|
||||
|
||||
## Div and CSS exceptions
|
||||
|
||||
- Native `div` is allowed for `ref` measure slots, scroll containers, and third-party DOM requirements.
|
||||
- New CSS files must be on the `verify:ui` allowlist (see `scripts/verify-ui.mjs`); prefer tokens over new CSS.
|
||||
|
||||
## YAGNI
|
||||
|
||||
- Do not extract a shared hook/component without a third call site.
|
||||
- Do not add parallel abstractions when an existing shell (`DataTable`, `FilterToolbar`, `FormModal`, `useResourceCRUD`) covers the need.
|
||||
|
||||
## Validation
|
||||
|
||||
- Run: `pnpm exec vp check --no-fmt`
|
||||
- For UI flow changes, run focused e2e where possible.
|
||||
- Run: `pnpm check` (or `pnpm exec vp check --no-fmt`)
|
||||
- Run: `pnpm verify:ui` (local/Agent gate; not CI in phase 1)
|
||||
- On failure: fix the same violation set at most twice, then stop and shrink scope
|
||||
- For UI flow changes, run focused e2e where possible
|
||||
|
||||
@@ -13,6 +13,7 @@ Reduce duplication while preserving behavior and public contracts.
|
||||
|
||||
- Keep refactors incremental and scoped to one concern per change.
|
||||
- Prefer extracting shared utilities/hooks/components over large rewrites.
|
||||
- Do not extract a shared module without at least three call sites.
|
||||
- Preserve existing external behavior and route/store contracts.
|
||||
- Keep diffs reviewable with minimal unrelated formatting churn.
|
||||
- Add or update lightweight comments only when logic is non-obvious.
|
||||
|
||||
@@ -71,6 +71,9 @@ These commands map to their corresponding tools. For example, `vp dev --port 300
|
||||
|
||||
- Run `vp install` after pulling remote changes and before getting started.
|
||||
- Run `vp check` and `vp test` to validate changes.
|
||||
- For UI/theme work, also run `pnpm verify:ui` (local gate; not CI).
|
||||
- On check/`verify:ui` failure, fix the same violation set at most twice, then stop and shrink scope.
|
||||
- Keep a single intent per change; do not mix unrelated refactors.
|
||||
|
||||
## Monorepo git hooks
|
||||
|
||||
|
||||
Reference in New Issue
Block a user