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

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)

1. List top-level directories:

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

1. Match against platform patterns:

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

1. 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

1. 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)

1. 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**:

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:

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:

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

1. 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)