@w3kits-com/plugin-opendesign 0.1.8 → 0.1.9

package/dist/__w3kits/assets/design-systems/zapier/DESIGN.md

@@ -0,0 +1,331 @@
+# Design System Inspired by Zapier
+
+> Category: Productivity & SaaS
+> Automation platform. Warm orange, friendly illustration-driven.
+
+## 1. Visual Theme & Atmosphere
+
+Zapier's website radiates warm, approachable professionalism. It rejects the cold monochrome minimalism of developer tools in favor of a cream-tinted canvas (`#fffefb`) that feels like unbleached paper -- the digital equivalent of a well-organized notebook. The near-black (`#201515`) text has a faint reddish-brown warmth, creating an atmosphere more human than mechanical. This is automation designed to feel effortless, not technical.
+
+The typographic system is a deliberate interplay of two distinct personalities. **Degular Display** -- a geometric, wide-set display face -- handles hero-scale headlines at 56-80px with medium weight (500) and extraordinarily tight line-heights (0.90), creating headlines that compress vertically like stacked blocks. **Inter** serves as the workhorse for everything else, from section headings to body text and navigation, with fallbacks to Helvetica and Arial. **GT Alpina**, an elegant thin-weight serif with aggressive negative letter-spacing (-1.6px to -1.92px), makes occasional appearances for softer editorial moments. This three-font system gives Zapier the ability to shift register -- from bold and punchy (Degular) to clean and functional (Inter) to refined and literary (GT Alpina).
+
+The brand's signature orange (`#ff4f00`) is unmistakable -- a vivid, saturated red-orange that sits precisely between traffic-cone urgency and sunset warmth. It's used sparingly but decisively: primary CTA buttons, active state underlines, and accent borders. Against the warm cream background, this orange creates a color relationship that feels energetic without being aggressive.
+
+**Key Characteristics:**
+- Warm cream canvas (`#fffefb`) instead of pure white -- organic, paper-like warmth
+- Near-black with reddish undertone (`#201515`) -- text that breathes rather than dominates
+- Degular Display for hero headlines at 0.90 line-height -- compressed, impactful, modern
+- Inter as the universal UI font across all functional typography
+- GT Alpina for editorial accents -- thin-weight serif with extreme negative tracking
+- Zapier Orange (`#ff4f00`) as the single accent -- vivid, warm, sparingly applied
+- Warm neutral palette: borders (`#c5c0b1`), muted text (`#939084`), surface tints (`#eceae3`)
+- 8px base spacing system with generous padding on CTAs (20px 24px)
+- Border-forward design: `1px solid` borders in warm grays define structure over shadows
+
+## 2. Color Palette & Roles
+
+### Primary
+- **Zapier Black** (`#201515`): Primary text, headings, dark button backgrounds. A warm near-black with reddish undertones -- never cold.
+- **Cream White** (`#fffefb`): Page background, card surfaces, light button fills. Not pure white; the yellowish warmth is intentional.
+- **Off-White** (`#fffdf9`): Secondary background surface, subtle alternate tint. Nearly indistinguishable from cream white but creates depth.
+
+### Brand Accent
+- **Zapier Orange** (`#ff4f00`): Primary CTA buttons, active underline indicators, accent borders. The signature color -- vivid and warm.
+
+### Neutral Scale
+- **Dark Charcoal** (`#36342e`): Secondary text, footer text, border color for strong dividers. A warm dark gray-brown with 70% opacity variant.
+- **Warm Gray** (`#939084`): Tertiary text, muted labels, timestamp-style content. Mid-range with greenish-warm undertone.
+- **Sand** (`#c5c0b1`): Primary border color, hover state backgrounds, divider lines. The backbone of Zapier's structural elements.
+- **Light Sand** (`#eceae3`): Secondary button backgrounds, light borders, subtle card surfaces.
+- **Mid Warm** (`#b5b2aa`): Alternate border tone, used on specific span elements.
+
+### Interactive
+- **Orange CTA** (`#ff4f00`): Primary action buttons and active tab underlines.
+- **Dark CTA** (`#201515`): Secondary dark buttons with sand hover state.
+- **Light CTA** (`#eceae3`): Tertiary/ghost buttons with sand hover.
+- **Link Default** (`#201515`): Standard link color, matching body text.
+- **Hover Underline**: Links remove `text-decoration: underline` on hover (inverse pattern).
+
+### Overlay & Surface
+- **Semi-transparent Dark** (`rgba(45, 45, 46, 0.5)`): Overlay button variant, backdrop-like elements.
+- **Pill Surface** (`#fffefb`): White pill buttons with sand borders.
+
+### Shadows & Depth
+- **Inset Underline** (`rgb(255, 79, 0) 0px -4px 0px 0px inset`): Active tab indicator -- orange underline using inset box-shadow.
+- **Hover Underline** (`rgb(197, 192, 177) 0px -4px 0px 0px inset`): Inactive tab hover -- sand-colored underline.
+
+## 3. Typography Rules
+
+### Font Families
+- **Display**: `Degular Display` -- wide geometric display face for hero headlines
+- **Primary**: `Inter`, with fallbacks: `Helvetica, Arial`
+- **Editorial**: `GT Alpina` -- thin-weight serif for editorial moments
+- **System**: `Arial` -- fallback for form elements and system UI
+
+### Hierarchy
+
+| Role | Font | Size | Weight | Line Height | Letter Spacing | Notes |
+|------|------|------|--------|-------------|----------------|-------|
+| Display Hero XL | Degular Display | 80px (5.00rem) | 500 | 0.90 (tight) | normal | Maximum impact, compressed block |
+| Display Hero | Degular Display | 56px (3.50rem) | 500 | 0.90-1.10 (tight) | 0-1.12px | Primary hero headlines |
+| Display Hero SM | Degular Display | 40px (2.50rem) | 500 | 0.90 (tight) | normal | Smaller hero variant |
+| Display Button | Degular Display | 24px (1.50rem) | 600 | 1.00 (tight) | 1px | Large CTA button text |
+| Section Heading | Inter | 48px (3.00rem) | 500 | 1.04 (tight) | normal | Major section titles |
+| Editorial Heading | GT Alpina | 48px (3.00rem) | 250 | normal | -1.92px | Thin editorial headlines |
+| Editorial Sub | GT Alpina | 40px (2.50rem) | 300 | 1.08 (tight) | -1.6px | Editorial subheadings |
+| Sub-heading LG | Inter | 36px (2.25rem) | 500 | normal | -1px | Large sub-sections |
+| Sub-heading | Inter | 32px (2.00rem) | 400 | 1.25 (tight) | normal | Standard sub-sections |
+| Sub-heading MD | Inter | 28px (1.75rem) | 500 | normal | normal | Medium sub-headings |
+| Card Title | Inter | 24px (1.50rem) | 600 | normal | -0.48px | Card headings |
+| Body Large | Inter | 20px (1.25rem) | 400-500 | 1.00-1.20 (tight) | -0.2px | Feature descriptions |
+| Body Emphasis | Inter | 18px (1.13rem) | 600 | 1.00 (tight) | normal | Emphasized body text |
+| Body | Inter | 16px (1.00rem) | 400-500 | 1.20-1.25 | -0.16px | Standard reading text |
+| Body Semibold | Inter | 16px (1.00rem) | 600 | 1.16 (tight) | normal | Strong labels |
+| Button | Inter | 16px (1.00rem) | 600 | normal | normal | Standard buttons |
+| Button SM | Inter | 14px (0.88rem) | 600 | normal | normal | Small buttons |
+| Caption | Inter | 14px (0.88rem) | 500 | 1.25-1.43 | normal | Labels, metadata |
+| Caption Upper | Inter | 14px (0.88rem) | 600 | normal | 0.5px | Uppercase section labels |
+| Micro | Inter | 12px (0.75rem) | 600 | 0.90-1.33 | 0.5px | Tiny labels, often uppercase |
+| Micro SM | Inter | 13px (0.81rem) | 500 | 1.00-1.54 | normal | Small metadata text |
+
+### Principles
+- **Three-font system, clear roles**: Degular Display commands attention at hero scale only. Inter handles everything functional. GT Alpina adds editorial warmth sparingly.
+- **Compressed display**: Degular at 0.90 line-height creates vertically compressed headline blocks that feel modern and architectural.
+- **Weight as hierarchy signal**: Inter uses 400 (reading), 500 (navigation/emphasis), 600 (headings/CTAs). Degular uses 500 (display) and 600 (buttons).
+- **Uppercase for labels**: Section labels (like "01 / Colors") and small categorization use `text-transform: uppercase` with 0.5px letter-spacing.
+- **Negative tracking for elegance**: GT Alpina uses -1.6px to -1.92px letter-spacing for its thin-weight editorial headlines.
+
+## 4. Component Stylings
+
+### Buttons
+
+**Primary Orange**
+- Background: `#ff4f00`
+- Text: `#fffefb`
+- Padding: 8px 16px
+- Radius: 4px
+- Border: `1px solid #ff4f00`
+- Use: Primary CTA ("Start free with email", "Sign up free")
+
+**Primary Dark**
+- Background: `#201515`
+- Text: `#fffefb`
+- Padding: 20px 24px
+- Radius: 8px
+- Border: `1px solid #201515`
+- Hover: background shifts to `#c5c0b1`, text to `#201515`
+- Use: Large secondary CTA buttons
+
+**Light / Ghost**
+- Background: `#eceae3`
+- Text: `#36342e`
+- Padding: 20px 24px
+- Radius: 8px
+- Border: `1px solid #c5c0b1`
+- Hover: background shifts to `#c5c0b1`, text to `#201515`
+- Use: Tertiary actions, filter buttons
+
+**Pill Button**
+- Background: `#fffefb`
+- Text: `#36342e`
+- Padding: 0px 16px
+- Radius: 20px
+- Border: `1px solid #c5c0b1`
+- Use: Tag-like selections, filter pills
+
+**Overlay Semi-transparent**
+- Background: `rgba(45, 45, 46, 0.5)`
+- Text: `#fffefb`
+- Radius: 20px
+- Hover: background becomes fully opaque `#2d2d2e`
+- Use: Video play buttons, floating actions
+
+**Tab / Navigation (Inset Shadow)**
+- Background: transparent
+- Text: `#201515`
+- Padding: 12px 16px
+- Shadow: `rgb(255, 79, 0) 0px -4px 0px 0px inset` (active orange underline)
+- Hover shadow: `rgb(197, 192, 177) 0px -4px 0px 0px inset` (sand underline)
+- Use: Horizontal tab navigation
+
+### Cards & Containers
+- Background: `#fffefb`
+- Border: `1px solid #c5c0b1` (warm sand border)
+- Radius: 5px (standard), 8px (featured)
+- No shadow elevation by default -- borders define containment
+- Hover: subtle border color intensification
+
+### Inputs & Forms
+- Background: `#fffefb`
+- Text: `#201515`
+- Border: `1px solid #c5c0b1`
+- Radius: 5px
+- Focus: border color shifts to `#ff4f00` (orange)
+- Placeholder: `#939084`
+
+### Navigation
+- Clean horizontal nav on cream background
+- Zapier logotype left-aligned, 104x28px
+- Links: Inter 16px weight 500, `#201515` text
+- CTA: Orange button ("Start free with email")
+- Tab navigation uses inset box-shadow underline technique
+- Mobile: hamburger collapse
+
+### Image Treatment
+- Product screenshots with `1px solid #c5c0b1` border
+- Rounded corners: 5-8px
+- Dashboard/workflow screenshots prominent in feature sections
+- Light gradient backgrounds behind hero content
+
+### Distinctive Components
+
+**Workflow Integration Cards**
+- Display connected app icons in pairs
+- Arrow or connection indicator between apps
+- Sand border containment
+- Inter weight 500 for app names
+
+**Stat Counter**
+- Large display number using Inter 48px weight 500
+- Muted description below in `#36342e`
+- Used for social proof metrics
+
+**Social Proof Icons**
+- Circular icon buttons: 14px radius
+- Sand border: `1px solid #c5c0b1`
+- Used for social media follow links in footer
+
+## 5. Layout Principles
+
+### Spacing System
+- Base unit: 8px
+- Scale: 1px, 4px, 6px, 8px, 10px, 12px, 16px, 20px, 24px, 32px, 40px, 48px, 56px, 64px, 72px
+- CTA buttons use generous padding: 20px 24px for large, 8px 16px for standard
+- Section padding: 64px-80px vertical
+
+### Grid & Container
+- Max content width: approximately 1200px
+- Hero: centered single-column with large top padding
+- Feature sections: 2-3 column grids for integration cards
+- Full-width sand-bordered dividers between sections
+- Footer: multi-column dark background (`#201515`)
+
+### Whitespace Philosophy
+- **Warm breathing room**: Generous vertical spacing between sections (64px-80px), but content areas are relatively dense -- Zapier packs information efficiently within its cream canvas.
+- **Architectural compression**: Degular Display headlines at 0.90 line-height compress vertically, contrasting with the open spacing around them.
+- **Section rhythm**: Cream background throughout, with sections separated by sand-colored borders rather than background color changes.
+
+### Border Radius Scale
+- Tight (3px): Small inline spans
+- Standard (4px): Buttons (orange CTA), tags, small elements
+- Content (5px): Cards, links, general containers
+- Comfortable (8px): Featured cards, large buttons, tabs
+- Social (14px): Social icon buttons, pill-like elements
+- Pill (20px): Play buttons, large pill buttons, floating actions
+
+## 6. Depth & Elevation
+
+| Level | Treatment | Use |
+|-------|-----------|-----|
+| Flat (Level 0) | No shadow | Page background, text blocks |
+| Bordered (Level 1) | `1px solid #c5c0b1` | Standard cards, containers, inputs |
+| Strong Border (Level 1b) | `1px solid #36342e` | Dark dividers, emphasized sections |
+| Active Tab (Level 2) | `rgb(255, 79, 0) 0px -4px 0px 0px inset` | Active tab underline (orange) |
+| Hover Tab (Level 2b) | `rgb(197, 192, 177) 0px -4px 0px 0px inset` | Hover tab underline (sand) |
+| Focus (Accessibility) | `1px solid #ff4f00` outline | Focus ring on interactive elements |
+
+**Shadow Philosophy**: Zapier deliberately avoids traditional shadow-based elevation. Structure is defined almost entirely through borders -- warm sand (`#c5c0b1`) borders for standard containment, dark charcoal (`#36342e`) borders for emphasis. The only shadow-like technique is the inset box-shadow used for tab underlines, where a `0px -4px 0px 0px inset` shadow creates a bottom-bar indicator. This border-first approach keeps the design grounded and tangible rather than floating.
+
+### Decorative Depth
+- Orange inset underline on active tabs creates visual "weight" at the bottom of elements
+- Sand hover underlines provide preview states without layout shifts
+- No background gradients in main content -- the cream canvas is consistent
+- Footer uses full dark background (`#201515`) for contrast reversal
+
+## 7. Do's and Don'ts
+
+### Do
+- Use Degular Display exclusively for hero-scale headlines (40px+) with 0.90 line-height for compressed impact
+- Use Inter for all functional UI -- navigation, body text, buttons, labels
+- Apply warm cream (`#fffefb`) as the background, never pure white
+- Use `#201515` for text, never pure black -- the reddish warmth matters
+- Keep Zapier Orange (`#ff4f00`) reserved for primary CTAs and active state indicators
+- Use sand (`#c5c0b1`) borders as the primary structural element instead of shadows
+- Apply generous button padding (20px 24px) for large CTAs to match Zapier's spacious button style
+- Use inset box-shadow underlines for tab navigation rather than border-bottom
+- Apply uppercase with 0.5px letter-spacing for section labels and micro-categorization
+
+### Don't
+- Don't use Degular Display for body text or UI elements -- it's display-only
+- Don't use pure white (`#ffffff`) or pure black (`#000000`) -- Zapier's palette is warm-shifted
+- Don't apply box-shadow elevation to cards -- use borders instead
+- Don't scatter Zapier Orange across the UI -- it's reserved for CTAs and active states
+- Don't use tight padding on large CTA buttons -- Zapier's buttons are deliberately spacious
+- Don't ignore the warm neutral system -- borders should be `#c5c0b1`, not gray
+- Don't use GT Alpina for functional UI -- it's an editorial accent at thin weights only
+- Don't apply positive letter-spacing to GT Alpina -- it uses aggressive negative tracking (-1.6px to -1.92px)
+- Don't use rounded pill shapes (9999px) for primary buttons -- pills are for tags and social icons
+
+## 8. Responsive Behavior
+
+### Breakpoints
+| Name | Width | Key Changes |
+|------|-------|-------------|
+| Mobile Small | <450px | Tight single column, reduced hero text |
+| Mobile | 450-600px | Standard mobile, stacked layout |
+| Mobile Large | 600-640px | Slight horizontal breathing room |
+| Tablet Small | 640-680px | 2-column grids begin |
+| Tablet | 680-768px | Card grids expand |
+| Tablet Large | 768-991px | Full card grids, expanded padding |
+| Desktop Small | 991-1024px | Desktop layout initiates |
+| Desktop | 1024-1280px | Full layout, maximum content width |
+| Large Desktop | >1280px | Centered with generous margins |
+
+### Touch Targets
+- Large CTA buttons: 20px 24px padding (comfortable 60px+ height)
+- Standard buttons: 8px 16px padding
+- Navigation links: 16px weight 500 with adequate spacing
+- Social icons: 14px radius circular buttons
+- Tab items: 12px 16px padding
+
+### Collapsing Strategy
+- Hero: Degular 80px display scales to 40-56px on smaller screens
+- Navigation: horizontal links + CTA collapse to hamburger menu
+- Feature cards: 3-column grid to 2-column to single-column stacked
+- Integration workflow illustrations: maintain aspect ratio, may simplify
+- Footer: multi-column dark section collapses to stacked
+- Section spacing: 64-80px reduces to 40-48px on mobile
+
+### Image Behavior
+- Product screenshots maintain sand border treatment at all sizes
+- Integration app icons maintain fixed sizes within responsive containers
+- Hero illustrations scale proportionally
+- Full-width sections maintain edge-to-edge treatment
+
+## 9. Agent Prompt Guide
+
+### Quick Color Reference
+- Primary CTA: Zapier Orange (`#ff4f00`)
+- Background: Cream White (`#fffefb`)
+- Heading text: Zapier Black (`#201515`)
+- Body text: Dark Charcoal (`#36342e`)
+- Border: Sand (`#c5c0b1`)
+- Secondary surface: Light Sand (`#eceae3`)
+- Muted text: Warm Gray (`#939084`)
+
+### Example Component Prompts
+- "Create a hero section on cream background (`#fffefb`). Headline at 56px Degular Display weight 500, line-height 0.90, color `#201515`. Subtitle at 20px Inter weight 400, line-height 1.20, color `#36342e`. Orange CTA button (`#ff4f00`, 4px radius, 8px 16px padding, white text) and dark button (`#201515`, 8px radius, 20px 24px padding, white text)."
+- "Design a card: cream background (`#fffefb`), `1px solid #c5c0b1` border, 5px radius. Title at 24px Inter weight 600, letter-spacing -0.48px, `#201515`. Body at 16px weight 400, `#36342e`. No box-shadow."
+- "Build a tab navigation: transparent background. Inter 16px weight 500, `#201515` text. Active tab: `box-shadow: rgb(255, 79, 0) 0px -4px 0px 0px inset`. Hover: `box-shadow: rgb(197, 192, 177) 0px -4px 0px 0px inset`. Padding 12px 16px."
+- "Create navigation: cream sticky header (`#fffefb`). Inter 16px weight 500 for links, `#201515` text. Orange pill CTA 'Start free with email' right-aligned (`#ff4f00`, 4px radius, 8px 16px padding)."
+- "Design a footer with dark background (`#201515`). Text `#fffefb`. Links in `#c5c0b1` with hover to `#fffefb`. Multi-column layout. Social icons as 14px-radius circles with sand borders."
+
+### Iteration Guide
+1. Always use warm cream (`#fffefb`) background, never pure white -- the warmth defines Zapier
+2. Borders (`1px solid #c5c0b1`) are the structural backbone -- avoid shadow elevation
+3. Zapier Orange (`#ff4f00`) is the only accent color; everything else is warm neutrals
+4. Three fonts, strict roles: Degular Display (hero), Inter (UI), GT Alpina (editorial)
+5. Large CTA buttons need generous padding (20px 24px) -- Zapier buttons feel spacious
+6. Tab navigation uses inset box-shadow underlines, not border-bottom
+7. Text is always warm: `#201515` for dark, `#36342e` for body, `#939084` for muted
+8. Uppercase labels at 12-14px with 0.5px letter-spacing for section categorization

