# OSHUN V1 Copy-Compression Rules

Status: Accepted v1.0  
Owner: OSHUN Design + Product + Engineering  
Last Updated: March 26, 2026  
Implements: `V1-UX-067`  
Related:

- `docs/releases/v1/design/readability-standards.md`
- `docs/releases/v1/scope/scan-first-content-hierarchy-rules.md`
- `docs/releases/v1/specs/tara-content-tone-standards.md`
- `docs/releases/v1/specs/veritas-content-tone-standards.md`
- `docs/releases/v1/specs/nisaba-content-tone-standards.md`
- `docs/releases/v1/design/ai-disclosure-copy-guidance.md`
- `docs/releases/v1/design/error-outage-and-fallback-copy-guidance.md`
- `docs/releases/v1/specs/studio-internationalization-and-localization-dependency-and-data-contract-map.md`
- `apps/oshun/mobile/src/i18n/strings.ts`
- `apps/oshun/web/src/i18n/config.ts`
- `apps/oshun/web/src/i18n/formatting.ts`
- `apps/oshun/web/src/components/LanguageSwitcher.tsx`
- `docs/releases/v1/specs/todos.md`

## 1. Purpose

This document defines the canonical rules for compressing UI copy in OSHUN V1 so
interface text stays:

- concise
- specific
- scannable
- localizable
- resilient under text expansion

The goal is not to make OSHUN sound clipped or robotic.

The goal is to remove waste so the remaining words still communicate clearly
after translation, reflow, dynamic type, and right-to-left layout.

## 2. Current Repo Signals, External Scan, And Gap

The current repo already establishes several strong constraints:

- `READABILITY_STANDARDS.md` already requires support for dynamic text scaling,
  no clipping, and `30-50%` localization expansion in labels and buttons.
- `OSHUN_V1_SCAN_FIRST_CONTENT_HIERARCHY_RULES.md` already sets concise label
  targets, rejects placeholder-only naming, and treats headings, actions, and
  helper text as different hierarchy jobs.
- Tara tone guidance already says headings should usually stay within `2-5`
  words and supporting copy should usually be one short sentence.
- Error and disclosure copy guidance already favors short titles, direct body
  text, and plain vocabulary over decorative or defensive writing.
- `apps/oshun/mobile/src/i18n/strings.ts` already centralizes a large portion of
  shell copy in one catalog instead of scattering strings across components.
- `apps/oshun/web/src/i18n/config.ts` already declares a multi-locale target set
  including `ar` for RTL handling.
- `apps/oshun/web/src/i18n/formatting.ts` already uses locale-aware date, time,
  number, currency, and list formatting rather than English-specific string
  assembly.
- the Studio localization contract already includes `ci_expansion`,
  `expansionViolationCount`, and RTL validation as first-class release signals.

External implementation guidance points in the same direction:

- Microsoft’s current localization writing guidance says easy-to-read content is
  easier to localize, recommends short simple sentences, lists instead of dense
  paragraphs, verbs in short labels when clarity requires them, and consistent
  terminology for each concept.
- Microsoft also explicitly warns against idioms, modifier stacks, sentence
  fragments that reduce clarity, and synonym drift for the same feature.
- USWDS guidance says interface copy should be clear, focused, concise, written
  in plain language, and biased toward short sentences and straightforward
  wording.
- Android and Apple both recommend pseudolocalization to test whether layouts
  can absorb longer strings before translation ships.
- Android’s localization tooling also distinguishes truly untranslatable strings
  such as product names or trademarks from ordinary UI copy.

Inference from those sources plus the repo state:

- OSHUN already knows it must support expansion and multiple locales.
- OSHUN does not yet have one explicit rule set telling teams how to compress
  source-English copy so those localization budgets remain viable across
  buttons, headings, helper text, notifications, and operator surfaces.

## 3. Canonical Thesis

Compress the wording, not the meaning.

OSHUN copy compression means:

- fewer words
- less drift
- less duplication
- stronger terms
- layouts that still work when translated

It does not mean:

- vague labels
- generic actions
- unexplained abbreviations
- removing the one word that carries the real consequence

