From 8cd29bd3fa560a109f5f6b44a2855c3a3682efbd Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Sun, 18 Oct 2026 03:37:45 +0000 Subject: [PATCH] chore: lean AI-native UI quality deliverables Drop alwaysApply Cursor rule and in-tree plan doc; revert non-core api/refactor/README instruction churn. Keep theme.config, verify:ui, frontend instructions, and AGENTS validation. Co-authored-by: zuiidea --- .cursor/rules/ai-native-ui-quality.mdc | 12 --- apps/basic/.github/instructions/README.md | 4 +- .../.github/instructions/api.instructions.md | 1 - .../instructions/refactor.instructions.md | 1 - .../.github/instructions/README.md | 4 +- .../instructions/refactor.instructions.md | 1 - .../2026-10-17-ai-native-ui-quality-design.md | 10 +- .../2026-10-17-ai-native-ui-quality-plan.md | 99 ------------------- 8 files changed, 7 insertions(+), 125 deletions(-) delete mode 100644 .cursor/rules/ai-native-ui-quality.mdc delete mode 100644 docs/specs/2026-10-17-ai-native-ui-quality-plan.md diff --git a/.cursor/rules/ai-native-ui-quality.mdc b/.cursor/rules/ai-native-ui-quality.mdc deleted file mode 100644 index ee6fe5b..0000000 --- a/.cursor/rules/ai-native-ui-quality.mdc +++ /dev/null @@ -1,12 +0,0 @@ ---- -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 3c2132a..27850d7 100644 --- a/apps/basic/.github/instructions/README.md +++ b/apps/basic/.github/instructions/README.md @@ -4,13 +4,11 @@ This directory contains scoped instruction files used by AI coding agents. ## Files -- `frontend.instructions.md`: UI/routes/components/style changes (includes golden paths and `verify:ui`) +- `frontend.instructions.md`: UI/routes/components/style changes - `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 295649b..24f0c26 100644 --- a/apps/basic/.github/instructions/api.instructions.md +++ b/apps/basic/.github/instructions/api.instructions.md @@ -13,7 +13,6 @@ 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/refactor.instructions.md b/apps/basic/.github/instructions/refactor.instructions.md index fa66b51..81e74f5 100644 --- a/apps/basic/.github/instructions/refactor.instructions.md +++ b/apps/basic/.github/instructions/refactor.instructions.md @@ -14,7 +14,6 @@ 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/.github/instructions/README.md b/apps/with-lingui/.github/instructions/README.md index 8c29033..87f921e 100644 --- a/apps/with-lingui/.github/instructions/README.md +++ b/apps/with-lingui/.github/instructions/README.md @@ -4,14 +4,12 @@ This directory contains scoped instruction files used by AI coding agents. ## Files -- `frontend.instructions.md`: UI/routes/components/style changes (includes golden paths and `verify:ui`) +- `frontend.instructions.md`: UI/routes/components/style changes - `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/refactor.instructions.md b/apps/with-lingui/.github/instructions/refactor.instructions.md index 0727d49..de28975 100644 --- a/apps/with-lingui/.github/instructions/refactor.instructions.md +++ b/apps/with-lingui/.github/instructions/refactor.instructions.md @@ -13,7 +13,6 @@ 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/docs/specs/2026-10-17-ai-native-ui-quality-design.md b/docs/specs/2026-10-17-ai-native-ui-quality-design.md index c3b3213..dab7ca2 100644 --- a/docs/specs/2026-10-17-ai-native-ui-quality-design.md +++ b/docs/specs/2026-10-17-ai-native-ui-quality-design.md @@ -1,16 +1,16 @@ # Design: AI-native UI quality (theme SSOT + thin verify:ui) -> Status: approved for phase-1 implementation -> Date: 2026-10-17 -> Companion plan: [2026-10-17-ai-native-ui-quality-plan.md](./2026-10-17-ai-native-ui-quality-plan.md) +> Status: approved for phase-1 implementation (leaned) +> Date: 2026-10-17 ## Decisions (confirmed) -1. Phase 1 scope: `theme.config` + `verify:ui` + instructions/docs only; no `packages/create` changes; no shared UI package. +1. Phase 1 scope: `theme.config` + `verify:ui` + frontend/AGENTS only; no `packages/create` changes; no shared UI package. 2. File name: **`theme.config.ts`** (not `brand.config.ts`); export **`themeConfig`**. 3. **`colorPrimary` is optional** on `themeConfig.token` (reserved; omit to use Ant Design default / existing env override where present). 4. **`verify:ui` is local/Agent only** in phase 1 (not wired into CI or `vp check`). -5. Root **alwaysApply** Cursor rule is OK. +5. **No** root alwaysApply Cursor rule (avoid overlap with app `frontend.instructions.md` / `AGENTS.md`). +6. Keep this design spec only; do not keep a separate implementation-plan doc in-tree. ## 1. Background diff --git a/docs/specs/2026-10-17-ai-native-ui-quality-plan.md b/docs/specs/2026-10-17-ai-native-ui-quality-plan.md deleted file mode 100644 index be4fac1..0000000 --- a/docs/specs/2026-10-17-ai-native-ui-quality-plan.md +++ /dev/null @@ -1,99 +0,0 @@ -# Plan: AI-native UI quality (phase 1) - -> Companion design: [2026-10-17-ai-native-ui-quality-design.md](./2026-10-17-ai-native-ui-quality-design.md) - -Confirmed naming: **`theme.config.ts` / `themeConfig`**. Optional `colorPrimary`. `verify:ui` local-only. alwaysApply Cursor rule. - -Implement in Task order. - -## Task 0 — Land Spec/Plan - -**Files:** - -- Create: `docs/specs/2026-10-17-ai-native-ui-quality-design.md` -- Create: `docs/specs/2026-10-17-ai-native-ui-quality-plan.md` - -**Done when:** both files exist (with `theme.config` naming). - -## Task 1 — `apps/basic` theme SSOT - -**Files:** - -- Create: `apps/basic/src/theme/theme.config.ts` -- Modify: `apps/basic/src/hooks/tokenBuilders.ts` - -**Steps:** - -1. Create `theme.config.ts` with seeds + optional `colorPrimary` type slot. -2. Import `themeConfig` in `tokenBuilders`; delete local duplicates. -3. Run `pnpm check` in `apps/basic`. - -**Done when:** check green; theme seeds live in `theme.config.ts`. - -## Task 2 — `apps/with-lingui` theme mirror - -**Files:** - -- Create: `apps/with-lingui/src/theme/theme.config.ts` -- Modify: `apps/with-lingui/src/hooks/tokenBuilders.ts` - -**Steps:** Mirror basic seeds; preserve `VITE_BRAND_PRIMARY` / `readBrandPrimary` (env wins over optional static `colorPrimary`). - -**Done when:** lingui `pnpm check` green; primary env override still works. - -## Task 3 — verify-ui (`basic`) - -**Files:** - -- Create: `apps/basic/scripts/verify-ui.mjs` -- Modify: `apps/basic/package.json` (`verify:ui` script) - -**Done when:** `pnpm verify:ui` prints OK, exit 0. No CI wiring. - -## Task 4 — verify-ui (`with-lingui`) - -**Files:** Mirror Task 3. - -**Done when:** lingui `pnpm verify:ui` OK. - -## Task 5 — Instructions + Cursor rule - -**Files:** - -- Modify both apps’ `frontend.instructions.md`, `refactor.instructions.md`, `AGENTS.md`, instructions `README.md` -- Optionally tighten `api.instructions.md` Zod line if missing -- Create: `.cursor/rules/ai-native-ui-quality.mdc` (`alwaysApply: true`) - -**frontend.instructions.md required sections:** - -```markdown -## Golden paths -## Ant Design and tokens -## Div and CSS exceptions -## YAGNI -## Validation -``` - -Validation must include check + `pnpm verify:ui` (local/Agent). - -**Done when:** both frontends have golden path table; root Cursor rule exists and is short. - -## Task 6 — Acceptance - -1. Both apps: `pnpm check` && `pnpm verify:ui` -2. `pnpm test:unit` where feasible -3. Diff check: no `packages/create`, no new dependencies, no new `packages/*`, no CI `verify:ui` job - -**Done when:** design success criteria satisfied. - -## Commit strategy - -1. `docs: add AI-native UI quality spec and plan` -2. `feat(basic): extract theme.config SSOT` -3. `feat(with-lingui): mirror theme.config SSOT` -4. `feat: add verify:ui scripts for admin templates` -5. `docs: harden agent UI/quality instructions` - -## Out of scope reminders - -- No `packages/ui`, eslint plugin, create CLI flags, CI verify job, LLM review, or screenshot baselines.