super-ux 0.29.0 → 0.30.0

package/plugins/super-ux/scripts/ux_doctor.py

@@ -166,6 +166,44 @@ def fix(ux: Path, d: dict) -> list[str]:
     return done
 
 
+def brand_contract_state(root: Path) -> list[str]:
+    """The brand pack's contract version, or why there is nothing to report.
+
+    Same blind spot as the chain's: a pack written to an old contract is
+    internally consistent, so `brand_lint.py` stays quiet about it. Only a
+    marker comparison notices, which is why the doctor reads it too.
+    """
+    brand = root / "docs" / "brand"
+    if not brand.is_dir():
+        return []
+    versions: dict[str, str] = {}
+    unmarked: list[str] = []
+    for path in sorted(brand.rglob("*.md")):
+        text = path.read_text(encoding="utf-8", errors="replace")
+        found = re.search(r"^Contract:\s*brand-contract\s*(v\d+)\s*$", text, re.M)
+        rel = path.relative_to(brand).as_posix()
+        if found:
+            versions[rel] = found.group(1)
+        else:
+            unmarked.append(rel)
+    out = []
+    distinct = set(versions.values())
+    if len(distinct) > 1:
+        out.append(
+            "docs/brand: mixed contract versions -- "
+            + ", ".join(f"{k} {v}" for k, v in sorted(versions.items()))
+        )
+    elif distinct and distinct != {"v1"}:
+        out.append(
+            f"docs/brand: written to brand-contract {distinct.pop()}, current is v1"
+        )
+    if unmarked:
+        out.append(
+            "docs/brand: no contract marker on " + ", ".join(unmarked[:4])
+        )
+    return out
+
+
 def main() -> int:
     args = [a for a in sys.argv[1:] if not a.startswith("--")]
     ux = find_ux_dir(args[0] if args else None)
@@ -188,6 +226,14 @@ def main() -> int:
         return 0
 
     problems = report(ux, d)
+
+    brand = brand_contract_state(ux.parent.parent)
+    if brand:
+        print("\nBrand pack:")
+        for line in brand:
+            print(f"  {line}")
+        problems = True
+
     if "--fix" in sys.argv:
         applied = fix(ux, d)
         print("\nApplied:" if applied else "\nNothing to apply automatically.")

package/templates/brand/README.md

@@ -0,0 +1,53 @@
+Contract: brand-contract v1
+
+# docs/brand/ — how this product speaks
+
+`docs/ux/` decides **what the product does**. This folder decides **how it
+speaks** — in the interface, on the landing page, in the store listing, in a
+post. One voice, many registers.
+
+Owned by the `brand-voice` skill. Written by `copywriting`. Checked by
+`python3 docs/brand/lint.py` and by `/ux-audit copy`.
+
+| File | Holds |
+|---|---|
+| `voice.md` | the identity: pack, five axes, narrative, invariants |
+| `terminology.md` | our words, banned words, entity and tier names |
+| `facts.md` | canonical numbers and proof — the only source of a figure |
+| `channels.md` | one record per surface: register, limits, bans |
+| `strings.md` | interface string registry → `file:line` → scenario |
+| `locales/<code>.md` | per-locale delta |
+
+## Sources
+
+**Fill this in before anything else.** The linter scans nothing outside these
+paths, and refuses to report a clean run over a surface it never read
+(`B006`). Delete the keys this project does not have — a declared-but-absent
+source is worse than an omitted one.
+
+```
+Sources:
+  ui:        src/**/*.{ts,tsx,js,jsx,vue,svelte}
+  marketing: content/**/*.{md,mdx}
+  store:     store/{ios,android}/*.md
+  robots:    public/robots.txt
+  locales:   src/locales/*.json
+```
+
+`ui` and `marketing` also classify findings — several checks apply to only
+one of the two.
+
+## The hard rule
+
+Any change to public-facing text updates this folder in the same change, and
+`python3 docs/brand/lint.py` exits clean before the work is called done.
+
+## Commands
+
+| Command | Does |
+|---|---|
+| `/brand` | status across every file, then one recommended action |
+| `/brand-init` | pick a voice pack and calibrate it to this product |
+| `/brand-update` | recalibrate after positioning or personas changed |
+| `/brand-lint` | run the linter |
+| `/copy` | write or edit copy for a named surface |

package/templates/brand/channels.md

