Extract Design System

---
name: extract-design-system
description: "Use when building, styling, optimizing, and auditing extract design system components, responsive layouts, design systems, and frontend state."
version: 6.0.0
last-updated: 2026-09-29
skills:
  - create-design-md
  - tailwind-patterns
  - baseline-ui
tools: Read, Grep, Glob, Bash, Edit, Write
scripts-binding:
  - .agent/scripts/lint_runner.js
  - .agent/scripts/verify_all.js
---

# Extract Design System — Tokenization Mastery

## Mandatory Pre-Flight Context Inspection
Before reading, generating, or refactoring code in the `extract-design-system` domain, inspect these 5 critical parameters:
1. **System Boundaries & Dependencies**: Verify that all required dependencies exist in target package manifests and environment paths.
2. **Runtime Context & Platform Invariants**: Confirm target platform constraints (Node.js, Browser, Mobile OS, Edge runtime) before applying APIs.
3. **Execution Guardrails**: Identify potential side-effects, state mutations, and unhandled asynchronous exceptions.
4. **Validation & Type Contracts**: Validate input data schemas and strict type constraints across all module interfaces.
5. **Observability & Proof of Execution**: Ensure execution produces tangible verification signals (terminal output, tests, metrics).


## Activation Boundaries
- **Activate when:** Use when building, styling, optimizing, and auditing extract design system components, responsive layouts, design systems, and frontend state.
- **DO NOT activate when:** The task falls outside the `extract-design-system` domain or is managed by a different dedicated specialist agent.


## 🔁 Multi-Pass Execution Protocol

| Pass | Phase | Core Action | Adaptive Depth |
|:---|:---|:---|:---|
| **Pass 1** | **Understand** | Deconstruct the user's explicit objective, implicit requirements, and platform constraints. | Fast / Standard / Deep |
| **Pass 2** | **Plan** | Decompose task into smallest logical steps; map dependencies, affected files, and tool calls. | Standard / Deep |
| **Pass 3** | **Execute** | Implement solution with production-grade craft, zero placeholders, and strict typing. | All Modes |
| **Pass 4** | **Verify** | Run linters, unit tests, or compiler checks to validate structural correctness. | All Modes |
| **Pass 5** | **Attack & Falsify** | Perform adversarial search for edge-case failures, counterexamples, race conditions, and traps. | Standard / Deep |
| **Pass 6** | **Harden** | Eliminate discovered friction, optimize performance, and harden error boundaries. | Standard / Deep |
| **Pass 7** | **Quality Gate** | Enforce Verification-Before-Completion (VBC) with concrete terminal proof before finalizing. | All Modes |


---

## 🛠️ Technical Architecture & Reference Recipes

## Hallucination Traps (Read First)

- ❌ Creating CSS variables for every possible value -> ✅ Only tokenize values that appear 3+ times across components
- ❌ Extracting a design system before the UI is stable -> ✅ Wait until patterns are proven by real usage before standardizing
- ❌ Naming tokens by appearance (`--blue-500`) instead of purpose (`--color-primary`) -> ✅ Semantic names survive theme changes

---
## 1. The Token Extraction Protocol

When reviewing a messy, legacy UI file (`<div style="background: #e23e2a; border-radius: 6px; padding: 12px">`), the agent must extract these hardcoded values into Global Tokens.

### Tier 1: Core Design Tokens (The Foundation)

Tokens should be semantic, not literal. `color-brand` > `color-red`.

```css
:root {
  /* Colors (HSL is preferred for programmatic manipulation) */
  --brand-primary: 360, 76%, 53%; /* The specific red */
  --surface-default: 0, 0%, 100%;
  --surface-muted: 210, 40%, 96%;

  /* Typography */
  --font-sans: 'Inter', system-ui, sans-serif;

  /* Space / Geometry (8px grid scale) */
  --space-1: 0.25rem; /* 4px */
  --space-2: 0.5rem; /* 8px */
  --space-3: 0.75rem; /* 12px */
  --space-4: 1rem; /* 16px */

  /* Radaii */
  --radius-sm: 4px;
  --radius-md: 6px; /* Extracted from the 6px legacy element */
}
```

### Tier 2: The Refactor

(Using Tailwind v4 CSS-First as the standard delivery mechanism)

