product-copy.md

Guards the words: microcopy, errors, empty states, terminology, and product voice.

The file that actually governs: .claude/skills/product-copy/SKILL.md — history on GitHub. This copy ships with the release the site is built from.

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. 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.