voidmachine 0.0.0 → 4.0.0

package/core-assets/skills/void-domain-driven-design/SKILL.md

@@ -0,0 +1,292 @@
+---
+name: void-domain-driven-design
+description: Bounded contexts, aggregates as consistency boundaries, value objects as branded types, always-valid domain, ubiquitous language. No CQRS, event sourcing, or generic Repository<T>. Use on the domain.
+---
+
+# domain-driven-design — voidcorp craftsman edition
+
+The data model does not drive the design. The domain does. Inside a bounded context, every word has one meaning. Aggregates enforce invariants. Value objects model semantic primitives. The code uses the words the team uses.
+
+**Attribution**: see `.source` in this directory. Foundation: Evans 2003, Vernon 2013, Wlaschin "Domain Modeling Made Functional," Stemmler TS adaptation, Khorikov.
+
+---
+
+## Strategic DDD — the vocabulary
+
+| Term | Definition |
+|---|---|
+| **Bounded Context** | A boundary inside which a model is valid and a language is consistent. One context = one module/package. |
+| **Ubiquitous Language** | The shared vocabulary inside a context. Code uses the same words stakeholders use. Diverging is a bug. |
+| **Context Map** | The graph of bounded contexts and their relationships (partnership, conformist, anti-corruption layer, ...). Documented in `docs/CONTEXT-MAP.md` for non-trivial systems. |
+| **Aggregate** | A cluster of objects treated as a single unit for consistency. The aggregate enforces its own invariants. |
+| **Aggregate Root** | The single entity through which the aggregate is accessed. The only thing repositories return. |
+| **Entity** | An object identified by its identity (UserId), not its attributes. Two entities with the same fields but different IDs are distinct. |
+| **Value Object** | An object identified by its attributes. Two value objects with the same fields are equal. Immutable. |
+| **Domain Service** | A stateless operation that does not fit any single aggregate (e.g., `TransferFunds` across two accounts). |
+| **Domain Event** | A typed record describing something that happened in the domain (`OrderConfirmed`, `UserSuspended`). Emitted by aggregates. |
+
+---
+
+## Bounded Context = unit of language
+
+Inside one context, `Order` means ONE thing. Across contexts, `Order` can mean different things — and that is fine, as long as the boundary translates.
+
+Example:
+
+- In the **Checkout** context, `Order` = a cart in the process of being paid.
+- In the **Fulfilment** context, `Order` = a list of items to ship.
+- In the **Accounting** context, `Order` = a revenue line on the ledger.
+
+These are three distinct types in three distinct packages. They share an ID (`OrderId`) and are translated at the boundary by an **anti-corruption layer** (an adapter that maps from one context's model to another's).
+
+The companion advisory hook `ubiquitous-language-lint` flags terms appearing in code but not in `docs/DOMAIN.md` (the per-context glossary).
+
+### Banned
+
+- Cross-context type imports (`import { Order } from '@/contexts/fulfilment'` from inside the checkout context). The boundary MUST go through an adapter.
+- A single shared `Order` type across all contexts. That is "Big Ball of Mud" by another name.
+
+---
+
+## Aggregates — consistency boundaries
+
+An aggregate is a transactional unit. Loading and saving happens at the aggregate root. Invariants inside the aggregate are ALWAYS true (by construction and by aggregate methods).
+
+### Small aggregates (Vernon's rule)
+
+Prefer many small aggregates referencing each other by ID over fewer large aggregates that load deep graphs. Default to small.
+
+<Good>
+```typescript
+// small aggregates
+class Order { id: OrderId; customerId: CustomerId; lineItems: LineItem[]; ... }
+class Customer { id: CustomerId; email: Email; ... }
+// Order does NOT contain the full Customer object — just the ID
+```
+</Good>
+
+<Bad>
+```typescript
+// large aggregate loading everything
+class Order {
+  customer: Customer;     // loads the customer's address book, preferences, ...
+  shipments: Shipment[];  // loads every shipment with carrier details
+  invoices: Invoice[];    // loads every invoice with line items
+  ...
+}
+// loading one Order from DB now requires N joins or N+1 queries
+```
+</Bad>
+
+### Always-valid domain model (Khorikov)
+
+```typescript
+class Order {
+  private constructor(
+    readonly id: OrderId,
+    private status: OrderStatus,
+    private items: LineItem[],
+  ) {}
+
+  static create(input: { items: LineItem[]; customerId: CustomerId }): Result<Order, ValidationError> {
+    if (input.items.length === 0) return err({ kind: 'empty_order' });
+    return ok(new Order(newOrderId(), 'draft', input.items));
+  }
+
+  confirm(): Result<void, OrderError> {
+    if (this.status !== 'draft') return err({ kind: 'not_draft', currentStatus: this.status });
+    this.status = 'confirmed';
+    return ok(undefined);
+  }
+}
+```
+
+- No public constructor (smart constructor `create`).
+- No setter `setStatus(s: string)` that accepts any value.
+- Every mutation goes through a method that preserves invariants and returns `Result`.
+
+### State machines as discriminated unions (alternative shape)
+
+For workflows with distinct shapes per state, prefer a discriminated union:
+
+```typescript
+type Booking =
+  | { kind: 'draft'; id: BookingId; partyOf: number }
+  | { kind: 'submitted'; id: BookingId; partyOf: number; submittedAt: IsoDate }
+  | { kind: 'confirmed'; id: BookingId; partyOf: number; confirmedAt: IsoDate; tableNumber: number }
+  | { kind: 'cancelled'; id: BookingId; reason: string; cancelledAt: IsoDate };
+```
+
+Transitions are functions: `submit(b: Booking & { kind: 'draft' }): Booking & { kind: 'submitted' }`. The compiler refuses to call `submit` on a `confirmed` booking. Composes with `void-typescript-strict` exhaustive switches and `void-functional` ADTs.
+
+### Heuristic: class vs discriminated union
+
+- Class for aggregates with many invariants and behavior methods (Order, Account)
+- Discriminated union for stateful workflows with distinct data per state (BookingFlow, SignupFlow)
+- Document the choice per aggregate in `docs/DOMAIN.md`
+
+---
+
+## Value objects — branded types with smart constructors
+
+A value object is identified by attributes. Two `Email`s with the same string are equal. Immutable.
+
+```typescript
+type Email = string & { readonly __brand: 'Email' };
+
+export function createEmail(raw: string): Result<Email, ValidationError> {
+  if (!EMAIL_REGEX.test(raw)) return err({ kind: 'invalid_email', raw });
+  return ok(raw as Email);
+}
+```
+
+Apply to every domain primitive: `UserId`, `OrgId`, `OrderId`, `Email`, `PhoneNumber`, `IsoDate`, `Money` (`{ amount: number; currency: CurrencyCode }`, with `CurrencyCode` itself branded).
+
+Composes with `void-typescript-strict` (branded type mechanics) and `void-functional` (smart constructors return `Result`).
+
+### Banned: raw primitives for things with semantics
+
+```typescript
+function transferFunds(from: string, to: string, amount: number) { ... }
+// BAD — nothing prevents transferFunds('alice@example.com', '42', -100)
+```
+
+```typescript
+function transferFunds(from: AccountId, to: AccountId, amount: Money): Result<void, TransferError> { ... }
+// GOOD — the compiler refuses raw strings; Money carries currency
+```
+
+---
+
+## Repositories — ports per aggregate, no generic `Repository<T>`
+
+A repository in DDD = a port in `void-hexagonal-architecture`. Named by what it does, methods specific to the aggregate's invariants.
+
+<Good>
+```typescript
+interface OrdersPort {
+  findById(id: OrderId): Promise<Result<Order, NotFoundError>>;
+  findByCustomer(customerId: CustomerId): Promise<Result<Order[], never>>;
+  save(order: Order): Promise<Result<void, ConflictError>>;
+  // NO `delete()` if orders are never deleted (audit constraint)
+}
+```
+</Good>
+
+<Bad>
+```typescript
+interface Repository<T> {
+  findById(id: string): Promise<T | null>;
+  findAll(): Promise<T[]>;
+  save(t: T): Promise<void>;
+  delete(id: string): Promise<void>;
+}
+// BAD — exposes operations the aggregate may not allow (`delete`); lies about success (`null` vs Result)
+```
+</Bad>
+
+---
+
+## Domain Services — multi-aggregate operations only
+
+A domain service is justified when the operation involves multiple aggregates.
+
+```typescript
+// domain service: TransferFunds across two Account aggregates
+export async function transferFunds(
+  deps: { accounts: AccountsPort; events: EventBusPort },
+  input: { from: AccountId; to: AccountId; amount: Money },
+): Promise<Result<TransferResult, TransferError>> {
+  // ... orchestration across two aggregates ...
+}
+```
+
+Single-aggregate operations are aggregate methods — `account.deposit(amount)`, not `AccountService.deposit(account, amount)`. Without this discipline, domain services become anemic dumping grounds.
+
+---
+
+## Domain Events — typed records emitted by aggregates
+
+```typescript
+type OrderEvent =
+  | { kind: 'OrderConfirmed'; orderId: OrderId; at: IsoDate }
+  | { kind: 'OrderCancelled'; orderId: OrderId; reason: string; at: IsoDate };
+```
+
+Aggregates collect events; use-cases dispatch them via an injected `EventBusPort` at the end of the transaction. Composes with `void-hexagonal-architecture` (event bus as a port).
+
+---
+
+## Banned by default
+
+### CQRS, event sourcing, mediator, generic `Repository<T>`
+
+All rejected per `.void/installed/PHILOSOPHY.md` Wing Chun. Re-introducing any of them is an ADR, written through the `void-decide` skill.
+
+### Anemic models (data + setters, logic elsewhere)
+
+Public setters on aggregate fields are forbidden. Mutations go through methods that preserve invariants.
+
+### Service classes named `*Manager`, `*Helper`, `*Util`
+
+Evans' anemic anti-patterns. A `UserManager` that holds `signUp`, `login`, `delete` is a domain service collection — split into named operations.
+
+### Cross-context type imports
+
+The anti-corruption layer (adapter) is mandatory. No direct import.
+
+---
+
+## Companion hooks
+
+- **`ubiquitous-language-lint`** (advisory) — flags code terms not in `docs/DOMAIN.md` (per-context glossary), and glossary terms not present in code. Informational; HITL decides. See `../../hooks/`.
+
+(The structural rules surface through `void-code-review` flags and `void-hexagonal-architecture`'s `boundary-direction-check` hook.)
+
+---
+
+## Composition with other skills
+
+- **`void-hexagonal-architecture`**: this skill decides what an aggregate IS; hex decides where it sits physically. Repositories are ports.
+- **`void-functional`**: aggregates as discriminated unions for stateful flows. Value objects as branded types + smart constructors returning `Result`. Always-valid domain.
+- **`void-typescript-strict`**: value objects ARE branded types. State machines ARE discriminated unions.
+- **`void-tdd`**: aggregate invariants are test-driven — each invariant is a test.
+- **`void-code-review`**: structure dimension flags anemic models, generic repositories, raw primitives, public setters.
+- **`void-refactor`**: refactors that touch aggregate boundaries (Extract Aggregate, Move Field across contexts) compose for the boundary decision.
+- **`void-security-guidance`**: anti-corruption layer at the context boundary is also a trust boundary.
+
+---
+
+## Anti-rules
+
+- MUST NOT prescribe CQRS / event sourcing / mediator / generic repositories by default.
+- MUST NOT decide tactical implementation shape (FP / OOP) inside an aggregate — `void-functional`'s call.
+- MUST NOT decide whether a sub-domain is Core / Supporting / Generic — product call, lives upstream.
+- MUST NOT decide framework / DB / queue — pack concerns.
+- MUST NOT silently allow cross-context type imports.
+- MUST NOT decide aggregate identity strategy (UUID / nanoid / DB-assigned) — pack provides default, consumer overrides.
+
+---
+
+## When you are stuck
+
+| Problem | Solution |
+|---|---|
+| Where does this aggregate sit? | Identify the bounded context. One context per package. Cross-context = anti-corruption adapter. |
+| Class or discriminated union? | Class for many-invariants + methods. Union for distinct-shape-per-state workflows. |
+| Should this be an aggregate or a value object? | Identity matters → entity / aggregate root. Pure attributes → value object. |
+| Aggregate growing too large | Apply small-aggregate rule. Reference other aggregates by ID, not by inclusion. |
+| Stuck naming | Use the stakeholders' word. If terminology is unclear, the domain is unclear — fix that first. |
+| Need to share data across contexts | Anti-corruption adapter at the destination context. No direct type import. |
+
+---
+
+## Final rule
+
+```
+Bounded contexts are independent. Aggregates are always valid.
+Value objects use branded types. The code speaks the team's language.
+Otherwise → it is not voidcorp DDD.
+```
+
+The domain is the heart. The technology is plumbing. Get the domain right and the rest follows.

package/core-assets/skills/void-domain-driven-design/harness.yaml

@@ -0,0 +1,15 @@
+# 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
+activation: always
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: pretooluse
+    codex: pretooluse
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/skills/void-frontend-design/.source

@@ -0,0 +1,19 @@
+Sources for `void-frontend-design` skill (see `docs/plans/skill-audits/void-frontend-design.md` for full audit):
+
+- Vercel `frontend-design` plugin (installed globally as `frontend-design:frontend-design`) — https://github.com/vercel-labs/agent-skills — vendored with void-machine additions (mobile-first dual-quality, matrix integration, shadcn composition)
+- citypaul/.dotfiles UI patterns — density, hierarchy notes
+- Refactoring UI (Adam Wathan + Steve Schoger) — book — foundation, density, hierarchy, motion principles
+- Apple HIG visual design chapter — https://developer.apple.com/design/human-interface-guidelines — mobile layout heuristics
+- Folpe DESIGN.md convention (per-project) — brand identity belongs in consumer DESIGN.md
+- pbakaus/impeccable-design — referenced by citypaul
+- impeccable (standalone skill) — VENDORED (DEV-389, build-time half): the current-AI-tell absolute bans (side-stripe, gradient-text, glassmorphism, hero-metric, eyebrow/numbered-markers, cream/sand body, text-overflow), the color-strategy commitment axis, and the type/layout/motion/interaction specifics. Its audit/critique/refine half went to the new `void-ui-review`; its browser runtime is deferred to Vague 4.
+- gstack /design-review — the Krug reading model (scan/satisfice/muddle) vendored here (DEV-389); its designer's-eye QA went to ui-review.
+
+Strategy: vendor-plugin + distill. Fork Vercel plugin for Void Machine invariant (mobile-first dual-quality) + matrix integration; DEV-389 enriched it with impeccable's build-time craft so the harness is self-contained on UI (no external impeccable dependency).
+
+Companion hooks: viewport-screenshot-gate (shared with accessibility), anti-ai-slop-grep.
+
+Stack-specific @repo/ui + design system tokens + Tailwind config in pack-nextjs-pwa.
+
+DEV-444 adaptation: consumes a fresh-context Experience Designer brief before build; independent
+post-build judgment remains downstream in ui-review and Visual Craft Director.

package/core-assets/skills/void-frontend-design/SKILL.md

@@ -0,0 +1,274 @@
+---
+name: void-frontend-design
+description: Anti-AI-slop UI. Density first, 3-size hierarchy, motion <250ms, components via @repo/ui (Radix/shadcn), mobile-first dual-quality. Brand from DESIGN.md. Use when building or modifying UI.
+---
+
+# frontend-design — voidcorp craftsman edition
+
+AI-generated UI tends to "vibe coded": blue-to-violet gradients, generic hero copy, low information density, mid hierarchy, motion as decoration. The result reads as generated. This skill encodes the discipline that breaks that pattern.
+
+Brand identity (palette, typography stack, motion language) lives in the consumer project's `DESIGN.md`. This skill imposes the DISCIPLINE that applies across all brand identities.
+
+**Attribution**: see `.source`. Foundation: Vercel `void-frontend-design` plugin + Refactoring UI + Apple HIG + citypaul UI notes; the current-AI-tell bans, color-strategy axis, and type/layout/motion specifics are vendored from `impeccable` (DEV-389); the Krug reading model from gstack `/design-review`.
+
+---
+
+## Mobile-first dual-quality
+
+Every UI is designed mobile-first AND must reach first-class quality on both viewports simultaneously. (Folpe rule, `.void/installed/PHILOSOPHY.md`.)
+
+- **Layout starts at 360–390px** (iPhone 12 mini → 15 Pro range), progressively enhanced wider.
+- **Never the reverse.** No "desktop-first then squeeze for mobile."
+- **Both viewports screenshot-reviewed before merge** — `viewport-screenshot-gate` hook (shared with `void-accessibility`).
+- **No mobile-only / desktop-only features** without an explicit decision recorded through the `void-decide` skill.
+- **Performance budget enforced for both**: LCP < 2.5s on slow 4G mobile AND on desktop fiber (measure with the project's perf tooling — Lighthouse CI, WebPageTest, bundlesize).
+
+---
+
+## Pre-build experience pass
+
+Before implementation, invoke `core:experience-designer` in a fresh read-only context with the
+ticket, product intent, `DESIGN.md`, and existing interface evidence. Its build brief names the IA,
+primary action, keyboard path, responsive intent, and applicable UI states. Missing or stale
+pre-build attestation blocks implementation. This skill consumes that brief and owns the build; it
+does not self-approve the post-build result.
+
+---
+
+## Anti-AI-slop — banned patterns
+
+### Banned copy
+
+- "Build faster, ship smarter"
+- "Ship 10× faster"
+- "Unlock your potential"
+- "Empower your team"
+- "Transform your workflow"
+- Generic CTA: "Get Started Free Forever"
+
+These signal "vibe coded" and lose user trust before the content is read. The companion hook `anti-ai-slop-grep` warns on these patterns in staged copy. Override per-string with explicit code review approval — the discipline is heuristic, the writer is final.
+
+### Banned visual patterns by default
+
+- Blue → violet / purple → pink gradient backgrounds as default decoration
+- Abstract 3D / blobs / orbs as primary hero visual
+- Lorem ipsum or placeholder text in shipped UI
+- Random ad hoc font sizes outside the 3-size system
+- Decorative animations longer than 250ms
+
+These are defaults. Brand can override via `DESIGN.md` if the brand justifies a specific pattern (e.g., a brand that legitimately uses a specific gradient). Override is documented; default is rejection.
+
+### Absolute bans — the current AI tells (match-and-refuse; vendored from impeccable)
+
+If you are about to write any of these, rewrite the element with different structure:
+
+- **Side-stripe borders** — a colored `border-left`/`border-right` > 1px on cards/alerts/list-items. Use a full border, a background tint, a leading number/icon, or nothing.
+- **Gradient text** — `background-clip: text` over a gradient. Use a single solid color; emphasize with weight or size.
+- **Glassmorphism as default** — decorative blur/glass cards. Rare and purposeful, or nothing.
+- **The hero-metric template** — an oversized figure over a tiny caption, flanked by supporting stats and a gradient flourish. The default SaaS landing scaffold; reach for a real layout instead.
+- **Uppercase tracked eyebrows above every section** and **numbered section markers (01 / 02 / 03) as default scaffolding.** One deliberate kicker or a real ordered sequence is voice; one on *every* section is AI grammar — pick a different cadence.
+- **The cream / sand / beige body background** — the warm-neutral band (OKLCH L 0.84-0.97, C < 0.06, hue 40-100) reading as paper/parchment is the saturated AI default of 2026, tell-tale even under names like `--cream`/`--sand`/`--linen`. Carry "warmth" through accent + type + imagery, not a warm-tinted near-white body.
+- **Text that overflows its container** at any breakpoint — long heading words + large `clamp()` + narrow grids. The viewport is part of the design; test heading copy at every width.
+
+---
+
+## Color strategy — commit before picking colors (vendored from impeccable)
+
+Pick a strategy on the commitment axis first; picking colors without one produces the timid default.
+
+- **Restrained** — tinted neutrals + one accent ≤ 10%. Product default.
+- **Committed** — one saturated color carries 30-60% of the surface. Identity-driven pages.
+- **Full palette** — 3-4 named roles, each used deliberately. Campaigns, data viz.
+- **Drenched** — the surface IS the color. Heroes, campaign pages.
+
+Use OKLCH. Dark vs light is never a reflex ("tools look cool dark", "light to be safe") — write one sentence of physical scene (who uses this, where, under what light, in what mood); if it doesn't force the answer, add detail until it does. Tint neutrals 0.005-0.015 toward the brand hue, never toward warm/cool "because it feels that way."
+
+---
+
+## Information architecture before visual design
+
+The discipline is structural FIRST:
+
+1. **What is the hierarchy?** What does the user need to read / do first, second, third?
+2. **What is the primary action?** Singular. The page exists to lead to this action.
+3. **What is supporting context?** Provided but recessed.
+4. **What is noise?** Cut.
+
+THEN visual:
+
+5. Typography expresses the hierarchy
+6. Color guides attention to the primary action
+7. Motion communicates state change, not entertainment
+
+AI-generated UI tends to skip the IA step and jump to visual. The result feels busy and unfocused.
+
+---
+
+## Density first
+
+Information density > whitespace by default. Whitespace earns its place via hierarchy, not as default.
+
+Generic AI output over-uses whitespace ("looks clean!") and under-uses density. Real users want to do work, not admire margins.
+
+**How users actually read** (Krug, *Don't Make Me Think* — vendored via design-review): they *scan*, not read; they *satisfice* (pick the first reasonable option, so make the right choice the most visible one); they *muddle through*. Design rule: "omit needless words, then omit again." The **mindless-click test** — every decision point should be an obvious click, not a puzzle the user has to solve.
+
+### Density heuristics
+
+- Lists with > 3 items: tabular, not card-grid-with-images.
+- Forms: compact, with inline labels when label space matches input width.
+- Dashboards: tabular metrics with sparklines. Cards only for genuinely independent objects.
+- Hero sections: useful from the first scroll. No 100vh splash without immediate value.
+
+---
+
+## Type hierarchy: 3 sizes max + weight + color
+
+The design system tokens (in `pack-nextjs`) expose exactly 3 type sizes:
+
+| Token | Use |
+|---|---|
+| `text-display` | Page hero, section header (rare) |
+| `text-heading` | Section title |
+| `text-body` | Everything else |
+
+Differentiation within `text-body` comes from weight (`font-medium`, `font-bold`) and color (`text-primary`, `text-muted`).
+
+### Specifics (vendored from impeccable)
+
+- Cap body line length at **65-75ch**.
+- Pair fonts on a **contrast axis** (serif + sans, geometric + humanist) or one family in multiple weights — never two similar-but-not-identical sans.
+- Display heading `clamp()` max **≤ 6rem** (above that the page is shouting), letter-spacing floor **≥ -0.04em** (tighter and letters touch).
+- `text-wrap: balance` on h1-h3; `text-wrap: pretty` on long prose.
+
+### Banned
+
+- Random custom font sizes (`text-[19px]`, `text-[27px]`, etc.) outside the token system
+- Five+ levels of heading hierarchy
+- Lowercase `text-xs` for body copy on mobile (under 14px is unreadable for many users)
+- **`system-ui` / `-apple-system` as the primary display or body font** — the "I gave up on typography" tell. Choose a real typeface.
+
+---
+
+## Color guides attention
+
+The primary action is the most saturated, most contrasted, most singular color on the screen. Everything else recesses.
+
+- ONE primary action color per view. Two competing primaries = no primary.
+- Secondary actions: muted, lower contrast.
+- Tertiary: ghost / link style.
+- Destructive: red — but reserve for actually destructive (delete, unsubscribe). Not for "Cancel."
+
+WCAG AA contrast minimum (composes with `void-accessibility` — 4.5:1 normal text, 3:1 large / UI components).
+
+---
+
+## Motion: purpose-driven, < 250ms, ease-out
+
+```css
+/* allowed */
+.dropdown-content { animation: slide-down 200ms ease-out; }
+
+/* banned */
+.hero-decoration { animation: float 8s ease-in-out infinite; }
+```
+
+Motion communicates state change. Not entertainment. Reserve for:
+
+- Opening / closing (modal, dropdown, drawer)
+- Affordance feedback (button press)
+- State transition (success, error)
+
+Duration: < 250ms. Easing: `ease-out` for entry, `ease-in` for exit. The design system (`pack-nextjs`) provides default tokens.
+
+`prefers-reduced-motion` respected — composes with `void-accessibility`. The design system handles by default.
+
+### Banned
+
+- Looping decorative animations
+- Bouncy easing on functional UI (`ease-in-out-back` etc.) — reserves for playful brands explicitly
+- Animations longer than 250ms unless documented (page transitions, intentional reveals)
+
+---
+
+## Layout & interaction craft (vendored from impeccable)
+
+- **Cards are the lazy answer** — use them only when they are truly the best affordance; nested cards are always wrong.
+- **Flexbox for 1D, Grid for 2D.** Don't reach for Grid when `flex-wrap` fits. Responsive grid without breakpoints: `repeat(auto-fit, minmax(280px, 1fr))`.
+- **Semantic z-index scale** (dropdown → sticky → modal-backdrop → modal → toast → tooltip). Never `999` / `9999`.
+- **Vary spacing for rhythm** — uniform spacing reads as a wireframe.
+- **Motion easing**: ease-out with exponential curves (quart / quint / expo); no bounce, no elastic on functional UI. Every animation needs a `prefers-reduced-motion` alternative (crossfade or instant).
+- **Reveal animations must enhance an already-visible default** — never gate content visibility on a class-triggered transition; it pauses on hidden tabs / headless renderers and the section ships blank.
+- **Dropdown clipping**: a `position: absolute` menu inside `overflow: hidden`/`auto` is clipped — use `<dialog>` / the popover API / `position: fixed` / a portal to escape the stacking context.
+
+---
+
+## Components from `@repo/ui`
+
+Composed with `void-accessibility`. No hand-rolled UI primitives:
+
+```tsx
+// banned
+<div className="px-4 py-2 bg-blue-500 rounded" onClick={...}>Submit</div>
+
+// preferred
+import { Button } from '@repo/ui';
+<Button variant="primary" onClick={...}>Submit</Button>
+```
+
+`@repo/ui` is shadcn-style — Radix base + Tailwind tokens + design system extension. Provided by `pack-nextjs`.
+
+---
+
+## Composition with other skills
+
+- **With `void-accessibility`**: a11y is a precondition. Shared mobile-first dual-quality invariant. Shared `viewport-screenshot-gate` hook.
+- **With `void-typescript-strict`**: component props strongly typed; discriminated unions for variants; no `any` in UI.
+- **With `void-code-review`**: dimensions `readability` and `correctness` include UI quality flags.
+- **With `pack-nextjs`**: provides `@repo/ui` + design system tokens + Tailwind config + shadcn preset matching this discipline.
+- **With `void-ui-review`**: the audit/critique ceiling to this build-time floor — it catches on an existing UI what this skill prevents while building. Downstream.
+- **With `core:experience-designer`**: the read-only pre-build brief upstream; this skill implements it without absorbing product or audit ownership.
+- **With `DESIGN.md`**: the brand contract (palette, type, motion, decisions) is UPSTREAM; this skill consumes it. The file is produced by `impeccable document`/`init` or authored by hand — the schema is the interface, not a gstack workflow.
+- **With `forge`** (voidcorp plugin): market recon, 12-dimension critique, and multi-variant design prompts live there (the design-shotgun/consultation exploration), bridged by the `docs/specs/` `source: forge` artifact contract, not a code dependency.
+
+---
+
+## Companion hooks
+
+- `viewport-screenshot-gate` (pre-PR on UI changes, shared with `void-accessibility`) — fails PRs lacking both mobile and desktop screenshots.
+- `anti-ai-slop-grep` (pre-commit) — warns on banned copy patterns. Initial list of ~10; grows from `void-learn` harness-gap feedback.
+
+See `../../hooks/`.
+
+---
+
+## Anti-rules
+
+- MUST NOT decide brand identity (colors / typography / motion language) — `DESIGN.md` per project owns.
+- MUST NOT do the audit/critique pass — that is `void-ui-review` (this skill is build-time; ui-review is audit-time).
+- MUST NOT permit hand-rolled UI primitives.
+- MUST NOT skip dual-viewport verification.
+- MUST NOT silently allow banned copy / banned visual patterns.
+
+---
+
+## When you are stuck
+
+| Problem | Solution |
+|---|---|
+| Layout looks generic | Density audit. Information architecture first. Cut what does not earn its place. |
+| Hero feels weak | Singular primary action. Recess everything else. Cut decorative gradient if generic. |
+| Too many font sizes | Reduce to the 3-token system. Vary by weight and color. |
+| Motion feels excessive | Cut decorative animations. Keep only state-change communication. |
+| Mobile screenshot fails | Layout was desktop-first. Restart at 360–390px. |
+| Cannot reach AA contrast | Design system token failure. Adjust palette tokens, not per-component overrides. |
+
+---
+
+## Final rule
+
+```
+Every UI → IA first, density first, 3-size hierarchy, motion <250ms, @repo/ui components, dual-viewport verified, brand-from-DESIGN.md.
+Otherwise → it is not voidcorp frontend-design.
+```
+
+AI generates infinite UI. The discipline is what makes ours stop looking generated.

package/core-assets/skills/void-frontend-design/harness.yaml

@@ -0,0 +1,17 @@
+# 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: action
+activation: always
+triggers:
+  extensions: ["tsx"]
+owner: folpe
+runtimes: [claude, codex]
+enforcement:
+  floor: ci
+  inline:
+    claude: pretooluse
+    codex: pretooluse
+    hermes: ci-only
+eval_targets: [claude/anthropic/opus]

package/core-assets/skills/void-functional/.source

@@ -0,0 +1,14 @@
+Sources for `void-functional` skill (see `docs/plans/skill-audits/void-functional.md` for full audit):
+
+- Scott Wlaschin "Domain Modeling Made Functional" — https://pragprog.com/titles/swdddf — DDD + FP synthesis, Result for railway-oriented programming
+- Mark Seemann "Code That Fits in Your Head" — FP discipline, complexity budget, command-query separation
+- Gary Bernhardt "Functional Core, Imperative Shell" — DCDC 2012 talk — mental model
+- Vlad Khorikov "Enterprise Craftsmanship" — Result alternative to exceptions, immutability rationale
+- citypaul/.dotfiles fp notes — pragmatic FP-in-TS without Effect-TS
+- fp-ts — https://gcanti.github.io/fp-ts/ — referenced, NOT vendored as default
+- Effect-TS — https://effect.website — referenced as future opt-in pack, NOT default
+- Eric Normand "Grokking Simplicity" — calculations vs actions framing
+
+Strategy: distill. Reject Effect-TS / fp-ts / point-free / monad transformers as defaults. Standardize Result<T, E> + Option<T> + pipe helpers in @voidcorp/core (≤ 50 LOC total).
+
+Companion hook: no-null-grep (warn on null in domain code).