@skilly-hand/skilly-hand 0.6.1 → 0.8.0

package/catalog/skills/accessibility-audit/scripts/audit-a11y.sh

@@ -0,0 +1,372 @@
+#!/usr/bin/env bash
+# Portable accessibility audit helper aligned to WCAG 2.2 Level AA (W3C)
+# Sources:
+# - https://www.w3.org/WAI/standards-guidelines/wcag/
+# - https://www.w3.org/TR/WCAG22/
+# - https://www.w3.org/WAI/WCAG22/quickref/
+
+set -euo pipefail
+
+RED='\033[0;31m'
+YELLOW='\033[0;33m'
+CYAN='\033[0;36m'
+GREEN='\033[0;32m'
+BOLD='\033[1m'
+DIM='\033[2m'
+RESET='\033[0m'
+
+REPORT_MODE=false
+JSON_MODE=false
+TARGET=""
+ROOT="$(pwd)"
+REPORT_FILE="$ROOT/a11y-audit-report.md"
+REPORT_CONTENT=""
+JSON_ENTRIES=""
+
+FILES_SCANNED=0
+FILES_WITH_ISSUES=0
+TOTAL_ISSUES=0
+ISSUES_CRITICAL=0
+ISSUES_SERIOUS=0
+ISSUES_MODERATE=0
+
+usage() {
+  cat <<USAGE
+Usage:
+  bash catalog/skills/accessibility-audit/scripts/audit-a11y.sh [options] [path]
+
+Options:
+  --report     Write markdown report to ./a11y-audit-report.md
+  --json       Emit JSON findings to stdout
+  --help       Show this help
+
+Default path:
+  current directory
+USAGE
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --report) REPORT_MODE=true; shift ;;
+    --json) JSON_MODE=true; shift ;;
+    --help|-h) usage; exit 0 ;;
+    *) TARGET="$1"; shift ;;
+  esac
+done
+
+TARGET="${TARGET:-.}"
+
+if [[ ! -e "$TARGET" ]]; then
+  echo "Target does not exist: $TARGET" >&2
+  exit 1
+fi
+
+json_escape() {
+  echo "$1" | sed 's/\\/\\\\/g; s/"/\\"/g; s/\t/\\t/g; s/\r/\\r/g; s/\n/\\n/g'
+}
+
+record_finding() {
+  local file="$1"
+  local relative_path="$2"
+  local category="$3"
+  local severity="$4"
+  local wcag_sc="$5"
+  local lineno="$6"
+  local raw_line="$7"
+  local message="$8"
+
+  local color_code=""
+  local label=""
+
+  case "$severity" in
+    critical) color_code="$RED"; label="CRITICAL"; ISSUES_CRITICAL=$((ISSUES_CRITICAL + 1)) ;;
+    serious) color_code="$YELLOW"; label="SERIOUS"; ISSUES_SERIOUS=$((ISSUES_SERIOUS + 1)) ;;
+    moderate) color_code="$CYAN"; label="MODERATE"; ISSUES_MODERATE=$((ISSUES_MODERATE + 1)) ;;
+  esac
+
+  if ! $JSON_MODE; then
+    printf "  ${color_code}%-14s${RESET} [${DIM}%s${RESET}] line %-4s %s\n" "$category" "$wcag_sc" "$lineno:" "$message"
+    echo -e "             ${DIM}->${RESET} $raw_line"
+  fi
+
+  if $REPORT_MODE; then
+    REPORT_CONTENT+="| \`${relative_path}\` | ${lineno} | ${label} | \`${category}\` | ${wcag_sc} | ${message} |"$'\n'
+  fi
+
+  if $JSON_MODE; then
+    [[ -n "$JSON_ENTRIES" ]] && JSON_ENTRIES+=","
+    JSON_ENTRIES+="{\"file\":\"$(json_escape "$relative_path")\",\"line\":${lineno},\"severity\":\"${severity}\",\"category\":\"$(json_escape "$category")\",\"wcag\":\"$(json_escape "$wcag_sc")\",\"message\":\"$(json_escape "$message")\",\"code\":\"$(json_escape "$raw_line")\"}"
+  fi
+}
+
+audit_markup_file() {
+  local file="$1"
+  local relative_path="${file#$ROOT/}"
+  local file_issues=0
+
+  FILES_SCANNED=$((FILES_SCANNED + 1))
+
+  while IFS=: read -r lineno line; do
+    [[ "$line" =~ ^[[:space:]]*\<\!-- ]] && continue
+    local trimmed
+    trimmed="$(echo "$line" | sed 's/^[[:space:]]*//')"
+    record_finding "$file" "$relative_path" "MISSING-ALT" "critical" "1.1.1" "$lineno" "$trimmed" "Image is missing alt attribute"
+    file_issues=$((file_issues + 1))
+  done < <(grep -n -E '<img[[:space:]]' "$file" 2>/dev/null | grep -v -E 'alt=' || true)
+
+  while IFS=: read -r lineno line; do
+    [[ "$line" =~ ^[[:space:]]*\<\!-- ]] && continue
+    echo "$line" | grep -qE 'aria-label|aria-labelledby|title=' && continue
+    local trimmed
+    trimmed="$(echo "$line" | sed 's/^[[:space:]]*//')"
+    if echo "$trimmed" | grep -qE '<button[^>]*>[[:space:]]*</button>' || echo "$trimmed" | grep -qE '<button[^>]*/>'; then
+      record_finding "$file" "$relative_path" "EMPTY-BUTTON" "critical" "4.1.2" "$lineno" "$trimmed" "Button has no text or accessible name"
+      file_issues=$((file_issues + 1))
+    fi
+  done < <(grep -n -E '<button' "$file" 2>/dev/null || true)
+
+  while IFS=: read -r lineno line; do
+    [[ "$line" =~ ^[[:space:]]*\<\!-- ]] && continue
+    echo "$line" | grep -qE 'aria-label|aria-labelledby|title=' && continue
+    local trimmed
+    trimmed="$(echo "$line" | sed 's/^[[:space:]]*//')"
+    if echo "$trimmed" | grep -qE '<a[^>]*>[[:space:]]*</a>'; then
+      record_finding "$file" "$relative_path" "EMPTY-LINK" "critical" "2.4.4" "$lineno" "$trimmed" "Link has no text or accessible name"
+      file_issues=$((file_issues + 1))
+    fi
+  done < <(grep -n -E '<a[[:space:]]' "$file" 2>/dev/null || true)
+
+  while IFS=: read -r lineno line; do
+    [[ "$line" =~ ^[[:space:]]*\<\!-- ]] && continue
+    echo "$line" | grep -qE 'aria-label|aria-labelledby' && continue
+    echo "$line" | grep -qE 'type="hidden"|type="submit"|type="button"' && continue
+
+    local has_label=false
+    if echo "$line" | grep -qE 'id="[^"]+"'; then
+      local input_id
+      input_id="$(echo "$line" | sed -n 's/.*id="\([^"]*\)".*/\1/p' | head -1)"
+      if [[ -n "$input_id" ]] && grep -qE "for=\"${input_id}\"" "$file" 2>/dev/null; then
+        has_label=true
+      fi
+    fi
+
+    if [[ "$has_label" == "false" ]]; then
+      local trimmed
+      trimmed="$(echo "$line" | sed 's/^[[:space:]]*//')"
+      record_finding "$file" "$relative_path" "MISSING-LABEL" "serious" "1.3.1/3.3.2" "$lineno" "$trimmed" "Form control missing label association or ARIA naming"
+      file_issues=$((file_issues + 1))
+    fi
+  done < <(grep -n -E '<(input|select|textarea)[[:space:]]' "$file" 2>/dev/null || true)
+
+  while IFS=: read -r lineno line; do
+    [[ "$line" =~ ^[[:space:]]*\<\!-- ]] && continue
+    echo "$line" | grep -qE 'role=|tabindex=' && continue
+    local trimmed
+    trimmed="$(echo "$line" | sed 's/^[[:space:]]*//')"
+    record_finding "$file" "$relative_path" "CLICK-NO-ROLE" "serious" "2.1.1" "$lineno" "$trimmed" "Non-semantic clickable element needs keyboard and role semantics"
+    file_issues=$((file_issues + 1))
+  done < <(grep -n -E '<(div|span|li)[^>]*((onclick=)|(\(click\)))' "$file" 2>/dev/null || true)
+
+  while IFS=: read -r lineno line; do
+    [[ "$line" =~ ^[[:space:]]*\<\!-- ]] && continue
+    local tab_val
+    tab_val="$(echo "$line" | grep -oE 'tabindex="[0-9]+"' | grep -oE '[0-9]+' | head -1)"
+    if [[ -n "$tab_val" ]] && [[ "$tab_val" -gt 0 ]]; then
+      local trimmed
+      trimmed="$(echo "$line" | sed 's/^[[:space:]]*//')"
+      record_finding "$file" "$relative_path" "TABINDEX-POS" "serious" "2.4.3" "$lineno" "$trimmed" "Positive tabindex can break logical focus order"
+      file_issues=$((file_issues + 1))
+    fi
+  done < <(grep -n -E 'tabindex="[1-9]' "$file" 2>/dev/null || true)
+
+  local prev_level=0
+  while IFS=: read -r lineno line; do
+    [[ "$line" =~ ^[[:space:]]*\<\!-- ]] && continue
+    local level
+    level="$(echo "$line" | grep -oE '<h[1-6]' | grep -oE '[1-6]' | head -1)"
+    [[ -z "$level" ]] && continue
+
+    if [[ "$prev_level" -gt 0 ]] && [[ "$level" -gt $((prev_level + 1)) ]]; then
+      local trimmed
+      trimmed="$(echo "$line" | sed 's/^[[:space:]]*//')"
+      record_finding "$file" "$relative_path" "HEADING-SKIP" "moderate" "1.3.1" "$lineno" "$trimmed" "Heading level skipped"
+      file_issues=$((file_issues + 1))
+    fi
+
+    prev_level="$level"
+  done < <(grep -n -E '<h[1-6]' "$file" 2>/dev/null || true)
+
+  if grep -qE '<html[[:space:]]' "$file" 2>/dev/null; then
+    if ! grep -qE '<html[^>]*lang=' "$file" 2>/dev/null; then
+      local lineno
+      lineno="$(grep -n -E '<html' "$file" | head -1 | cut -d: -f1)"
+      local trimmed
+      trimmed="$(grep -E '<html' "$file" | head -1 | sed 's/^[[:space:]]*//')"
+      record_finding "$file" "$relative_path" "MISSING-LANG" "serious" "3.1.1" "$lineno" "$trimmed" "Missing language declaration on html element"
+      file_issues=$((file_issues + 1))
+    fi
+  fi
+
+  if [[ "$file_issues" -gt 0 ]]; then
+    FILES_WITH_ISSUES=$((FILES_WITH_ISSUES + 1))
+    TOTAL_ISSUES=$((TOTAL_ISSUES + file_issues))
+    if ! $JSON_MODE; then
+      echo -e "\n${BOLD}${relative_path}${RESET} - ${RED}${file_issues} issue(s)${RESET}"
+    fi
+  fi
+}
+
+audit_style_file() {
+  local file="$1"
+  local relative_path="${file#$ROOT/}"
+  local file_issues=0
+
+  FILES_SCANNED=$((FILES_SCANNED + 1))
+
+  while IFS=: read -r lineno line; do
+    [[ "$line" =~ ^[[:space:]]*/\* ]] && continue
+
+    local context_start=$((lineno > 4 ? lineno - 4 : 1))
+    local context_end=$((lineno + 8))
+    if sed -n "${context_start},${context_end}p" "$file" 2>/dev/null | grep -qE 'focus-visible'; then
+      continue
+    fi
+
+    local trimmed
+    trimmed="$(echo "$line" | sed 's/^[[:space:]]*//')"
+    record_finding "$file" "$relative_path" "FOCUS-REMOVED" "critical" "2.4.7" "$lineno" "$trimmed" "Focus outline removed without visible focus-visible replacement"
+    file_issues=$((file_issues + 1))
+  done < <(
+    grep -n -E ':focus[[:space:]]*\{' "$file" 2>/dev/null | while IFS=: read -r ln _; do
+      local end=$((ln + 5))
+      if sed -n "${ln},${end}p" "$file" 2>/dev/null | grep -qE 'outline:[[:space:]]*(none|0)'; then
+        echo "${ln}:focus"
+      fi
+    done || true
+  )
+
+  if [[ "$file_issues" -gt 0 ]]; then
+    FILES_WITH_ISSUES=$((FILES_WITH_ISSUES + 1))
+    TOTAL_ISSUES=$((TOTAL_ISSUES + file_issues))
+    if ! $JSON_MODE; then
+      echo -e "\n${BOLD}${relative_path}${RESET} - ${RED}${file_issues} issue(s)${RESET}"
+    fi
+  fi
+}
+
+generate_report() {
+  local generated_at
+  generated_at="$(date '+%Y-%m-%d %H:%M:%S')"
+
+  cat > "$REPORT_FILE" <<REPORT_HEAD
+# Accessibility Audit Report (WCAG 2.2 Level AA)
+
+Generated: ${generated_at}
+Target: \`${TARGET}\`
+
+## Summary
+
+| Metric | Count |
+| --- | --- |
+| Files scanned | ${FILES_SCANNED} |
+| Files with issues | ${FILES_WITH_ISSUES} |
+| Critical | ${ISSUES_CRITICAL} |
+| Serious | ${ISSUES_SERIOUS} |
+| Moderate | ${ISSUES_MODERATE} |
+| Total issues | ${TOTAL_ISSUES} |
+
+## Findings
+
+| File | Line | Severity | Category | WCAG SC | Description |
+| --- | --- | --- | --- | --- | --- |
+REPORT_HEAD
+
+  echo "$REPORT_CONTENT" >> "$REPORT_FILE"
+
+  cat >> "$REPORT_FILE" <<REPORT_TAIL
+
+## Source References (W3C)
+
+- https://www.w3.org/WAI/standards-guidelines/wcag/
+- https://www.w3.org/TR/WCAG22/
+- https://www.w3.org/WAI/WCAG22/quickref/
+- https://www.w3.org/WAI/WCAG22/Understanding/
+- https://www.w3.org/developers/tools/
+REPORT_TAIL
+}
+
+if ! $JSON_MODE; then
+  echo -e "${BOLD}WCAG 2.2 Level AA accessibility audit${RESET}"
+  echo -e "Target: ${CYAN}${TARGET}${RESET}"
+fi
+
+MARKUP_FILES=()
+STYLE_FILES=()
+
+if [[ -f "$TARGET" ]]; then
+  case "$TARGET" in
+    *.html|*.htm|*.xhtml|*.jsx|*.tsx) MARKUP_FILES+=("$TARGET") ;;
+    *.css|*.scss|*.sass|*.less) STYLE_FILES+=("$TARGET") ;;
+  esac
+else
+  while IFS= read -r f; do MARKUP_FILES+=("$f"); done < <(
+    find "$TARGET" -type f \( -name "*.html" -o -name "*.htm" -o -name "*.xhtml" -o -name "*.jsx" -o -name "*.tsx" \) \
+      -not -path "*/node_modules/*" \
+      -not -path "*/.git/*" \
+      -not -path "*/dist/*" \
+      -not -path "*/build/*" \
+      -not -path "*/coverage/*" \
+      -not -path "*/.next/*" \
+      -not -path "*/storybook-static/*" \
+      | sort
+  )
+
+  while IFS= read -r f; do STYLE_FILES+=("$f"); done < <(
+    find "$TARGET" -type f \( -name "*.css" -o -name "*.scss" -o -name "*.sass" -o -name "*.less" \) \
+      -not -path "*/node_modules/*" \
+      -not -path "*/.git/*" \
+      -not -path "*/dist/*" \
+      -not -path "*/build/*" \
+      -not -path "*/coverage/*" \
+      -not -path "*/.next/*" \
+      -not -path "*/storybook-static/*" \
+      | sort
+  )
+fi
+
+for file in "${MARKUP_FILES[@]:-}"; do
+  [[ -n "$file" ]] && audit_markup_file "$file"
+done
+
+for file in "${STYLE_FILES[@]:-}"; do
+  [[ -n "$file" ]] && audit_style_file "$file"
+done
+
+if $REPORT_MODE; then
+  generate_report
+fi
+
+if $JSON_MODE; then
+  cat <<JSON
+{"standard":"WCAG 2.2 Level AA","target":"$(json_escape "$TARGET")","summary":{"filesScanned":${FILES_SCANNED},"filesWithIssues":${FILES_WITH_ISSUES},"critical":${ISSUES_CRITICAL},"serious":${ISSUES_SERIOUS},"moderate":${ISSUES_MODERATE},"total":${TOTAL_ISSUES}},"findings":[${JSON_ENTRIES}]}
+JSON
+else
+  echo ""
+  echo -e "${BOLD}Summary${RESET}"
+  echo "Files scanned:      $FILES_SCANNED"
+  echo "Files with issues:  $FILES_WITH_ISSUES"
+  echo "Critical:           $ISSUES_CRITICAL"
+  echo "Serious:            $ISSUES_SERIOUS"
+  echo "Moderate:           $ISSUES_MODERATE"
+  echo "Total:              $TOTAL_ISSUES"
+  if $REPORT_MODE; then
+    echo "Report:             $REPORT_FILE"
+  fi
+  if [[ "$TOTAL_ISSUES" -eq 0 ]]; then
+    echo -e "${GREEN}No issues found by this heuristic scanner.${RESET}"
+  fi
+fi
+
+if [[ "$TOTAL_ISSUES" -gt 0 ]]; then
+  exit 1
+fi

package/catalog/skills/frontend-design/SKILL.md

@@ -0,0 +1,237 @@
+---
+name: frontend-design
+description: >
+  Project-aware frontend design skill that detects the existing tech stack, UI libraries,
+  CSS variables, and design tokens before proposing any UI work. Never invents design
+  decisions — reads the project first, confirms with the user, then designs.
+  Trigger: user asks to build, design, style, or update any UI component, page, or visual element in a frontend project.
+metadata:
+  author: skilly-hand
+  last-edit: 2026-04-04
+  license: Apache-2.0
+  version: "1.0.0"
+  changelog: "initial release; prevents AI slop design by enforcing project-aware stack detection before any design work; affects all frontend design and styling tasks"
+  auto-invoke: "design a component, create a UI, style this page, build a frontend, update the layout"
+allowed-tools: Read, Grep, Glob, Bash, Edit, Write
+allowed-modes:
+  - stack-detector      # Scan the project for tech stack, UI libs, CSS vars, and design tokens
+  - component-designer  # Design and implement components following the confirmed project stack
+---
+
+# Frontend Design Guide
+
+## When to Use
+
+Use this skill when:
+
+- You are designing, building, or restyling a UI component, page, or layout in an existing project.
+- You are adding new visual elements that must match the project's existing design language.
+- You are refactoring styling or structure of frontend code to align with established patterns.
+- You need to choose between UI components, tokens, or styles already available in the project.
+
+Do not use this skill for:
+
+- Greenfield design system creation with no existing codebase to read from.
+- Backend, API, or data-layer tasks with no UI surface.
+- Design tool work (Figma, Sketch) unrelated to code implementation.
+- Projects where the user has explicitly opted out of stack detection.
+
+---
+
+## Routing Map
+
+Always run stack detection first. Never skip to design.
+
+| Step | Intent | Sub-agent |
+| --- | --- | --- |
+| 0 (always first) | Detect framework, UI library, CSS approach, tokens, and existing patterns | [agents/stack-detector.md](agents/stack-detector.md) |
+| 1 (only after confirmation) | Design and implement components using confirmed stack | [agents/component-designer.md](agents/component-designer.md) |
+
+---
+
+## Standard Execution Sequence
+
+1. **Run stack detection** — always start with `stack-detector`, no exceptions.
+2. **Present findings to the user** — surface the detected stack clearly and ask for explicit confirmation.
+3. **If anything is unclear or ambiguous, ask** — do not proceed with partial or uncertain information.
+4. **Scan existing tokens and components** — read what already exists before proposing anything.
+5. **Design with confirmed context only** — hand off to `component-designer` only after step 2 is complete.
+
+---
+
+## Critical Patterns
+
+### Pattern 1: Tech Stack Detection is Non-Negotiable
+
+Before writing a single line of UI code or proposing any design, run [agents/stack-detector.md](agents/stack-detector.md).
+
+This means:
+- Reading `package.json` to identify the framework and installed libraries.
+- Detecting CSS approach (Tailwind, CSS Modules, styled-components, Sass, vanilla).
+- Finding existing design tokens (CSS custom properties, theme files, `tokens.json`).
+- Sampling real components from the project to understand naming, structure, and styling conventions.
+
+If `package.json` is missing or the project root is unclear, stop and ask the user where to look.
+
+Never assume a library is present based on file extensions alone — verify it in dependencies.
+
+### Pattern 2: Never Invent Tokens — Read First
+
+Before using any color, spacing, font size, border radius, shadow, or z-index value:
+
+1. Search for CSS custom properties: `grep -r "var(--" src/`
+2. Check for a theme file: `tailwind.config.ts`, `theme.ts`, `tokens.json`, `_variables.scss`
+3. Check for a design system config: `@mui/material`, `chakra-ui/theme`, `shadcn/ui` config
+
+If the token does not exist in the project, do not invent it. Ask the user: "This project doesn't define a token for X. Should I add one, or is there an existing value I missed?"
+
+### Pattern 3: Confirm Before Every Design Decision
+
+At every fork — layout choice, component variant, color, interaction pattern — if the right answer is not derivable from the existing code, ask the user.
+
+Examples of things that require confirmation:
+- Which existing component to base a new one on.
+- Whether to use Tailwind utility classes or a CSS module.
+- Whether to match a specific existing page's spacing rhythm or start fresh.
+- Which breakpoints the project already targets.
+
+Short, specific questions are better than long ambiguous ones. One question at a time if possible.
+
+### Pattern 4: Follow the Project's Visual Language
+
+After stack detection, read 3–5 existing components before proposing any design. Identify:
+- The naming convention (PascalCase components, BEM CSS, camelCase tokens, etc.)
+- The composition pattern (atomic components, compound components, render props, slots)
+- The styling approach (co-located styles, global theme, utility-first classes)
+
+Every new component or style must feel like it was written by the same team that wrote the existing code — not imported from a different design system.
+
+---
+
+## What Not To Do
+
+These are the most critical rules. Violating any of them produces AI slop.
+
+- **Never assume a UI library is present** without verifying it in `package.json`. Shadcn and Radix look similar in JSX — check the deps.
+- **Never pick colors, fonts, or spacing values not already in the project**. If the project has no purple, do not introduce purple.
+- **Never use Inter as a default font** unless it is explicitly declared in the project. Inter is a sign of uncontextualized AI output.
+- **Never generate a component without reading at least one existing component first**. The project's conventions must be the template.
+- **Never apply a generic layout** (hero + cards + CTA, standard nav + footer) without verifying the project already uses or wants that structure.
+- **Never chain design decisions silently**. If one decision implies a downstream choice (e.g. using a grid library implies a layout system), surface it.
+- **Never proceed after ambiguity**. If the detected stack is inconsistent (e.g., Tailwind and styled-components both present), stop and ask which one is canonical.
+- **Never treat a partial stack detection as complete**. If `package.json` was readable but no component files were found, say so and ask for the component directory.
+- **Never ship a "placeholder" or "you can customize this later" design**. Every value must be intentional and project-derived.
+- **Never skip the confirmation step** even if the stack looks obvious. One confirmation prevents ten corrections.
+
+---
+
+## Decision Tree
+
+```text
+User asks for UI work
+  -> Has stack-detector been run and confirmed by user?
+       NO  -> Run stack-detector, present findings, ask for confirmation
+       YES -> Continue
+
+Is the requested component similar to an existing one in the project?
+  YES -> Read the existing component, use it as the structural and styling template
+  NO  -> Ask the user which existing component is closest, or if this is a net-new pattern
+
+Does the design require a token/value (color, spacing, font) not yet found in the project?
+  YES -> Ask the user: add a new token, use an existing one, or clarify?
+  NO  -> Use the existing token
+
+Is the CSS approach Tailwind?
+  YES -> Use only classes declared in tailwind.config; no arbitrary values unless project already uses them
+  NO  -> Continue
+
+Is the CSS approach CSS Modules or Sass?
+  YES -> Follow the naming convention of existing .module.css or .scss files exactly
+  NO  -> Continue
+
+Is the CSS approach styled-components or CSS-in-JS?
+  YES -> Match the theme structure; use theme.colors/spacing/typography from the existing theme provider
+  NO  -> Use whatever CSS approach was detected; if none detected, ask the user
+
+Ready to implement?
+  YES -> Hand off to component-designer with full confirmed context
+```
+
+---
+
+## Code Examples
+
+### Example 1: Detecting CSS custom properties in a project
+
+```bash
+# Find all CSS variables defined at :root
+grep -rn ":root" src/ --include="*.css" --include="*.scss"
+
+# Find all usages of CSS custom properties
+grep -rn "var(--" src/ --include="*.css" --include="*.scss" --include="*.tsx" --include="*.vue"
+```
+
+### Example 2: Identifying a Tailwind project and reading its token config
+
+```bash
+# Check if Tailwind is installed
+cat package.json | grep tailwind
+
+# Read the full color/spacing/font token config
+cat tailwind.config.ts
+```
+
+### Example 3: Sampling existing components to learn the pattern
+
+```bash
+# Find all component files in a React project
+find src/components -name "*.tsx" | head -5
+
+# Read one to understand structure and styling approach
+cat src/components/Button/Button.tsx
+```
+
+### Example 4: Detecting shadcn/ui vs MUI vs Chakra
+
+```bash
+# shadcn/ui (no package — installed as local files)
+ls src/components/ui/
+
+# MUI
+grep '"@mui/material"' package.json
+
+# Chakra UI
+grep '"@chakra-ui/react"' package.json
+
+# Radix Primitives (often underlies shadcn)
+grep '"@radix-ui' package.json
+```
+
+---
+
+## Commands
+
+```bash
+# Read project dependencies
+cat package.json | grep -A 50 '"dependencies"'
+
+# Detect CSS approach from file extensions
+find src -name "*.module.css" | head -3       # CSS Modules
+find src -name "*.module.scss" | head -3      # Sass Modules
+grep -rl "styled-components\|emotion" src/    # CSS-in-JS
+grep -rl "cn(\|clsx\|classnames" src/         # Tailwind class merging
+
+# Find design token files
+find . -name "tokens.json" -o -name "theme.ts" -o -name "_variables.scss" 2>/dev/null
+
+# List existing components
+find src/components -maxdepth 2 -name "*.tsx" -o -name "*.vue" | head -10
+```
+
+---
+
+## Resources
+
+- Stack detection procedure: [agents/stack-detector.md](agents/stack-detector.md)
+- Component design rules: [agents/component-designer.md](agents/component-designer.md)
+- Full scan checklist: [assets/stack-scan-checklist.md](assets/stack-scan-checklist.md)