```css
@theme {
  --color-primary: hsl(var(--brand-primary));
  --spacing-3: var(--space-3);
  --radius-md: var(--radius-md);
}
```

---

## 2. Standardizing the 3 "C" Configurations

If building a design system inside React/Next.js, standardize the system through 3 primary mechanisms.

1. **Colors (Dark Mode First):** Every single color extracted must have an inverse defined for `[data-theme='dark']`.
2. **Container Queries:** Media queries (`@media (min-width)`) define the _device_. Container queries (`@container (min-width)`) define the _component context_. Always extract component sizing to rely on container-driven layouts for ultimate reusability.
3. **Compound Variants (CVA):** Group extracted CSS classes into logical component states rather than passing 10 boolean props.

```typescript
// ✅ Efficient Extracted Component Architecture
import { cva } from 'class-variance-authority';

const buttonStyles = cva(
  'inline-flex items-center justify-center rounded-md font-medium transition-colors', // Base
  {
    variants: {
      intent: {
        primary: 'bg-primary text-white hover:bg-primary/90',
        destructive: 'bg-red-500 text-white hover:bg-red-600',
        outline: 'border border-input hover:bg-accent',
      },
      size: {
        sm: 'h-9 px-3 text-sm',
        default: 'h-10 px-4 py-2', // Extracted standard size
        lg: 'h-11 px-8',
      },
    },
    defaultVariants: {
      intent: 'primary',
      size: 'default',
    },
  },
);
```

---

## 3. Auditing the Accessibility Baseline

A Design System must mandate accessibility at the token level, preventing developers from manually breaking contrast ratios later.

1. Extracted primary text colors must hit a **4.5:1 contrast ratio** against the extracted background surfaces.
2. Focus rings must be decoupled and standardized globally (`ring-2 ring-primary ring-offset-2`).

## 🚨 Edge-Case & Failure Mode Matrix

| Scenario | Risk | Production Mitigation |
|:---|:---|:---|
| **Empty or Null Inputs** | Unhandled exception or unexpected rendering collapse | Enforce fallback guards, optional chaining, and explicit empty state handlers |
| **Network Timeout / Latency** | Hanging operations or duplicate side-effects | Implement bounded abort controllers, exponential backoff, and idempotency keys |
| **Concurrency / Race Conditions** | Stale state overwrite or inconsistent data mutations | Use atomic transactions, mutex locking, or cancel-on-resubmit controls |
| **Invalid Schema / Malformed Payload** | Downstream runtime errors or security injection | Validate boundary payloads with Zod/Pydantic schemas prior to execution |
| **Resource / Memory Saturation** | OOM errors, frame drops, or memory leaks | Clean up listeners, cancel active timers, and enforce pagination/virtualization |


## 🏛️ Tribunal Verification & Guardrails

**Active Reviewers:** `frontend-reviewer` · `type-safety` · `ui-ux-auditor` · `complexity-reviewer`
**Slash Command:** `/review` or `/tribunal-full`

### 🔬 Evidence Standard (Tri-State Verification)
Every finding, audit statement, or completion claim must classify its factual certainty:
- **`[OBSERVED]`**: Directly confirmed in the codebase or verified via executed terminal command.
- **`[INFERRED]`**: Logically deduced from code patterns, architectural data flow, or schema relations.
- **`[UNVERIFIED]`**: Speculative hypothesis or runtime possibility requiring active testing or measurement.

### ✅ Pre-Flight Self-Audit Checklist
```
✅ Are all component props strictly typed with zero implicit "any"?
✅ Are responsive breakpoints, fluid typography, and optical balance verified?
✅ Is accessibility (ARIA labels, keyboard navigation, contrast ratio >= 4.5:1) validated?
✅ Are re-renders minimized and state lifecycles cleanly separated?
✅ Did I verify all imported UI components and icon sets actually exist?
```

### 🛑 Verification-Before-Completion (VBC) Protocol
**CRITICAL:** You must follow a strict "evidence-based closeout" state machine.
- ❌ **Forbidden:** Declaring a task complete because the output "looks correct."
- ✅ **Required:** You are explicitly forbidden from finalizing any task without providing **concrete evidence** (terminal output, passing test suites, compiler success, or equivalent operational proof) that your output works as intended.