@thedecipherist/claude-packs 0.0.0-stage → 1.0.0

package/packs/web/checks/rcss-no-100vw.json

@@ -0,0 +1,21 @@
+{
+  "id": "rcss-no-100vw",
+  "why": "100vw includes the scrollbar, so a 100vw box overflows sideways on every desktop browser. width: 100%.",
+  "rule": ".claude/rules/styles-live-in-stylesheets.md",
+  "concepts": [
+    "styles"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    "**/out/**",
+    ".claude/**",
+    "**/.claude/**"
+  ],
+  "code": false,
+  "pattern": "\\b100vw\\b",
+  "bad": ".hero { width: 100vw; }",
+  "good": ".hero { width: 100%; }"
+}

package/packs/web/checks/rcss-no-fixed-wide-width.json

@@ -0,0 +1,21 @@
+{
+  "id": "rcss-no-fixed-wide-width",
+  "why": "A fixed width of 500px or more is wider than a phone; the layout scrolls sideways. max-width, %, or min(800px, 100%).",
+  "rule": ".claude/rules/styles-live-in-stylesheets.md",
+  "concepts": [
+    "styles"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    "**/out/**",
+    ".claude/**",
+    "**/.claude/**"
+  ],
+  "code": false,
+  "pattern": "(?<![\\w-])(?:min-)?width\\s*:\\s*(?:[5-9]\\d{2}|\\d{4,})px",
+  "bad": ".card { width: 640px; }",
+  "good": ".card { max-width: 640px; width: min(640px, 100%); }"
+}

package/packs/web/checks/rcss-viewport-meta.json

@@ -0,0 +1,28 @@
+{
+  "id": "rcss-viewport-meta",
+  "why": "Without the viewport meta the page renders at 980px and is zoomed out on every phone. Next's app router emits it; a hand-written document must.",
+  "rule": ".claude/rules/styles-live-in-stylesheets.md",
+  "globs": [
+    "**/index.html",
+    "**/_document.tsx",
+    "**/root.tsx",
+    "**/app.html"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    "**/out/**",
+    ".claude/**",
+    "**/.claude/**"
+  ],
+  "code": false,
+  "mode": "needs",
+  "pattern": "<html\\b",
+  "needs": [
+    "width=device-width"
+  ],
+  "bad": "<html lang=\"en\"><head><title>x</title></head></html>",
+  "good": "<html lang=\"en\"><head><meta name=\"viewport\" content=\"width=device-width, initial-scale=1\" /></head></html>"
+}

package/packs/web/checks/secret-not-in-web-storage.json

@@ -0,0 +1,25 @@
+{
+  "id": "secret-not-in-web-storage",
+  "why": "The key that makes the privacy claim true should not be readable by every third-party script on the page.",
+  "rule": ".claude/rules/secrets-not-in-the-browser.md",
+  "globs": [
+    "**/*.tsx",
+    "**/*.jsx",
+    "**/client/**/*.ts"
+  ],
+  "exclude": [
+    "**/tests/**",
+    "**/test/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/e2e/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**"
+  ],
+  "code": true,
+  "pattern": "(?:local|session)Storage\\.setItem\\([^,\\n]+,\\s*\\w*(?:[kK]ey(?:Input)?|[tT]oken|[sS]ecret|[pP]assword)\\w*\\s*\\)",
+  "bad": "localStorage.setItem(STORAGE_KEY, keyInput);",
+  "good": "localStorage.setItem(THEME_KEY, theme);"
+}

package/packs/web/checks/tw-no-raw-hex-in-markup.json

@@ -0,0 +1,34 @@
+{
+  "id": "tw-no-raw-hex-in-markup",
+  "why": "A hex colour in a page or component is a value outside the token system; it drifts and has no dark: pair. Declare it once in @theme and use the utility.",
+  "rule": ".claude/rules/ui-primitives-one-module.md",
+  "globs": [
+    "**/*.tsx",
+    "**/*.jsx"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    "**/out/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/test/**",
+    "**/tests/**",
+    "**/*.stories.*",
+    "**/tokens*",
+    "**/theme*",
+    "**/components/ui/**",
+    "**/email/**",
+    "**/emails/**",
+    "**/mail/**"
+  ],
+  "code": false,
+  "pattern": "#[0-9a-fA-F]{6}\\b",
+  "bad": "<div className=\"bg-[#1f2937]\">",
+  "good": "<div className=\"bg-surface-2\">",
+  "kind": "quality"
+}

