Design tokens a component library system

# Design Tokens & Component Library: FitFlow

## 1. Token Architecture

**Token Hierarchy:**
```
Global Tokens (Primitives)
↓
Alias Tokens (Semantic)
↓
Component Tokens (Specific)
```

**Example Flow:**
```json
// Global (literal color)
"color.blue.500": "#3B82F6"

// Alias (semantic meaning)
"color.primary": "{color.blue.500}"

// Component (specific use)
"button.primary.bg": "{color.primary}"
```

**Naming Convention:**
```
[category]-[property]-[variant]-[state]

Examples:
color-text-primary (base state)
color-text-primary-hover (interaction state)
space-padding-card (component-specific)
fontSize-heading-xl (size variant)
```

**Token Categories:**
1. **Color** - Brand, semantic, state colors
2. **Spacing** - Margins, padding, gaps
3. **Typography** - Fonts, sizes, weights, line heights
4. **Shadows** - Elevation, depth
5. **Borders** - Widths, radii
6. **Animation** - Durations, easing
7. **Breakpoints** - Responsive design
8. **Z-index** - Layering

**Semantic vs Literal:**
```json
// ❌ Literal (hard to maintain)
"buttonBackground": "#3B82F6"

// ✅ Semantic (flexible)
"buttonBackground": "{color.primary}"
// Now changing brand color updates all buttons
```

---

## 2. Color Tokens

### Primitive Colors (Brand Palette)
```json
{
"color": {
"brand": {
"blue": {
"50": "#EFF6FF",
"100": "#DBEAFE",
"200": "#BFDBFE",
"300": "#93C5FD",
"400": "#60A5FA",
"500": "#3B82F6", // Primary
"600": "#2563EB",
"700": "#1D4ED8",
"800": "#1E40AF",
"900": "#1E3A8A"
},
"green": {
"500": "#10B981", // Success/Activity
"600": "#059669"
},
"red": {
"500": "#EF4444", // Error/Heart rate
"600": "#DC2626"
},
"yellow": {
"500": "#F59E0B" // Warning/Calories
}
},
"gray": {
"50": "#F9FAFB",
"100": "#F3F4F6",
"200": "#E5E7EB",
"300": "#D1D5DB",
"400": "#9CA3AF",
"500": "#6B7280",
"600": "#4B5563",
"700": "#374151",
"800": "#1F2937",
"900": "#111827"
}
}
}
```

### Semantic Color Tokens
```json
{
"color": {
// Text
"text": {
"primary": "{color.gray.900}",
"secondary": "{color.gray.600}",
"disabled": "{color.gray.400}",
"inverse": "#FFFFFF",
"link": "{color.brand.blue.600}",
"error": "{color.brand.red.600}",
"success": "{color.brand.green.600}"
},
// Backgrounds
"bg": {
"primary": "#FFFFFF",
"secondary": "{color.gray.50}",
"tertiary": "{color.gray.100}",
"inverse": "{color.gray.900}",
"success": "{color.brand.green.50}",
"error": "{color.brand.red.50}",
"warning": "{color.brand.yellow.50}"
},
// Borders
"border": {
"default": "{color.gray.200}",
"hover": "{color.gray.300}",
"focus": "{color.brand.blue.500}",
"error": "{color.brand.red.500}"
},
// Interactive
"interactive": {
"primary": "{color.brand.blue.500}",
"primary-hover": "{color.brand.blue.600}",
"primary-pressed": "{color.brand.blue.700}",
"secondary": "{color.gray.200}",
"secondary-hover": "{color.gray.300}"
}
}
}
```

### Theme Variants (Light/Dark)
```json
{
"light": {
"color.text.primary": "#111827",
"color.bg.primary": "#FFFFFF"
},
"dark": {
"color.text.primary": "#F9FAFB",
"color.bg.primary": "#111827"
}
}
```

### Alpha Variants (Opacity)
```json
{
"color": {
"overlay": {
"light": "rgba(0, 0, 0, 0.5)", // 50% black
"dark": "rgba(0, 0, 0, 0.75)", // 75% black
"inverse": "rgba(255, 255, 255, 0.9)" // 90% white
},
"scrim": "rgba(0, 0, 0, 0.32)" // Modal backdrop
}
}
```

**Usage Documentation:**
```
color.text.primary → Body text, headlines
color.text.secondary → Captions, metadata
color.interactive.primary → CTA buttons, links
color.bg.success → Success alerts background
```

---

## 3. Spacing Tokens

