@jaimevalasek/aioson 1.30.0 → 1.30.2

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

@@ -1,71 +1,92 @@
-# 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`.
+
+### Asset test
+Does the first viewport show a real product, place, person, object, UI state, generated bitmap, photo, or video when the surface is a website or landing page?
+If not, the page is probably decoration plus copy, not a visual experience.
+
+### Responsive fit test
+Do all labels, buttons, counters, cards, tables, media, and headings fit at mobile and desktop widths without overlap, clipping, or layout shift?
+If not, add explicit constraints: grid `minmax()`, `aspect-ratio`, fixed control heights, line wrapping, overflow rules, and stable media dimensions.
+
+### Font delivery test
+Are the named fonts actually loaded through the stack's supported mechanism?
+If not, declare a credible fallback stack and preserve the intended contrast with weight, scale, and line-height instead of pretending the unavailable font exists.
+
+### Motion test
+Does motion communicate feedback, state, navigation, or reveal?
+If not, remove it. If yes, include a `prefers-reduced-motion` fallback.
+
+### Browser inspection test
+If a runnable UI exists, inspect it in a browser at one mobile and one desktop viewport before delivery.
+Screenshots beat imagination: fix blank renders, overflow, text collision, illegible contrast, missing assets, and awkward crop/framing before handoff.
+
+---
+
+## 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 + line-height + size (not size alone)? Do surfaces carry 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.
+5. The delivered UI must survive real viewport inspection: no overlap, clipped text, missing states, broken font loading, unsupported assets, or default-template composition.

package/template/.aioson/skills/design/interface-design/references/intent-and-domain.md