The ideal compressed string is shorter because it is sharper, not because it is
missing the hard part.

## 4. Core Rules

### 4.1 One String, One Job

Each UI string should carry one primary job:

- orient
- label
- instruct
- confirm
- warn
- recover

If one string tries to explain the page, justify the policy, and tell the user
what to do next, it is too long.

### 4.2 Prefer Specific Words Over Extra Words

Good compression comes from stronger nouns and verbs.

Prefer:

- `Retry`
- `Queued actions pending`
- `Signoff notes`
- `Saved for later`

Over:

- `Try again now`
- `There are queued actions that are still pending`
- `Notes related to the signoff`
- `This item has been successfully saved for later review`

### 4.3 One Product Concept Gets One Term

Use the same word for the same concept across the product.

Examples:

- `Save` should not alternate casually with `Bookmark`, `Store`, and
  `Keep for later`.
- `Changes requested` should not alternate with `Needs edits` unless the
  workflow genuinely defines different states.
- `Synthetic voice` should not alternate with `AI voice actor` or
  `generated voice`.

Compression fails when synonym drift forces the user to re-learn the same
concept in different places.

### 4.4 Write For Translation, Not Just For Native English

Avoid:

- idioms
- slang
- puns
- culture-specific references
- metaphor-heavy action labels

Also avoid stacked modifier phrases such as:

- `high-priority runtime queue approval state`
- `rapid-release emergency policy override workflow`

Break the idea into a heading plus structured labels instead.

### 4.5 Break Dense Sentences Into Lists Or Paired Lines

If the English source needs multiple commas, `and`, `or`, or `but` to stay
grammatical, it probably needs structural compression instead of copy edits.

Preferred replacements:

- bullet list
- field group
- metadata row
- title plus short support line

### 4.6 Use Fragments Carefully

Fragments are acceptable for:

- tabs
- chips
- compact labels
- short state badges

Prefer full sentences when the copy explains:

- recovery
- consequence
- safety limitation
- blocking error

### 4.7 Compression Must Preserve Accessible Clarity

Do not compress visible or assistive copy so far that the control becomes
ambiguous.

Bad compression:

- `Do it`
- `Open`
- `Go`
- `More`

unless the surrounding object and screen structure already make the outcome
unmistakable.

## 5. Source-English Compression Budgets

These are review thresholds for source English, not universal hard caps.

If a string exceeds them, the author should justify the length or redesign the
layout.

### 5.1 Labels, Tabs, Chips, And Segmented Controls

Preferred target:

- `1-3` words
- usually one line at launch widths

Review closely when:

- the label exceeds `16` source characters
- the concept needs punctuation to make sense
- the label wraps before localization

### 5.2 Buttons And Primary Actions

Preferred target:

- `1-4` words
- one clear verb

Review closely when:

- the action exceeds `24` source characters
- the label contains more than one clause
- the label repeats context already visible in the heading

### 5.3 Field Labels

Preferred target:

- `1-5` words

Review closely when:

- the label is longer than the field value it describes
- helper text is carrying the true label meaning
- the label contains policy explanation instead of field naming

### 5.4 Titles And Headings

Preferred target:

- `2-6` words
- no more than `2` lines above the fold

Review closely when:

- the title exceeds roughly `55` source characters
- the title contains both orientation and explanation
- a subtitle is required just to decode the title

### 5.5 Helper Text, Empty-State Bodies, And Toast Bodies

Preferred target:

- one short sentence
- one idea only

Review closely when:

- the copy exceeds `2` clauses
- the message repeats the title
- a list would communicate the detail more efficiently

## 6. Localization Expansion Rules

### 6.1 Design For `30-50%` Expansion By Default

English source copy should usually consume no more than about `70%` of the
available width budget in compact controls.

If the English source already fills the full available line, the design or the
copy is not ready for translation.

### 6.2 Short English Strings Are Not Always Safe

One-word or two-word English strings can expand sharply in translation.

Do not assume:

- `Save`
- `Done`
- `Later`
- `Queued`

will remain equally short in every locale.

### 6.3 Pseudolocalization Is Mandatory For Risky Surfaces