package/dist/__w3kits/assets/design-templates/AGENTS.md

@@ -0,0 +1,34 @@
+# design-templates
+
+This directory holds **design templates** — packaged "shapes" the agent
+renders into a project artifact (decks, prototypes, image/video/audio
+templates, …). Each entry is a folder with a `SKILL.md` (same shape as
+functional skills) plus rendering side files (`example.html`,
+`assets/`, `references/`, …).
+
+If the entry primarily *does work* on user input — utilities, briefs,
+asset packagers, fidelity audits — it belongs under `../skills/`
+instead. See `specs/current/skills-and-design-templates.md` for the
+full split.
+
+## Daemon plumbing
+
+- Listed under `/api/design-templates`. The shape mirrors `/api/skills`
+  (same `SkillSummary`/`SkillDetail` types) so the web client can
+  reuse a single `SkillSummary[]` consumer for both surfaces.
+- Asset and example routes (`/api/skills/:id/example`,
+  `/api/skills/:id/assets/*`) intentionally span both registries — the
+  example HTML rewrites to `/api/skills/<id>/...` regardless of which
+  root owns the folder, so URLs keep resolving after the split.
+- Surfaced in the EntryView Templates tab and in the New-project panel
+  as the rendering catalogue.
+
+## Adding a design template
+
+1. Create `design-templates/<my-template>/SKILL.md` with `name`,
+   `description`, `triggers`, and an explicit `od.mode` (one of
+   `prototype`, `deck`, `template`, `image`, `video`, `audio`).
+2. Ship a baked `example.html` (and any side files) so the EntryView
+   gallery has something to preview.
+3. Optionally drop additional baked samples under `examples/<key>.html`
+   to surface them as derived `<parent>:<key>` cards.

