---
name: dictum-voice-ui-design
description: Design, implement, or review polished Dictum voice UI surfaces for product-native speech-to-text. Use when Codex needs to define component anatomy, visual hierarchy, responsive behavior, accessibility, motion, stateful microphone controls, transcription feedback, insertion affordances, or UX copy around the public Dictum SDK contract.
---

# Dictum Voice UI Design

Use this skill to design Dictum speech-to-text UI that feels native to the host product while staying compatible with the headless SDK contract.

## Workflow

1. Inspect the host product first: input shape, density, brand colors, interaction style, mobile constraints, and where speech should appear.
2. Treat Dictum as embedded product UI, not a generic recorder. The voice surface should look owned by the host app.
3. Choose the smallest composition that fits the host: trailing input action, composer toolbar action, or compact control group beside the editable target.
4. Design around explicit SDK states and events:
   - States: `idle`, `requesting_mic`, `listening`, `paused`, `retrying`, `transcribing`, `failed`.
   - Events: `state_changed`, `volume_changed`, `transcript_ready`, `text_inserted`, dedicated recovery/error events, and `sdk_error`.
5. Define the component anatomy, state matrix, control availability, status copy, focus behavior, responsive adaptation, and reduced-motion behavior before styling details.
6. Keep the control visible but compact. Use a microphone, waveform, spinner, check, stop, pause, retry, or warning icon only when the state requires it.
7. Show progress where users need confidence:
   - listening: live audio signal or active capture affordance.
   - transcribing: spinner plus concise status text.
   - `text_inserted`: transcript appears in the target, not in a detached debug surface.
   - `failed`: short recovery copy plus one clear next action derived from the public error payload.
8. Preserve keyboard, touch, and pointer ergonomics. The voice control must be tappable on mobile and must not steal normal typing behavior.
9. Match the host design tokens. Use existing tokens and components before introducing Dictum-specific values.

## References

- Read `references/voice-control-design-system.md` when producing visual specifications, implementing the control, reviewing responsive/accessibility behavior, or mapping every SDK state to UI.

## Design Rules

- Do not add SDK-owned overlays, floating panels, hidden debug cards, or generic audio-upload UI.
- Do not expose raw SDK internals, transport frames, provider names, or implementation details to end users.
- Do not expose session ids, attempt ids, or model/key selection; the public SDK intentionally hides them.
- Do not make state labels look clickable unless they actually are controls.
- Do not rely on color alone for state. Pair color with icon, motion, text, or shape.
- Keep the editable target visually dominant; the voice control is a compact action, not a competing centerpiece.
- Reuse the host's typography, radii, spacing, borders, shadows, and focus treatment. Add no standalone Dictum design system when one already exists.
- Keep animations short and consistent with the host motion system. Animate transform and opacity when possible.
- For provider-inspired examples, reproduce the interaction pattern, not a misleading fake product integration.
- For marketing demos, show the transcript landing in the real target surface users understand.

## Output Checklist

- The idle, requesting-microphone, listening, paused, retrying, transcribing, inserted, and failed paths are represented.
- The UI can recover from permission denial, compatibility failure, no speech, empty audio, network failure, identity failure, and quota rejection.
- `limit_reached` remains informational and flows directly into transcription; `fallback_started` may explain a delay without presenting it as user retry.
- Mobile and desktop layouts keep the control aligned with the input, not floating elsewhere.
- Keyboard focus, screen-reader status, touch targets, contrast, and reduced motion are specified.
- The design avoids competitor claims and focuses on voice input integrated into sites or apps.
- The implementation can be driven by public SDK states/events without private worker assumptions.