Psi — themeable design system
Live site: psi.kurkin.de · Storybook
OKLCH-based design system for web applications, built on four core principles:
- OKLCH calculations, not swatch ladders. Semantic colors are formulas, not hand-picked scales.
- Pixel-true scale names.
psi-gap-8 means 8px; component sizes are numbers (32, 40), never S/M/L.
- Component-level tokens. Every component is independently themeable; derived states live in code, not as separate styles.
- Flat variant naming.
accent, accent-subtle, neutral — no primary/secondary hierarchies.
Workspace
- packages/tokens — Formula DSL, token definitions, codegen, CSS + JSON artifacts
- packages/react — 52 React 19 components (Button, IconButton, Card, Panel, Stack, Text, Toolbar, NavBar, SkipLink, NavTree, NavGroup, NavItem, AppShell, AspectRatio, Input, Select, Field, Dialog, Checkbox, Switch, Textarea, RadioGroup, Radio, Tag, Tooltip, Menu, MenuItem, MenuSeparator, MenuText, Table, TableHead, TableBody, TableRow, TableHeaderCell, TableCell, TableCaption, Pagination, CursorPagination, Toast, ToastRegion, ToastProvider, Announcement, Tabs, TabList, Tab, TabPanel, DescriptionList, DescriptionItem, Banner, InlineAlert, Skeleton, CopyButton) + 30 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 dependenciespnpm build — Build all packagespnpm test — Run vitest across the workspacepnpm 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
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.