@@ -0,0 +1,129 @@
+Contract: brand-contract v1
+
+# Channels
+
+One record per surface. `Register` is deltas against the five axes in
+`voice.md` — a register moves the axes, never the invariants.
+
+`Forbidden` always carries both halves, even when one is `none`. Platform
+physics and brand choice written on one line become indistinguishable within
+a quarter, and then nobody can tell which is safe to revisit when the
+platform changes.
+
+Delete the surfaces this product does not have. Do not rename one: the
+linter and the audit address surfaces by the names in the contract.
+
+---
+
+## Product surfaces
+
+### primary action
+
+```
+Register:   <humor -1>
+Format:     <verb phrase naming the outcome; one primary per screen>
+Limits:     <24 characters>
+Forbidden:  physics: none | brand: <"Submit", "OK", bare nouns>
+CTA:        <this surface is the CTA>
+Proof:      none
+Locales:    <coefficient applies to the character limit>
+```
+
+### error
+
+```
+Register:   humor -3, density +1, distance -1
+Format:     what happened, what was not affected, one next step
+Limits:     <…>
+Forbidden:  physics: none | brand: humor, "unexpected", blame, bare codes
+CTA:        the recovery action
+Proof:      none
+Locales:    <…>
+```
+
+### empty state
+
+```
+Register:   <unchanged>
+Format:     what belongs here, why it is worth it, the one starting action
+Limits:     <…>
+Forbidden:  physics: none | brand: apology, "Nothing here yet" alone
+CTA:        one
+Proof:      none
+Locales:    <…>
+```
+
+### paywall and upgrade
+
+```
+Register:   humor -3, distance +1
+Format:     what is sold, what it costs, what happens at term end, how to leave
+Limits:     <…>
+Forbidden:  physics: none | brand: humor, manufactured urgency, hidden terms
+CTA:        one primary, one way out
+Proof:      one sourced figure
+Locales:    <legal differences per locale>
+```
+
+### destructive confirm
+
+```
+Register:   humor -3
+Format:     object, consequence, reversibility; verb repeats the action
+Limits:     <…>
+Forbidden:  physics: none | brand: humor, "OK" as the confirming verb
+CTA:        the destructive verb
+Proof:      none
+Locales:    <…>
+```
+
+<add the remaining product surfaces this product has: loading,
+success/toast, onboarding, billing and receipts, settings and legal,
+transactional email and push, docs and help>
+
+---
+
+## Marketing surfaces
+
+### landing hero
+
+```
+Register:   confidence +1, density -1
+Format:     one headline, one subhead, one primary action
+Limits:     title 60, meta description 160
+Forbidden:  physics: none | brand: superlatives with no facts.md row
+CTA:        one, verb plus outcome
+Proof:      one number, sourced
+Locales:    <coefficient applies to both limits>
+```
+
+### X
+
+```
+Register:   density +1, distance -1
+Format:     one idea; threads 5-12 posts, each standing alone
+Limits:     280
+Forbidden:  physics: link in body suppresses reach; >2 hashtags penalised;
+            editing within 30 minutes resets distribution
+            | brand: <engagement bait, fake urgency>
+CTA:        <in the first reply, not the post>
+Proof:      <one figure, sourced>
+Locales:    <…>
+```
+
+### Reddit
+
+```
+Register:   distance -2, humor +1
+Format:     a statement, not a headline; the comments are the content
+Limits:     <per subreddit>
+Forbidden:  physics: <subreddit rules outrank everything here>
+            | brand: undisclosed affiliation, CTA of any kind
+CTA:        none
+Proof:      <first-hand only>
+Locales:    <…>
+```
+
+<add the remaining marketing surfaces this product uses: landing body,
+pricing, blog, changelog, LinkedIn, HN and Product Hunt, App Store,
+Google Play, ads, lifecycle email>

package/templates/brand/facts.md

@@ -0,0 +1,36 @@
+Contract: brand-contract v1
+
+# Facts
+
+**The only source of any figure in public copy.** A number on a public
+surface with no row here is `B030` and blocks. A row with no `Source`, or one
+past its `Review by`, is `B031` and warns.
+
+A missing fact is reported, never invented to close a gap.
+
+| Fact | Value | Source | Checked | Review by | Public |
+|---|---|---|---|---|---|
+| <what the number counts> | <448> | <api/catalog.json> | <2026-08-05> | <2026-11-05> | <yes> |
+| <internal figure> | <$3.10> | <billing export> | <2026-08-05> | <2026-11-05> | <no> |
+
+`Public: no` marks figures that exist and must never be quoted — internal
+margins, unreleased counts, anything under embargo. The linter treats
+quoting one as the same failure as quoting a number that does not exist.
+
+## Proof that is not a number
+
+Testimonials, awards, certifications and press. Same rules: attributed,
+dated, and re-checked.
+
+| Claim | Attribution | Source | Checked | Review by | Public |
+|---|---|---|---|---|---|
+| <…> | <name, role, company> | <where it was said> | <YYYY-MM-DD> | <YYYY-MM-DD> | <yes> |
+
+## Required disclaimers
+
+Text that must appear alongside specific claims — regulatory, contractual, or
+promised. Locale differences live in `locales/<code>.md`.
+
+| Claim it attaches to | Required text |
+|---|---|
+| <…> | <…> |

