detect-design

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

Argument	Effect
(none)	Light mode (default): Token + component scan, single summary file
[repo]	Scan specified repo (applies to both modes)
--full	Full mode: All detection steps, 6 output files (current behavior)

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:

Platform	Folder Patterns
web	web/, webapp/, frontend/, client/
mobile	mobile/, app/
backend	backend/, server/, api/, services/
androidtv	androidtv/, tv/, android-tv/
ios	ios/, iOS/
android	android/, Android/
desktop	desktop/, electron/
cli	cli/, cmd/

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:

Platform Type	UI Expected	If No UI Found
web, mobile, androidtv, ios, android, desktop	Yes	Report as finding (unexpected)
backend, cli, services	Conditional	Report "Not Applicable" (expected)

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)