detect-design

Detect real design system in code with drift findings and evidence blocks.

Context Files

• $JAAN_LEARN_DIR/jaan-to-detect-design.learn.md - Past lessons (loaded in Pre-Execution)
• $JAAN_CONTEXT_DIR/tech.md - Tech stack (if exists, for framework-aware scanning)
• $JAAN_TEMPLATES_DIR/jaan-to-detect-design.template.md - Output template
• ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md - Language resolution protocol

Output path: $JAAN_OUTPUTS_DIR/detect/design/ — flat files, overwritten each run (no IDs).

Input

Arguments: $ARGUMENTS — parsed in Step 0.0. Repository path and mode determined there.

Pre-Execution Protocol

MANDATORY — Read and execute ALL steps in: ${CLAUDE_PLUGIN_ROOT}/docs/extending/pre-execution-protocol.md Skill name: detect-design Execute: Step 0 (Init Guard) → A (Load Lessons) → B (Resolve Template) → C (Offer Template Seeding)

Language Settings

Read and apply language protocol: ${CLAUDE_PLUGIN_ROOT}/docs/extending/language-protocol.md Override field for this skill: language_detect-design

Standards Reference

Reference: See ${CLAUDE_PLUGIN_ROOT}/docs/extending/detect-shared-reference.md for Evidence Format (SARIF), Evidence ID Generation, Confidence Levels, Frontmatter Schema, Platform Detection, Document Structure, and Codebase Content Safety.

This skill's namespace: E-DSN-* (e.g., E-DSN-001, E-DSN-WEB-001) Tool name in frontmatter: detect-design

Drift Detection — Paired Evidence

"Drift" findings REQUIRE two evidence items showing the conflict:

evidence:
  - id: E-DSN-001a
    type: token-definition
    confidence: 0.95
    location:
      uri: "src/tokens/colors.json"
      startLine: 15
    snippet: |
      "primary": "#3B82F6"
  - id: E-DSN-001b
    type: conflicting-usage
    confidence: 0.90
    location:
      uri: "src/components/Button.tsx"
      startLine: 42
    snippet: |
      color: "#2563EB"  // hardcoded, differs from token

PHASE 1: Detection (Read-Only)

Step 0.0: Parse Arguments

Arguments: $ARGUMENTS

Mode determination:

• If $ARGUMENTS contains --full as a standalone token → set run_depth = "full"
• Otherwise → set run_depth = "light"

Strip --full token from arguments. Set repo_path to remaining arguments (or current working directory if empty).

Thinking Mode

If run_depth == "full": ultrathink If run_depth == "light": megathink

Use extended reasoning for:

• Identifying design token hierarchies and naming conventions
• Detecting drift between definitions and usage
• Mapping component library patterns
• Accessibility scope assessment

Step 0: Detect Platforms

Purpose: Auto-detect platform structure and check for UI presence before analysis.

Use Glob and Bash to identify platform folders:

Platform Patterns

Match top-level directories against these patterns:

Detection Process

1. Check for monorepo markers:

   • Glob: pnpm-workspace.yaml, lerna.json, nx.json, turbo.json
   • If found, proceed to multi-platform detection
   • If not found, check folder structure anyway (could be non-standard monorepo)

2. List top-level directories:

   • Run: ls -d */ | grep -Ev "node_modules|\.git|dist|build|\.next|__pycache__|coverage"
   • Extract directory names (strip trailing slashes)

3. Match against platform patterns:

   • For each directory, check if name matches any platform pattern (case-insensitive)
   • Apply disambiguation rules (same as detect-dev)

4. Handle detection results:

   • No platforms detected → Single-platform mode:
     • Set platforms = [{ name: 'all', path: '.' }]
     • Path = repository root
   • Platforms detected → Multi-platform mode:
     • Build list: platforms = [{ name: 'web', path: 'web/' }, { name: 'backend', path: 'backend/' }, ...]
     • Ask user: "Detected platforms: {list}. Analyze all or select specific? [all/select]"
     • If 'select', prompt: "Enter platform names (comma-separated): "

UI Presence Check (Design System Applicability)

