@cordagehq/ui-design-system 1.0.0

package/README.md

@@ -0,0 +1,214 @@
+# UI Design System — Components
+
+A comprehensive design system built with React, Stitches CSS-in-JS, and Figma tokens.
+
+## Quick Start
+
+### Start Storybook
+```bash
+npm run storybook
+```
+Storybook will open at `http://localhost:6006`
+
+### Build Design System
+```bash
+npm run build
+```
+
+### Run Tests
+```bash
+npm run test
+```
+
+## Documentation
+
+### Getting Started
+- **[Storybook Quick Start](./docs/getting-started/storybook-quickstart.md)** - Get started with Storybook
+- **[Storybook Integration Guide](./docs/getting-started/storybook.md)** - Complete Storybook + Stitches setup
+- **[Dark Theme Configuration](./docs/getting-started/dark-theme.md)** - Dark theme setup and usage
+
+### Font Awesome Pro Icons
+- **[Font Awesome Pro README](./FONTAWESOME_README.md)** ⭐ **START HERE** - Overview and next steps
+- **[Quick Reference](./FONTAWESOME_QUICK_REFERENCE.md)** - 30-second setup and API
+- **[Complete Setup Guide](./FONTAWESOME_SETUP.md)** - Detailed configuration guide
+- **[Token Configuration](./TOKEN_SETUP.md)** - How to configure FA_TOKEN (IMPORTANT!)
+- **[Solution to Common Error](./SOLUTION_ERROR.md)** - If you get "Failed to replace env in config" error
+- **[Troubleshooting](./TROUBLESHOOTING.md)** - Common problems and solutions
+- **[Verification Checklist](./FONTAWESOME_VERIFICATION.md)** - Verify everything works
+- **[Implementation Details](./FONTAWESOME_IMPLEMENTATION.md)** - Technical details
+
+### Theme & Configuration
+- **[Dark Theme Setup Summary](./DARK_THEME_SETUP.md)** - Complete setup overview
+- **[Storybook Configuration](./.storybook/README.md)** - Configuration details
+- **[UI Contract](./contracts/ui-contract.md)** - Technical contract
+- **[Component Guidelines](./docs/contributing/component-guidelines.md)** - 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
+
+```bash
+# 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:
+
+```bash
+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
+
+```bash
+npm install @cordage/ui-design-system
+```
+
+### Using Components
+
+```typescript
+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
+
+```typescript
+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:
+
+```bash
+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:
+
+```typescript
+import { darkTheme } from './theme-dark';
+
+// Apply to root element
+document.documentElement.classList.add(darkTheme);
+```
+
+Or conditionally based on user preference:
+
+```typescript
+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](./docs/getting-started/dark-theme.md)**
+
+## Contributing
+
+See [Component Guidelines](./docs/contributing/component-guidelines.md) for guidelines on creating new components.
+
+## Consumed by
+
+- `apps/frontend-app/`
+- `apps/frontend-lovable/`
+
+## License
+
+MIT

package/dist/atoms/Avatar.d.ts

@@ -0,0 +1,13 @@
+import { default as React } from 'react';
+export type AvatarSize = '2xs' | 'xxs' | 'xs' | 'sm' | 'md' | 'lg' | 'xl' | '2xl';
+export interface AvatarProps extends React.HTMLAttributes<HTMLDivElement> {
+    size?: AvatarSize;
+    src?: string;
+    alt?: string;
+    name?: string;
+    showBorder?: boolean;
+    showNotification?: boolean;
+    badgeIcon?: React.ReactNode;
+    onClick?: () => void;
+}
+export declare const Avatar: React.ForwardRefExoticComponent<AvatarProps & React.RefAttributes<HTMLDivElement>>;

package/dist/atoms/Badge.d.ts

