@jaimevalasek/aioson 1.8.0 → 1.9.1

package/template/.aioson/skills/design/interface-design/SKILL.md

@@ -1,47 +1,47 @@
----
-name: interface-design
-description: Interface Design is a craft-first packaged design skill for choosing an intentional visual direction, building a stable token system, and maintaining UI continuity across screens. Use it when `design_skill: interface-design` is selected or when the user explicitly chooses this broad craft package.
----
-
-# Interface Design
-
-This is a general design-craft package.
-It helps the agent make strong decisions when the user wants a deliberate, high-quality UI but has not chosen a niche visual language such as `cognitive-ui` or `premium-command-center-ui`.
-
-## Package structure
-
-```text
-.aioson/skills/design/interface-design/
-  SKILL.md
-  references/
-    intent-and-domain.md
-    design-directions.md
-    tokens-and-depth.md
-    components-and-states.md
-    handoff-and-quality.md
-```
-
-## Activation rules
-
-- Apply this package only when `design_skill: interface-design` is selected.
-- Do not combine it with any other design skill.
-- Use it when the user wants strong design craft but has not asked for a very specific visual system.
-
-## Loading guide
-
-| Task | Load |
-|---|---|
-| Any visual work | `references/intent-and-domain.md` + `references/design-directions.md` |
-| Tokens and system decisions | add `references/tokens-and-depth.md` |
-| Component behavior | add `references/components-and-states.md` |
-| Final delivery quality | add `references/handoff-and-quality.md` |
-
-## Positioning
-
-Use this package for:
-- general web apps
-- websites that need strong craft but not a preset style language
-- redesigns that need a clearer system
-- multi-screen work where continuity matters
-
-Do not use it when a more explicit visual package was selected.
+---
+name: interface-design
+description: Interface Design is a craft-first packaged design skill for choosing an intentional visual direction, building a stable token system, and maintaining UI continuity across screens. Use it when `design_skill: interface-design` is selected or when the user explicitly chooses this broad craft package.
+---
+
+# Interface Design
+
+This is a general design-craft package.
+It helps the agent make strong decisions when the user wants a deliberate, high-quality UI but has not chosen a niche visual language such as `cognitive-ui` or `premium-command-center-ui`.
+
+## Package structure
+
+```text
+.aioson/skills/design/interface-design/
+  SKILL.md
+  references/
+    intent-and-domain.md
+    design-directions.md
+    tokens-and-depth.md
+    components-and-states.md
+    handoff-and-quality.md
+```
+
+## Activation rules
+
+- Apply this package only when `design_skill: interface-design` is selected.
+- Do not combine it with any other design skill.
+- Use it when the user wants strong design craft but has not asked for a very specific visual system.
+
+## Loading guide
+
+| Task | Load |
+|---|---|
+| Any visual work | `references/intent-and-domain.md` + `references/design-directions.md` |
+| Tokens and system decisions | add `references/tokens-and-depth.md` |
+| Component behavior | add `references/components-and-states.md` |
+| Final delivery quality | add `references/handoff-and-quality.md` |
+
+## Positioning
+
+Use this package for:
+- general web apps
+- websites that need strong craft but not a preset style language
+- redesigns that need a clearer system
+- multi-screen work where continuity matters
+
+Do not use it when a more explicit visual package was selected.

package/template/.aioson/skills/design/interface-design/references/components-and-states.md

