# standby.design

> Small tools for designers and developers. Generates production-ready design
> systems: OKLCH color palettes, fluid type scales, spacing & layout, shape
> tokens, and icon recommendations — exportable as CSS, Tailwind v4, or W3C
> design tokens.
> https://standby.design

Open source (MIT): https://github.com/KarstenKreh/Standby.Design
Free to use for everyone — humans and AI agents alike.

## For AI agents: the share link is the deliverable

If a user asks you to build a design system with standby.design:

1. **Use the MCP server.** Do NOT drive the website UI via browser automation,
   do NOT hand-construct URL hashes, and do NOT recompute the tokens yourself
   from the methodology — the generators are the source of truth.
   - Hosted endpoint, no install, no auth: `https://mcp.standby.design/mcp`
     (Streamable HTTP — usable from any remote-capable MCP client)
   - Local stdio: `npx -y standby-design-mcp`
   - Claude Code: `claude mcp add standby-design -- npx -y standby-design-mcp`
2. **Always give the returned URL to the user.** The first response line of
   every generate_* tool and export_design_system is the canonical share link (`https://standby.design/system#...`).
   The link IS the deliverable: it opens the complete design system with a
   live preview, and every value can be fine-tuned there. The full
   configuration lives in the URL hash — no accounts, no server-side storage.
   **Also store the link in the project you build**: put it as a comment above
   the tokens in the theme file (e.g. `theme.css`). Every export already starts
   with it. Without the link nobody can reopen and edit the system later; the
   tokens alone cannot restore it.
3. **Chain tools to build a full system.** Each tool edits only its own
   section of the URL and preserves the rest: pass the URL from one call into
   the next (generate_color_palette → generate_type_scale →
   generate_space_tokens → generate_shape_tokens → generate_icon_tokens →
   generate_motion_tokens →
   export_design_system for the final CSS/Tailwind code).
4. **No MCP available?** Tell the user to open https://standby.design and
   configure the tools manually — the share link can then be copied straight
   from the browser address bar.

### MCP server details

- Docs (install for Claude, Cursor and other clients): https://standby.design/docs/mcp
- Tools: generate_color_palette, generate_type_scale, generate_shape_tokens,
  generate_icon_tokens, generate_space_tokens, generate_motion_tokens,
  get_design_system, export_design_system, list_fonts, get_design_rules,
  update_project (steps to set up or update the design lint in a project)
- npm: https://www.npmjs.com/package/standby-design-mcp
- Source: https://github.com/KarstenKreh/Standby.Design/tree/master/packages/mcp-server

## Design rules

- Overview: https://standby.design/docs/rules
- All rules in one Markdown file: https://standby.design/docs/rules.md
- What: 63 rules for building UI with the tokens: layout, flow (empty,
  loading, error), shape, surfaces, interaction states, typography and color.
  59 are universal, 4 are stack rules for Tailwind and React Native. The
  generators deliver the values; the rules say how to use them.
- Each rule states the rule, why it holds, how to detect a violation in code,
  a right/wrong example, and its limits. Rules with a number separate the hard
  invariant from a soft default ("Korridor" = allowed range, "Vorgabe" =
  default until the project sets its own value).
- Via MCP: `get_design_rules` returns one line per rule, or the full text for a
  category or a list of rule slugs. Every LLM briefing export links the rules.
- Language: German.

## Design lint

- Page: https://standby.design/docs/lint
- What: the npm package `standby-design-lint` checks React and Vue code against
  the design rules with eight ESLint rules. Each message names the violation,
  the fix and the rule page. Messages and rule pages are in German. The rule
  ids:
  - `standby/no-raw-values`: colors, sizes and fonts set by hand, Tailwind
    palette colors
  - `standby/no-inline-style`: fixed values in inline styles
  - `standby/no-state-classes-in-views`: hover, focus and active classes
    outside the component folder
  - `standby/no-transition-all`: `transition-all`, `transition: all`
  - `standby/no-opacity-on-semantic-colors`: opacity modifiers like
    `bg-primary/10`
  - `standby/no-space-utilities`: `space-*` utilities and `last:mb-0`
  - `standby/no-disabled-by-validity`: `disabled={!isValid}` on buttons
  - `standby/no-click-on-non-interactive`: `onClick` on `div` or `span`
- Vue: in `.vue` files the lint checks the template (`class`, `:class` as object,
  array or ternary, `style`, `:style`, `:disabled`, `@click` on `div` or `span`),
  `<script>` and `transition: all` in `<style>`. It needs `vue-eslint-parser`,
  which `init` installs. Messages point to the line in the `.vue` file. The
  Biome plugins do not check Vue templates.
