claude-code-superkit 0.0.0-stage → 1.5.3

package/packages/frontend-3d/agents/ui-design-reviewer.md

@@ -0,0 +1,169 @@
+---
+name: ui-design-reviewer
+description: Anti-slop UI review — typography, color calibration, layout diversity, motion quality, interactive states. Activate when reviewing frontend components for design quality.
+tokens: 2246
+model: opus
+allowed-tools: Read, Grep, Glob
+---
+
+# UI Design Reviewer
+
+You review frontend code for design quality, catching AI-generated slop patterns and enforcing premium aesthetics. Read-only reviewer: you report, you never edit.
+
+## Hard Rules
+
+1. Every FAIL MUST cite exact `file:line` from a file you Read in this session — never from memory.
+2. Severity is ONLY `CRITICAL` / `WARNING` / `SUGGESTION`. Confidence is ONLY `HIGH` / `MEDIUM` / `LOW`. Never `INFO`, never percentages.
+3. All 16 checks get a status row (`PASS` / `FAIL` / `N/A`) — never omit a check.
+4. A clean review (0 FAILs) is a valid result — do not manufacture findings.
+5. If a referenced file/symbol cannot be found: output `NOT FOUND: <path>` — never invent its contents.
+6. Never flag a documented, intentional design choice (Phase 0 context) as slop.
+
+## Phase 0 — Load Project Context
+
+Read if present, skip silently if absent: `CLAUDE.md` or `AGENTS.md` (design tokens, brand guidelines, UI conventions); `docs/architecture/*.md` (frontend layers, typography/color decisions); `.claude/rules/frontend-aesthetics-3d.md` (if present, treat as authoritative aesthetic standards).
+Use it to: avoid flagging the project's intentional choices (chosen accent palette, typography pairings) as AI slop. Violations of DOCUMENTED conventions → report with HIGH confidence instead of MEDIUM.
+
+## Process
+
+1. **Scope** — Determine files to review: if the caller names files, review those; otherwise Glob for the components mentioned in the task (e.g. `**/components/**/*.tsx`, `**/*.css`). Read every in-scope file in full. Done when: every in-scope file is Read or reported `NOT FOUND: <path>`.
+2. **Run the 16 checks** — Apply the checklist below to every in-scope file. Useful ripgrep patterns: `h-screen`, `from-purple|from-violet|from-indigo`, `tracking-`, `max-w-`, `transition|animate`, `linear`, `backdrop-blur`. A grep hit is a lead, not evidence — Read the surrounding code before marking FAIL. Done when: all 16 checks have a status for the reviewed scope.
+3. **Report** — Emit exactly the Output Contract. Done when: every FAIL row has `file:line`, every LOW-confidence suspicion is in Open Questions, and the score follows the Score Rule.
+
+## Review Checklist (16 checks)
+
+### Typography (3 checks)
+
+| # | Check | Severity | What to look for |
+|---|-------|----------|------------------|
+| 1 | Font choice | WARNING | No Inter/Roboto/Arial as display/headline font in premium designs — use distinctive fonts. System fonts OK for body text in utility apps. Tier rule below |
+| 2 | Headline tracking | WARNING | Headlines should use `tracking-tighter` or `tracking-tight`. Default tracking looks AI-generated |
+| 3 | Body width | SUGGESTION | Body text constrained to `max-w-[65ch]` or similar. Full-width paragraphs are hard to read |
+
+**Check 1 tier rule** — decide premium vs utility in this order: (a) project docs declare a design tier → use it; (b) no declaration → marketing/landing/hero pages are premium, dashboards/admin/internal tools are utility; (c) still ambiguous → treat as premium but report the finding at MEDIUM confidence.
+
+### Color (3 checks)
+
+| # | Check | Severity | What to look for |
+|---|-------|----------|------------------|
+| 4 | Accent count | WARNING | Max 1 accent color. Multiple accents = visual noise. Use shades/tints for variation |
+| 5 | Saturation | WARNING | Accent saturation < 80%. Hyper-saturated colors look cheap on most screens |
+| 6 | AI gradient default | CRITICAL | No purple-to-blue gradient as default accent. This is the #1 AI-generated pattern red flag |
+
+### Layout (3 checks)
+
+| # | Check | Severity | What to look for |
+|---|-------|----------|------------------|
+| 7 | Center bias | WARNING | Not everything centered. Use split screen, asymmetric layouts when content permits |
+| 8 | Grid over flex | SUGGESTION | CSS Grid for page layout over flex percentage math. Grid is more intentional |
+| 9 | Viewport height | CRITICAL | `min-h-[100dvh]` not `h-screen`. iOS Safari address bar causes viewport jumping with `h-screen` |
+
+### Motion (3 checks)
+
+| # | Check | Severity | What to look for |
+|---|-------|----------|------------------|
+| 10 | Spring physics | WARNING | Use spring/ease-out for interactions, not `linear`. Linear motion feels robotic |
+| 11 | Staggered reveals | SUGGESTION | List/grid items use staggered entrance (0.05-0.1s delay between items). Batch pop-in looks cheap |
+| 12 | No instant changes | WARNING | State transitions should animate. Instant opacity/display toggle breaks flow |
+
+### Interactive States (2 checks)
+
+| # | Check | Severity | What to look for |
+|---|-------|----------|------------------|
+| 13 | Loading/empty/error | CRITICAL | All async states have explicit UI: loading skeleton, empty state message, error fallback |
+| 14 | Active feedback | WARNING | `:active` state on buttons/cards — `scale-[0.98]` or similar for tactile feel |
+
+### Glassmorphism (2 checks — `N/A` if no glassmorphic elements in scope)
+
+| # | Check | Severity | What to look for |
+|---|-------|----------|------------------|
+| 15 | Glass border | SUGGESTION | Glassmorphic elements have inner `border border-white/10` + `shadow-inner` for refraction effect |
+| 16 | Tinted shadow | SUGGESTION | Shadows should be tinted (not pure black) — `shadow-accent/10` matches the element's context |
+
+## Evidence Gate
+
+Report a finding ONLY if all four hold:
+1. **Citation** — exact `file:line` you Read in this session, never from memory.
+2. **Failure mode** — a concrete input/path that triggers the problem (no "could be problematic").
+3. **Context** — you read the surrounding component/styles, not just the flagged line.
+4. **Severity** you can defend to a skeptic.
+If a referenced file/symbol cannot be found: output `NOT FOUND: <path>` — never invent its contents.
+A clean review (0 findings) is a valid result — do not manufacture findings.
+
+## Severity / Confidence
+
+Severity — CRITICAL: data loss, security, crash (here: broken viewport, missing async states, hallmark AI-slop gradient) · WARNING: incorrect behavior under specific conditions, degraded perceived quality · SUGGESTION: style/readability, safe to ignore.
+Confidence — HIGH (≥80): problem visible in the code · MEDIUM (60–79): pattern-based, mark "needs verification" · LOW (<60): route to Open Questions, never silently drop.
+
+## Score Rule
+
+`score = round(100 × PASS / (PASS + FAIL))`, counting only checks with status PASS or FAIL (N/A excluded). Any FAIL on a CRITICAL check (#6, #9, #13) caps the score at 50. If PASS + FAIL = 0, report `score: N/A`.
+
+## Output Contract
+
+~~~
+## UI Design Review: <files or scope>
+
+### Check Table
+| # | Check | Severity | Status | Confidence | Evidence |
+|---|-------|----------|--------|------------|----------|
+<16 rows, one per check; Status PASS / FAIL / N/A; FAIL rows include file:line; N/A rows say why>
+
+### Findings
+[SEVERITY/CONFIDENCE] file:line — one-line description
+  Evidence: <what the code shows>
+  Fix: <concrete change>
+<one block per FAIL row; if none: "No findings — clean review.">
+
+### Open Questions
+LOW-confidence or ambiguous items — listed, not dropped:
+- file:line — what you suspect + what context would confirm it
+<or "None.">
+
+### Summary
+- Checks: X PASS, Y FAIL, Z N/A
+- Critical failures: <list or "none">
+- Design quality score: <N>/100 (Score Rule)
+- Recommendations: <top 3 or fewer, most impactful first>
+~~~
+
+**Mini example** (abbreviated to 2 rows):
+
+~~~
+## UI Design Review: src/components/Hero.tsx
+
+### Check Table
+| # | Check | Severity | Status | Confidence | Evidence |
+|---|-------|----------|--------|------------|----------|
+| 1 | Font choice | WARNING | PASS | HIGH | Space Grotesk display font, Hero.tsx:12 |
+| 6 | AI gradient default | CRITICAL | FAIL | HIGH | Hero.tsx:34 `from-purple-500 to-blue-600` |
+
+### Findings
+[CRITICAL/HIGH] src/components/Hero.tsx:34 — purple-to-blue gradient as hero accent
+  Evidence: `bg-gradient-to-r from-purple-500 to-blue-600` on the primary CTA background
+  Fix: replace with the project's single brand accent (or a shade/tint of it)
+
+### Open Questions
+None.
+
+### Summary
+- Checks: 13 PASS, 1 FAIL, 2 N/A
+- Critical failures: #6 AI gradient default
+- Design quality score: 50/100 (Score Rule — CRITICAL fail caps at 50)
+- Recommendations: replace hero gradient with brand accent
+~~~
+
+## Done ONLY when
+
+- [ ] All 16 checks have a status row (PASS / FAIL / N/A).
+- [ ] Every FAIL row and Finding cites `file:line` from a file Read this session.
+- [ ] Score computed by the Score Rule — not estimated.
+- [ ] LOW-confidence items are in Open Questions, not dropped and not promoted.
+
+## Recap — non-negotiables
+
+- FAIL requires exact `file:line` you Read this session; unfound files → `NOT FOUND: <path>`.
+- Only CRITICAL / WARNING / SUGGESTION + HIGH / MEDIUM / LOW — no INFO, no percentages.
+- All 16 checks reported; 0 FAILs is a legitimate outcome — never manufacture findings.
+- Documented project design choices are never slop.
+- Score comes from the Score Rule, never from feel.

package/packages/frontend-3d/commands/capture-screen.md

@@ -0,0 +1,166 @@
+---
+description: Capture a React component as PNG texture for 3D model screens
+argument-hint: "[port] (default: 3000)"
+allowed-tools: Bash, Read
+---
+
+# Capture Screen PNG
+
+## Role
+
+Capture a running app screen as a high-resolution PNG in `public/textures/` for use as a texture on a 3D model: a full-viewport screenshot of a URL/route, or a single element marked `data-screen-id` (element capture runs through the Step 5 script).
+
+## Hard Rules
+
+1. Playwright CLI: use ONLY these verified flags — `--viewport-size`, `--device`, `--full-page`, `--wait-for-timeout`. A `--device-scale-factor` flag DOES NOT exist; for DPR control beyond a device preset use the Step 5 script.
+2. Dev server not responding → STOP and tell the user to start it. Never screenshot a dead server.
+3. No capture route found → ASK the user for the route. Never assume `/capture` exists.
+4. Defaults: iPhone 16 Pro Max — viewport 440x956, scale 2x (expected output 880x1912), corner radius R=124 (62pt × 2). Another device → use its Resolution Guide row; non-iPhone corner radius → ask the user or skip rounding, never guess.
+5. Before reporting done, verify the PNG's real dimensions (Step 7); if they differ from expected, report Status: MISMATCH — do not claim OK.
+
+## Prerequisites
+
+- Dev server running (Vite, Next.js, etc.)
+- `playwright` installed (`npx playwright install chromium`)
+- `sharp` installed (only for rounded corners, Step 6)
+
+## Resolution Guide
+
+| Device | Viewport | @2x Output |
+|--------|----------|------------|
+| iPhone 15 Pro | 393x852 | 786x1704 |
+| iPhone 16 Pro Max | 440x956 | 880x1912 |
+| iPad Pro 11" | 834x1194 | 1668x2388 |
+| MacBook Pro 14" | 1512x982 | 3024x1964 |
+
+## Steps
+
+### 1. Resolve inputs
+
+- `<PORT>` = $ARGUMENTS if a port number was given, else `3000`. Substitute this value everywhere `<PORT>` appears below.
+- Target device: the default from Hard Rule 4, unless the user named another Resolution Guide device.
+- Done when: `<PORT>`, viewport, and expected output size are fixed.
+
+### 2. Check dev server
+
+```bash
+curl -s -o /dev/null -w "%{http_code}" "http://localhost:<PORT>"
+```
+
+- Status 200–399 → continue. Anything else, or no output → STOP (Hard Rule 2): "Dev server not responding on port <PORT> — start it and re-run /capture-screen."
+- Done when: a 2xx/3xx status was actually observed.
+
+### 3. Find the capture route
+
+```bash
+find . -name "capture*.html" -o -name "test-3d*.html" 2>/dev/null | head -5
+grep -rln "data-screen-id" src/ app/ pages/ 2>/dev/null | head -5
+```
+
+- Capture/test page found → `<ROUTE>` = its route (e.g. `/capture`).
+- `data-screen-id` found in a component → note it: capture that element in Step 5.
+- Neither found → ASK the user which route renders the screen (Hard Rule 3), then set `<ROUTE>` from the answer.
+- Done when: `<ROUTE>` is set and you know whether element capture applies.
+
+### 4. Capture — CLI path
+
+Pick exactly ONE:
+
+- **1x at exact viewport** (quick preview, any device row):
+
+```bash
+npx playwright screenshot \
+  --viewport-size "440,956" \
+  --wait-for-timeout 3000 \
+  "http://localhost:<PORT><ROUTE>" \
+  public/textures/screen-capture.png
+```
+
+- **@2x via device preset — iPad Pro 11" only** (its Playwright descriptor is 2x DPR: 834x1194 → 1668x2388). iPhone presets are 3x DPR with smaller viewports and do NOT produce the table's @2x sizes:
+
+```bash
+npx playwright screenshot --device "iPad Pro 11" --wait-for-timeout 3000 \
+  "http://localhost:<PORT><ROUTE>" public/textures/screen-capture.png
+```
+
+- **Neither fits** (exact @2x at iPhone/MacBook sizes, or element capture) → go to Step 5.
+
+- Done when: PNG written, or Step 5 chosen.
+
+### 5. Capture — script fallback (exact @2x / element by data-screen-id)
+
+```bash
+node -e "
+const { chromium } = require('playwright');
+(async () => {
+  const browser = await chromium.launch();
+  const page = await browser.newPage({ viewport: { width: 440, height: 956 }, deviceScaleFactor: 2 });
+  await page.goto('http://localhost:<PORT><ROUTE>', { waitUntil: 'networkidle' });
+  const el = page.locator('[data-screen-id]');
+  if (await el.count() > 0) { await el.first().screenshot({ path: 'public/textures/screen-capture.png' }); }
+  else { await page.screenshot({ path: 'public/textures/screen-capture.png' }); }
+  await browser.close();
+})();
+"
+```
+
+- Replace width/height with the chosen Resolution Guide viewport; narrow the selector to `[data-screen-id="<id>"]` if a specific id is known.
+- Done when: PNG written.
+
+### 6. Apply rounded corners (optional, for phone screens)
+
+R=124 is the Hard Rule 4 default; for other devices follow Hard Rule 4.
+
+```bash
+node -e "
+const sharp = require('sharp');
+const fs = require('fs');
+const FILE = 'public/textures/screen-capture.png';
+const R = 124; // 62pt * 2x
+async function main() {
+  const meta = await sharp(FILE).metadata();
+  const w = meta.width, h = meta.height;
+  const mask = Buffer.from('<svg width=\"'+w+'\" height=\"'+h+'\"><rect x=\"0\" y=\"0\" width=\"'+w+'\" height=\"'+h+'\" rx=\"'+R+'\" ry=\"'+R+'\" fill=\"white\"/></svg>');
+  await sharp(FILE).ensureAlpha().composite([{input:mask,blend:'dest-in'}]).png().toFile(FILE+'.tmp');
+  fs.renameSync(FILE+'.tmp', FILE);
+  const m2 = await sharp(FILE).metadata();
+  console.log('Done:', m2.width, 'x', m2.height, 'alpha:', m2.hasAlpha);
+}
+main();
+"
+```
+
+- Done when: script printed `Done: <w> x <h> alpha: true` (skipped entirely if corners not wanted).
+
+### 7. Verify output
+
+```bash
+# macOS (built-in)
+sips -g pixelWidth -g pixelHeight public/textures/screen-capture.png
+# Linux (requires ImageMagick: apt install imagemagick)
+identify public/textures/screen-capture.png
+# Universal (Node.js)
+node -e "const s=require('sharp');s('public/textures/screen-capture.png').metadata().then(m=>console.log(m.width+'x'+m.height,'alpha:',m.hasAlpha))"
+```
+
+- Expected dimensions: @2x table value for the Step 5 full-viewport path or the iPad preset; the viewport size for the 1x CLI path. Element capture (`data-screen-id`): expected = the element's rendered box × 2 — the device table does not apply.
+- Done when: real dimensions compared against expected, and `alpha: true` confirmed if Step 6 ran.
+
+## Output
+
+```
+## Capture Result
+- URL: http://localhost:<PORT><ROUTE>
+- Method: [CLI 1x | CLI --device "iPad Pro 11" @2x | script @2x full-viewport | script element <data-screen-id>]
+- File: public/textures/screen-capture.png
+- Dimensions: <W>x<H> (expected: <EW>x<EH>)
+- Corners: [applied R=<R>, alpha: yes | skipped]
+- Status: [OK | MISMATCH: <what differs>]
+```
+
+## Recap
+
+- Only verified CLI flags — `--device-scale-factor` does not exist; DPR beyond a preset means the Step 5 script.
+- Server down → STOP; no route found → ASK. Never assume `/capture`.
+- Default target: iPhone 16 Pro Max 440x956 @2x → 880x1912, R=124; other devices come from the Resolution Guide.
+- Verify real PNG dimensions before reporting; a size mismatch is reported, never hidden.

package/packages/frontend-3d/hooks/bundle-size-warn.sh

@@ -0,0 +1,93 @@
+#!/bin/bash
+# bundle-size-warn.sh — PostToolUse hook for Edit/Write
+# Warns on heavy package imports that bloat bundle size.
+# Warnings only (exit 0 always) — never blocks.
+# Profile: standard, strict (skip on fast)
+
+# Unified profile + disable check
+SUPERKIT_PROFILE_LIB="$(dirname "$0")/lib/profile.sh"
+[ -f "$SUPERKIT_PROFILE_LIB" ] || SUPERKIT_PROFILE_LIB="$(dirname "$0")/../lib/profile.sh"
+# shellcheck source=/dev/null
+[ -f "$SUPERKIT_PROFILE_LIB" ] && source "$SUPERKIT_PROFILE_LIB" && should_skip_hook "$(basename "$0" .sh)" && exit 0
+
+PROFILE="${CLAUDE_HOOK_PROFILE:-standard}"
+if [ "$PROFILE" = "fast" ]; then
+  exit 0
+fi
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Only process .tsx/.jsx/.ts files
+if [[ ! "$FILE_PATH" =~ \.(tsx|jsx|ts)$ ]]; then
+  exit 0
+fi
+
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Get the content that was written/edited
+CONTENT=$(echo "$INPUT" | jq -r '.tool_input.new_string // .tool_input.content // empty')
+
+if [ -z "$CONTENT" ]; then
+  exit 0
+fi
+
+BASENAME=$(basename "$FILE_PATH")
+WARNINGS=""
+
+# 1. moment.js (67kb gzipped)
+if echo "$CONTENT" | grep -qE "from\s+['\"]moment['\"]|require\s*\(\s*['\"]moment['\"]\s*\)" 2>/dev/null; then
+  WARNINGS="${WARNINGS}\n  ⚠ Bundle: moment (67kb gzipped) — consider date-fns or dayjs as lighter alternatives in ${BASENAME}"
+fi
+
+# 2. lodash full import (71kb gzipped)
+if echo "$CONTENT" | grep -qE "from\s+['\"]lodash['\"]|require\s*\(\s*['\"]lodash['\"]\s*\)" 2>/dev/null; then
+  WARNINGS="${WARNINGS}\n  ⚠ Bundle: lodash full import (71kb gzipped) — use lodash-es with named imports (import { debounce } from 'lodash-es') in ${BASENAME}"
+fi
+
+# 3. import * as THREE (600kb+)
+if echo "$CONTENT" | grep -qE "import\s+\*\s+as\s+THREE" 2>/dev/null; then
+  WARNINGS="${WARNINGS}\n  ⚠ Bundle: import * as THREE (600kb+) — use named imports (import { Scene, Mesh } from 'three') or dynamic import() for code splitting in ${BASENAME}"
+fi
+
+# 4. chart.js (200kb+ gzipped)
+if echo "$CONTENT" | grep -qE "from\s+['\"]chart\.js['\"]|require\s*\(\s*['\"]chart\.js['\"]\s*\)" 2>/dev/null; then
+  WARNINGS="${WARNINGS}\n  ⚠ Bundle: chart.js (200kb+) — use tree-shaking imports: import { Chart, LineController } from 'chart.js' in ${BASENAME}"
+fi
+
+# 5. @mui/material (300kb+)
+if echo "$CONTENT" | grep -qE "from\s+['\"]@mui/material['\"]" 2>/dev/null; then
+  WARNINGS="${WARNINGS}\n  ⚠ Bundle: @mui/material barrel import (300kb+) — use deep imports: import Button from '@mui/material/Button' in ${BASENAME}"
+fi
+
+# 6. antd (350kb+)
+if echo "$CONTENT" | grep -qE "from\s+['\"]antd['\"]" 2>/dev/null; then
+  WARNINGS="${WARNINGS}\n  ⚠ Bundle: antd barrel import (350kb+) — use babel-plugin-import or import { Button } from 'antd' with tree-shaking in ${BASENAME}"
+fi
+
+# 7. framer-motion (140kb)
+if echo "$CONTENT" | grep -qE "from\s+['\"]framer-motion['\"]" 2>/dev/null; then
+  WARNINGS="${WARNINGS}\n  ⚠ Bundle: framer-motion (140kb) — consider motion/react (lighter) or CSS animations for simple transitions in ${BASENAME}"
+fi
+
+# 8. Generic namespace import warning (import * as)
+if echo "$CONTENT" | grep -qE "import\s+\*\s+as\s+" 2>/dev/null; then
+  # Don't double-warn on THREE which is already covered
+  if ! echo "$CONTENT" | grep -qE "import\s+\*\s+as\s+THREE" 2>/dev/null; then
+    WARNINGS="${WARNINGS}\n  ⚠ Bundle: namespace import (import * as) defeats tree-shaking — prefer named imports in ${BASENAME}"
+  fi
+fi
+
+# Output warnings
+if [ -n "$WARNINGS" ]; then
+  echo -e "\nBundle size check:${WARNINGS}"
+  echo ""
+fi
+
+exit 0

package/packages/frontend-3d/hooks/gsap-pattern-check.sh

@@ -0,0 +1,74 @@
+#!/bin/bash
+# gsap-pattern-check.sh — PostToolUse hook for Edit/Write
+# Checks for common GSAP anti-patterns in .tsx/.jsx files.
+# Warnings only (exit 0 always) — never blocks.
+# Profile: standard, strict (skip on fast)
+
+# Unified profile + disable check
+SUPERKIT_PROFILE_LIB="$(dirname "$0")/lib/profile.sh"
+[ -f "$SUPERKIT_PROFILE_LIB" ] || SUPERKIT_PROFILE_LIB="$(dirname "$0")/../lib/profile.sh"
+# shellcheck source=/dev/null
+[ -f "$SUPERKIT_PROFILE_LIB" ] && source "$SUPERKIT_PROFILE_LIB" && should_skip_hook "$(basename "$0" .sh)" && exit 0
+
+PROFILE="${CLAUDE_HOOK_PROFILE:-standard}"
+if [ "$PROFILE" = "fast" ]; then
+  exit 0
+fi
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Only process .tsx/.jsx files
+if [[ ! "$FILE_PATH" =~ \.(tsx|jsx)$ ]]; then
+  exit 0
+fi
+
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+BASENAME=$(basename "$FILE_PATH")
+WARNINGS=""
+
+# 1. scrub: true without a number — should be scrub: 1 or scrub: 0.5
+if grep -qnE 'scrub:\s*true' "$FILE_PATH" 2>/dev/null; then
+  WARNINGS="${WARNINGS}\n  ⚠ GSAP: scrub: true should be a number (scrub: 1 or scrub: 0.5) for smooth animation in ${BASENAME}"
+fi
+
+# 2. scrollTrigger present but missing invalidateOnRefresh: true
+if grep -qiE 'scrollTrigger\s*[:={]' "$FILE_PATH" 2>/dev/null; then
+  if ! grep -q 'invalidateOnRefresh\s*:\s*true' "$FILE_PATH" 2>/dev/null; then
+    WARNINGS="${WARNINGS}\n  ⚠ GSAP: ScrollTrigger without invalidateOnRefresh: true — layout breaks on resize in ${BASENAME}"
+  fi
+fi
+
+# 3. Timeline created without tl.set({}, {}, 1.0) extension
+if grep -qE 'gsap\.timeline\(' "$FILE_PATH" 2>/dev/null; then
+  if ! grep -qE '\.set\(\s*\{\s*\}\s*,\s*\{\s*\}\s*,\s*[0-9]' "$FILE_PATH" 2>/dev/null; then
+    WARNINGS="${WARNINGS}\n  ⚠ GSAP: timeline without tl.set({}, {}, 1.0) — animations may compress into first 10% of scroll in ${BASENAME}"
+  fi
+fi
+
+# 4. GSAP imported directly from "gsap" instead of a centralized setup
+if grep -qE "from\s+['\"]gsap['\"]" "$FILE_PATH" 2>/dev/null; then
+  WARNINGS="${WARNINGS}\n  ⚠ GSAP: direct import from \"gsap\" — use a centralized GSAP setup file for unified plugin registration in ${BASENAME}"
+fi
+
+# 5. Animations outside gsap.context()
+if grep -qE 'gsap\.(to|from|fromTo|timeline)\(' "$FILE_PATH" 2>/dev/null; then
+  if ! grep -q 'gsap\.context(' "$FILE_PATH" 2>/dev/null; then
+    WARNINGS="${WARNINGS}\n  ⚠ GSAP: animations without gsap.context() — may cause cleanup issues on unmount in ${BASENAME}"
+  fi
+fi
+
+# Output warnings
+if [ -n "$WARNINGS" ]; then
+  echo -e "\nGSAP pattern check:${WARNINGS}"
+  echo ""
+fi
+
+exit 0

package/packages/frontend-3d/hooks/r3f-color-check.sh

@@ -0,0 +1,76 @@
+#!/bin/bash
+# r3f-color-check.sh — PostToolUse hook for Edit/Write
+# Checks Three.js / React Three Fiber color management anti-patterns.
+# Warnings only (exit 0 always) — never blocks.
+# Profile: standard, strict (skip on fast)
+
+# Unified profile + disable check
+SUPERKIT_PROFILE_LIB="$(dirname "$0")/lib/profile.sh"
+[ -f "$SUPERKIT_PROFILE_LIB" ] || SUPERKIT_PROFILE_LIB="$(dirname "$0")/../lib/profile.sh"
+# shellcheck source=/dev/null
+[ -f "$SUPERKIT_PROFILE_LIB" ] && source "$SUPERKIT_PROFILE_LIB" && should_skip_hook "$(basename "$0" .sh)" && exit 0
+
+PROFILE="${CLAUDE_HOOK_PROFILE:-standard}"
+if [ "$PROFILE" = "fast" ]; then
+  exit 0
+fi
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Only process .tsx/.jsx/.ts files
+if [[ ! "$FILE_PATH" =~ \.(tsx|jsx|ts)$ ]]; then
+  exit 0
+fi
+
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Only check files that import three or @react-three
+if ! grep -qE "from\s+['\"](@react-three/|three)" "$FILE_PATH" 2>/dev/null; then
+  exit 0
+fi
+
+BASENAME=$(basename "$FILE_PATH")
+WARNINGS=""
+
+# 1. sRGBEncoding / LinearEncoding deprecated since Three.js r152
+if grep -qE '(sRGBEncoding|LinearEncoding)' "$FILE_PATH" 2>/dev/null; then
+  WARNINGS="${WARNINGS}\n  ⚠ R3F: sRGBEncoding/LinearEncoding is deprecated since r152 — use texture.colorSpace = THREE.SRGBColorSpace or THREE.LinearSRGBColorSpace in ${BASENAME}"
+fi
+
+# 2. Texture loaded without explicit colorSpace assignment
+if grep -qE '(useTexture|useLoader\s*\(\s*TextureLoader|new\s+TextureLoader)' "$FILE_PATH" 2>/dev/null; then
+  if ! grep -qE '\.colorSpace\s*=' "$FILE_PATH" 2>/dev/null; then
+    WARNINGS="${WARNINGS}\n  ⚠ R3F: texture loaded without explicit colorSpace — set texture.colorSpace to avoid incorrect gamma in ${BASENAME}"
+  fi
+fi
+
+# 3. MeshStandardMaterial on screen/display elements (should use meshBasicMaterial)
+if grep -qiE '(meshStandardMaterial|MeshStandardMaterial)' "$FILE_PATH" 2>/dev/null; then
+  if grep -qiE '(screen|display|monitor|ui|hud|overlay)' "$FILE_PATH" 2>/dev/null; then
+    WARNINGS="${WARNINGS}\n  ⚠ R3F: MeshStandardMaterial on screen/display mesh — consider meshBasicMaterial (no lighting needed for flat screens) in ${BASENAME}"
+  fi
+fi
+
+# 4. Material with texture but no toneMapped prop
+if grep -qE '(\bmap\s*=|\bmap:\s)' "$FILE_PATH" 2>/dev/null; then
+  if grep -qE '(meshStandardMaterial|meshBasicMaterial|meshPhongMaterial|MeshStandardMaterial|MeshBasicMaterial|MeshPhongMaterial)' "$FILE_PATH" 2>/dev/null; then
+    if ! grep -qE 'toneMapped' "$FILE_PATH" 2>/dev/null; then
+      WARNINGS="${WARNINGS}\n  ⚠ R3F: material with texture but no toneMapped prop — add toneMapped={false} for UI/screen textures to preserve colors in ${BASENAME}"
+    fi
+  fi
+fi
+
+# Output warnings
+if [ -n "$WARNINGS" ]; then
+  echo -e "\nR3F color management check:${WARNINGS}"
+  echo ""
+fi
+
+exit 0

package/packages/frontend-3d/hooks/tailwind-version-guard.sh

@@ -0,0 +1,98 @@
+#!/bin/bash
+# tailwind-version-guard.sh — PostToolUse hook for Edit/Write
+# Detects Tailwind CSS v3 vs v4 syntax mismatches.
+# Warnings only (exit 0 always) — never blocks.
+# Profile: standard, strict (skip on fast)
+
+# Unified profile + disable check
+SUPERKIT_PROFILE_LIB="$(dirname "$0")/lib/profile.sh"
+[ -f "$SUPERKIT_PROFILE_LIB" ] || SUPERKIT_PROFILE_LIB="$(dirname "$0")/../lib/profile.sh"
+# shellcheck source=/dev/null
+[ -f "$SUPERKIT_PROFILE_LIB" ] && source "$SUPERKIT_PROFILE_LIB" && should_skip_hook "$(basename "$0" .sh)" && exit 0
+
+PROFILE="${CLAUDE_HOOK_PROFILE:-standard}"
+if [ "$PROFILE" = "fast" ]; then
+  exit 0
+fi
+
+INPUT=$(cat)
+FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')
+
+if [ -z "$FILE_PATH" ]; then
+  exit 0
+fi
+
+# Only process .tsx/.jsx/.css/.scss files
+if [[ ! "$FILE_PATH" =~ \.(tsx|jsx|css|scss)$ ]]; then
+  exit 0
+fi
+
+if [ ! -f "$FILE_PATH" ]; then
+  exit 0
+fi
+
+BASENAME=$(basename "$FILE_PATH")
+
+# Detect Tailwind version from nearest package.json
+TW_VERSION=""
+SEARCH_DIR=$(dirname "$FILE_PATH")
+while [ "$SEARCH_DIR" != "/" ]; do
+  if [ -f "${SEARCH_DIR}/package.json" ]; then
+    TW_VERSION=$(jq -r '.dependencies.tailwindcss // .devDependencies.tailwindcss // empty' "${SEARCH_DIR}/package.json" 2>/dev/null)
+    break
+  fi
+  SEARCH_DIR=$(dirname "$SEARCH_DIR")
+done
+
+if [ -z "$TW_VERSION" ]; then
+  exit 0
+fi
+
+# Extract major version number
+TW_MAJOR=$(echo "$TW_VERSION" | grep -oE '[0-9]+' | head -1)
+
+if [ -z "$TW_MAJOR" ]; then
+  exit 0
+fi
+
+WARNINGS=""
+
+if [ "$TW_MAJOR" = "4" ]; then
+  # Tailwind v4 project — warn on v3 patterns
+
+  # Old postcss plugin name (tailwindcss used as postcss plugin in v3)
+  if grep -qE "require\s*\(\s*['\"]tailwindcss['\"]\s*\)" "$FILE_PATH" 2>/dev/null; then
+    WARNINGS="${WARNINGS}\n  ⚠ TW v4: postcss plugin 'tailwindcss' is v3 syntax — v4 uses @tailwindcss/postcss in ${BASENAME}"
+  fi
+
+  # @tailwind directives (v3 syntax)
+  if grep -qE '@tailwind\s+(base|components|utilities)' "$FILE_PATH" 2>/dev/null; then
+    WARNINGS="${WARNINGS}\n  ⚠ TW v4: @tailwind directives are v3 syntax — v4 uses @import \"tailwindcss\" in ${BASENAME}"
+  fi
+
+  # tailwind.config reference (v4 uses CSS-based config)
+  if grep -qE 'tailwind\.config' "$FILE_PATH" 2>/dev/null; then
+    WARNINGS="${WARNINGS}\n  ⚠ TW v4: tailwind.config is v3 syntax — v4 uses @theme in CSS for configuration in ${BASENAME}"
+  fi
+
+elif [ "$TW_MAJOR" = "3" ]; then
+  # Tailwind v3 project — warn on v4 patterns
+
+  # @import "tailwindcss" (v4 syntax)
+  if grep -qE $'@import\\s+["\']tailwindcss["\']' "$FILE_PATH" 2>/dev/null; then
+    WARNINGS="${WARNINGS}\n  ⚠ TW v3: @import \"tailwindcss\" is v4 syntax — v3 uses @tailwind base/components/utilities in ${BASENAME}"
+  fi
+
+  # @theme directive (v4 syntax)
+  if grep -qE '@theme\s*\{' "$FILE_PATH" 2>/dev/null; then
+    WARNINGS="${WARNINGS}\n  ⚠ TW v3: @theme directive is v4 syntax — v3 uses tailwind.config.js for theme configuration in ${BASENAME}"
+  fi
+fi
+
+# Output warnings
+if [ -n "$WARNINGS" ]; then
+  echo -e "\nTailwind version guard (v${TW_MAJOR} detected):${WARNINGS}"
+  echo ""
+fi
+
+exit 0