@jaimevalasek/aioson 1.7.2 → 1.9.0

package/template/.aioson/docs/tester/coverage-quality.md

@@ -0,0 +1,351 @@
+---
+description: "Tester deep guide — mutation testing, property-based patterns, test smells catalog, contract testing, adjacent quality layers. Load when entering Phase 4 on critical modules or when a coverage gap requires graduated assertion quality."
+---
+
+# Tester — Coverage Quality Beyond Line %
+
+Line coverage tells you which lines ran. It tells you nothing about whether the test caught the bug. This module is the playbook for graduating from "lines covered" to "bugs prevented".
+
+Load this when:
+- Critical modules (auth, money, ownership, irreversible actions) reach line coverage ≥ 80% and need stronger evidence.
+- Existing tests pass but the user reports bugs in production (signal: weak assertions, missing failure-mode tests).
+- A failing mutation, property, or pact test surfaces in CI and you need to interpret it.
+
+## 1. The four-tier coverage quality ladder
+
+| Tier | Metric | Target overall | Target critical paths |
+|---|---|---|---|
+| 1 — Line | line coverage | ≥ 80% | ≥ 90% |
+| 2 — Branch | branch / decision coverage | ≥ 60% | ≥ 80% |
+| 3 — Mutation | mutation score | not required overall | ≥ 80% on critical modules |
+| 4 — Property | invariants on serializers, calculators, state machines | n/a | one property test per critical invariant |
+
+**Critical paths** (always treated as critical):
+- Authentication, authorization, ownership boundaries
+- Money / value transfer, balance accounting
+- Irreversible actions (delete, send, publish)
+- Public APIs that other systems consume
+- State machines with consistency invariants (queues, ledgers, inventory)
+
+## 2. Mutation testing — the actual quality signal
+
+### 2.1 Tooling by stack
+
+| Stack | Tool | Install |
+|---|---|---|
+| JavaScript / TypeScript | `@stryker-mutator/core` | `npm i -D @stryker-mutator/core` |
+| .NET | Stryker.NET | `dotnet tool install -g dotnet-stryker` |
+| PHP (Laravel/Symfony) | Infection | `composer require --dev infection/infection` |
+| Python | mutmut | `pip install mutmut` |
+| Java | PIT | Maven/Gradle plugin |
+| Ruby | mutant | `gem install mutant` |
+| Solidity | (no true mutation tool — `forge fuzz` is closest analog) | — |
+
+### 2.2 Threshold configuration
+
+Working defaults (project-wide):
+```yaml
+# Stryker (JS/TS) — stryker.conf.json
+{
+  "thresholds": { "high": 80, "low": 70, "break": 70 },
+  "mutate": ["src/**/*.ts", "!src/**/*.test.ts", "!src/**/*.spec.ts"]
+}
+```
+
+For legacy code being driven up: `high: 80, low: 60, break: 50`. The `break` value fails the build.
+
+### 2.3 What to do with the score
+
+- **80–100%**: ship. Track over time as quality leading indicator.
+- **60–80%**: identify survived mutants by category — boundary conditions and conditional logic produce the most valuable feedback.
+- **< 60%**: tests are coincidentally passing; rewrite assertions or add property-based tests.
+
+### 2.4 When to run
+
+- **Full codebase**: nightly CI job. 10×–100× normal test runtime; never run on every push.
+- **Incremental** (changed files only): every PR via `--since` flag (Stryker) or equivalent. Adds ~30 s–2 min depending on diff size.
+- **First-time adoption**: pick one critical module, run mutation, fix survived mutants, ratchet. Don't try to mutate the whole repo on day one.
+
+### 2.5 Survived mutant — example workflow
+
+```
+SURVIVED  src/auth/jwt.ts:42:10  Boolean replacement (true → false)
+```
+
+The mutator changed `if (token.expired === true)` to `if (token.expired === false)` and your tests still passed → the test never exercises the `expired` branch. Action: add a test that boots an expired token and asserts rejection.
+
+## 3. Property-based testing — the five canonical patterns
+
+Property-based tests describe a property that must hold for *all* inputs, then the framework generates inputs that try to break it. One good property test replaces dozens of brittle example tests.
+
+### 3.1 Round-trip (most common, easiest first win)
+
+`decode(encode(x)) == x`. Any serialization, encoding, compression, encryption.
+
+```ts
+// fast-check
+import fc from 'fast-check';
+import { encode, decode } from './codec';
+
+test('codec round-trip', () => {
+  fc.assert(fc.property(fc.anything(), (x) => {
+    expect(decode(encode(x))).toEqual(x);
+  }));
+});
+```
+
+```python
+# Hypothesis
+from hypothesis import given, strategies as st
+from codec import encode, decode
+
+@given(st.dictionaries(st.text(), st.integers()))
+def test_codec_round_trip(payload):
+    assert decode(encode(payload)) == payload
+```
+
+### 3.2 Invariants (always-true properties)
+
+```ts
+test('sort preserves multiset and orders ascending', () => {
+  fc.assert(fc.property(fc.array(fc.integer()), (xs) => {
+    const sorted = sort(xs);
+    expect(sorted.length).toBe(xs.length);
+    expect([...sorted].sort((a,b)=>a-b)).toEqual(sorted);
+  }));
+});
+```
+
+```python
+@given(st.lists(st.integers()))
+def test_balance_never_negative(transactions):
+    account = Account(starting_balance=100)
+    for t in transactions:
+        account.apply(t)
+    assert account.balance >= 0  # invariant
+```
+
+### 3.3 Stateful (sequence-based)
+
+Generate sequences of operations; replay must reach a consistent state regardless of order. Critical for ledgers, inventory, queues.
+
+```python
+# Hypothesis stateful
+from hypothesis.stateful import RuleBasedStateMachine, rule, invariant
+
+class LedgerMachine(RuleBasedStateMachine):
+    def __init__(self):
+        super().__init__()
+        self.ledger = Ledger()
+
+    @rule(amount=st.integers(min_value=1, max_value=1000))
+    def deposit(self, amount):
+        self.ledger.deposit(amount)
+
+    @rule(amount=st.integers(min_value=1, max_value=1000))
+    def withdraw(self, amount):
+        try: self.ledger.withdraw(amount)
+        except InsufficientFunds: pass
+
+    @invariant()
+    def balance_matches_history(self):
+        assert self.ledger.balance == sum(self.ledger.history)
+```
+
+### 3.4 Differential (compare two implementations)
+
+When migrating from a legacy implementation to a new one, or comparing optimized vs reference. Same input → same output.
+
+```ts
+test('new sort matches legacy sort on all inputs', () => {
+  fc.assert(fc.property(fc.array(fc.integer()), (xs) => {
+    expect(newSort(xs)).toEqual(legacySort(xs));
+  }));
+});
+```
+
+### 3.5 Metamorphic (relations between inputs/outputs)
+
+When there's no single correct answer, only relative correctness.
+
+```ts
+test('reverse(reverse(x)) == x', () => {
+  fc.assert(fc.property(fc.string(), (s) => {
+    expect(reverse(reverse(s))).toBe(s);
+  }));
+});
+
+test('sum(reverse(xs)) == sum(xs)', () => {
+  fc.assert(fc.property(fc.array(fc.integer()), (xs) => {
+    expect(sum(reverse(xs))).toBe(sum(xs));
+  }));
+});
+```
+
+### 3.6 Solidity / Foundry fuzz
+
+```solidity
+function testFuzz_transferNeverExceedsBalance(uint256 amount) public {
+    amount = bound(amount, 0, token.balanceOf(alice));
+    uint256 before = token.balanceOf(bob);
+    vm.prank(alice);
+    token.transfer(bob, amount);
+    assertEq(token.balanceOf(bob), before + amount);
+}
+
+function invariant_TotalSupplyEqualsSumOfBalances() public {
+    assertEq(token.totalSupply(), token.balanceOf(alice) + token.balanceOf(bob));
+}
+```
+
+### 3.7 When to use property-based vs example tests
+
+- **Property-based**: for invariants, codecs, calculators, state machines, parsers. The gain is finding edge cases you didn't think of.
+- **Example tests**: for known-bug regressions, specific business rules with named inputs, UI flows. The gain is readable documentation.
+- Use both. They are complements, not substitutes.
+
+## 4. Test smell self-audit — Phase 4.5 checklist
+
+Run this checklist after writing tests, before declaring Phase 4 done. Each smell links to a specific refactor.
+
+### 4.1 Eager Test
+**Symptom**: one test contains 10+ assertions on unrelated behaviors.
+**Detection**: count `expect`/`assert` statements per test; > 5 unrelated → eager.
+**Fix**: split into one test per behavior. Name each by what it asserts.
+
+### 4.2 Mystery Guest
+**Symptom**: test reads from a file, env var, current time, or external service without explicit setup.
+**Detection**: grep for `fs.readFile`, `process.env`, `new Date()`, `Date.now()`, `fetch(` inside test bodies.
+**Fix**: inject the dependency. Use `vi.useFakeTimers()` / `freezegun` for time.
+
+### 4.3 Test Run War
+**Symptom**: tests pass alone, fail when run together. Or: parallel runs are flaky.
+**Detection**: run with `--shuffle` (Pest) / `vitest --no-isolate` / `pytest -p no:randomly`. Or simply re-run 10×.
+**Fix**: per-test fresh database, in-memory state, or transactional rollback.
+
+### 4.4 Conditional Test Logic
+**Symptom**: `if`/`else` or loops inside the test body.
+**Detection**: AST scan or eyeball.
+**Fix**: parameterize (`it.each` / `pytest.mark.parametrize`) or split.
+
+### 4.5 Redundant Assertion
+**Symptom**: `assert.equal(x, x)`, `expect(true).toBe(true)`, multiple assertions verifying the same property.
+**Detection**: identical LHS/RHS, or repeated equivalent assertions on the same value.
+**Fix**: delete.
+
+### 4.6 Mock Overdose
+**Symptom**: more than ~50% of test setup is mocks; the test verifies the mock, not the system.
+**Detection**: count mock invocations vs system invocations in setup.
+**Fix**: write an integration test instead. If integration is too slow/complex, the abstraction is wrong — escalate to `@architect`.
+
+### 4.7 Tools
+
+- **JS/TS**: `eslint-plugin-vitest`, `eslint-plugin-jest` rules cover most static smells.
+- **Java**: TASTE, JNose Test, tsdetect.
+- **Python**: `pylint` custom rules for `pytest` smells.
+- **Generic fallback**: write the checklist above as a code review template.
+
+### 4.8 Auto-generated tests are higher-smell
+
+Tests generated by EvoSuite, Pynguin, or LLMs are 2–3× denser in smells than human-written tests. Treat anything generated as a *draft*: check every test for Mystery Guest and Mock Overdose before keeping.
+
+## 5. Consumer-Driven Contract Testing (Pact)
+
+### 5.1 When it applies
+
+Two or more services with explicit boundaries: microservices, mobile↔backend, frontend↔BFF, public APIs. Skip if the codebase is a single deployable.
+
+### 5.2 The discipline
+
+1. **Consumer writes** the contract from real client code (not mocks of the contract).
+2. **Pact library generates** the pact file from the consumer test run.
+3. **Provider verifies** against the latest pact file fetched from the broker (Pactflow, self-hosted).
+4. **CI pipeline**: provider verification blocks deploy on red; consumer publishes pact on every commit.
+
+### 5.3 Best practices
+
+- **Loose contracts**: match only fields the consumer reads. Tightening leaks implementation details and creates false breakage.
+- **Real consumer code**: contract tests must exercise the actual HTTP client / SDK, not a mock of it.
+- **Separate from E2E**: pact answers "do the contracts match?", E2E answers "does the user flow work?". Different failure modes; don't mix them.
+- **Anti-pattern**: writing pact tests against mock providers — validates the mock, not the integration.
+
+### 5.4 Minimal example (Node + pact-js)
+
+```ts
+const { PactV3, MatchersV3 } = require('@pact-foundation/pact');
+
+const provider = new PactV3({ consumer: 'frontend', provider: 'orders-api' });
+
+test('GET /orders/:id returns order', async () => {
+  provider
+    .given('order 42 exists')
+    .uponReceiving('a request for order 42')
+    .withRequest({ method: 'GET', path: '/orders/42' })
+    .willRespondWith({
+      status: 200,
+      body: MatchersV3.like({ id: 42, total: 100, status: 'paid' })
+    });
+
+  await provider.executeTest(async (mockServer) => {
+    const order = await fetchOrder(mockServer.url, 42);  // real consumer code
+    expect(order.id).toBe(42);
+  });
+});
+```
+
+## 6. Adjacent quality layers — opt-in by trigger
+
+Don't auto-load. Add only when the trigger fires.
+
+| Layer | Trigger | Tooling |
+|---|---|---|
+| Snapshot | Stable UI/DOM/JSON output | `vitest --update`, `jest --ci`, `__snapshots__/` |
+| Visual regression | Design-system-stable UI | Percy, Chromatic, Playwright `toHaveScreenshot()` |
+| Accessibility | User-facing UI | `axe-core`, `jest-axe`, `playwright/axe` |
+| Load / performance | Public API or perf-sensitive flow | `k6`, `locust`, `artillery` |
+| Dependency vuln scan | Every project | `npm audit`, `pip-audit`, `OSV-Scanner`, `Snyk`, `Trivy` |
+
+**Rules:**
+- Snapshot — sanitize timestamps and IDs before snapshotting; never snapshot dynamic data.
+- Visual — high cost (storage, antialiasing flake); only when design system is stable.
+- A11y — one automated pass catches ~30% of WCAG issues; doesn't replace human/assistive-tech testing.
+- Load — separate suite, never blocks unit/integration; report against agreed SLOs.
+- Depscan — treat as test signal in CI, fail PRs on `high`/`critical` CVEs unless explicitly accepted.
+
+## 7. Reporting template
+
+When invoked on a feature, produce this structure in `test-plan.md`:
+
+```markdown
+## Coverage Quality Report — {feature/module} — {date}
+
+### Tier 1 — Line coverage
+- Module: src/auth/  →  87% (target ≥ 90% critical) ⚠
+- Module: src/orders/ →  82% (target ≥ 80% overall) ✓
+
+### Tier 2 — Branch coverage
+- src/auth/jwt.ts: 64% — gap: error-path branches uncovered
+- src/orders/cart.ts: 71% ✓
+
+### Tier 3 — Mutation score (critical modules only)
+- src/auth/jwt.ts: 73% (target ≥ 80%) ⚠ — survivors:
+  - jwt.ts:42:10 boolean replacement (expired check)
+  - jwt.ts:58:14 conditional boundary (>= → >)
+
+### Tier 4 — Property-based
+- ✓ codec round-trip (auth/token.ts)
+- ✗ ledger-balance-invariant — not implemented yet
+
+### Test smells found
+- Mystery Guest in tests/auth.test.ts:88 (reads JWT_SECRET from env)
+- Mock Overdose in tests/orders.test.ts (8 mocks for 1 system call)
+
+### Recommendations
+- Cover the two survived mutants in jwt.ts before merge.
+- Add ledger-balance invariant property test.
+- Refactor 2 smells before next sprint.
+```
+
+## 8. References
+
+This document distills `researchs/tester-coverage-quality-2026/summary.md`. See that file for the full source list and verdict.