For each platform, check for UI indicators:

# Check for UI component files
ui_files=$(find {platform.path} -type f \( -name "*.jsx" -o -name "*.tsx" -o -name "*.vue" -o -name "*.svelte" \) 2>/dev/null | head -n 1)

if [ -z "$ui_files" ]; then
  # No UI files detected - design system analysis not applicable
  # Will create minimal output files with "Not Applicable" findings
  platform_has_ui = false
else
  platform_has_ui = true
fi

Platform applicability:

Analysis Loop

For each platform in platforms:

1. Set current_platform = platform.name
2. Set base_path = platform.path
3. Check UI presence using the check above
4. If platform_has_ui == false and platform is backend/cli:
   • Skip Steps 1-7 (detection steps)
   • Go directly to Step 8 with "Not Applicable" findings
5. If platform_has_ui == true or platform is expected to have UI:
   • Run detection steps per run_depth:
     • If run_depth == "full": Run Steps 1-7 scoped to base_path
     • If run_depth == "light": Run Steps 1-2 only scoped to base_path (skip Steps 3-7)
6. Use platform-specific output paths in Step 9

"Not Applicable" Findings Structure:

When a platform has no UI files and design analysis is not applicable, create minimal output files with this finding:

---
findings_summary:
  critical: 0
  high: 0
  medium: 0
  low: 0
  informational: 1
overall_score: 10.0  # Perfect score (nothing to assess)
---

## Executive Summary

No UI components detected for platform '{platform}'. Design system analysis is not applicable to this platform.

## Findings

### E-DSN-{PLATFORM}-001: No UI Components Detected

**Severity**: Informational
**Confidence**: Confirmed (1.0)

**Description**: Platform '{platform}' does not contain UI component files (.jsx, .tsx, .vue, .svelte). Design system detection, token analysis, and component inventory are not applicable to this platform type.

