authoring-design-system

What this skill does

# Design System Assembly

## Overview

Synthesize individual screenshot extractions produced by `humaninloop:analysis-screenshot` into a unified, coherent design system. Every token in the final system traces back to its source screenshot, every conflict is documented with resolution rationale, and the output is implementation-ready.

## When to Use

- Multiple screenshot extractions exist and need merging into one system
- Token consolidation required across color, typography, spacing, and elevation
- Component variants from different sources need harmonizing
- Building a unified design system from visual inspiration across apps
- Preparing implementation-ready token definitions from merged extractions

## When NOT to Use

- Only one screenshot extraction exists (no merging needed -- use the extraction directly)
- Designing from scratch without reference screenshots (use `humaninloop:patterns-interface-design`)
- Extractions have not been completed yet (run `humaninloop:analysis-screenshot` first)
- Implementing an already-defined design system (no synthesis needed)

## Prerequisites

**REQUIRED:** Run `humaninloop:analysis-screenshot` on each reference screenshot before invoking this skill. Each extraction provides the raw material for assembly.

Gather all extraction documents. Each extraction should contain: color palette, typography scale, spacing scale, component catalog, layout structure, and border/elevation system.

## Phase 1: Extraction Inventory

Before merging anything, catalog what exists.

### Process

1. List every extraction by source name (e.g., "Linear dashboard," "Stripe checkout," "Notion sidebar")
2. For each extraction, note what token categories are present and what is marked as a gap
3. Identify overlap -- which categories appear in multiple extractions
4. Identify unique contributions -- tokens or components present in only one source

### Output Format

```
EXTRACTION INVENTORY

Source 1: [Name]
  Platform: [platform]
  Color tokens: [count] | Typography levels: [count] | Spacing values: [count]
  Components: [list]
  Gaps: [list]

Source 2: [Name]
  ...

OVERLAP MATRIX:
  Colors:      Sources [1, 2, 3] — merge required
  Typography:  Sources [1, 3] — merge required
  Spacing:     Sources [1, 2] — merge required
  Components:  Sources [1, 2, 3] — normalization required
  Elevation:   Source [2] only — adopt directly

UNIQUE CONTRIBUTIONS:
  Source 1: [specific tokens or components only this source provides]
  Source 2: [specific tokens or components only this source provides]
```

## Phase 2: Token Consolidation

Merge color palettes, typography scales, and spacing scales from all sources into unified scales.

### Color Consolidation

1. **Collect all neutrals** -- List every background, surface, border, and text color from every source. Group by role (background-base, background-elevated, text-primary, etc.).
2. **Identify near-duplicates** -- Colors within delta-E 3.0 of each other serving the same role are candidates for merging. Choose the value that best serves the intended palette temperature.
3. **Resolve conflicts** -- When two sources assign different colors to the same role (e.g., different background-base values), document both and select one. Record the rationale.
4. **Build unified palette** -- Assign every color a single canonical name. Attribute each to its source.

```
UNIFIED COLOR PALETTE

NEUTRALS:
  bg-base:       #1A1A2E  (from: Source 1 — Notion dark mode)
  bg-elevated:   #222240  (from: Source 2 — Linear cards)
  bg-surface:    #2A2A4A  (derived: midpoint between Source 1 and Source 2)
  ...

CONFLICTS RESOLVED:
  bg-base: Source 1 used #1A1A2E, Source 2 used #1C1C1C
  Decision: Adopted Source 1 value — warmer tone aligns with brand direction
```

### Typography Consolidation

1. **Align scales** -- Map each source's type levels to a common naming convention (display, h1, h2, h3, body, caption, label, overline).
2. **Resolve size conflicts** -- When sources disagree on a level's size, favor the value from the source whose overall scale has better mathematical consistency (e.g., major third ratio).
3. **Unify font families** -- Select one primary, one monospace. Document alternatives considered.
4. **Unify weights** -- Build a single weight scale covering all needed weights across sources.

### Spacing Consolidation

1. **Identify base units** -- Note each source's base unit (4px, 8px, etc.).
2. **Standardize** -- Choose one base unit. If sources disagree, prefer the value that produces the most consistent scale.
3. **Merge scales** -- Combine all spacing values into a single scale. Eliminate redundant values within 1px of each other.
4. **Validate coverage** -- Ensure the unified scale covers micro (2-4px), component (8-16px), section (24-48px), and layout (64px+) ranges.

## Phase 3: Component Normalization

Harmonize component variants from different sources into a consistent library.

### Process

1. **Build a component union** -- List every component type that appears in any extraction.
2. **Merge variants** -- For components that appear in multiple sources, merge variant lists. Remove duplicates.
3. **Retoken components** -- Replace each component's original color, spacing, and typography references with the unified tokens from Phase 2.
4. **Resolve style conflicts** -- When sources use different border-radii, padding, or styling for the same component type, document the options and choose one.
5. **Assign component tokens** -- Each component references only unified system tokens. No hard-coded values.

### Output Format

```
COMPONENT: Button
  Sources: [Source 1, Source 3]
  Variants: primary, secondary, ghost, icon-only
  Resolved tokens:
    Height: var(--space-xl) (40px)
    Padding: var(--space-xs) var(--space-md)
    Border radius: var(--radius-md)
    Font: var(--font-size-label) / var(--font-weight-medium)
    Colors:
      Primary BG: var(--color-brand-primary)
      Primary text: var(--color-text-inverse)
      Secondary BG: var(--color-bg-elevated)
  Conflict notes:
    Source 1 used 8px radius, Source 3 used 12px.
    Decision: 8px — matches the overall compact density.
```

## Phase 4: Hierarchy Establishment

Define primary/secondary/tertiary relationships across the entire system.

### Color Hierarchy

| Level | Purpose | Example Assignment |
|-------|---------|-------------------|
| Primary | Main actions, brand expression | Brand color for buttons, links |
| Secondary | Supporting actions, alternative paths | Muted brand for secondary buttons |
| Tertiary | Background accents, hover states | Tinted surfaces |
| Neutral | Content, structure, text | Gray scale for text and borders |
| Semantic | Status communication | Success, warning, error, info |

### Typography Hierarchy

| Level | Role | Tokens |
|-------|------|--------|
| Display | Hero content, landing sections | Largest size, heaviest weight |
| Heading | Section titles, page headers | h1 through h3 |
| Body | Primary content, descriptions | Standard reading size |
| UI | Labels, buttons, inputs | Slightly smaller, medium weight |
| Caption | Metadata, timestamps, help text | Smallest, muted color |

### Spacing Hierarchy

| Context | Scale Range | Application |
|---------|-------------|-------------|
| Component internals | 2xs through sm | Icon gaps, input padding, tight pairs |
| Between elements | sm through lg | Form fields, button groups, list items |
| Section separation | lg through 2xl | Content sections, card groups |
| Layout structure | 2xl through 3xl | Page margins, major divisions |

## Phase 5: Conflict Resolution

All conflicts identified during Phases 2-4 MUST be documented in a single conflict log.

### Conflict Log Format

```
CONFLICT LOG

ID: C-001
Category: Color
Description: Background base color differs between sources
  Source 1: #1A1A2E (warm dark blue)
  Source 2: #1C1C1C (neutral dark gray)
Resolution: Adopted #1A1A2E
Rationale: Warm undertone creates more inviting feel; neutral gray reser