Spawn Partners — Design System

The single source of truth for the Spawn Partners brand. One spec for everything: marketing & client-facing work and internal tooling & shippable products.

Editorial, founder-led, technical. Warm paper and ink with a single clay-red accent used as a highlighter — never a theme color.

It ships as @spawn-llc/design-system — a React component library built on Base UI primitives (the full shadcn component set, themed from the tokens below) plus the raw design tokens and brand assets.

What's in here

SPEC.md                  ← the canonical spec. Read this first.
CLAUDE.md                ← auto-loaded rules for Claude Code / Claude Design
src/
  components/ui/         ← Base UI components, themed (button, card, table, …)
  styles/theme.css       ← shadcn/Tailwind-v4 theme derived from the tokens
  index.ts               ← public API (barrel export)
tokens/
  tokens.css             ← CSS custom properties — import, don't hardcode hex
  tokens.json            ← machine-readable tokens
assets/
  logo/                  ← Instance Mark + lockups (ink / paper / white)
  avatars/               ← profile marks (clay / ink / paper)
  banners/               ← social headers (LinkedIn, X, Slack)
examples/
  finance-dashboard-overview.png   ← internal-tooling reference
  brand-system-reference.png       ← full brand reference sheet
NOTES.md                 ← paste-ready copy for the Claude Design setup form

Quick start

• Color: White #FFFFFF base · Sand #F5F1E9 overlay · Ink #1A1916 · Clay #B8452C (the one accent). Char #2A2B2D for tool chrome only.
• Type: Newsreader (marketing/reports) · Geist (all UI/body/figures/labels) · Geist Mono (literal code only). Serif for what's said, sans for what's done, mono for code.
• Shape: 8px base, near-square corners (6px controls, 8px cards, ≤16px), hairlines over boxes, no shadows on anchored surfaces.

The one rule that matters most: clay marks exactly one element per view.

See SPEC.md for the full system.

Docs for agents

The brand docs ship inside the package and are read from the installed copy, so a coding agent always gets the docs that match the version in node_modules — no stale forks. There are two ways in.

MCP server (primary)

The package ships an MCP server that documents itself to your coding agent. Register it once — it's also auto-registered on install (skipped in CI):

npx @spawn-llc/design-system mcp init         # adds it to this project's .mcp.json

Your agent (e.g. Claude Code) then discovers these tools (approve the server on first use):

| Tool | What it returns | |------|-----------------| | overview | The agent guide — the brand non-negotiables. Start here. | | list_components / search_docs | Find the right primitive (filter/keyword). | | get_component | A component's variants, when-to-use, and real examples. | | get_spec | The full brand spec (section 7 = marketing vs product tiers). | | get_tokens | The token/color/type reference — use these, never hardcode hex. | | check_compliance | A brand checklist to self-verify generated UI. |

npx @spawn-llc/design-system mcp runs the stdio server directly (what the .mcp.json entry invokes).

CLI (fallback — no MCP client needed)

npx @spawn-llc/design-system docs            # the agent guide (AGENTS.md)
npx @spawn-llc/design-system docs spec        # the full brand spec (SPEC.md)
npx @spawn-llc/design-system docs reference   # generated token reference
npx @spawn-llc/design-system docs button      # a per-component doc
npx @spawn-llc/design-system list             # what's available
npx @spawn-llc/design-system init             # adds a pointer to AGENTS.md / CLAUDE.md

init writes a small marked block (never a copy of the docs), refreshed in place on re-run. The package also publishes static llms.txt (an index) and llms-full.txt (every doc inlined) for agents/tools without MCP. The same files render, browsable, in the playground's Agents / Spec / Reference pages.

Use the component library

npm install @spawn-llc/design-system

Peer dependencies: react and react-dom — React 18.2+ and React 19 both supported (developed, built, and tested on React 19).

Fonts — self-hosted, no external requests. Import once at your app entry:

import "@spawn-llc/design-system/fonts"

Styling — two paths:

1. Plain / no Tailwind — import the prebuilt stylesheet, then use components:

   import "@spawn-llc/design-system/styles.css"
   import { Button, Card } from "@spawn-llc/design-system"

2. Tailwind v4 consumers — import the brand theme into your CSS and add the package to your sources so the component classes compile (with tree-shaking):

   @import "tailwindcss";
   @import "@spawn-llc/design-system/theme.css";
   @source "../node_modules/@spawn-llc/design-system/dist";

import { Button } from "@spawn-llc/design-system"

export function Example() {
  return <Button>Get started</Button> // ink by default; clay reserved for one accent
}

Raw tokens are also exported directly: @spawn-llc/design-system/tokens.css and @spawn-llc/design-system/tokens.json.

Light mode only. Spawn has no dark theme — components ship no dark: utilities, and a .dark wrapper or OS dark-mode setting will not change the brand. There is nothing to opt into and nothing to configure.

Playground

A local development harness for previewing every component lives in playground/. It consumes the library from source, so adding a playground/src/demos/<name>.demo.tsx file surfaces it automatically — a coverage test fails the build if any component lacks a demo. It also includes a marketing-tier and an internal-tooling-tier view.

npm run play          # dev server with HMR
npm run play:build    # static build (local preview)

The playground is a local-only dev tool: it is not part of the published npm package, and it is not deployed anywhere.

Build, test, verify

npm run build         # tsup (ESM + types) + Tailwind (dist/styles.css)
npm run typecheck     # library types
npm run play:typecheck
npm test              # Vitest: coverage gate, behavior, demo smoke tests
npm run test:e2e      # Playwright: tier rendering + interaction

License

MIT © Spawn Partners.