@@ -1,105 +1,105 @@
-# Components and States — Interface Design
-
----
-
-## Component quality (mandatory for every component)
-
-Define all six states before handing off to @dev:
-
-| State | What to specify |
-|---|---|
-| Default | Baseline appearance |
-| Hover | Subtle shift (background, border, or opacity) |
-| Focus | Visible ring — `outline: 2px solid brand/primary; outline-offset: 2px` |
-| Active / pressed | Slight scale or brightness change |
-| Disabled | Reduced opacity (0.4–0.5), no cursor pointer, no hover effect |
-| Loading | Skeleton or spinner — never block critical flow |
-
-Container components also need:
-- **Empty state** — illustration or message + primary action
-- **Error state** — clear message + recovery action
-- **Success confirmation** — when relevant, transient (not permanent)
-
----
-
-## Forms
-
-- Labels outside placeholders. Placeholders are hints, not labels.
-- Validate on blur (not on keystroke, not on submit only).
-- Inline field errors directly below the field. One global summary for multi-field failures.
-- Disable the submit button and show progress during async operations.
-- Input height minimum: 40px (desktop), 44px (mobile/touch) — **consumer/public-facing forms only.**
-
-**Admin / operational form scale (settings, config, entity managers):**
-
-```
-Label  : text-[0.65rem]  mb: 2px          ← not text-sm mb-2
-Input  : px-3 py-2  text-xs  radius 10–12px  (height ~32px)
-Select : px-3 py-2  text-xs  radius 10–12px
-Button : px-3 py-2  text-xs  radius 10–12px
-```
-
-The 40px minimum only applies to authenticated public flows (login, onboarding, checkout). In dense admin contexts, 32px controls reduce visual weight without usability loss — the audience is power users, not first-time visitors.
-
-**Entity add/edit forms → Modal, not inline expansion:**
-- Inline accordions (RevealPanel, details-based expansion) inside entity cards cause layout shift and make the page feel unstable
-- Correct pattern: `+ Add` button + `Edit` button each open a centered modal (`max-w-448px`, `backdrop-blur overlay`)
-- Modal form: single-column, `gap: 10px`, compact controls, full-width submit button
-
----
-
-## Typography hierarchy
-
-Size alone is never enough. Use weight + tracking + opacity to create layers:
-
-```
-Page title    : largest size, 600-weight, tight tracking
-Section title : medium-large, 500-weight, normal tracking
-Body          : base size, 400-weight, comfortable line-height (1.5–1.6)
-Helper / meta : small, 400-weight, muted color
-Data / mono   : monospace for numbers in tables, code, metrics
-```
-
----
-
-## Layout and composition
-
-- **Rhythm** — interfaces breathe unevenly: dense tool areas give way to open content. Same card size, same gaps everywhere = flatness = no one decided.
-- **Proportions declare intent** — a 280px sidebar says "navigation serves content." A 360px sidebar says "these are peers." Know what your proportions are saying.
-- **One focal point per screen** — the primary action dominates through size, position, contrast, or surrounding space. When everything competes equally, nothing wins.
-- **Reading order** — 1. Page intent → 2. Primary action → 3. Supporting data. Never invert.
-
----
-
-## Accessibility baseline (non-negotiable)
-
-- Semantic HTML and proper landmarks (`<main>`, `<nav>`, `<header>`, `<aside>`)
-- Full keyboard navigation — Tab order must match visual reading order
-- Visible focus rings on all interactive elements
-- Color contrast: 4.5:1 for body text, 3:1 for large text and UI components
-- Never convey meaning through color alone — add icon, pattern, or text
-- `aria-label` on icon-only buttons, `aria-live` on dynamic status regions
-- `prefers-reduced-motion` fallback for all animations
-
----
-
-## Motion rules
-
-- Motion clarifies transitions, it does not decorate them.
-- Duration: micro-interactions 100–150ms, page transitions 200–300ms.
-- Easing: ease-out for entrances, ease-in for exits.
-- Never animate properties that affect layout (width, height, padding). Animate transform and opacity only.
-- Always provide `prefers-reduced-motion: reduce` fallback.
-
----
-
-## Stack-specific notes
-
-| Stack | Priority |
-|---|---|
-| Laravel + TALL | Flux UI / Livewire primitives first; custom only for signature moves |
-| Filament | Built-in Filament components before any override |
-| Next.js + shadcn/ui | shadcn primitives + Tailwind tokens; keep component boundaries clean |
-| React + Tailwind | Design token CSS vars → Tailwind config → components |
-| Vue + Nuxt | Nuxt UI or PrimeVue first; avoid mixing component libraries |
-| Vanilla HTML | Define CSS custom properties at `:root`, semantic class names only |
+# Components and States — Interface Design
+
+---
+
+## Component quality (mandatory for every component)
+
+Define all six states before handing off to @dev:
+
+| State | What to specify |
+|---|---|
+| Default | Baseline appearance |
+| Hover | Subtle shift (background, border, or opacity) |
+| Focus | Visible ring — `outline: 2px solid brand/primary; outline-offset: 2px` |
+| Active / pressed | Slight scale or brightness change |
+| Disabled | Reduced opacity (0.4–0.5), no cursor pointer, no hover effect |
+| Loading | Skeleton or spinner — never block critical flow |
+
+Container components also need:
+- **Empty state** — illustration or message + primary action
+- **Error state** — clear message + recovery action
+- **Success confirmation** — when relevant, transient (not permanent)
+
+---
+
+## Forms
+
+- Labels outside placeholders. Placeholders are hints, not labels.
+- Validate on blur (not on keystroke, not on submit only).
+- Inline field errors directly below the field. One global summary for multi-field failures.
+- Disable the submit button and show progress during async operations.
+- Input height minimum: 40px (desktop), 44px (mobile/touch) — **consumer/public-facing forms only.**
+
+**Admin / operational form scale (settings, config, entity managers):**
+
+```
+Label  : text-[0.65rem]  mb: 2px          ← not text-sm mb-2
+Input  : px-3 py-2  text-xs  radius 10–12px  (height ~32px)
+Select : px-3 py-2  text-xs  radius 10–12px
+Button : px-3 py-2  text-xs  radius 10–12px
+```
+
+The 40px minimum only applies to authenticated public flows (login, onboarding, checkout). In dense admin contexts, 32px controls reduce visual weight without usability loss — the audience is power users, not first-time visitors.
+
+**Entity add/edit forms → Modal, not inline expansion:**
+- Inline accordions (RevealPanel, details-based expansion) inside entity cards cause layout shift and make the page feel unstable
+- Correct pattern: `+ Add` button + `Edit` button each open a centered modal (`max-w-448px`, `backdrop-blur overlay`)
+- Modal form: single-column, `gap: 10px`, compact controls, full-width submit button
+
+---
+
+## Typography hierarchy
+
+Size alone is never enough. Use weight + tracking + opacity to create layers:
+
+```
+Page title    : largest size, 600-weight, tight tracking
+Section title : medium-large, 500-weight, normal tracking
+Body          : base size, 400-weight, comfortable line-height (1.5–1.6)
+Helper / meta : small, 400-weight, muted color
+Data / mono   : monospace for numbers in tables, code, metrics
+```
+
+---
+
+## Layout and composition
+
+- **Rhythm** — interfaces breathe unevenly: dense tool areas give way to open content. Same card size, same gaps everywhere = flatness = no one decided.
+- **Proportions declare intent** — a 280px sidebar says "navigation serves content." A 360px sidebar says "these are peers." Know what your proportions are saying.
+- **One focal point per screen** — the primary action dominates through size, position, contrast, or surrounding space. When everything competes equally, nothing wins.
+- **Reading order** — 1. Page intent → 2. Primary action → 3. Supporting data. Never invert.
+
+---
+
+## Accessibility baseline (non-negotiable)
+
+- Semantic HTML and proper landmarks (`<main>`, `<nav>`, `<header>`, `<aside>`)
+- Full keyboard navigation — Tab order must match visual reading order
+- Visible focus rings on all interactive elements
+- Color contrast: 4.5:1 for body text, 3:1 for large text and UI components
+- Never convey meaning through color alone — add icon, pattern, or text
+- `aria-label` on icon-only buttons, `aria-live` on dynamic status regions
+- `prefers-reduced-motion` fallback for all animations
+
+---
+
+## Motion rules
+
+- Motion clarifies transitions, it does not decorate them.
+- Duration: micro-interactions 100–150ms, page transitions 200–300ms.
+- Easing: ease-out for entrances, ease-in for exits.
+- Never animate properties that affect layout (width, height, padding). Animate transform and opacity only.
+- Always provide `prefers-reduced-motion: reduce` fallback.
+
+---
+
+## Stack-specific notes
+
+| Stack | Priority |
+|---|---|
+| Laravel + TALL | Flux UI / Livewire primitives first; custom only for signature moves |
+| Filament | Built-in Filament components before any override |
+| Next.js + shadcn/ui | shadcn primitives + Tailwind tokens; keep component boundaries clean |
+| React + Tailwind | Design token CSS vars → Tailwind config → components |
+| Vue + Nuxt | Nuxt UI or PrimeVue first; avoid mixing component libraries |
+| Vanilla HTML | Define CSS custom properties at `:root`, semantic class names only |