package/template/.aioson/docs/ux-ui/accessibility-audit.md

@@ -0,0 +1,55 @@
+---
+description: "UI/UX accessibility audit mode — WCAG-focused scan, remediation format, and QA handoff guidance for UI accessibility issues."
+---
+
+# UX/UI Accessibility Audit
+
+Activate via `@ux-ui a11y`.
+
+## Step 1 — Scan
+
+Read UI code and check:
+
+| Category | Checks |
+|---|---|
+| Perceivable | Contrast, alt text, captions |
+| Operable | Keyboard reachability, focus rings, no keyboard traps, skip links |
+| Understandable | `lang` attribute, label association, clear errors |
+| Robust | Semantic HTML first, ARIA only when needed, no div-as-button |
+| Motion | `prefers-reduced-motion`, no uncontrolled long autoplay animation |
+
+## Step 2 — Produce findings
+
+Use this structure:
+
+```markdown
+## Accessibility Report — [Project Name]
+
+### Summary
+- WCAG 2.1 AA compliance: [estimated %]
+- Critical issues: [count]
+- Total issues: [count]
+
+### 🔴 Critical
+- [Issue]: [specific element] → [concrete fix]
+
+### 🟡 Important
+- [Issue]: [specific element] → [concrete fix]
+
+### 🟢 Enhancement
+- [Suggestion]: [specific element] → [improvement]
+
+### ✅ Already compliant
+- [Specific accessibility decision that is correct]
+```
+
+## Step 3 — QA integration
+
+If `@qa` is the next workflow agent, add an `## Accessibility` section with:
+- automated checks to add to the test suite
+- manual checks that still require human verification
+
+## Output
+
+- write to `.aioson/context/ui-a11y.md`
+- do not modify code during this audit

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

