agemon 0.1.0 → 6.0.0

package/assets/skills/design/agemon-design/references/sound.md

@@ -0,0 +1,150 @@
+# Sound Design for UI
+
+Web Audio API best practices, UI sound appropriateness, and implementation.
+
+---
+
+## When Sound is Appropriate
+
+| Interaction | Sound? | Reason |
+|-------------|--------|--------|
+| Payment success | Yes | Significant confirmation |
+| Form submission | Yes | User needs assurance |
+| Error state | Yes | Can't be overlooked |
+| Notification | Yes | User may not be looking |
+| Significant button | Maybe | Only for important actions |
+| Typing | **No** | Too frequent |
+| Hover | **No** | Decorative only |
+| Scroll | **No** | Too frequent |
+| Navigation | **No** | Keyboard nav would be noisy |
+
+---
+
+## Accessibility Rules
+
+- Every audio cue MUST have a visual equivalent — sound never replaces visual feedback
+- Provide explicit toggle to disable sounds in settings
+- Respect `prefers-reduced-motion` as a default proxy for sound sensitivity, AND provide an explicit independent sound toggle. **Why caveat:** the proxy is imperfect — some users tolerate visual motion but not audio (vestibular conditions, hearing aids), some users tolerate audio but not motion. Always offer a sound toggle separate from motion preference; reduced-motion is the default-off, not the only signal.
+- Allow volume adjustment independent of system volume
+- Never add sound to high-frequency interactions
+- Sound should inform, not punish — avoid harsh sounds for mistakes
+
+---
+
+## Web Audio API Implementation
+
+### Single AudioContext
+
+Single AudioContext per page. Never create new AudioContext per sound. **Why critical:** browsers limit AudioContext instances (typically 6 per page); exhausting them silently fails new sounds. A shared AudioContext also synchronizes timing across rapid-fire UI feedback (typing keystrokes, button clicks within 50ms) — independent contexts desync.
+
+```ts
+let audioContext: AudioContext | null = null;
+function getAudioContext(): AudioContext {
+  if (!audioContext) audioContext = new AudioContext();
+  return audioContext;
+}
+```
+
+### Resume Suspended Context
+```ts
+if (ctx.state === "suspended") ctx.resume();
+```
+
+### Clean Up Nodes
+```ts
+source.onended = () => { source.disconnect(); gain.disconnect(); };
+```
+
+---
+
+## Sound Design Patterns
+
+### Clicks/Taps (Percussion) — Use Filtered Noise
+```ts
+const buffer = ctx.createBuffer(1, ctx.sampleRate * 0.008, ctx.sampleRate);
+const data = buffer.getChannelData(0);
+for (let i = 0; i < data.length; i++) {
+  data[i] = (Math.random() * 2 - 1) * Math.exp(-i / 50);
+}
+
+const filter = ctx.createBiquadFilter();
+filter.type = "bandpass";
+filter.frequency.value = 4000;  // 3000-6000Hz range
+filter.Q.value = 3;             // 2-5 for focused but not harsh
+source.connect(filter).connect(gain).connect(ctx.destination);
+```
+
+### Confirmations/Pops (Tonal) — Use Oscillators
+```ts
+const osc = ctx.createOscillator();
+osc.frequency.setValueAtTime(400, t);
+osc.frequency.exponentialRampToValueAtTime(600, t + 0.04);
+```
+
+### Envelope
+
+Use exponential decay (not linear) for sound envelopes. **Why:** linear decay produces an audible click as the envelope hits zero — the abrupt stop creates a high-frequency artifact at the cutoff. Exponential decay mimics natural acoustic decay (room reverberation, string damping) — it reaches zero asymptotically, no click.
+
+```ts
+gain.gain.setValueAtTime(0.3, t);  // set initial value first
+gain.gain.exponentialRampToValueAtTime(0.001, t + 0.05);  // never target 0
+```
+
+---
+
+## Parameters
+
+| Parameter | Range | Notes |
+|-----------|-------|-------|
+| Click duration | 5-15ms | Quick and percussive |
+| Filter frequency | 3000-6000Hz | For click sounds |
+| Filter Q | 2-5 | Focused but not harsh |
+| Gain | ≤ 1.0 | Prevent clipping |
+| Default volume | 0.3 | Subtle, not loud |
+| "too harsh" | → lower filter frequency, reduce Q | |
+| "too muffled" | → higher filter frequency | |
+| "too long" | → shorter duration, faster decay | |
+| "cuts off" | → use exponential decay | |
+| "more mechanical" | → higher Q, faster decay | |
+| "softer" | → lower gain, triangle wave | |
+
+---
+
+## Weight Matching
+
+Sound weight should match action importance:
+- **Subtle click** for toggle switches
+- **Soft pop** for adding items
+- **Rich confirmation** for purchases/payments
+- **Brief alert** for errors
+
+Sound duration should match action duration:
+- **50ms** for clicks/taps
+- **100-200ms** for confirmations
+- **Longer** for uploads/completions
+
+---
+
+## Preloading
+
+```ts
+const sounds = {
+  success: new Audio("/sounds/success.mp3"),
+  error: new Audio("/sounds/error.mp3"),
+};
+Object.values(sounds).forEach(audio => audio.load());
+
+// Reset before replay for rapid triggering
+function play(sound: HTMLAudioElement) {
+  sound.currentTime = 0;
+  sound.play();
+}
+```
+
+---
+
+## Cross-Refs
+
+- `accessibility.md` — the full reduced-motion contract; `prefers-reduced-motion` as a sound-sensitivity proxy lives there.
+- `motion.md` — sound duration should match the duration of the action it accompanies, the same pairing rule as interaction timing.
+- `state-design.md` — sound cues for state transitions (error, success) must never be the only signal; pair with the visual state.