package/dist/__w3kits/assets/design-templates/audio-jingle/SKILL.md

@@ -0,0 +1,132 @@
+---
+name: audio-jingle
+description: |
+  Audio generation skill — jingles, beds, voiceover, and sound effects.
+  Routes music requests to Suno V5 / Udio / Lyria, speech to MiniMax
+  TTS / FishAudio / ElevenLabs V3, and SFX to ElevenLabs SFX or
+  AudioCraft. Output is one MP3/WAV file saved to the project folder.
+triggers:
+  - "music"
+  - "jingle"
+  - "bed"
+  - "voiceover"
+  - "tts"
+  - "sound effect"
+  - "音乐"
+  - "配音"
+  - "音效"
+od:
+  mode: audio
+  surface: audio
+  scenario: marketing
+  preview:
+    type: html
+    entry: example.html
+  design_system:
+    requires: false
+  example_prompt: |
+    A 30-second upbeat indie-pop jingle for a coffee shop launch — warm
+    electric piano lead, brushed drums, gentle bass, a single sun-soaked
+    "ahhh" choir on the chorus. No vocals. Loop-friendly tail.
+---
+
+# Audio Jingle Skill
+
+Three sub-modes. The active project's `audioKind` decides which one
+runs:
+
+| `audioKind` | Models we route to | Plan focus |
+|---|---|---|
+| `music` | Suno V5 (default), Udio, Lyria 2 | genre + tempo + instrumentation |
+| `speech` | MiniMax TTS (default), Fish, ElevenLabs V3 | script + voice + pacing |
+| `sfx` | ElevenLabs SFX (default), AudioCraft | texture + impact + duration |
+
+## Resource map
+
+```
+audio-jingle/
+├── SKILL.md
+└── example.html
+```
+
+## Workflow
+
+### Step 0 — Read the project metadata
+
+`audioKind`, `audioModel`, `audioDuration` (seconds), and (for speech)
+`voice`. Branch by `audioKind` and use the values verbatim — no
+clarifying form unless something is marked `(unknown — ask)`.
+
+Important: `voice` is provider-specific. For `minimax-tts`, `--voice`
+must be a valid MiniMax `voice_id` (for example `male-qn-qingse`), not
+a natural-language description. If you only have a prose voice brief
+("warm female narrator", "neutral Mandarin"), keep that in your plan
+but omit `--voice` so the daemon's default voice id applies, or ask the
+user to choose a specific id.
+
+### Step 1 — Plan
+
+**Music**
+- Genre + reference artists (1-2)
+- Tempo (BPM) + key
+- Instrumentation (3-5 instruments max)
+- Vocals: yes / no / hummed / choir
+- Mood arc (intro → chorus → outro)
+
+**Speech**
+- Script (final, not draft — TTS runs verbatim)
+- Voice target + pacing
+  For MiniMax this means a real `voice_id`, not prose in `--voice`
+- Pronunciation hints for proper nouns / acronyms
+
+**SFX**
+- Texture (impact / whoosh / ambience / foley)
+- Duration + envelope (sharp attack vs. gentle swell)
+- Layering note (single hit vs. stacked)
+
+State the plan in 2-3 sentences before dispatching.
+
+### Step 2 — Compose the prompt
+
+Use the format the upstream model prefers. Bind `audioDuration` to the
+API parameter directly; never put "make it 30 seconds" in prose.
+
+### Step 3 — Dispatch via the media contract
+
+Use the unified dispatcher — do **not** call provider APIs by hand:
+
+```bash
+"$OD_NODE_BIN" "$OD_BIN" media generate \
+  --project "$OD_PROJECT_ID" \
+  --surface audio \
+  --audio-kind "<music|speech|sfx>" \
+  --model "<audioModel from metadata>" \
+  --duration <audioDuration seconds> \
+  [--voice "<provider voice id (speech only)>"] \
+  --output "<short-slug>-<duration>s.mp3" \
+  --prompt "<assembled prompt from Step 2 — for speech, the literal script>"
+```
+
+The command prints one line of JSON: `{"file": {"name": "...", ...}}`.
+The bytes land in the project; the FileViewer renders the audio
+transport controls automatically.
+
+### Step 4 — Hand off
+
+Reply with: plan summary, the filename returned by the dispatcher, and
+one sentence on what to try if the user wants a variation (e.g. "swap
+tempo from 92 to 108 BPM" rather than "make it different").
+
+## Hard rules
+
+- TTS runs your script **literally**. Proof it before dispatching —
+  even one stray comma changes the cadence.
+- MiniMax TTS rejects free-form voice prose in `--voice`. Use a real
+  MiniMax `voice_id` (for example `male-qn-qingse`) or omit the flag
+  and let the daemon's default voice apply.
+- Music: under 30s = single section; 30–90s = intro + body; 90s+ =
+  full arc. Don't try to fit a 3-act song into 15 seconds.
+- SFX: prefer one well-described layer over a paragraph of "make it
+  cool" — generators reward specific texture words.
+- Save the file every turn. The audio viewer shows transport controls
+  the moment the file lands.

package/dist/__w3kits/assets/design-templates/audio-jingle/example.html

@@ -0,0 +1,128 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>Audio jingle — example</title>
+    <style>
+      :root {
+        --bg: #f5efe5;
+        --panel: #ffffff;
+        --ink: #1c1b1a;
+        --muted: #8b8579;
+        --accent: #c96442;
+        --grid: #e6dfd1;
+      }
+      * { box-sizing: border-box; }
+      html, body { margin: 0; padding: 0; background: var(--bg); color: var(--ink);
+        font-family: 'Iowan Old Style', 'Charter', Georgia, serif; }
+      body { min-height: 100dvh; display: grid; place-items: center; padding: 32px; }
+      .card {
+        width: min(640px, 92vw);
+        background: var(--panel);
+        border-radius: 8px;
+        padding: 26px 28px 22px;
+        box-shadow: 0 16px 40px rgba(28,27,26,0.10), 0 1px 2px rgba(28,27,26,0.05);
+        border: 1px solid rgba(28,27,26,0.06);
+      }
+      .row1 { display: flex; align-items: center; gap: 14px; margin-bottom: 18px; }
+      .icon {
+        width: 44px; height: 44px; border-radius: 50%;
+        background: var(--accent); color: #fff;
+        display: grid; place-items: center;
+        box-shadow: 0 6px 18px rgba(201, 100, 66, 0.35);
+      }
+      .icon svg { width: 22px; height: 22px; }
+      .title { margin: 0; font-size: 20px; line-height: 1.2; }
+      .sub { font-family: ui-monospace, 'SF Mono', Menlo, monospace;
+        font-size: 11px; color: var(--muted); letter-spacing: 0.14em; text-transform: uppercase; margin-top: 2px; }
+
+      .wave {
+        display: flex; align-items: end; gap: 3px;
+        height: 96px; padding: 0 4px;
+        border-top: 1px dashed var(--grid);
+        border-bottom: 1px dashed var(--grid);
+      }
+      .wave span {
+        flex: 1; background: linear-gradient(180deg, var(--accent), #a4502f);
+        border-radius: 2px;
+        animation: bob 2s ease-in-out infinite;
+        animation-delay: var(--d, 0s);
+      }
+      @keyframes bob {
+        0%, 100% { height: var(--h, 30%); }
+        50% { height: calc(var(--h, 30%) * 1.6); }
+      }
+
+      .transport {
+        margin-top: 14px;
+        display: grid; grid-template-columns: auto 1fr auto auto; gap: 12px;
+        align-items: center;
+      }
+      .play {
+        width: 36px; height: 36px; border-radius: 50%;
+        background: var(--ink); color: #fff;
+        display: grid; place-items: center;
+      }
+      .timeline {
+        height: 4px; border-radius: 2px;
+        background: linear-gradient(90deg, var(--accent) 0 32%, var(--grid) 32% 100%);
+      }
+      .time {
+        font-family: ui-monospace, 'SF Mono', Menlo, monospace;
+        font-size: 11px; color: var(--muted);
+        letter-spacing: 0.08em;
+      }
+      .badge {
+        font-family: ui-monospace, 'SF Mono', Menlo, monospace;
+        font-size: 10px; color: var(--accent);
+        letter-spacing: 0.18em; text-transform: uppercase;
+        padding: 4px 8px; border-radius: 999px;
+        background: rgba(201, 100, 66, 0.1);
+      }
+    </style>
+  </head>
+  <body>
+    <div class="card">
+      <div class="row1">
+        <div class="icon" aria-hidden>
+          <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M9 18V5l12-2v13"/><circle cx="6" cy="18" r="3"/><circle cx="18" cy="16" r="3"/></svg>
+        </div>
+        <div>
+          <h1 class="title">A 30s coffee-shop launch jingle.</h1>
+          <div class="sub">suno-v5 · 92 BPM · loop-friendly tail</div>
+        </div>
+      </div>
+      <div class="wave" aria-hidden>
+        <span style="--h:24%;--d:0s"></span>
+        <span style="--h:38%;--d:.05s"></span>
+        <span style="--h:52%;--d:.1s"></span>
+        <span style="--h:64%;--d:.15s"></span>
+        <span style="--h:48%;--d:.2s"></span>
+        <span style="--h:70%;--d:.25s"></span>
+        <span style="--h:42%;--d:.3s"></span>
+        <span style="--h:58%;--d:.35s"></span>
+        <span style="--h:36%;--d:.4s"></span>
+        <span style="--h:62%;--d:.45s"></span>
+        <span style="--h:26%;--d:.5s"></span>
+        <span style="--h:50%;--d:.55s"></span>
+        <span style="--h:34%;--d:.6s"></span>
+        <span style="--h:46%;--d:.65s"></span>
+        <span style="--h:58%;--d:.7s"></span>
+        <span style="--h:30%;--d:.75s"></span>
+        <span style="--h:44%;--d:.8s"></span>
+        <span style="--h:54%;--d:.85s"></span>
+        <span style="--h:28%;--d:.9s"></span>
+        <span style="--h:48%;--d:.95s"></span>
+      </div>
+      <div class="transport">
+        <div class="play" aria-hidden>
+          <svg viewBox="0 0 24 24" width="14" height="14" fill="currentColor"><path d="M6 4v16l14-8z"/></svg>
+        </div>
+        <div class="timeline" aria-hidden></div>
+        <span class="time">00:09 / 00:30</span>
+        <span class="badge">MP3</span>
+      </div>
+    </div>
+  </body>
+</html>