**Base Unit: 8px Grid System**
```json
{
"space": {
"0": "0px",
"1": "4px", // 0.5x
"2": "8px", // 1x (base)
"3": "12px", // 1.5x
"4": "16px", // 2x
"5": "20px", // 2.5x
"6": "24px", // 3x
"8": "32px", // 4x
"10": "40px", // 5x
"12": "48px", // 6x
"16": "64px", // 8x
"20": "80px", // 10x
"24": "96px" // 12x
}
}
```

**Semantic Spacing Names:**
```json
{
"space": {
"xs": "{space.1}", // 4px
"sm": "{space.2}", // 8px
"md": "{space.4}", // 16px
"lg": "{space.6}", // 24px
"xl": "{space.8}", // 32px
"2xl": "{space.12}", // 48px
"3xl": "{space.16}" // 64px
}
}
```

**Component-Specific Spacing:**
```json
{
"space": {
"button": {
"paddingX": "{space.4}", // 16px horizontal
"paddingY": "{space.2}", // 8px vertical
"gap": "{space.2}" // 8px icon-text gap
},
"card": {
"padding": "{space.4}", // 16px all sides
"gap": "{space.3}" // 12px between elements
},
"layout": {
"gutter": "{space.4}", // 16px grid gutter
"section": "{space.12}" // 48px section spacing
}
}
}
```

**Responsive Modifiers:**
```json
{
"space": {
"container": {
"mobile": "{space.4}", // 16px on mobile
"tablet": "{space.6}", // 24px on tablet
"desktop": "{space.8}" // 32px on desktop
}
}
}
```

---

## 4. Typography Tokens

**Font Families:**
```json
{
"font": {
"primary": "Inter, -apple-system, BlinkMacSystemFont, sans-serif",
"mono": "'JetBrains Mono', 'Courier New', monospace",
"display": "'Poppins', sans-serif" // For headlines
}
}
```

**Font Sizes (Type Scale):**
```json
{
"fontSize": {
"xs": "12px", // 0.75rem
"sm": "14px", // 0.875rem
"base": "16px", // 1rem (default)
"lg": "18px", // 1.125rem
"xl": "20px", // 1.25rem
"2xl": "24px", // 1.5rem
"3xl": "30px", // 1.875rem
"4xl": "36px", // 2.25rem
"5xl": "48px", // 3rem
"6xl": "64px" // 4rem
}
}
```

**Line Heights:**
```json
{
"lineHeight": {
"none": "1",
"tight": "1.25",
"snug": "1.375",
"normal": "1.5",
"relaxed": "1.625",
"loose": "2"
}
}
```

**Font Weights:**
```json
{
"fontWeight": {
"light": "300",
"normal": "400",
"medium": "500",
"semibold": "600",
"bold": "700",
"extrabold": "800"
}
}
```

**Letter Spacing:**
```json
{
"letterSpacing": {
"tighter": "-0.05em",
"tight": "-0.025em",
"normal": "0em",
"wide": "0.025em",
"wider": "0.05em",
"widest": "0.1em"
}
}
```

**Typography Presets:**
```json
{
"typography": {
"h1": {
"fontFamily": "{font.display}",
"fontSize": "{fontSize.4xl}",
"fontWeight": "{fontWeight.bold}",
"lineHeight": "{lineHeight.tight}",
"letterSpacing": "{letterSpacing.tight}"
},
"body": {
"fontFamily": "{font.primary}",
"fontSize": "{fontSize.base}",
"fontWeight": "{fontWeight.normal}",
"lineHeight": "{lineHeight.normal}",
"letterSpacing": "{letterSpacing.normal}"
},
"caption": {
"fontFamily": "{font.primary}",
"fontSize": "{fontSize.sm}",
"fontWeight": "{fontWeight.normal}",
"lineHeight": "{lineHeight.snug}",
"color": "{color.text.secondary}"
}
}
}
```

---

## 5. Component Tokens

### Button Tokens
```json
{
"button": {
"primary": {
"bg": "{color.interactive.primary}",
"bg-hover": "{color.interactive.primary-hover}",
"bg-pressed": "{color.interactive.primary-pressed}",
"bg-disabled": "{color.gray.200}",
"text": "#FFFFFF",
"text-disabled": "{color.gray.400}",
"border": "transparent"
},
"secondary": {
"bg": "transparent",
"bg-hover": "{color.gray.100}",
"text": "{color.interactive.primary}",
"border": "{color.interactive.primary}"
},
"height": {
"sm": "32px",
"md": "40px",
"lg": "48px"
},
"paddingX": {
"sm": "{space.3}", // 12px
"md": "{space.4}", // 16px
"lg": "{space.6}" // 24px
},
"borderRadius": "8px",
"fontSize": {
"sm": "{fontSize.sm}",
"md": "{fontSize.base}",
"lg": "{fontSize.lg}"
},
"fontWeight": "{fontWeight.semibold}",
"shadow": "{shadow.sm}",
"shadow-hover": "{shadow.md}"
}
}
```

