Design system

Every surface here has a look someone already decided. Find it before you open a design skill, because a skill left to itself picks its own fonts and colours.

Step 1 — Read the document that governs the surface

The table goes stale; the filesystem does not. Check it before trusting a row:

find . -name DESIGN.md -not -path '*/node_modules/*'

When the surface's package.json depends on @shared/ui, @cire/ui or @shared/design-tokens, also read:

• wiki/shared/design-tokens.md — the ui-* contract the shared components paint with, and how an app maps its own palette onto it.
• wiki/shared/component-library.md — which component already exists, and what a call site may and may not override. Reuse before you build.

On every task, read wiki/shared/frontend-patterns.md §Rendering and animation gotchas — the layout and motion bugs no unit test sees. Read the sections a task needs, not whole pages: several of these run past a thousand lines.

Step 2 — Know what outranks what

The DESIGN.md comes first, then the surface's wiki pages, then a skill. A skill's taste rules fill the gaps a design system leaves open; they never override a font, colour, radius, type step or motion rule the system names. When the system has to grow — a new token, a new component pattern — amend its DESIGN.md in the same pull request, so the next screen reads the change.

A surface with no DESIGN.md and no wiki page on its look has no locked system. Say so in your report, take the direction from the brief, and if the work sets a lasting look, write the surface a DESIGN.md in the shape of the existing ones.

Step 3 — Pick the design skill, if the task needs one

A change the design system already settles — a token swap, spacing on the existing scale, a missing dark-mode value — needs no design skill: apply what the document says.

frontend-design:frontend-design is a plugin skill; the rest are user-level skills on the maintainer's machine. None of them is a file in this repository. Invoke a skill after reading the design system, and hand it the path of the DESIGN.md with the instruction that it is locked: none of them looks for one inside a package.

Five things these skills do that an agent here must not follow:

• They stop to ask the user. A dispatched agent has nobody to ask. Answer from the brief and the design system; where they do not settle it, take the choice that changes least of what exists, and record it in your report.
• hallmark writes exports — tokens.css, a Tailwind @theme, DTCG and shadcn blocks — into an ## Exports section of the design file it finds. Never let it write into a DESIGN.md here; token changes go through the surface's stylesheet and its DESIGN.md prose.
• design-taste-frontend and others ask for generated images. A coding agent cannot generate images. Skip those steps and say so.
• They install packages their own way — npm install, yarn add, npx shadcn@latest. Dependencies here follow AGENTS.md §Installs: bun add <pkg> --cwd <dir>, which keeps the repository's release-age delay. A skill's install command is never run as written.
• They fill gaps with third-party assets — placeholder photos from picsum.photos, icons from a CDN such as cdn.simpleicons.org. Ship no image, icon or font from a host the page does not already load: put the asset in the repository, or leave the slot empty and say so. A new outside origin needs a row in wiki/compliance/subprocessors.md and a CSP change, which are the owner's call.

Never on a surface with a design system: high-end-visual-design, minimalist-ui, industrial-brutalist-ui and gpt-taste. Each brings its own fonts, palette or motion library — gpt-taste requires GSAP, where this repository prefers CSS transitions and the View Transitions API — and would overwrite the system rather than serve it. brandkit, image-to-code and the imagegen-frontend-* skills only work with image generation. stitch-design-taste writes a DESIGN.md for Google Stitch, not for this repository.

A skill that is not installed is not a blocker. A remote session usually has none of them. Say which one you would have used, then follow the design system and the wiki pages above, which hold everything a skill would be checked against.

Step 4 — Show the result, not the claim

A design that only type-checks has not been looked at. Before you report done:

• Look at it rendered at a phone width and a desktop width, and in light and dark on a surface that themes. With the Chrome browser tools (mcp__claude-in-chrome__*), open the dev server for that surface alone — never a bare bun run dev, which starts every workspace in the repository, in every worktree that runs it. Prefix each with CLAUDECODE=; hosts are in wiki/conventions/devloop-urls.md.

  Surface	Command
  cire/host, cire/invites	bun run dev:cire
  cire/vendor	bunx --bun turbo dev --filter=@cire/vendor --filter=@cire/api --filter=@osn/api
  cire/landing	bun run dev:cire-landing
  pulse/web	bun run dev:pulse
  pulse/landing	bun run dev:pulse-landing
  musubi/social	bun run dev:social
  musubi/landing	bun run dev:landing
  Shared components, osn/auth-ui	bun run dev:lab

  Without them, a browser test can take the screenshots (wiki/conventions/browser-tests.md). With neither, the check is NOT RUN, with the reason.

• When layout or a computed style is the thing that must hold, write the browser test that proves it; bun run test:browser runs it.

• Run the gates AGENTS.md names and report their real output. A check you did not run is NOT RUN, which is a true and useful thing to say.

In your report, name the design document you followed, every skill you invoked or would have invoked, and every place you departed from the system and why.