Psi — themeable design system

Live site: psi.kurkin.de · Storybook

OKLCH-based design system for web applications, built on four core principles:

1. OKLCH calculations, not swatch ladders. Semantic colors are formulas, not hand-picked scales.
2. Pixel-true scale names. psi-gap-8 means 8px; component sizes are numbers (32, 40), never S/M/L.
3. Component-level tokens. Every component is independently themeable; derived states live in code, not as separate styles.
4. Flat variant naming. accent, accent-subtle, neutral — no primary/secondary hierarchies.

Workspace

• packages/tokens — Formula DSL, token definitions, codegen, CSS + JSON artifacts
• packages/react — 18 React 19 components (Button, IconButton, Card, Panel, Toolbar, NavBar, AspectRatio, Input, Select, Field, Dialog, Checkbox, Switch, Tag, Tooltip, Menu, MenuItem, MenuSeparator) + 22 icons
• packages/figma-plugin — In-repo Figma plugin syncing resolved tokens
• apps/storybook — Workbench and generated component documentation
• apps/promo — Public website (promo one-pager + update feed), built with Psi itself

Quick start

pnpm install
pnpm build
pnpm test
pnpm dev

• pnpm install — Install dependencies
• pnpm build — Build all packages
• pnpm test — Run vitest across the workspace
• pnpm dev — Start tokens watcher + Storybook dev server

Website

The public site (promo page at / + Storybook at /storybook/) deploys to Vercel from this repo:

• pnpm build:web — build all packages, then assemble site-dist/ (promo + storybook)
• pnpm dev:web — tokens watcher + promo (5199) + storybook (6006) dev servers
• Publish an update: add an entry to apps/promo/src/content/updates.ts, merge to main — the Vercel Git integration rebuilds and deploys the site.
• Vercel config lives in vercel.json (build command, output site-dist/).

Documentation

• Design spec — Principles, architecture, decisions
• Implementation plan — Active roadmap
• @handamade/psi-tokens README — Token usage and theming
• @handamade/psi-react README — Component usage and API

For AI: see llms.txt and per-package llms.txt files for machine-readable artifacts.

Agent access (MCP)

• Hosted (no install): Streamable HTTP at https://psi.kurkin.de/mcp
• Local (stdio): npx @handamade/psi-mcp

Tools: search(query) → compact briefs with ids · get(id) → full detail (component:Button, token:bgPrimary, topic:variants, or a bare name).

Generate agent context: npx @handamade/psi-mcp init (writes/updates AGENTS.md; add --claude for CLAUDE.md too). See packages/mcp/README.md.