### Input Tokens
```json
{
"input": {
"bg": "{color.bg.primary}",
"border": "{color.border.default}",
"border-hover": "{color.border.hover}",
"border-focus": "{color.border.focus}",
"border-error": "{color.border.error}",
"text": "{color.text.primary}",
"placeholder": "{color.text.secondary}",
"height": "44px", // Touch-friendly
"paddingX": "{space.3}",
"borderRadius": "8px",
"fontSize": "{fontSize.base}",
"focus": {
"ring": "0 0 0 3px rgba(59, 130, 246, 0.1)" // Blue glow
}
}
}
```

### Card Tokens
```json
{
"card": {
"bg": "{color.bg.primary}",
"border": "{color.border.default}",
"padding": "{space.4}",
"borderRadius": "12px",
"shadow": "{shadow.sm}",
"shadow-hover": "{shadow.md}"
}
}
```

---

## 6. Shadow & Elevation

**Shadow Levels:**
```json
{
"shadow": {
"none": "none",
"xs": "0 1px 2px 0 rgba(0, 0, 0, 0.05)",
"sm": "0 1px 3px 0 rgba(0, 0, 0, 0.1), 0 1px 2px 0 rgba(0, 0, 0, 0.06)",
"md": "0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06)",
"lg": "0 10px 15px -3px rgba(0, 0, 0, 0.1), 0 4px 6px -2px rgba(0, 0, 0, 0.05)",
"xl": "0 20px 25px -5px rgba(0, 0, 0, 0.1), 0 10px 10px -5px rgba(0, 0, 0, 0.04)",
"2xl": "0 25px 50px -12px rgba(0, 0, 0, 0.25)",
"inner": "inset 0 2px 4px 0 rgba(0, 0, 0, 0.06)"
}
}
```

**Elevation Scale (Z-Index):**
```json
{
"zIndex": {
"base": "0",
"dropdown": "1000",
"sticky": "1100",
"fixed": "1200",
"modal-backdrop": "1300",
"modal": "1400",
"popover": "1500",
"tooltip": "1600",
"notification": "1700"
}
}
```

**Usage:**
```
shadow.sm → Cards, buttons (resting state)
shadow.md → Cards on hover, dropdowns
shadow.lg → Modals, overlays
shadow.2xl → Hero images, featured content
```

---

## 7. Border & Radius

**Border Widths:**
```json
{
"borderWidth": {
"0": "0px",
"1": "1px",
"2": "2px",
"4": "4px",
"8": "8px"
}
}
```

**Border Radius Scale:**
```json
{
"borderRadius": {
"none": "0px",
"sm": "4px",
"md": "8px",
"lg": "12px",
"xl": "16px",
"2xl": "24px",
"3xl": "32px",
"full": "9999px" // Pills, circles
}
}
```

**Usage:**
```
radius.sm → Input fields, small buttons
radius.md → Cards, buttons (default)
radius.lg → Large cards, modals
radius.full → Avatar, pill buttons, badges
```

---

## 8. Animation Tokens

**Duration:**
```json
{
"duration": {
"instant": "0ms",
"fast": "150ms",
"normal": "300ms",
"slow": "500ms",
"slower": "700ms"
}
}
```

**Easing Functions:**
```json
{
"easing": {
"linear": "cubic-bezier(0, 0, 1, 1)",
"easeIn": "cubic-bezier(0.4, 0, 1, 1)",
"easeOut": "cubic-bezier(0, 0, 0.2, 1)",
"easeInOut": "cubic-bezier(0.4, 0, 0.2, 1)",
"spring": "cubic-bezier(0.68, -0.55, 0.265, 1.55)" // Bounce
}
}
```

**Usage:**
```css
/* Button hover */
transition: background-color {duration.fast} {easing.easeOut};

/* Modal open */
transition: transform {duration.normal} {easing.spring};

/* Fade in */
transition: opacity {duration.slow} {easing.easeIn};
```

---

## 9. Implementation

