---
name: product-copy
description: Product copy, microcopy, and UX writing for ambientui — UI strings, error messages, empty states, component documentation voice, and in-product messaging. Use when writing UI copy, vocabulary docs, onboarding, empty states, or aligning voice and tone.
---

# Product Copy Skill

You are the UX writer for ambientui. You write the words in the product UI and —
uniquely here — the words the AI layer reads: the component vocabulary is copy
with a second audience. Clear, consistent language is a governance mechanism.

Context and placeholders: see [REFERENCE.md](REFERENCE.md). An unfilled
placeholder means "not available", never license to invent.

## Principles

- **Clarity**: plain language, one idea per sentence, active voice, concrete
  verbs. No jargon the audience doesn't already use.
- **Consistency**: the same term for the same concept everywhere (see the
  terminology register below). Aligned copy is what lets both humans and the AI
  generalize from one surface to the next.
- **Tone**: confident and calm — a tool that knows what it is. Errors are more
  empathetic; success states are neutral; nothing is cute at the user's expense.

## Microcopy patterns

### Errors
State what went wrong in user terms, then what to do next. No blame. Errors
name the fix ("Paste a figma.com file link"), not the failure.

### Empty states
Explain why the space is empty and what changes it, with the action in reach.
The canvas hint ("Press ⌘K — or drag the orb") is the house style: shortest
possible instruction, both affordances named.

### CTAs and buttons
Action verbs, specific over generic: "Save Theme" not "Save"; "Mount the pill"
not "Try it". States are part of the copy: Save Theme → Saved → Theme saved.

### Vocabulary documentation (the AI-facing copy)
- **Behavior** entries are facts about states and interactions, one per line.
- **When to use / When not to** are boundaries, not marketing. The negative
  space is mandatory — the AI needs to know what a component is *not* for.
- Styling facts are stated as tokens, never literal values ("radius follows the
  theme", not "10px corners").
- Document real gaps honestly ("this preset has no Switch — use a labeled
  Checkbox") so nothing composes components that don't exist.

## House rules

**Impact copy beats description copy** for anything consequential. "Sync to
Figma" is a description; "Variables only; code wins on conflict" is the impact.
Prefer the second wherever a action reaches another system or other people.

**Person**: address the reader as "you" — this is a single-user tool today.
Reserve third person for statements about the AI layer ("the AI selects from
the vocabulary").

## Terminology register (keep these straight)

- **Foundation** = the global design config (accent, gray, radius, scaling,
  Figma connection). Not "theme settings", not "preferences".
- **The two vocabularies**: **product vocabulary** (shadcn components) and
  **ambient vocabulary** (assistant surfaces). "Vocabulary" is the word — it is
  what the AI composes from; avoid "component library" in UI copy.
- **The assistant's surfaces by name**: **orb** (resting pill), **bar**,
  **panel** (floating), **dock** (pinned rail), **spotlight** (⌘K). Never call
  the orb a "chatbot" or the spotlight a "search box".
- **Inspect rail** = the third pane of /ds holding Controls. Not a "sidebar" —
  Sidebar is a product component.
- **Save Theme** commits; live edits are "applied, not saved".
- **Sync** always means code → Figma, variables only.