- Setup and update, run in the project root (needs a package.json, Node 20.19
  or newer): `npx standby-design-lint@latest init`. The command installs the
  package as a dev dependency and sets up:
  - a Claude Code hook in `.claude/settings.json`
  - a pre-commit hook in `.husky/` if the project uses husky, otherwise in the
    git hooks folder
  - the CI workflow `.github/workflows/design-lint.yml`, only if the project
    has a `.github` folder
  - the skill `.claude/skills/design-review`
  - a rules block in `AGENTS.md` and `CLAUDE.md`
  - the `standbyDesignLint` settings in `package.json`
  - `.design-review/` in `.gitignore`
  Running it again only updates and never duplicates entries. Hooks from other
  tools and your own text in CLAUDE.md and AGENTS.md stay.
- Strictness per stage:
  - Claude Code hook: reports violations in edited lines to the agent right
    after each edit. The agent fixes them in the same session.
  - Pre-commit: only warns (`--warn`). The commit goes through, also on a
    branch where the package is not installed.
  - CI workflow: fails a pull request with new violations.
  Only new or changed lines are checked, so projects with existing violations
  do not turn red.
- The hook works in Claude Code only. Cursor, Codex and other agents are
  covered by pre-commit, CI and the rules block in AGENTS.md.
- Update through the MCP server: tell the agent "Get the latest standby
  update" (German: "Hol Dir das Update"). It calls `update_project`, which
  returns the steps, and runs init.
- Exceptions: write an ESLint disable comment with a reason on the line before
  the violation, for example
  `// eslint-disable-next-line standby/no-raw-values -- brand color from the logo guideline`.
  Use the id of the rule that reports. In a Vue template, use an HTML comment:
  `<!-- eslint-disable-next-line standby/no-raw-values -- reason -->`.
- Text roles: each text gets one role. The role sets font, size, weight and
  line height. `title-1` (h1),
  `title-2` (h3), `title-3` (h5), `figure` (h2, regular weight, tabular
  numbers), `body` (body-m), `label` (body-s, weight 500), `meta` (caption).
  The classes `text-role-<role>` come from the Type export as a CSS class, a
  Tailwind v4 `@utility` or design tokens. Titles sit two scale steps apart.
- Visual review: `npx standby-design-lint review <url>` takes screenshots at
  1280 and 375 px and counts the text styles on the screen. The corridor is 4
  to 7 text styles, the default is 5. It needs Playwright:
  `npm i -D playwright && npx playwright install --only-shell chromium`. The
  skill `design-review` runs the review, starts a fresh review subagent and
  fixes the findings, in at most two rounds.
- Everything runs locally. The lint and init send no code or project data.
  The only network access is the package download from npm.
- npm: https://www.npmjs.com/package/standby-design-lint
- Source: https://github.com/KarstenKreh/Standby.Design/tree/master/packages/design-lint

## Research

