add-component
Use when adding or substantially modifying any UI component in this repo — before writing the first line of JSX.
- License 许可
- MIT
- 最近更新
- 2026-10-29
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- add-component
- description
- Use when adding or substantially modifying any UI component in this repo — before writing the first line of JSX.
03 SKILL.md 正文
Add a Component
Overview
This repo has ~99 cataloged components; the most common failure is building one that already exists or styling it outside the theme boundary. The workflow is catalog-first, token-only, catalog-registered.
Checklist
- Search before you build: read
src/components/catalog.ts. It's the machine-readable index — import path,purpose,use_when,prefer_over(which near-twin to pick and why), real props, and a snippet./docsrenders it live in the running app. If a near-twin exists, extend it instead of adding a sibling. - Style with tokens only. Token-backed Tailwind utilities
(
bg-surface,text-ink,border-line,text-accent,text-pos/neg/warn,bg-accent-soft, …) and the.num/.micro/.displayhelper classes.var(--token)references are fine — that's howSparklineand the charts get color. Never raw colors (npm run lint:themeblocks them) and never named Tailwind colors likebg-black/40(the linter misses those, but they break re-skinning). Need a new color? Add/derive a token insrc/theme/tokens.cssfirst. - Export from the right barrel (
ui,shell,charts,DataGrid, or thesrc/componentsaggregate) — consumers import from barrels, not deep paths. - Register it in
CATALOG(src/components/catalog.ts) via thedefineComponentfactory — thepropsarray is compile-checked against the component's real props, sonpm run buildfails on typos. Fillpurpose,use_when, a copy-pastesnippet, andprefer_overif it has near-twins. Helper components not meant for direct use go in theINTERNALmap instead (name → one-line reason).src/components/catalog.test.tsfails if any export is neither cataloged norINTERNAL, if anINTERNALentry goes stale, or ifprefer_over/relatedreference uncataloged names. - Colocate a test as
ComponentName.test.tsxnext to the source. - Verify the smallest affected surface: run the component's colocated
test first. If you changed exports, catalog metadata, or public props, also
run
npx vitest run src/components/catalog.test.ts src/components/barrels.test.tsandnpm run buildbecause the catalogpropscheck only runs in the build gate, not in Vitest. If you only changed internal rendering or styling, do not run the full repo gauntlet unless the change is cross-cutting or the user asks for it.
Common mistakes
| Mistake | Fix |
|---|---|
| Built a twin of an existing component | Check use_when/prefer_over in the catalog first |
| Hardcoded a hex "temporarily" | Add a token; lint:theme fails the build regardless |
bg-white, bg-black/40, text-gray-500 |
Invisible to lint:theme but wrong — use bg-surface, text-muted, … |
| Skipped the CATALOG entry | catalog.test.ts fails; intentional helpers go in INTERNAL |
| Internal component test passed, but public props changed | defineComponent props are checked by tsc, so run npm run build |
04 同仓库更多 Skills
verify-changes
Use before claiming any change to this repo is done, fixed, or passing — and when a build fails after tests passed, a color sneaks past lint, or a localStorage test misbehaves.
swap-data-domain
Use when replacing the demo accounts/MRR data with your own domain — new entity types, seed data, KPIs, chart series, grid columns, or CRUD forms.
retheme
Use when re-skinning this dashboard to a new brand or palette — changing colors, accent, dark mode, radii, fonts, or chart colors, or when asked to "make it match my brand".
verify-changes
Use before claiming any change to this repo is done, fixed, or passing — and when a build fails after tests passed, a color sneaks past lint, or a localStorage test misbehaves.
swap-data-domain
Use when replacing the demo accounts/MRR data with your own domain — new entity types, seed data, KPIs, chart series, grid columns, or CRUD forms.
retheme
Use when re-skinning this dashboard to a new brand or palette — changing colors, accent, dark mode, radii, fonts, or chart colors, or when asked to "make it match my brand".