package/assets/skills/design/agemon-design/references/spec.md

@@ -0,0 +1,123 @@
+# Composition Spec
+
+Defines `.ui-craft/spec.md` — the durable "what" between brief (why) and build (how). Created by `/shape` Step 6, consumed by `/sddesign` and `/craft`. Sits beside `brief.md` in `.ui-craft/` and is committed to the repo.
+
+---
+
+## The Spec Format
+
+One file. Per-surface `## Surface: <name>` sections. Append-mostly — new surfaces add a new section; existing sections are only edited when a composition decision changes. No JSX, no component code — this is a design document, not implementation.
+
+Multiple surfaces coexist in a single file, just as a brief covers one project with multiple concerns in one place.
+
+---
+
+## Per-Surface Template
+
+Copy this block for each new surface. Fill every subsection — leave none empty or the acceptance bar is undefined.
+
+```markdown
+## Surface: <name>
+
+### Composition
+
+**Recipe:** `recipe-<type>.md` → <Variant name>
+**Why:** <one line citing the brief principle or constraint that drove this choice>
+
+### Layout skeleton
+
+Desktop
+┌──────────────────────────────────────────────┐
+│ [region]               [region]     [region] │
+├──────────────────────────────────────────────┤
+│  ┌────────────────┐   ┌───────────────────┐  │
+│  │ <content area> │   │ <content area>    │  │
+│  └────────────────┘   └───────────────────┘  │
+└──────────────────────────────────────────────┘
+
+Mobile
+┌──────────────────┐
+│ [region]   [☰]   │
+├──────────────────┤
+│  <content area>  │
+└──────────────────┘
+
+### Component inventory
+
+| Region | Component | Contract ref |
+|--------|-----------|--------------|
+| header | Nav bar | components.md → Nav bar |
+| hero | Headline + CTA | components.md → Buttons |
+| … | … | … |
+
+### State lattice
+
+| State | Required / Optional / N-A | Notes |
+|-------|--------------------------|-------|
+| idle | Required | default, data present |
+| loading | Required | skeletons mirror final layout |
+| empty | Required | first-run or no data |
+| error | Required | cause + recovery action |
+| partial | Optional — only if widgets can fail independently | |
+| conflict | N-A | no collaborative editing on this surface |
+| offline | Optional — only if writes are queued | |
+| success | Required | confirmation after primary action |
+
+See [state-design.md](state-design.md) for state contracts and CRAFT_LEVEL thresholds.
+
+### Acceptance bar
+
+Drawn from the recipe's acceptance criteria. All items must be green before build reports done.
+
+- [ ] <recipe checklist item 1>
+- [ ] <recipe checklist item 2>
+- [ ] <recipe checklist item 3>
+```
+
+---
+
+## How the Spec Gets Used
+
+**Discovery phase** — read `.ui-craft/spec.md` after `brief.md`. If the surface already has a spec section, it is the composition ground truth; do not re-derive from scratch.
+
+**Build phase** — `/craft <surface>` builds against the acceptance bar in the surface's spec section. Every item in the acceptance bar must be green before the build reports done.
+
+**Finalize phase** — `/finalize` verifies against the acceptance bar and the brief's learned constraints (§6). The acceptance bar is the surface-level definition of done; the brief's §6 constraints are the project-level floor.
+
+---
+
+## When to Update
+
+Update a spec section when any of these change:
+
+- **Composition changes** — different recipe variant selected.
+- **New surface** — append a new `## Surface: <name>` section. Never overwrite an existing section.
+- **Recipe swap** — the recipe file changed and the acceptance bar items shift.
+- **Learned constraint overrides a composition choice** — note it in the Composition subsection, citing the brief §6 entry.
+
+Append-mostly. When deprecating a composition choice within a surface, mark the old entry as:
+
+```markdown
+~~**Recipe:** [recipe-landing.md](recipe-landing.md) → Product-forward~~ — deprecated 2026-06-24, swapped to Message-forward per brief §6 constraint (no hero visuals).
+```
+
+Never delete past composition records — the spec is a log, not a config file.
+
+---
+
+## File Location and Git
+
+Commit `.ui-craft/spec.md` to the repo. It belongs in version control alongside the code it governs — losing it between sessions means losing the composition rationale.
+
+The `.ui-craft/` directory is the project's design decision store:
+
+```
+.ui-craft/
+├── brief.md      # why — principles, user, success metric
+├── spec.md       # what — chosen composition, layout, inventory, acceptance bar
+└── (tokens live in the project's own token files)
+```
+
+`brief.md` and `spec.md` are companions: the brief anchors principles; the spec records how those principles translated into a specific surface composition. When they conflict, the brief wins — a spec choice that violates a brief §6 constraint must be updated to comply.
+
+See `../SKILL.md` for routing and when to run `/sddesign` vs `/craft`.