@event4u/agent-config 7.1.0 → 7.3.0

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

@@ -9,6 +9,7 @@ workspaces:
   - engineering
 packs:
   - frontend-design
+token_budget_class: rich
 trust:
   level: professional
 install:
@@ -48,6 +49,80 @@ Provenance + licenses: [`ATTRIBUTION.md`](ATTRIBUTION.md); manifest:
   layout pattern / chart type / icon system fits this product.
 - Stack-idiom lookup before writing UI code (`--stack` axis).
 
+## Cross-task design memory — read DESIGN.md / PRODUCT.md first
+
+Before running the corpus grounding or producing any design brief, check
+the project root for `DESIGN.md` and/or `PRODUCT.md` (written by
+`design-system-capture`). If they exist:
+
+1. Read `DESIGN.md` — apply its captured visual decisions (radius, shadows,
+   motion, spacing) as **project constraints** that take precedence over
+   corpus suggestions. The corpus fills gaps; DESIGN.md overrides.
+2. Read `PRODUCT.md` — note interaction patterns that affect the design
+   (e.g., destructive-action policy, empty-state approach) so the brief
+   is consistent with existing product conventions.
+3. After generating the design brief: if a decision was made that isn't yet
+   in DESIGN.md (e.g., chose a specific shadow for a new elevated surface),
+   flag it for capture: *"Suggest adding to DESIGN.md: elevated surface shadow = …"*
+
+Boundary vs `brand-to-tokens`/`.tokens.json`:
+- `.tokens.json` = primitive definitions (gray-700 = #374151)
+- `DESIGN.md` = usage decisions (elevated surfaces use the gray-700 shadow, 8px radius)
+Both are consumed; DESIGN.md takes precedence for usage questions.
+
+## Register — brand vs product
+
+Determine the design register before grounding (see
+[`docs/guidelines/design-modes.md`](../../../docs/guidelines/design-modes.md)):
+**brand mode** ("the impression IS the product" — marketing, landing, consumer
+first-impression) prioritizes distinctive selection; **product mode** ("design
+serves the task" — dashboard, admin, workflow) prioritizes earned familiarity
+and accessibility. The register changes which corpus selections are appropriate
+(distinctive palette/typography in brand mode; predictable, semantic in product
+mode). State the register in the Design Read line below.
+
+## Design Read — articulate intent before generating
+
+Before producing any design brief or making any style selection, emit one
+line that declares the design read:
+
+```
+Reading this as: <page-kind> for <audience>, <vibe> language, leaning <design-system>.
+```
+
+Examples:
+- `Reading this as: SaaS dashboard for internal ops teams, functional language, leaning Radix/shadcn.`
+- `Reading this as: marketing landing for B2C consumer product, playful editorial, leaning custom tokens.`
+- `Reading this as: admin panel for technical users, dense/utilitarian language, leaning data-grid primitives.`
+
+**If context is incomplete:** state so and proceed exploratory — *"Design context incomplete: no audience defined; proposing exploratory direction, expect revision after audience is clarified."* Do NOT block on missing context; do NOT prompt the user with a gate; state the gap and continue.
+
+**Anti-Default Discipline — first-impulse check:** Before committing to any design direction, verify you are NOT defaulting to:
+- Purple/violet + cyan-on-dark gradient palette (AI color cliché)
+- Centered hero over a dark gradient mesh with a single CTA
+- Three equal-weight feature cards in a grid
+- Inter or Space Grotesk as the uncritical body font choice
+- "Premium consumer" cream/sand background + brass/clay accents
+
+If any of these was the first impulse, name a different direction or explicitly justify why this brief genuinely calls for it.
+
+## Honesty / real-system grounding
+
+When the brief maps to an official design system (Material Design, Fluent,
+Carbon, Polaris, GOV.UK, shadcn, Tailwind UI, Radix, etc.):
+
+1. **Install the real package** — do not hand-recreate its CSS or components.
+   Surface the install command for the project's package manager (the
+   system's official package, e.g. the shadcn CLI or the `@mui/material`
+   distribution) and link the canonical documentation URL.
+2. **Never label an approximation as the official system.** If generating
+   approximate CSS for a system the project does not yet depend on, label it
+   explicitly: *"Approximation of Material Design elevation — not the official
+   `@mui/material` package; install the package for production use."*
+3. **If no official system is relevant:** pick a deliberate creative direction
+   (see Design Read above); never fall back to an unnamed generic aesthetic
+   (per `source-discovery-gate`: real source before guessing).
+
 ## Procedure: Produce a grounded design brief (`ui-design-brief` rebound)
 
 1. **Ground** (one call — engine runs the manifest's plan
@@ -170,6 +245,27 @@ guidance + docs URLs from here instead of memory.
 - Keep queries product-shaped ("fintech dashboard", "luxury e-commerce
   mobile") — the detect map routes generic words to `style`.
 
+## Anti-slop discipline
+
+Before finalizing any design brief, cross-check against
+[`docs/guidelines/design-antipatterns.md`](../../../docs/guidelines/design-antipatterns.md)
+— especially the Color (C1–C5), Typography (T7–T8), and Layout (L1–L2) sections.
+If the grounded corpus selection lands on a pattern in the catalog, either invoke
+the override condition or adjust the selection. Run the AI-slop originality
+self-test (catalog § "The AI-slop originality self-test") on the chosen aesthetic
+direction before emitting `design_confirmed`.
+
+## Why this skill is rich
+
+This skill carries 11 tabular CSVs (161-row UI-reasoning decision map,
+WCAG-adjusted color token sets, 84 styles, 73 font pairings, 25 chart rules, UX/
+react/mobile guidelines) plus 16 prose design-language specs and a 10-category
+pre-delivery checklist. Agents need to see the full corpus to make grounded
+selections — condensing to a summary destroys the evidence trail ("corpus
+row 47 justifies the palette choice") that the skill's output contract requires.
+Compressing the 16 design-language specs into fragments makes the style
+selection unreproducible and audit-unfriendly.
+
 ## Policies
 
 - Upstream MIT + Apache-2.0 obligations: [`ATTRIBUTION.md`](ATTRIBUTION.md).

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

@@ -36,6 +36,12 @@ A **live preview URL** is required for testing.
 
 ## Procedure: Design review
 
+1. **Inspect the PR and preview** — Read the PR description, diff, and identify changed components/pages; capture a baseline screenshot of the preview URL.
+2. **Walk the interactions** — Run Phase 1; cover hover/focus/active/disabled, keyboard, loading, and form error states.
+3. **Cover responsiveness, polish, a11y, robustness** — Run Phases 2–5 in order; record findings per phase.
+4. **Audit code-health and content** — Run Phases 6–7; check tokens, dead styles, copy, console warnings.
+5. **Verify and report** — Consolidate findings in the report structure; classify each as Blocker / High / Medium / Nit before posting.
+
 ### Phase 0: Preparation
 
 - Read PR description and git diff.
@@ -110,6 +116,61 @@ Test at three viewports:
 - No placeholder text left in production.
 - Check browser console for JavaScript errors or warnings.
 
+## Reviewer posture
+
+**Approval is earned, not assumed. Default to flagging.**
+
+A design review is a skeptic's pass. The default verdict for every element
+is "this needs to justify itself" — not "this is probably fine." Approve
+explicitly when you have examined the evidence and found it sound.
+
+This posture prevents the failure of "nothing to report" reviews that miss
+real issues because the reviewer defaulted to charitable assumptions.
+
+## Subtraction-first remedial hierarchy
+
+When a finding warrants a remediation recommendation, prefer in this order:
+
+1. **Delete** — remove the element, animation, pattern, or copy entirely
+2. **Reduce** — make it smaller, shorter, subtler, less frequent
+3. **Fix the specific issue** — change easing, origin, duration, contrast, font
+4. **Make it interruptible** (for motion) — switch to transition/spring
+5. **Move to GPU** (for motion) — animate only transform/opacity
+6. **Polish** — the lowest-leverage fix; only if the above don't apply
+
+*"Delete the animation" is always the first option to consider, even before
+suggesting a different easing curve.* The same applies to decorative elements,
+excessive copy, and redundant UI chrome.
+
+## Before / After / Why output format
+
+When reporting a finding with a specific remediation, use this table format:
+
+| Field | Content |
+|---|---|
+| **Before** | The current state (quote the code, value, or describe the pattern) |
+| **After** | The corrected state (specific value or alternative) |
+| **Why** | The mechanism: why is Before wrong and After better? (one sentence, states the principle) |
+
+**Wrong format** (do not use):
+```
+Before:
+  button { transition: all 0.3s ease; }
+After:
+  button { transition: transform 0.2s ease-out, opacity 0.2s ease-out; }
+```
+
+**Right format:**
+
+| | |
+|---|---|
+| **Before** | `transition: all 0.3s ease` |
+| **After** | `transition: transform 0.2s ease-out, opacity 0.2s ease-out` |
+| **Why** | `transition: all` animates layout properties on every state change, causing browser reflow; enumerate only the properties that move. |
+
+The Why column carries the reasoning — it's the part that teaches the developer
+and prevents the same finding from recurring.
+
 ## Communication principles
 
 ### Problems over prescriptions
@@ -224,6 +285,28 @@ This is especially useful when the user provides a screenshot or Figma export as
 - The model tends to suggest accessibility improvements that break the existing design system.
 - "Best practice" is not always the right choice — sometimes "good enough" ships faster.
 
+## Anti-slop scan
+
+During any design review, load
+[`docs/guidelines/design-antipatterns.md`](../../../docs/guidelines/design-antipatterns.md)
+as a reference. After the structured review phases, add an explicit
+**Anti-Slop Check** section to the review output:
+
+1. List any patterns from the catalog that appear in the reviewed UI (cite by
+   entry ID, e.g. V1, T2, C1).
+2. For each finding: note whether an override condition is in effect (if yes,
+   verify it is stated in the design brief; if not, flag as a finding).
+3. Run the AI-slop originality self-test on the overall aesthetic direction.
+   Report the result (pass / flag / fail) with one sentence of evidence.
+
+For the **objective quality floors** (WCAG contrast, font-size, line-length,
+reduced-motion, heading hierarchy, focus indicator), do NOT eyeball them —
+cite [`lint_design_quality`](../../../src/scripts/lint_design_quality.ts)
+output for the consumer project (Q1–Q6 in the catalog). The review owns the
+*subjective* anti-slop judgment (Visual / Typography / Color / Layout taste);
+the linter owns the *objective* floors; `accessibility-auditor` owns the WCAG
+*audit method*. Cite, don't re-derive.
+
 ## Do NOT
 
 - Do NOT skip accessibility testing — it's not optional.

package/dist/agent-src/skills/design-system-capture/SKILL.md

@@ -0,0 +1,234 @@
+---
+model_tier: inherit
+name: design-system-capture
+description: "Write and maintain DESIGN.md + PRODUCT.md — captures visual decisions and interaction patterns so design tasks stay consistent across sessions without re-scanning past work."
+domain: engineering
+personas:
+  - frontend-engineer
+workspaces:
+  - engineering
+packs:
+  - frontend-design
+token_budget_class: rich
+execution:
+  type: manual
+---
+
+# design-system-capture
+
+> Solves "design amnesia" — the failure mode where every AI design task
+> re-invents visual patterns (radius, shadows, motion, spacing) and
+> interaction patterns (destructive-action handling, optimistic UI, filter
+> persistence) because the agent has no cross-task memory of decisions
+> already made.
+>
+> **Boundary:** `brand-to-tokens` extracts *primitives* (colors, font
+> families → DTCG tokens). `existing-ui-audit` inventories *what exists*.
+> **This skill captures *usage decisions*:** "we use 8px radius for
+> elevated surfaces", "all destructive actions require typed confirmation".
+> They are complementary, not redundant.
+>
+> Gated by `tokens.rich_skills` in `.agent-settings.yml` (default `on`).
+> If `off`, skip rich context loading and work from brief alone.
+
+## Why this skill is rich
+
+DESIGN.md and PRODUCT.md serve as the project's design memory. To write
+useful capture documents and to read/apply them effectively, the agent
+needs full templates with worked examples showing what a well-structured
+DESIGN.md and PRODUCT.md look like in practice. A condensed version that
+says "write down your design decisions" produces documents too vague to
+be useful. The worked examples teach agents both the *vocabulary*
+(elevation, motion strategy, destructive-action policy) and the
+*specificity level* that makes these documents actionable across tasks.
+
+## When to use
+
+- Starting a new consumer project (initial capture, run once early)
+- After 2+ design tasks in the same project (update to capture what was decided)
+- When a subsequent design task produces inconsistent results (audit and reconcile)
+- Explicitly asked: "capture the design system", "write a DESIGN.md", "document our patterns"
+
+## The two documents
+
+### `DESIGN.md` — visual-system decisions
+
+Captures the *visual usage decisions* (not token primitives) that agents
+should apply consistently across all UI tasks in this project. Unlike
+`.tokens.json` (which records what a color value IS), DESIGN.md records
+*how and when to use it*.
+
+**Format:**
+
+```markdown
+# DESIGN.md — [Project name] visual system
+
+> AI-readable project design memory. Update after each design decision.
+> Last updated: [date]
+
+## Design philosophy
+One sentence: [density/formality/complexity philosophy]
+Example: "Information-dense dashboard; optimize for power users, not casual exploration."
+
+## Visual system
+
+### Elevation and radius
+- Elevated surfaces (modals, sheets, dropdowns): [X]px radius, [shadow-spec]
+- Inline elements (cards, chips): [X]px radius
+- Buttons: [X]px radius
+
+### Shadows
+- Elevated: [box-shadow value]
+- Floating (tooltips, popovers): [box-shadow value]
+- None (flat cards): [confirm]
+
+### Motion
+- Overlays and modals: [spring / easing spec + duration]
+- Micro-interactions (button feedback, toggles): [duration + easing]
+- Page transitions: [strategy or "none"]
+
+### Spacing
+- Base unit: [X]px
+- Card padding: [spec]
+- Section gap: [spec]
+- Tight grouping: [spec]
+
+### Color usage
+- Primary action: [token name]
+- Destructive: [token name]
+- Surface hierarchy: [primary bg → secondary bg → elevated bg]
+
+## Stack and conventions
+- CSS approach: [Tailwind / CSS modules / styled-components / etc.]
+- Component primitives: [shadcn / Radix / Headless UI / custom]
+- Icon system: [Phosphor / Heroicons / Lucide / etc.]
+```
+
+### `PRODUCT.md` — cross-feature interaction patterns
+
+Captures *interaction decisions* that should be consistent across features.
+Unlike a feature spec (which describes one feature), PRODUCT.md captures
+patterns that apply everywhere.
+
+**Format:**
+
+```markdown
+# PRODUCT.md — [Project name] interaction patterns
+
+> AI-readable cross-feature pattern memory. Update when a new pattern is established.
+> Last updated: [date]
+
+## Destructive actions
+Policy: [typed confirmation ("DELETE") / dialog with verb button / undo toast / etc.]
+Example: "All destructive actions require the user to type 'DELETE' or the resource name."
+
+## Mutation feedback
+Policy: [optimistic UI + inline undo / loading spinner / success toast / etc.]
+Undo window: [N seconds, or "not applicable"]
+Example: "Optimistic UI for all mutations; inline undo toast for 5 seconds, then commit."
+
+## Filter and sort persistence
+Policy: [URL params / localStorage / session / not persisted]
+Restore on load: [yes / no]
+
+## Empty states
+Approach: [illustration + CTA / text only / skeleton / etc.]
+Example: "Illustration + primary CTA for empty lists; text-only for zero-search-results."
+
+## Error handling
+Approach: [inline field errors / toast / error boundary / etc.]
+Network errors: [retry + message / fail fast / etc.]
+
+## Navigation and routing
+Pattern: [SPA / MPA / hybrid / etc.]
+Active state: [how active nav items are marked]
+
+## Mental model
+One sentence: [how the product conceptualizes itself to the user]
+Example: "Dashboard = control panel for power users, not an exploration space."
+```
+
+## Procedure
+
+### Step 1 — Assess what exists
+
+1. Check if `DESIGN.md` and `PRODUCT.md` already exist in the project root.
+2. If they exist: read both → skip to Step 3 (Update).
+3. If they don't exist: run `existing-ui-audit` (if not already done for this session) to inventory existing components, tokens, and conventions → proceed to Step 2.
+
+### Step 2 — Create (first run)
+
+1. **Extract visual decisions from the audit** (`state.ui_audit`): dominant
+   radius values, shadow patterns, spacing conventions, motion patterns.
+   Fill the DESIGN.md template above with the observed values. Mark
+   un-observed sections as `TBD`.
+2. **Extract interaction decisions from the codebase**: scan for delete
+   confirmation patterns, toast/feedback patterns, filter/URL persistence.
+   Fill the PRODUCT.md template. Mark un-observed sections as `TBD`.
+3. Write `DESIGN.md` and `PRODUCT.md` to the project root.
+4. Surface a one-paragraph summary: what was captured, what is still TBD,
+   and what action the user should take (review and correct the TBDs).
+
+### Step 3 — Update (subsequent runs)
+
+1. Read existing `DESIGN.md` and `PRODUCT.md`.
+2. Identify any decisions made in recent tasks that aren't yet captured
+   (e.g., a modal was built with 12px radius — add that to DESIGN.md).
+3. Correct any TBDs that are now resolved.
+4. Update the "Last updated" date.
+5. Output a diff summary: what changed and why.
+
+## How the design skills consume these documents
+
+When `DESIGN.md` or `PRODUCT.md` is present in the project root:
+
+- **`design-intelligence`** and **`fe-design`**: read DESIGN.md at the
+  start of any design task — use the captured decisions as project
+  constraints that override corpus suggestions.
+- **`ui-component-architect`**: read DESIGN.md for radius/shadow/motion
+  conventions before proposing any new component.
+- **`existing-ui-audit`**: when a full audit is impractical (large project),
+  read DESIGN.md as a proxy for "what this project's conventions are".
+
+The boundary from `brand-to-tokens`:
+- `.tokens.json` carries primitive values (gray-700 = #374151)
+- DESIGN.md carries usage decisions (elevated surfaces use 8px radius,
+  not 4px or 12px)
+Both are consumed together; DESIGN.md takes precedence for usage questions.
+
+## Gotcha
+
+- **Over-writing instead of diff-updating** — the most common failure.
+  Always read existing `DESIGN.md`/`PRODUCT.md` before writing; carry
+  all existing decisions forward and only add/correct. Losing prior
+  captured history is worse than capturing nothing.
+- **Copying tokens into DESIGN.md** — DESIGN.md is NOT a copy of
+  `.tokens.json`. It captures *usage decisions* ("8px radius on elevated
+  surfaces"), not primitive values ("gray-700 = #374151"). The
+  distinction is what makes DESIGN.md actionable.
+- **Capturing feature-specific behavior** — PRODUCT.md is for patterns
+  that repeat across 2+ features. A delete-confirmation pattern in one
+  form does NOT belong in PRODUCT.md until it appears in at least two
+  independent features.
+
+## Do NOT
+
+- Do NOT overwrite DESIGN.md/PRODUCT.md without first reading and diffing
+  the existing content — accumulated history is the value.
+- Do NOT make DESIGN.md a copy of `.tokens.json` — it captures decisions,
+  not token definitions.
+- Do NOT capture feature-specific behavior in PRODUCT.md — only patterns
+  that repeat across multiple features.
+- Do NOT mark a decision as captured without evidence from the actual codebase.
+
+## Output format
+
+On create:
+1. Write `DESIGN.md` to the project root with the extracted visual decisions.
+2. Write `PRODUCT.md` to the project root with the extracted interaction patterns.
+3. Surface a one-paragraph summary of what was captured and what is TBD.
+4. List any questions where the existing code is ambiguous.
+
+On update:
+1. Update both files with new decisions.
+2. Output a short diff: "Added: destructive-action policy. Updated: motion strategy (was TBD, now spring)."

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

@@ -132,4 +132,5 @@ four-operation split assigns to *rules/linters*, not the corpus).
 - [`design-intelligence`](../design-intelligence/SKILL.md) — grounded value selection.
 - [`tailwind-engineer`](../tailwind-engineer/SKILL.md) — utility-discipline consumer.
 - [`react-shadcn-ui`](../react-shadcn-ui/SKILL.md) — shadcn token conventions.
+- [`docs/guidelines/design-antipatterns.md`](../../../docs/guidelines/design-antipatterns.md) — when authoring the colour layer, avoid the C5 cream/sand default palette (OKLCH L 0.84–0.97, C < 0.06) and C1 purple/violet primaries unless the brand explicitly defines them; the `brand-consistency` rule validates emitted tokens against the active brand profile.
 - Tests: `tests/test_design_tokens_toolchain.py`.

package/dist/agent-src/skills/dpa-review/SKILL.md

@@ -4,12 +4,13 @@ name: dpa-review
 description: "Use when reviewing a DPA as controller or processor against GDPR Art. 28 — GREEN/YELLOW/RED gap frame, never a final call. Triggers on \"review this DPA\", \"check this DPA\"."
 status: active
 tier: senior
+council_depth: deep
 domain: process
 recommended_for_user_types: [legal]
 workspaces:
-  - legal
+  - legal-review-prep
 packs:
-  - legal
+  - legal-review-prep
 trust:
   level: advisory
 install:

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

@@ -16,10 +16,10 @@ packs:
 > **Interplay:** this audit answers *what exists* (components, tokens,
 > primitives → `state.ui_audit`);
 > [`design-intelligence`](../design-intelligence/SKILL.md) answers *what to
-> build* (corpus-grounded style/token/typography/pattern selection).
-> Audit runs first; its reuse findings outrank corpus suggestions — never
-> let a grounded recommendation introduce a component the inventory
-> already covers.
+> build* (corpus-grounded style/token/typography/pattern selection for the
+> brief). Audit runs first, and its reuse findings outrank corpus
+> suggestions — never let a grounded recommendation introduce a new
+> component the inventory already covers.
 
 ## When to use
 
@@ -208,6 +208,17 @@ violations will surface as new findings on every run.
 - Greenfield is detected, not assumed — a project with one Blade layout and no components is still greenfield only if tokens AND design system markers AND components are all empty.
 - Re-running the skill on a stale state-file: cache by `(composer.json mtime, package.json mtime)`; if either changed, re-audit and overwrite.
 
+## 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. The
+next design step can then decide whether to continue the existing pattern (for
+consistency) or introduce a corrective direction change.
+
 ## Do NOT
 
 - Do NOT advance to `directives/ui/design.py` or `apply.py` if `state.ui_audit` is empty.

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

@@ -49,9 +49,10 @@ Do NOT use this skill to:
 states, microcopy, a11y). Selection decisions (style, semantic color
 tokens, typography pairing, layout pattern, anti-patterns) come **grounded**
 from [`design-intelligence`](../design-intelligence/SKILL.md) — run its
-corpus query first; fall back to these heuristics only where the corpus
-reports an evidence gap or the audit already pins a project pattern.
-Stack-specific choices come from the dispatched impl skill.
+corpus query first; fall back to the heuristics in this reference only
+where the corpus reports an evidence gap or the audit already pins a
+project pattern. Stack-specific choices come from the dispatched
+implementation skill, not from here.
 
 ## Component Architecture
 
@@ -198,24 +199,97 @@ Step indicator (1 — 2 — 3)
 | 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)
-2. **Forgiveness** — Undo for destructive actions, confirmation for irreversible ones
-3. **Consistency** — Same patterns for same interactions across the app
-4. **Progressive disclosure** — Show basics first, details on demand
-5. **Loading states** — Skeleton screens or spinners, never blank screens
-6. **Error recovery** — Clear error messages with suggested actions
+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.
+
+## 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, verify you are NOT defaulting to:
+- Centered hero + 3-column feature grid + CTA (the "AI landing page" layout)
+- Side-stripe `border-left` accent cards (V1 in `design-antipatterns`)
+- Identical card grids with no visual rhythm (L2)
+- `Inter` or `Space Grotesk` as the uncritical font pick (T7)
+- Glassmorphism as a decoration device (V2)
+
+If any of these was the first impulse, choose a different approach or
+explicitly justify why this brief genuinely calls for it.
 
 ## 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 combos, Google Fonts URLs +
-Tailwind config) and icon-system guidance (104 Phosphor entries with
-import code) come grounded from
+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.
+(`--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.
 
@@ -228,7 +302,7 @@ When `directives/ui/design.py` (or any caller) cites this skill:
 1. **Inspect `state.ui_audit` first** — review the audit produced by [`existing-ui-audit`](../existing-ui-audit/SKILL.md); it is mandatory. Stop and request the audit if missing.
 2. **Pick the smallest matching section** — Component Architecture, Form Design, Table Design, Responsive Strategy, Accessibility, or UX Principles. Cite by H2/H3 heading, never paste the whole skill.
 3. **Defer to audit findings** — when the audit pins a project pattern (token, primitive, layout convention), use it. The heuristics here are fallbacks for gaps, not overrides.
-4. **Defer to the stack apply skill** — Blade vs. Livewire vs. Flux vs. React-shadcn choices come from the dispatched impl skill, never from this reference.
+4. **Defer to the stack apply skill** — Blade vs. Livewire vs. Flux vs. React-shadcn choices come from the dispatched implementation skill, never from this reference.
 5. **Surface conflicts** — if a heuristic here contradicts an audit finding or stack convention, name both and let the caller decide; do not silently pick.
 
 ## Output format
@@ -245,8 +319,8 @@ When this skill's content is folded into a design brief or review:
 - **Orchestrator:** [`directives/ui/`](../../templates/scripts/work_engine/directives/ui/) — owns the UI flow
 - **Pre-step (mandatory):** [`existing-ui-audit`](../existing-ui-audit/SKILL.md) — inventory before design
 - **Stack apply skills (dispatched, not standalone):**
-  - [`blade-ui`](../blade-ui/SKILL.md) — Blade template impl
-  - [`livewire`](../livewire/SKILL.md) — Livewire component impl
+  - [`blade-ui`](../blade-ui/SKILL.md) — Blade template implementation
+  - [`livewire`](../livewire/SKILL.md) — Livewire component implementation
   - [`flux`](../flux/SKILL.md) — Flux component library usage
   - [`react-shadcn-ui`](../react-shadcn-ui/SKILL.md) — React + shadcn primitives
 - **Adjacent reference:** [`dashboard-design`](../dashboard-design/SKILL.md) — monitoring dashboard design (different domain)
@@ -257,6 +331,14 @@ When this skill's content is folded into a design brief or review:
 - Heuristics in this reference apply across stacks; do not promote them to project rules without checking the audit.
 - Mobile-first is not optional — every layout must work on 320px width.
 
+## Anti-slop discipline
+
+Before proposing any UI layout, component, or aesthetic direction, pull
+[`docs/guidelines/design-antipatterns.md`](../../../docs/guidelines/design-antipatterns.md)
+and scan the Visual (V1–V7), Layout (L1–L8), and Quality-floors (Q1–Q12) sections.
+If the first-impulse design matches a listed pattern, either choose a different
+approach or explicitly invoke the override condition in the design brief.
+
 ## Do NOT
 
 - Do NOT skip mobile viewport testing.