@windyroad/style-guide 0.2.0

package/.claude-plugin/plugin.json

@@ -0,0 +1,5 @@
+{
+  "name": "wr-style-guide",
+  "version": "0.1.0",
+  "description": "Style guide enforcement for Claude Code"
+}

package/agents/agent.md

@@ -0,0 +1,83 @@
+---
+name: agent
+description: Style guide reviewer for CSS and visual design changes. Use before
+  editing any CSS, style tokens, or visual styling in component style blocks,
+  .css files, or inline styles. Reads docs/STYLE-GUIDE.md and reviews proposed
+  changes against the guide. Reports violations with suggested fixes.
+tools:
+  - Read
+  - Glob
+  - Grep
+model: inherit
+---
+
+You are the Style Guide Lead. You review proposed styling changes against the project's docs/STYLE-GUIDE.md before any visual styling is edited. You are a reviewer, not an editor.
+
+## Your Role
+
+1. Read `docs/STYLE-GUIDE.md` in the project to load the current guide
+2. Read the file(s) being edited to understand the existing styles and context
+3. Review proposed changes against every section of the guide
+4. Report: OK if compliant, or list specific violations with suggested fixes
+
+## What You Check
+
+All review criteria come from `docs/STYLE-GUIDE.md`. Read the guide first and apply its sections. Typical sections include:
+
+- **Color tokens / palette** — whether colours use defined tokens, not hardcoded values
+- **Typography** — font stacks, type scale, weight usage
+- **Spacing** — spacing scale, touch target sizes
+- **Component patterns** — button variants, form inputs, cards, tables
+- **Layout & responsive** — mobile-first approach, breakpoints, max-widths
+- **Motion & animation** — `prefers-reduced-motion` support, duration tokens
+- **Dark mode** — CSS custom property usage, contrast in both modes
+- **Border radius & shadows** — defined scales
+
+If the guide defines additional sections, check those too. Do not invent rules that are not in the guide.
+
+Additionally, always check WCAG AA contrast requirements regardless of whether the guide mentions them:
+- Text on background: 4.5:1 minimum
+- Large text (18px+ bold or 24px+): 3:1 minimum
+- UI components and borders: 3:1
+
+## How to Report
+
+If the styling is compliant:
+> **Style Guide Review: PASS**
+> No violations found. Styling aligns with the style guide.
+
+If there are violations, list each one:
+
+> **Style Guide Review: VIOLATIONS FOUND**
+>
+> 1. **[Section/Rule]** - File: `path`, Line ~N
+>    - **Issue**: What is wrong
+>    - **Current**: The offending CSS/style
+>    - **Fix**: Suggested replacement using the correct token
+>
+> 2. ...
+
+## Guide Gap Detection
+
+If the code introduces a UI component, visual pattern, or design token not covered by `docs/STYLE-GUIDE.md`, flag this as a guide gap:
+
+> **Style Guide Review: GUIDE UPDATE NEEDED**
+>
+> The code introduces [component/pattern/token] which is not covered by the current style guide.
+> Recommended addition to `docs/STYLE-GUIDE.md`: [specific section/content to add]
+
+This is a FAIL verdict — the guide must be updated before the code can proceed. Write `printf 'FAIL' > /tmp/style-guide-verdict` for guide gaps.
+
+## Verdict
+
+After completing your review, write your verdict to `/tmp/style-guide-verdict`:
+- `printf 'PASS' > /tmp/style-guide-verdict` — styling is compliant and guide covers the patterns used
+- `printf 'FAIL' > /tmp/style-guide-verdict` — violations found or guide gap detected
+
+## Constraints
+
+- You are read-only. You do not edit files (except writing the verdict file).
+- You review styling in `.css` files and `<style>` blocks in component files.
+- If the change has no visual/styling impact (logic, copy, structure only), report PASS.
+- Do not review copy or text content (that is the voice-and-tone-lead's job).
+- Do not review accessibility markup (that is the accessibility-lead's job).

package/bin/install.mjs

@@ -0,0 +1,42 @@
+#!/usr/bin/env node
+
+import { resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const utils = await import(resolve(__dirname, "../../shared/install-utils.mjs"));
+
+const PLUGIN = "wr-style-guide";
+const DEPS = [];
+
+const flags = utils.parseStandardArgs(process.argv);
+
+if (flags.help) {
+  console.log(`
+Usage: npx @windyroad/style-guide [options]
+
+Style guide enforcement for CSS and UI components
+
+Options:
+  --update     Update this plugin and its skills
+  --uninstall  Remove this plugin
+  --dry-run    Show what would be done without executing
+  --help, -h   Show this help
+`);
+  process.exit(0);
+}
+
+if (flags.dryRun) {
+  utils.setDryRun(true);
+  console.log("[dry-run mode — no commands will be executed]\n");
+}
+
+utils.checkPrerequisites();
+
+if (flags.uninstall) {
+  utils.uninstallPackage(PLUGIN);
+} else if (flags.update) {
+  utils.updatePackage(PLUGIN);
+} else {
+  utils.installPackage(PLUGIN, { deps: DEPS });
+}

package/hooks/hooks.json

@@ -0,0 +1,16 @@
+{
+  "hooks": {
+    "UserPromptSubmit": [
+      { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/style-guide-eval.sh" }] }
+    ],
+    "PreToolUse": [
+      { "matcher": "Edit|Write", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/style-guide-enforce-edit.sh" }] }
+    ],
+    "PostToolUse": [
+      { "matcher": "Agent", "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/style-guide-mark-reviewed.sh" }] }
+    ],
+    "Stop": [
+      { "hooks": [{ "type": "command", "command": "${CLAUDE_PLUGIN_ROOT}/hooks/style-guide-reset-marker.sh" }] }
+    ]
+  }
+}

package/hooks/lib/review-gate.sh

@@ -0,0 +1,102 @@
+#!/bin/bash
+# Shared gate logic for review enforcement hooks (a11y, voice-tone, style-guide).
+# Sourced by *-enforce-edit.sh hooks and review-plan-enforce.sh.
+# Provides: check_review_gate, review_gate_deny, review_gate_parse_error
+
+# Source shared portable helpers (_mtime, _hashcmd)
+_REVIEW_GATE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+source "$_REVIEW_GATE_DIR/gate-helpers.sh"
+
+# Check review gate marker. Returns 0 if marker is valid (allow), 1 if invalid (deny).
+# Sets REVIEW_GATE_REASON on failure.
+# Usage: check_review_gate "$SESSION_ID" "style-guide" "docs/STYLE-GUIDE.md"
+check_review_gate() {
+  local SESSION_ID="$1"
+  local SYSTEM="$2"        # e.g., "a11y", "voice-tone", "style-guide"
+  local POLICY_FILE="$3"   # e.g., "docs/STYLE-GUIDE.md"
+  local MARKER="/tmp/${SYSTEM}-reviewed-${SESSION_ID}"
+  local HASH_FILE="/tmp/${SYSTEM}-reviewed-${SESSION_ID}.hash"
+  local TTL_SECONDS="${REVIEW_TTL:-600}"
+
+  # 1. Marker must exist
+  if [ ! -f "$MARKER" ]; then
+    REVIEW_GATE_REASON="No ${SYSTEM} review marker found. The ${SYSTEM} agent must review first."
+    return 1
+  fi
+
+  # 2. TTL check — marker mtime must be within TTL
+  local NOW=$(date +%s)
+  local MARKER_TIME=$(_mtime "$MARKER")
+  local AGE=$(( NOW - MARKER_TIME ))
+  if [ "$AGE" -ge "$TTL_SECONDS" ]; then
+    rm -f "$MARKER" "$HASH_FILE"
+    REVIEW_GATE_REASON="${SYSTEM} review expired (${AGE}s old, TTL ${TTL_SECONDS}s). Re-run the ${SYSTEM} agent."
+    return 1
+  fi
+
+  # 3. Drift detection — policy file hash must match
+  if [ -f "$HASH_FILE" ] && [ -n "$POLICY_FILE" ]; then
+    local STORED_HASH=$(cat "$HASH_FILE")
+    local CURRENT_HASH=""
+    if [ -f "$POLICY_FILE" ]; then
+      CURRENT_HASH=$(cat "$POLICY_FILE" | _hashcmd | cut -d' ' -f1)
+    elif [ -d "$POLICY_FILE" ]; then
+      # Directory (e.g., docs/decisions/) — hash all .md files
+      CURRENT_HASH=$(find "$POLICY_FILE" -name '*.md' -not -name 'README.md' -print0 | sort -z | xargs -0 cat 2>/dev/null | _hashcmd | cut -d' ' -f1)
+    else
+      CURRENT_HASH="missing"
+    fi
+    if [ "$STORED_HASH" != "$CURRENT_HASH" ]; then
+      rm -f "$MARKER" "$HASH_FILE"
+      REVIEW_GATE_REASON="${SYSTEM} policy file changed since last review. Re-run the ${SYSTEM} agent."
+      return 1
+    fi
+  fi
+
+  # Slide TTL window forward
+  touch "$MARKER"
+  return 0
+}
+
+# Store policy file hash after a successful review.
+# Usage: store_review_hash "$SESSION_ID" "style-guide" "docs/STYLE-GUIDE.md"
+store_review_hash() {
+  local SESSION_ID="$1"
+  local SYSTEM="$2"
+  local POLICY_FILE="$3"
+  local HASH_FILE="/tmp/${SYSTEM}-reviewed-${SESSION_ID}.hash"
+
+  if [ -n "$POLICY_FILE" ]; then
+    local HASH=""
+    if [ -f "$POLICY_FILE" ]; then
+      HASH=$(cat "$POLICY_FILE" | _hashcmd | cut -d' ' -f1)
+    elif [ -d "$POLICY_FILE" ]; then
+      HASH=$(find "$POLICY_FILE" -name '*.md' -not -name 'README.md' -print0 | sort -z | xargs -0 cat 2>/dev/null | _hashcmd | cut -d' ' -f1)
+    else
+      HASH="missing"
+    fi
+    echo "$HASH" > "$HASH_FILE"
+  fi
+}
+
+# Emit fail-closed deny JSON for PreToolUse hooks.
+review_gate_deny() {
+  local REASON="$1"
+  cat <<EOF
+{
+  "hookSpecificOutput": {
+    "hookEventName": "PreToolUse",
+    "permissionDecision": "deny",
+    "permissionDecisionReason": "$REASON"
+  }
+}
+EOF
+}
+
+# Emit fail-closed deny JSON for parse failures.
+review_gate_parse_error() {
+  cat <<'EOF'
+{ "hookSpecificOutput": { "hookEventName": "PreToolUse", "permissionDecision": "deny",
+    "permissionDecisionReason": "BLOCKED: Could not parse hook input. Gate is fail-closed." } }
+EOF
+}

package/hooks/style-guide-enforce-edit.sh

@@ -0,0 +1,58 @@
+#!/bin/bash
+# Style Guide - PreToolUse enforcement hook
+# BLOCKS Edit/Write to UI source files until style-guide-lead is consulted.
+# Uses shared review-gate.sh for TTL, drift detection, and fail-closed.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/lib/review-gate.sh"
+
+INPUT=$(cat)
+
+FILE_PATH=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('tool_input', {}).get('file_path', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+
+SESSION_ID=$(echo "$INPUT" | python3 -c "
+import sys, json
+try:
+    data = json.load(sys.stdin)
+    print(data.get('session_id', ''))
+except:
+    print('')
+" 2>/dev/null || echo "")
+
+if [ -z "$SESSION_ID" ]; then
+  review_gate_parse_error
+  exit 0
+fi
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Gate all UI source files (CSS and component files)
+case "$FILE_PATH" in
+  *.css|*.html|*.jsx|*.tsx|*.vue|*.svelte|*.ejs|*.hbs) ;;
+  *) exit 0 ;;
+esac
+
+BASENAME=$(basename "$FILE_PATH")
+
+# If no policy file exists, block and direct to create skill
+if [ ! -f "docs/STYLE-GUIDE.md" ]; then
+  review_gate_deny "BLOCKED: Cannot edit '${BASENAME}' because docs/STYLE-GUIDE.md does not exist. Run /wr-style-guide:create to generate a style guide for this project, then delegate to wr-style-guide:agent for review."
+  exit 0
+fi
+
+# Check gate with TTL + drift detection
+if check_review_gate "$SESSION_ID" "style-guide" "docs/STYLE-GUIDE.md"; then
+  exit 0
+fi
+
+review_gate_deny "BLOCKED: Cannot edit '${BASENAME}' without style guide review. You MUST first delegate to wr-style-guide:agent using the Agent tool (subagent_type: 'wr-style-guide:agent'). ${REVIEW_GATE_REASON}"
+exit 0

package/hooks/style-guide-eval.sh

@@ -0,0 +1,34 @@
+#!/bin/bash
+# Style Guide - UserPromptSubmit hook
+# Detects STYLE-GUIDE.md in the project and injects delegation instruction.
+# If the file doesn't exist, instructs Claude to create it via the agent.
+
+if [ -f "docs/STYLE-GUIDE.md" ]; then
+  cat <<'HOOK_OUTPUT'
+INSTRUCTION: MANDATORY STYLE GUIDE CHECK. YOU MUST FOLLOW THIS.
+DETECTED: docs/STYLE-GUIDE.md exists in this project.
+
+This is a NON-OPTIONAL instruction. You MUST use the style-guide-lead agent
+before editing any .css or UI component file. This is proactive.
+Do not wait for the user to ask.
+
+REQUIRED ACTIONS:
+1. Use the Agent tool to delegate to wr-style-guide:agent
+   (subagent_type: "wr-style-guide:agent")
+2. The style-guide-lead will review proposed styling against docs/STYLE-GUIDE.md
+3. Do NOT write or edit styling without style-guide-lead review FIRST
+4. Do NOT skip this step even if you think you can handle it yourself
+
+SCOPE: All .css and UI component files (.html, .jsx, .tsx, .vue, .svelte, .ejs, .hbs).
+Does NOT apply to: .ts/.js backend files, .md files, config files.
+HOOK_OUTPUT
+else
+  # Check if this is a web project (has UI files)
+  if ls src/**/*.tsx src/**/*.jsx src/**/*.css src/**/*.html 2>/dev/null | head -1 | grep -q .; then
+    cat <<'HOOK_OUTPUT'
+NOTE: This project has UI files but no docs/STYLE-GUIDE.md.
+If the user's task involves editing CSS or UI components, the edit will be blocked
+until a style guide exists. Run /wr-style-guide:create to generate one.
+HOOK_OUTPUT
+  fi
+fi

package/hooks/style-guide-mark-reviewed.sh

@@ -0,0 +1,49 @@
+#!/bin/bash
+# Style Guide - PostToolUse hook for Agent tool
+# Creates a session marker when style-guide-lead has been consulted with PASS verdict.
+# This marker unlocks the style-guide-enforce-edit.sh PreToolUse block.
+
+SCRIPT_DIR="$(cd "$(dirname "$0")" && pwd)"
+source "$SCRIPT_DIR/lib/review-gate.sh"
+
+INPUT=$(cat)
+
+SUBAGENT=$(echo "$INPUT" | jq -r '.tool_input.subagent_type // empty') || true
+SESSION_ID=$(echo "$INPUT" | jq -r '.session_id // empty') || true
+
+if [ -z "$SESSION_ID" ]; then
+  exit 0
+fi
+
+case "$SUBAGENT" in
+  *style-guide-lead*|*wr-style-guide*)
+    VERDICT_FILE="/tmp/style-guide-verdict"
+    VERDICT=""
+    if [ -f "$VERDICT_FILE" ]; then
+      VERDICT=$(cat "$VERDICT_FILE")
+      rm -f "$VERDICT_FILE"
+    fi
+
+    case "$VERDICT" in
+      PASS)
+        touch "/tmp/style-guide-reviewed-${SESSION_ID}"
+        store_review_hash "$SESSION_ID" "style-guide" "docs/STYLE-GUIDE.md"
+        ;;
+      FAIL)
+        # Do NOT create marker — review found issues
+        ;;
+      *)
+        # No verdict file — backward compat, allow with marker
+        touch "/tmp/style-guide-reviewed-${SESSION_ID}"
+        store_review_hash "$SESSION_ID" "style-guide" "docs/STYLE-GUIDE.md"
+        ;;
+    esac
+
+    # Plan review: agent completion = reviewed.
+    # The main agent must actually run the review agent to reach this hook.
+    # No verdict file needed — PostToolUse:Agent is the unforgeable signal.
+    touch "/tmp/style-guide-plan-reviewed-${SESSION_ID}"
+    ;;
+esac
+
+exit 0