package/packs/web/checks/wp-hero-not-lazy.json

@@ -0,0 +1,27 @@
+{
+  "id": "wp-hero-not-lazy",
+  "why": "loading=\"lazy\" or fetchpriority=\"low\" on the hero delays the very element LCP measures. Preload it and mark it fetchpriority=\"high\".",
+  "rule": ".claude/rules/web-performance.md",
+  "concepts": [
+    "markup"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    "**/out/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/test/**",
+    "**/tests/**",
+    "**/*.stories.*"
+  ],
+  "code": false,
+  "flags": "i",
+  "pattern": "fetchpriority=.?low[^>]*hero|hero[^>]*loading=.?lazy",
+  "bad": "<img class=\"hero\" src=\"/hero.avif\" loading=\"lazy\">",
+  "good": "<img class=\"hero\" src=\"/hero.avif\" fetchpriority=\"high\" width=\"1600\" height=\"900\" alt=\"\u2026\">"
+}

package/packs/web/checks/wp-img-needs-dimensions.json

@@ -0,0 +1,26 @@
+{
+  "id": "wp-img-needs-dimensions",
+  "why": "An <img> without width and height reserves no box, so the layout shifts when it arrives (CLS). Give it intrinsic dimensions; the stylesheet keeps it fluid with max-width: 100%; height: auto.",
+  "rule": ".claude/rules/web-performance.md",
+  "concepts": [
+    "markup"
+  ],
+  "exclude": [
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**",
+    "**/out/**",
+    ".claude/**",
+    "**/.claude/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/test/**",
+    "**/tests/**",
+    "**/*.stories.*"
+  ],
+  "code": false,
+  "pattern": "<img\\b(?![^>]*\\bwidth\\s*=)[^>]*>",
+  "bad": "<img src=\"/a.png\" alt=\"a\">",
+  "good": "<img src=\"/a.png\" alt=\"a\" width=\"320\" height=\"200\">"
+}

package/packs/web/pack.json

@@ -0,0 +1,73 @@
+{
+  "name": "web",
+  "version": "1.0.0",
+  "description": "Web UI (Next.js, HTML, CSS, Tailwind 4): accessibility, one primitives module, styles in stylesheets, performance, production build, client boundaries.",
+  "type": "stock",
+  "author": "claude-packs",
+  "license": "MIT",
+  "homepage": "https://github.com/TheDecipherist/claude-packs",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/TheDecipherist/claude-packs.git",
+    "directory": "packs/web"
+  },
+  "keywords": [
+    "nextjs",
+    "react",
+    "css"
+  ],
+  "engines": {
+    "claude-packs": ">=0.19.0"
+  },
+  "folders": {},
+  "concepts": {
+    "markup": [
+      "**/*.tsx",
+      "**/*.jsx",
+      "**/*.html",
+      "**/*.vue",
+      "**/*.svelte"
+    ],
+    "styles": [
+      "**/*.css",
+      "**/*.scss",
+      "**/styles/**",
+      "**/tailwind.config.*",
+      "**/postcss.config.*"
+    ],
+    "pages": [
+      "**/app/**/page.tsx",
+      "**/app/**/layout.tsx",
+      "**/app/**/template.tsx",
+      "**/pages/**/*.tsx",
+      "**/pages/**/*.jsx",
+      "**/routes/**/*.tsx"
+    ],
+    "components": [
+      "**/components/**",
+      "**/client/**"
+    ],
+    "client": [
+      "**/app/**",
+      "**/components/**",
+      "**/client/**",
+      "**/public/**",
+      "**/*.tsx",
+      "**/*.jsx"
+    ],
+    "build-config": [
+      "**/next.config.*",
+      "**/webpack*.js",
+      "**/webpack*.mjs",
+      "**/webpack*.cjs",
+      "**/webpack*.ts",
+      "**/rollup.config.*",
+      "**/esbuild*.js",
+      "**/esbuild*.mjs",
+      "**/index.html",
+      "**/_document.tsx"
+    ]
+  },
+  "skillsIn": null,
+  "hooks": {}
+}

