@jaimevalasek/aioson 1.8.0 → 1.9.0

package/template/.aioson/docs/ux-ui/component-map.md

@@ -1,35 +1,35 @@
----
-description: "UI/UX component map mode — component inventory, atomic classification, variants, states, and gap analysis between spec and implementation."
----
-
-# UX/UI Component Map
-
-Activate via `@ux-ui component-map`.
-
-## Step 1 — Scan
-
-- if code exists, scan `src/`, `components/`, `app/`, and `pages/` for visual patterns
-- if `ui-spec.md` exists, extract the component list from the spec
-- if `design_skill` is set, load the skill's component catalog
-
-## Step 2 — Classify
-
-For each component found, record:
-
-| Component | Category | Variants | States | Used in |
-|---|---|---|---|---|
-| `Button` | atom | primary, secondary, ghost | default, hover, focus, active, disabled, loading | Header, Hero CTA, Forms |
-
-Categories follow Atomic Design: atom → molecule → organism → template.
-
-## Step 3 — Gap analysis
-
-Identify:
-- components that exist in the spec but not in code
-- components that exist in code but not in the spec
-- near-duplicate components that should be consolidated
-- missing states or variants
-
-## Output
-
-- write to `.aioson/context/ui-component-map.md`
+---
+description: "UI/UX component map mode — component inventory, atomic classification, variants, states, and gap analysis between spec and implementation."
+---
+
+# UX/UI Component Map
+
+Activate via `@ux-ui component-map`.
+
+## Step 1 — Scan
+
+- if code exists, scan `src/`, `components/`, `app/`, and `pages/` for visual patterns
+- if `ui-spec.md` exists, extract the component list from the spec
+- if `design_skill` is set, load the skill's component catalog
+
+## Step 2 — Classify
+
+For each component found, record:
+
+| Component | Category | Variants | States | Used in |
+|---|---|---|---|---|
+| `Button` | atom | primary, secondary, ghost | default, hover, focus, active, disabled, loading | Header, Hero CTA, Forms |
+
+Categories follow Atomic Design: atom → molecule → organism → template.
+
+## Step 3 — Gap analysis
+
+Identify:
+- components that exist in the spec but not in code
+- components that exist in code but not in the spec
+- near-duplicate components that should be consolidated
+- missing states or variants
+
+## Output
+
+- write to `.aioson/context/ui-component-map.md`

package/template/.aioson/docs/ux-ui/design-execution.md

