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

Project documentation and token sources live under design-workspace/. Ver design-workspace/README.md para crear rama y archivos desde un issue (etiqueta ui-design-workspace).

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

# Iconography (design-workspace)
npm run generate:icons-index      # Generate icon index
npm run generate:icon-thumbnails  # Generate icon thumbnails
npm run generate:icon-docs        # Generate icon docs

Project Structure

packages/ui-design-system/
├── .storybook/             # Storybook configuration
├── design-workspace/       # Source docs, specs and token files
├── src/
│   ├── atoms/              # Basic UI elements
│   ├── molecules/          # Composed components
│   ├── stories/            # Storybook documentation
│   ├── stitches.config.ts  # Stitches theme configuration
│   └── index.ts            # Main entry point
└── package.json

Design Tokens

Design tokens are sourced from design-workspace/tokens/ and consumed by the generated theme in src/stitches.config.ts.

There is currently no public tokens:transform script exposed in package.json.

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 @cordagehq/ui-design-system

Using Components

import { styled } from '@cordagehq/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 '@cordagehq/ui-design-system/stitches.config';

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

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

Dark Theme

Dark theme is currently not exposed in the public API and src/theme-dark.ts is not present in the current src tree.

If dark theme support is reintroduced, this README section will be updated with the official setup flow.

Contributing

See documentation under design-workspace/docs/ for component and governance guidelines.

Consumed by

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

License

MIT