Carol's voice — copy rewrite + sentence-case audit; CLAUDE.md Conventions entry #145

New issue

Closed

opened 2026-06-19 17:35:13 +00:00 by james · 0 comments

james commented

2026-06-19 17:35:13 +00:00

Owner

Existing UI strings read like dev docs ("Reference surface for the TanStack Query + Form + Table pattern (ADR-0012)"). The design's voice guide (../carol-design/design_system_readme.md → CONTENT FUNDAMENTALS) prescribes:

First person: Carol speaks as "I" and addresses the user as "you." "I read your resume — here's my take."
Sentence case everywhere — buttons, headers, nav, titles. Never Title Case in UI; never ALL CAPS except the mono eyebrow/label style.
Lead with the takeaway, then the detail. Short sentences. Numbered steps for advice.
Concrete numbers only when earned, never decorative stats.
No emoji. Warmth comes from words and the blue accent.

The current copy violates all four. This ticket is the rewrite + the convention to keep it from drifting back.

Scope

Audit pass across app/(app)/, app/login, app/register, app/account/* for:
- Case (must be sentence case; reject Title Case button text and headings).
- Voice (Carol speaks first-person where she addresses the user; system text stays neutral but never preachy).
- Emoji (none).
- Dev-doc references (every "Reference surface for the TanStack Query + Form + Table pattern (ADR-0012)"-shaped string gets rewritten in human copy).
Rewrite per the guide. Lead with the takeaway, drop hedges, replace dev-doc references with user-facing copy.
CLAUDE.md gains a new bullet under Conventions: link to the design guide as the canonical voice reference, with the four rules summarised inline.

Dependency note

If the i18n migration ticket lands first, this rewrite touches messages/en.json instead of JSX. If this lands first, the i18n ticket wraps the rewritten strings. Either order works; the PR description must call out which.

Acceptance criteria

A grep over (app) routes turns up no Title Case button text, no "click here", and no emoji.
Every dev-doc-style label is replaced with user-facing copy.
CLAUDE.md Conventions entry added, linking to the design guide and summarising the four rules.

Out of scope

Marketing copy (/, /offline) — separate pass when product copy lands.
Internal-only surfaces (docs/ci.md, ADRs, API error JSON) — keep neutral / developer-doc voice there.

Composes with

Design package (../carol-design/design_system_readme.md), all four screen-rebuild tickets, the i18n migration ticket (either order).

Existing UI strings read like dev docs ("Reference surface for the TanStack Query + Form + Table pattern (ADR-0012)"). The design's voice guide (`../carol-design/design_system_readme.md` → *CONTENT FUNDAMENTALS*) prescribes: - **First person:** Carol speaks as "I" and addresses the user as "you." *"I read your resume — here's my take."* - **Sentence case everywhere** — buttons, headers, nav, titles. Never Title Case in UI; never ALL CAPS except the mono eyebrow/label style. - **Lead with the takeaway**, then the detail. Short sentences. Numbered steps for advice. - **Concrete numbers** only when earned, never decorative stats. - **No emoji.** Warmth comes from words and the blue accent. The current copy violates all four. This ticket is the rewrite + the convention to keep it from drifting back. ## Scope - **Audit pass** across `app/(app)/`, `app/login`, `app/register`, `app/account/*` for: - Case (must be sentence case; reject Title Case button text and headings). - Voice (Carol speaks first-person where she addresses the user; system text stays neutral but never preachy). - Emoji (none). - Dev-doc references (every "Reference surface for the TanStack Query + Form + Table pattern (ADR-0012)"-shaped string gets rewritten in human copy). - **Rewrite** per the guide. Lead with the takeaway, drop hedges, replace dev-doc references with user-facing copy. - **CLAUDE.md** gains a new bullet under *Conventions*: link to the design guide as the canonical voice reference, with the four rules summarised inline. ## Dependency note If the i18n migration ticket lands first, this rewrite touches `messages/en.json` instead of JSX. If this lands first, the i18n ticket wraps the rewritten strings. Either order works; the PR description must call out which. ## Acceptance criteria - [ ] A grep over `(app)` routes turns up no Title Case button text, no "click here", and no emoji. - [ ] Every dev-doc-style label is replaced with user-facing copy. - [ ] `CLAUDE.md` *Conventions* entry added, linking to the design guide and summarising the four rules. ## Out of scope - Marketing copy (`/`, `/offline`) — separate pass when product copy lands. - Internal-only surfaces (`docs/ci.md`, ADRs, API error JSON) — keep neutral / developer-doc voice there. ## Composes with Design package (`../carol-design/design_system_readme.md`), all four screen-rebuild tickets, the i18n migration ticket (either order).

james added the

area:pwa

label

2026-06-19 17:36:13 +00:00

james referenced this issue from a commit

2026-06-20 04:01:26 +00:00

docs(pwa): adopt Carol's voice in user-facing copy (#145)

james referenced this issue from a pull request that will close it,

2026-06-20 04:01:45 +00:00

docs(pwa): adopt Carol's voice in user-facing copy (#145) #173

james closed this issue

2026-06-20 04:08:35 +00:00