@@ -1,111 +1,111 @@
----
-description: "UI/UX design execution — entry check, refine-vs-rebuild routing, design intent, domain exploration, direction selection, and delivery quality rules."
----
-
-# UX/UI Design Execution
-
-Use this module for the default creation flow and for `refine-spec`.
-
-## Entry check
-
-Run before Step 1:
-
-1. Does `.aioson/context/ui-spec.md` exist?
-2. Does `index.html` exist in the project root? Relevant when `project_type=site`.
-3. Do component or layout files exist in `src/`, `components/`, `app/`, or `pages/`?
-
-If none exist, proceed directly to the creation flow.
-
-If any exist, ask:
-
-> "I can see this project already has UI. What would you like to do?
-> → **Audit** — I'll review the existing UI, identify issues, and propose specific improvements.
-> → **Refine spec** — I'll update `ui-spec.md` without touching the existing implementation.
-> → **Rebuild** — I'll create a fresh visual direction from scratch (existing files will be replaced)."
-
-Routing:
-- **Audit** → switch to `audit-mode.md`
-- **Refine spec** → read `ui-spec.md`, identify gaps or drift, update in place
-- **Rebuild** → warn that `index.html` and `ui-spec.md` will be overwritten, then confirm before continuing
-
-## Step 1 — Intent
-
-Answer these three questions before any layout or token work:
-
-1. Who exactly is visiting this?
-2. What must they do or feel?
-3. What should this feel like?
-
-If you cannot answer all three with specifics, ask. Do not guess.
-
-## Step 2 — Domain exploration
-
-Produce all four before proposing visuals:
-
-1. **Domain concepts** — 5+ metaphors or patterns from this product's world
-2. **Color world** — 5+ colors that exist naturally in this domain
-3. **Signature element** — one visual thing that could only belong to this product
-4. **Defaults to avoid** — 3 generic choices to replace with intentional ones
-
-Identity test: remove the product name. Can someone still identify what this is for?
-
-## Step 3 — Design direction
-
-Choose one direction. Never mix incompatible directions.
-
-### For apps, dashboards, SaaS
-- **Precision & Density** — dashboards, admin, dev tools. Borders-only, compact, cool slate.
-- **Warmth & Approachability** — consumer apps, onboarding. Shadows, generous spacing, warm tones.
-- **Sophistication & Trust** — fintech, enterprise. Cold palette, restrained layers, firm typography.
-- **Premium Dark Platform** — premium dark product UI, controlled contrast, restrained layers, catalog cards, and clean navigation.
-- **Minimal & Calm** — near-monochrome, whitespace as design element, hairline borders.
-
-### For landing pages and sites
-- **Clean & Luminous** — light surfaces, one strong accent, large confident headings, subtle fade-up animation.
-- **Bold & Cinematic** — dark hero, full-bleed photography, gradient overlays, scroll reveals.
-
-## Visual continuity
-
-When the work spans more than one screen:
-- shared surfaces must stay visually identical across screens
-- token values must be consistent for the same purpose
-- component variants must be reused, not reinvented
-- depth strategy must stay consistent across screens
-- when adding a new screen, explicitly note which existing components and tokens are being reused
-
-## Non-site fallback
-
-If `project_type≠site` and the user explicitly proceeds without a registered `design_skill`, use the fallback directions in this module and output:
-- `ui-spec.md` with token block
-- token ownership
-- screen map
-- component state matrix
-- responsive rules
-- handoff notes
-
-## Working rules
-- Stack first: use the project's existing design system before proposing custom UI.
-- Ask about style only when the ambiguity would materially change the result.
-- Define complete design tokens: spacing, typography, semantic colors, radius, and depth strategy.
-- Declare token ownership explicitly.
-- Commit to one depth strategy per surface type.
-- Accessibility first: keyboard flow, visible focus rings, semantic HTML, and 4.5:1 contrast minimum.
-- State completeness: default, hover, focus, active, disabled, loading, empty, error, success.
-- Mobile-first: small screens defined before desktop enhancements.
-- `prefers-reduced-motion` fallback required for any motion.
-- Scope proportional to classification: MICRO → root HTML only, SMALL → spec + HTML, MEDIUM → full spec.
-
-## Quality checks
-- **Swap test** — would changing the typeface make this look like a different product?
-- **Squint test** — does hierarchy survive when blurred?
-- **Signature test** — can you name 5 design decisions unique to this product?
-- **Wow test** — for landing pages only, would someone screenshot this and share it? If not, revise.
-
-## Self-critique
-
-Before delivering, check:
-
-1. **Composition** — rhythm, intentional proportions, one clear focal point per screen
-2. **Craft** — spacing on-grid, typography uses weight + tracking + size, surfaces whisper hierarchy
-3. **Content** — real copy, real image URLs, coherent story from hero to final CTA
-4. **Structure** — no placeholder text, no arbitrary pixel values, no hacks
+---
+description: "UI/UX design execution — entry check, refine-vs-rebuild routing, design intent, domain exploration, direction selection, and delivery quality rules."
+---
+
+# UX/UI Design Execution
+
+Use this module for the default creation flow and for `refine-spec`.
+
+## Entry check
+
+Run before Step 1:
+
+1. Does `.aioson/context/ui-spec.md` exist?
+2. Does `index.html` exist in the project root? Relevant when `project_type=site`.
+3. Do component or layout files exist in `src/`, `components/`, `app/`, or `pages/`?
+
+If none exist, proceed directly to the creation flow.
+
+If any exist, ask:
+
+> "I can see this project already has UI. What would you like to do?
+> → **Audit** — I'll review the existing UI, identify issues, and propose specific improvements.
+> → **Refine spec** — I'll update `ui-spec.md` without touching the existing implementation.
+> → **Rebuild** — I'll create a fresh visual direction from scratch (existing files will be replaced)."
+
+Routing:
+- **Audit** → switch to `audit-mode.md`
+- **Refine spec** → read `ui-spec.md`, identify gaps or drift, update in place
+- **Rebuild** → warn that `index.html` and `ui-spec.md` will be overwritten, then confirm before continuing
+
+## Step 1 — Intent
+
+Answer these three questions before any layout or token work:
+
+1. Who exactly is visiting this?
+2. What must they do or feel?
+3. What should this feel like?
+
+If you cannot answer all three with specifics, ask. Do not guess.
+
+## Step 2 — Domain exploration
+
+Produce all four before proposing visuals:
+
+1. **Domain concepts** — 5+ metaphors or patterns from this product's world
+2. **Color world** — 5+ colors that exist naturally in this domain
+3. **Signature element** — one visual thing that could only belong to this product
+4. **Defaults to avoid** — 3 generic choices to replace with intentional ones
+
+Identity test: remove the product name. Can someone still identify what this is for?
+
+## Step 3 — Design direction
+
+Choose one direction. Never mix incompatible directions.
+
+### For apps, dashboards, SaaS
+- **Precision & Density** — dashboards, admin, dev tools. Borders-only, compact, cool slate.
+- **Warmth & Approachability** — consumer apps, onboarding. Shadows, generous spacing, warm tones.
+- **Sophistication & Trust** — fintech, enterprise. Cold palette, restrained layers, firm typography.
+- **Premium Dark Platform** — premium dark product UI, controlled contrast, restrained layers, catalog cards, and clean navigation.
+- **Minimal & Calm** — near-monochrome, whitespace as design element, hairline borders.
+
+### For landing pages and sites
+- **Clean & Luminous** — light surfaces, one strong accent, large confident headings, subtle fade-up animation.
+- **Bold & Cinematic** — dark hero, full-bleed photography, gradient overlays, scroll reveals.
+
+## Visual continuity
+
+When the work spans more than one screen:
+- shared surfaces must stay visually identical across screens
+- token values must be consistent for the same purpose
+- component variants must be reused, not reinvented
+- depth strategy must stay consistent across screens
+- when adding a new screen, explicitly note which existing components and tokens are being reused
+
+## Non-site fallback
+
+If `project_type≠site` and the user explicitly proceeds without a registered `design_skill`, use the fallback directions in this module and output:
+- `ui-spec.md` with token block
+- token ownership
+- screen map
+- component state matrix
+- responsive rules
+- handoff notes
+
+## Working rules
+- Stack first: use the project's existing design system before proposing custom UI.
+- Ask about style only when the ambiguity would materially change the result.
+- Define complete design tokens: spacing, typography, semantic colors, radius, and depth strategy.
+- Declare token ownership explicitly.
+- Commit to one depth strategy per surface type.
+- Accessibility first: keyboard flow, visible focus rings, semantic HTML, and 4.5:1 contrast minimum.
+- State completeness: default, hover, focus, active, disabled, loading, empty, error, success.
+- Mobile-first: small screens defined before desktop enhancements.
+- `prefers-reduced-motion` fallback required for any motion.
+- Scope proportional to classification: MICRO → root HTML only, SMALL → spec + HTML, MEDIUM → full spec.
+
+## Quality checks
+- **Swap test** — would changing the typeface make this look like a different product?
+- **Squint test** — does hierarchy survive when blurred?
+- **Signature test** — can you name 5 design decisions unique to this product?
+- **Wow test** — for landing pages only, would someone screenshot this and share it? If not, revise.
+
+## Self-critique
+
+Before delivering, check:
+
+1. **Composition** — rhythm, intentional proportions, one clear focal point per screen
+2. **Craft** — spacing on-grid, typography uses weight + tracking + size, surfaces whisper hierarchy
+3. **Content** — real copy, real image URLs, coherent story from hero to final CTA
+4. **Structure** — no placeholder text, no arbitrary pixel values, no hacks