- Overview: https://standby.design/docs/research
- All pages in one Markdown file: https://standby.design/docs/research.md
- What: the reasoning behind the tools. The rules say what to do, research says why. Each page sorts findings by strength of evidence (well replicated, weakly supported, folklore or industry convention), states what the tool does with it, and lists the key sources.
- Pages: perception of motion (why the Motion tool's Energy axis, calm to lively, rests on research on speed and arousal, while the Material axis, firm to elastic, is a design convention).
- Language: German. Not available via MCP yet.

## URL-as-state

All tools share one unified hash format:
`#c=<color>&t=<type>&s=<shape>&y=<icons>&p=<spacing>`
Each tool reads/writes only its own segment and preserves the rest, so links
accumulate a full design system. There are no accounts and no server-side
storage — the URL is the document.

## Tools

### Color Palette Generator
- URL: https://standby.design/color
- Purpose: Generate perceptually uniform color palettes in the OKLCH color space
- Output formats: CSS Custom Properties, Tailwind v4 config, Design Tokens (JSON), LLM briefing (Markdown)
- Features: Primitive & semantic tokens (shadcn/ui compatible), accent colors, shadow generation, light/dark/high-contrast modes; exports begin with a seed comment + restore URL so themes can be traced and rebuilt
- Use case: Designers and developers building accessible, perceptually uniform color systems for web apps

### Type Scale Generator
- URL: https://standby.design/type
- Purpose: Generate fluid typographic scales using mathematical ratios and clamp()
- Output formats: CSS Custom Properties, Tailwind v4 config, Design Tokens (JSON), Fontshare embed code
- Features: Golden ratio / custom ratio / traditional scales, fluid clamp() values, responsive mobile scales, live Fontshare font preview
- Use case: Designers and developers building consistent, responsive type hierarchies

### Spacing & Layout Generator
- URL: https://standby.design/space
- Purpose: Generate spacing scales, breakpoints, container widths, and aspect ratios
- Output formats: CSS Custom Properties, Tailwind v4 config, Design Tokens (JSON)
- Features: Harmonic and geometric (√φ) spacing modes, Tailwind-compatible breakpoints, container max-widths, aspect ratio tokens including golden and silver
- Use case: Designers and developers building consistent spatial systems independent of typography

### Motion Token Generator
- URL: https://standby.design/motion
- Purpose: Turn a brand's character (energy: calm to lively, material: firm to elastic) into spring-based motion tokens
- Output formats: CSS Custom Properties (linear() springs with cubic-bezier fallback), SwiftUI, Jetpack Compose, Motion (JS), Design Tokens (JSON)
- Features: Six primitive springs (spatial and effect, fast/default/slow), semantic tokens (press, move, expand, enter, exit, fade, navigate, sheet, container), reduced-motion variant with effects only
- Use case: Designers and developers who want motion that matches the brand and stays interruptible

### Shape Token Generator
- URL: https://standby.design/shape
- Purpose: Generate shape tokens — radii, shadows, borders, focus rings — in four visual styles
- Styles: paper (layered shadows), glass (liquid glass), neomorph, neobrutalism
- Output formats: CSS Custom Properties, Tailwind v4 config, LLM briefing
- Use case: Giving an app a coherent physical character (elevation, edges, focus) that matches its palette

### Icon Style Recommender
- URL: https://standby.design/symbol
- Purpose: Recommend an icon set matching the design's personality and generate icon sizing tokens
- Sets: Material Symbols, Lucide, Phosphor, Solar, Tabler, Radix — with style/weight/corner variants
- Output: size tokens (xs–2xl), stroke width, npm install command for the chosen set
- Use case: Picking and sizing icons consistently instead of mixing sets ad hoc

### Interaction Roles
- URL: https://standby.design/role
- Purpose: Show how interaction states (hover, pressed, focus, on, current, invalid) map onto the system's palette steps — and export the rules
- Roles: pressable, toggleable, editable, navigable, readable
- Output: CSS [data-*] state rules referencing the color export's tokens, plus a grammar.md file (role dictionary, combination rules, forbidden patterns) for AI agents
- Principle: behavior is platform truth and is not configurable; momentary states shift steps within the active palette, persistent states switch the palette
- Use case: Consistent interaction feedback without per-component state styling; grammar file as the single source of truth for AI-generated UI

### Design System Viewer
- URL: https://standby.design/system
- Purpose: Combined view of color + type + spacing + shape + icons with a live app preview and a merged export
- Output: one combined CSS / Tailwind v4 export plus an LLM briefing covering the entire system
- Use case: Reviewing, sharing, and exporting the complete design system from one URL

## How to use the generated code

All tools export production-ready code. Copy and paste into your project:

1. **CSS Custom Properties** — Copy into any global CSS file. Framework-agnostic. Works everywhere.
   - Color example: `var(--color-brand-500)`, `var(--color-surface-100)`, `var(--shadow-md)`
   - Type example: `var(--text-h1)`, `var(--leading-h3)`, `var(--space-md)`

2. **Tailwind v4** — Paste into your `@theme` block in Tailwind CSS v4.
   - Color example: `bg-brand-500`, `text-surface-900`, `shadow-md`
   - Type example: `text-h1`, `tracking-h3`, `gap-md`

3. **Design Tokens (JSON)** — W3C Design Tokens Community Group format with `$type` and `$value`.
   Import into Figma, Style Dictionary, or any token pipeline.

4. **LLM Briefing (Markdown)** — a usage guide for AI code generation: token tables, seed colors, and rules (e.g. form controls use `--input`, pair every background token with its `*-foreground`).

5. **Fontshare Embed** (Type tool only) — `<link>` tag to load the selected fonts from Fontshare CDN.

## Design philosophy

### Color: Why OKLCH?
OKLCH is a perceptually uniform color space — equal numeric steps produce equal visual steps. This means a palette generated in OKLCH looks consistently balanced across hues, unlike HSL where e.g. yellow and blue at the same lightness appear wildly different. The tool generates primitive tokens (raw shades) and semantic tokens (background, foreground, border, etc.) that map to shadcn/ui conventions.

### Type: Why √φ?
The Type Scale Generator defaults to a ratio near √φ ≈ 1.272. Historical type scales (Renaissance to modern) and natural proportions cluster around this value. It is a recommendation, not a strict rule — values in the range of roughly 1.2 to 1.35 produce harmonious typographic hierarchies. The tool generates fluid sizes via CSS clamp() that interpolate smoothly between mobile and desktop viewports.

## Technical details

- Color space: OKLCH (perceptually uniform lightness, chroma, hue)
- Color tokens: primitive scales (25–975), semantic mappings, shadow values with color-matched opacity
- Typography: fluid sizing via CSS clamp() with viewport-based interpolation between mobile and desktop
- Spacing: harmonic or geometric scales; breakpoints, containers, prose measure, aspect ratios
- All values are rem-based and respect user font-size preferences
- All computation is client-side and deterministic; the same URL always produces the same system