27. Reference Architecture for a Modern Web Design System
Organize tokens, primitives, components, and documentation in a modern monorepo.
A practical monorepo might look like:
design-system/
├── apps/
│ ├── docs/
│ └── storybook/
│
├── packages/
│ ├── tokens/
│ ├── primitives/
│ ├── react/
│ ├── icons/
│ ├── eslint-config/
│ └── typescript-config/
│
├── .changeset/
├── package.json
├── pnpm-workspace.yaml
└── turbo.jsonPackage relationships
Diagram source
flowchart TD
TOKENS["@company/tokens"]
ICONS["@company/icons"]
PRIM["@company/primitives"]
REACT["@company/react"]
DOCS["Docs"]
SB["Storybook"]
APP["Product Apps"]
TOKENS --> PRIM
TOKENS --> REACT
ICONS --> REACT
PRIM --> REACT
REACT --> DOCS
REACT --> SB
REACT --> APPToken package
Outputs might include:
dist/tokens.css
dist/tokens.json
dist/tokens.tsReact package
Example structure:
src/
├── button/
│ ├── button.tsx
│ ├── button.test.tsx
│ ├── button.stories.tsx
│ └── index.ts
│
├── dialog/
├── input/
└── index.tsCSS strategy
Possible options:
- plain CSS
- CSS Modules
- Tailwind
- vanilla-extract
- Panda CSS
- CSS-in-JS
There is no universally correct answer.
Important requirements:
- token usage
- predictable styling
- theming
- SSR compatibility if needed
- low runtime cost
- consumer ergonomics