From e4f9edd97f3a2689b19bbf6336e191a10e08f1d8 Mon Sep 17 00:00:00 2001
From: Richie <richie.phillips@proton.me>
Date: Wed, 25 Mar 2026 15:22:10 +1100
Subject: [PATCH] Add preflight quality check skill

Runs 5 checks before commit: TypeScript compilation, Storybook build,
token sync verification, hardcoded values scan, and component exports.
Integrates with the git workflow to catch issues before they hit the repo.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
---
 .claude/skills/preflight/SKILL.md | 80 +++++++++++++++++++++++++++++++
 1 file changed, 80 insertions(+)
 create mode 100644 .claude/skills/preflight/SKILL.md

diff --git a/.claude/skills/preflight/SKILL.md b/.claude/skills/preflight/SKILL.md
new file mode 100644
index 0000000..b205330
--- /dev/null
+++ b/.claude/skills/preflight/SKILL.md
@@ -0,0 +1,80 @@
+---
+name: preflight
+description: Pre-commit quality check — verifies TypeScript, Storybook, token sync, and no hardcoded values
+argument-hint: "[--fix to auto-fix issues]"
+---
+
+Run quality checks before committing. Reports pass/fail for each check and blocks commit if critical issues are found.
+
+**Mode:** $ARGUMENTS (pass `--fix` to attempt auto-fixes, otherwise report-only)
+
+**Run these checks in order:**
+
+### 1. TypeScript compilation
+```bash
+npx tsc --noEmit 2>&1 | grep -v "tokens.js"
+```
+- **Pass:** No errors (the tokens.js declaration warning is a known pre-existing issue — ignore it)
+- **Fail:** Any other TypeScript errors → report them
+- **Critical:** Yes — do not commit if this fails
+
+### 2. Storybook build
+```bash
+npx storybook build --quiet 2>&1
+```
+- **Pass:** Build succeeds
+- **Fail:** Build errors → report them
+- **Critical:** Yes — do not commit if this fails
+
+### 3. Token sync check
+Compare timestamps: do the generated outputs (`src/theme/generated/tokens.js`, `src/theme/generated/tokens.css`) have an older modification time than any `tokens/**/*.json` file?
+```bash
+# Find newest token JSON file
+newest_token=$(find tokens/ -name "*.json" -newer src/theme/generated/tokens.js 2>/dev/null | head -5)
+```
+- **Pass:** No token JSON files are newer than the generated outputs
+- **Fail:** Token JSON was modified but outputs weren't regenerated
+- **Fix:** Run `npm run build:tokens`
+- **Critical:** Yes — stale generated tokens cause silent bugs
+
+### 4. Hardcoded values scan
+Scan component files for hardcoded colours, spacing, and font values that should use tokens:
+```bash
+# Check for hex colours in component files (excluding stories and tokens)
+grep -rn "#[0-9a-fA-F]\{3,8\}" src/components/ --include="*.tsx" --include="*.ts" | grep -v ".stories." | grep -v "// ok-hardcode"
+```
+- **Pass:** No hex colours found in component source files (stories are exempt)
+- **Fail:** Hardcoded values found → report file and line
+- **Note:** Lines with `// ok-hardcode` comment are exempted (for rare intentional cases)
+- **Critical:** No — warn but don't block commit
+
+### 5. Component exports check
+Verify each component folder has a barrel export (`index.ts`) and the component has `displayName`:
+```bash
+# Check for missing index.ts
+for dir in src/components/atoms/*/; do
+  [ -f "$dir/index.ts" ] || echo "Missing index.ts: $dir"
+done
+# Check for missing displayName (exclude stories)
+find src/components/atoms/ -name "*.tsx" ! -name "*.stories.tsx" | xargs grep -L "displayName" 2>/dev/null
+```
+- **Pass:** All component folders have index.ts and components set displayName
+- **Fail:** Missing exports or displayName
+- **Critical:** No — warn but don't block commit
+
+### Report format
+```
+PREFLIGHT RESULTS
+═══════════════════════════════
+✓ TypeScript .............. PASS
+✓ Storybook build ........ PASS
+✓ Token sync ............. PASS
+⚠ Hardcoded values ....... WARN (2 issues)
+✓ Component exports ...... PASS
+───────────────────────────────
+Result: PASS (safe to commit)
+```
+
+Use `PASS`, `FAIL`, or `WARN`. If any critical check fails, the result is `FAIL (do not commit)`. If only warnings, result is `PASS (safe to commit)` with warnings listed.
+
+If `--fix` was passed, attempt to fix issues automatically (e.g., run `npm run build:tokens` for stale tokens) and re-check.