package/packs/web/rules/accessibility.md

@@ -0,0 +1,26 @@
+---
+# concepts: markup, styles
+paths:
+  - "placeholder"
+---
+
+# Accessibility is built in with the right element, never bolted on
+
+Most of it costs nothing if the right element is used from the start. The defaults that break screen readers and keyboards (clickable divs, missing labels, removed focus rings) are expensive to retrofit.
+
+<constraints>
+Always do:
+- The native element: `<button>` for actions, `<a href>` for navigation, `<nav>`, `<ul>`, `<label>`, `<input>`, `<dialog>` with `showModal()`. ARIA only when no native element does the job; bad ARIA is worse than none.
+- An accessible name on every interactive thing: descriptive `alt` (or `alt=""` for decorative, never omitted: that reads the filename); a real `<label>` tied to each field (a placeholder is not a label); `aria-label` on icon-only buttons.
+- Keyboard: `:focus-visible` styles that replace, never remove, the focus ring; focus moved to the new view's heading on route change and into a modal on open.
+- Structure: one `<h1>`, then `<h2>`/`<h3>` in order (never skipped for size); landmarks `<header>`, `<nav>`, one `<main>`, `<footer>`, a skip-to-content link; `<section>` only with a heading.
+- Contrast 4.5:1 (3:1 large text), meaning never by colour alone, zoom never disabled, `prefers-reduced-motion` respected, dynamic changes announced with `aria-live`.
+- Vendor stylesheets (editors, pickers, charts): force `svg, svg * { fill: currentColor; stroke: currentColor }` inside the wrapper, and verify the surface **rendered, in both colour schemes**: the colour is in node_modules, not in your markup.
+- Contrast is verified rendered (both schemes) by a Playwright check, never by grepping colour classes: a grep passes cleanly in exactly the failing case.
+
+Never do:
+- `<div onClick>` / `<span onClick>` (`a11y-no-clickable-div`): not focusable, no Enter/Space, announced as nothing.
+- `tabindex` above 0 (`a11y-no-positive-tabindex`): it hijacks the tab order.
+- `outline: none` or `outline: 0` (`a11y-no-bare-outline-none`) without a `:focus-visible` replacement in the same rule.
+- `<img>` without `alt` (`a11y-img-needs-alt`).
+</constraints>

package/packs/web/rules/client-boundaries.md

@@ -0,0 +1,23 @@
+---
+# concepts: client
+paths:
+  - "placeholder"
+---
+
+# The client bundle holds no server code, no secrets, and navigates only through the router
+
+<constraints>
+Always do:
+- Server-only code (the gateway, env, anything with a secret) reaches a `'use client'` component only through a server component's props, a route handler or a server action; `import type` from a server module is the one allowed import, and only under `verbatimModuleSyntax: true`.
+- Browser globals (`window`, `document`, `localStorage`, `navigator`) inside effects, event handlers or behind `typeof window !== 'undefined'`; never at module scope, where the server render evaluates them.
+- Internal navigation through the router (`<Link>`, `router.push`), so SPA state, prefetching and transitions survive. `window.location` only for external URLs and file downloads, marked `// allow location nav` on the line.
+- Hydration data is initial-only: every client-side navigation target has its own data path (a route handler or server component fetch), or it renders stale or blank.
+- Loader/props payloads are a projection shaped to what the component renders, never the service's full result: SSR embeds the data twice (HTML + hydration JSON).
+- Verify once per feature that the client build contains no connection string, collection name or server env key.
+
+Never do:
+- A value import from `/server/`, `/db/`, `gateway`, `.server` in a `'use client'` file (`client-no-server-import`).
+- `const x = window.…` / `document.…` at module scope (`client-no-browser-global-at-module-scope`).
+- `window.location.href = '/…'`, `.assign`, `.replace`, `.reload` for an internal route (`client-no-window-location-nav`).
+- An API key or `MONGODB_URI` anywhere under `app/`, `components/`, `client/`, `public/` (`client-no-api-key`).
+</constraints>

package/packs/web/rules/production-build.md

