@kensaurus/skills 0.0.0-stage → 2.1.0

package/skills/enhance-web-forms/SKILL.md

@@ -0,0 +1,154 @@
+---
+name: enhance-web-forms
+description: >
+  Build or upgrade web forms: accessible structure, schema-driven validation,
+  client↔server parity. Use when "improve this form", "form validation",
+  "accessible form", "multi-step form", "form error handling", or "the form UX
+  is bad".
+license: MIT
+---
+
+# enhance-web-forms — Production-Quality Forms
+
+**Degree of freedom: MIXED.** Schema and state-machine judgment `[HIGH freedom]`; a11y probes and playwright walks `[LOW freedom — run exactly]`.
+
+Forms are where users hand you their data and where apps most often feel broken: unlabeled
+fields, validation that fires on every keystroke, errors screen readers never announce, a
+submit button that does nothing visible for three seconds, and no recovery when the request
+fails. This skill fixes all of that on real forms in the repo.
+
+> **A form is done when it is accessible, validated on both sides, gives feedback for every
+> state, and recovers from failure.** Compile-clean is not done.
+
+**Before any browser interaction, read `protocol-browser-anti-stall` and apply it.**
+
+## How to reason
+
+1. **Inventory** — forms, library, schema; bow out if none
+2. **Structure** — programmatic labels, types, error association
+3. **Parity** — one schema both sides; blur + submit, not every keystroke
+4. **States** — submitting / success / error / unsaved; recover on failure
+
+## Worked example
+
+> **Inventory:** signup uses raw `<form>` + inline `if (!email)`; API validates with zod.
+> **Structure:** `htmlFor` labels; `autocomplete="email"`; `aria-invalid` + summary.
+> **Parity:** share the zod schema; validate on blur/submit; map "email taken" to the field.
+> **States:** submit disables + `aria-busy`; values preserved on 500; dirty-nav warn.
+
+## Self-critique before reporting
+
+- **Labeled** — placeholder is never the only name
+- **Both sides** — client and server rules match; error shapes map to fields
+- **Walked** — empty, invalid, valid, and server-error paths in the browser
+- **Right owner** — page/flow UX beyond the form → `enhance-web-ux`; WCAG sweep → `audit-accessibility`
+
+---
+
+## Phase 0 — Detect the stack and inventory forms  [HIGH freedom]
+
+```bash
+cat package.json | grep -iE "react-hook-form|formik|@tanstack/react-form|final-form|zod|yup|valibot|superstruct"
+rg -n "<form|onSubmit|useForm|handleSubmit" -g "*.{tsx,jsx,vue,svelte}" -l
+```
+
+Record: form library (or native), validation/schema library, UI/component library, and the
+list of forms to enhance (auth, checkout, settings, contact, search, etc.). If there are no
+forms, bow out.
+
+---
+
+## Phase 1 — Research + prioritize  [HIGH freedom]
+
+Follow `/research`: Context7 for the detected form/validation library's current API;
+Firecrawl for current form UX/a11y guidance dated to now. Prioritize forms by traffic and
+risk (auth, payment, destructive actions first).
+
+---
+
+## Phase 2 — Accessible structure (the foundation)  [HIGH freedom]
+
+For each form, verify/fix:
+
+- **Every input has a programmatic label** — `<label htmlFor>` or `aria-label`; placeholder
+  is **not** a label.
+- **Correct input types + `autocomplete`** — `type="email|tel|url|number"`, `inputmode`,
+  `autocomplete="email|current-password|cc-number|..."` for autofill.
+- **Grouping** — related inputs in `<fieldset>` + `<legend>` (radio groups, address blocks).
+- **Required + optional** — marked in text, not color alone; `required` / `aria-required`.
+- **Keyboard + focus** — logical tab order, visible focus ring, Enter submits, no keyboard traps.
+- **Error association** — each field error linked via `aria-describedby`; invalid fields get
+  `aria-invalid="true"`; a form-level error **summary** with links to fields on submit failure.
+
+```bash
+rg -n "placeholder=" -g "*.{tsx,jsx}"        # placeholders masquerading as labels?
+rg -n "aria-describedby|aria-invalid|htmlFor|aria-label" -g "*.{tsx,jsx}" -c
+```
+
+---
+
+## Phase 3 — Validation (schema-driven, both sides)  [HIGH freedom]
+
+- **Single schema as SSOT** — define validation once (zod/yup/valibot) and share it
+  between client and server so rules can't drift. If the backend validates separately,
+  reconcile the two so error shapes match.
+- **Timing** — validate on **blur** and on **submit**, not on every keystroke; re-validate a
+  field on change **after** it has errored once (so users see fixes immediately).
+- **Messages** — specific and actionable ("Password needs 8+ characters", not "Invalid").
+- **Server errors** — map field-level server errors back onto the right inputs; show
+  form-level errors (e.g. "Email already registered") in the summary.
+
+---
+
+## Phase 4 — States & feedback (every one, no gaps)  [HIGH freedom]
+
+Wire the full state machine for each form and submit:
+
+| State | Required behavior |
+|---|---|
+| Idle | Clean, submit enabled/disabled per validity policy |
+| Validating | Inline field feedback (see Phase 3 timing) |
+| Submitting | Submit shows spinner/label swap + `disabled` + `aria-busy`; prevent double-submit |
+| Success | Confirmation (toast/inline/redirect); reset or lock as appropriate |
+| Error | Preserve entered values; surface the failure; keep the user's place; retry path |
+| Empty/optional | Sensible defaults; empty state for dependent selects |
+
+Also handle:
+- **Multi-step** — progress indicator, per-step validation, back/forward preserves data,
+  final review before submit.
+- **Unsaved-changes guard** — warn on navigation away from a dirty form.
+- **Autosave / draft** — for long forms, if the app already has a persistence pattern.
+- **Micro-feedback** — subtle transitions on error/success via `design-motion` conventions
+  (reduced-motion safe). Don't animate layout in a way that shifts fields.
+
+---
+
+## Phase 5 — Verify and report  [LOW freedom — do not skip]
+
+- **playwright-cli:** walk each form — tab through it, submit empty (see the error summary +
+  focus moves to first error), submit invalid, submit valid, force a server error. Check
+  `console`. Confirm screen-reader names via the accessibility snapshot.
+  Screenshots to `.playwright-mcp/`.
+- **Build/typecheck/lint:** run the repo's commands.
+
+```markdown
+## Forms Enhancement — report
+**Stack:** form=[..] · validation=[..] · UI=[..]
+**Forms upgraded:** [list]
+**Structure:** labels/types/autocomplete/fieldsets fixed on [N] forms
+**Validation:** shared schema SSOT · client↔server parity · blur+submit timing
+**States:** submitting/success/error/multi-step/unsaved-guard wired
+**A11y:** error summary + aria-describedby/aria-invalid + focus management (evidence)
+**Verification:** build ✓ · console clean ✓ · flows walked (screenshots [paths])
+```
+
+---
+
+## Related
+
+- `audit-accessibility` — deep WCAG audit (run to verify the a11y work)
+- `audit-ux` — form usability heuristics, microcopy, cognitive load
+- `audit-fe-api` — validate the submit request/response contract against the backend
+- `backend-error-handling` — server-side validation + structured error responses
+- `design-motion` — reduced-motion-safe micro-feedback for error/success
+- `enhance-web-ux` — broader page/flow UX beyond the form itself

