@event4u/agent-config 9.16.0 → 9.18.0

package/dist/agent-src/skills/design-review/references/verification-automation.md

@@ -0,0 +1,61 @@
+# design-review — verification automation
+
+> Section-level entry point of the `design-review` skill (progressive
+> disclosure, 2026-08-04). Content moved VERBATIM from SKILL.md —
+> load this file when the section index in SKILL.md routes here.
+
+## Visual QA with browser automation
+
+When Playwright MCP or browser tools are available, use them for automated visual verification:
+
+### Before/After comparison
+
+1. **Capture baseline** — screenshot before changes at all 3 viewports.
+2. **Apply changes** — deploy or hot-reload.
+3. **Capture after** — screenshot at the same viewports and states.
+4. **Compare** — visually diff the screenshots, flag regressions.
+
+### State-based verification
+
+Don't just screenshot the default state. Capture:
+
+| State | How to trigger |
+|---|---|
+| Empty | Remove data, check empty state UI |
+| Loading | Throttle network, capture skeleton/spinner |
+| Error | Force an error response, check error UI |
+| Overflow | Add very long text, many items |
+| Interactive | Hover, focus, open dropdowns |
+
+### Mockup-to-code verification
+
+When implementing from a design mockup or screenshot:
+
+1. **Open the mockup** — use the provided image/screenshot.
+2. **Implement** — build the UI component.
+3. **Side-by-side** — compare mockup vs. implementation at the same viewport.
+4. **Flag deviations** — spacing, colors, typography, alignment differences.
+
+This is especially useful when the user provides a screenshot or Figma export as a reference.
+
+## Async-verifier pattern (keep the main context clean)
+
+For a review that needs browser probing, use an **async background verifier**
+rather than self-screenshotting inline: fork a verifier subagent with its own
+view — it takes the screenshots, probes viewports, and checks states, then
+**stays silent on pass and surfaces only real, actionable problems** (never
+nitpicks). The main agent does not self-screenshot, so its context stays clean
+for the actual review reasoning. This is an orchestration pattern —
+dispatch it via [`subagent-orchestration`](../subagent-orchestration/SKILL.md)
+and position it against [`verify-repair-loop`](../verify-repair-loop/SKILL.md)
+(the existing verify skill); it complements them, it does not duplicate them.
+
+**Why the audit passes stay serial (not a parallel-4 fan-out).** A fan-out of
+a11y + slop + hierarchy + states across four subagents was evaluated and
+deferred: the passes share one live browser/navigation session and later phases
+build on state established by earlier ones, so they are not cleanly independent;
+and the expensive part — browser probing / screenshots — is already offloaded by
+the async verifier above, which captures the fan-out's main win without spinning
+up four separate views. Reconsider only when `design-review` runs as a standalone
+heavy batch over many *independent* surfaces, where per-surface
+`do-in-parallel` genuinely pays.

package/dist/agent-src/skills/existing-ui-audit/SKILL.md

@@ -234,6 +234,14 @@ violations will surface as new findings on every run.
 2. Verify `state.ui_audit.greenfield == true` implies `state.ui_audit.greenfield_decision` is set.
 3. Write the full object back into the state-file. Audit completes with outcome `done` — the dispatcher's audit gate now passes.
 
+## Section index — load on demand
+
+Load on demand once the audit needs the pitfall catalog:
+
+- [`references/anti-slop-cross-reference.md`](references/anti-slop-cross-reference.md) — Anti-slop cross-reference
+
+- [`references/output-and-pitfalls.md`](references/output-and-pitfalls.md) — Output format · Gotcha · Anti-slop cross-reference
+
 ## Output format
 
 1. **`state.ui_audit.components`** — array of component/template descriptors (path, name, kind, exports)
@@ -273,33 +281,6 @@ tool produces, so the import path is uniform.
   that run are absent from the inventory the later ones are checked against.
   Adding a second component in the same run → re-read the component directories
   directly rather than trusting `state.ui_audit.components_found`.