package/templates/brand/locale.md

@@ -0,0 +1,68 @@
+Contract: brand-contract v1
+Locale: <de>
+Primary: <no>
+Address form: <Sie>
+Length coefficient: <1.30>
+Humor: <-1 from base>
+Never translated: <product name, entity names, tier names>
+Keywords: <own research — see below>
+Reviewed by: <name of someone who reads this language daily, or `unreviewed`>
+
+# Locale delta
+
+Copy this file to `locales/<code>.md`, one per declared locale. The invariant
+half of the voice does not appear here — it is in `voice.md` and holds in
+every language. This file carries only what is decided again.
+
+## Address form
+
+<The single choice, applied everywhere. This decision changes how the brand
+is perceived more than any word choice, so it is made once and recorded, not
+per string.>
+
+## Dead idioms
+
+Idiom and wordplay from the primary locale that does not survive. The
+replacement does the same **job**; it is not a translation of the joke.
+
+| Primary | Replacement | Job it does |
+|---|---|---|
+| <"ship it"> | <"raus damit"> | <permission to stop polishing> |
+
+## Keywords
+
+Researched in this market, never translated from the primary. The
+translation of a high-volume English term is routinely a term with no volume,
+while the term people actually type is a different word.
+
+| Term | Volume | Where it is used |
+|---|---|---|
+| <…> | <…> | <…> |
+
+## Legal differences
+
+Required copy this locale has and others do not. Treated as required strings:
+a missing one is a defect even when parity is otherwise complete.
+
+| Requirement | Text or reference |
+|---|---|
+| <Impressum> | <…> |
+| <VAT-inclusive pricing> | <…> |
+
+## Length notes
+
+Surfaces where the coefficient bites hardest in this locale — usually
+buttons, tab labels, store title and subtitle. Recorded here so the
+constraint reaches the primary-locale original, where it can still be
+designed around.
+
+| Surface | Primary limit | Effective limit | Note |
+|---|---|---|---|
+| <App Store title> | <30> | <23> | <…> |
+
+## Parity
+
+Computed by the linter against `strings.md`; not maintained by hand. Below
+the threshold in `voice.md` it warns (`B071`) with the percentage. A partial
+locale that declares itself is a known state; one that does not is a surprise
+for a user who does not speak the fallback.

package/templates/brand/strings.md

@@ -0,0 +1,41 @@
+Contract: brand-contract v1
+
+# Interface strings
+
+A **decision registry**, not a message catalog. It holds no translations and
+does not replace i18n keys. It records which strings have been reconciled
+with the voice, which scenario each serves, and where each one lives.
+
+This is what makes "one action, two names" (`B020`) checkable at all. Without
+it, that defect is only findable by reading the entire interface — which is
+why it survives in every product that has not written one down.
+
+Populated by an inventory sweep at init, not by hand.
+
+| Key | Text (primary) | Location | Scenario | Status |
+|---|---|---|---|---|
+| <action.project.publish> | <Publish> | <src/ui/ProjectBar.tsx:47> | <SCN-014> | <agreed> |
+
+## Columns
+
+- **Key** — dot-separated, stable, names the action rather than the screen.
+  Two rows sharing a `Key` with different `Text` is `B020`.
+- **Text (primary)** — the string in the primary locale. Other locales live
+  in the project's own i18n files; parity is computed against this column.
+- **Location** — `file:line`. A location that no longer resolves is `B023`.
+- **Scenario** — the `SCN-NNN` this string serves. A string serving no
+  scenario is a question for `ux-scenarios`, not a copy problem.
+- **Status** — `agreed` · `proposed` · `drifted` · `orphan`.
+
+## Statuses
+
+| Status | Means |
+|---|---|
+| `agreed` | reconciled with the voice and approved |
+| `proposed` | written, not yet approved |
+| `drifted` | the code no longer matches this row (`B021`) |
+| `orphan` | in the registry, no longer in the code |
+
+A string found in code with no row here is `B022` — a warning, not an error,
+so adopting this registry on an existing product does not block from day one.
+It becomes an error only once someone agrees the row.

package/templates/brand/terminology.md