package/template/.aioson/docs/ux-ui/design-gate.md

@@ -1,27 +1,27 @@
----
-description: "UI/UX design gate — context repair, design skill selection, isolation rules, and style ambiguity handling before visual direction is chosen."
----
-
-# UX/UI Design Gate
-
-Load this module before any operation that creates or revises visual direction.
-
-## Step 0 — Design skill gate
-
-Read `.aioson/context/project.context.md` before deciding direction, theme, or density.
-
-Rules:
-- if `project.context.md` contains stale or inconsistent metadata that affects visual work, repair the objectively inferable fields before continuing
-- if `design_skill` is already set, load `.aioson/skills/design/{design_skill}/SKILL.md` before making visual decisions
-- when `design_skill` is set, treat that package as the single source of truth for visual language, typography, component rhythm, and page composition
-- if `project_type=site` or `project_type=web_app` and `design_skill` is blank, ask the user which installed design skill to use before producing new visual direction
-- if only one packaged design skill is installed, still ask for confirmation instead of auto-selecting it
-- if the user chooses to proceed without one, state clearly: `Proceeding without a registered design skill.`
-- never silently invent, swap, auto-pick, or mix design skills
-- never use context inconsistency as a reason to leave the workflow
-- when `design_skill` is set, do not load, reference, or apply visual rules from another design package
-
-Once the gate is resolved:
-- if the user gave an explicit theme or style preference, obey it
-- otherwise infer the direction from product context and the selected design skill
-- ask at most one short style question only when the ambiguity is material
+---
+description: "UI/UX design gate — context repair, design skill selection, isolation rules, and style ambiguity handling before visual direction is chosen."
+---
+
+# UX/UI Design Gate
+
+Load this module before any operation that creates or revises visual direction.
+
+## Step 0 — Design skill gate
+
+Read `.aioson/context/project.context.md` before deciding direction, theme, or density.
+
+Rules:
+- if `project.context.md` contains stale or inconsistent metadata that affects visual work, repair the objectively inferable fields before continuing
+- if `design_skill` is already set, load `.aioson/skills/design/{design_skill}/SKILL.md` before making visual decisions
+- when `design_skill` is set, treat that package as the single source of truth for visual language, typography, component rhythm, and page composition
+- if `project_type=site` or `project_type=web_app` and `design_skill` is blank, ask the user which installed design skill to use before producing new visual direction
+- if only one packaged design skill is installed, still ask for confirmation instead of auto-selecting it
+- if the user chooses to proceed without one, state clearly: `Proceeding without a registered design skill.`
+- never silently invent, swap, auto-pick, or mix design skills
+- never use context inconsistency as a reason to leave the workflow
+- when `design_skill` is set, do not load, reference, or apply visual rules from another design package
+
+Once the gate is resolved:
+- if the user gave an explicit theme or style preference, obey it
+- otherwise infer the direction from product context and the selected design skill
+- ask at most one short style question only when the ambiguity is material

