voidmachine 0.0.0 → 4.0.0

package/core-assets/packs/pack-pwa/skills/void-offline-first-mutation/.source

@@ -0,0 +1,8 @@
+Sources for `void-offline-first-mutation` skill (see `docs/plans/skill-audits/void-offline-first-mutation.md` for the full audit):
+
+- Solaar `@solaar/ui/offline` implementation — primary source; pattern lifted with adaptation to be stack-neutral.
+- Stripe API idempotency-key docs — confirms the client-generates-UUID approach for HTTP idempotency.
+- RxDB / WatermelonDB conflict-resolution docs — inspiration for "server wins" baseline; richer reconciliation rejected for scope.
+- Yjs / Automerge — mentioned as out-of-scope for explicit non-coverage.
+
+Strategy: distill. Capture-queue + sync pattern distilled from Solaar and adapted to be stack-neutral.

package/core-assets/packs/pack-pwa/skills/void-offline-first-mutation/SKILL.md

@@ -0,0 +1,266 @@
+---
+name: void-offline-first-mutation
+description: "Implement a UI mutation that works offline via the capture-queue + sync pattern: IndexedDB, optimistic UI, idempotency keys, retry, conflict resolution. Self-contained, no harness wrappers."
+---
+
+# offline-first-mutation
+
+Use when implementing **any user-triggered write** in a PWA that must succeed when the device is offline (mobile in subway, mobile in field, flaky wifi) and reconcile when connectivity returns.
+
+If the mutation is read-only or the user can tolerate "please try again when online", this skill does not apply.
+
+## When this skill triggers
+
+- "User taps the save button" / "user posts a comment" / "user updates a profile field"
+- "Capture this action even if offline"
+- Any flow where dropping the user's input is a product failure
+
+## The model (capture-queue + sync)
+
+```
+┌────────────┐    enqueue    ┌─────────────┐    sync()    ┌──────────────┐
+│ UI write   │ ────────────► │ IndexedDB   │ ───────────► │ Server Action │
+│ (optimistic│               │ capture     │              │ (or POST API) │
+│  update)   │               │ queue       │              └──────────────┘
+└────────────┘               └─────────────┘                       │
+       ▲                            │                              ▼
+       │       conflict ?           │                       commit | reject
+       └────────────────────────────┴───── server wins ────────────┘
+```
+
+Three guarantees:
+
+1. **Local first**: UI updates synchronously from the optimistic state — the user never waits for the network.
+2. **Durable**: the intent is persisted to IndexedDB **before** the UI confirms; an immediate browser crash doesn't lose it.
+3. **Idempotent**: each intent carries a client-generated `idempotencyKey` so retries are safe.
+
+## Anatomy of an intent
+
+```ts
+type Intent<TPayload> = {
+  readonly id: string;                  // client UUID v7 — sortable, also serves as idempotencyKey
+  readonly kind: string;                // 'note.create', 'contact.update', etc.
+  readonly payload: TPayload;           // serializable
+  readonly createdAt: number;           // epoch ms (client clock; used for ordering, not for truth)
+  readonly attempts: number;            // bumped on each retry
+  readonly status: 'pending' | 'syncing' | 'committed' | 'failed';
+  readonly lastError?: { code: string; message: string };
+};
+```
+
+`status` transitions:
+
+- `pending` → `syncing` (sync picks it up, network in-flight)
+- `syncing` → `committed` (server returned 2xx)
+- `syncing` → `pending` (retryable error: network, 5xx, 429 — schedule next attempt with backoff)
+- `syncing` → `failed` (non-retryable: 4xx other than 429 — surface to user, do not retry automatically)
+
+## Capture-queue primitives (write them once per project)
+
+The capture-queue is small enough to own outright. Write these in your project (e.g., `packages/offline/src/`):
+
+```ts
+// packages/offline/src/capture-queue.ts
+import { openDB, IDBPDatabase } from 'idb';
+
+const DB_NAME = 'offline-queue';
+const STORE = 'intents';
+
+let dbPromise: Promise<IDBPDatabase> | null = null;
+function db() {
+  if (!dbPromise) {
+    dbPromise = openDB(DB_NAME, 1, {
+      upgrade(d) {
+        d.createObjectStore(STORE, { keyPath: 'id' });
+      },
+    });
+  }
+  return dbPromise;
+}
+
+export async function enqueue<T>(intent: Omit<Intent<T>, 'attempts' | 'status' | 'createdAt'> & { createdAt?: number }): Promise<Intent<T>> {
+  const full: Intent<T> = {
+    ...intent,
+    createdAt: intent.createdAt ?? Date.now(),
+    attempts: 0,
+    status: 'pending',
+  };
+  const d = await db();
+  await d.put(STORE, full);
+  return full;
+}
+
+export async function pending(): Promise<Intent<unknown>[]> {
+  const d = await db();
+  return (await d.getAll(STORE)).filter((i) => i.status === 'pending');
+}
+
+export async function markStatus(id: string, status: Intent<unknown>['status'], lastError?: Intent<unknown>['lastError']): Promise<void> {
+  const d = await db();
+  const intent = await d.get(STORE, id);
+  if (!intent) return;
+  await d.put(STORE, { ...intent, status, lastError, attempts: intent.attempts + (status === 'pending' ? 1 : 0) });
+}
+
+export async function failed(): Promise<Intent<unknown>[]> {
+  const d = await db();
+  return (await d.getAll(STORE)).filter((i) => i.status === 'failed');
+}
+```
+
+## Sync engine
+
+```ts
+// packages/offline/src/sync.ts
+import { pending, markStatus } from './capture-queue';
+
+const BACKOFF_MS = [2_000, 5_000, 15_000, 60_000, 300_000, 1_800_000, 14_400_000]; // 2s..4h
+
+export type SyncHandler<T> = (intent: Intent<T>) => Promise<void>;
+
+export async function sync(handlers: Record<string, SyncHandler<unknown>>): Promise<void> {
+  if (typeof navigator !== 'undefined' && navigator.onLine === false) return;
+
+  const items = await pending();
+  for (const intent of items) {
+    const handler = handlers[intent.kind];
+    if (!handler) continue;
+
+    await markStatus(intent.id, 'syncing');
+    try {
+      await handler(intent);
+      await markStatus(intent.id, 'committed');
+    } catch (err) {
+      if (isPermanentFailure(err)) {
+        await markStatus(intent.id, 'failed', { code: 'permanent', message: String(err) });
+      } else {
+        // Schedule retry — caller's responsibility to call sync() again after backoff
+        await markStatus(intent.id, 'pending', { code: 'transient', message: String(err) });
+      }
+    }
+  }
+}
+
+function isPermanentFailure(err: unknown): boolean {
+  // Adapt to your error types — 4xx (not 429) is permanent
+  if (err && typeof err === 'object' && 'status' in err) {
+    const s = (err as { status: number }).status;
+    return s >= 400 && s < 500 && s !== 429;
+  }
+  return false;
+}
+```
+
+That's ~60 lines of code consumers OWN — not a wrapper from this pack. Easier to debug, easier to adapt to your stack (Dexie, idb-keyval, raw IndexedDB).
+
+## Use it in a component
+
+```tsx
+'use client';
+
+import { useState } from 'react';
+import { enqueue } from '@/offline/capture-queue';
+import { sync } from '@/offline/sync';
+import { createNoteAction } from '@/actions/notes';
+
+export function NoteForm() {
+  const [submitting, setSubmitting] = useState(false);
+
+  async function onSubmit(formData: FormData) {
+    setSubmitting(true);
+    const intent = await enqueue({
+      id: crypto.randomUUID(),
+      kind: 'note.create',
+      payload: {
+        title: formData.get('title'),
+        body: formData.get('body'),
+      },
+    });
+
+    // Optimistic UI update — show the note in the list immediately
+    addNoteOptimistic({ id: intent.id, ...intent.payload, status: 'pending' });
+
+    // Kick off sync in background — do not await
+    sync({
+      'note.create': async (i) => {
+        await createNoteAction({
+          idempotencyKey: i.id,
+          ...(i.payload as { title: string; body: string }),
+        });
+      },
+    });
+
+    setSubmitting(false);
+    // Form clears immediately — the optimistic note is in the list already.
+  }
+
+  return <form action={onSubmit}>...</form>;
+}
+```
+
+## Server-side idempotency
+
+The Server Action MUST honor `idempotencyKey`:
+
+```ts
+'use server';
+
+export async function createNoteAction(input: { idempotencyKey: string; title: string; body: string }) {
+  // Inbox pattern: check if we've already committed this key
+  const existing = await db.query.notes.findFirst({
+    where: eq(notes.idempotencyKey, input.idempotencyKey),
+  });
+  if (existing) return { ok: true, data: existing };       // safe re-deliver
+
+  // Otherwise create + commit
+  const [created] = await db.insert(notes).values({ ... }).returning();
+  return { ok: true, data: created };
+}
+```
+
+The `idempotencyKey` column on the notes table needs a unique index. Migration follows the safe pattern (see `void-drizzle-migration-safe`).
+
+## Conflict resolution
+
+When the server response contradicts the local optimistic state (e.g., a concurrent edit from another device), the **server wins**. Two cases:
+
+- **Field-level conflict** (last-write-wins): server returns its version, UI overwrites the optimistic state.
+- **Validation rejection** (e.g., title became required): mark intent as `failed`, surface a toast to the user with the option to edit and retry.
+
+For richer reconciliation (operational transforms, CRDTs), don't try to roll your own — use Yjs or Automerge. Outside this skill's scope.
+
+## Backoff schedule
+
+Default retry intervals: **2s, 5s, 15s, 60s, 5min, 30min, 4h**. After 4h with no success, mark `failed` and notify the user. Driven by the caller (re-call `sync()` from a `setTimeout` or `requestIdleCallback` chain).
+
+Pause sync entirely when `navigator.onLine === false`. Resume on `online` event:
+
+```ts
+window.addEventListener('online', () => sync(handlers));
+```
+
+## Dead-letter
+
+Intents in `failed` status surface in a dead-letter UI (`Settings → Pending sync`) where the user can:
+
+- Retry manually (`markStatus(id, 'pending')` + `sync()`)
+- Edit and resubmit (creates a new intent, discards the old)
+- Delete (drops the change permanently)
+
+Never silently drop a failed intent — the user wrote it, it's their data.
+
+## Anti-patterns
+
+- ✗ **Optimistic update without persistence**: tab close = lost data.
+- ✗ **Client-generated IDs that aren't UUID v7 / ULID**: ordering breaks across devices.
+- ✗ **`idempotencyKey` reused across mutations**: server returns the wrong response.
+- ✗ **Showing "Saved!" toast on enqueue**: lies to the user — sync hasn't happened. Use "Captured" or no toast.
+- ✗ **Catching `failed` errors and swallowing them**: dead-letter MUST be visible.
+- ✗ **Mixing capture-queue with React Query**: pick one for mutations. RQ for reads, capture-queue for offline-tolerant writes.
+
+## Composition (informational)
+
+- `void-server-action` — sync target; idempotency-key handling lives there.
+- `void-async-safety` — backoff schedule, dead-letter, bounded retry semantics.
+- `void-drizzle-migration-safe` — adding the `idempotencyKey` unique index.
+- `void-observability` — log sync attempts with `idempotencyKey` so a failed intent can be traced end-to-end.