@@ -0,0 +1,22 @@
+---
+# concepts: build-config, markup, styles
+paths:
+  - "placeholder"
+---
+
+# The production build serves from its own origin, hashed, minified, and runs once at the end
+
+<constraints>
+Always do:
+- Development iterates on the dev server with hot reload; the **first** production build of a feature happens at final verification, against a freshly built and restarted prod app, because a class of bugs exists only there (CSP blocking an inline script, Secure cookies, static middleware serving the raw index, cache staleness).
+- Fonts downloaded into the repo and served from the app's origin: `next/font` or `@fontsource`, woff2 only, `font-display: swap`, one critical face preloaded, old `preconnect` hints deleted.
+- Runtime JS/CSS bundled or vendored; never a CDN `<script>`/`<link>` in a production page.
+- Hashed filenames for every cacheable asset; CSS extracted to files, never injected by JS; chunks that always load together are one chunk; a `performance` budget that fails the build on regression.
+- Modular imports (`lodash/merge`, not `lodash`); the bundle analyzer run when a heavy dependency is added.
+- `preflight-build` before any deploy: it audits the **emitted** output (request count, third-party origins, hashing, size), not the config.
+
+Never do:
+- `fonts.googleapis.com`, `fonts.gstatic.com`, typekit, fontawesome CDN, bunny (`prodbuild-no-remote-fonts`).
+- `unpkg`, `jsdelivr`, `cdnjs` in a shipped page (`prodbuild-no-cdn-runtime-deps`).
+- `minify: false`, `mode: 'development'`, `productionBrowserSourceMaps: true` in the shipped config (`prodbuild-no-dev-flags`).
+</constraints>

package/packs/web/rules/secrets-not-in-the-browser.md

@@ -0,0 +1,18 @@
+---
+paths:
+  - "**/*.tsx"
+  - "**/*.jsx"
+---
+
+# Long-lived secrets stay out of browser storage
+
+<constraints>
+Always do:
+- Keep sessions in `HttpOnly` cookies.
+
+Never do:
+- Put a refresh token or an API key in `localStorage`.
+</constraints>
+
+## Check
+`secret-not-in-web-storage`.

package/packs/web/rules/styles-live-in-stylesheets.md

@@ -0,0 +1,23 @@
+---
+# concepts: markup, styles
+paths:
+  - "placeholder"
+---
+
+# Styles live in stylesheets, mobile-first, and every clickable thing shows a pointer
+
+<constraints>
+Always do:
+- CSS in `.css` files (or CSS Modules / Tailwind utilities), linked and cached. Runtime values go in as a custom property (`style="--progress: 73%"`) consumed by the stylesheet; only the value is inline.
+- `<meta name="viewport" content="width=device-width, initial-scale=1">` on every document that is not Next's app router (which emits it); `html { -webkit-text-size-adjust: 100% }`.
+- Mobile-first: base styles small, `@media (min-width: …)` to enhance up. `box-sizing: border-box` globally.
+- `min-width: 0` on flex and grid children (the fix for most mysterious horizontal scroll). `pre { overflow-x: auto; max-width: 100% }`, prose `overflow-wrap: break-word`.
+- Fluid type with `clamp()`; `max-width`, `%` or `min(800px, 100%)` instead of fixed pixel widths; `width: 100%` never `100vw` (it includes the scrollbar); `img, video, svg { max-width: 100%; height: auto }` with intrinsic `width`/`height` on every `<img>`.
+- iOS: `overscroll-behavior: contain` on scroll regions, `100dvh` not `100vh`, `font-size: 16px` on inputs (no focus zoom), pinch-zoom never disabled.
+- `cursor: pointer` on everything clickable, in the base stylesheet: `button, [role="button"], [role="link"], [onclick] { cursor: pointer }`, `button:disabled { cursor: not-allowed }`. Buttons do not get it from the browser. The inverse holds: pointer on something inert is a lie.
+
+Never do:
+- `style="…"` attributes or large `style={{…}}` objects in markup (`css-no-inline-style`): they cannot be responsive, hover or animate, and start a specificity war. A single `<style>` block is fine only in a single-file deliverable; email HTML is the one case that requires inline.
+- `100vw` (`rcss-no-100vw`); `width`/`min-width` of 500px or more (`rcss-no-fixed-wide-width`).
+- A CSS reset that sets `button { cursor: default }` (several popular ones do).
+</constraints>

