design-system
Workspace styling and UI-structure standards. Use for any UI work in /Users/Ford/workspace, including CSS, Tailwind, colors, spacing, type, radius, light and dark themes, app layout or sidebars, new pages or components, component folder structure, restyling an app, or moving an app onto the shared tokens.
- License 许可
- MIT
- 最近更新
- 2026-11-07
- Stars
- ★ 0
- Forks
- 0
01 前言 Front Matter
- name
- design-system
- metadata
- { "version": "0.1.0" }
- description
- Workspace styling and UI-structure standards. Use for any UI work in /Users/Ford/workspace, including CSS, Tailwind, colors, spacing, type, radius, light and dark themes, app layout or sidebars, new pages or components, component folder structure, restyling an app, or moving an app onto the shared tokens.
03 SKILL.md 正文
Design System
/Users/Ford/workspace/codebases/codecaine/core/design-system (@codecaine-ai/design-system) is the one source of truth for how every Codecaine and Lascari AI app looks and is laid out. Read its AGENTS.md before UI work.
Style UI
- Style only with tokens:
var(--ds-*)in CSS, the utilities from@codecaine-ai/design-system/tailwind.css(Tailwind v4), orcssVar()andtokensfrom@codecaine-ai/design-systemin JS. Withtailwind.css,dark:followsdata-theme, not the OS. - Use the semantic roles (surface, text, border, fill, accent, link, status). Use hue tokens only for categorical color. Text uses
link, neveraccent.dist/guide/tokens.mdlists every token, and the docs pagedocs/30-guide/10-tokensgives the rules. - Never hard-code a color, size, spacing, radius, font, shadow, duration or z-index. Never copy token values into an app. In Tailwind, never use Tailwind's own scales (
bg-red-500,text-sm,shadow-md,rounded-lg). New apps importtailwind-strict.cssbeforetailwind.css, so those utilities don't generate at all. - Check light and dark: set
data-theme="dark"on<html>. - Scan the folders you touched with
bun /Users/Ford/workspace/codebases/codecaine/core/design-system/scripts/scan-literals.ts <dir>. A new hard-coded literal is a bug.
Build a New App or Screen
- Use the app shell in the docs page
docs/30-guide/20-layout: a collapsible left sidebar (⌘\toggles it and the state persists), a topbar with the page title and actions, content in lanes, and an optional inspector. Start fromtemplates/react-app-shell/for React, or from the markup indocs/30-guide/20-layout. - Organize code by vertical slice, as the docs page
docs/30-guide/30-code-structuredescribes. Every component is a folder,_components/<Name>/index.tsx. Its parts go in its own_components/. Keep breaking components down. Move shared code up to the nearest common ancestor.
Change the Look
- Edit
tokens/. Never editdist/. - In
/Users/Ford/workspace/codebases/codecaine/core/design-system, runbun run build,bun run checkandbun run test. - Open
dist/guide/index.htmland check light and dark. Every connected app picks up the change.
Connect an App
- Inside Codecaine Core: add
"@codecaine-ai/design-system": "workspace:*"to the package, then runbun installat the Core root. Core'sworkspacesalready listsdesign-system(the folder sits inside Core), so the link is live. - Another local bun app: add the relative path to the root
workspacesand depend onworkspace:*, or usebun link. That gives a live link. Avoid a bunfile:dependency: bun links it file by file at install time, so files added later (new outputs) are missing until someone rerunsbun install. - npm apps: use a
file:dependency, which npm links live, or@importthe CSS by relative path. - Apps built on Vercel, Railway or Docker: vendor a packed copy. Run
bun run pack --out ../<app>/vendorin design-system (--outis relative to the design-system folder) and depend onfile:vendor/<tgz name>. Repack after a token change. - Load order:
@codecaine-ai/design-system/fonts.css, thentokens.css(tokens-dark-first.csson a dark-first surface), thenlayout.css. Agent-viewer hosts addhost-contract.cssafter the tokens. For Tailwind v4,tailwind-strict.csscomes beforetailwind.css; Tailwind v3 apps use thetailwind-v3-presetexport as a preset. - The docs page
docs/30-guide/40-consumehas the full recipe, including the Vite settings.
Check an App
Run these in /Users/Ford/workspace/codebases/codecaine/core/design-system. --root defaults to the workspace that holds it: /Users/Ford/workspace/codebases, three levels up.
- Find the app's entry in
apps.json: repo, wiring, entry stylesheet, scan paths, literal floor, run profile and routes. After you change an entry, runbun run registry:check. - Run
bun run lint:apps <app>(add--pass <n>to check one migration pass). It prints one line per violation and exits 0 when the app is wired and conformant. - Run
bun run verify:apps <app>. It starts the app under its run profile and proves in a browser that it renders from the tokens in light and dark. - Run
bun run test:apps <app>for the app's tests (add--commands typecheck,buildfor those; a command the entry does not set is skipped). It runs them under the run profile and the sandbox, fails on a write into the app's own checkout, and compares the results with the baselines inapps.json. Never run an app's tests or commands directly. - Run
bun run use:app --app <app>to use the app under its run profile. It visits every route in each theme, runs the route's steps, toggles the sidebar and hovers buttons and links. It clicks only the registry's route steps, which the managing agent reviews, and the sidebar toggle. A guard checks each click and key press as a second line of defence: it refuses a submit control, anything in a form, a control whose label names a write, and any key but Tab, Escape, the arrows, PageUp/PageDown, Home/End and a plain Enter or Space. It exits 1 on a console error, a failed or blocked request, a refused step, or a change to the app's checkout, and prints the path of its JSON log. - Never start the app outside its run profile.
verify:apps,snapshot,test:appsanduse:appstart and stop it for you. - The app passes when every gate its
apps.jsonentry marks required passes: lint, verify, tests, snapshot and pixel diff. bun run progresswrites one page with every app's status and literal count.
Move an Existing App
apps.json holds each app's registry entry, and bun run progress reports each app's pass status. The migration waves are finished. Move tokens first, then the shell, then the code structure, one app per change:
- Capture the before state:
bun run snapshot --app <id> --set before. - Run
bun run codemod:literals --app <id> propose, mark the rows you accept"approve": "yes", then runbun run codemod:literals apply --table <mapping.json>. - Wire the CSS (
docs/30-guide/40-consume) and fix what is left untillint:apps --pass <n>andverify:apps --pass <n>both pass, andtest:apps <id>shows no failure beyond the baseline. - Run
bun run snapshot --app <id> --set after, thenbun run snapshot:sheet --app <id> --a before --b after(andsnapshot:diffwith the same flags) to prove the change.
04 同仓库更多 Skills
beta
Drafts a commit message from a staged diff.
gamma
Summarizes a test run into a short report.
alpha
Formats release notes from a changelog.
beta
Drafts a commit message from a staged diff.
alpha
Formats release notes from a changelog.