Capper UI
An open source, token-first React design system built on Brad Frost's atomic design
principles.
Packages
| Package | Description |
|---|
@capper-ui/tokens | CSS custom properties: primitives and semantic tokens, light/dark theming |
@capper-ui/react | React atoms built on the token layer: Box, Text, Button, Input, Link, Badge, Alert, Icon, Stack, Inline, and the Card molecule |
@capper-ui/docs | Storybook + a multi-page documentation site |
Requirements
- pnpm >= 9 (for developing this repo)
Install
pnpm add @capper-ui/tokens @capper-ui/react
import '@capper-ui/tokens';
import { Button, Icon, Sun } from '@capper-ui/react';
Develop this repo
git clone https://github.com/chetanraj/capper-ui.git
cd capper-ui
pnpm install
pnpm dev # docs site at localhost:5173
pnpm storybook # Storybook at localhost:6006
Docs site (Netlify)
Live site: capper-ui-docs.netlify.app
Build and deploy settings live in netlify.toml. From the repo root:
netlify deploy --build --filter @capper-ui/docs # preview
netlify deploy --prod --filter @capper-ui/docs # production
Scripts
| Command | Description |
|---|
pnpm build | Build all packages |
pnpm build:docs | Build react + docs site (Netlify deploy output) |
pnpm test | Run all tests (Vitest) |
pnpm test:watch | Run Vitest in watch mode |
pnpm test:coverage | Run Vitest with coverage |
pnpm lint | Lint TS/TSX/JSON with Biome |
pnpm lint:fix | Lint and auto-fix with Biome |
pnpm lint:css | Lint CSS with Stylelint |
pnpm lint:css:fix | Lint and auto-fix CSS |
pnpm format | Format TS/TSX/JSON with Biome |
pnpm typecheck | Type-check all packages |
Principles
- Token-first. Every color, space, radius, and shadow a component uses
is a CSS custom property (
--c-*). No raw hex or magic numbers in
component styles. Stylelint enforces this.
- Two-layer tokens. Primitives are raw, named-by-value scales.
Semantic tokens reference primitives and carry meaning (
--c-accent,
--c-surface, --c-danger); only semantic tokens are used outside the
tokens package.
- Atomic design.
packages/react/src/{atoms,molecules,organisms}
mirrors Brad Frost's atomic design model. Atoms exist today; molecules
and organisms are scaffolded for what comes next.
- CSS Modules. Each component owns a co-located
.module.css file.
No CSS-in-JS, no utility-class soup.
License
Capper UI is MIT licensed.
Contributing
See CONTRIBUTING.md for setup, design rules, and pull request guidelines.
