Skip to content

Add the design kit preview bundle #503

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
mtaanquist merged 1 commit into from
Jul 29, 2026
Merged

Add the design kit preview bundle #503

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
55 changes: 55 additions & 0 deletions scratch/design-kit/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@
# Design kit

Preview cards for the Codex design system, built for syncing into a Claude
Design (claude.ai/design) design-system project so design sessions work from
the real system instead of a description.

Each `*.html` file is one card: a self-contained page that renders a
canonical primitive in all three themes (dark, light, warm) side by side,
using the real CSS. The first line of each file is a `@dsCard` marker with
the card's group; the Design System pane uses it to build its index.

## Ground rules

- `styles/` is a symlink to `src/lib/styles/`. The kit has no CSS of its
own beyond per-card scaffolding; the shipped stylesheets are the single
source of truth, and the cards always render whatever is currently
shipped.
- Cards show only the canonical primitives named in
`scratch/system-design/design-system.md`. Legacy skins (the extra button
and menu systems listed in that sheet's drift section) stay out, so
design sessions never learn them.
- Markup in the cards mirrors real call sites in `src/lib/components/` and
`src/routes/`. When a primitive's markup changes in the app, update its
card.
- Fonts: the app loads Hanken Grotesk, Spectral, and JetBrains Mono via
fontsource. The kit does not, so previews fall back to the system stacks
declared in the tokens. Shapes and colours are accurate; letterforms are
approximate.

## Viewing locally

Open any card straight from this directory in a browser; the symlink makes
the shipped CSS resolve. No build step.

## Syncing to Claude Design

Use the DesignSync tool from a Claude Code session (it needs the user
present to approve the plan):

1. `list_projects`, or `create_project` the first time.
2. `finalize_plan` with writes for `styles/*.css`, `*.html`, `kit.css`,
and `kit.js`, with this directory as `localDir`.
3. `write_files` uploading the stylesheets into the project's `styles/`
and the cards plus the two kit scaffold files at the project root. The
symlink means `localPath: styles/tokens.css` resolves to the shipped
file.

Re-run the sync whenever a primitive or token changes. The sync is one-way,
repo to project; never edit the system inside the project.

## Cards

Foundations: `colors.html`, `type.html`, `spacing.html`.
Components: `buttons.html`, `forms.html`, `menus.html`, `badges.html`,
`seg.html`, `cards.html`, `empty-states.html`.
49 changes: 49 additions & 0 deletions scratch/design-kit/badges.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,49 @@
<!-- @dsCard group="Components" -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Badges, chips, pills</title>
<link rel="stylesheet" href="styles/tokens.css" />
<link rel="stylesheet" href="styles/theme.css" />
<link rel="stylesheet" href="styles/pages.css" />
<link rel="stylesheet" href="kit.css" />
</head>
<body>
<div class="themes" id="themes"></div>
<template id="sample">
<div class="kit-h">Badge: entity identity</div>
<div class="row">
<span class="badge dot" style="background: var(--cat-violet)"></span>
<span class="badge sm" style="background: var(--cat-teal)">H</span>
<span class="badge sm" style="background: var(--cat-rose)">A</span>
<span class="badge lg" style="background: var(--cat-blue)">M</span>
</div>
<div class="kit-h">Chip: interactive token</div>
<div class="row">
<span class="chip">Mrs. Fenwick <button type="button" class="chip-x" aria-label="Remove">&times;</button></span>
<span class="chip muted">treaty</span>
<span class="chip dashed">Add alias</span>
<span class="chip link">Halden</span>
</div>
<div class="kit-h">Pill: static status label</div>
<div class="row">
<span class="pill">Nightly</span>
<span class="pill pill-accent">Current</span>
</div>
<div class="kit-h">Status dots</div>
<div class="row">
<span class="scene-dot" style="background: var(--status-outline)"></span> outline
<span class="scene-dot" style="background: var(--status-draft)"></span> draft
<span class="scene-dot" style="background: var(--status-revised)"></span> revised
<span class="scene-dot" style="background: var(--status-final)"></span> final
</div>
<p class="note">
Three words, three meanings: a badge marks an entity's identity, a chip is an interactive
token (tags, filters, add-affordances), a pill is a small static label. Status dots use
the four status tokens only.
</p>
</template>
<script src="kit.js"></script>
</body>
</html>
61 changes: 61 additions & 0 deletions scratch/design-kit/buttons.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,61 @@
<!-- @dsCard group="Components" -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Buttons</title>
<link rel="stylesheet" href="styles/tokens.css" />
<link rel="stylesheet" href="styles/theme.css" />
<link rel="stylesheet" href="styles/pages.css" />
<link rel="stylesheet" href="kit.css" />
</head>
<body>
<div class="themes" id="themes"></div>
<template id="sample">
<div class="row">
<button class="btn btn-primary" type="button">Primary</button>
<button class="btn btn-secondary" type="button">Secondary</button>
<button class="btn btn-ghost" type="button">Ghost</button>
<button class="btn btn-danger" type="button">Delete</button>
</div>
<div class="row">
<button class="btn btn-primary btn-sm" type="button">Small primary</button>
<button class="btn btn-secondary btn-sm" type="button">Small secondary</button>
<button class="btn btn-secondary" type="button" disabled>Disabled</button>
</div>
<div class="row">
<button class="icon-btn" type="button" title="Add" aria-label="Add">
<svg
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
stroke-width="1.8"
stroke-linecap="round"
stroke-linejoin="round"
>
<path d="M12 5v14M5 12h14" />
</svg>
</button>
<button class="icon-btn" type="button" title="Search" aria-label="Search">
<svg
viewBox="0 0 24 24"
fill="none"
stroke="currentColor"
stroke-width="1.8"
stroke-linecap="round"
stroke-linejoin="round"
>
<circle cx="11" cy="11" r="7" />
<path d="m21 21-4.3-4.3" />
</svg>
</button>
</div>
<p class="note">
The only general button system. One primary action per view; ghost for quiet actions
inside panels; danger only for destructive actions. Icon-only buttons use icon-btn with an
aria-label. Do not invent a new button skin.
</p>
</template>
<script src="kit.js"></script>
</body>
</html>
68 changes: 68 additions & 0 deletions scratch/design-kit/cards.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,68 @@
<!-- @dsCard group="Components" -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Cards</title>
<link rel="stylesheet" href="styles/tokens.css" />
<link rel="stylesheet" href="styles/theme.css" />
<link rel="stylesheet" href="styles/pages.css" />
<link rel="stylesheet" href="styles/admin.css" />
<link rel="stylesheet" href="kit.css" />
<style>
.pane .story-card {
max-width: 300px;
}
.pane .r-card,
.pane .admin-card {
max-width: 300px;
margin-bottom: 14px;
}
</style>
</head>
<body>
<div class="themes" id="themes"></div>
<template id="sample">
<div class="kit-h">Story card (library)</div>
<a class="story-card" href="#story" style="margin-bottom: 14px">
<div class="story-card-header">
<h3 class="story-card-title">Book of ash</h3>
<span class="story-card-status">
<span class="scene-dot" style="background: var(--status-draft)"></span>
Draft
</span>
</div>
<p class="story-card-brief">The first winter after the burning of the archive.</p>
<div class="story-card-meta">
<span>12 chapters</span>
<span class="story-card-meta-sep">&middot;</span>
<span>48,200 words</span>
<span class="story-card-meta-sep">&middot;</span>
<span>edited 3 weeks ago</span>
</div>
</a>
<div class="kit-h">Reference card (right pane)</div>
<div class="r-card">
<h5>Today</h5>
<div class="r-sub">Words in this story</div>
<div class="r-line">1,240</div>
</div>
<div class="kit-h">Settings card</div>
<div class="admin-card">
<div class="field">
<label for="kit-card-name">Universe name</label>
<input id="kit-card-name" class="input" value="The shattered realms" />
</div>
<div class="settings-actions">
<button class="btn btn-primary" type="button">Save</button>
</div>
</div>
<p class="note">
Three card families by home: story-card on the library, r-card in the right reference
pane, admin-card for settings and admin sections. New content in those homes composes the
matching family.
</p>
</template>
<script src="kit.js"></script>
</body>
</html>
98 changes: 98 additions & 0 deletions scratch/design-kit/colors.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,98 @@
<!-- @dsCard group="Foundations" -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Colors</title>
<link rel="stylesheet" href="styles/tokens.css" />
<link rel="stylesheet" href="kit.css" />
<style>
.sw-grid {
display: grid;
grid-template-columns: repeat(auto-fill, minmax(92px, 1fr));
gap: 8px;
margin-bottom: 6px;
}
.sw {
border: 1px solid var(--border);
border-radius: var(--radius-sm);
overflow: hidden;
font-size: 10.5px;
color: var(--text-muted);
}
.sw i {
display: block;
height: 32px;
}
.sw span {
display: block;
padding: 4px 6px;
}
.tx b {
display: block;
font-weight: 500;
font-size: 13.5px;
}
</style>
</head>
<body>
<div class="themes" id="themes"></div>
<template id="sample">
<div class="kit-h">Surfaces, back to front</div>
<div class="sw-grid">
<div class="sw"><i style="background: var(--bg)"></i><span>bg</span></div>
<div class="sw"><i style="background: var(--bg-elevated)"></i><span>bg-elevated</span></div>
<div class="sw"><i style="background: var(--bg-panel)"></i><span>bg-panel</span></div>
<div class="sw"><i style="background: var(--bg-card)"></i><span>bg-card</span></div>
<div class="sw"><i style="background: var(--bg-canvas)"></i><span>bg-canvas</span></div>
<div class="sw"><i style="background: var(--bg-inset)"></i><span>bg-inset</span></div>
<div class="sw"><i style="background: var(--bg-hover)"></i><span>bg-hover</span></div>
<div class="sw"><i style="background: var(--bg-active)"></i><span>bg-active</span></div>
</div>
<div class="kit-h">Text tiers and borders</div>
<div class="row tx">
<b style="color: var(--text)">text</b>
<b style="color: var(--text-muted)">text-muted</b>
<b style="color: var(--text-faint)">text-faint</b>
</div>
<div class="sw-grid">
<div class="sw"><i style="background: var(--border)"></i><span>border</span></div>
<div class="sw"><i style="background: var(--border-strong)"></i><span>border-strong</span></div>
</div>
<div class="kit-h">Accent and danger</div>
<div class="sw-grid">
<div class="sw"><i style="background: var(--accent)"></i><span>accent</span></div>
<div class="sw"><i style="background: var(--accent-soft)"></i><span>accent-soft</span></div>
<div class="sw"><i style="background: var(--accent-line)"></i><span>accent-line</span></div>
<div class="sw"><i style="background: var(--danger)"></i><span>danger</span></div>
<div class="sw"><i style="background: var(--danger-soft)"></i><span>danger-soft</span></div>
</div>
<div class="kit-h">Status</div>
<div class="sw-grid">
<div class="sw"><i style="background: var(--status-outline)"></i><span>outline</span></div>
<div class="sw"><i style="background: var(--status-draft)"></i><span>draft</span></div>
<div class="sw"><i style="background: var(--status-revised)"></i><span>revised</span></div>
<div class="sw"><i style="background: var(--status-final)"></i><span>final</span></div>
</div>
<div class="kit-h">Category tints</div>
<div class="sw-grid">
<div class="sw"><i style="background: var(--cat-violet)"></i><span>violet</span></div>
<div class="sw"><i style="background: var(--cat-rose)"></i><span>rose</span></div>
<div class="sw"><i style="background: var(--cat-green)"></i><span>green</span></div>
<div class="sw"><i style="background: var(--cat-blue)"></i><span>blue</span></div>
<div class="sw"><i style="background: var(--cat-amber)"></i><span>amber</span></div>
<div class="sw"><i style="background: var(--cat-red)"></i><span>red</span></div>
<div class="sw"><i style="background: var(--cat-lime)"></i><span>lime</span></div>
<div class="sw"><i style="background: var(--cat-teal)"></i><span>teal</span></div>
<div class="sw"><i style="background: var(--cat-cyan)"></i><span>cyan</span></div>
<div class="sw"><i style="background: var(--cat-fuchsia)"></i><span>fuchsia</span></div>
</div>
<p class="note">
Every colour in the app is one of these tokens. Text on accent fills uses
accent-contrast, never white. Status colours mark scene and story state only; category
tints mark whatever the user colour-codes. New tints derive with color-mix over a token.
</p>
</template>
<script src="kit.js"></script>
</body>
</html>
35 changes: 35 additions & 0 deletions scratch/design-kit/empty-states.html
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,35 @@
<!-- @dsCard group="Components" -->
<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8" />
<title>Empty states</title>
<link rel="stylesheet" href="styles/tokens.css" />
<link rel="stylesheet" href="styles/theme.css" />
<link rel="stylesheet" href="kit.css" />
<style>
.pane .kit-frame {
border: 1px dashed var(--border-strong);
border-radius: var(--radius);
margin-bottom: 14px;
}
</style>
</head>
<body>
<div class="themes" id="themes"></div>
<template id="sample">
<div class="kit-frame">
<div class="empty">Select a scene to start writing.</div>
</div>
<div class="kit-frame">
<div class="empty">No mentions in this scene yet.</div>
</div>
<p class="note">
One empty-state primitive: centred, faint, thirteen pixels. The text is one short
sentence telling the user what to do next, never why the area exists. The dashed frame
here is scaffolding, not part of the primitive.
</p>
</template>
<script src="kit.js"></script>
</body>
</html>
Loading