@@ -0,0 +1,45 @@
+Contract: brand-contract v1
+
+# Terminology
+
+The dictionary the linter reads. Column one of **Product terms** and
+**Banned** drives `B010` and `B011`; **Entity and tier names** drives `B012`.
+
+## Product terms — always
+
+Where the product has its own word, the generic one is a defect, not a
+synonym.
+
+| Our term | Never write | Applies to |
+|---|---|---|
+| <Run> | <Execution, Job> | <what the product performs> |
+
+## Entity and tier names — exact spelling
+
+One spelling, everywhere: interface, marketing, billing, support, docs.
+
+| Name | Wrong forms seen |
+|---|---|
+| <Pro> | <PRO, Pro plan, pro> |
+
+## Banned
+
+Seeded at init from weak verbs, hedging chains and the marker vocabulary in
+`ai-tells.md`. Calibration adds what is specific to this product.
+
+| Word or phrase | Why | Use instead |
+|---|---|---|
+| leverage | filler verb | use |
+| seamless | claims what it cannot show | name the step that disappeared |
+| utilize | longer word, same meaning | use |
+| robust | hides the number | the number |
+| <…> | <…> | <…> |
+
+## Glossary
+
+Terms this product uses in a specific sense. If a term is here, it is
+grounded before it is leaned on.
+
+| Term | Meaning |
+|---|---|
+| <…> | <…> |

package/templates/brand/voice.md

@@ -0,0 +1,58 @@
+Contract: brand-contract v1
+Voice pack: <pack id from voice-packs.md, or `custom`>
+Locales: <en (primary)>
+Locale parity threshold: 80%
+Derived-from: <PER-NN, JTBD-NN from docs/ux/foundation.md — or `inferred`>
+Status: draft
+Last calibrated: <YYYY-MM-DD>
+
+# Voice
+
+The pack was the starting position. This file is the truth.
+
+## Axes
+
+The five axes are fixed. A project sharpens the wording; it does not add or
+remove an axis, because `channels.md` expresses every register as a delta
+against exactly these five.
+
+| Axis | The product IS | The product IS NOT |
+|---|---|---|
+| Confidence | <…> | <…> |
+| Register | <…> | <…> |
+| Distance | <…> | <…> |
+| Humor | <…> | <…> |
+| Density | <…> | <…> |
+
+## Narrative
+
+```
+Hero:         <who the reader is, in the role this product meets them in>
+Enemy:        <the state of the world that costs them — not a competitor>
+Product role: <instrument | guide | weapon>
+Promise:      <one line, checkable against a row in facts.md>
+```
+
+## Invariant in every language
+
+What survives translation. Breaking one of these is a finding on any surface,
+in any locale.
+
+- <e.g. never hedges>
+- <e.g. never claims a number that is not in facts.md>
+
+## Reconsidered per locale
+
+Conventions rather than character. Each is decided again in
+`locales/<code>.md`.
+
+- address form
+- humor level
+- idiom and wordplay
+- <…>
+
+## Failure mode
+
+Copied from the pack, kept here so the audit can look for it by name.
+
+<the degenerate form this voice collapses into when overdone>

package/templates/claude-rule.md

@@ -29,3 +29,23 @@
 - Use `/ux` as the entry point; skills: `ux-foundation`, `ux-flows`
   (flows + Figma mockups), `ux-scenarios` for maintenance, `ux-audit` for
   evidence-backed verification. Full map: the plugin's system-map reference.
+
+## Brand voice — hard rule (super-ux)
+
+- `docs/brand/` is the source of truth for how the product speaks:
+  `voice.md` (axes, narrative, invariants), `terminology.md` (our words and
+  the banned ones), `facts.md` (the only source of any public figure),
+  `channels.md` (one record per surface), `strings.md` (the interface string
+  registry), `locales/<code>.md`.
+- Any change to public-facing text — an interface string, a landing page, a
+  post, a store listing, an ad, an email — updates `docs/brand/` in the SAME
+  change. A new string with no registry row is drift, not a detail.
+- **Never quote a number that has no row in `facts.md`,** and never invent a
+  fact, statistic, quote or expert to fill a gap. Report the gap instead.
+- **One action keeps one name** across button, confirmation, toast, history,
+  notification and accessible name. Search `strings.md` before naming one.
+- **No humor, exclamation marks or emoji** on error, destructive confirm,
+  billing or paywall surfaces — in any voice.
+- Run `python3 docs/brand/lint.py` after any text change and before calling
+  work done. It must exit clean; wire it into CI or pre-commit alongside the
+  UX linter so copy drift cannot merge.