package/core-assets/packs/pack-pwa/skills/void-offline-first-mutation/harness.yaml

@@ -0,0 +1,14 @@
+# Harness metadata for this skill. Not part of the Agent Skills
+# specification, and never copied into a consumer project: the SKILL.md
+# beside it stays portable and validates against the official six fields.
+# Read by this repository's graph, and by the installer for `runtimes`.
+kind: standard
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: active
+    codex: active
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/packs/pack-pwa/skills/void-service-worker-strategy/.source

@@ -0,0 +1,5 @@
+Sources for `void-service-worker-strategy` skill (see `docs/plans/skill-audits/void-service-worker-strategy.md` for the full audit):
+
+- No external source table in the audit — skill distilled into the canonical per-resource-class strategy table, cache versioning rule, update activation patterns, and a Serwist-based config + DevTools debug section.
+
+Strategy: distill. The audit lists no external "Sources audited" table; recorded honestly here.

package/core-assets/packs/pack-pwa/skills/void-service-worker-strategy/SKILL.md

@@ -0,0 +1,178 @@
+---
+name: void-service-worker-strategy
+description: Pick caching strategy per route class (NetworkFirst, CacheFirst, StaleWhileRevalidate, NetworkOnly), version your caches, handle update activation. Use Serwist (Next) or vite-plugin-pwa.
+---
+
+# service-worker-strategy
+
+Use when configuring or modifying a service worker in a PWA project. The strategy choice per route class is the difference between "instant repeat visits" and "stale content shown for days" or "no offline support".
+
+If your app has no service worker yet, this skill says how to add one. If it has one but feels broken, this skill says how to debug.
+
+## The library choice
+
+| Stack | Library |
+|---|---|
+| Next.js 16 | **Serwist** (modern Workbox successor, App Router compatible) |
+| Vite | **vite-plugin-pwa** (wraps Workbox) |
+| Astro | `@vite-pwa/astro` |
+| Custom | Workbox directly (hard mode; only if you understand SW internals) |
+
+Don't hand-write a service worker. Serwist/Workbox handles the lifecycle gotchas (skipWaiting, clientsClaim, cache versioning) you'd otherwise rediscover the hard way.
+
+## Strategies per route class
+
+Match the strategy to the **freshness vs availability** trade-off of each resource type.
+
+| Resource | Strategy | Why |
+|---|---|---|
+| HTML pages (`/`, `/blog/*`) | `NetworkFirst({ networkTimeoutSeconds: 3 })` | Fresh content preferred; fallback to cache after 3s for offline |
+| JS / CSS bundles (hashed names) | `CacheFirst` | Hash in name = immutable; cache forever |
+| Fonts | `CacheFirst({ maxAge: 1 year })` | Rarely changes; large download |
+| Images | `CacheFirst({ maxAge: 30 days, maxEntries: 60 })` | Expensive bandwidth |
+| API responses | `NetworkOnly` (default) | Fresh data required; capture-queue handles offline writes |
+| API responses (tolerable stale, e.g. /me) | `StaleWhileRevalidate` | Show cached, update in background |
+| Manifest | `NetworkOnly` | Browser handles caching natively |
+| `/api/health` | `NetworkOnly` | Should always reflect server reality |
+
+## Canonical Serwist config sketch (Next 16)
+
+> Serwist evolves quickly; the **strategy-per-resource-class principles** below are the substance. The exact config shape may differ per Serwist version — always cross-reference the current Serwist docs when scaffolding.
+
+```ts
+// apps/web/app/sw.ts (shape — confirm against current Serwist version)
+import { Serwist, NetworkFirst, CacheFirst, NetworkOnly } from 'serwist';
+
+const SW_VERSION = '__BUILD_HASH__';   // injected by build
+
+declare const self: ServiceWorkerGlobalScope;
+
+const serwist = new Serwist({
+  precacheEntries: self.__SW_MANIFEST,  // injected: static assets to pre-cache
+  skipWaiting: true,
+  clientsClaim: true,
+  navigationPreload: true,
+  runtimeCaching: [
+    // HTML pages: prefer fresh, fall back to cache after 3s on slow networks
+    {
+      matcher: ({ request }) => request.destination === 'document',
+      handler: new NetworkFirst({
+        cacheName: `html-${SW_VERSION}`,
+        networkTimeoutSeconds: 3,
+      }),
+    },
+    // JS/CSS: hashed filenames are immutable; cache forever
+    {
+      matcher: ({ request }) => request.destination === 'script' || request.destination === 'style',
+      handler: new CacheFirst({ cacheName: `static-${SW_VERSION}` }),
+    },
+    // Images: cache for 30 days, cap at 60 entries
+    {
+      matcher: ({ request }) => request.destination === 'image',
+      handler: new CacheFirst({ cacheName: `images-${SW_VERSION}` }),
+    },
+    // API: never cache; let the network speak
+    {
+      matcher: ({ url }) => url.pathname.startsWith('/api/'),
+      handler: new NetworkOnly(),
+    },
+  ],
+});
+
+serwist.addEventListeners();
+```
+
+`vite-plugin-pwa` exposes the same strategies under Workbox names (`NetworkFirst`, etc.) with slightly different option keys. The **what** (per-resource strategy + version cacheName + max age) transfers; the **how** (exact constructor call) is library-specific.
+
+## Cache versioning — the critical detail
+
+Without versioning, an updated worker reads old caches with old asset URLs → broken page after deploy.
+
+The pattern: include `SW_VERSION` (build hash, app version, anything that changes per deploy) in EVERY `cacheName`:
+
+```ts
+cacheName: `html-${SW_VERSION}`        // not just `html`
+```
+
+On worker activation, old caches (with old version names) are orphaned. Periodic cleanup:
+
+```ts
+self.addEventListener('activate', (event) => {
+  event.waitUntil((async () => {
+    const keys = await caches.keys();
+    await Promise.all(
+      keys
+        .filter((k) => !k.endsWith(`-${SW_VERSION}`))
+        .map((k) => caches.delete(k))
+    );
+  })());
+});
+```
+
+Serwist handles this if `cleanupOutdatedCaches: true` (default in newer versions).
+
+## Update activation UX
+
+Three patterns; pick one.
+
+### A. Silent — worker activates on next page load
+
+Default. Simplest. New worker becomes active after the user closes/reopens the tab. Works for most apps.
+
+### B. "Reload to update" prompt
+
+When a new worker is waiting, show a banner. User clicks → `skipWaiting()` + reload.
+
+```ts
+// In a Client Component
+import { Workbox } from 'workbox-window';
+
+const wb = new Workbox('/sw.js');
+wb.addEventListener('waiting', () => {
+  setShowUpdatePrompt(true);
+});
+
+function applyUpdate() {
+  wb.addEventListener('controlling', () => window.location.reload());
+  wb.messageSkipWaiting();
+}
+```
+
+Use when shipping critical fixes that should not wait for tab close.
+
+### C. Auto-apply (aggressive)
+
+`skipWaiting: true` + `clientsClaim: true` (shown in canonical config above). New worker takes over immediately. Risk: in-flight requests served by old worker can race with new worker.
+
+Default to C for greenfield, B for production-critical apps where users keep tabs open for days.
+
+## Anti-patterns
+
+- ✗ **No version in cacheName** — orphan caches grow forever, eventually quota-exceed
+- ✗ **CacheFirst on HTML** — stuck on stale page after deploy
+- ✗ **NetworkFirst without networkTimeoutSeconds** — slow networks see infinite spinner instead of cached fallback
+- ✗ **Workbox plugin without HTTPS** — service workers only register on HTTPS or localhost (silent failure otherwise)
+- ✗ **`skipWaiting` for sensitive data screens** — old worker mid-checkout, new worker takes over, weird state. Pattern B (prompt) is safer for checkout flows.
+- ✗ **Caching POST/PUT/DELETE** — only GET is cacheable; service workers don't cache mutations
+
+## Debugging
+
+DevTools → Application → Service Workers:
+
+- "Update on reload" checkbox helps during development
+- "Unregister" + hard reload resets state
+- "Bypass for network" disables SW temporarily
+
+DevTools → Application → Cache Storage:
+
+- Lists all named caches
+- Click a cache → see entries, sizes, last accessed
+- Should see one cache PER cacheName variant (versioned correctly)
+
+## Composition
+
+- `void-manifest-checklist` — manifest declares the SW scope; service worker honors it.
+- `void-install-prompt-ux` — SW must be registered before install prompt fires.
+- `void-offline-first-mutation` — capture-queue lives alongside SW; SW handles GET caching, capture-queue handles mutations.
+- `void-cache-component-pattern` — Next's server-side cache is independent of SW; both layers compose.
+- `void-async-safety` — SW activation race conditions are timing bugs; bounded retries on update apply.