@@ -0,0 +1,15 @@
+import { default as React } from 'react';
+export type BadgeVariant = 'primary' | 'secondary' | 'tertiary' | 'teal' | 'slate' | 'sunset' | 'success' | 'warning' | 'danger' | 'info' | 'white' | 'pink' | 'fuchsia' | 'violet' | 'indigo' | 'cyan' | 'gray' | 'dark' | 'black' | 'skeleton' | 'default' | 'error';
+export type BadgeSize = 'sm' | 'md' | 'lg';
+export type BadgeStyleType = 'solid' | 'outline' | 'dot';
+export interface BadgeProps extends React.HTMLAttributes<HTMLSpanElement> {
+    variant?: BadgeVariant;
+    size?: BadgeSize;
+    styleType?: BadgeStyleType;
+    children?: React.ReactNode;
+    /** Icon rendered before the text. Accepts a ReactNode (e.g. FontAwesomeIcon or <i> element). */
+    iconLeft?: React.ReactNode;
+    /** Icon rendered after the text. Accepts a ReactNode (e.g. FontAwesomeIcon or <i> element). */
+    iconRight?: React.ReactNode;
+}
+export declare const Badge: React.ForwardRefExoticComponent<BadgeProps & React.RefAttributes<HTMLSpanElement>>;

package/dist/atoms/Flag.d.ts

@@ -0,0 +1,39 @@
+import { default as React } from 'react';
+export type FlagSize = 'sm' | 'md' | 'lg';
+export interface FlagProps extends React.HTMLAttributes<HTMLDivElement> {
+    /**
+     * ISO 3166-1 alpha-2 country code (e.g., 'US', 'MX', 'ES')
+     */
+    countryCode: string;
+    /**
+     * Size of the flag
+     * @default 'md'
+     */
+    size?: FlagSize;
+    /**
+     * Whether to show a badge indicating this is the main language
+     * @default false
+     */
+    mainLanguage?: boolean;
+    /**
+     * Custom className for additional styling
+     */
+    className?: string;
+    /**
+     * Accessible label for the flag
+     */
+    'aria-label'?: string;
+}
+/**
+ * Flag Component
+ *
+ * Displays a country flag based on ISO 3166-1 alpha-2 country code.
+ * Optionally shows a badge to indicate the main language.
+ *
+ * @example
+ * ```tsx
+ * <Flag countryCode="US" size="md" />
+ * <Flag countryCode="MX" size="sm" mainLanguage />
+ * ```
+ */
+export declare const Flag: React.ForwardRefExoticComponent<FlagProps & React.RefAttributes<HTMLDivElement>>;

package/dist/atoms/Icon.d.ts

@@ -0,0 +1,72 @@
+import { default as React } from 'react';
+/**
+ * Icon component using Font Awesome Pro via CDN Kit
+ *
+ * Uses <i> tag with Font Awesome classes
+ * Supports 5 pro styles:
+ * - fas (Solid)
+ * - far (Regular)
+ * - fal (Light)
+ * - fat (Thin)
+ * - fad (Duotone)
+ */
+export interface IconProps {
+    /**
+     * Icon prefix: 'fas' | 'far' | 'fal' | 'fat' | 'fad' | 'fab'
+     */
+    prefix?: 'fas' | 'far' | 'fal' | 'fat' | 'fad' | 'fab';
+    /**
+     * Icon name (e.g., 'heart', 'star', 'user')
+     * See: https://fontawesome.com/icons
+     */
+    name: string;
+    /**
+     * Icon size: 'xs' | 'sm' | 'base' | 'lg' | 'xl' | '2xl'
+     * @default 'base'
+     */
+    size?: 'xs' | 'sm' | 'base' | 'lg' | 'xl' | '2xl';
+    /**
+     * Icon color - uses design tokens
+     * @default 'inherit'
+     */
+    color?: string;
+    /**
+     * Custom className for additional styling
+     */
+    className?: string;
+    /**
+     * Rotate the icon
+     */
+    rotation?: 90 | 180 | 270;
+    /**
+     * Flip the icon
+     */
+    flip?: 'horizontal' | 'vertical' | 'both';
+    /**
+     * Spin the icon
+     */
+    spin?: boolean;
+    /**
+     * Pulse the icon
+     */
+    pulse?: boolean;
+    /**
+     * Border around the icon
+     */
+    border?: boolean;
+}
+/**
+ * Icon Component
+ *
+ * Uses Font Awesome CDN Kit with <i> tags
+ *
+ * @example
+ * ```tsx
+ * <Icon prefix="fas" name="heart" size="lg" />
+ * <Icon prefix="far" name="star" color="primary" />
+ * <Icon prefix="fal" name="user" size="xl" />
+ * <Icon prefix="fat" name="bell" />
+ * <Icon prefix="fad" name="shield" size="2xl" color="success" />
+ * ```
+ */
+export declare const Icon: React.ForwardRefExoticComponent<IconProps & React.RefAttributes<HTMLElement>>;

