v0.3.0 — Reference implementations and a checked interface

Reference implementations and a checked interface: the component gallery is rebuilt as the pages developers and AI agents copy from, a whole-app interface audit is fixed (accessibility, color, layout, copy), and a project can now start from a release with its own name and the gallery hidden.

Highlights

• A gallery to copy from. Ten page patterns (standard / card / tree / stats list, detail, step form, dynamic form, kanban, gantt, advanced table) on one shared demo backend, eleven component showcase pages (live examples with their exact source and key props) and the new ConditionBuilder; AGENTS.md, the skills and the docs site say which page to copy for a requirement.
• Interface audit fixed. Visible focus everywhere (including Windows high contrast), names and keyboard paths for every control, reduced motion honored, route titles and landmarks, text alternatives for all charts, measured color tokens (234 text / focus pairs across 6 accents × light / dark, none below threshold), pinned row actions, full text for truncated values, errors that say how to recover; axe reports no serious or critical issue on any page.
• Ready for your own project. A Starting a project guide (repository from a release tag, naming, going live, taking later releases including migrations), APP_NAME to name the product, and a gallery that nothing else depends on and one line hides.
• The AI workflow, dogfooded. Building a module end to end with /new-feature-autopilot fixed two dozen rough edges in pnpm scaffold, pnpm verify, pnpm db:migrate, seed:rbac and the docs.

Upgrading from 0.2.0

• pnpm db:migrate (Docker: on start). 0003 / 0004 add demo_records; 0005 drops the twelve tables of the old gallery pages (demo data only) and deletes their menus (40, 401–409).
• pnpm seed:rbac -- --incremental (Docker: on start) adds the 页面模板 (43, 4301–4310) and 组件 (47, 4701–4711) menus and renames the _add buttons 新增… → 新建….
• Color tokens (apps/web/src/index.css): the light status text steps, --muted-foreground and --destructive (now the danger red) changed, and each accent preset gained --brand-primary (text, links, focus; --primary / --ring use it), --brand-strong-from/to (gradients under white text) and --primary-hover. A project with its own presets defines those too.
• Focus: controls use focus-visible:outline-* with --ring, and test/focus-ring.test.ts now rejects a bare outline-none and translucent focus rings in your own components as well.
• Chart requires a summary (its accessible name); DataTable gained pin: 'end' for actions columns, primary, isRowActive, filtered / onClearFilters and new empty states; FilterSelect / SearchInput take a label.
• The dashboard's system status reads GET /api/admin/dashboard/system; pnpm scaffold --domain component_center modules use /api/admin/component-center/<name>s and register under 页面模板.

Added

