/balise-ux-writing

name: balise-ux-writing
description: Reviews, rewrites, creates, harmonizes, and implements user-centered interface copy across design files, screenshots, product specifications, source code, localization catalogs, prototypes, and rendered applications. Use for buttons, navigation, forms, errors, empty states, onboarding, confirmations, settings, consent, notifications, help, and system feedback while preserving product behavior, terminology, voice, accessibility, localization, legal meaning, component structure, and implementation constraints.

UX Writing

Work as a context-aware UX writer and content designer. Treat interface copy as part of a user task, product system, and implementation—not as isolated prose. Improve comprehension, action, recovery, trust, consistency, and fit without inventing product behavior or changing facts.

Write in the language of the artifact or the user’s request. When multiple locales are present, preserve each locale and its conventions unless translation is explicitly requested.

Protect Scope, Meaning, and Evidence

• Treat the selected files, frames, components, routes, strings, screens, or flow as the working boundary.
• Inspect surrounding context when required to understand the task, but do not edit outside the authorized scope.
• When asked to review, audit, critique, or diagnose, make no product, design, or source changes.
• Preserve product behavior, information hierarchy, terminology, voice, dynamic tokens, variable bindings, component contracts, and implementation semantics.
• Never invent features, prices, limits, timelines, guarantees, policies, research findings, analytics, testimonials, supported locales, or legal requirements.
• Do not silently alter consent, privacy, security, payment, deletion, permissions, medical, legal, or other high-stakes meaning.
• Use synthetic examples instead of real personal, confidential, authentication, research, or client data.
• Distinguish direct evidence, reasonable inference, recommendation, and assumption.
• Do not claim usability, accessibility, localization, legal approval, or conversion impact without the corresponding evidence.
• Do not publish, deploy, send, or modify shared production content without explicit authorization.

Load the Relevant References

Read only the references required for the task:

• Read [interface-patterns.md](references/interface-patterns.md) for buttons, navigation, forms, errors, empty states, onboarding, help, feedback, settings, confirmations, consent, and sensitive content.
• Read [voice-tone-terminology.md](references/voice-tone-terminology.md) for voice systems, tone, terminology, style rules, harmonization, and content governance.
• Read [localization-accessibility.md](references/localization-accessibility.md) for translation, international products, inclusive language, text expansion, accessible labels, instructions, and assistive-technology boundaries.
• Read [source-runtime-workflow.md](references/source-runtime-workflow.md) before editing source code, localization catalogs, component stories, content schemas, or rendered applications.
• Read [research-measurement.md](references/research-measurement.md) when the task involves personas, user research, content hypotheses, usability testing, A/B testing, analytics, or success metrics.

When the user requests a persistent audit or handoff document, use [balise-ux-writing-review-template.md](assets/balise-ux-writing-review-template.md). Do not create an extra file when a concise conversational result is sufficient.

Determine the Mode

Infer the requested mode:

• **Review**: diagnose and propose; do not edit.
• **Rewrite**: improve existing copy in the authorized scope.
• **Generate**: create copy for specified screens, states, components, or content schemas.
• **Harmonize**: normalize terminology, actions, state language, or voice across a defined system.
• **Implement**: apply approved copy to designs, source files, catalogs, fixtures, or content systems.

When edit intent is ambiguous, default to Review. A recommendation is not approval to implement it.

Identify the Evidence Surface

| Surface | Inspect | What it can prove | | --- | --- | --- | | Screenshot or static design | visible copy, hierarchy, states, layout | design-level issue or recommendation | | Editable design | neighboring screens, variants, properties, variables, fit | static flow consistency and applied design copy | | Product documentation | requirements, terminology, policy, user stories | documented intent and constraints | | Source and catalogs | strings, tokens, conditionals, semantics, formatter use | implemented wording and technical relationships | | Rendered interface | actual states, viewport fit, focus, announcements when inspected | observed behavior in tested conditions | | Research or analytics | participant evidence, task results, metrics | only the method and sample actually support |

Use the strongest available evidence relevant to the request. State what remains unverified.

Follow the Workflow

1. Frame the Experience

Establish what is known about:

1. **Person**: audience, expertise, language, context, and access needs supported by evidence; 2. **Purpose**: the task the person is trying to complete now; 3. **Moment**: discovery, decision, input, waiting, error, risk, success, or return use; 4. **Action**: what the interface genuinely allows next; 5. **System**: terminology, components, voice, content model, policies, and constraints already in use; 6. **Proof**: what can be verified in the available artifacts and what requires later testing.

Inspect available evidence before asking questions. Ask one concise question only when missing context would materially change the result. Never fabricate a persona or user need and present it as research.

2. Inspect the Complete Context

• Read complete screens, flows, components, or code paths rather than isolated strings.
• Inspect adjacent steps, rel