package/core-assets/packs/pack-pwa/skills/void-service-worker-strategy/harness.yaml

@@ -0,0 +1,14 @@
+# Harness metadata for this skill. Not part of the Agent Skills
+# specification, and never copied into a consumer project: the SKILL.md
+# beside it stays portable and validates against the official six fields.
+# Read by this repository's graph, and by the installer for `runtimes`.
+kind: standard
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: active
+    codex: active
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/packs/pack-react/skills/void-accessibility-check/.source

@@ -0,0 +1,8 @@
+Sources for `void-accessibility-check` skill (see `docs/plans/skill-audits/void-accessibility-check.md` for the full audit):
+
+- WCAG 2.2 quick reference — authoritative for contrast and touch target sizes.
+- WebAIM "Designing for Screen Reader Compatibility" — source of the "name accessible to AT" framing.
+- Apple HIG / Material Design (touch targets) — 44×44 / 48×48 numbers.
+- accessibility (parent skill) — doctrine source; this skill is its execution arm.
+
+Strategy: distill. The doctrine lives in accessibility; this skill is the per-component operational gate.

package/core-assets/packs/pack-react/skills/void-accessibility-check/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: void-accessibility-check
+description: "Per-component accessibility checklist: semantic HTML, ARIA, keyboard, focus, contrast, touch targets. Auto-applies on any React component edit. Composes with accessibility."
+---
+
+# accessibility-check
+
+Use when creating or editing **any React component** in a `components/` directory. The 7-point checklist below is the gate — if a component ships violating any of these, it ships broken for somebody.
+
+Composes with `void-accessibility` (the generic doctrine and Radix-as-primitive philosophy). This skill is the **execution checklist** for one component.
+
+If the file is in `services/`, `adapters/`, or `domain/`, this skill does not apply (those are not UI).
+
+## When this skill triggers
+
+- New file under `apps/*/src/components/` or `packages/ui/src/`
+- Editing JSX in a component file
+- "Add a button that does X" / "make this a card" / any UI creation
+
+## The 7-point gate
+
+A component does not ship until all 7 are satisfied. Each one has an easy check + the lazy mistake to avoid.
+
+### 1. Semantic HTML
+
+Choose the tag that matches the role, before reaching for ARIA.
+
+- Action that submits or navigates → `<button>` or `<a>`, never `<div onClick>`.
+- Heading → `<h1>` to `<h6>` in document order, never `<div className="text-2xl font-bold">`.
+- List → `<ul>` / `<ol>` / `<li>`.
+- Form control → `<input>`, `<select>`, `<textarea>` with associated `<label>`.
+
+Lazy mistake: shadcn primitives wrap divs but expose the right role (via Radix). Always check the underlying element — `<DropdownMenuItem>` is keyboard-navigable because Radix sets `role="menuitem"`. Custom replacements lose that.
+
+### 2. Labels and names
+
+Every interactive element has a programmatic name accessible to screen readers.
+
+```tsx
+// ✓
+<button aria-label="Close dialog"><XIcon /></button>
+<label htmlFor="email">Email</label>
+<input id="email" type="email" />
+
+// ✗
+<button><XIcon /></button>                           // unnamed
+<input type="email" placeholder="Email" />           // placeholder is NOT a label
+```
+
+Lazy mistake: relying on placeholder text. Placeholders disappear on focus and don't announce as labels. Use a real `<label>` or `aria-label`.
+
+### 3. Keyboard navigation
+
+Every interactive element reachable by Tab, operable by Enter / Space, dismissible by Esc (for modals/menus).
+
+- Tab order follows visual order (avoid `tabIndex` ≥ 1).
+- `outline` is **never** stripped without a replacement focus ring (use a `:focus-visible` style).
+- Modals trap focus (Radix Dialog does this automatically; if you build a modal from scratch you must trap).
+
+Lazy mistake: `outline: none` in global CSS. The focus ring is the only signal a keyboard user has for where they are.
+
+### 4. Focus management on action
+
+When an action changes context (open modal, route to new page, reveal an error):
+
+- Modal opens → focus moves to the modal (Radix handles).
+- Modal closes → focus returns to the trigger (Radix handles).
+- Form submit with error → focus moves to the first invalid field, or to an error summary.
+- Route change → focus moves to the new page's `<h1>` (or main content) on Next.js soft navigation (manual via `next/navigation` `useRouter` + `useEffect`).
+
+Lazy mistake: forgetting to restore focus when a dialog closes — keyboard user lands at the top of the page.
+
+### 5. Contrast
+
+WCAG AA minimum:
+
+- Normal text: **4.5:1** against background.
+- Large text (≥ 18px bold or ≥ 24px): **3:1**.
+- Interactive elements (button borders, focus rings, form field borders): **3:1**.
+
+Quick checks:
+
+- The design tokens in `@repo/ui` should already meet AA. If you reach for a non-token color, justify it in a comment.
+- Disabled buttons are often the lazy violator (`opacity: 0.5` halves contrast).
+
+Lazy mistake: gray-on-gray placeholder text. Most placeholders are 2.5:1 — fail.
+
+### 6. Touch targets
+
+Minimum **44×44 CSS px** (iOS HIG) / **48×48 dp** (Material). Applies to anything tappable.
+
+```tsx
+// ✓ Tappable from @repo/ui enforces it
+<Tappable onPress={handlePress}><Icon /></Tappable>
+
+// ✗ Bare icon with 24px hitbox
+<button onClick={handlePress}><Icon size={24} /></button>
+```
+
+Lazy mistake: dense icon-only toolbars with 24-32px buttons. Fail on every phone.
+
+### 7. Motion and reduced motion
+
+Animations respect `prefers-reduced-motion`:
+
+```css
+@media (prefers-reduced-motion: reduce) {
+  * { animation-duration: 0.01ms !important; transition-duration: 0.01ms !important; }
+}
+```
+
+Or per-component via `useReducedMotion()` from Framer Motion.
+
+Lazy mistake: shipping a beautiful parallax that triggers vestibular nausea for ~3% of users.
+
+## Workflow
+
+For each new or edited component:
+
+1. **Run the 7-point gate mentally** before opening the JSX.
+2. If you're not sure what role the component plays, write one sentence first: "this is a button that submits a form" / "this is a heading announcing the section". The sentence dictates the tag.
+3. **Prefer Radix primitives** from `@repo/ui` over building from scratch — Radix gets roles, keyboard, focus right.
+4. **Run a Lighthouse a11y audit** on the route the component lands in (`pnpm dlx @lhci/cli` or DevTools). Target score: 100. Anything under 95 = block.
+5. **Manual keyboard test**: Tab through the component, Enter/Space/Esc as appropriate. If you have to use the mouse to operate it, it's broken.
+6. **Screen reader test on at least one new component per PR**: macOS VoiceOver (`Cmd+F5`), Windows NVDA, Android TalkBack, or iOS VoiceOver. You'll hear gaps immediately.
+
+## When AA is not enough
+
+`void-accessibility` floor is AA. AAA is sometimes the goal for **specific surfaces** (form errors, primary CTAs). It's not the project-wide default — declare it explicitly in `PROJECT-DOCTRINE.md` if so.
+
+## Composition
+
+- `void-accessibility` — the doctrine; this skill is the gate.
+- `void-frontend-design` — anti AI-slop, sober density, real visual hierarchy.
+- the `pack-react` doctrine module on components — components are pure UI (no DB, no fetch) which is itself an a11y win (less surface to break).
+- `void-tdd` — interactive components get jsdom tests asserting roles and keyboard behavior (`@testing-library/user-event`).

package/core-assets/packs/pack-react/skills/void-accessibility-check/harness.yaml

@@ -0,0 +1,14 @@
+# Harness metadata for this skill. Not part of the Agent Skills
+# specification, and never copied into a consumer project: the SKILL.md
+# beside it stays portable and validates against the official six fields.
+# Read by this repository's graph, and by the installer for `runtimes`.
+kind: standard
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: active
+    codex: active
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/packs/pack-react/skills/void-client-vs-server-component/.source

@@ -0,0 +1,5 @@
+Sources for `void-client-vs-server-component` skill (see `docs/plans/skill-audits/void-client-vs-server-component.md` for the full audit):
+
+- No external source audited — native skill authored for void-machine.
+
+Strategy: native. Codifies "server by default, client at the leaf" for React 19 / Next 14+ Server Components, a construct that does not exist in non-RSC stacks.