@@ -1,74 +1,74 @@
-# Intent and Domain — Interface Design
-
-> Read this before touching layout, tokens, or components.
-> Generic is the enemy. Every spacing value, typeface choice, and depth strategy is a decision. Own every one of them.
-
----
-
-## The mandate
-
-If another AI, given the same prompt, would produce substantially the same output — you have failed.
-Defaults disguise themselves as infrastructure. Craft means owning every decision.
-
----
-
-## Design memory and continuity
-
-If `.interface-design/system.md` exists, treat it as the visual source of truth:
-- Load it before changing direction, tokens, or component patterns.
-- Respect it unless the user explicitly wants a redesign.
-- Update it when you introduce a reusable pattern, token rule, or layout decision.
-
-If the file does not exist and the task covers more than one screen or component family, create it with:
-- Product context and UI intent
-- Chosen design direction and anti-goals
-- Token decisions (color, type, spacing, radius, depth, motion)
-- Core component patterns (navigation, card, table, form, modal, empty state)
-- Open constraints or decisions still pending
-
-One product should not look like it was designed from scratch on every screen.
-
----
-
-## If the UI already exists
-
-When refining an existing product:
-- Identify the current visual direction before proposing a new one.
-- Diagnose token drift first: off-grid spacing, repeated hardcoded colors, mixed radii, mixed depth strategies, missing interactive states.
-- Improve consistency before re-theming.
-- Replace the direction only when the current system blocks the product intent or the user explicitly asked for a redesign.
-
----
-
-## Phase 0 — Intent first (mandatory, cannot skip)
-
-Before touching layout or tokens, answer three questions with specificity:
-
-1. **Who is this human?** — Actual person, actual context.
-   Bad: "a user." Good: "a finance manager reviewing budget reports at 8am before a board meeting."
-2. **What must they accomplish?** — A specific verb, not a vague goal.
-   Bad: "manage their projects." Good: "approve or reject 15 expense requests before end of day."
-3. **What should this feel like?** — Concrete texture, not an adjective.
-   Bad: "clean and modern." Good: "a Bloomberg terminal that doesn't exhaust you."
-
-**If you cannot answer all three with specifics — stop. Ask. Do not guess. Do not default.**
-
----
-
-## Phase 1 — Domain exploration (4 required outputs)
-
-Before proposing any visual direction, produce:
-
-1. **Domain concepts** — 5+ metaphors, patterns, or ideas from the product's world.
-   Example (clinic scheduling): appointment slots, patient flow, triage priority, clinical notes, white coat.
-
-2. **Color world** — 5+ colors that exist naturally in that domain.
-   Example (clinic): antiseptic white, calm blue (trust, clinical), soft green (go/available), amber (warning/urgent), warm gray (neutral).
-
-3. **Signature element** — One thing that could only belong to THIS product.
-   Example: a subtle "pulse" animation on available time slots, echoing a heartbeat.
-
-4. **Defaults to avoid** — 3 obvious, generic choices that must be replaced.
-   Example: blue primary button → calm teal; card shadows → border-only depth; Inter font → IBM Plex Sans (clinical precision).
-
-**The identity test:** Remove the product name. Could someone identify what this is for?
+# Intent and Domain — Interface Design
+
+> Read this before touching layout, tokens, or components.
+> Generic is the enemy. Every spacing value, typeface choice, and depth strategy is a decision. Own every one of them.
+
+---
+
+## The mandate
+
+If another AI, given the same prompt, would produce substantially the same output — you have failed.
+Defaults disguise themselves as infrastructure. Craft means owning every decision.
+
+---
+
+## Design memory and continuity
+
+If `.interface-design/system.md` exists, treat it as the visual source of truth:
+- Load it before changing direction, tokens, or component patterns.
+- Respect it unless the user explicitly wants a redesign.
+- Update it when you introduce a reusable pattern, token rule, or layout decision.
+
+If the file does not exist and the task covers more than one screen or component family, create it with:
+- Product context and UI intent
+- Chosen design direction and anti-goals
+- Token decisions (color, type, spacing, radius, depth, motion)
+- Core component patterns (navigation, card, table, form, modal, empty state)
+- Open constraints or decisions still pending
+
+One product should not look like it was designed from scratch on every screen.
+
+---
+
+## If the UI already exists
+
+When refining an existing product:
+- Identify the current visual direction before proposing a new one.
+- Diagnose token drift first: off-grid spacing, repeated hardcoded colors, mixed radii, mixed depth strategies, missing interactive states.
+- Improve consistency before re-theming.
+- Replace the direction only when the current system blocks the product intent or the user explicitly asked for a redesign.
+
+---
+
+## Phase 0 — Intent first (mandatory, cannot skip)
+
+Before touching layout or tokens, answer three questions with specificity:
+
+1. **Who is this human?** — Actual person, actual context.
+   Bad: "a user." Good: "a finance manager reviewing budget reports at 8am before a board meeting."
+2. **What must they accomplish?** — A specific verb, not a vague goal.
+   Bad: "manage their projects." Good: "approve or reject 15 expense requests before end of day."
+3. **What should this feel like?** — Concrete texture, not an adjective.
+   Bad: "clean and modern." Good: "a Bloomberg terminal that doesn't exhaust you."
+
+**If you cannot answer all three with specifics — stop. Ask. Do not guess. Do not default.**
+
+---
+
+## Phase 1 — Domain exploration (4 required outputs)
+
+Before proposing any visual direction, produce:
+
+1. **Domain concepts** — 5+ metaphors, patterns, or ideas from the product's world.
+   Example (clinic scheduling): appointment slots, patient flow, triage priority, clinical notes, white coat.
+
+2. **Color world** — 5+ colors that exist naturally in that domain.
+   Example (clinic): antiseptic white, calm blue (trust, clinical), soft green (go/available), amber (warning/urgent), warm gray (neutral).
+
+3. **Signature element** — One thing that could only belong to THIS product.
+   Example: a subtle "pulse" animation on available time slots, echoing a heartbeat.
+
+4. **Defaults to avoid** — 3 obvious, generic choices that must be replaced.
+   Example: blue primary button → calm teal; card shadows → border-only depth; Inter font → IBM Plex Sans (clinical precision).
+
+**The identity test:** Remove the product name. Could someone identify what this is for?