• Shared demo data for the component gallery's page patterns (docs/roadmap.md "Component gallery redesign", step 2): table demo_records (migrations 0003_demo_record, 0004_demo_record_board_order) and the API /api/admin/component-center/demo-records — list with filters (search, category, status, owner, enabled, parent / root, start-date range) and sorting (sort_field + sort_dir), tree, stats (count, amount / quantity sums, counts per status and category, same filters), CRUD, batch-update, batch-delete, reorder (each entry changes only what it carries: board_order + status for kanban moves, sort_order + parent for tree drags, so the two orders never disturb each other; cycle-checked), import / export / template. A record with children can't be deleted (400); a batch delete may take a parent together with all of its children. Demo fixtures: a three-level project tree of 24 rows.
• 组件示例中心 → 页面模板 (Page patterns) directory (menu 43, cc_patterns) with its first page, 标准列表 (Standard list) (menu 4301, /component-center/patterns/standard-list): the scaffold-generated list page on the shared API, the reference implementation of the standard list pattern. The API's buttons (cc_patterns_add / _edit / _delete / _export / _import, menus 431–435) belong to the directory, and any page under it may read. Run pnpm db:migrate && pnpm seed:rbac -- --incremental after upgrading.
• The other nine page patterns under 页面模板 (menus 4302–4310, component_center/patterns/*), each the reference implementation of its pattern on the shared demo API: 卡片列表 (card list: card grid, cover upload, tags), 树形列表 (tree list: drag to reorder / reparent), 统计列表 (stats list: stat cards and status bar from stats), 详情页 (detail with tabs, the record id in the URL), 分步表单 (step form), 动态表单 (dynamic form: extra fields in extra), 看板 (kanban: status columns, drag across columns), 甘特图 (gantt: start / end dates and progress), 高级表格 (advanced table: inline edit, batch update / delete). Their status / category / enabled options and badge tones come from one module (pages/patterns/demo-record-options.ts; status tones: 待办 warning, 进行中 info, 已完成 success, 已归档 neutral).
• 组件示例中心 → 组件 (Components) directory (menu 47, cc_components, right after 页面模板) with 11 pages (4701–4711, /component-center/components/<slug>, component_center/components/*): one page per group of shared components (apps/web/src/shared/components), the usage reference for developers and AI agents — live examples, each example's exact source (syntax-highlighted, copyable) and the key props. 数据表格 (DataTable, RowActions, ConfirmAction), 表单 (FormFields, FormGrid, FormDialog, FormSheet, DetailSheet / DescriptionList), 筛选 (FilterBar, SearchInput, FilterSelect, SegmentedTabs), 选择器 (MultiSelect, TagInput, DatePicker / DateTimePicker, TreeSelect), 树 (TreeView, CheckableTree), 上传 (FileUpload, ImageUpload, AvatarUpload, FileIdUpload, to the real file center), 导入导出 (ImportDialog, ExportDialog on mock handlers), 反馈 (StatusBadge, EmptyState, ConfirmAction, toast, Skeleton), 数据展示 (StatCard with CountUp / Sparkline, Chart, Panel, PageHeader, UserAvatar), Markdown (MarkdownView), 条件构建器 (ConditionBuilder); no buttons, mock data only. The pages share a small showcase kit (modules/component_center/showcase: ShowcasePage, ShowcaseSection, Example, PropsTable, CodeBlock); each example is its own file imported twice, as a component and with Vite ?raw for the source shown, so the two can't drift (test/showcase.test.tsx checks every example file is wired both ways); props tables are hand-written per page in props.ts. The code highlighting reuses the AI Elements Shiki setup (tokensFor, now exported) and loads on demand. How to add one: AGENTS.md "Component showcase pages"; overview on the docs site's component gallery guide. Run pnpm seed:rbac -- --incremental after upgrading.
• ConditionBuilder shared component (apps/web/src/shared/components/ConditionBuilder.tsx), replacing the old list page's saved-query condition builder: conditions (field / operator / value, operators and value editor by field type — text, number, date, select, boolean) combined with AND / OR, plus one level of condition groups (allowGroups); controlled (value / onChange), typed over the field keys (ConditionBuilder<K>), and its value ConditionTree is plain JSON to save or send to an API — saving, API parameters or client-side filtering stay with the page.
• Which page to copy: AGENTS.md "Page patterns (which page to copy)" maps a requirement (cards, tree, stats, detail, steps, dynamic fields, kanban, gantt, batch editing) to its gallery page and the backend pieces it needs; the shadcn and autopilot skills and the docs site's gallery guide ("Building a feature from a pattern", en / zh / ja) point to it.
• Starting a project guide (docs site, en / zh / ja): create a repository from a release tag with castor-kit as upstream, name the product, hide the component gallery (one line in seed-rbac.ts; the code stays as the AI reference), go live, and take later releases, including how to merge when both sides added migrations (tried end to end on a scratch copy).
• APP_NAME (server) and APP_NAME in apps/web/src/lib/brand.ts (web) name the product in one place each: authenticator apps, the default mail sender and test mail, the AI assistant's introduction, logs; tab titles, the sidebar wordmark, the sign-in footer, the recovery-code file name.

Removed

• The old gallery pages (组件示例中心 → 管理系统 / Admin pages: list page with saved queries and the condition builder, stats list, card list, tree list, dynamic form, kanban board, detail tabs, gantt, advanced table), replaced by the page patterns: their backend modules (/api/admin/component-center/{list-page,stats-list-page,card-list-page,tree-list-page,dynamic-form-page,kanban,detail-tabs,gantt,advanced-table}), pages, API files, tests, demo fixtures, messages and OpenAPI paths. Migration 0005_remove_old_gallery_modules drops their tables (saved_queries, saved_query_versions, stats_items, card_items, tree_nodes, dynamic_form_records, dynamic_form_fields, kanban_boards, kanban_cards, detail_members, gantt_tasks, advanced_table_rows) and deletes the 管理系统 menu directory (40) with its pages (401–409), their buttons and role grants. The saved-query condition builder comes back as a component showcase page (roadmap step 4). The dashboard's gallery quick link now opens the page patterns. Upgrading: pnpm db:migrate deletes the rows of those tables — demo data only; nothing else reads them.

• The component gallery's 3D / creative pages (particle network, CSS 3D cards, Three.js globe, particle morphing) and the three dependency: the gallery is being reshaped into reference implementations for developers and AI (docs/roadmap.md "Component gallery redesign"). Migration 0002_remove_creative_menus deletes their menus and role grants on existing databases.

• pnpm verify no longer accepts a .jsx page or .js API file (the frontend is TypeScript only); AGENTS.md / CLAUDE.md name the page glob as index.tsx.

Fixed

• Interface audit (2026-09-28, all 52 pages; #84–#89): visible focus outlines on every control (a 1.3:1 translucent ring before) that survive Windows high contrast; reduced motion for motion/react (MotionConfig reducedMotion="user"); per-route document titles, <main> focus on navigation, nav landmarks and a skip link; accessible names for filters, pickers, tree / table rows and settings fields; keyboard paths for trees (APG tree), table row clicks, tag close, clear buttons, the drag layout and kanban cards (localized dnd-kit announcements); chart text alternatives (summary + ECharts aria / decals); focus return after dialogs; sign-in errors linked to their fields; error toasts that stay until dismissed; translated names for close / sidebar / loading / toasts / date picker; measured color tokens (status text, muted text, one red, accent split, hue separation, fixed chart palette); pinned actions columns and full text for truncated values; actionable network and validation errors; no clipping at 320px; 16px inputs on iOS; one create verb (新建) and clearer empty states.
• pnpm scaffold --domain component_center writes the page to pages/patterns/<name>_page/ (menu component component_center/patterns/<name>_page), next to the gallery's page patterns, instead of the removed pages/admin/ group.
• Pages that update on their own can be paused: the perf monitor (every second) and the dashboard's system status (every 3 s); the step form moves focus to each step's heading and to the first invalid field; the advanced table's inline edit focuses the name input, saves on Enter, cancels on Escape and returns focus to the row's Edit button.
• pnpm scaffold --domain component_center: the API lives under the gallery prefix (/api/admin/component-center/<name>s, writable in demo mode like the other gallery APIs), and a spec menu registers the page under 组件示例中心 → 页面模板 (IDs 4301–4399, path /component-center/patterns/<name>) instead of 业务管理.
• The dashboard's system status only worked for users holding the gallery's performance-monitor permission (it polled /api/admin/component-center/devtools/perf-stats); it now reads GET /api/admin/dashboard/system (login only). The gallery is no longer needed by the rest of the app: the chat helpers the AI assistant shares moved to common/ai-chat.ts, the system metrics to common/system-stats.ts, the business-table rule of the read-only role (used by setup-once / init-ro-role) to common/sql-visibility.ts, and the dashboard shows its gallery shortcuts, "Ask AI" and "Audit logs" only when those pages are in the user's menus. Page prefetching matches the page patterns again (it still named the removed component_center/admin group), and the AI chat's system prompt lists the current 36 gallery pages.
• The public demo's notification fixtures no longer include two leftover test rows ("test", "csrf ok").

Found by building a module end to end with /new-feature-autopilot (friction log in #79):

• pnpm scaffold: each enum field gets a list filter (FilterSelect on the page, an exact-match query parameter on the list route, documented with the option values, checked in the generated API test); the backend templates show where the list page template's status filter is read. Enum columns are StatusBadges, coloured by an optional tone per spec option; list columns keep short values on one line and give free text a minimum width, so narrow screens scroll the table instead of squeezing a column to one character (and ellipsis columns no longer collapse); webhook events are described with the module title ("设备台账已新增") and translated in the module's page locales; downloads are saved under the names the server gives them. --validate-only and --dry-run name the menu ID and path, --dry-run reports the same writes as a real run and ends with "nothing was written", the field list is printed in the --fields syntax, and a spec translation that loses to an existing one gets a [note].
• pnpm scaffold: a spec with a required number / option field and no default (e.g. docs/examples/specs/expense.json) generated a page that failed tsc (the empty form value is null, the create body isn't nullable); the page now narrows those fields in a generated toBody() before submitting. Its --fields next steps and AGENTS.md "Changing menus" mention the menu names in apps/web/src/locales/menus/, which the web i18n test requires.
• pnpm verify prints each check's detail (the migrated to <tag> line for the delivery report), counts skipped checks as skipped, and no longer says "ready to deliver" when --skip-* flags skipped checks (complete in --json).
• pnpm db:migrate prints in English how many migrations it applied and which one the database is at; pnpm seed:rbac -- --incremental lists only menus that changed.
• The tests read TEST_DATABASE_URL from apps/api/.env.test as well as the shell, and the Vite dev proxy takes API_PORT, so a second checkout can run beside the first with its own databases and ports.
• AGENTS.md, CLAUDE.md and the autopilot skill lead with the spec flow (--spec → --validate-only → generate), no longer describe request schemas as .passthrough(), and explain a checkout without apps/api/.env.development.

Full changelog: v0.2.0...v0.3.0