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 — 34 React 19 components (Button, IconButton, Card, Panel, Toolbar, NavBar, AspectRatio, Input, Select, Field, Dialog, Checkbox, Switch, Tag, Tooltip, Menu, MenuItem, MenuSeparator, Table, TableHead, TableBody, TableRow, TableHeaderCell, TableCell, Pagination, Toast, ToastRegion, ToastProvider, Tabs, TabList, Tab, TabPanel, DescriptionList, DescriptionItem) + 26 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.