package/template/.aioson/skills/design/interface-design/references/design-directions.md

@@ -1,101 +1,101 @@
-# Design Directions — Interface Design
-
-Choose ONE direction. Never mix. Mixing produces visual noise.
-The chosen direction defines spacing, typography, border strategy, depth, and motion posture — before components are built.
-
----
-
-## Precision & Density
-
-*For: dashboards, admin panels, developer tools, power-user interfaces.*
-
-```
-Foundation : Cool slate (borders-only depth)
-Spacing    : 4px base — scale: 4, 8, 12, 16, 24, 32
-Colors     : foreground=slate-900, secondary=slate-600, muted=slate-400,
-             faint=slate-200, border=rgba(0,0,0,0.08), accent=blue-600
-Radius     : 4px / 6px / 8px  (sharp, technical)
-Typography : system-ui, 11–18px, weights 400/500/600
-             monospace: SF Mono, Consolas (for data/code)
-Components :
-  Button   → 32px height, 8px/12px padding, 4px radius, 13px 500-weight
-  Card     → 0.5px faint border, 12px padding, 6px radius, NO shadows
-  Table    → 8px/12px cell padding, tabular-nums, 13px font, 1px bottom border
-Rationale  : borders-only maximizes density; compact sizing serves power users;
-             system fonts feel native and load instantly.
-```
-
----
-
-## Warmth & Approachability
-
-*For: consumer apps, collaborative tools, onboarding flows, customer-facing products.*
-
-```
-Foundation : Warm stone (subtle shadows)
-Spacing    : 4px base — scale: 8, 12, 16, 24, 32, 48 (generous)
-Colors     : foreground=stone-900, secondary=stone-600, accent=orange-500,
-             surface=white on stone-50
-Radius     : 8px / 12px / 16px  (rounded, friendly)
-Typography : Inter, 13–24px, weights 400/500/600
-Components :
-  Button   → 40px height, 12px/20px padding, 8px radius
-  Card     → 20px padding, 12px radius, white on stone-50
-  Input    → 44px height, 12px/16px padding, 1.5px faint border
-Rationale  : subtle shadows add approachable depth; generous spacing enables
-             focused tasks; warm tones feel human and inviting.
-```
-
----
-
-## Sophistication & Trust
-
-*For: fintech, enterprise SaaS, operational products where clarity and trust matter more than novelty.*
-
-```
-Foundation : Cool mineral (restrained layers)
-Spacing    : 4px base — scale: 4, 8, 12, 16, 24, 32
-Colors     : foreground=slate-950, secondary=slate-700, muted=slate-500,
-             surface=white, border=rgba(15,23,42,0.10), accent=blue-700
-Radius     : 8px / 10px / 12px  (firm, not playful)
-Typography : IBM Plex Sans or Public Sans, 12–20px, weights 400/500/600
-Components :
-  Button   → 38px height, 12px/18px padding, 10px radius
-  Card     → 16px padding, 10px radius, subtle border, rare soft shadow
-  Table    → 10px/14px cell padding, tabular-nums, quiet row dividers
-Rationale  : trust comes from control, not decoration; a restrained palette and
-             firm typography make the product feel expensive and dependable.
-```
-
----
-
-## Premium Dark Platform
-
-*For: premium dashboards, media/catalog products, command surfaces, high-density apps with persistent navigation.*
-
-```
-Foundation : Graphite layers (borders-first)
-Spacing    : 4px base — scale: 4, 8, 12, 16, 24, 32
-Colors     : base=#0b1015, surface=#10161d, elevated=#151c24,
-             foreground=#f3f7fb, secondary=#b7c2cf, muted=#7f8b99,
-             border=rgba(255,255,255,0.08), accent=desaturated blue
-Radius     : 12px / 14px / 16px  (premium, controlled)
-Typography : Manrope, Geist, or IBM Plex Sans, 12–22px, weights 400/500/600
-Components :
-  Button   → 40px height, 12px/18px padding, 12px radius
-  Card     → layered surfaces, 16px padding, 14px radius, no heavy glow
-  Sidebar  → quiet active state, compact icon rhythm, clean section grouping
-Rationale  : premium dark works when contrast is controlled, surfaces are few,
-             and borders quietly separate the system without turning neon.
-```
-
----
-
-## Other directions (adapt token specs above)
-
-- **Data & Analysis** — cool blue, high-density tables, monospace for numbers, minimal chrome
-- **Editorial** — strong typographic hierarchy, generous white space, restrained color
-- **Commerce** — aspirational photography support, high contrast CTAs, smooth transitions
-- **Minimal & Calm** — near-monochrome, whitespace as design element, hairline borders only
-- **Boldness & Clarity** — stronger accent, harder contrast, one dominant focal move
-- **Utility & Function** — minimal decoration, maximum legibility, near-invisible chrome
+# Design Directions — Interface Design
+
+Choose ONE direction. Never mix. Mixing produces visual noise.
+The chosen direction defines spacing, typography, border strategy, depth, and motion posture — before components are built.
+
+---
+
+## Precision & Density
+
+*For: dashboards, admin panels, developer tools, power-user interfaces.*
+
+```
+Foundation : Cool slate (borders-only depth)
+Spacing    : 4px base — scale: 4, 8, 12, 16, 24, 32
+Colors     : foreground=slate-900, secondary=slate-600, muted=slate-400,
+             faint=slate-200, border=rgba(0,0,0,0.08), accent=blue-600
+Radius     : 4px / 6px / 8px  (sharp, technical)
+Typography : system-ui, 11–18px, weights 400/500/600
+             monospace: SF Mono, Consolas (for data/code)
+Components :
+  Button   → 32px height, 8px/12px padding, 4px radius, 13px 500-weight
+  Card     → 0.5px faint border, 12px padding, 6px radius, NO shadows
+  Table    → 8px/12px cell padding, tabular-nums, 13px font, 1px bottom border
+Rationale  : borders-only maximizes density; compact sizing serves power users;
+             system fonts feel native and load instantly.
+```
+
+---
+
+## Warmth & Approachability
+
+*For: consumer apps, collaborative tools, onboarding flows, customer-facing products.*
+
+```
+Foundation : Warm stone (subtle shadows)
+Spacing    : 4px base — scale: 8, 12, 16, 24, 32, 48 (generous)
+Colors     : foreground=stone-900, secondary=stone-600, accent=orange-500,
+             surface=white on stone-50
+Radius     : 8px / 12px / 16px  (rounded, friendly)
+Typography : Inter, 13–24px, weights 400/500/600
+Components :
+  Button   → 40px height, 12px/20px padding, 8px radius
+  Card     → 20px padding, 12px radius, white on stone-50
+  Input    → 44px height, 12px/16px padding, 1.5px faint border
+Rationale  : subtle shadows add approachable depth; generous spacing enables
+             focused tasks; warm tones feel human and inviting.
+```
+
+---
+
+## Sophistication & Trust
+
+*For: fintech, enterprise SaaS, operational products where clarity and trust matter more than novelty.*
+
+```
+Foundation : Cool mineral (restrained layers)
+Spacing    : 4px base — scale: 4, 8, 12, 16, 24, 32
+Colors     : foreground=slate-950, secondary=slate-700, muted=slate-500,
+             surface=white, border=rgba(15,23,42,0.10), accent=blue-700
+Radius     : 8px / 10px / 12px  (firm, not playful)
+Typography : IBM Plex Sans or Public Sans, 12–20px, weights 400/500/600
+Components :
+  Button   → 38px height, 12px/18px padding, 10px radius
+  Card     → 16px padding, 10px radius, subtle border, rare soft shadow
+  Table    → 10px/14px cell padding, tabular-nums, quiet row dividers
+Rationale  : trust comes from control, not decoration; a restrained palette and
+             firm typography make the product feel expensive and dependable.
+```
+
+---
+
+## Premium Dark Platform
+
+*For: premium dashboards, media/catalog products, command surfaces, high-density apps with persistent navigation.*
+
+```
+Foundation : Graphite layers (borders-first)
+Spacing    : 4px base — scale: 4, 8, 12, 16, 24, 32
+Colors     : base=#0b1015, surface=#10161d, elevated=#151c24,
+             foreground=#f3f7fb, secondary=#b7c2cf, muted=#7f8b99,
+             border=rgba(255,255,255,0.08), accent=desaturated blue
+Radius     : 12px / 14px / 16px  (premium, controlled)
+Typography : Manrope, Geist, or IBM Plex Sans, 12–22px, weights 400/500/600
+Components :
+  Button   → 40px height, 12px/18px padding, 12px radius
+  Card     → layered surfaces, 16px padding, 14px radius, no heavy glow
+  Sidebar  → quiet active state, compact icon rhythm, clean section grouping
+Rationale  : premium dark works when contrast is controlled, surfaces are few,
+             and borders quietly separate the system without turning neon.
+```
+
+---
+
+## Other directions (adapt token specs above)
+
+- **Data & Analysis** — cool blue, high-density tables, monospace for numbers, minimal chrome
+- **Editorial** — strong typographic hierarchy, generous white space, restrained color
+- **Commerce** — aspirational photography support, high contrast CTAs, smooth transitions
+- **Minimal & Calm** — near-monochrome, whitespace as design element, hairline borders only
+- **Boldness & Clarity** — stronger accent, harder contrast, one dominant focal move
+- **Utility & Function** — minimal decoration, maximum legibility, near-invisible chrome