package/packs/web/rules/tailwind-v4.md

@@ -0,0 +1,23 @@
+---
+# concepts: styles
+paths:
+  - "placeholder"
+---
+
+# Tailwind 4: borders default to currentColor, unlayered CSS beats utilities, tokens live in @theme
+
+Training-data idiom is v3. Three v4 differences shipped real visual bugs while every DOM test stayed green.
+
+<constraints>
+Always do:
+- Restore a neutral border default once, in the global stylesheet: `@layer base { *, ::after, ::before, ::backdrop, ::file-selector-button { border-color: var(--color-slate-200, #e2e8f0); } }`. Load-bearing surfaces still name their colour (`border-slate-200 dark:border-slate-700`): a bare `border`/`divide-*` draws near-black in v4.
+- Custom component CSS goes in `@layer components` (or base). Unlayered author CSS beats **every** utility regardless of order or specificity; a hand-written `.app-top-bar { padding-top: … }` silently zeroes `pt-14` on the same element.
+- One owner per property per element: fold the utility's value into the custom class or drop the class; never split one box's property between the two.
+- Tokens (palette, fonts, radii) declared once in `@theme` so utilities exist for them. A raw hex in a page or component is the drift the schema rule kills in data (`tw-no-raw-hex-in-markup`).
+- Fonts are self-hosted: `next/font` or `@fontsource`, family registered in `@theme --font-sans`; prove it with a computed-style assert, the import alone proves nothing.
+- Dark mode is one decision (`prefers-color-scheme` via `dark:` or a class toggle), recorded in the global stylesheet header; every surface that sets a light colour pairs its `dark:` value in the same edit.
+
+Never do:
+- Unlayered CSS that touches a property a utility also sets on that element.
+- Remote font hosts (`prodbuild-no-remote-fonts`).
+</constraints>

package/packs/web/rules/ui-primitives-one-module.md

@@ -0,0 +1,30 @@
+---
+# concepts: pages, components
+paths:
+  - "placeholder"
+---
+
+# One UI primitives module; pages compose it and never hand-roll a control
+
+People judge the product by its UI first: a styled, consistent surface makes everything else credible; an unstyled one gets no second look. The structural fix is the same as the schemas module and the database gateway: exactly one place where raw controls are styled.
+
+<constraints>
+Always do:
+- One pinned primitives module (`src/components/ui/`): Button, Field (label + input/select with the shared field styling), Card, PageHeader, EmptyState, Modal/Sheet, and whatever the spec's component inventory names. Its barrel carries the header contract:
+  ```ts
+  // UI PRIMITIVES: the ONLY place raw controls are styled. Pages compose these; never a bare
+  // button/input/select with ad-hoc classes. Tokens come from @theme. New primitive => new file here.
+  // Rule: ui-primitives-one-module.
+  ```
+- The primitives module ships in the **first** wave of any web build, before any page.
+- Every page states its layout skeleton (container width, page header, section order, where the primary action sits) in its doc; two pages with the same kind of content use the same skeleton.
+- One primary action per view, visually dominant; destructive actions in the red family and never adjacent-identical to safe ones; secondary actions quiet.
+- Every list surface designs its empty state (first login **is** the demo); every async surface designs loading and error. `EmptyState` is a primitive so the designed version is one import away.
+- Colour, spacing and type come from tokens; both colour schemes are first-class.
+- When `design/` holds approved reference images, surfaces are built to match them; kit rules (contrast, a11y, self-hosted fonts) win over the image and the deviation is recorded.
+
+Never do:
+- `<button>`, `<input>`, `<select>`, `<textarea>` in a page or feature component (`ds-pages-compose-primitives`).
+- A raw hex colour in a page or component (`tw-no-raw-hex-in-markup`).
+- Ship a surface with zero styling classes: it is an automatic blocker in `design-review`.
+</constraints>

package/packs/web/rules/web-performance.md

