UI Design System — Components

A comprehensive design system built with React, Stitches CSS-in-JS, and Figma tokens.

Quick Start

Start Storybook

npm run storybook

Storybook will open at http://localhost:6006

Build Design System

npm run build

Run Tests

npm run test

Documentation

Getting Started

• Storybook Quick Start - Get started with Storybook
• Storybook Integration Guide - Complete Storybook + Stitches setup
• Dark Theme Configuration - Dark theme setup and usage

Font Awesome Pro Icons

• Font Awesome Pro README ⭐ START HERE - Overview and next steps
• Quick Reference - 30-second setup and API
• Complete Setup Guide - Detailed configuration guide
• Token Configuration - How to configure FA_TOKEN (IMPORTANT!)
• Solution to Common Error - If you get "Failed to replace env in config" error
• Troubleshooting - Common problems and solutions
• Verification Checklist - Verify everything works
• Implementation Details - Technical details

Theme & Configuration

• Dark Theme Setup Summary - Complete setup overview
• Storybook Configuration - Configuration details
• UI Contract - Technical contract
• Component Guidelines - How to create components

Tech Stack

• React 18 - UI library
• Stitches - CSS-in-JS for React
• Figma Tokens - Design tokens automation
• Font Awesome Pro - Icon library (9400+ icons in 5 styles)
• Storybook 8 - Component documentation
• Vite - Build tool
• TypeScript - Type safety
• Vitest - Testing framework

Scripts

# Development
npm run dev              # Start development server
npm run storybook       # Start Storybook documentation
npm run build-storybook # Build static Storybook

# Quality
npm run typecheck       # Type check with TypeScript
npm run lint           # Lint code with ESLint
npm run format         # Format code with Prettier

# Testing
npm run test           # Run tests with Vitest
npm run test:ui        # Run tests with UI
npm run test:coverage  # Generate coverage report

# Build
npm run build          # Build the package
npm run preview        # Preview the built package

# Tokens
npm run tokens:transform  # Transform Figma tokens to stitches config

# Components
npm run generate:component  # Generate new component scaffold

Project Structure

packages/ui-design-system/
├── .storybook/             # Storybook configuration
├── src/
│   ├── atoms/              # Basic UI elements
│   ├── molecules/          # Composed components
│   ├── organisms/          # Complex components
│   ├── templates/          # Page templates
│   ├── stories/            # Storybook documentation
│   ├── stitches.config.ts  # Stitches theme configuration
│   └── index.ts            # Main entry point
├── tokens/                 # Design tokens (Figma)
├── docs/                   # Documentation
├── contracts/              # Technical contracts
├── scripts/                # Build and utility scripts
└── package.json

Design Tokens

All design tokens are automatically generated from the tokens/ directory:

npm run tokens:transform

Tokens include:

• Colors - Brand and semantic colors
• Typography - Font sizes, weights, line heights
• Spacing - Padding, margins, gaps
• Border Radius - Rounded corner sizes
• Shadows - Box shadows
• Transitions - Animation durations and timing functions

Consuming this Package

Installation

npm install @cordage/ui-design-system

Using Components

import { styled } from '@cordage/ui-design-system/stitches.config';

const Button = styled('button', {
  padding: '$spacing-12 $spacing-16',
  backgroundColor: '$color-primary',
  borderRadius: '$borderRadius-md',
  // ... more styles
});

Using Tokens

import { getCssText, theme } from '@cordage/ui-design-system/stitches.config';

// Get CSS text for SSR
const styles = getCssText();

// Access theme tokens
const color = theme.colors['color-primary'];

Dark Theme

The design system supports a comprehensive dark theme with 260+ tokens automatically generated from semantic token definitions.

Generate Dark Theme

To regenerate the dark theme configuration from tokens:

node scripts/generate-dark-theme.js

This generates src/theme-dark.ts with all dark theme colors resolved from Figma tokens.

Using Dark Theme

In your application:

import { darkTheme } from './theme-dark';

// Apply to root element
document.documentElement.classList.add(darkTheme);

Or conditionally based on user preference:

import { darkTheme } from './theme-dark';

// Check system preference
const isDark = window.matchMedia('(prefers-color-scheme: dark)').matches;
if (isDark) {
  document.documentElement.classList.add(darkTheme);
}

// Listen for changes
window.matchMedia('(prefers-color-scheme: dark)').addEventListener('change', (e) => {
  if (e.matches) {
    document.documentElement.classList.add(darkTheme);
  } else {
    document.documentElement.classList.remove(darkTheme);
  }
});

Full Dark Theme Documentation

Contributing

See Component Guidelines for guidelines on creating new components.

Consumed by

• apps/frontend-app/
• apps/frontend-lovable/

License

MIT