### Source File (tokens.json)
```json
{
"color": {
"brand": {
"blue": {
"500": { "value": "#3B82F6", "type": "color" }
}
},
"text": {
"primary": { "value": "{color.gray.900}", "type": "color" }
}
},
"space": {
"4": { "value": "16px", "type": "dimension" },
"md": { "value": "{space.4}", "type": "dimension" }
},
"fontSize": {
"base": { "value": "16px", "type": "dimension" }
},
"button": {
"primary": {
"bg": { "value": "{color.brand.blue.500}", "type": "color" }
}
}
}
```

### CSS Variables Output
```css
:root {
/* Colors */
--color-brand-blue-500: #3B82F6;
--color-text-primary: var(--color-gray-900);

/* Spacing */
--space-4: 16px;
--space-md: var(--space-4);

/* Typography */
--fontSize-base: 16px;

/* Components */
--button-primary-bg: var(--color-brand-blue-500);
}

/* Usage in components */
.button-primary {
background-color: var(--button-primary-bg);
padding: var(--space-2) var(--space-4);
font-size: var(--fontSize-base);
}
```

### Platform-Specific Exports

**iOS (Swift)**
```swift
// Colors.swift
enum Colors {
static let brandBlue500 = UIColor(hex: \"#3B82F6\")
static let textPrimary = UIColor(hex: \"#111827\")
static let buttonPrimaryBg = Colors.brandBlue500
}

// Spacing.swift
enum Spacing {
static let space4: CGFloat = 16
static let md: CGFloat = space4
}
```

**Android (XML)**
```xml
<!-- colors.xml -->
<resources>
<color name=\"color_brand_blue_500\">#3B82F6</color>
<color name=\"color_text_primary\">#111827</color>
<color name=\"button_primary_bg\">@color/color_brand_blue_500</color>
</resources>

<!-- dimens.xml -->
<resources>
<dimen name=\"space_4\">16dp</dimen>
<dimen name=\"space_md\">@dimen/space_4</dimen>
</resources>
```

**React Native (JavaScript)**
```javascript
// tokens.js
export const colors = {
brand: {
blue: {
500: '\1'
}
},
text: {
primary: '\1'
},
button: {
primary: {
bg: '#3B82F6' // Resolved from {color.brand.blue.500}
}
}
};

export const space = {
4: 16,
md: 16 // Resolved from {space.4}
};

// Usage in components
import { colors, space } from './tokens';

const buttonStyle = {
backgroundColor: colors.button.primary.bg,
paddingHorizontal: space.md
};
```

**Flutter (Dart)**
```dart
// tokens.dart
class AppColors {
static const brandBlue500 = Color(0xFF3B82F6);
static const textPrimary = Color(0xFF111827);
static const buttonPrimaryBg = brandBlue500;
}

class AppSpacing {
static const double space4 = 16.0;
static const double md = space4;
}
```

### Build Pipeline (Style Dictionary)

**config.json**
```json
{
"source": [\"tokens/**/*.json\"],
"platforms": {
"css": {
"transformGroup\": \"css\",
\"buildPath\": \"build/css/\",
\"files\": [{
\"destination\": \"tokens.css\",
\"format\": \"css/variables\"
}]
},
"ios\": {
\"transformGroup\": \"ios\",
\"buildPath\": \"build/ios/\",
\"files\": [{
\"destination\": \"Tokens.swift\",
\"format\": \"ios-swift/class.swift\"
}]
},
\"android\": {
\"transformGroup\": \"android\",
\"buildPath\": \"build/android/\",
\"files\": [{
\"destination\": \"tokens.xml\",
\"format\": \"android/resources\"
}]
},
\"react-native\": {
\"transformGroup\": \"js\",
\"buildPath\": \"build/rn/\",
\"files\": [{
\"destination\": \"tokens.js\",
\"format\": \"javascript/es6\"
}]
}
}
}
```

**Build Command:**
```bash
npm install style-dictionary
style-dictionary build --config config.json
```

---

## 10. Component Library

### Atomic Design Structure
```
components/
├── atoms/
│ ├── Button/
│ │ ├── Button.tsx
│ │ ├── Button.styles.ts
│ │ ├── Button.stories.tsx
│ │ └── Button.test.tsx
│ ├── Input/
│ ├── Text/
│ ├── Icon/
│ └── Badge/
├── molecules/
│ ├── InputGroup/ (Input + Label + Error)
│ ├── Card/
│ ├── StatCard/
│ └── SearchBar/
├── organisms/
│ ├── Header/
│ ├── WorkoutCard/
│ ├── ProfileStats/
│ └── ActivityFeed/
└── templates/
├── DashboardLayout/
└── WorkoutDetailLayout/
```

