ui

Supabase's shared React component library. Built on Radix UI primitives and shadcn/ui patterns; styled with Tailwind. Imported across every app via the 'ui' alias.

Purpose

A central, tree-shaken component package that all Supabase apps consume. The package owns nothing about layout — only primitives — and owns nothing about colour values — only semantic Tailwind tokens.

Directory layout

packages/ui/
├── index.tsx              # Top-level barrel re-exports
├── src/                   # Component sources
│   └── components/, lib/, hooks/, ...
├── build/                 # Build output
├── scripts/               # Token sync, registry helpers
├── components.json        # shadcn-style metadata
├── tailwind.config.js     # Stub for IntelliSense (real config is at workspace root)
├── vitest.config.ts
└── package.json

The actual Tailwind config that compiles styles is owned by the workspace root and propagated through Turborepo. The file in this package is a stub for editor IntelliSense (per packages/ui/README.md).

How to import

import { Badge, Button, clipboard, cn, Input, mergeDeep } from 'ui';

Some components have a _Shadcn_ suffix. Prefer the _Shadcn_ versions — the older non-suffixed ones are gradually being replaced.

Conventions

• Tailwind only. No inline styles. No CSS modules.
• Use semantic tokens — bg-muted, text-foreground-light, border-default, text-brand. Never raw colour names like gray-300.
• Components are headless-where-possible (Radix primitives) and stylable through className.
• Class composition uses cn() (clsx + tailwind-merge).
• Object merging for theme overrides uses mergeDeep.

How it works

The barrel index.tsx re-exports primitives from src/components/. Each primitive ships its own file with a default and a Radix-based composition. Tests live next to each primitive (*.test.tsx).

Tests

pnpm test:ui

Runs Vitest with @testing-library/react. CI workflow: ui-tests.yml.

Tokens

packages/ui/tokens/**/*.json is gitignored — those tokens are produced by token-build scripts under scripts/ and consumed by the design-system app for previews. The workspace's Tailwind configuration is the source of truth at runtime.

Integration points

• Consumed by every app under apps/ and several other packages (ui-patterns, marketing).
• Documented by apps/design-system and exposed publicly via apps/ui-library.

Entry points for modification

• Add a primitive → create a file in src/components/<component>.tsx, re-export from index.tsx, add a test, document it in apps/design-system.
• Add a hook or helper → place under src/hooks/ or src/lib/, re-export from index.tsx.
• Replace an older component → ship a _Shadcn_-suffixed version that wraps the Radix primitive, then deprecate the old one once consumers migrate.