@@ -0,0 +1,21 @@
+---
+# concepts: markup, pages
+paths:
+  - "placeholder"
+---
+
+# Performance is decided up front: first paint first, everything else deferred
+
+<constraints>
+Always do:
+- Split: critical (above the fold) in the initial HTML with inlined critical CSS, the LCP image preloaded with `fetchpriority="high"`, one critical font preloaded. Everything else deferred: `loading="lazy"` on below-fold images and iframes, `defer`/`async` scripts, dynamic imports for offscreen components, analytics late.
+- Reserve space: `width` and `height` on every image (`wp-img-needs-dimensions`), `aspect-ratio` for backgrounds, `font-display` with a size-adjusted fallback. CLS is mostly "the space was not reserved".
+- Images as WebP/AVIF through `<picture>` (or `next/image`), with `srcset` + `sizes`; vector stays SVG; animated GIFs become video; a full-resolution PNG hero is the most common single perf bug.
+- Fonts self-hosted, subset, two weights not four.
+- Less JavaScript: built-ins and small deps, route-level code splitting, nothing blocking first paint or interaction on analytics.
+- A Core Web Vitals budget (LCP, CLS, INP) set at the start; Lighthouse for the lab number, field data for the truth.
+
+Never do:
+- `loading="lazy"` or `fetchpriority="low"` on the hero/LCP element (`wp-hero-not-lazy`).
+- A `<script>` in `<head>` without `defer`.
+</constraints>

package/packs/web/skills/design-direction/SKILL.md

@@ -0,0 +1,30 @@
+---
+name: design-direction
+description: Use when a feature, page or app gets a user-facing surface and no Design Direction exists yet for it, or when a restyle is asked for. Produces the plan (tokens, type roles, layout, signature element) that the code is then derived from.
+---
+
+# design-direction
+
+One thing: write the `## Design Direction` section **before** any UI code, so the look is decided once and every colour and type choice in the build derives from it. Accessibility floors (`accessibility` rule) and the primitives module (`ui-primitives-one-module`) are the frame it works inside; `design-review` judges the rendered result against it.
+
+<constraints>
+Always do:
+1. Ground it: name the one concrete subject, its audience and the page's single job. If the brief leaves it open, pick and state the choice.
+2. Brainstorm a compact plan:
+   - **Colour**: 4 to 6 named tokens (surface, text, accent, per-domain colours), each with its dark-scheme pair. They go to `@theme`, nowhere else.
+   - **Type**: a characterful display face used with restraint, a complementary body face, a utility face for data if needed; a scale with intentional weights and spacing. Self-hosted.
+   - **Layout**: the concept in one sentence plus an ASCII wireframe; the page skeleton (container width, page header, section order, where the primary action sits).
+   - **Signature**: the single element this page will be remembered by. Spend the boldness there and keep everything around it quiet.
+   - **Risk**: one line on the risk taken.
+3. Critique the plan before building: anything that reads like the generic default for this kind of prompt gets revised, with what changed and why. The three defaults to avoid: warm cream + high-contrast serif + terracotta; near-black + one acid accent; the purple-gradient SaaS page with Inter everywhere and a card for everything.
+4. Review the plan against the brief before building: work through a similar prompt, and anything you would have arrived at anyway is a default, not a choice. `no-generated-look` lists them when the `ui-craft` pack is here. The brief's own words and a project's design system always win.
+5. Write it into the feature doc as `## Design Direction`. The build derives from it; `design-review` checks against it.
+6. Words are design material: controls say what happens ("Save changes", not "Submit"), the name survives the whole flow ("Publish" → "Published"), errors say what went wrong and how to fix it, empty states invite the first action. Sentence case, plain verbs, no filler.
+
+Never do:
+- Write UI code before the section exists.
+- Scatter motion: one orchestrated moment beats many effects, and all of it respects `prefers-reduced-motion`.
+- Let the direction override an accessibility floor; it works inside them.
+</constraints>
+
+Put the choice through a question only when the brief genuinely supports two directions; otherwise decide and show it.

package/packs/web/skills/design-review/SKILL.md

