---
name: dictum-voice-ui-design
description: Design or review product-native Dictum speech-to-text interfaces using the public SDK states and events.
---

<!-- Generated from DICTUM_STT_EVENT_CONTRACT (fe3fb49b2593dbc7de4b6a7d8a0dfe5cd433447b370f782b5459b2dd19313473). Do not edit public/skill.md directly. -->

# Dictum Voice UI Design

Use this skill when building or reviewing Dictum voice interfaces for websites
and apps. Dictum should feel native inside the host product rather than looking
like a generic recorder.

## Workflow

1. Inspect the host product first: input shape, density, brand colors,
   interaction style, mobile constraints, and where speech should appear.
2. Design against the SDK's exact closed public contract:
   - States (7): `idle`, `requesting_mic`, `listening`, `paused`, `retrying`, `transcribing`, `failed`.
   - Events (17): `state_changed`, `volume_changed`, `transcript_delta`, `text_inserted`, `mic_denied`, `no_transcript`, `network_error`, `audio_invalid`, `compat_failed`, `limit_reached`, `fallback_started`, `quota_exceeded`, `auth_required`, `identity_expired`, `auth_invalid`, `retry_started`, `sdk_error`.
   - `text_inserted` is an event after successful insertion, never a lifecycle
     state.
3. Keep the control visible but compact. Use a microphone, waveform, spinner,
   check, stop, pause, retry, or warning icon only when the state requires it.
4. Show progress where users need confidence:
   - `listening`: show live audio signal or an active capture affordance.
   - `transcribing`: show a spinner with concise status text.
   - `text_inserted`: place the transcript in the target or preview, not in a
     detached debug surface.
   - `failed`: provide short recovery copy and one clear next action based on
     the typed public error.
5. Preserve keyboard, touch, and pointer ergonomics. The voice control must be
   tappable on mobile and must not interfere with normal typing.
6. Match the host design tokens. Use Tailwind tokens or declared theme
   variables and isolate provider-specific colors inside provider-inspired
   mockups.

## 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 invent, rename, title-case, or space-separate SDK state or event names.
- Do not make state labels look clickable unless they are controls.
- Do not rely on color alone for state. Pair color with an icon, motion, text,
  or shape.
- Keep animations short and consistent with the host motion system. Animate
  transform and opacity when possible.
- For provider-inspired examples, reproduce the interaction pattern rather than
  presenting a misleading fake product integration.
- For marketing demos, show the transcript landing in the real target surface
  users understand.

## Output checklist

- Every public SDK state listed above has a deliberate UI path.
- Event handlers use the exact public names listed above.
- Successful insertion is handled through `text_inserted`, not an `inserted`
  state.
- The UI can recover from permission denied, no speech, empty audio, network
  error, authentication error, quota exceeded, and audio too long.
- Mobile and desktop layouts keep the control aligned with the input.
- The design avoids competitor claims and focuses on voice input integrated
  into sites or apps.
- The implementation uses no private Worker assumptions.