Skip to content

dvy1987/agent-loom / .agents/skills/design-system

design-system

Verified

Turn a chosen design direction into a canonical DESIGN.md plus production tokens that don't look vibecoded — state-level colors (8-step neutral ramp, rest/hover/active/ disabled, focus ring), APCA-checked contrast, typography, spacing/radius/motion/elevation, an icon strategy, and component contracts for the core atoms. Emits tokens in the project's stack format (shadcn HSL vars or Tailwind v4 @theme). Load when the user asks to build a design system, generate design tokens, create a DESIGN.md, set up a theme, design a color or type system, pick icons, or when frontend-design routes here. Replaces design-tokens-craft and icon-craft. Sub-skill of frontend-design. Reads DIRECTION.md first.

references/design-md-template.md

View on GitHub
# DESIGN.md — Canonical Source-of-Truth Template

`DESIGN.md` is the ONE artifact every downstream step reads before styling anything. It
replaces the old scatter of ARCHETYPE.md / TOKENS.md / ICONS.md. Keep it tight and
machine-readable. Live at the project root (or `.design/<feature>/DESIGN.md` for scoped
work). Tokens also ship as real `tokens.css` — DESIGN.md is the human/agent contract.

Copy the structure below verbatim and fill every slot. No empty sections, no "TBD".

```markdown
# DESIGN.md — [Product]

> Single source of truth. Read this before generating or styling any UI.
> Direction: [name] — feels like [reference]. Posture: [one line].
> Stack: [e.g. React + Tailwind v4 + shadcn/ui]. Token format: [shadcn HSL vars / @theme].

## 1. Theme & Atmosphere
[2-3 sentences: mood, density, the one bold move that carries identity.]

## 2. Color (semantic roles, light + dark)
| Role | Light | Dark |
|---|---|---|
| surface-0 (base) | oklch(...) | oklch(...) |
| surface-1 (raised) | ... | ... |
| surface-2 (hover/sunken) | ... | ... |
| border-subtle | ... | ... |
| border-strong | ... | ... |
| text-primary | ... | ... |
| text-secondary | ... | ... |
| text-tertiary | ... | ... |
| accent | ... | ... |
| accent-hover | ... | ... |
| accent-active | ... | ... |
| text-on-accent | ... | ... |
| focus-ring (color / opacity) | ... | ... |
| status-success / warning / error / info | ... | ... |
Neutral ramp: 8 steps, oklch, dark hand-set (not inverted). See `state-tokens.md`.
APCA: body Lc≥75, large Lc≥45, non-text Lc≥30 — all pairs pass.

## 3. Typography
- Display: [family, weights, sizes, tracking]
- Body: [family, weights, sizes, line-height]
- Mono (if used): [family]
- Type scale: [list] · Reading column: [ch]
- Pairing rule: [one line — two families used confidently]

## 4. Spacing, Radius, Elevation, Motion
- Spacing (log): 4, 8, 12, 16, 24, 32, 48, 64, 96
- Radius: [chip < card < modal, e.g. 4 / 8 / 12]
- Elevation: [0-3 levels; borderless-card default]
- Motion: durations [instant/quick/base/emphasized] + curves [real cubic-bezier] + reduced-motion

## 5. Icons
- Strategy: [tuned-phosphor / custom-svg / system-native / mixed]
- Weight + size: [matched to type weight]; one family only. See `icon-strategies.md`.

## 6. Components (contracts for core atoms)
For each of button, input, card, nav, modal, table row:
| Component | Variants | Tokens consumed | Composition rule / use-when |
|---|---|---|---|
| Button | primary, secondary, ghost, destructive · sizes sm/md/lg | --button-* | primary = one per view; never inside a table cell |
| Card | default (borderless), interactive | --surface-1, --border-subtle | a card never contains another card |
| Input | text, select, textarea · rest/focus/error/disabled | --input-* | always paired with a <label> |
| ... | ... | ... | ... |
Every component defines rest / hover / active / focus-visible / disabled (+ loading/empty/error where it holds data).

## 7. Nevers (anti-slop guardrails)
- No Inter/Roboto as the only font; no pure #000/#fff; no slate/zinc default grey ramp.
- No purple→pink / indigo→violet gradient; no grey 1px border on every card.
- No 3-equal-column feature grid; no centered H1 + subhead + 2 CTAs default hero.
- No opacity-only hover; no `transition-all`; no Lucide default drop-in.
- [Add 2-3 product-specific nevers.]

## 8. Files
- src/styles/tokens.css  (or app/globals.css) — the live tokens
- src/styles/tokens.ts   — typed exports (optional)
```

---

## Notes
- Keep DESIGN.md under ~120 lines. Depth/rationale lives in `state-tokens.md` and the
  reference files, not here.
- If the stack is shadcn/ui, emit tokens in HSL channel format (`"240 33% 14%"`, no
  `hsl()` wrapper) so they slot into `hsl(var(--token))`. Otherwise emit `oklch()` under
  `:root` / `[data-theme="dark"]` (or Tailwind v4 `@theme`).
brainstormingobra/superpowersYou MUST use this before any creative work - creating features, building components, adding functionality, modifying behavior, or planning anything new, in software or out of it (a talk, a business, a renovation).Stars: 322kUpdated Claude CodeCodexVerifiedInstall
brand-guidelinesanthropics/skillsApplies Anthropic's official brand colors and typography to any sort of artifact that may benefit from having Anthropic's look-and-feel. Use it when brand colors or style guidelines, visual formatting, or company design standards apply.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
frontend-designanthropics/skillsGuidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.Stars: 198kUpdated Claude CodeCodexVerifiedInstall
mcp-builderanthropics/skillsGuide for creating high-quality MCP (Model Context Protocol) servers that enable LLMs to interact with external services through well-designed tools. Use when building MCP servers to integrate external APIs or services, whether in Python (FastMCP) or Node/TypeScript (MCP SDK).Stars: 198kUpdated Claude CodeCodexVerifiedInstall