Axiom

A React implementation of Optimizely's Axiom Design System.

For Users

Installation

npm install @optiaxiom/react

• Documentation
• Philosophy

AI Assistant Integration

We provide an MCP server that enables AI assistants like Claude Code and Cursor to access accurate Axiom component metadata, design tokens, and usage examples. This helps AI assistants generate better code using the Axiom design system.

npm install -g @optiaxiom/mcp

See the MCP guide for setup instructions.

For Contributors

Prerequisites

• Node.js: Version specified in .node-version
  • Install with fnm: fnm install
• pnpm: Version specified in package.json
  • Install with corepack: corepack enable

Project Structure

This is a monorepo containing multiple packages and applications:

optiaxiom/
├── packages/
│   ├── react/              # Main React component library (@optiaxiom/react)
│   ├── web-components/     # Framework-agnostic web components
│   ├── globals/            # Internal utilities and design tokens
│   ├── icons/              # Material Symbols icon kit (@optiaxiom/icons)
│   ├── mcp/                # MCP server for AI assistants (@optiaxiom/mcp)
│   ├── proteus/            # JSON-based UI spec renderer (@optiaxiom/proteus)
│   ├── codemod/            # Codemods for migrating Axiom code
│   └── shared/             # Shared build and development tools
├── apps/
│   ├── docs/               # Documentation site (Nextra + Next.js)
│   ├── storybook/          # Component development and visual testing
│   └── figma/              # Figma integration utilities
└── .changeset/             # Changesets for version management

Packages

• @optiaxiom/react: React component library
• @optiaxiom/web-components: Web component library
• @optiaxiom/globals: Design tokens and shared React contexts (for module federation)
• @optiaxiom/icons: Material Symbols icon kit
• @optiaxiom/proteus: Renderer for Proteus, a JSON-based UI specification for building interactive tool interfaces
• @optiaxiom/mcp: MCP server exposing component metadata to AI assistants
• @optiaxiom/codemod: Codemods for migrating Axiom code
• @optiaxiom/shared: Shared build tools (not for public use)

Apps

• docs: Public documentation site built with Nextra
• storybook: Component development and visual regression testing
• figma: Figma Code Connect integration

Architecture

Technology Stack

The project uses a modern, type-safe stack optimized for design system development:

Core Libraries:

• React - Component implementation
• TypeScript - Type safety
• Vanilla Extract - Zero-runtime CSS-in-JS with type-safe design tokens

Component Primitives:

• Radix UI - Accessible component primitives
• Downshift - Accessible comboboxes
• TanStack Table - Flexible table components
• React DayPicker - Date pickers and calendars

Development & Testing:

• Vitest - Unit testing
• Testing Library - Component testing
• Storybook - Component development & documentation
• Chromatic - Visual regression testing

Documentation & Tooling:

• Nextra - Documentation site
• Rollup - Package bundling
• Changesets - Version management & changelog

Design Tokens

Design tokens are defined in @optiaxiom/globals and provide a consistent design language:

• Colors: Semantic color system with light/dark mode support
• Spacing: Consistent spacing scale
• Typography: Font sizes, weights, and line heights
• Shadows: Elevation and depth
• Radii: Border radius values

Tokens are consumed via Vanilla Extract's type-safe API, ensuring consistency across components.

Component Development Flow

1. Design - Components start in Figma with design team approval
2. Develop - Built in Storybook with all variants and states
3. Test - Unit tests + interaction tests + visual regression
4. Document - API docs, usage examples, and demos
5. Review - Code review + design review via Chromatic
6. Release - Automated releases via Changesets

Build System

• Bundling: Rollup with ESM and CJS outputs
• CSS: Vanilla Extract generates static CSS at build time
• Types: Generated TypeScript declarations
• Tree-shaking: Components are individually importable for optimal bundle size

Contributing

For detailed contribution guidelines, see CONTRIBUTING.md.

Quick Start:

Clone the project and run:

pnpm install

Development

Run the following to start your dev environment:

pnpm dev

This will spin up all the apps and packages in dev mode. Use pnpm filtering to run individual apps:

# run docs only (along with all dependencies)
pnpm dev:docs

# run storybook only (along with all dependencies)
pnpm dev:storybook

Testing

Run lint and test to check the codebase and run unit tests respectively. pnpm lint type-checks, formats, and lints in one step (see CONTRIBUTING.md for details):

pnpm lint

# run tests (in watch mode)
pnpm test
# run tests (once and exit)
pnpm test run

Building

Run build to build the whole project or individual packages:

pnpm build

# build react only
pnpm -F react build

Thanks

Thanks to Chromatic for providing the visual testing platform that helps us review UI changes and catch visual regressions.