package/template/.aioson/skills/design/interface-design/references/handoff-and-quality.md

@@ -1,71 +1,71 @@
-# Handoff and Quality — Interface Design
-
----
-
-## Quality checks (run before delivering)
-
-### Swap test
-Would swapping the typeface or layout make the design look like a different product?
-If yes — good. If no — the design has no identity.
-
-### Squint test
-Blur your eyes (or the screenshot). Does the visual hierarchy still read clearly?
-If not — the hierarchy is too weak.
-
-### Signature test
-Can you point to five specific decisions where your craft appears?
-If you cannot name five — you defaulted somewhere.
-
-### Token test
-Do your CSS variable names sound like they belong to THIS product?
-Generic: `--color-primary`. Specific: `--slot-available`, `--urgency-amber`.
-
----
-
-## Self-critique before delivery
-
-Walk through each section before handing off:
-
-1. **Composition** — Does the layout have rhythm? Are proportions intentional? Is there one clear focal point?
-2. **Craft** — Is every spacing value on-grid? Does typography use weight + tracking + size (not size alone)? Do surfaces whisper hierarchy without thick borders or dramatic shadows?
-3. **Content** — Does the spec tell one coherent story? Could a real person at a real company act on this?
-4. **Structure** — Are there any hacks? Negative-margin workarounds? Arbitrary pixel values? Fix them.
-
-**Ask yourself: "If a design lead reviewed this, what would they call out?" Fix that thing. Then ask again.**
-
----
-
-## Handoff to @dev
-
-A strong handoff includes:
-- Explicit visual direction and anti-goals
-- Design token block (fonts, colors, spacing, radius, depth strategy, motion posture)
-- Per-screen layout notes with component names mapped to real library components
-- Full state matrix (default / hover / focus / active / disabled / loading / empty / error / success)
-- Responsive rules (mobile breakpoints, collapse behavior)
-- Accessibility checklist items
-- Any signature visual moves with implementation notes
-- Anti-patterns to avoid
-
-The `ui-spec.md` must be concise enough to code from directly. Not a design document — a build contract.
-
----
-
-## Update design memory
-
-When the work introduces or changes reusable design decisions, update `.interface-design/system.md` with:
-- Final direction and anti-goals
-- Token block
-- Component pattern notes
-- New exceptions or constraints
-
-This file is the continuity layer between screens, agents, and future sessions.
-
----
-
-## Quality bar
-
-1. The result must not look generic.
-2. Repeated elements must share spacing, radius, and depth logic.
-3. Typography hierarchy must be legible without decorative tricks.
-4. The screen must communicate purpose before style.
+# Handoff and Quality — Interface Design
+
+---
+
+## Quality checks (run before delivering)
+
+### Swap test
+Would swapping the typeface or layout make the design look like a different product?
+If yes — good. If no — the design has no identity.
+
+### Squint test
+Blur your eyes (or the screenshot). Does the visual hierarchy still read clearly?
+If not — the hierarchy is too weak.
+
+### Signature test
+Can you point to five specific decisions where your craft appears?
+If you cannot name five — you defaulted somewhere.
+
+### Token test
+Do your CSS variable names sound like they belong to THIS product?
+Generic: `--color-primary`. Specific: `--slot-available`, `--urgency-amber`.
+
+---
+
+## Self-critique before delivery
+
+Walk through each section before handing off:
+
+1. **Composition** — Does the layout have rhythm? Are proportions intentional? Is there one clear focal point?
+2. **Craft** — Is every spacing value on-grid? Does typography use weight + tracking + size (not size alone)? Do surfaces whisper hierarchy without thick borders or dramatic shadows?
+3. **Content** — Does the spec tell one coherent story? Could a real person at a real company act on this?
+4. **Structure** — Are there any hacks? Negative-margin workarounds? Arbitrary pixel values? Fix them.
+
+**Ask yourself: "If a design lead reviewed this, what would they call out?" Fix that thing. Then ask again.**
+
+---
+
+## Handoff to @dev
+
+A strong handoff includes:
+- Explicit visual direction and anti-goals
+- Design token block (fonts, colors, spacing, radius, depth strategy, motion posture)
+- Per-screen layout notes with component names mapped to real library components
+- Full state matrix (default / hover / focus / active / disabled / loading / empty / error / success)
+- Responsive rules (mobile breakpoints, collapse behavior)
+- Accessibility checklist items
+- Any signature visual moves with implementation notes
+- Anti-patterns to avoid
+
+The `ui-spec.md` must be concise enough to code from directly. Not a design document — a build contract.
+
+---
+
+## Update design memory
+
+When the work introduces or changes reusable design decisions, update `.interface-design/system.md` with:
+- Final direction and anti-goals
+- Token block
+- Component pattern notes
+- New exceptions or constraints
+
+This file is the continuity layer between screens, agents, and future sessions.
+
+---
+
+## Quality bar
+
+1. The result must not look generic.
+2. Repeated elements must share spacing, radius, and depth logic.
+3. Typography hierarchy must be legible without decorative tricks.
+4. The screen must communicate purpose before style.