-
-## Anti-slop cross-reference
-
-When the audit inventory reveals an existing aesthetic direction (dominant color
-scheme, border-radius convention, motion patterns), cross-check the findings
-against
-[`docs/guidelines/design-antipatterns.md`](../../../docs/guidelines/design-antipatterns.md).
-If the existing UI already uses a listed anti-pattern, surface it as a design-debt
-finding (separate from the reuse inventory) — flag by entry ID and severity.
-
-**What the design step may then do depends on whose aesthetic it is.** These
-are two different situations and the sentence that used to cover both was
-wrong about one of them:
-
-| The anti-pattern lives in… | The design step may… |
-|---|---|
-| **The consumer's own legacy UI** (inventoried from the repo) | continue it for consistency, **or** propose a corrective direction change. Both are legitimate; it is their codebase and their debt. |
-| **A supplied spec** (a handed-over artifact, a `design-system.json`, a registered brand token) | **neither.** Build it as given. The finding is recorded as informational, marked `artifact_covered`, and no polish round acts on it. |
-
-A corrective direction change against a supplied spec is not a design
-improvement, it is overriding a decision the user already made — the failure
-[`design-fidelity`](../../rules/design-fidelity.md) exists to prevent, arriving
-through the audit's side door. Precedence and its exact scope:
-[`design-fidelity-mechanics`](../../../docs/guidelines/design-fidelity-mechanics.md)
-§ Provided-artifact precedence. Where the two sources disagree, surface the
-conflict rather than picking (fixture `daf-slop-vs-provided`).
-
 ## Do NOT
 
 - Do NOT advance to `directives/ui/design.ts` or `apply.ts` if `state.ui_audit` is empty.

package/dist/agent-src/skills/existing-ui-audit/references/anti-slop-cross-reference.md

@@ -0,0 +1,31 @@
+# existing-ui-audit — anti-slop cross-reference
+
+> Section-level entry point of the `existing-ui-audit` skill (progressive
+> disclosure, 2026-08-04). Content moved VERBATIM from SKILL.md —
+> load this file when the section index in SKILL.md routes here.
+
+## Anti-slop cross-reference
+
+When the audit inventory reveals an existing aesthetic direction (dominant color
+scheme, border-radius convention, motion patterns), cross-check the findings
+against
+[`docs/guidelines/design-antipatterns.md`](../../../../docs/guidelines/design-antipatterns.md).
+If the existing UI already uses a listed anti-pattern, surface it as a design-debt
+finding (separate from the reuse inventory) — flag by entry ID and severity.
+
+**What the design step may then do depends on whose aesthetic it is.** These
+are two different situations and the sentence that used to cover both was
+wrong about one of them:
+
+| The anti-pattern lives in… | The design step may… |
+|---|---|
+| **The consumer's own legacy UI** (inventoried from the repo) | continue it for consistency, **or** propose a corrective direction change. Both are legitimate; it is their codebase and their debt. |
+| **A supplied spec** (a handed-over artifact, a `design-system.json`, a registered brand token) | **neither.** Build it as given. The finding is recorded as informational, marked `artifact_covered`, and no polish round acts on it. |
+
+A corrective direction change against a supplied spec is not a design
+improvement, it is overriding a decision the user already made — the failure
+[`design-fidelity`](../../rules/design-fidelity.md) exists to prevent, arriving
+through the audit's side door. Precedence and its exact scope:
+[`design-fidelity-mechanics`](../../../../docs/guidelines/design-fidelity-mechanics.md)
+§ Provided-artifact precedence. Where the two sources disagree, surface the
+conflict rather than picking (fixture `daf-slop-vs-provided`).

package/dist/agent-src/skills/fe-design/SKILL.md

@@ -73,297 +73,12 @@ implementation skill, not from here.
 > present an ungrounded pick as grounded, and never record a missing pack as
 > an evidence gap.
 
-## Component Architecture
+## Section index — load on demand
 
-### Page structure (universal shape)
+Load the reference file whose sections the task needs — never all of them by default:
 