package/hooks/style-guide-reset-marker.sh

@@ -0,0 +1,22 @@
+#!/bin/bash
+# Style Guide - Stop hook
+# Removes the session marker so the next prompt requires a fresh style review.
+# This tightens the gate from per-session to per-turn.
+
+INPUT=$(cat)
+
+SESSION_ID=$(echo "$INPUT" | python3 -c "
+import sys, json
+data = json.load(sys.stdin)
+print(data.get('session_id', ''))
+" 2>/dev/null)
+
+if [ -n "$SESSION_ID" ]; then
+  rm -f "/tmp/style-guide-reviewed-${SESSION_ID}" \
+        "/tmp/style-guide-reviewed-${SESSION_ID}.hash" \
+        "/tmp/style-guide-verdict" \
+        "/tmp/style-guide-plan-reviewed-${SESSION_ID}" \
+        "/tmp/style-guide-plan-verdict"
+fi
+
+exit 0

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@windyroad/style-guide",
+  "version": "0.2.0",
+  "description": "Style guide enforcement for CSS and UI components",
+  "bin": {
+    "windyroad-style-guide": "./bin/install.mjs"
+  },
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/windyroad/agent-plugins.git",
+    "directory": "packages/style-guide"
+  },
+  "keywords": [
+    "claude-code",
+    "claude-code-plugin",
+    "ai-agent",
+    "ai-coding"
+  ],
+  "files": [
+    "bin/",
+    "agents/",
+    "hooks/",
+    "skills/",
+    ".claude-plugin/"
+  ]
+}

