// Use when reverse-engineering a codebase's implicit design system, creating a DESIGN.md style guide, documenting design tokens, or establishing visual language standards. Also use when asked to audit UI consistency, rationalize ad-hoc styling into a system, or prepare a design reference that enables one-shotting new components.
Produce an Apple-keynote-quality motion-design video in HyperFrames (HTML + GSAP compositions) — kinetic typography plus real product UI, scored to a real music track, rendered at 4K. Use when asked to make a motion-design video, an Apple-style launch/product film, a feature-announcement video, a hype/promo reel or sizzle, ESPECIALLY in HyperFrames, or when porting motion-studio/Remotion components into a HyperFrames video. The engine is HyperFrames — `npx hyperframes` lint/inspect/render, one paused GSAP timeline on window.__timelines, sub-compositions, a reusable component library, and a 4K scale-stage. Covers the full pipeline — discovery, a binding creative brief, a music beat grid, an agent team (scriptwriter, reviewer, component porter, video builder, UX and craft auditors), faithful component porting, the Apple aesthetic and exact palette, sourcing a real royalty-free music track beat-matched to the edit, 4K export, frame-by-frame verification, and the hard-won pitfalls that cost real iterations.
Write test cases that catch real bugs in production code instead of producing false confidence. Use when writing, reviewing, or planning tests for any codebase. Triggers on: "write tests", "add test coverage", "test this function", "create unit tests", "integration tests", "fix flaky tests", "improve test coverage", "review test quality", "are these tests good", "test plan", or any task involving pytest, vitest, jest, or other test frameworks. Prevents common AI testing pitfalls: over-mocking, testing frameworks instead of production code, fake implementations that bypass real logic, and assertion-free tests.
1-shot high-quality landing pages and demos in GAIA's design system. Use when building any new marketing or landing page, feature showcase, persona page, or integration page for the GAIA web app.
Create high-quality Remotion video animations for GAIA product commercials. Use when building, modifying, or creating new scenes for the GAIA promotional video (apps/video), creating Apple-style motion design commercials in Remotion, or when working on any video animation in the GAIA monorepo. Covers scene architecture, animation patterns, typography, transitions, sound design, and aesthetic rules derived from 72 production conversations. Also use when the user asks to create a new video, add scenes, fix animation timing, or improve visual quality of Remotion compositions.
Design language and visual conventions for the GAIA web app (apps/web). Use when building new components, pages, tool call sections, chat bubbles, or any UI element in GAIA. Covers the design philosophy, color system, typography, spacing, icons, animations, and all patterns needed to make anything look native to GAIA.
| name | creating-design-systems |
| description | Use when reverse-engineering a codebase's implicit design system, creating a DESIGN.md style guide, documenting design tokens, or establishing visual language standards. Also use when asked to audit UI consistency, rationalize ad-hoc styling into a system, or prepare a design reference that enables one-shotting new components. |
Reverse-engineer a codebase's implicit visual language into a practical, implementation-ready style guide that lets you (or any agent) one-shot new UI components without configuration or guesswork.
Read actual source files — don't guess from file names.
| What | Where to look |
|---|---|
| Colors, radius, shadows, fonts | globals.css, tailwind.config.*, CSS custom properties |
| Component library config | components.json (Shadcn), theme files, provider wrappers |
| Base component variants | button.tsx, input.tsx, card.tsx — the primitives |
| What | Where to look |
|---|---|
| Real token usage | 3-5 feature components that ship to users (not storybook demos) |
| Recurring class combos | Grep for rounded-, bg-, text- — find the actual palette in use |
| Interactive states | Button, input, dropdown — how hover/focus/disabled/error look |
| Status/semantic colors | Badges, chips, alerts — how success/warning/error/info are expressed |
| Animation patterns | Grep for animate-, transition-, motion imports |
| Icon system | How icons are imported, sized, colored |
| Toast/notification | Which library, how it's configured, how it's called |
| Overlay usage | When dialog vs sheet vs popover vs tooltip |
| Depth/elevation | Shadows vs background layering vs blur — how the project creates depth |
| Glass/blur patterns | Grep for backdrop-blur, bg-opacity, /40 — some apps use transparency as a design tool |
| Gradients | Grep for gradient, linear-gradient — decorative moments, hero sections |
| Text overflow | How long strings are handled — truncate, line-clamp-*, max-w-[] patterns |
| Class composition | What utility the project uses for conditional classes (cn, clsx, cva, tv) |
| Landing vs app UI | Some codebases have two visual registers — check if marketing pages use different fonts, spacing, or tone |
Order matters — philosophy sets the mental model, tokens are the vocabulary, patterns show how to compose.
1. Philosophy — 3-5 bullets. The "why" behind visual choices.
2. Colors — Brand tokens, semantic variables, neutral scale, status colors.
3. Typography — Font families and when each is used. Heading scale.
4. Spacing — Common values and what each is for.
5. Border Radius — Decision table: which radius for which context.
6. Shadows — When shadow vs flat. Usually a short section.
7. Icons — Library, import pattern, sizing convention.
8. Animations — Available classes, transition defaults, easing, motion library.
9. Toast — Library name, how to call it, don't configure it.
10. Styling Tools — cn(), cva, or whatever the project uses for class composition.
11. Component Library — What's available. Overlay hierarchy (dialog vs sheet vs popover).
12. Card/Surface Contract — The reusable pattern for data display. Include a template.
13. Forms — Field pattern, input states, error display.
14. Loading States — Skeleton, spinner, empty state patterns.
15. Interactive States — Hover, focus, active, disabled, error, hover-reveal.
16. Dark/Light Mode — How theming works, what switches and what doesn't.
17. Responsiveness — Breakpoints and what changes at each.
Not every project needs every section. Skip what doesn't apply. Never pad.
A design system doc is never right on the first pass. Plan for three.
Dump every token, pattern, and convention you find. Over-include. Get the raw material down.
Compare against existing docs (rules files, component-level CLAUDE.md files, READMEs). If something is already documented elsewhere, either:
Never have the same rule in two files. Pick one owner.
This is the critical pass. Ask of every line: "Is this design language or is this how a specific component works?"
Keep (design language):
rounded-2xl bg-zinc-800 p-4" — a reusable token/pattern/10 opacity backgrounds" — a system-wide rulefont-serif for editorial headings only" — a design decisionRemove (implementation details):
TextBubble → ThinkingBubble → MarkdownRenderer)The test: If someone building a completely different feature wouldn't use this info, it's implementation detail — move it to a component-level doc or delete it.
Put the design system in one file at the repo root: DESIGN.md.
Other files should point to it, not duplicate it:
# .claude/rules/design.md (or equivalent rules file)
See DESIGN.md at the repo root for the full design system.
# In CLAUDE.md (or equivalent project instructions)
## Design System
See [DESIGN.md](./DESIGN.md) for the full design system guide.
| File | Contains | Does NOT contain |
|---|---|---|
DESIGN.md | Visual language, tokens, patterns, templates | Component internals, developer workflows |
Code rules file (e.g. typescript.md) | Code standards, import rules, type rules | Design tokens (just point to DESIGN.md) |
| Component-level docs | Architecture, registration steps, render logic | Design tokens (inherit from DESIGN.md) |
If a code rules file has a Styling section, keep it to one line: "TailwindCSS exclusively — see DESIGN.md for tokens and patterns."
Some things feel like code standards but are actually design decisions. When in doubt: if it governs how things look, it's design system; if it governs how code is written, it's code rules.
| Belongs in DESIGN.md | Belongs in code rules |
|---|---|
cn() / cva usage patterns (class composition is a styling tool) | "Use import type for type-only imports" |
Card contract: rounded-2xl bg-zinc-800 p-4 | "Named exports only, no default exports" |
Status color pattern: bg-emerald-400/10 text-emerald-400 | "No any type — use unknown and narrow" |
| "Never add borders to cards" | "TailwindCSS exclusively, no inline styles" |
| Animation timing defaults | Import ordering rules |
A common mistake is putting the card contract in the code rules file because it "looks like a coding pattern." It's a visual pattern — move it to the design system and point to it from code rules.
Most apps have a dominant card pattern for displaying structured data. Document it as a contract with a copy-paste template. This is the highest-value section — it's what enables one-shotting new components.
What to include:
/10 opacity pattern or whatever the project uses)Example contract (from a dark-first app):
Outer: rounded-2xl bg-zinc-800 p-4
Inner: rounded-2xl bg-zinc-900 p-3
Header: text-sm font-semibold text-zinc-100 mb-3
Title: text-sm font-medium text-zinc-200
Body: text-xs text-zinc-400
Meta: text-xs text-zinc-500
Gap: space-y-2
Status: bg-{color}-400/10 text-{color}-400
The template should be a real component someone can copy, rename, and fill in — not pseudocode.
"The PDF container is 330x150px" — this is one component's spec, not design language. The design system should say "use rounded-2xl for cards" and let each component decide its own dimensions.
The card contract appears in DESIGN.md, also in the TypeScript rules, also in a component-level doc. Now they'll drift. Pick one home.
Don't list every Shadcn component's props — that's in the component file. Document when to use which (the overlay hierarchy) and what they look like in this project (the customizations).
"Register the component in TOOL_RENDERERS" is a workflow step. "All data cards use rounded-2xl bg-zinc-800" is design language. The design system file should only contain the latter.
Without it, the tokens are just a list of values with no rationale. "Flat depth — never borders, only background layering" explains why there are no border classes anywhere and prevents someone from adding them.
If someone needs to read 800 lines before they can build a card, the doc is too long. Front-load the card template and checklist. Put reference material (full color tables, all animation classes) after the actionable patterns.