package/dist/fontawesome.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Font Awesome Pro Integration
+ *
+ * This file provides utilities to use Font Awesome Pro icons
+ * Install via npm using the Font Awesome registry or use via CDN Kit
+ *
+ * NPM Setup in .npmrc:
+ * @fortawesome:registry=https://npm.fontawesome.com/
+ * //npm.fontawesome.com/:_authToken=${FA_TOKEN}
+ *
+ * Then install:
+ * - @fortawesome/fontawesome-pro
+ * - @fortawesome/fontawesome-svg-core
+ * - @fortawesome/react-fontawesome
+ */
+declare let FontAwesomeIcon: any;
+/**
+ * Register Font Awesome Pro icons globally
+ * Call this once at app initialization
+ *
+ * Example:
+ * import { fas } from '@fortawesome/pro-solid-svg-icons';
+ * initFontAwesome([fas]);
+ */
+export declare function initFontAwesome(iconLibraries?: any[]): void;
+/**
+ * Helper to find and use an icon
+ * Example: getIcon('fas', 'heart') returns the heart icon
+ */
+export declare function getIcon(prefix: 'fas' | 'far' | 'fal' | 'fat' | 'fad' | 'fab', iconName: string): any;
+export { FontAwesomeIcon };
+/**
+ * Usage in components:
+ *
+ * Method 1: NPM Packages (Recommended)
+ * ====================================
+ * import { FontAwesomeIcon, initFontAwesome } from '@cordage/ui-design-system';
+ * import { fas } from '@fortawesome/pro-solid-svg-icons';
+ *
+ * // Initialize once in your app
+ * initFontAwesome([fas]);
+ *
+ * // Use in components
+ * <FontAwesomeIcon icon={['fas', 'heart']} />
+ *
+ * Method 2: CDN Kit (Alternative)
+ * ===============================
+ * Set VITE_FONTAWESOME_KIT_ID in .env.local
+ * Then use HTML classes:
+ * <i className="fa-solid fa-heart"></i>
+ */

package/dist/fonts-cdn.html

@@ -0,0 +1,22 @@
+<!-- 
+  Cordage Design System - Font Loading
+  
+  This file contains the font loading links for the design system.
+  Copy these lines into your HTML file or use them in your bundler.
+-->
+
+<!-- Google Fonts Preconnect -->
+<link rel="preconnect" href="https://fonts.googleapis.com">
+<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+
+<!-- Satoshi - Primary UI Font (from Fontshare) -->
+<!-- Weights: 300, 400, 500, 600, 700 -->
+<link rel="stylesheet" href="https://api.fontshare.com/css?f[]=satoshi@300,400,500,600,700&display=swap">
+
+<!-- Lora - Secondary Serif Font (from Google Fonts) -->
+<!-- Weights: 400, 500, 600, 700 -->
+<link rel="stylesheet" href="https://fonts.googleapis.com/css2?family=Lora:wght@400;500;600;700&display=swap">
+
+<!-- Font Awesome Icons (Optional - from CDN) -->
+<!-- If you want to use Font Awesome icons, uncomment this line: -->
+<!-- <link rel="stylesheet" href="https://cdnjs.cloudflare.com/ajax/libs/font-awesome/6.7.0/css/all.min.css"> -->

package/dist/fonts.d.ts