### Button Component Example

**Button.tsx (React)**
```typescript
import { tokens } from '@/design-tokens';
import { ButtonContainer } from './Button.styles';

interface ButtonProps {
variant: 'primary' | 'secondary' | 'ghost';
size: 'sm' | 'md' | 'lg';
children: React.ReactNode;
disabled?: boolean;
onPress: () => void;
}

export const Button = ({
variant = 'primary',
size = 'md',
children,
disabled = false,
onPress
}: ButtonProps) => {
return (
<ButtonContainer
variant={variant}
size={size}
disabled={disabled}
onPress={onPress}
>
{children}
</ButtonContainer>
);
};
```

**Button.styles.ts (Styled Components)**
```typescript
import styled from 'styled-components/native';
import { tokens } from '@/design-tokens';

interface ContainerProps {
variant: string;
size: string;
disabled: boolean;
}

export const ButtonContainer = styled.TouchableOpacity<ContainerProps>`
/* Layout */
height: ${
props => props.size === 'sm' ? tokens.button.height.sm :
props.size === 'lg' ? tokens.button.height.lg :
tokens.button.height.md
};
padding-horizontal: ${
props => props.size === 'sm' ? tokens.button.paddingX.sm :
props.size === 'lg' ? tokens.button.paddingX.lg :
tokens.button.paddingX.md
};
border-radius: ${tokens.button.borderRadius};

/* Colors */
background-color: ${
props => props.disabled ? tokens.button.primary['bg-disabled'] :
props.variant === 'primary' ? tokens.button.primary.bg :
props.variant === 'secondary' ? tokens.button.secondary.bg :
'transparent'
};

/* Border */
border-width: ${
props => props.variant === 'secondary' ? '2px' : '0px'
};
border-color: ${
props => props.variant === 'secondary' ? tokens.button.secondary.border : 'transparent'
};

/* Shadow */
shadow-color: #000;
shadow-offset: 0px 1px;
shadow-opacity: 0.1;
shadow-radius: 3px;
elevation: 2;

/* Alignment */
justify-content: center;
align-items: center;
flex-direction: row;
`;
```

**Button.stories.tsx (Storybook)**
```typescript
import { Button } from './Button';

export default {
title: 'Atoms/Button',
component: Button,
argTypes: {
variant: {
options: ['primary', 'secondary', 'ghost'],
control: { type: 'radio' }
},
size: {
options: ['sm', 'md', 'lg'],
control: { type: 'radio' }
}
}
};

export const Primary = () => (
<Button variant=\"primary\" size=\"md\" onPress={() => console.log('Pressed')}>
Start Workout
</Button>
);

export const Secondary = () => (
<Button variant=\"secondary\" size=\"md\" onPress={() => {}}>
Cancel
</Button>
);

export const Disabled = () => (
<Button variant=\"primary\" size=\"md\" disabled onPress={() => {}}>
Loading...
</Button>
);

export const AllSizes = () => (
<>
<Button variant=\"primary\" size=\"sm\" onPress={() => {}}>Small</Button>
<Button variant=\"primary\" size=\"md\" onPress={() => {}}>Medium</Button>
<Button variant=\"primary\" size=\"lg\" onPress={() => {}}>Large</Button>
</>
);
```

### Component API Design

**Prop Design Principles:**
1. **Semantic names:** `variant=\"primary\"` not `color=\"blue\"`
2. **Predictable defaults:** Most common use case is default
3. **Composition over configuration:** Allow children, icons, etc.
4. **Type safety:** Use TypeScript enums/unions

**Composition Patterns:**
```typescript
// ✅ Good: Composable
<Button>
<Icon name=\"plus\" />
Add Workout
</Button>

// ❌ Bad: Too many props
<Button
iconName=\"plus\"
iconPosition=\"left\"
iconSize=\"16\"
text=\"Add Workout\"
/>
```

### Storybook Documentation

Run Storybook:
```bash
npm run storybook
```

Organization:
```
- Atoms
- Button
- Primary
- Secondary
- Disabled
- All Sizes
- Input
- Badge
- Molecules
- InputGroup
- Card
- Organisms
- Header
- WorkoutCard
```

---

**Token System Version:** 1.0
**Framework:** Style Dictionary
**Last Updated:** Nov 2025
**Maintained by:** Design Systems Team