Getting started

For engineers#

Components live at src/components/ui/* and are imported directly:

import { Button, TrustBadge, ProductCard } from "@/components/ui";

export default function Demo() {
return (
  <ProductCard
    title="XX-002 Selvedge Jeans"
    brand="Oyama Denim"
    price="$298"
    tier="t3"
    buyUrl="https://example.com"
  />
);
}

Styling is via Tailwind v4 utilities wired to the tokens in globals.css. Prefer bg-teal, text-fg, bg-surface, border-border over raw colors. When Tailwind falls short, use var(--color-...) directly.

Design tokens#

All tokens are declared once in src/app/globals.css on :root and exposed to Tailwind via @theme inline. See tokens for the full list.

Adding a new token: add the CSS variable on :root, expose it under @theme inline, and document it in tokens. New tokens land in the changelog.

Contributing#

1. Change a component. Edit the file at src/components/ui/<Name>.tsx. If the change affects visible API, update src/lib/design-site/props.ts so the props table stays accurate.
2. Change a token. Edit src/app/globals.css. All components reference tokens, so downstream changes ripple automatically. Test in both light and dark.
3. Add a component. Create the file in src/components/ui/, add a props entry in src/lib/design-site/props.ts, and author its page at src/app/design/components/<kebab-name>/page.mdx. Add it to the nav in src/lib/design-site/nav.ts.
4. Write the docs. Follow the existing spine: Overview → Preview with variants → Usage → Props → Code → Accessibility. Every component page looks the same on purpose.

Philosophy#

• Document what we ship, not what we wish we shipped. If a component doesn't exist in src/components/ui/, it doesn't get a page.
• Prose is part of the system. Usage notes matter as much as the code. Teach the why.
• Ship the site, then iterate. Missing pieces are tracked in the changelog — not hidden behind “coming soon” modals.