@@ -0,0 +1,28 @@
+---
+name: design-review
+description: Use when a screen, component, mockup or stylesheet is ready for feedback, when a build reaches its verification phase with a browser surface, or when asked to critique layout, typography, colour, contrast or UX. Reviews rendered screenshots, never markup alone.
+---
+
+# design-review
+
+One thing: judge the rendered UI, with cited findings, against the `## Design Direction` and the accessibility floors.
+
+<constraints>
+Always do:
+- Review **screenshots of the running product**, both colour schemes, at phone width and desktop (Playwright, `deviceScaleFactor: 2`). Reading markup proves nothing about colour, contrast or layout; the colour may live in node_modules.
+- Cite, never assert: a claim about user behaviour or a contrast failure points to a measurable standard (WCAG AA 4.5:1 body, 3:1 large) or a source; otherwise mark it as opinion.
+- Accessibility is pass/fail: contrast; a visible focus state on every interactive element; `cursor: pointer` on every clickable thing and on nothing inert; icon-only buttons labelled; real `<label>`s; reduced motion respected; nothing by colour alone.
+- Hierarchy: the most important thing is the most prominent; structure for the scan, not the close read; spacing groups what belongs together.
+- Consistency: components and tokens reused before anything new; a one-off that duplicates a primitive is a finding; hardcoded colours or spacing are findings.
+- Distinctive over default: name the templated patterns (purple gradient, Inter everywhere, a card for everything, centred everything) as findings, not taste notes; usability beats trend when a fashionable pattern costs the user.
+- A surface with zero styling classes, or a list with no designed empty state, is an automatic **blocker**.
+- Compare against `design/` reference images when they exist.
+- Say which findings are law (a standard, a measured number) and which are taste: a taste finding must be defensible to a designer in one sentence.
+- Judge the production build when there is one: minifiers and bundlers change what ships.
+
+Never do:
+- Pass a surface from the DOM or the diff.
+- Soften a contrast or focus failure into a suggestion.
+</constraints>
+
+Output: findings grouped blocker / major / minor, each with the screenshot it was seen in, the standard or source, and the one change that fixes it; then the three things that are working and must not be lost in the fix.

package/packs/web/skills/pick-rendering-mode/SKILL.md

@@ -0,0 +1,21 @@
+---
+name: pick-rendering-mode
+description: Use when starting or scaffolding a site or app, adding a page kind that may render differently, or deciding whether a page is static, server-rendered, client-rendered or an island. Records the decision where the build can see it.
+---
+
+# pick-rendering-mode
+
+One thing: decide the rendering mode per page kind up front and record it, instead of drifting into client-side rendering and hand-rolled multi-page HTML.
+
+<constraints>
+Always do:
+- For anything where content, SEO or first paint matters, the content is in the **initial HTML response**: SSG (build time, CDN) for marketing, docs, blog, listing pages; SSR (per request) for personalised or auth-gated content; CSR or islands only for the genuinely interactive parts and for app surfaces behind a login where SEO is irrelevant. Mix per page.
+- Several pages, a shared layout, routing or real data fetching → **Next.js** (the house framework), never hand-rolled vanilla JS and never a pure client-rendered SPA for a content site.
+- A single landing page or a tiny embeddable widget → plain HTML and CSS; a framework there is its own mistake.
+- Record the mode in the spec and in CLAUDE.md's load-bearing section: `Rendering: SSG for /, /docs/*; SSR for /account/*; islands for the editor`. A mode that is not written down was not decided.
+- The client/server boundary follows from the mode (`client-boundaries` rule): data paths for every client-side navigation target are listed in the spec's API section.
+
+Never do:
+- Default to client rendering because it is the habit.
+- Leave the mode implicit, or change it per page without updating the record.
+</constraints>

package/packs/web/skills/preflight-build/SKILL.md

