diff --git a/.cursor/rules/ai-native-ui-quality.mdc b/.cursor/rules/ai-native-ui-quality.mdc new file mode 100644 index 0000000..ee6fe5b --- /dev/null +++ b/.cursor/rules/ai-native-ui-quality.mdc @@ -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. diff --git a/apps/basic/.github/instructions/README.md b/apps/basic/.github/instructions/README.md index 27850d7..3c2132a 100644 --- a/apps/basic/.github/instructions/README.md +++ b/apps/basic/.github/instructions/README.md @@ -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. diff --git a/apps/basic/.github/instructions/api.instructions.md b/apps/basic/.github/instructions/api.instructions.md index 24f0c26..295649b 100644 --- a/apps/basic/.github/instructions/api.instructions.md +++ b/apps/basic/.github/instructions/api.instructions.md @@ -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. diff --git a/apps/basic/.github/instructions/frontend.instructions.md b/apps/basic/.github/instructions/frontend.instructions.md index 1f88597..1e98f93 100644 --- a/apps/basic/.github/instructions/frontend.instructions.md +++ b/apps/basic/.github/instructions/frontend.instructions.md @@ -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 diff --git a/apps/basic/.github/instructions/refactor.instructions.md b/apps/basic/.github/instructions/refactor.instructions.md index 81e74f5..fa66b51 100644 --- a/apps/basic/.github/instructions/refactor.instructions.md +++ b/apps/basic/.github/instructions/refactor.instructions.md @@ -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. diff --git a/apps/basic/AGENTS.md b/apps/basic/AGENTS.md index 49ea51f..0835dff 100644 --- a/apps/basic/AGENTS.md +++ b/apps/basic/AGENTS.md @@ -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 diff --git a/apps/with-lingui/.github/instructions/README.md b/apps/with-lingui/.github/instructions/README.md index 87f921e..8c29033 100644 --- a/apps/with-lingui/.github/instructions/README.md +++ b/apps/with-lingui/.github/instructions/README.md @@ -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. diff --git a/apps/with-lingui/.github/instructions/frontend.instructions.md b/apps/with-lingui/.github/instructions/frontend.instructions.md index 263fda0..47c47eb 100644 --- a/apps/with-lingui/.github/instructions/frontend.instructions.md +++ b/apps/with-lingui/.github/instructions/frontend.instructions.md @@ -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 diff --git a/apps/with-lingui/.github/instructions/refactor.instructions.md b/apps/with-lingui/.github/instructions/refactor.instructions.md index de28975..0727d49 100644 --- a/apps/with-lingui/.github/instructions/refactor.instructions.md +++ b/apps/with-lingui/.github/instructions/refactor.instructions.md @@ -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. diff --git a/apps/with-lingui/AGENTS.md b/apps/with-lingui/AGENTS.md index 233591c..2f4aecb 100644 --- a/apps/with-lingui/AGENTS.md +++ b/apps/with-lingui/AGENTS.md @@ -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