design-system

A Next.js + Contentlayer site that documents Supabase's shared design system. Hosted at supabase.com/design-system.

Purpose

Living documentation for components, patterns, charts, fragments, and design tokens used across all Supabase apps. The app references components from packages/ui and packages/ui-patterns rather than housing them.

Directory layout

apps/design-system/
├── app/                        # Next.js App Router pages
├── components/                 # Site chrome and doc surface
├── content/docs/               # MDX docs for each component
├── config/                     # Sidebar / TOC config
├── contentlayer.config.js      # Contentlayer schema for MDX
├── registry/                   # Examples, fragments, charts, full-component examples
├── __registry__/               # Generated registry output (build artifact)
├── scripts/                    # build-registry.ts and friends
├── public/                     # Tokens and static assets
└── styles/

How it works

Components live in packages/ui (basic primitives) and packages/ui-patterns (composed patterns). The design-system app loads them, renders examples from registry/default/example/, and serves the corresponding MDX docs from content/docs/.

Adding or changing a component requires touching multiple places (per apps/design-system/README.md):

1. Add the component in packages/ui or packages/ui-patterns.
2. List it in apps/design-system/config/docs.ts (sidebar).
3. Add a doc in apps/design-system/content/docs/.
4. Register an example in apps/design-system/registry/examples.ts, with the example component under registry/default/example/.
5. Re-run pnpm --filter design-system build:registry.

The dev:full script (pnpm --filter design-system dev:full) runs the Next.js dev server alongside Contentlayer's content watcher so MDX edits hot-reload.

Local dev

cd apps/design-system
cp .env.local.example .env.local
pnpm i
pnpm dev:full     # → http://localhost:3003

Or from the repo root: pnpm dev:design-system (Next.js only) plus pnpm --filter=design-system content:dev in another shell for content watching.

Integration points

• Renders components from packages/ui and packages/ui-patterns.
• Mirrors the convention used by apps/ui-library (the public registry surface).
• Tokens published from packages/ui/tokens/**/*.json are gitignored and produced by token build scripts.

Entry points for modification

• Document a new primitive → add an MDX file in content/docs/<area>/<component>.mdx, then register the component in config/docs.ts.
• Add a code example → drop a .tsx file in registry/default/example/, register it in registry/examples.ts, then run pnpm build:registry.
• Update sidebar or section ordering → edit config/docs.ts.