package/skills/enhance-web-instant-nav/SKILL.md

@@ -0,0 +1,138 @@
+---
+name: enhance-web-instant-nav
+description: >
+  Instant in-site navigation: Speculation Rules, View Transitions, bfcache,
+  103 Early Hints. Use when "instant navigation", "prerender", "early hints",
+  "back button reloads", or "second page is slow". First-load CWV →
+  audit-performance.
+license: MIT
+---
+
+> Surface router: `/uiux`. You are here: `enhance-web-instant-nav`.
+
+# enhance-web-instant-nav — Instant Navigations
+
+**Degree of freedom: MIXED.** Which pages to speculate `[HIGH freedom]`;
+the exclusion list, `Sec-Purpose` handling, and re-measure `[LOW freedom — run exactly]`.
+
+> Applies to MPAs and Next.js App Router (server-rendered routes). Pure SPA
+> routing → use the framework's prefetch API; Speculation Rules are per-document.
+
+## How to reason
+
+1. **Observe** — quote 2nd-page LCP p75, bfcache test result, and the top 5 next-click paths
+2. **Rank** — probability × page cost. Prefetch broadly; prerender only ≥ ~50% likely next pages
+3. **Guard** — list every URL with GET side effects or per-user state; exclude or downgrade to prefetch
+4. **Ship** — rules + server guard + analytics guard in the same PR
+5. **Re-measure** — if 2nd-page LCP didn't drop, the rule isn't firing (DevTools → Application → Speculative loads)
+
+## Worked example
+
+> **Observe:** blog; first-page LCP 1.9 s, next-article LCP 2.8 s; back button reloads (`unload` in analytics).
+> **Rank:** "next article" 61% of sessions → prerender moderate; category links → prefetch moderate.
+> **Guard:** `/logout`, `/account/*`, `?utm_*` excluded; server returns early on `Sec-Purpose`.
+> **Ship:** rules block + `pagehide` swap + `document.prerendering` guard in the GA loader.
+> **Re-measure:** next-article LCP 0.3 s (activation), bfcache green, no analytics double-count.
+
+## Safety contract  [LOW freedom — run exactly]
+
+- Never prerender: logout, cart/checkout, payment, auth, anything whose GET mutates state
+- Server: if `Sec-Purpose` contains `prefetch`, skip counters/side effects; return normal HTML
+- Client: analytics, ads, consent, A/B run only after `document.prerendering === false` or on `prerenderingchange`
+- Never add `unload` listeners; never set `Cache-Control: no-store` on HTML unless legally required
+- Cross-origin / cross-site prerender is not attempted
+
+## Phase 1 — Measure  [LOW freedom — run exactly]
+
+- `web-vitals/attribution` `onLCP` on the *second* page in a session; record p75
+- DevTools → Application → Back/forward cache → Test; record blocking reasons
+- `curl -sv <url> 2>&1 | grep "< HTTP"` — is a `103` emitted today?
+- Top next-click paths from analytics (or infer from IA)
+
+```bash
+# Field: CrUX / PSI p75 for origin + top URLs
+npx @lhci/cli autorun --config=lighthouserc.json
+curl -sv https://example.com/ 2>&1 | grep -E "< HTTP/.* 103"
+```
+
+## Phase 2 — Speculation Rules  [HIGH freedom on selection]
+
+Baseline (adjust `where` to the site's IA):
+
+```html
+<script type="speculationrules">
+{
+  "prefetch": [{
+    "where": { "and": [
+      { "href_matches": "/*" },
+      { "not": { "href_matches": ["/logout", "/account/*", "/cart*", "/checkout*", "/api/*"] } },
+      { "not": { "selector_matches": "[rel~=nofollow], .no-prefetch" } }
+    ]},
+    "eagerness": "moderate"
+  }],
+  "prerender": [{
+    "where": { "href_matches": "/posts/*" },
+    "eagerness": "moderate"
+  }]
+}
+</script>
+```
+
+- Eagerness: `conservative` (pointer/touch down) → `moderate` (desktop: hover 200 ms or pointerdown; mobile: viewport heuristics) → `eager` (Chrome 143+: desktop hover 10 ms, mobile viewport heuristics) → `immediate` (as soon as the rules load). Left unset, list (`urls`) rules default to `immediate` and document (`where`) rules to `conservative`, so set `moderate` explicitly. `immediate` on document rules is allowed but speculates on every matching link; use it with care.
+- Query strings: `"expects_no_vary_search": "params=(\"utm_source\" \"utm_medium\")"` or exclude `?` URLs
+- Next.js App Router: keep `<Link>` prefetch for RSC payloads; add the block in `app/layout.tsx` via a raw `<script>`. On Next.js 16.3+ evaluate **Instant Navigations** first (opt-in: `cacheComponents: true` + `partialPrefetching: true` in `next.config`); if it covers the case, skip prerender rules and keep only prefetch.
+- Chromium-first progressive enhancement. Check caniuse at implementation time — never block on Firefox/Safari.
+
+Syntax depth: `references/speculation-rules.md`.
+
+## Phase 3 — bfcache  [LOW freedom — run exactly]
+
+- Replace `unload` → `pagehide`; `beforeunload` only while unsaved input exists
+- Close WebSockets / BroadcastChannel in `pagehide`; reopen on `pageshow` if `event.persisted`
+- Drop `Cache-Control: no-store` from HTML (keep it on APIs)
+- Re-run the DevTools test until green
+
+Blocker list: `references/bfcache-blockers.md`.
+
+## Phase 4 — View Transitions (cross-document)  [HIGH freedom]
+
+```css
+@view-transition { navigation: auto; }
+@media (prefers-reduced-motion: reduce) { @view-transition { navigation: none; } }
+.hero-img { view-transition-name: hero; }
+```
+
+- Pair with prerender: activation + transition = app-like feel
+- Progressive: nothing breaks without it
+- Keep `view-transition-name` unique per document or the transition aborts
+- `prefers-reduced-motion` is required (pairs with `audit-accessibility`)
+
+## Phase 5 — 103 Early Hints  [LOW freedom — run exactly]
+
+- HTML responses only: `Link: </hero.avif>; rel=preload; as=image; fetchpriority=high`, `Link: <https://cdn.example>; rel=preconnect`
+- Node/Next custom server: `res.writeEarlyHints({ link: [...] })`; else CDN config
+- Do not hint > ~5 resources; do not hint per-user content
+- Per-platform: `references/early-hints.md`
+
+## Self-critique before reporting
+
+- **Exclusions listed** — every GET-with-side-effects URL is in the PR
+- **Server checks `Sec-Purpose`** — grep it
+- **No double analytics** — prerender → activation tested
+- **Prerender scarce** — only pages with ≥ ~50% next-click probability
+- **Re-measured** — 2nd-page LCP p75 dropped, or the rule isn't firing
+- **Right owner** — first-load LCP/INP/CLS → `audit-performance`; JS weight → `audit-bundle-size`
+
+## Required output
+
+1. Before/after: 2nd-page LCP p75, bfcache status, 103 present, transition on/off
+2. Rules block + exclusion list
+3. Server guard + client analytics guard diffs
+4. One-line rollback: delete the `<script type="speculationrules">` block
+
+## Related
+
+- `audit-performance` — first-load CWV / loading priority
+- `audit-bundle-size` — JS weight; don't double-prefetch
+- `audit-accessibility` — reduced-motion for View Transitions
+- `enhance-pwa` — service worker vs speculation / bfcache

package/skills/enhance-web-instant-nav/references/bfcache-blockers.md

@@ -0,0 +1,23 @@
+# bfcache blockers
+
+Test: DevTools → Application → Back/forward cache → Test.
+
+| Reason (typical) | Fix |
+|------------------|-----|
+| `unload` listener | Use `pagehide` / `pageshow` |
+| `Cache-Control: no-store` on HTML | Drop from HTML; keep on APIs |
+| Open WebSocket | Close in `pagehide`; reopen on `pageshow` if `event.persisted` |
+| Open IndexedDB transaction | Commit/abort before leave |
+| `beforeunload` always on | Only while unsaved input exists |
+| Busy service worker (some cases) | See `enhance-pwa` — don't claim the page if SW holds it |
+
+```js
+window.addEventListener('pagehide', (e) => {
+  socket?.close();
+});
+window.addEventListener('pageshow', (e) => {
+  if (e.persisted) reconnect();
+});
+```
+
+Never add `unload`. A green DevTools test is required before claiming bfcache.

package/skills/enhance-web-instant-nav/references/early-hints.md

@@ -0,0 +1,33 @@
+# 103 Early Hints — per platform
+
+Emit on **HTML** only. ≤ ~5 `Link` values. Never hint per-user URLs.
+
+```
+Link: </hero.avif>; rel=preload; as=image; fetchpriority=high
+Link: <https://cdn.example>; rel=preconnect
+```
+
+## Verify
+
+```bash
+curl -sv https://example.com/ 2>&1 | grep -E "< HTTP/.* 103"
+```
+
+## Node / Next custom server
+
+```js
+res.writeEarlyHints({
+  link: [
+    '</hero.avif>; rel=preload; as=image; fetchpriority=high',
+    '<https://cdn.example>; rel=preconnect',
+  ],
+});
+```
+
+## CDN
+
+- **Cloudflare:** Early Hints toggle; reads origin `Link` headers
+- **Fastly:** `http_status 103` + `Link` in VCL / Compute
+- **Nginx:** `http2_push` is not 103; use a CDN or OpenResty module that emits 103
+
+103 is wasted if the LCP image is still lazy or not in HTML.

package/skills/enhance-web-instant-nav/references/speculation-rules.md

@@ -0,0 +1,44 @@
+# Speculation Rules — syntax
+
+Official: https://developer.mozilla.org/en-US/docs/Web/API/Speculation_Rules_API
+
+## Actions
+
+| Action | What it does | Use |
+|--------|--------------|-----|
+| `prefetch` | Fetch HTML (and often subresources) | Broad in-site links |
+| `prerender` | Fully render in a hidden document | ≥ ~50% next-click pages only |
+
+## Eagerness
+
+| Value | When | Risk |
+|-------|------|------|
+| `conservative` | pointerdown | Lowest waste |
+| `moderate` | hover ~200 ms / viewport heuristics | Default |
+| `eager` | sooner | More waste |
+| `immediate` | as soon as parsed | List rules only |
+
+## Chrome limits (verify at implement time)
+
+Prerender count and memory caps change. Prefer few prerender URLs.
+`target_hint` can hint `_blank` vs `_self`.
+
+## No-Vary-Search
+
+Ignore tracking params so `/posts/1?utm_source=x` matches `/posts/1`:
+
+```json
+"expects_no_vary_search": "params=(\"utm_source\" \"utm_medium\" \"utm_campaign\")"
+```
+
+Or exclude `?` URLs entirely.
+
+## Headers
+
+Browser sends `Sec-Purpose: prefetch` (and `prerender` when prerendering).
+Server must skip side effects on that header.
+
+## Next.js 16.3 Instant Navigations
+
+Opt-in suite (partial prefetch, navigation insights). If it covers the
+case, skip custom prerender rules; keep moderate prefetch + `<Link>`.