-```
-Page layout
-├── Header (static)
-├── Navigation (interactive — active state)
-├── Content area
-│   ├── Page heading + actions (static)
-│   ├── Filters (interactive — reactive)
-│   ├── Data display (interactive — table / cards)
-│   └── Pagination (interactive)
-└── Footer (static)
-```
-
-The stack-specific mapping (Blade partial vs. Livewire component vs.
-React island vs. Vue SFC) is the apply-step's concern, not this skill's.
-
-### When to use what (kind, not framework)
-
-| Kind | When | Example |
-|---|---|---|
-| **Static partial** | No interactivity, server-rendered only | Header, footer, static info |
-| **Reusable UI component** | Props-only, no state | Button, badge, card shell |
-| **Stateful component** | Needs server interaction or local state | Forms, tables, filters |
-| **Library primitive** | Standard UI from a design system | Modal, dropdown, input, toast |
-| **Client-only micro-interaction** | No server roundtrip needed | Toggle, accordion, clipboard |
-
-### Component granularity
-
-- **One stateful component per concern** — don't build mega-components.
-- **Compose with reusable UI components** for shared shells, headers, fields.
-- **Use the project's library primitives first** — never rebuild what the design system already provides (audit findings tell you which).
-- **Extract when used 3+ times** — DRY applies to UI too.
-- **Component workshop when the project is large enough** — for a real, growing shared-component library, isolate and document each reusable component in a component workshop so it stays discoverable and reused, not re-invented; skip it for a small surface of one-offs. Tool-specific setup is a carve-out (Storybook et al.) — see the implementation skill (e.g. [`react-shadcn-ui`](../react-shadcn-ui/SKILL.md) § Component workshop), never a generic mandate.
-
-## Form Design
-
-### Principles
-
-1. **Labels always visible** — no placeholder-only inputs
-2. **Validation on blur + submit** — immediate feedback, not on every keystroke
-3. **Error messages below the field** — red text, specific message
-4. **Required fields marked** — asterisk (*) or "(required)" label
-5. **Logical grouping** — related fields in sections with headings
-6. **Primary action prominent** — submit button stands out, cancel is secondary
-
-### Layout patterns
-
-| Fields | Layout | When |
-|---|---|---|
-| 1–3 fields | Single column | Simple forms (login, search) |
-| 4–8 fields | Two columns on desktop, single on mobile | Standard CRUD forms |
-| 8+ fields | Sections with headings or tabs/steps | Complex entity forms |
-| Related pairs | Side by side (first/last name, city/zip) | Logically paired fields |
-
-### Multi-step forms
-
-```
-Step indicator (1 — 2 — 3)
-├── Step 1: Basic info     → Next
-├── Step 2: Details        → Back / Next
-└── Step 3: Review + Submit → Back / Submit
-```
-
-- Show progress indicator (step numbers or progress bar)
-- Allow going back without losing data
-- Validate each step before allowing next
-- Show summary on final step
-
-## Table Design
-
-### Principles
-
-1. **Right-align numbers** — easier to compare
-2. **Left-align text** — natural reading direction
-3. **Sortable columns** — click header to sort
-4. **Sticky header** — visible when scrolling long tables
-5. **Row actions** — edit/delete as icon buttons or dropdown menu
-6. **Empty state** — helpful message when no data, not just blank
-
-### Responsive tables
-
-| Screen | Strategy |
-|---|---|
-| Desktop (≥1024px) | Full table with all columns |
-| Tablet (768–1023px) | Hide less important columns |
-| Mobile (<768px) | Card layout or horizontal scroll |
-
-### Pagination
-
-- Default: 25 rows per page
-- Show total count: "Showing 1–25 of 142"
-- Allow page size change (10, 25, 50, 100)
-- Prefer server-side pagination — avoid loading the full set client-side
-
-## Responsive Strategy
-
-### Breakpoints (Tailwind reference scale)
-
-| Prefix | Min width | Target |
-|---|---|---|
-| `sm:` | 640px | Large phones |
-| `md:` | 768px | Tablets |
-| `lg:` | 1024px | Small laptops |
-| `xl:` | 1280px | Desktops |
-| `2xl:` | 1536px | Large screens |
-
-### Mobile-first approach
-
-1. Design for mobile first (default styles)
-2. Add complexity at larger breakpoints
-3. Test at each breakpoint, not just desktop
-
-### Common patterns
-
-| Element | Mobile | Desktop |
-|---|---|---|
-| Navigation | Hamburger menu | Sidebar or top nav |
-| Forms | Single column | Two columns |
-| Tables | Cards or scroll | Full table |
-| Actions | Bottom sheet / FAB | Inline buttons |
-| Filters | Collapsible panel | Sidebar or inline |
-
-## Accessibility (a11y)
-
-### Minimum requirements
-
-- **Color contrast:** 4.5:1 for text, 3:1 for large text (WCAG AA)
-- **Keyboard navigation:** All interactive elements reachable via Tab
-- **Focus indicators:** Visible focus ring on all focusable elements
-- **Alt text:** All meaningful images have descriptive alt text
-- **ARIA labels:** Interactive elements without visible text need `aria-label`
-- **Semantic HTML:** Use `<button>`, `<nav>`, `<main>`, `<form>` — not `<div>` for everything
-
-### Common mistakes
-
-| Mistake | Fix |
-|---|---|
-| `<div onclick>` | Use `<button>` |
-| Color-only status | Add icon or text alongside color |
-| Missing form labels | Add `<label for="...">` |
-| Auto-playing content | Provide pause/stop control |
-| Tiny click targets | Min 44×44px touch target |
-
-## Motion — decision-tree and rationale
-
-Before adding any animation to a UI element, run through this decision tree:
-
-**1. Should this animate at all?**
-- Used 100+ times per day (keyboard shortcut, command palette)? **No animation. Why:** animations on high-frequency interactions feel sluggish; users wait for them on every invocation. Raycast has no open/close animation by design.
-- Triggered by user action with visible result (button → state change)? **Micro-feedback only (< 160ms).** Why: quick enough to feel instant, visible enough to confirm the action.
-- Modal/overlay/sheet entering/exiting? **Animate. Why:** position change needs motion to maintain spatial continuity.
-- Background process with no user action? **No animation.** Why: unexplained motion is disorienting.
-
-**2. Which easing?**
-- Entering (element appearing)? **ease-out** (starts fast, slows to rest). Why: the element arriving quickly signals responsiveness; the deceleration feels natural as it settles.
-- Exiting (element disappearing)? **ease-in** (starts slow, accelerates out). Why: the reverse is true — fast exit signals completion.
-- **Never ease-in for entering elements.** Why: ease-in delays the initial movement — the exact moment the user is watching most closely — making it feel slow even at the same total duration.
-- **Never bounce or elastic easing in UI.** Why: bounce draws attention to the animation itself, not the content; it feels dated.
-
-**3. How long?**
-- Button/micro-feedback: 100–160ms. Tooltip: 100ms. Dropdown open: 150–200ms. Modal: 200–350ms. Page transition: 300–500ms. Above 500ms: almost never.
-- **Never animate layout properties** (width, height, top, left, padding). Why: triggers browser layout recalculation on every frame; always solvable with `transform`.
-- **Always add `@media (prefers-reduced-motion: reduce)`** — gentler animation (reduced distance/opacity), NOT display:none. Why: vestibular disorders make motion UI unusable; reducing is better than removing.
-
-**4. What to animate?**
-Animate `transform` and `opacity` only. Why: these run on the GPU compositor thread, not the main thread; they never trigger layout or paint.
-`scale(0)` → `scale(1)` is wrong. Why: nothing in the real world appears from nothing. Use `scale(0.95)` + `opacity: 0` → `scale(1)` + `opacity: 1` instead.
-
-## UX Principles
-
-1. **Feedback** — Every action gets a response (toast, loading state, success message). **Why:** users interpret no feedback as failure.
-2. **Forgiveness** — Undo beats confirmation dialogs. Users click through confirmations mindlessly. **Why:** remove destructively then show undo toast; actually delete after toast expires.
-3. **Consistency** — Same patterns for same interactions across the app. **Why:** predictability reduces cognitive load; inconsistency forces users to re-learn.
-4. **Progressive disclosure** — Show basics first, details on demand. **Why:** premature complexity overwhelms; reveal information as it becomes relevant.
-5. **Loading states** — Skeleton screens preferred over spinners. **Why:** skeletons reduce perceived wait time by showing structure immediately.
-6. **Error recovery** — Clear error messages with suggested actions. **Why:** "something went wrong" gives the user nothing to do; a specific message with a next step reduces support burden.
-
-## Craft details — typography & imagery
-
-- **`text-wrap: pretty` on body copy** — avoids widows/orphans without manual
-  breaks; cheap, no layout risk. (Display headlines: `text-wrap: balance`.)
-- **Honest placeholders over weak assets** — when the real image/illustration
-  is missing, use a striped placeholder with a monospace size label
-  (`repeating-linear-gradient(45deg, #E5E5E5 0 10px, #F5F5F5 10px 20px)` +
-  `product shot (1200×800)`) instead of a hand-drawn SVG or stock-ish filler.
-  A placeholder signals "asset needed"; a weak illustration signals nobody
-  had the asset. Never Lorem-ipsum copy in review-bound output
-  (per `output-discipline`) — use short label-style skeleton copy.
-
-## Presenting variants
-
-This skill produces ONE refined solution by default. **Plan the variation
-decision before generating** — do not reflexively emit one generic design when
-exploration was asked, nor spam options when one production answer was asked.
-
-- **Decide whether to vary (ask only if ambiguous).** For ambiguous creative
-  work, decide the variation count and the axis that varies — visual direction,
-  UX flow, interaction model, copy, density, or brand strictness. Ask about
-  count + axis only when the choice changes the work materially; for a clear
-  implementation task, proceed with one answer. (fixture: `daf-requested-variations`.)
-- **Variation floors.** When the user asks to explore, produce **two to three
-  meaningfully different** options along the stated axis — different *decisions*,
-  not the same layout recoloured. When the user asks for one production answer,
-  produce one; no decorative option spam. (fixtures: `daf-requested-variations`,
-  `daf-unwanted-variations`.)
-- **Canvas / exploration contract (host-neutral).** Presenting side-by-side
-  concepts: give each a **stable frame label**, keep frames flat (no nested
-  cards), use generous spacing, and — on tools with a canvas — export-safe
-  coordinates so the layout survives export. Same labelled-frames shape whether
-  the host has a real canvas or just stacked sections.
-- **Cost / UX tie-breaker.** Ask about the axis only when it changes the work
-  materially; otherwise choose a strong default and **document the axis used in
-  the handoff** ("explored along visual-direction; density held constant").
-
-Hand off the actual variation **mechanics** — the basic→bold method and the
-single-file tweak-panel (CSS custom properties + floating "Tweaks" panel +
-`localStorage`) — to [`design-variations`](../design-variations/SKILL.md): this
-section owns the *planning decision*, that skill owns the *execution*.
-
-## Cross-task design memory — read DESIGN.md / PRODUCT.md first
-
-Before applying any heuristics from this reference, check the project root
-for `DESIGN.md` and/or `PRODUCT.md` (written by `design-system-capture`):
-
-- `DESIGN.md` present → use its captured radius/shadow/motion/spacing as
-  project constraints. The heuristics in this skill are **fallbacks for
-  gaps**, not overrides for captured decisions.
-- `PRODUCT.md` present → honor its interaction patterns (empty-state approach,
-  mutation feedback policy, filter persistence) in any UI design that touches
-  those surfaces.
-
-Flag any new decision for future capture: *"This establishes a new pattern —
-suggest adding to PRODUCT.md: [pattern description]."*
-
-## Register — brand vs product
-
-Before applying heuristics, determine the register (see
-[`docs/guidelines/design-modes.md`](../../../docs/guidelines/design-modes.md)):
-brand mode (impression-first) vs product mode (task-first). Form-heavy, table-heavy,
-and dashboard surfaces are almost always product mode — favour the standard
-patterns in this skill (Form Design, Table Design) over expressive variance.
-Marketing/landing surfaces are brand mode — let the Aesthetic-direction section
-commit to a deliberate, distinctive direction.
-
-## Design Read — articulate intent before generating
-
-When this reference is cited for a UI planning task, emit one line declaring
-the design read before any heuristics are applied:
-
-```
-Reading this as: <page-kind> for <audience>, <vibe> language, leaning <design-system>.
-```
-
-**If context is incomplete:** state so and proceed exploratory — do NOT block.
-
-**Anti-Default Discipline:** Before committing to any layout or component
-pattern, cross-check your first impulse against
-[`design-antipatterns.md`](../../../docs/guidelines/design-antipatterns.md) —
-the L1/L2 "AI landing page" layout (centered hero + 3-column grid + CTA), the
-V1 side-stripe card, the T7 default-font pick, and V2 decorative glassmorphism.
-If a tell was the first impulse, choose a different approach or explicitly
-justify why this brief calls for it. (The full pre-proposal scan is under
-*Anti-slop discipline* below.)
-
-**Carve-out — a supplied artifact is the spec, not a first impulse.** This
-discipline governs what *you* reach for. When the user hands over a finished
-artifact, the choices it makes are not your impulses and the justify-or-change
-burden does not apply to them: build them as given. The carve-out is scoped to
-decisions the artifact actually covers — anything it leaves open (a state it
-never shows, a surface it never had) is your first impulse again and gets the
-full scan. See
-[`design-fidelity-mechanics`](../../../docs/guidelines/design-fidelity-mechanics.md)
-§ Provided-artifact precedence.
-
-## Aesthetic direction
-
-Audit-pinned tokens and components always take precedence (see `existing-ui-audit`). When the audit pins an aesthetic, honor it without deviation. When the audit shows **no pinned aesthetic** — greenfield surface, marketing landing page, brand-new feature without design-system precedent — the design brief is allowed (and expected) to commit to a deliberate direction instead of defaulting to safe centered hero + 3-column features + CTA.
-
-Typography pairings (73 curated heading/body combinations with Google
-Fonts URLs + Tailwind config) and icon-system guidance (104 Phosphor
-entries with import code) come grounded from
-[`design-intelligence`](../design-intelligence/SKILL.md)
-(`--domain typography`, `--domain icons`) — query before picking from
-memory.
-
-Pick one direction up front and let composition, typography, and color follow from it. Avoid the "neutral AI default": uniform grid, system fonts as the visible body face, purple-to-blue gradients on white, predictable spacing. A direction that fits the brand intent (editorial / brutalist / refined / playful / retro / maximal / minimal / etc.) and is consistent across the page beats hedging.
-
-Surface the chosen direction in the design brief as a one-line statement (e.g. `aesthetic: editorial-magazine — asymmetric grid, serif display + sans body, generous gutters`). The apply step (`react-shadcn-ui` / `blade-ui` / `livewire` / `flux`) reads this line and matches typography, spacing, and motion to it; if no line is present, the apply step uses project defaults.
+- [`references/design-patterns.md`](references/design-patterns.md) — Component Architecture · Form Design · Table Design · Responsive Strategy · Accessibility (a11y) · Motion — decision-tree and rationale · UX Principles · Craft details — typography & imagery · Presenting variants
+- [`references/design-read-and-memory.md`](references/design-read-and-memory.md) — Cross-task design memory — read DESIGN.md / PRODUCT.md first · Register — brand vs product · Design Read — articulate intent before generating · Aesthetic direction
 
 ## Procedure