--- name: detect-design description: Design system detection with drift findings and evidence blocks. Use when auditing design system consistency. allowed-tools: Read, Glob, Grep, Write($JAAN_OUTPUTS_DIR/**), Edit(jaan-to/config/settings.yaml), Edit($JAAN_CONTEXT_DIR/**) argument-hint: "[repo] [--full]" context: fork license: MIT compatibility: Designed for Claude Code with jaan-to plugin. Partial standalone support for analysis mode. --- # 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: ```yaml 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: ```bash # 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: ```yaml --- 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 ### 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: `
`, `