Before signoff on new or revised UI copy, expansion-sensitive surfaces should be
checked with pseudolocalization or equivalent expansion testing, especially for:

- nav labels
- tab bars
- button groups
- form labels
- compact tables or queue rows
- sticky action bars

### 6.4 RTL And Reordering Must Stay Viable

Do not build copy patterns that assume English word order, left-to-right icon
placement, or sentence fragments assembled by concatenation.

Localized strings must be able to reorder naturally.

## 7. String Construction Rules

### 7.1 Do Not Concatenate UI Fragments Into English-Only Sentences

Avoid constructing messages like:

- `Saved ` + objectName + ` successfully`
- `You have ` + count + ` pending items`

Prefer full-message templates with variables so translators can reorder the
sentence naturally.

### 7.2 Keep Data Formatting Out Of Literal Copy

Dates, times, numbers, percentages, currencies, and lists should come from the
locale-aware formatting layer rather than custom English copy.

This preserves compression and translation quality at the same time.

### 7.3 Mark Only Truly Untranslatable Terms As Fixed

Product names, trademarks, canonical domain names, and approved technical terms
may remain untranslatable when necessary.

Do not freeze ordinary UI text in English just because the shorter English
string fits the layout better.

### 7.4 Provide Context For Ambiguous Short Strings

Short strings such as:

- `Save`
- `Review`
- `Archive`
- `Pending`

need translator context when the intended meaning is not obvious from the key
alone.

Compression without context creates translation drift.

## 8. Pattern-Specific Rules

### 8.1 Titles And Subtitles

The title should name the object or state.

The subtitle should add only what the title cannot.

Bad:

- title: `Manage your language preferences and notification settings`
- subtitle:
  `Use this page to update the language you want and how often you hear from us.`

Better:

- title: `Language and notifications`
- subtitle: `Choose your language and delivery preferences.`

### 8.2 Buttons And Action Labels

Prefer direct verbs:

- `Retry`
- `Sync now`
- `Save changes`
- `Request changes`

Avoid:

- `Proceed`
- `Take action`
- `Complete this step now`

unless the surrounding step container already resolves the ambiguity.

### 8.3 Helper Text

Helper text should explain:

- requirement
- format
- consequence
- limit

It should not restate the label in longer words.

### 8.4 Empty, Error, And Status States

Use the shortest structure that still answers:

1. what happened
2. what it means
3. what to do next

Default pattern:

- short title
- one-sentence body
- one dominant action

### 8.5 Dense Admin And Table Surfaces

On operator surfaces, compress by moving detail into structure:

- columns
- badges
- metadata clusters
- helper rows

Do not convert everything into sentence-form explanatory copy.

## 9. Explicit Anti-Patterns

These patterns are non-canonical for OSHUN V1:

- headings that read like campaign copy
- action labels that need the whole screen to make sense
- filler openings such as `Use this page to...`
- filler confirmations such as `Your request has been successfully...`
- duplicate title and body copy in toasts, alerts, and empty states
- string concatenation that fixes English word order
- unexplained abbreviations added only to save space
- compressing copy while leaving the layout over-constrained
- freezing ordinary strings as English-only to avoid localization reflow

## 10. Acceptance Criteria

OSHUN copy compression is correct only when all of these are true:

- the source string is shorter because it is more specific, not because it is
  less truthful
- the string still makes sense when read out of full-page context
- the layout preserves room for `30-50%` expansion
- pseudolocalization or equivalent expansion checks pass on compact surfaces
- terminology stays consistent across customer and operator surfaces
- formatted dates, times, numbers, and lists come from locale-aware utilities
- ambiguous short strings have sufficient implementation context for translators

## 11. Delivery Checklist For Coding Agents

When adding or revising OSHUN UI copy:

- shorten by removing duplication before removing meaning
- check whether a list, badge, or field group can replace a long sentence
- keep source English within the review thresholds above where feasible
- store strings in catalogs or stable message definitions rather than ad hoc
  concatenation
- use locale-aware formatting helpers for numbers, dates, times, currencies, and
  lists
- verify compact controls under expanded or pseudolocalized text before signoff
- leave translator notes or clearer keys when a short label could be ambiguous