@@ -0,0 +1,152 @@
+/**
+ * Fonts Configuration
+ *
+ * This file configures the typography system for the Cordage Design System.
+ * It defines @font-face rules for all fonts used in the design system.
+ *
+ * Fonts:
+ * - Satoshi: Primary UI font (sans-serif)
+ * - Lora: Secondary serif font
+ * - Font Awesome Pro: Icon font (via CDN Kit)
+ *
+ * Font Awesome Pro Configuration:
+ * Set your Kit ID in the environment variable: VITE_FONTAWESOME_KIT_ID
+ * The Kit ID is available at: https://fontawesome.com/account/kits
+ */
+/**
+ * Font Awesome Pro Configuration
+ * Get your Kit ID from: https://fontawesome.com/account/kits
+ */
+export declare const FONTAWESOME_KIT_ID: string;
+export declare const FONTAWESOME_KIT_URL: string;
+/**
+ * Import fonts from Google Fonts API and Font Awesome Pro
+ * This can be loaded via CDN link in HTML or via @import in CSS
+ */
+/**
+ * Register fonts by providing the `globalCss` function from the stitches
+ * instance. This avoids importing the stitches instance here and therefore
+ * prevents circular module initialization.
+ */
+export declare const registerFonts: (globalCss: (styles: any) => any) => any;
+/**
+ * Font stack definitions for use in components
+ */
+export declare const FONT_STACKS: {
+    ui: string;
+    serif: string;
+    mono: string;
+    icons: string;
+};
+/**
+ * Font weight values from tokens
+ */
+export declare const FONT_WEIGHTS: {
+    light: number;
+    regular: number;
+    medium: number;
+    semibold: number;
+    bold: number;
+};
+/**
+ * Font size values from tokens (in px)
+ */
+export declare const FONT_SIZES: {
+    '2xs': string;
+    xs: string;
+    sm: string;
+    md: string;
+    lg: string;
+    xl: string;
+    '2xl': string;
+    '3xl': string;
+    '4xl': string;
+    '5xl': string;
+    '6xl': string;
+};
+/**
+ * Line height values from tokens
+ */
+export declare const LINE_HEIGHTS: {
+    tight: string;
+    normal: string;
+    relaxed: string;
+};
+/**
+ * Typography presets combining font, size, and weight
+ * Use these for consistent typography across components
+ */
+export declare const TYPOGRAPHY_PRESETS: {
+    h1: {
+        fontSize: string;
+        fontWeight: number;
+        lineHeight: string;
+        fontFamily: string;
+    };
+    h2: {
+        fontSize: string;
+        fontWeight: number;
+        lineHeight: string;
+        fontFamily: string;
+    };
+    h3: {
+        fontSize: string;
+        fontWeight: number;
+        lineHeight: string;
+        fontFamily: string;
+    };
+    h4: {
+        fontSize: string;
+        fontWeight: number;
+        lineHeight: string;
+        fontFamily: string;
+    };
+    h5: {
+        fontSize: string;
+        fontWeight: number;
+        lineHeight: string;
+        fontFamily: string;
+    };
+    h6: {
+        fontSize: string;
+        fontWeight: number;
+        lineHeight: string;
+        fontFamily: string;
+    };
+    body: {
+        fontSize: string;
+        fontWeight: number;
+        lineHeight: string;
+        fontFamily: string;
+    };
+    'body-small': {
+        fontSize: string;
+        fontWeight: number;
+        lineHeight: string;
+        fontFamily: string;
+    };
+    'body-large': {
+        fontSize: string;
+        fontWeight: number;
+        lineHeight: string;
+        fontFamily: string;
+    };
+    label: {
+        fontSize: string;
+        fontWeight: number;
+        lineHeight: string;
+        fontFamily: string;
+    };
+    caption: {
+        fontSize: string;
+        fontWeight: number;
+        lineHeight: string;
+        fontFamily: string;
+    };
+    code: {
+        fontSize: string;
+        fontWeight: number;
+        lineHeight: string;
+        fontFamily: string;
+    };
+};

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Cordage Design System
+ *
+ * Main entry point for the design system.
+ * Exports Stitches utilities (styled, css, etc.) and themes.
+ */
+export { styled, css, globalCss, keyframes, getCssText, theme, createTheme, config, type CSS, type VariantProps, } from './stitches.config';
+export { FONT_STACKS, FONT_WEIGHTS, FONT_SIZES, LINE_HEIGHTS, TYPOGRAPHY_PRESETS, FONTAWESOME_KIT_ID, FONTAWESOME_KIT_URL, } from './fonts';
+export { initFontAwesome, getIcon, FontAwesomeIcon } from './fontawesome';
+export { Badge, type BadgeProps, type BadgeVariant, type BadgeSize, type BadgeStyleType, } from './atoms/Badge';
+export { Icon, type IconProps } from './atoms/Icon';
+export { Avatar, type AvatarProps, type AvatarSize } from './atoms/Avatar';
+export { Flag, type FlagProps, type FlagSize } from './atoms/Flag';
+export { Card, type CardProps, type CardDensity, type CardSurface, type CardStatus, type CardHeaderProps, type CardBodyProps, type CardFooterProps, } from './molecules/Card';