@@ -0,0 +1,23 @@
+---
+name: preflight-build
+description: Use before any production build, deploy, image publish or release of a web app, and when asked whether the build is production-ready. Runs the real build and audits the emitted output; findings are blockers.
+---
+
+# preflight-build
+
+One thing: prove the **actual** production build against the `production-build` rule. Configs can lie; the emitted output cannot.
+
+<constraints>
+Always do:
+1. **Detect**: the bundler or framework CLI (next, webpack, rollup, esbuild, none), the real production build command from `scripts` (never invented), the output directory. Announce all three. No web build → say so and stop; do not pretend to have checked.
+2. **Config audit**: the `prodbuild-*` lesson checks against every config file; Next: no `productionBrowserSourceMaps`, no disabled minification; webpack: `mode: 'production'`, `[contenthash]`, `output.clean`, `splitChunks { chunks: 'all' }`, CSS extracted (never `style-loader`), a `performance` budget, `devtool: 'source-map'` never `eval`. Build identity: a per-build version linked to a commit; its absence is advisory on the first preflight and a blocker once the project has ever deployed.
+3. **Build for real**: run the command. A failing build is a hard stop; report the error verbatim.
+4. **Output audit**: parse the entry HTML; count every request it triggers and list them; grep the emitted HTML/CSS/JS for third-party origins (a font host or runtime CDN is a blocker); every cacheable asset carries a content hash and the HTML references the hashed names; CSS is in files; total JS/CSS/image bytes (gzip) and the five largest assets against the budget; a full-resolution PNG hero is a blocker; run the bundle analyzer if it is already a dependency and report duplicates.
+5. **Fix** what is fixable (self-host the font, vendor the CDN file, add the hash, compress the image), rebuild, re-audit.
+6. **Gate**: blockers remaining → the deploy does not happen. Report: the three detected facts, the request count and origin list, the size table, each finding with its evidence and its fix.
+
+Never do:
+- Audit the source instead of `dist/`/`.next/`.
+- Add a dependency just to get stats.
+- Downgrade a blocker to a note because the deploy is wanted today.
+</constraints>

package/packs/web/skills/seo-audit/SKILL.md

@@ -0,0 +1,22 @@
+---
+name: seo-audit
+description: Use when asked to audit a URL or page for SEO, indexing, structured data, LLM citability, or why a page does not rank. Runs the 27 checks in checks.md against the live DOM and writes a severity-grouped report file.
+---
+
+# seo-audit
+
+One thing: run the 27 technical SEO and LLM-readability checks in `checks.md` (beside this file) against the live page and write `seo-audit-<domain>-<date>.md`.
+
+<constraints>
+Always do:
+1. Read `checks.md` first and run its JavaScript **verbatim** through the browser (Playwright, or the `playwright` MCP server if the project has it); never from memory. If `checks.md` is missing, say so up front and derive each check from its description, noting in the report that the canonical snippets were unavailable.
+2. Navigate, wait for `document.readyState === 'complete'`, then run the categories in order: A identity and indexing (title, H1, heading hierarchy, meta, canonical, robots.txt fetched separately); B structured data (JSON-LD types, FAQ, chunk extractability: H2/H3 followed by a self-contained paragraph); C content semantics (alt audit, links, P vs SPAN census, landmarks, nav quality, article metadata); D accessibility and E-E-A-T as LLM signals (LLMs parse like screen readers); E performance and security (reload **before** console checks: timing, script and third-party counts, protocol, preloads, console errors including React hydration #418/#423); F cross-page internal linking.
+3. Severity: P0 blocks indexing or throws errors; P1 major ranking, security or LLM impact; P2 clear degradation; P3 LLM/GEO gaps; P4 quick wins.
+4. Report: title/URL/date; a 3 to 5 sentence summary naming the single most important fix; findings P0→P4 with the measured value; "What Google most likely ranks this page for" from the signals found; "Prerequisites before content work" when P0/P1 exist.
+5. Save the file in the working directory and send it.
+
+Never do:
+- Guess a check's output.
+- Skip the reload before capturing console errors.
+- Report a finding without the measured value behind it.
+</constraints>

package/packs/websocket/checks/no-token-in-query.json

@@ -0,0 +1,26 @@
+{
+  "id": "no-token-in-query",
+  "why": "A token in a URL lands in logs, history and proxies.",
+  "rule": ".claude/rules/identity-comes-from-the-connection.md",
+  "globs": [
+    "**/*.ts",
+    "**/*.js",
+    "**/*.mjs",
+    "**/*.cjs"
+  ],
+  "exclude": [
+    "**/tests/**",
+    "**/test/**",
+    "**/*.test.*",
+    "**/*.spec.*",
+    "**/e2e/**",
+    "**/node_modules/**",
+    "**/dist/**",
+    "**/build/**",
+    "**/.next/**"
+  ],
+  "pattern": "searchParams\\.get\\(\\s*['\"](?:token|api_?key|access_token|secret)['\"]",
+  "bad": "const token = url.searchParams.get('token');",
+  "good": "const token = await firstMessageToken(ws);",
+  "kind": "security"
+}