**Evidence**:
```yaml
evidence:
  id: E-DSN-{PLATFORM}-001
  type: absence
  confidence: 1.0
  method: glob-pattern-match
  description: "No UI files found in {platform.path}"

**Note**: If single-platform mode (`platform.name == 'all'`), output paths have NO suffix. If multi-platform mode, output paths include `-{platform}` suffix.

## Step 1: Scan Design Tokens

### Token Definition Files
- Glob: `**/tokens/**/*.{json,js,ts}` — design token packages
- Glob: `**/*.tokens.json` — token files by convention
- Glob: `tailwind.config.*` — Tailwind theme tokens
- Glob: `**/theme.{js,ts,json}`, `**/theme/**` — theme definitions

### CSS Variables
- Grep in `**/*.{css,scss,less}` for `--` prefixed custom properties
- Extract variable names, values, and categorize (color, spacing, typography, etc.)
- Detect naming conventions (BEM, kebab-case, camelCase)

### Token Categories
Map discovered tokens to categories:
- **Colors**: brand, semantic (success/warning/error/info), neutral/gray scales
- **Typography**: font families, sizes, weights, line heights
- **Spacing**: margins, paddings, gaps (detect scale: 4px/8px base)
- **Shadows**: elevation levels
- **Border radius**: shape tokens
- **Breakpoints**: responsive breakpoints
- **Animation**: timing, easing, duration tokens

## Step 2: Scan Component Library

### Component Files
- Glob: `**/components/**/*.{tsx,jsx,vue,svelte}` — component source
- Glob: `**/*.stories.{tsx,jsx,ts,js,mdx}` — Storybook stories
- Glob: `.storybook/**` — Storybook configuration

### Storybook & Component Tooling Signals
- Grep in `.storybook/main.*` for `addon-mcp` — MCP addon integration
- Grep in `.storybook/main.*` for `experimentalComponentsManifest` — component manifest generation
- Detect CSF version: grep for `satisfies Meta` or `satisfies StoryObj` (CSF3) vs `export default { title:` without `satisfies` (CSF2) in `**/*.stories.{tsx,jsx,ts,js}`
- Grep in `**/src/**/*.{tsx,jsx,ts,js}` for `cva(` — Class Variance Authority usage
- Glob: `components.json` — shadcn/ui presence; if found, extract `style`, `tailwind`, `aliases` fields

### Component Inventory
For each component directory, extract:
- Component name and file path
- Props interface (TypeScript types or PropTypes)
- Variant patterns (size, color, state)
- Composition patterns (compound components, slots)

### Component Categories
Classify components:
- **Primitives**: Button, Input, Text, Icon, Image
- **Layout**: Container, Grid, Stack, Flex, Spacer
- **Navigation**: Nav, Menu, Breadcrumb, Tabs, Pagination
- **Feedback**: Alert, Toast, Modal, Dialog, Progress
- **Data display**: Table, Card, List, Badge, Avatar
- **Form**: Select, Checkbox, Radio, Switch, DatePicker

**If `run_depth == "light"`:** Skip Steps 3-7. Proceed directly to Step 8 (Present Detection Summary).

**Precedence**: N/A handling (platform_has_ui checks) always takes priority over run_depth gates. If `platform_has_ui == false`, skip ALL detection steps regardless of run_depth.

## Step 3: Scan Brand Assets

- Glob: `**/assets/brand/**` — brand directory
- Glob: `**/assets/logo*`, `**/assets/icons/**` — logo and icon assets
- Glob: `**/fonts/**`, `**/*.woff2`, `**/*.ttf` — font files
- Detect font loading strategy (preload, font-display)
- Check for favicon and app icons

## Step 4: Scan UI Patterns

- Grep for layout patterns: grid systems, responsive utilities
- Detect spacing scale usage consistency
- Scan for color usage patterns outside token definitions
- Check for hardcoded values vs token references (drift signals)
- Detect dark mode / theme switching patterns (`prefers-color-scheme`, theme context)

## Step 5: Scan Accessibility Signals

**Scope**: Repo-level only. Cannot make claims about runtime behavior.

- Grep for ARIA attributes: `aria-label`, `aria-describedby`, `aria-live`, `role=`
- Check for semantic HTML usage: `<main>`, `<nav>`, `<article>`, `<section>`, `<header>`, `<footer>`
- Glob: `**/*.test.{ts,tsx,js,jsx}` and grep for a11y test patterns: `axe`, `jest-axe`, `@testing-library`, `getByRole`
- Check for skip links, focus management patterns
- Detect `alt` attribute usage on images

**Important**: Mark findings as "Unknown" when repo evidence is insufficient for runtime behavior claims.

## Step 6: Scan Governance Signals

- Glob: `CODEOWNERS` — check for design system file ownership
- Look for design system changelogs or versioning
- Detect Storybook configuration and deployment
- Check for visual regression testing (chromatic, percy, backstop)
- Look for design system documentation conventions
- Check for token versioning or release process

### MCP Readiness Assessment

Check `.mcp.json` (project root) for MCP server entries:

| Entry | Grep Pattern | What It Means |
|-------|-------------|---------------|
| storybook-mcp | `storybook-mcp` or `@anthropic/storybook-mcp` | Storybook components exposed via MCP |
| shadcn | `shadcn` or `@anthropic/shadcn-mcp` | shadcn/ui registry available via MCP |
| playwright | `playwright` or `@anthropic/playwright-mcp` | Browser automation available via MCP |

**Scoring**:
- **Ready** (all 3 configured): Full MCP integration for design system tooling
- **Partial** (1-2 configured): Some MCP servers present, gaps noted
- **Not Configured** (0 or no `.mcp.json`): No MCP integration detected

Cross-reference with Step 2 signals:
- If `addon-mcp` found in Storybook config but no `storybook-mcp` in `.mcp.json` → flag as misconfiguration
- If `components.json` (shadcn) found but no `shadcn` MCP entry → flag as opportunity
- Record MCP readiness score and individual server statuses for governance output

## Step 7: Detect Drift

For every token/variable definition found in Step 1, scan component files for:
- Hardcoded values that should reference tokens
- Inconsistent token usage (same semantic meaning, different tokens)
- Orphaned tokens (defined but never used)
- Undocumented overrides

Each drift finding MUST have paired evidence (definition + conflicting usage).

---

# HARD STOP — Detection Summary & User Approval

## Step 8: Present Detection Summary

**If `run_depth == "light"`:**

DESIGN SYSTEM DETECTION COMPLETE (Light Mode)

PLATFORM: {platform_name or 'all'} UI PRESENCE: {Yes/No} {if No, show "(Not Applicable)"}

TOKEN INVENTORY Colors: {n} tokens found [Confidence: {level}] Typography: {n} tokens found [Confidence: {level}] Spacing: {n} tokens found [Confidence: {level}] Other: {n} tokens found [Confidence: {level}]

COMPONENTS: {n} components detected across {n} categories

SEVERITY SUMMARY Critical: {n} | High: {n} | Medium: {n} | Low: {n} | Info: {n}

OVERALL SCORE: {score}/10

OUTPUT FILE (1): $JAAN_OUTPUTS_DIR/detect/design/summary{-platform}.md

Note: Run with --full for brand assets, UI patterns, accessibility audit, governance signals, and full drift analysis (6 output files).

> "Proceed with writing summary to $JAAN_OUTPUTS_DIR/detect/design/? [y/n]"

**If `run_depth == "full"`:**

DESIGN SYSTEM DETECTION COMPLETE

PLATFORM: {platform_name or 'all'} UI PRESENCE: {Yes/No} {if No, show "(Not Applicable)"}

TOKEN INVENTORY Colors: {n} tokens found [Confidence: {level}] Typography: {n} tokens found [Confidence: {level}] Spacing: {n} tokens found [Confidence: {level}] Other: {n} tokens found [Confidence: {level}]

COMPONENTS: {n} components detected across {n} categories DRIFT FINDINGS: {n} drift issues found ACCESSIBILITY: {n} a11y findings

SEVERITY SUMMARY Critical: {n} | High: {n} | Medium: {n} | Low: {n} | Info: {n}

OVERALL SCORE: {score}/10

OUTPUT FILES (6): $JAAN_OUTPUTS_DIR/detect/design/brand{-platform}.md - Brand signals $JAAN_OUTPUTS_DIR/detect/design/tokens{-platform}.md - Design token inventory $JAAN_OUTPUTS_DIR/detect/design/components{-platform}.md - Component inventory $JAAN_OUTPUTS_DIR/detect/design/patterns{-platform}.md - UI patterns and conventions $JAAN_OUTPUTS_DIR/detect/design/accessibility{-platform}.md - A11y findings $JAAN_OUTPUTS_DIR/detect/design/governance{-platform}.md - Governance signals

Note: {-platform} suffix only if multi-platform mode (e.g., -web, -mobile). Single-platform mode has no suffix. If UI presence = No, files contain "Not Applicable" findings.

> "Proceed with writing 6 output files to $JAAN_OUTPUTS_DIR/detect/design/? [y/n]"

**Do NOT proceed to Phase 2 without explicit approval.**

---

# PHASE 2: Write Output Files

## Step 9: Write to $JAAN_OUTPUTS_DIR/detect/design/

Create directory `$JAAN_OUTPUTS_DIR/detect/design/` if it does not exist.

> **Reference**: See `${CLAUDE_PLUGIN_ROOT}/docs/extending/detect-shared-reference.md` sections "Output Path Logic" and "Stale File Cleanup" for platform-specific suffix convention and run_depth cleanup rules.

### If `run_depth == "light"`: Write Single Summary File

Write one file: `$JAAN_OUTPUTS_DIR/detect/design/summary{suffix}.md`

Contents:
1. Universal YAML frontmatter with `platform` field, `findings_summary`, and `overall_score`
2. **Executive Summary** — BLUF of design system findings
3. **Token Inventory** — categories, count, naming convention, confidence levels (from Step 1)
4. **Component Inventory** — name, category, variant count (from Step 2)
5. **Token Coverage Gaps** — categories defined vs categories missing
6. **Top Findings** — up to 5 highest-severity findings with evidence blocks
7. "Run with `--full` for brand assets, UI patterns, accessibility audit, governance signals, and full drift analysis."

### If `run_depth == "full"`: Write 6 Output Files

Write 6 output files using the template:

| File | Content |
|------|---------|
| `$JAAN_OUTPUTS_DIR/detect/design/brand{suffix}.md` | Brand signals (colors, typography, logos) |
| `$JAAN_OUTPUTS_DIR/detect/design/tokens{suffix}.md` | Design token definitions and usage with drift findings |
| `$JAAN_OUTPUTS_DIR/detect/design/components{suffix}.md` | Component inventory and patterns |
| `$JAAN_OUTPUTS_DIR/detect/design/patterns{suffix}.md` | UI patterns and conventions |
| `$JAAN_OUTPUTS_DIR/detect/design/accessibility{suffix}.md` | A11y implementation findings (scoped to repo evidence) |
| `$JAAN_OUTPUTS_DIR/detect/design/governance{suffix}.md` | Design system governance signals (includes MCP Readiness section) |

**Note**: `{suffix}` is empty for single-platform mode, or `-{platform}` for multi-platform mode.

**If UI presence = No** (from Step 0 check), write minimal "Not Applicable" files with:
- Frontmatter: `findings_summary.informational: 1`, `overall_score: 10.0`
- Single finding: "E-DSN-{PLATFORM}-001: No UI Components Detected" (severity: informational)

Each file MUST include:
1. Universal YAML frontmatter with `platform` field and findings_summary/overall_score
2. Executive Summary
3. Scope and Methodology
4. Findings with evidence blocks (using E-DSN-{PLATFORM}-NNN or E-DSN-NNN IDs)
5. Recommendations

---

## Step 9a: Seed Reconciliation

> **Reference**: See `${CLAUDE_PLUGIN_ROOT}/docs/extending/seed-reconciliation-reference.md` for comparison rules, discrepancy format, and auto-update protocol.

1. Read domain-relevant seed files: `$JAAN_CONTEXT_DIR/tone-of-voice.template.md`
2. Compare detection results against seed content (brand colors, typography, voice characteristics if design tokens reference them)
3. If discrepancies found:
   - Display discrepancy table to user
   - Offer auto-updates for non-destructive changes: `[y/n]`
   - Suggest `/jaan-to:learn-add` commands for patterns worth documenting
4. If no discrepancies: display "Seed files are aligned with detection results."

---

## Step 10: Capture Feedback

> "Any feedback on the design system detection? [y/n]"

If yes:
- Run `/jaan-to:learn-add detect-design "{feedback}"`

---

## Skill Alignment

- Two-phase workflow with HARD STOP for human approval
- Evidence-based findings with confidence scoring
- Fork-isolated execution (`context: fork`)
- Output to standardized `$JAAN_OUTPUTS_DIR` path

## Definition of Done

**If `run_depth == "light"`:**

- [ ] Single summary file written to `$JAAN_OUTPUTS_DIR/detect/design/summary{suffix}.md`
- [ ] Universal YAML frontmatter with `overall_score`
- [ ] Token and component findings have evidence blocks with E-DSN-NNN IDs
- [ ] Confidence scores assigned to all findings
- [ ] Detection summary shown to user before writing
- [ ] User approved output

**If `run_depth == "full"`:**

- [ ] All 6 output files written to `$JAAN_OUTPUTS_DIR/detect/design/`
- [ ] Universal YAML frontmatter with `platform` field in every file
- [ ] Every finding has evidence block with correct ID format (E-DSN-NNN for single-platform, E-DSN-{PLATFORM}-NNN for multi-platform)
- [ ] Drift findings have paired evidence (definition + conflicting usage)
- [ ] Accessibility findings scoped to repo evidence (no runtime claims)
- [ ] Confidence scores assigned to all findings
- [ ] Overall score calculated
- [ ] Output filenames match platform suffix convention (no suffix for single-platform, -{platform} suffix for multi-platform)
- [ ] If no UI files detected for platform, minimal "Not Applicable" files created with informational findings
- [ ] User approved output
- [ ] Seed reconciliation check performed (discrepancies reported or alignment confirmed)