package/skills/wr:style-guide/SKILL.md

@@ -0,0 +1,96 @@
+---
+name: wr:style-guide
+description: Create or update the project's docs/STYLE-GUIDE.md by examining existing CSS, components, and design patterns, then asking the user about style preferences.
+allowed-tools: Read, Write, Edit, Bash, Glob, Grep, AskUserQuestion
+---
+
+# Style Guide Generator
+
+Create or update `docs/STYLE-GUIDE.md` tailored to this project's visual design and component patterns. The style-guide-lead agent reads this file to review CSS and UI component changes.
+
+## What belongs in docs/STYLE-GUIDE.md
+
+- **Design tokens**: Colors, spacing, typography, border radius, shadows
+- **Component patterns**: How common UI elements should be built
+- **Layout conventions**: Grid system, responsive breakpoints, spacing rhythm
+- **CSS conventions**: Naming, architecture (BEM, utility-first, CSS modules, etc.)
+- **Do/Don't examples**: Concrete examples drawn from the actual project
+- **Last reviewed date**: When the guide was last reviewed or updated
+
+## Steps
+
+### 1. Discover project context
+
+Examine the project to understand its current styling approach.
+
+**Find the CSS architecture** by scanning for:
+- CSS/SCSS/Sass/Less files and their structure
+- Tailwind config (`tailwind.config.*`)
+- CSS-in-JS patterns (styled-components, emotion, CSS modules)
+- Design token files or theme configuration
+- Component library usage (MUI, Chakra, Radix, shadcn, etc.)
+
+**Discover design patterns**:
+- Color palette (scan CSS custom properties, Tailwind config, or theme files)
+- Typography scale (font sizes, weights, line heights in use)
+- Spacing system (consistent spacing values or ad-hoc)
+- Component structure (how are common patterns like cards, buttons, forms built?)
+- Responsive approach (breakpoints, mobile-first vs desktop-first)
+
+**Identify inconsistencies**:
+- Are there multiple color values that should be the same token?
+- Mixed approaches (some components use utility classes, others use custom CSS)?
+- Inconsistent spacing or typography?
+
+### 2. Check for existing guide
+
+If `docs/STYLE-GUIDE.md` already exists, read it. Identify:
+- Whether it still reflects the current CSS architecture
+- Whether examples reference classes or patterns that no longer exist
+- Whether the last reviewed date is stale (> 2 weeks)
+
+### 3. Draft the style guide
+
+Based on project discovery, draft sections covering:
+
+**CSS Architecture**:
+What approach this project uses and why (utility-first, BEM, CSS modules, etc.).
+
+**Design Tokens**:
+Document the token system (colors, spacing, typography, shadows, borders). Reference the actual source (CSS variables, Tailwind config, theme file).
+
+**Component Patterns**:
+How to build common UI elements. At least cover: buttons, forms, cards, navigation, layout containers.
+
+**Layout and Responsive**:
+Grid system, breakpoints, spacing rhythm, container widths.
+
+**Do/Don't Examples**:
+At least 5 concrete pairs drawn from the actual project. Show the wrong way and the right way.
+
+**Naming Conventions**:
+Class naming, file naming, component naming patterns.
+
+### 4. Confirm with the user
+
+You MUST use the AskUserQuestion tool to collect user confirmation.
+
+Present:
+1. The CSS architecture summary and ask if it's accurate
+2. The design tokens discovered and ask if any are wrong or missing
+3. The component patterns and ask if the direction is right
+4. Whether any specific requirements are missing (e.g., dark mode, accessibility contrast requirements, animation preferences)
+
+### 5. Write docs/STYLE-GUIDE.md
+
+Write the guide including:
+- A header with "Last reviewed" date (today's date)
+- All sections from step 3, refined based on user feedback from step 4
+- A note that the wr-style-guide:agent reads this file to review CSS and UI changes
+
+If updating rather than creating:
+- Preserve existing guidance the user hasn't asked to change
+- Show the user a diff of what changed
+- Update the "Last reviewed" date
+
+$ARGUMENTS