package/template/.aioson/docs/ux-ui/research-mode.md

@@ -1,39 +1,39 @@
----
-description: "UI/UX research mode — visual benchmarking, domain patterns, anti-patterns, and directional hypotheses before design work begins."
----
-
-# UX/UI Research Mode
-
-Activate via `@ux-ui research`.
-
-## Step 1 — Gather context
-
-Read all available artifacts:
-- `project.context.md`
-- `prd.md`
-- `discovery.md`
-- `architecture.md`
-
-## Step 2 — Visual benchmarking
-
-For the product domain, document:
-
-1. **3–5 reference products** — what works, what does not, and one detail worth borrowing
-2. **Visual patterns** — recurring layouts, interaction styles, or UI structures in the domain
-3. **Anti-patterns** — common UI mistakes in the domain to avoid
-4. **User expectations** — what the audience already understands visually
-
-## Step 3 — Directional hypotheses
-
-Propose 2–3 design directions. For each one include:
-- direction name
-- rationale
-- mood description
-- color palette sketch with 3–5 colors
-- typography suggestion
-- risk: what could go wrong with this direction
-
-## Output
-
-- write to `.aioson/context/ui-research.md`
-- the default creation flow may consume this artifact when choosing direction
+---
+description: "UI/UX research mode — visual benchmarking, domain patterns, anti-patterns, and directional hypotheses before design work begins."
+---
+
+# UX/UI Research Mode
+
+Activate via `@ux-ui research`.
+
+## Step 1 — Gather context
+
+Read all available artifacts:
+- `project.context.md`
+- `prd.md`
+- `discovery.md`
+- `architecture.md`
+
+## Step 2 — Visual benchmarking
+
+For the product domain, document:
+
+1. **3–5 reference products** — what works, what does not, and one detail worth borrowing
+2. **Visual patterns** — recurring layouts, interaction styles, or UI structures in the domain
+3. **Anti-patterns** — common UI mistakes in the domain to avoid
+4. **User expectations** — what the audience already understands visually
+
+## Step 3 — Directional hypotheses
+
+Propose 2–3 design directions. For each one include:
+- direction name
+- rationale
+- mood description
+- color palette sketch with 3–5 colors
+- typography suggestion
+- risk: what could go wrong with this direction
+
+## Output
+
+- write to `.aioson/context/ui-research.md`
+- the default creation flow may consume this artifact when choosing direction