@@ -0,0 +1,86 @@
+---
+description: "UI/UX audit mode — inventory scan, design quality checks, severity-based reporting, and fix recommendation format for existing UI."
+---
+
+# UX/UI Audit Mode
+
+Activate when the user chooses **Audit** or invokes `@ux-ui audit`.
+
+## Step 1 — Read existing artifacts
+
+Read all that exist:
+- `index.html` or the main template file
+- `ui-spec.md`
+- up to 5 component files from `src/`, `components/`, `app/`, or `pages/`, prioritizing layout-level files
+
+## Step 2 — Inventory scan
+
+Capture:
+
+| Inventory | What to capture |
+|---|---|
+| Colors | Every unique color value. Flag hardcoded values not in CSS custom properties. |
+| Spacing | Unique margin and padding values. Flag values not aligned to a scale. |
+| Radius | Unique border-radius values. Flag inconsistencies. |
+| Typography | Font families, sizes, and weights used. Flag values not in a type scale. |
+| Components | Visually repeated patterns. Flag near-duplicates that should be consolidated. |
+
+## Step 3 — Run quality checks
+
+Apply each check and record findings:
+
+| Check | What to look for |
+|---|---|
+| Swap test | Could this UI belong to any other product? |
+| Squint test | Is hierarchy clear or does everything compete? |
+| Signature test | Can you name 5 product-specific design decisions? |
+| State completeness | Hover, focus, active, disabled states defined? |
+| Depth consistency | Borders-only and shadows mixed on the same surface type? |
+| Token discipline | Hardcoded values vs CSS custom properties |
+| Accessibility | Contrast, focus, semantic HTML |
+| Mobile-first | Breakpoints and graceful degradation below 768px |
+| Motion safety | `prefers-reduced-motion` respected |
+| Visual continuity | Shared surfaces consistent across screens |
+
+## Step 4 — Produce the audit report
+
+Use this structure:
+
+```markdown
+## UI Audit — [Project Name]
+
+### Inventory
+- Colors: X unique values (Y hardcoded)
+- Spacing: X unique values
+- Radius: X unique values
+- Components: X patterns (Y near-duplicates)
+
+### 🔴 Critical
+- [Issue]: [specific location] → [concrete fix]
+
+### 🟡 Important
+- [Issue]: [specific location] → [concrete fix]
+
+### 🟢 Polish
+- [Issue]: [specific location] → [suggestion]
+
+### ✅ What's working
+- [Specific intentional decision]
+
+### Consolidation plan
+- [Pattern A and Pattern B] → [single component]
+- [Hardcoded values] → [semantic tokens]
+```
+
+Rules:
+- every finding must reference a specific element or line
+- every critical or important finding must include a concrete fix
+- always include at least one "What's working" entry
+- include a consolidation plan when near-duplicates or hardcoded values are found
+- end with: `Want me to apply the critical fixes now, or go through them one by one?`
+
+## Output
+
+- write the report to `.aioson/context/ui-audit.md`
+- do not modify `index.html`, component files, or `ui-spec.md` during audit
+- switch to targeted edits only after the user confirms which fixes to apply

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

@@ -0,0 +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`

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

@@ -0,0 +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

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

@@ -0,0 +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