design-system-patterns

Design System Patterns

Master design system architecture to create consistent, maintainable, and scalable UI foundations across the Fastlane application.

When to Use This Skill

• Creating and managing Pangea design tokens
• Implementing light/dark theme switching with Pangea tokens
• Building reusable Angular Material component abstractions
• Architecting component libraries aligned with Pangea
• Establishing design-to-code workflows with Figma tokens
• Creating semantic token hierarchies (primitive, semantic, component)
• Setting up design system documentation and governance

Core Capabilities

1. Design Tokens

• Primitive tokens (raw values: colors, sizes, fonts)
• Semantic tokens (contextual meaning: text-primary, surface-elevated)
• Component tokens (specific usage: button-bg, card-border)
• Token naming conventions and organization
• Pangea token contract (CSS custom properties on :root)

2. Theming Infrastructure (Angular)

• CSS custom properties architecture (Pangea standard)
• Angular ThemeService for theme switching
• Dynamic theme switching with Pangea dark mode
• System preference detection (prefers-color-scheme)
• Persistent theme storage
• Reduced motion and high contrast modes

3. Component Architecture

• Angular Material component wrapping and composition
• Slot-based composition with content projection
• Pangea token discipline in component styling
• Variant and size systems
• Component API design with signals

4. Token Pipeline

• Figma to code synchronization
• Token transformation and formatting
• CI/CD integration for token updates

Quick Start

Pangea Token Usage in SCSS

// Angular component file — use Pangea tokens from _root
.my-component {
  color: var(--on-surface);
  background: var(--surface);
  padding: var(--spacing-sm); // 16px

  &__title {
    color: var(--on-surface);
    font-weight: 600;
  }

  &__secondary-text {
    color: var(--pangea-text-secondary);
  }

  :host-context(body.dark-theme) & {
    background: var(--surface-alt);
  }
}

Angular ThemeService Pattern

import { Injectable, signal } from '@angular/core';

@Injectable({ providedIn: 'root' })
export class ThemeService {
  private readonly darkMode = signal<boolean>(false);
  readonly isDark = this.darkMode.asReadonly();

  constructor() {
    this.initializeTheme();
  }

  private initializeTheme(): void {
    const isDark = localStorage.getItem('theme') === 'dark' ||
      (window.matchMedia('(prefers-color-scheme: dark)').matches &&
        !localStorage.getItem('theme'));
    
    if (isDark) {
      this.applyDarkTheme();
    }
  }

  toggleDark(): void {
    const isDark = !this.darkMode();
    this.darkMode.set(isDark);
    
    if (isDark) {
      this.applyDarkTheme();
    } else {
      this.applyLightTheme();
    }
    
    localStorage.setItem('theme', isDark ? 'dark' : 'light');
  }

  private applyDarkTheme(): void {
    document.body.classList.add('dark-theme');
    this.darkMode.set(true);
  }

  private applyLightTheme(): void {
    document.body.classList.remove('dark-theme');
    this.darkMode.set(false);
  }
}

Key Patterns

Pattern 1: Token Hierarchy

/* Layer 1: Primitive tokens (raw values) */
:root {
  /* Pangea color palette — defined once */
  --color-primary: #2563eb;
  --color-primary-dark: #1e40af;
  --color-success: #16a34a;
  --color-error: #dc2626;
  --color-warning: #f59e0b;
  
  /* Neutral grays */
  --color-gray-50: #f9fafb;
  --color-gray-100: #f3f4f6;
  --color-gray-900: #111827;

  /* Spacing scale (8px base) */
  --spacing-xs: 0.5rem;    /* 8px */
  --spacing-sm: 1rem;      /* 16px */
  --spacing-md: 1.5rem;    /* 24px */
  --spacing-lg: 2rem;      /* 32px */
  --spacing-xl: 2.5rem;    /* 40px */

  /* Font sizes */
  --font-size-sm: 0.875rem;
  --font-size-base: 1rem;
  --font-size-lg: 1.125rem;

  --radius-sm: 0.25rem;
  --radius-md: 0.5rem;
  --radius-lg: 1rem;
}

