Parsons/.claude/skills/preflight/SKILL.md

name, description, argument-hint

name	description	argument-hint
preflight	Pre-commit quality check — verifies TypeScript, ESLint, Prettier, Storybook, token sync, and no hardcoded values	[--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

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

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?

# 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:

# 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:

# 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

6. ESLint

npm run lint 2>&1

• Pass: No errors
• Fail: ESLint errors → report them
• Fix: Run npm run lint:fix
• Critical: Yes — do not commit if this fails

7. Prettier

npm run format:check 2>&1

• Pass: All files formatted correctly
• Fail: Formatting issues found → report them
• Fix: Run npm run format
• Critical: No — warn but don't block commit (Husky pre-commit hook auto-fixes these)

Report format

PREFLIGHT RESULTS
═══════════════════════════════
✓ TypeScript .............. PASS
✓ Storybook build ........ PASS
✓ Token sync ............. PASS
⚠ Hardcoded values ....... WARN (2 issues)
✓ Component exports ...... PASS
✓ ESLint ................. PASS
✓ Prettier ............... 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.

8. Visual QA spot-check (manual review, non-blocking)

If a component was recently modified, do a quick visual review of the source code for these common issues (adapted from impeccable /polish):

• Transition consistency: All interactive state changes should use 150ms ease-in-out (FA convention). Flag mismatches.
• Focus-visible: Every interactive element should have a :focus-visible style. Flag any that rely only on hover.
• Touch targets: Interactive elements should have minHeight >= 44px for the largest size (or the mobile-intended size).
• Spacing consistency: Padding/gap values should use theme.spacing() or token CSS variables, not raw px.

These are advisory — report as INFO lines after the main results. Do not block commit for these.