rsc-universal 0.1.1

package/skills/deployment/scripts/verify.sh

@@ -0,0 +1,134 @@
+#!/usr/bin/env bash
+# verify.sh — deployment gate. Run inside YOUR project; CI runs the same file (parity).
+#
+# Usage:
+#   bash scripts/verify.sh
+#
+# Checks (each skips with a yellow warning if its tool is missing — never fails on absence):
+#   1. discover Dockerfiles / compose / workflows  (no artifacts -> exit 0)
+#   2. hadolint     each Dockerfile
+#   3. actionlint   .github/workflows
+#   4. trivy config (Dockerfile/compose/IaC misconfig)
+#   5. docker build smoke  (skippable: SKIP_DOCKER_BUILD=1)
+#   6. trivy image  (only if step 5 built an image)
+#   7. hosting config lint  (vercel.json JSON validity — detect-or-skip)
+#   8. summary; exit non-zero only on a real failure
+#
+# Hosting targets (Vercel / Hetzner+Coolify / …) are documented in
+# references/hosting-targets.md. Most are config-light: there is nothing to lint for a
+# Hetzner box or a Coolify resource (state lives in the platform, not the repo). The one
+# repo-local artifact worth a sanity check is vercel.json, and only if it exists.
+#
+# Env: SKIP_DOCKER_BUILD=1 to skip the build smoke; NO_COLOR=1 to disable color.
+#
+# Portability: runs on stock macOS bash 3.2 (no `mapfile`, no bash-4 features) and
+# on CI's bash 5 — that local<->CI parity is the whole point. Arrays are populated
+# without `mapfile` and always pre-initialised so `set -u` can't abort on an empty
+# array under bash 3.2.
+set -euo pipefail
+
+have() { command -v "$1" >/dev/null 2>&1; }
+
+# bash 3.2 aborts on `"${arr[@]}"` when arr is empty *and* unset under `set -u`.
+# Initialise every array up front and guard expansions with `${arr[@]+...}` so an
+# empty array is never an unbound-variable error. Never use `mapfile` (bash 4+).
+DOCKERFILES=()
+
+if [[ -n "${NO_COLOR:-}" ]]; then YEL=""; GRN=""; RED=""; RST=""
+else YEL=$'\033[33m'; GRN=$'\033[32m'; RED=$'\033[31m'; RST=$'\033[0m'; fi
+warn() { printf '%s[skip]%s %s\n' "$YEL" "$RST" "$*"; }
+ok()   { printf '%s[ ok ]%s %s\n' "$GRN" "$RST" "$*"; }
+fail() { printf '%s[fail]%s %s\n' "$RED" "$RST" "$*"; }
+
+FAILED=0
+BUILT_IMAGE=""
+SMOKE_TAG="verify-smoke:local"
+
+# 1. discover
+# Parenthesize the `-name ... -o -name ...` group so the path filter (-not -path)
+# applies to BOTH name patterns — otherwise the second pattern matches vendored or
+# example Dockerfiles and we'd smoke-build the wrong one. Read results with a while
+# loop (bash-3.2-safe; no `mapfile`). NUL-delimited so paths with spaces survive.
+while IFS= read -r -d '' df; do
+  DOCKERFILES+=("$df")
+done < <(find . \
+  \( -path '*/node_modules/*' -o -path '*/vendor/*' -o -path '*/.git/*' \
+     -o -path '*/examples/*' -o -path '*/example/*' -o -path '*/testdata/*' \) -prune \
+  -o \( -name 'Dockerfile' -o -name 'Dockerfile.*' \) -type f -print0 2>/dev/null)
+
+WORKFLOWS_DIR=".github/workflows"
+HAVE_WORKFLOWS=0; [[ -d "$WORKFLOWS_DIR" ]] && HAVE_WORKFLOWS=1
+COMPOSE=$(find . -maxdepth 2 \( -name 'compose*.y*ml' -o -name 'docker-compose*.y*ml' \) 2>/dev/null | head -n1 || true)
+if [[ ${#DOCKERFILES[@]} -eq 0 && $HAVE_WORKFLOWS -eq 0 && -z "$COMPOSE" ]]; then
+  printf 'No Dockerfiles, compose files, or workflows found — nothing to gate.\n'; exit 0
+fi
+
+# 2. hadolint
+if [[ ${#DOCKERFILES[@]} -eq 0 ]]; then
+  warn "no Dockerfile found — skipping Dockerfile lint"
+elif have hadolint; then
+  # `${arr[@]+"${arr[@]}"}` guards the expansion so an empty array is safe under
+  # `set -u` on bash 3.2 (we already know it's non-empty here, but stay consistent).
+  for df in ${DOCKERFILES[@]+"${DOCKERFILES[@]}"}; do
+    if hadolint --failure-threshold warning "$df"; then ok "hadolint $df"
+    else fail "hadolint $df"; FAILED=1; fi
+  done
+else warn "hadolint not installed — skipping Dockerfile lint"; fi
+
+# 3. actionlint
+if [[ $HAVE_WORKFLOWS -eq 1 ]]; then
+  if have actionlint; then
+    if actionlint; then ok "actionlint"; else fail "actionlint"; FAILED=1; fi
+  else warn "actionlint not installed — skipping workflow lint"; fi
+fi
+
+# 4. trivy config
+if have trivy; then
+  if trivy config --exit-code 1 --severity HIGH,CRITICAL .; then ok "trivy config"
+  else fail "trivy config"; FAILED=1; fi
+else warn "trivy not installed — skipping config/image scan"; fi
+
+# 5. docker build smoke
+if [[ -n "${SKIP_DOCKER_BUILD:-}" ]]; then
+  warn "SKIP_DOCKER_BUILD set — skipping build smoke"
+elif have docker && [[ ${#DOCKERFILES[@]} -gt 0 ]]; then
+  DF="${DOCKERFILES[0]}"
+  if DOCKER_BUILDKIT=1 docker build --pull -t "$SMOKE_TAG" -f "$DF" "$(dirname "$DF")"; then
+    ok "docker build $DF"; BUILT_IMAGE="$SMOKE_TAG"
+  else fail "docker build $DF"; FAILED=1; fi
+else warn "docker not available or no Dockerfile — skipping build smoke"; fi
+
+# 6. trivy image (only if we built one)
+if [[ -n "$BUILT_IMAGE" ]]; then
+  if have trivy; then
+    if trivy image --exit-code 1 --severity HIGH,CRITICAL --ignore-unfixed "$BUILT_IMAGE"; then
+      ok "trivy image $BUILT_IMAGE"
+    else fail "trivy image $BUILT_IMAGE"; FAILED=1; fi
+  else warn "trivy not installed — skipping image scan"; fi
+fi
+
+# 7. hosting config lint — vercel.json JSON validity (detect-or-skip).
+# Only runs if a vercel.json exists. Prefer python3/node: they set a reliable non-zero
+# exit on malformed JSON. jq is the last resort and MUST use `-e` — some jq builds (e.g.
+# Apple's jq-1.6) print a parse error to stderr but still exit 0 without it. If none of
+# the three is installed, skip — never fail on a missing linter.
+VERCEL_JSON=$(find . -maxdepth 2 -name 'vercel.json' -not -path '*/node_modules/*' 2>/dev/null | head -n1 || true)
+if [[ -n "$VERCEL_JSON" ]]; then
+  if have python3; then
+    if python3 -c 'import json,sys; json.load(open(sys.argv[1]))' "$VERCEL_JSON" >/dev/null 2>&1; then
+      ok "vercel.json valid JSON ($VERCEL_JSON)"
+    else fail "vercel.json is not valid JSON ($VERCEL_JSON)"; FAILED=1; fi
+  elif have node; then
+    if node -e 'JSON.parse(require("fs").readFileSync(process.argv[1],"utf8"))' "$VERCEL_JSON" >/dev/null 2>&1; then
+      ok "vercel.json valid JSON ($VERCEL_JSON)"
+    else fail "vercel.json is not valid JSON ($VERCEL_JSON)"; FAILED=1; fi
+  elif have jq; then
+    if jq -e . "$VERCEL_JSON" >/dev/null 2>&1; then ok "vercel.json valid JSON ($VERCEL_JSON)"
+    else fail "vercel.json is not valid JSON ($VERCEL_JSON)"; FAILED=1; fi
+  else warn "no python3/node/jq — skipping vercel.json validation"; fi
+fi
+
+# 8. summary
+if [[ $FAILED -eq 0 ]]; then ok "all checks passed (skips are not failures)"
+else fail "one or more checks failed"; fi
+exit "$FAILED"

package/skills/design/SKILL.md

@@ -0,0 +1,399 @@
+---
+name: design
+description: "Use when designing a modern UI, building/writing a high-converting landing page or web page, refreshing a hero, choosing type/color/spacing/motion, or making an interface feel premium instead of generic/AI-templated. Brand-grounded: reads the project's 02-DOCS brand study first and STOPS to interview the user if it is missing or incomplete. Research-first: studies award-winning current work (Awwwards, Godly, Land-book, Refactoring UI, Linear/Stripe/Vercel/Resend-tier) and pulls current 2026 trends with citations before prescribing. Ships Tailwind v4 + Next.js 15 + React 19 patterns with correctly-stated WCAG 2.2 AA and Core Web Vitals (LCP/INP/CLS) as hard design constraints; ties to 'marketing' for the words and 'nextjs' for the build. Triggers: 'design a landing page', 'build a web page', 'make this look premium', 'pick a color palette', 'this UI feels generic', 'bento section', 'design review', 'modern UI'."
+tags: [design, ux, ui, landing, conversion]
+recommends: [nextjs, marketing]
+origin: risco
+---
+
+# Design — Product UI, Landing Pages & Conversion Copy
+
+*Research the best current work, then ship a premium, accessible, fast, high-converting interface.*
+
+## When to use / When NOT to use
+
+Use when:
+
+- Building a new landing or marketing page.
+- Doing a redesign or a polish pass on an existing surface.
+- Writing hero, value-prop, pricing, or FAQ copy.
+- Choosing a visual system: type, color, spacing, radius, shadow, motion.
+- Rescuing a UI that "feels generic / AI-slop".
+- Running pre-launch design QA.
+
+Do NOT use when (delegate or decline):
+
+- Pure backend/data/infra work with no UI surface → decline; there is nothing to design.
+- Dense internal operational tooling used daily (not a sales page) → apply product-domain judgment and do NOT force a landing composition (the *frontend-design-direction* lens, an external reference — not a repo skill).
+- Native iOS/SwiftUI Liquid Glass material → the *liquid-glass-design* reference (external; this skill ships the *web* glass approximation only).
+- Deep motion code mechanics (springs, `AnimatePresence` internals, layout animations) → the *motion-ui* / *motion-foundations* references (external; this skill sets motion *intent + budget*).
+- Deep keyword research, GEO, or a technical SEO audit → the `../marketing/SKILL.md` sibling (it owns SEO-aware structure + keyword/intent; this skill only enforces SEO-aware *structure* in markup).
+
+**Tool vs. landing page:** A SaaS operations tool should be dense, quiet, and scannable — never paint a marketing skin on a tool that needs repeated daily use.
+
+## Brand grounding (read this first)
+
+Before producing ANY landing / web-page / marketing output, ground in the project's brand study. A design with no brand behind it is a guess, and a guess defaults to your AI-generic prior. This step is mandatory and self-reinforcing: **an incomplete brand study is a hard stop, not a warning.**
+
+Follow the harness 02-DOCS convention (brand study = wiki articles under `02-DOCS/wiki/brand/`, raw inputs under `02-DOCS/raw/brand/`, linked from root `CLAUDE.md`):
+
+1. **Locate the brand study.** Read the project root `CLAUDE.md` and look for a `## Brand & voice` section pointing into `02-DOCS/wiki/brand/...`. If present, read those articles.
+2. **If the link is MISSING, or the brand study is ABSENT or INCOMPLETE** (any checklist dimension empty), STOP. Do not design yet. Instead:
+   - Ask the user the targeted question script — **ONE focused batch at a time**, not a wall of questions — until every dimension in the completeness checklist is filled. (→ `references/brand-grounding.md`)
+   - Write/update the brand study into `02-DOCS/wiki/brand/` (and paste any raw inputs the user gives — screenshots, existing palettes, competitor lists — into `02-DOCS/raw/brand/`), following the wiki article format, and update `wiki/index.md` + `wiki/log.md`.
+   - Add/update a `## Brand & voice` section in the root `CLAUDE.md` linking to it (create `CLAUDE.md` if absent).
+3. **Only once the brand study exists and is sufficient, proceed** — and cite which brand articles drove which decisions in your output (e.g. "palette from `02-DOCS/wiki/brand/visual-identity.md`").
+
+The completeness checklist spans visual identity (OKLCH color system, type pairing & scale, logo, imagery/illustration mood, density, radius/shadow/motion personality), reference/inspiration sites the user loves, layout preferences, dark-mode stance, accessibility & performance constraints, and brand voice/positioning (so copy and design agree). Full checklist + exact question script → `references/brand-grounding.md`.
+
+The order is: **brand grounding → trend research → build.** If the brand study lacks aesthetic direction, or the user asks for "modern" / "2026" / "premium", run the research-first protocol (below) and fold current, cited findings into the output.
+
+## The non-negotiables
+
+These are constraints, not preferences. Violating any one is a defect, not a style choice.
+
+1. **Ground in the brand study before you design.** No `02-DOCS/wiki/brand/` study, or an incomplete one → STOP and complete it. (→ "Brand grounding" above, `references/brand-grounding.md`)
+2. **Research before you prescribe.** Run the research protocol; never ship from stale memory — your default taste skews AI-generic. Pull current 2026 trends with citations + dates. (→ `references/research-method.md`, `references/trends-2026.md`)
+3. **5-second value prop.** What it is, who it's for, and why it's better must be legible above the fold in 5 seconds.
+4. **One `<h1>` per page;** semantic landmarks (`header`/`nav`/`main`/`section`/`footer`).
+5. **Core Web Vitals are design constraints:** LCP < 2.5s, INP < 200ms, CLS < 0.1. (INP replaced FID in March 2024 — measure INP.)
+6. **WCAG 2.2 AA:** 4.5:1 text contrast (3:1 large text / UI), visible focus, `prefers-reduced-motion` honored. Target size: 24×24px is the AA floor (SC 2.5.8 Target Size (Minimum)); 44×44px is the recommended quality bar (Apple HIG / pointer comfort) — aim for 44, never ship below 24.
+7. **Design tokens, never magic numbers.** Tailwind v4 `@theme` → CSS vars.
+8. **Spacing on a 4/8px scale; type on a modular scale; color allocated 60-30-10.**
+9. **Motion must guide attention, communicate state, or preserve continuity** — else delete it.
+10. **Copy is benefit-led and specific.** No hype; the ban-list is enforced. (→ `references/copywriting-frameworks.md`)
+11. **Match the product domain.** Density and composition follow the audience and the job, not a template.
+12. **Commit to a visual concept and one signature element.** A page with no point of view defaults to AI-generic. Name the concept in one sentence; manufacture the ONE distinctive idea (not a gradient); force scale contrast and section rhythm; run the senior-designer crit before shipping. (→ "From competent to premium" below, `references/signature-and-craft.md`)
+
+## Decision rules (pick a direction first)
+
+Fill the direction brief before you write a single line of markup:
+
+```text
+DIRECTION BRIEF (fill before coding)
+1. Purpose .......... what job does this interface do, in one sentence?
+2. Audience ......... who repeats this workflow; what do they scan first?
+3. Tone ............. pick: utilitarian | editorial | playful | industrial | refined | technical | minimal | dense | calm
+4. Memorable detail . the ONE idea that makes it feel intentional (not a gradient)
+5. Constraints ...... framework, a11y, perf budget, existing design system/tokens
+```
+
+Then map the project type to composition, density, and motion budget:
+
+| Project type | Composition | Density | Motion budget |
+| --- | --- | --- | --- |
+| SaaS marketing | Full landing stack, hero→CTA | Generous | Tasteful reveals, hover affordances |
+| Dev tool | Show the product/CLI first, then proof | Medium | Subtle, fast (≤200ms) |
+| Dashboard / internal tool | Data-first, no hero | Dense, scannable | State-only (loading, success) |
+| Portfolio / editorial | Expressive, asymmetric | Airy | Expressive but reduced-motion-safe |
+| E-commerce | Product grid, fast PDP | Medium | Micro-interactions on add-to-cart |
+| Docs | Sidebar + reading column | Calm, 65ch measure | Near-zero |
+
+## Research-first protocol
+
+Trends churn quarterly and your built-in aesthetic prior is the median of every AI template ever scraped. Counter it with a loop:
+
+1. Define 2–3 reference archetypes from the DIRECTION BRIEF (e.g. "Linear-grade dev tool, dark, type-led").
+2. WebSearch award galleries and tier-1 product sites: `awwwards.com`, `godly.website`, `land-book.com`, `mobbin.com`, Refactoring UI, and the tier-1 sites (Linear, Stripe, Vercel, Cursor, Resend).
+3. WebFetch 3–5 exemplars, prompting each for type, color, layout, motion, and copy voice — concrete details, not adjectives.
+4. Extract a pattern table from what they share and where they differ.
+5. Synthesize a one-paragraph DESIGN DIRECTION with citations (which URL contributed what).
+6. Only THEN build; re-check the result against the references in QA.
+
+Re-research per project — trends churn, competitors moved, and the domain dictates the reference set. Do not rely on stale memory: whenever the brand study lacks aesthetic direction or the user asks for "modern" / "2026" / "premium", WebSearch/WebFetch current trends (award sites, Linear/Stripe/Vercel/Resend-tier, current type/color/motion/layout moves), fold the findings into the output **with citations + dates**, and refresh `references/trends-2026.md`. Full loop, source map, and synthesis template → `references/research-method.md`. Current snapshot (dated, cited) → `references/trends-2026.md`.
+
+## From competent to premium (the part that earns the score)
+
+Obeying every non-negotiable gets you to *competent* — a page that ships and passes review. It does NOT
+get you to premium, because every constraint catches an *absence* (no missing `<h1>`, contrast passes),
+while premium is a *presence*: a point of view. Competent-but-generic is the default failure mode of
+under-specified design output. Close it with four deliberate moves, in order, before and during the build:
+
+1. **Choose a visual concept.** One sentence the whole page answers to — `[feeling] + [structural metaphor]
+   for [audience doing job]` (e.g. "quiet instrument-panel precision for ops engineers"). Drawn from the
+   brand study + research exemplars, never your prior. If you cannot name what makes this surface different
+   from the median SaaS page, you have no concept yet, and the output will default to generic.
+2. **Manufacture the ONE signature element** the brief asks for — the thing you'd describe first to a
+   friend. Pick exactly one from a real vocabulary, biased by domain: a hero that *demonstrates not
+   describes* (live terminal / real chart / actual diff), an owned type moment, a structural signature
+   (asymmetric split, horizontal feature rail, editorial index), a material signature (hairline grid, one
+   grain pass, duotone), a motion signature, or a real-number/proof signature. Never default to "a
+   gradient". It must be true to the product, and cite the research exemplar that inspired it.
+3. **Force scale contrast.** Generic pages are tonally flat — headline, titles, body all within ~1.5×.
+   Make the hero dominant **3–5× the body**, demote eyebrows/labels/metadata smaller and quieter than
+   feels comfortable, and allow **one focal point per viewport**. If a section feels flat, add contrast,
+   not elements.
+4. **Give the page rhythm.** Ten identical `py-24` white card-grid sections read as one stripe. Vary
+   format (full-bleed vs. contained, alternate media sides), background (a dark section between light ones
+   anchors a CTA), density (a breathing statement after a dense grid), and container idiom (not everything
+   is a bordered card). Inter-section gap > intra-section gap, padding stepping on the scale.
+
+Then, **before claiming done, run the senior-designer crit** and make at least one concrete change as a
+result: What is the one idea here (name it in a sentence)? Would this place on Awwwards/Godly or just pass
+review? What is the single most generic element right now — and replace it. Where does the eye land first,
+and is that what should win? If the logo were removed, would anyone know whose product this is? Does every
+section earn its place, or is one there out of habit (cut it)?
+
+Full method — concept formula, signature vocabulary, scale/rhythm rules, the crit, and a worked
+generic→signature dev-tool hero — → `references/signature-and-craft.md`.
+
+## Visual system in 90 seconds
+
+Copy-pasteable foundation. Tokens once, consume everywhere.
+
+- Tailwind v4 `@theme` block (OKLCH): tokens become CSS vars and utilities automatically — no `tailwind.config.js`.
+- Type scale via `next/font` (one display + one text face) plus a fluid `clamp()` ladder.
+- Spacing, radius, and shadow are tokens too, never inline numbers.
+- The rule: arbitrary hex + random px = Bad; token references = Good.
+
+```css
+/* Good — Tailwind v4 @theme: OKLCH palette, tokens become CSS vars + utilities */
+@import "tailwindcss";
+@theme {
+  --color-bg:        oklch(0.99 0 0);
+  --color-fg:        oklch(0.21 0.01 256);
+  --color-muted:     oklch(0.55 0.01 256);
+  --color-brand-500: oklch(0.62 0.19 256);
+  --color-brand-600: oklch(0.55 0.19 256);
+  --font-display:    "Geist", ui-sans-serif, system-ui, sans-serif;
+  --font-text:       "Inter", ui-sans-serif, system-ui, sans-serif;
+  --radius-card:     0.875rem;
+  --shadow-card:     0 1px 2px oklch(0 0 0 / 0.06), 0 8px 24px oklch(0 0 0 / 0.08);
+  --ease-out:        cubic-bezier(0.22, 1, 0.36, 1);
+}
+```
+
+```html
+<!-- Bad — magic hex + arbitrary px, no system -->
+<div style="background:#5b54ff;border-radius:13px;padding:17px">…</div>
+<!-- Good — token-driven utilities -->
+<div class="bg-brand-500 rounded-card p-4">…</div>
+```
+
+Full token system, type scale, OKLCH ramp, bento, glass → `references/visual-system.md`.
+
+## Landing page build recipe ("the brutal landing")
+
+Each section has ONE job. Cut any section that has none.
+
+1. **Hero** — state the value prop; pass the 5s test.
+2. **Social-proof strip** — borrow credibility immediately (logos, a hard metric).
+3. **Problem / agitation** — name the pain in the reader's words.
+4. **Solution** — show the product doing the job.
+5. **Features → benefits (bento)** — translate each capability into an outcome.
+6. **Objection handling** — preempt the top reason they won't buy.
+7. **Pricing** — anchor, highlight one tier, default to annual.
+8. **FAQ** — answer the real blockers, not filler.
+9. **Final CTA** — one clear action, value on the button.
+10. **Footer** — navigation, legal, trust signals.
+
+```tsx
+// app/page.tsx — Server Component, LCP-safe hero (Next.js 15 / React 19)
+import Image from "next/image";
+
+export default function Page() {
+  return (
+    <main>
+      <section className="mx-auto max-w-5xl px-6 pt-24 text-center">
+        <h1 className="text-balance text-5xl font-semibold tracking-tight md:text-6xl">
+          Ship the change in an afternoon, not a sprint
+        </h1>
+        <p className="mx-auto mt-5 max-w-xl text-pretty text-lg text-fg/70">
+          Concrete benefit, who it is for, and why now — no hype.
+        </p>
+        <a
+          href="#start"
+          className="mt-8 inline-flex min-h-11 items-center rounded-card bg-brand-500 px-6 font-medium text-white transition-colors hover:bg-brand-600"
+        >
+          Start free
+        </a>
+        <Image
+          src="/hero.avif"
+          alt="Product dashboard showing a one-click deploy"
+          width={1200}
+          height={720}
+          priority
+          className="mt-16 rounded-card shadow-card"
+        />
+      </section>
+    </main>
+  );
+}
+```
+
+Full section-by-section anatomy, CTA cadence, pricing psychology, JSON-LD → `references/landing-anatomy-and-cro.md`.
+
+## Conversion copy in one pass
+
+- The 5s value-prop test: a stranger reads the hero and can say what it is, who it's for, why it's better.
+- Headline formula slots: outcome + timeframe; "X without Y"; the job-to-be-done.
+- Framework picker: PAS for pain-aware cold traffic; AIDA for broad / top-of-funnel; FAB/JTBD for feature → benefit translation.
+- CTA: put the value on the button ("Start free", "Get my estimate"), never "Submit".
+
+```text
+Bad  — "Revolutionize your workflow with our seamless platform"
+Good — "Deploy a fix in 4 minutes — no YAML, no on-call page"
+```
+
+Ban: `revolutionary` · `game-changer` · `cutting-edge` · "In today's landscape" · `unlock` · `seamless` · `elevate` · `supercharge` · bait questions · "not X, just Y" · forced lowercase · "Excited to share".
+
+Frameworks, value-prop canvas, Bad→Good rewrites, VOICE block → `references/copywriting-frameworks.md`.
+
+## Motion & interaction budget
+
+- Purposeful-only: motion must guide attention, communicate state, or preserve continuity.
+- Timing defaults: enter 200–350ms, exit ~150ms, press `scale(0.97)`.
+- Never `transition: all` — it animates layout props and janks.
+- Compositor-only properties: `transform`, `opacity`, `filter`.
+- `prefers-reduced-motion` is required, not optional.
+- Scroll-driven via native CSS `animation-timeline: view()` FIRST (no JS, no CLS) before any JS library.
+
+```css
+/* Good — native scroll-driven reveal, zero JS, explicit @supports fallback */
+.reveal { opacity: 1; } /* default visible: no scroll-timeline support => never hidden */
+@supports (animation-timeline: view()) {
+  @media (prefers-reduced-motion: no-preference) {
+    .reveal {
+      animation: reveal linear both;
+      animation-timeline: view();
+      animation-range: entry 0% cover 30%;
+    }
+  }
+}
+@keyframes reveal {
+  from { opacity: 0; translate: 0 16px; }
+  to   { opacity: 1; translate: 0 0; }
+}
+```
+
+Timing tokens, micro-interactions, scroll/parallax, when to escalate to motion/react → `references/motion-and-interaction.md`.
+
+## Premium details that compound
+
+Small things, applied consistently, are what reads as "designed".
+
+| Detail | Bad | Good |
+| --- | --- | --- |
+| Nested radius | Same radius parent + child | `outer = inner + padding` (concentric) |
+| Shadows | One hard `0 4px 8px #000` | Layered transparent OKLCH shadows |
+| Separation | Heavy drop shadow everywhere | Hairline 1px border first, shadow only for lift |
+| Headings | Ragged wrap | `text-wrap: balance` |
+| Body / captions | Orphan last word | `text-wrap: pretty` |
+| Numbers/prices | Width jitters | `font-variant-numeric: tabular-nums` |
+| Images | Edge blurs into bg | 1px neutral `outline`, `outline-offset: -1px` |
+| Glass | `backdrop-blur` on everything | Blur + 1px hairline + subtle noise, sparingly |
+
+```css
+html { -webkit-font-smoothing: antialiased; -moz-osx-font-smoothing: grayscale; }
+img  { outline: 1px solid oklch(0 0 0 / 0.1); outline-offset: -1px; }
+.price { font-variant-numeric: tabular-nums; }
+```
+
+Depth recipes, glass, noise, concentric math → `references/visual-system.md`.
+
+## Anti-patterns / rationalizations → STOP
+
+| Rationalization | Reality / Fix |
+| --- | --- |
+| "Purple→blue gradient on everything looks modern" | It reads AI-generic. Pick a domain-true palette; gradients are seasoning. |
+| "Centered text over an atmospheric gradient is a hero" | Show the product. Vague hero fails the 5s test. |
+| "Cards inside cards add structure" | They add noise. Flatten; use spacing + one border. |
+| "I know good design, I'll skip research" | Taste ≠ current trend. Re-research every project. |
+| "The image sells it, copy can be vague" | Copy carries the value prop. Pass the 5s test. |
+| "Animate everything on scroll" | CLS + INP cost. Reveal sparingly, transform/opacity only. |
+| "Ship now, check contrast later" | Contrast is a constraint, not polish. 4.5:1 or it ships broken. |
+| "Glass everywhere looks premium" | Glass on everything looks cheap. Reserve for floating surfaces. |
+| "`transition: all` is convenient" | It animates layout props → jank. List exact properties. |
+
+## Quick reference
+
+| Lever | Default | Token / where |
+| --- | --- | --- |
+| Type scale ratio | 1.25 | modular scale |
+| Body size | 16–18px | `--font-text` |
+| Line-height | 1.5 body / 1.1 display | per element |
+| Spacing base | 4 / 8px | Tailwind spacing |
+| Color allocation | 60-30-10 | bg / fg / brand |
+| Text contrast | ≥ 4.5:1 (3:1 large) | verify with checker |
+| Card radius | 0.875rem | `--radius-card` |
+| Touch target | 44×44px recommended; 24×24px AA floor (SC 2.5.8) | `min-h-11` |
+| Enter / exit motion | 250ms / 150ms | `--ease-out` |
+| LCP | < 2.5s | `next/image priority` |
+| INP | < 200ms | compositor-only motion |
+| CLS | < 0.1 | reserved space, `next/font` |
+| Hero | passes 5s test | value prop above fold |
+
+## Design-review QA checklist
+
+Run before claiming done. Same checks `scripts/verify.sh` falls back to.
+
+- [ ] Value prop legible in 5 seconds above the fold.
+- [ ] Text contrast ≥ 4.5:1 (3:1 for large text / UI).
+- [ ] Visible focus state on all interactive elements.
+- [ ] Touch targets 44×44px (recommended); never below the 24×24px WCAG 2.2 AA floor (SC 2.5.8).
+- [ ] `prefers-reduced-motion` honored.
+- [ ] Exactly one `<h1>` on the page.
+- [ ] Semantic landmarks present (`header`/`nav`/`main`/`section`/`footer`).
+- [ ] LCP image has `priority`.
+- [ ] Fonts use `next/font` (no CLS / FOUT swap shift).
+- [ ] No `transition: all` / `transition-all`.
+- [ ] Tokens used (no magic hex / px).
+- [ ] Ban-list words absent from copy.
+- [ ] Text fits at 360px and desktop without overflow.
+- [ ] Empty / loading / hover / error states designed.
+
+Automate → `scripts/verify.sh` (runs Lighthouse if a dev server is up, else static grep checks + this list).
+
+### Optional: graded visual-audit rubric (0–10)
+
+The checklist above is pass/fail. When the user asks for a *design review*, a *critique*, or a quality grade — or when you want to argue a surface is genuinely premium rather than merely compliant — score these 11 dimensions 0–10 and report the weighted total. Pass/fail tells you it ships; the rubric tells you how good it is.
+
+| # | Dimension | What a 10 looks like | Weight |
+| --- | --- | --- | --- |
+| 1 | First impression & value clarity | Passes the 5s test instantly; product shown, not a gradient | 1.5 |
+| 2 | Concept & signature | A nameable visual concept; one distinctive, domain-true signature element; logo-removed it's still recognizably this product, not a template | 1.5 |
+| 3 | Typographic craft | Modular scale, ≤2 families, balanced headings, 45–75ch measure, tabular numerals; deliberate 3–5× scale contrast | 1.0 |
+| 4 | Color & contrast | Disciplined 60-30-10 OKLCH system, all text ≥ 4.5:1, dark mode via token swap | 1.0 |
+| 5 | Layout, spacing & rhythm | Consistent 4/8px scale, intentional asymmetry/bento, clear focal point; sections vary in format/background/density, not one repeated stripe | 1.0 |
+| 6 | Hierarchy & scannability | Eye lands in the right order; one primary action per viewport | 1.0 |
+| 7 | Depth & detail polish | Concentric radius, layered shadows, hairline borders, restrained glass | 1.0 |
+| 8 | Motion quality | Purposeful only, compositor-only props, reduced-motion + `@supports` guards | 1.0 |
+| 9 | Accessibility | Landmarks, one `<h1>`, visible focus, 24px+ targets (44 ideal), no motion-only meaning | 1.0 |
+| 10 | Performance (CWV) | LCP < 2.5s, INP < 200ms, CLS < 0.1; LCP image `priority`, `next/font` | 1.0 |
+| 11 | Copy & brand fidelity | Benefit-led, specific, ban-list clean, voice matches the `02-DOCS/wiki/brand/` study | 0.5 |
+
+Score = Σ(dimension × weight), max 115 (normalize to /100 by ×100/115 if you want a percentage). **Bands (on the /115 raw total):** < 69 ships generic — redo; 69–91 competent but improvable — name the lowest two and fix; 92–108 premium; 109+ award-tier. (These are the prior 60/80/95-per-100 cutoffs rescaled to 115.) A surface that scores well on every constraint dimension but low on #1–2 is the classic "competent but generic" result — fix concept and signature first, it has the most leverage. For each dimension below 8, give one concrete, actionable fix (not "improve spacing" but "section padding jumps 48→96px with no 64px step — add `py-16` on mobile"). Cite the brand article or trend source that sets the bar where relevant.
+
+## Project grounding (02-DOCS + CLAUDE.md)
+
+This skill's 02-DOCS record has two parts, both indexed from a `## Knowledge map` section in
+the root `CLAUDE.md`:
+
+- The **brand study** at `02-DOCS/wiki/brand/` — a hard gate (see "Brand grounding" above): if
+  missing or incomplete, ask until complete before designing.
+- The **design-system decisions** at `02-DOCS/wiki/stack/design.md` — the chosen tokens
+  (color/OKLCH, type scale, spacing, radius, shadow, motion), the 2026 direction picked, and the
+  reference sites. Recorded, not gated.
+
+Create/update both as decisions are made and add/refresh their `CLAUDE.md` links (create the
+`## Knowledge map` section, and `CLAUDE.md` itself, if absent). Read them first on every use and
+keep outputs consistent with them.
+
+## See Also
+
+**Sibling skills in this repo** (these resolve to real skills you can invoke):
+
+- `../marketing/SKILL.md` — the WORDS: value prop, hero/section copy, microcopy, launch, and SEO-aware copy structure + keyword/intent capture. Co-owns the `02-DOCS/wiki/brand/` study (it owns the words dimensions; this skill owns the visual ones). Hand off deep keyword/SEO/GEO work here.
+- `../nextjs/SKILL.md` — the BUILD: App Router / React 19 stack implementation.
+- `../flutter/SKILL.md` — mirror the brand tokens into a Flutter app.
+- `../harness/SKILL.md` — the `02-DOCS` wiki protocol the brand study follows.
+
+**External / inspiration references** (NOT skills in this repo — names of well-known craft references and external skill ecosystems, cited for direction, not invocable here):
+
+- *frontend-design-direction* — product-domain design direction (e.g. dense internal tools vs sales pages); fold its judgment in via the DIRECTION BRIEF rather than expecting a sibling skill.
+- *make-interfaces-feel-better* — polish-pass micro-detail thinking; this skill's "Premium details that compound" table covers the same ground in-repo.
+- *motion-ui* / *motion-foundations* — deep motion-code mechanics (spring config, `AnimatePresence` internals, layout animations); this skill sets motion *intent + budget* and defers mechanics outward.
+- *product-lens* — validating the "why" before you build.
+- *liquid-glass-design* — native iOS 26 Liquid Glass material (this skill ships the *web* glass approximation only).
+
+- References (in this skill): `references/brand-grounding.md`, `references/research-method.md`, `references/trends-2026.md`, `references/signature-and-craft.md`, `references/visual-system.md`, `references/landing-anatomy-and-cro.md`, `references/copywriting-frameworks.md`, `references/motion-and-interaction.md`.

package/skills/design/evals/README.md

@@ -0,0 +1,53 @@
+# Eval harness — `design` skill
+
+This is an **agent-run** eval, not a shell script. The cases in `cases.yaml` are fed to a
+Claude Code agent and graded by inspection. There is no `pytest` to run; the "harness" is the
+procedure below plus a human (or a judge agent) checking outputs against the rubrics.
+
+## What's under test
+
+1. **Triggering** — does the `design` skill activate on the right prompts and stay quiet on
+   near-misses that belong to a sibling (`marketing`, `nextjs`, `flutter`) or to nothing in-repo?
+2. **Capability** — when it does fire, does the guidance measurably beat an unguided answer?
+
+## A. Triggering accuracy
+
+For each prompt in `should_trigger` and `should_not_trigger`:
+
+1. Start a fresh agent session with **only the `design` skill discoverable** (its `SKILL.md`
+   description in the system prompt / skill index). Do not pre-load sibling skills.
+2. Paste the prompt verbatim as the user's first message.
+3. Observe whether the agent **invokes/loads the `design` skill** (announces it, reads
+   `SKILL.md`, or applies its protocol) before answering.
+4. Run **3–5 independent trials per prompt** (fresh session each) to average out sampling noise.
+
+Scoring per prompt:
+- `should_trigger` → PASS if the skill fires in the **majority** of trials.
+- `should_not_trigger` → PASS if the skill **does not** fire in the majority of trials. Bonus:
+  the agent routes to the `route_to` target (or correctly declines when `route_to: none`).
+
+**Pass bar:** >= 90% trigger accuracy across all prompts (true-positives + true-negatives over
+total). Any `should_not_trigger` that fires in a majority of trials is a hard fail to fix in the
+`SKILL.md` description/When-NOT section, even if the aggregate clears 90%.
+
+## B. Capability uplift (with vs without)
+
+For each `capability` scenario:
+
+1. **Without:** fresh session, skill NOT available, give the scenario prompt. Save the answer.
+2. **With:** fresh session, `design` skill available and applied, same prompt. Save the answer.
+3. Grade both against the scenario's `must_include` points — one point per item, mark
+   covered / not covered. Use a second agent as judge or grade by hand.
+4. Compute coverage = covered / total `must_include`, for each condition.
+
+**Pass bar:** WITH the skill covers **>= 80%** of `must_include`; WITHOUT it covers materially
+less (target a >= 30-point absolute gap). If the gap is small, the skill isn't earning its place —
+fix the skill, not the rubric. The brand-grounding STOP and the research-first/CWV/WCAG points are
+the high-signal items most likely to be missing without the skill; weight attention there.
+
+## Notes / honesty
+
+- Triggering is inherently stochastic; that's why we average trials and report a percentage, not a
+  binary. Re-run if results straddle the bar.
+- Keep grading faithful to `SKILL.md` — if a case drifts from the actual description, fix the case.
+- These files document intent and a repeatable procedure; they are **not** wired into CI.

package/skills/design/evals/cases.yaml

@@ -0,0 +1,56 @@
+skill: design
+
+should_trigger:
+  - prompt: "Design a landing page for our new analytics SaaS — hero, pricing, the works."
+    why: "Explicit landing-page design with full marketing-page composition; this is the skill's core use case."
+  - prompt: "Our homepage looks generic, like every other AI-generated startup site. Can you make it feel premium and intentional?"
+    why: "Rescuing a 'feels generic / AI-slop' UI is named verbatim in the description and the When-to-use list."
+  - prompt: "Pick a color palette and type pairing for my product, and give me the Tailwind tokens."
+    why: "Choosing a visual system (color, type, tokens) is an explicit trigger; the skill ships Tailwind v4 @theme OKLCH tokens."
+  - prompt: "Can you do a design review of this hero section and tell me how to make it convert better?"
+    why: "Design review / critique plus conversion intent; the skill has a dedicated design-review QA checklist and a 0-10 visual-audit rubric."
+  - prompt: "I've got the React components built and working, but it all just looks flat and amateur — help me polish the visuals and spacing."
+    why: "A polish pass on an existing surface; user names the symptom (flat/amateur) without naming a tool, which the skill targets ('make an interface feel premium')."
+  - prompt: "Write the hero headline and a punchy value prop for our developer-tool site, and lay out the page so it sells."
+    why: "Conversion copy (hero/value-prop) plus page layout for selling — the skill owns visual + landing structure and co-owns copy; non-obvious because it leads with copy."
+  - prompt: "Add a bento-grid features section to our marketing site that doesn't look like a template."
+    why: "'bento section' is an explicit named trigger; involves layout/composition for a marketing surface."
+
+should_not_trigger:
+  - prompt: "Write the SEO keyword strategy and do a technical SEO audit for our marketing site, targeting buyer-intent terms."
+    route_to: "marketing"
+    why: "Deep keyword research, GEO, and technical SEO audits are explicitly delegated to the marketing sibling; design only enforces SEO-aware markup structure."
+  - prompt: "Set up the Next.js 15 App Router routing, server actions, and data fetching for these pages."
+    route_to: "nextjs"
+    why: "Pure App Router / React 19 build mechanics are the nextjs sibling's job; design hands off the build."
+  - prompt: "Build a daily-use internal ops dashboard for our support team to triage tickets fast — pure data tables, no marketing."
+    route_to: "none"
+    why: "Dense internal operational tooling is explicitly a do-NOT-force-a-landing case; the skill says not to paint a marketing skin on a daily-use tool. Routes to product judgment, not a sibling."
+  - prompt: "Mirror our brand colors and typography into the Flutter mobile app's theme."
+    route_to: "flutter"
+    why: "Translating brand tokens into a Flutter app is the flutter sibling's job, not web UI design."
+  - prompt: "Implement an iOS 26 SwiftUI Liquid Glass material for this native settings panel."
+    route_to: "none"
+    why: "Native iOS Liquid Glass is the external liquid-glass-design reference; this skill ships only the web glass approximation, so it should decline/defer (no in-repo sibling)."
+  - prompt: "Help me wire up the spring physics and AnimatePresence layout animations for this modal in Framer Motion."
+    route_to: "none"
+    why: "Deep motion-code mechanics (springs, AnimatePresence internals) are explicitly deferred to the external motion-ui references; design only sets motion intent + budget."
+
+capability:
+  - scenario: "User asks: 'Design the hero section for our new SaaS landing page and make it look premium.' (No 02-DOCS/wiki/brand/ study exists in the repo yet.)"
+    must_include:
+      - "STOPS before designing and checks for a brand study at 02-DOCS/wiki/brand/ (via root CLAUDE.md ## Brand & voice); on finding it missing/incomplete, asks a focused batch of brand-grounding questions instead of guessing."
+      - "Runs (or states it will run) the research-first protocol: WebSearch award galleries / tier-1 sites and synthesize a cited DESIGN DIRECTION before prescribing, rather than shipping from memory."
+      - "Enforces the 5-second value-prop test: hero states what it is, who it's for, why it's better, above the fold — and shows the product, not a centered headline over an atmospheric gradient."
+      - "Uses design tokens (Tailwind v4 @theme, OKLCH color, modular type scale, 4/8px spacing, radius/shadow tokens) — no magic hex or arbitrary px."
+      - "Treats accessibility as a hard constraint: text contrast >= 4.5:1, visible focus, one <h1>, semantic landmarks, touch targets >= 24px (44px ideal)."
+      - "Treats Core Web Vitals as design constraints: LCP < 2.5s with next/image priority on the hero image, INP < 200ms, CLS < 0.1, next/font."
+      - "Benefit-led, specific copy that avoids the ban-list (revolutionary, seamless, game-changer, unlock, supercharge, elevate, etc.)."
+  - scenario: "User asks: 'Here's our current pricing page — do a design review and tell me how good it actually is.'"
+    must_include:
+      - "Applies the design-review QA checklist (value prop in 5s, contrast >= 4.5:1, visible focus, one <h1>, semantic landmarks, LCP image priority, next/font, no transition: all, tokens not magic numbers, ban-list-clean copy, 360px fit, empty/loading/error states)."
+      - "Scores the 10-dimension visual-audit rubric 0-10 with weights and reports a weighted total out of 100, mapped to a band (<60 generic / 60-79 competent / 80-94 premium / 95+ award-tier)."
+      - "For each dimension scoring below 8, gives a concrete actionable fix (e.g. exact spacing/token change), not a vague 'improve spacing'."
+      - "Checks copy against the ban-list and flags hype/vague value props that fail the 5s test."
+      - "Flags any transition: all, magic hex/px, cards-in-cards, or purple->blue everything gradient as defects, not preferences."
+      - "Ties findings back to the brand study / cited trend source where the bar is set, rather than asserting taste."