/* Layer 2: Semantic tokens (light mode) */
:root {
  --surface: white;
  --surface-alt: #f9fafb;
  --on-surface: #111827;
  --pangea-text-secondary: #6b7280;
  --border-default: #e5e7eb;
  --interactive-primary: var(--color-primary);
  --interactive-primary-hover: var(--color-primary-dark);
}

/* Layer 3: Dark mode overrides */
body.dark-theme {
  --surface: #111827;
  --surface-alt: #1f2937;
  --on-surface: #f9fafb;
  --pangea-text-secondary: #9ca3af;
  --border-default: #374151;
  --interactive-primary: var(--color-primary);
}

/* Layer 4: Component tokens (specific usage) */
:root {
  --button-primary-bg: var(--interactive-primary);
  --button-primary-text: white;
  --button-primary-radius: var(--radius-md);
  --button-padding-x: var(--spacing-sm);
  --button-padding-y: 0.5rem;
}

Pattern 2: Angular Material Button Variants (Pangea)

<!-- Primary action — preferred action -->
<button mat-raised-button color="primary">Submit</button>

<!-- Success action (secondary emphasis) -->
<button mat-raised-button color="accent">Confirm</button>

<!-- Destructive action (danger) -->
<button mat-raised-button color="warn">Delete</button>

<!-- Secondary action (outlined) -->
<button mat-stroked-button>Cancel</button>

<!-- Tertiary action (text-only) -->
<button mat-icon-button aria-label="More actions">
  <mat-icon>more_vert</mat-icon>
</button>

Pattern 3: Wrapping Angular Material Primitives

import {
  Component,
  Input,
  input,
  ChangeDetectionStrategy,
} from '@angular/core';
import { CommonModule } from '@angular/common';
import { MatButtonModule } from '@angular/material/button';

@Component({
  selector: 'app-action-button',
  standalone: true,
  imports: [CommonModule, MatButtonModule],
  template: `
    <button
      mat-raised-button
      [color]="color()"
      [disabled]="disabled()"
      (click)="handleClick()"
      class="action-button"
    >
      <ng-content />
    </button>
  `,
  styleUrl: './action-button.component.scss',
  changeDetection: ChangeDetectionStrategy.OnPush,
})
export class ActionButtonComponent {
  readonly color = input<'primary' | 'accent' | 'warn'>('primary');
  readonly disabled = input<boolean>(false);

  handleClick(): void {
    // Component logic
  }
}

SCSS:

.action-button {
  min-width: 120px;
  
  :host-context(body.dark-theme) & {
    // Material handles dark mode automatically
    // but you can override specific tokens if needed
  }
}

Best Practices

1. Use Pangea Tokens Only: All colors, spacing, and sizing should reference Pangea tokens, never hardcoded hex values
2. Maintain Token Hierarchy: Primitives > Semantic > Component tokens
3. Document Token Usage: Include usage guidelines with token definitions
4. Version Tokens: Treat token changes as API changes
5. Test Theme Combinations: Verify light and dark modes work with all components
6. Automate Token Pipeline: CI/CD for Figma-to-code synchronization
7. Provide Migration Paths: Deprecate tokens gradually with clear alternatives
8. Scope Styling with :host: Always scope SCSS to :host for encapsulation

Pangea Token Contract

Fastlane uses Pangea's token system:

• Light mode: Tokens defined on :root (default)
• Dark mode: Tokens overridden on body.dark-theme
• No external build step: Tokens are CSS custom properties, ready to use in SCSS
• Location: apps/web/src/styles.scss contains token definitions
• Theme toggle: Use the ThemeService to switch modes

Common Issues

• Token Sprawl: Too many tokens without clear hierarchy
• Inconsistent Naming: Mixed conventions (camelCase vs kebab-case)
• Missing Dark Mode: Tokens that don't adapt to theme changes
• Hardcoded Values: Using raw values instead of tokens
• Circular References: Tokens referencing each other in loops

Cross-References

• pangea-design-system skill — complete Pangea token catalog and Material slot remapping
• design-system-patterns — Angular Material integration patterns
• visual-design-foundations — token vocabulary and semantic naming