@spawn-llc/design-system 1.1.0

package/DESIGN-SYSTEM.md

@@ -0,0 +1,105 @@
+# Spawn Partners — Design System Reference
+
+<!-- GENERATED from tokens/tokens.json by scripts/generate-tokens.mjs. Do not edit by hand. -->
+> Generated from `tokens/tokens.json`. Do not edit by hand — run `npm run tokens:gen`.
+> Editorial guidance (voice, clay discipline, do/don't, tier rules) lives in [SPEC.md](./SPEC.md).
+
+Color ratio: 70% paper / 22% ink / ≤8% clay.
+
+## Color
+
+| Token | Hex | Role |
+|-------|-----|------|
+| paper | `#FAF8F3` | app/page background |
+| white | `#FFFFFF` | cards / surfaces |
+| mist | `#F2F0E9` | subtle fills, track bg, flat chart fill |
+| line | `#8C8678` | hairlines, borders, dividers — clears WCAG 3:1 on paper/white/mist |
+| stone | `#B7B1A4` | muted bars, disabled |
+| slate | `#6B655A` | secondary text, labels, axis ticks |
+| ink | `#1A1916` | primary text, dark surfaces, default buttons |
+| clay | `#C0492F` | THE accent — one element per view |
+| ember | `#9C3A23` | clay hover / pressed |
+| steel | `#2E3A46` | nav / chrome — internal tooling ONLY |
+| steel-2 | `#3B4855` | active nav row |
+| steel-border | `#7A8690` | steel chrome border — clears WCAG 3:1 on steel |
+| nav-inactive | `#A6B0BB` | inactive nav labels |
+| row-hover | `#FBFAF6` | table row hover |
+
+## Semantic roles
+
+How brand colors map onto component/theme roles (shadcn / Tailwind names).
+
+| Role | Brand token | Hex |
+|------|-------------|-----|
+| background | paper | `#FAF8F3` |
+| foreground | ink | `#1A1916` |
+| card | white | `#FFFFFF` |
+| card-foreground | ink | `#1A1916` |
+| popover | white | `#FFFFFF` |
+| popover-foreground | ink | `#1A1916` |
+| primary | ink | `#1A1916` |
+| primary-foreground | paper | `#FAF8F3` |
+| secondary | mist | `#F2F0E9` |
+| secondary-foreground | ink | `#1A1916` |
+| muted | mist | `#F2F0E9` |
+| muted-foreground | slate | `#6B655A` |
+| accent | mist | `#F2F0E9` |
+| accent-foreground | ink | `#1A1916` |
+| destructive | ember | `#9C3A23` |
+| border | line | `#8C8678` |
+| input | line | `#8C8678` |
+| ring | ink | `#1A1916` |
+| chart-1 | stone | `#B7B1A4` |
+| chart-2 | steel | `#2E3A46` |
+| chart-3 | slate | `#6B655A` |
+| chart-4 | mist | `#F2F0E9` |
+| chart-5 | clay | `#C0492F` |
+| sidebar | steel | `#2E3A46` |
+| sidebar-foreground | nav-inactive | `#A6B0BB` |
+| sidebar-primary | clay | `#C0492F` |
+| sidebar-primary-foreground | paper | `#FAF8F3` |
+| sidebar-accent | steel-2 | `#3B4855` |
+| sidebar-accent-foreground | white | `#FFFFFF` |
+| sidebar-border | steel-border | `#7A8690` |
+| sidebar-ring | clay | `#C0492F` |
+
+## Type
+
+| Family | Stack | Use | Weights |
+|--------|-------|-----|---------|
+| serif | `'Newsreader Variable', Georgia, serif` | page titles, editorial, empty states | 300, 400, 500 |
+| sans | `'Geist Variable', 'Geist', system-ui, Arial, sans-serif` | all UI / body / buttons / cells | 300, 400, 600 |
+| mono | `'Geist Mono Variable', 'Geist Mono', ui-monospace, 'SFMono-Regular', monospace` | labels, metadata, headers, figures-in-tables | 400, 500 |
+
+Mono is set uppercase, 0.12em tracking, `tabular-nums`.
+
+## Type scale
+
+| Role | Font | Size | Line height | Weight | Color |
+|------|------|------|-------------|--------|-------|
+| pageTitle | serif | 24px | 1.1 | 500 | — |
+| figure | mono | 28px | 1 | 500 | — |
+| section | sans | 14px | 1.3 | 600 | — |
+| body | sans | 13px | 1.5 | 400 | — |
+| secondary | sans | 12px | 1.4 | 400 | slate |
+| label | mono | 10px | 1 | 500 | slate |
+| axisTick | mono | 10px | 1 | 400 | slate |
+
+## Spacing
+
+8px base. Scale 4 · 8 · 16 · 24 · 32 · 48 · 64 · 96 (px), exposed as `--s-1`…`--s-8`.
+
+## Radius & shape
+
+| Step | Value |
+|------|-------|
+| xs | 2px |
+| sm | 3px |
+| md | 4px |
+| lg | 6px |
+| xl | 8px |
+| 2xl | 10px |
+| 3xl | 12px |
+| 4xl | 16px |
+
+Base control radius 4px, max 16px. Separators: hairline 1px line. Shadows: none on anchored surfaces; small warm shadow on floating overlays (dropdowns, popovers, menus, sheets).

package/README.md

@@ -0,0 +1,118 @@
+# 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](https://base-ui.com) 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:** Paper `#FAF8F3` · Ink `#1A1916` · Clay `#C0492F` (the one accent).
+  Ratio ~70/22/≤8. Steel `#2E3A46` for tool chrome only.
+- **Type:** Newsreader (titles) · Geist (UI/body) · Geist Mono
+  (labels/figures). Serif for what's said, sans for what's done, mono for what's
+  measured.
+- **Shape:** 8px base, near-square corners (4px controls, 6px cards, ≤16px),
+  hairlines over boxes, no shadows.
+
+The one rule that matters most: **clay marks exactly one element per view.**
+
+See [`SPEC.md`](./SPEC.md) for the full system.
+
+## Use the component library
+
+```bash
+npm install @spawn-llc/design-system
+```
+
+Peer dependencies: `react` and `react-dom` (>=18.2).
+
+**Fonts** — self-hosted, no external requests. Import once at your app entry:
+
+```ts
+import "@spawn-llc/design-system/fonts"
+```
+
+**Styling** — two paths:
+
+1. **Plain / no Tailwind** — import the prebuilt stylesheet, then use components:
+
+   ```ts
+   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):
+
+   ```css
+   @import "tailwindcss";
+   @import "@spawn-llc/design-system/theme.css";
+   @source "../node_modules/@spawn-llc/design-system/dist";
+   ```
+
+```tsx
+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`.
+
+## Playground
+
+A live, self-updating showcase of every component lives in [`playground/`](./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.
+
+```bash
+npm run play          # dev server with HMR
+npm run play:build    # static build (deployed to GitHub Pages on push to main)
+```
+
+The playground is not part of the published package.
+
+## Build, test, verify
+
+```bash
+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.

package/SPEC.md

@@ -0,0 +1,170 @@
+# Spawn Partners — Design System
+
+The single source of truth for the Spawn Partners brand. Applies to **everything**:
+marketing & client-facing work (website, one-pagers, proposals, decks, reports,
+email signatures) and internal tooling & shippable products (dashboards, apps,
+admin). When in doubt, match the rendered references in `/examples`.
+
+Editorial, founder-led, technical. Warm paper and ink with a single clay-red
+accent used as a highlighter — never as a theme color.
+
+---
+
+## 1. Color
+
+<!-- @tokens:auto:start spec-colors -->
+| Token | Hex | Role |
+|-------|-----|------|
+| Paper | `#FAF8F3` | app/page background |
+| White | `#FFFFFF` | cards / surfaces |
+| Mist | `#F2F0E9` | subtle fills, track bg, flat chart fill |
+| Line | `#8C8678` | hairlines, borders, dividers — clears WCAG 3:1 on paper/white/mist |
+| Stone | `#B7B1A4` | muted bars, disabled |
+| Slate | `#6B655A` | secondary text, labels, axis ticks |
+| Ink | `#1A1916` | primary text, dark surfaces, default buttons |
+| Clay | `#C0492F` | THE accent — one element per view |
+| Ember | `#9C3A23` | clay hover / pressed |
+| Steel | `#2E3A46` | nav / chrome — internal tooling ONLY |
+| Steel-2 | `#3B4855` | active nav row |
+<!-- @tokens:auto:end spec-colors -->
+
+<!-- Color values above are generated from tokens/tokens.json — edit there, run `npm run tokens:gen`. -->
+
+
+**Ratio:** ~70% paper · ~22% ink · ≤8% clay.
+
+**Clay discipline (the most important rule):** clay marks exactly **ONE element
+per view** — the live or critical figure (runway, overdue, shortfall), the
+single current/critical bar in a chart, an active-link underline, the active nav
+tick, or OVERDUE status. It is a highlighter, never a theme color. KPI numbers
+and data values are **ink by default**, not clay.
+
+No gradients, glows, or neon AI purple/blue. Ever.
+
+**Contrast (enforced):** every text/surface pair must clear WCAG AA (4.5:1) and
+every border/divider must clear 3:1 — this is why `Line` is `#8C8678` rather than
+a fainter tint. The real pairings are listed in `test/contrast.manifest.ts` and
+checked by `npm run test:contrast`, which runs on `git push` and in CI before
+deploy/publish. After changing any token or component color, keep that gate
+green.
+
+---
+
+## 2. Type
+
+Three families, three jobs. **Serif for what's *said*, sans for what's *done*,
+mono for what's *measured*.**
+
+- **Newsreader** (serif, 300/400/500) — page titles, editorial headlines, empty
+  states. One serif headline per view. **Never body copy, never labels.**
+- **Geist** (300/400/600) — all interface, body, buttons, table cells. The web
+  UI/body face. Falls back to system-ui → Arial.
+- **Geist Mono** (400/500) — labels, metadata, table headers, axis ticks,
+  figures in tables. UPPERCASE, letter-spacing ~0.12–0.14em.
+  Always `font-variant-numeric: tabular-nums` on numerals. **Never paragraphs.**
+
+Fonts are **self-hosted** (no external requests) via `@fontsource`. Apps using
+this design system get them by importing `@spawn-llc/design-system/fonts`;
+standalone usage installs `@fontsource-variable/geist`,
+`@fontsource-variable/newsreader`, and `@fontsource-variable/geist-mono`.
+
+### Type scale (interface / dashboard density)
+```
+Page title        Newsreader 500   24px / 1.1   tracking -0.01em
+KPI / card figure  Geist Mono 500   28px / 1.0   tabular-nums
+Section heading    Geist 600        14px / 1.3
+Body / table cell  Geist 400        13px / 1.5
+Secondary text     Geist 400        12px / 1.4   #6B655A
+Label (mono)       Geist Mono 500   10px / 0.12em uppercase  #6B655A
+Axis tick          Geist Mono 400   10px         #6B655A
+```
+In tools, body text never exceeds 14px. Marketing/editorial headlines scale up
+freely in Newsreader, but the role rules never change.
+
+---
+
+## 3. Spacing & shape
+
+- **8px base:** 4 · 8 · 16 · 24 · 32 · 48 · 64 · 96.
+- Marketing section padding ≥ 76px. Tool card padding ~20px. Page padding 28–36px.
+- **Near-square corners:** very light rounding — **4px** base on controls
+  (buttons, inputs), **6px** on cards/dialogs, up to **16px** on the largest
+  surfaces. Enough to take the hard edge off; never soft or pill-shaped.
+- **Hairlines over boxes:** separate with 1px `Line #8C8678` rules, or a 1px
+  grid-gap on a `Line` background — not heavy borders or shadows.
+- **No drop shadows on anchored surfaces** (cards, inputs, tabs). The one
+  exception: surfaces that float free of the layout — dropdowns, popovers,
+  selects, menus, tooltips, sheets — get a small warm-tinted shadow on top of
+  their 1px border so they read as lifted. **No card-on-card nesting.**
+  Left-aligned, asymmetric layouts.
+- Cards: `background:#FFFFFF; border:1px solid #8C8678;`.
+- Generous whitespace is the premium signal.
+
+---
+
+## 4. Components
+
+- **Buttons** — default = ink (`bg #1A1916`, text `#FAF8F3`), optional clay arrow
+  glyph inside. Secondary = transparent + 1.5px ink border. Clay-filled button is
+  rare. **One primary action per screen.**
+- **Links** — ink text with a 1.5px clay underline.
+- **Sidebar / nav** (internal tooling) — Steel `#2E3A46`; active row `#3B4855`
+  with a 5px clay tick; inactive labels `#A6B0BB`.
+- **Tables** — mono uppercase headers in Slate; cells in Geist; numerics
+  right-aligned in mono tabular-nums; row hover `#FBFAF6`; 1px `Line` dividers;
+  no zebra striping. Status like OVERDUE in clay with a leading `●`.
+- **Charts** — bars in Stone / steel tint; only the single current/critical bar
+  in clay; flat Mist fills (never gradient ramps); 1.5px solid ink line strokes;
+  dashed `Line` target/baseline; mono 10px axis ticks; 9px square swatches.
+
+---
+
+## 5. Logo
+
+Primary = the **Instance Mark** (stepped origin square → two outline squares,
+outermost in clay) + the wordmark "Spawn" 600 (ink) / "Partners" 400 (slate),
+set live in **Geist** — not baked into the SVG, so it stays crisp at any size and
+tracks the theme. In React, use the `Logo` component (`variant` lockup/mark/
+wordmark, `tone` default/on-ink). Min 20px digital / 8mm print. Clear space = the
+height of the origin square. Static files in `/assets/logo`.
+
+---
+
+## 6. Voice
+
+Founder-led, direct, technical, precise. Show real numbers and timelines.
+
+**Banned words:** revolutionary, synergy, cutting-edge, leverage (v.),
+supercharge, unlock, best-in-class, game-changing. **No emoji. No exclamation
+marks.**
+
+---
+
+## 7. Tier rules — what to use where
+
+**Marketing & client-facing** (website, one-pagers, proposals, decks, reports,
+signatures) — paper / ink / clay only. Newsreader headlines, Geist body,
+mono labels. Dark (ink) sections for covers and heroes; paper for content.
+**No Steel.** The brand at full editorial volume.
+
+**Internal tooling & shippable products** (dashboards, apps, admin) — same
+palette and type, but **Steel `#2E3A46` is allowed for nav/chrome** to separate
+"the tool" from "the brand." Data stays calm and neutral; clay marks only the
+live or critical figure. Default button is ink. Newsreader reserved for page
+titles and empty states; everything functional is Geist.
+
+**All tiers** — default action button = ink; clay button is rare; text links =
+ink with a clay underline; one primary action per screen.
+
+---
+
+## 8. Don't
+
+- No gradients, glowing blobs, neon AI purple/blue.
+- No pill tags or chip soup.
+- No rounded corners > 16px, no pill shapes. No drop shadows on anchored
+  surfaces (a small lift on floating overlays is fine).
+- No card-on-card nesting.
+- No stock "team at laptops" photos or generic 3D renders.
+- Don't let clay spread beyond one element per view.
+- No emoji, no exclamation marks.

package/dist/DESIGN-SYSTEM.md

@@ -0,0 +1,105 @@
+# Spawn Partners — Design System Reference
+
+<!-- GENERATED from tokens/tokens.json by scripts/generate-tokens.mjs. Do not edit by hand. -->
+> Generated from `tokens/tokens.json`. Do not edit by hand — run `npm run tokens:gen`.
+> Editorial guidance (voice, clay discipline, do/don't, tier rules) lives in [SPEC.md](./SPEC.md).
+
+Color ratio: 70% paper / 22% ink / ≤8% clay.
+
+## Color
+
+| Token | Hex | Role |
+|-------|-----|------|
+| paper | `#FAF8F3` | app/page background |
+| white | `#FFFFFF` | cards / surfaces |
+| mist | `#F2F0E9` | subtle fills, track bg, flat chart fill |
+| line | `#8C8678` | hairlines, borders, dividers — clears WCAG 3:1 on paper/white/mist |
+| stone | `#B7B1A4` | muted bars, disabled |
+| slate | `#6B655A` | secondary text, labels, axis ticks |
+| ink | `#1A1916` | primary text, dark surfaces, default buttons |
+| clay | `#C0492F` | THE accent — one element per view |
+| ember | `#9C3A23` | clay hover / pressed |
+| steel | `#2E3A46` | nav / chrome — internal tooling ONLY |
+| steel-2 | `#3B4855` | active nav row |
+| steel-border | `#7A8690` | steel chrome border — clears WCAG 3:1 on steel |
+| nav-inactive | `#A6B0BB` | inactive nav labels |
+| row-hover | `#FBFAF6` | table row hover |
+
+## Semantic roles
+
+How brand colors map onto component/theme roles (shadcn / Tailwind names).
+
+| Role | Brand token | Hex |
+|------|-------------|-----|
+| background | paper | `#FAF8F3` |
+| foreground | ink | `#1A1916` |
+| card | white | `#FFFFFF` |
+| card-foreground | ink | `#1A1916` |
+| popover | white | `#FFFFFF` |
+| popover-foreground | ink | `#1A1916` |
+| primary | ink | `#1A1916` |
+| primary-foreground | paper | `#FAF8F3` |
+| secondary | mist | `#F2F0E9` |
+| secondary-foreground | ink | `#1A1916` |
+| muted | mist | `#F2F0E9` |
+| muted-foreground | slate | `#6B655A` |
+| accent | mist | `#F2F0E9` |
+| accent-foreground | ink | `#1A1916` |
+| destructive | ember | `#9C3A23` |
+| border | line | `#8C8678` |
+| input | line | `#8C8678` |
+| ring | ink | `#1A1916` |
+| chart-1 | stone | `#B7B1A4` |
+| chart-2 | steel | `#2E3A46` |
+| chart-3 | slate | `#6B655A` |
+| chart-4 | mist | `#F2F0E9` |
+| chart-5 | clay | `#C0492F` |
+| sidebar | steel | `#2E3A46` |
+| sidebar-foreground | nav-inactive | `#A6B0BB` |
+| sidebar-primary | clay | `#C0492F` |
+| sidebar-primary-foreground | paper | `#FAF8F3` |
+| sidebar-accent | steel-2 | `#3B4855` |
+| sidebar-accent-foreground | white | `#FFFFFF` |
+| sidebar-border | steel-border | `#7A8690` |
+| sidebar-ring | clay | `#C0492F` |
+
+## Type
+
+| Family | Stack | Use | Weights |
+|--------|-------|-----|---------|
+| serif | `'Newsreader Variable', Georgia, serif` | page titles, editorial, empty states | 300, 400, 500 |
+| sans | `'Geist Variable', 'Geist', system-ui, Arial, sans-serif` | all UI / body / buttons / cells | 300, 400, 600 |
+| mono | `'Geist Mono Variable', 'Geist Mono', ui-monospace, 'SFMono-Regular', monospace` | labels, metadata, headers, figures-in-tables | 400, 500 |
+
+Mono is set uppercase, 0.12em tracking, `tabular-nums`.
+
+## Type scale
+
+| Role | Font | Size | Line height | Weight | Color |
+|------|------|------|-------------|--------|-------|
+| pageTitle | serif | 24px | 1.1 | 500 | — |
+| figure | mono | 28px | 1 | 500 | — |
+| section | sans | 14px | 1.3 | 600 | — |
+| body | sans | 13px | 1.5 | 400 | — |
+| secondary | sans | 12px | 1.4 | 400 | slate |
+| label | mono | 10px | 1 | 500 | slate |
+| axisTick | mono | 10px | 1 | 400 | slate |
+
+## Spacing
+
+8px base. Scale 4 · 8 · 16 · 24 · 32 · 48 · 64 · 96 (px), exposed as `--s-1`…`--s-8`.
+
+## Radius & shape
+
+| Step | Value |
+|------|-------|
+| xs | 2px |
+| sm | 3px |
+| md | 4px |
+| lg | 6px |
+| xl | 8px |
+| 2xl | 10px |
+| 3xl | 12px |
+| 4xl | 16px |
+
+Base control radius 4px, max 16px. Separators: hairline 1px line. Shadows: none on anchored surfaces; small warm shadow on floating overlays (dropdowns, popovers, menus, sheets).

package/dist/fonts.d.ts

@@ -0,0 +1,2 @@
+
+export {  }

package/dist/fonts.js

@@ -0,0 +1,3 @@
+import '@fontsource-variable/geist';
+import '@fontsource-variable/newsreader';
+import '@fontsource-variable/geist-mono';