hayao 0.4.1 → 0.4.2

package/design/30-systems/unit-rosters.md

@@ -0,0 +1,123 @@
+---
+id: system-unit-rosters
+title: Unit Rosters — a legible roster
+kind: system
+tags: [units, roster, roles, tiers, diversity, rts, redundancy]
+summary: A roster of units whose roles are legible and distinct — every unit earns its slot, overlap is intentional, and redundancy is culled.
+use-when: You have a set of units/troops/pieces the player commands and need each to have a clear, non-redundant job.
+composes-with: [system-counter-systems, system-faction-asymmetry, system-enemy-archetypes, system-combat-model, system-tech-tree]
+anchors: [anchor-starcraft, anchor-age-of-empires]
+verify-with: docs/FUN.md#9-rts-lite
+---
+
+# Unit Rosters — a legible roster
+
+**What it is.** The **cast of pieces** the player fields — the units of an RTS, the
+troops of an auto-battler, the summons of a tactics game — organized so every one has
+a *readable job* and *earns its slot*. A roster is the vocabulary that
+[[system-counter-systems]] connects and [[system-faction-asymmetry]] differentiates.
+
+**Player fantasy / why it's fun.** "I know exactly what each of these does, and I'm
+choosing the right mix." A legible roster makes composition a pleasure — you read
+the enemy, pick your answer, and the units do what their silhouette promised.
+
+## When to use / when NOT
+
+| Use a designed roster when… | Skip when… |
+|---|---|
+| Player fields multiple unit types | One avatar / one active unit |
+| Composition is a decision | Units are just reskinned HP bars |
+| Counters/tech/factions need pieces | The "roster" is enemies only ([[system-enemy-archetypes]]) |
+
+## The role alphabet
+
+Most rosters are built from a small set of **functional roles**. Legibility comes
+from each unit reading as *one* role, not a blur of three.
+
+| Role | Job | Reads as |
+|---|---|---|
+| **Frontline / tank** | absorb, hold the line | big, slow, tough |
+| **DPS / line** | deal the damage | mid, fragile-ish |
+| **Skirmisher** | fast, harass, flank | small, quick, hits-and-runs |
+| **Artillery / siege** | range, area, anti-clump | long range, slow, glass |
+| **Support** | heal/buff/detect | non-combat, force-multiplier |
+| **Specialist** | one job (anti-air, cloak, transport) | the answer to a specific threat |
+
+A roster is *legible* when a new player can name each unit's role from its
+silhouette and speed alone — the [[pattern-readability]] test applied to the army.
+
+## Tiers vs. sidegrades
+
+| Structure | What it is | Watch for |
+|---|---|---|
+| **Tiers** | later units strictly stronger (T1→T3) | early units become dead weight — give them a lasting niche (cost, speed) |
+| **Sidegrades** | same tier, different role, no strict winner | the healthiest for diversity |
+| **Tech gates** | roster unlocks via [[system-tech-tree]] | pace the reveal; no unlock deserts (FUN.md §14 logic) |
+
+Prefer sidegrades within a tier and *role* differences across tiers. A pure linear
+tier ladder quietly kills half the roster.
+
+## Tuning levers
+
+| Lever | Does | Healthy range |
+|---|---|---|
+| **Roster size** | how many units | enough for a matrix, few enough to hold in the head (~6–12 per side) |
+| **Role coverage** | each role represented | no gap the counter-matrix needs filled |
+| **Overlap** | two units, similar job | intentional (a cheap and a premium tank) — not accidental |
+| **Cost curve** | resource/time per unit | maps to power; no unit both cheapest and best |
+| **Skill expression** | micro reward per unit | some reward control (skirmishers), some don't (tanks) |
+
+## Overlap vs. redundancy — the culling rule
+
+- **Overlap** is two units doing a similar job *for a reason*: a cheap disposable
+  tank and an expensive durable one give the player a real cost/quality choice.
+- **Redundancy** is two units doing the same job with no distinguishing decision —
+  one strictly dominates or they're interchangeable. **Cull it.** Every unit must
+  answer "when would I build *this* over its neighbor?" If it can't, merge or cut.
+
+The test: remove a unit. If no strategy got weaker, it was redundant.
+
+## How it wires to Hayao
+
+- **Roles are proven by duels.** Pure state + `world.rng` → clone the world, run the
+  unit in its intended matchup, read the result (FUN.md law 7). Assert the tank
+  *tanks* and the counter unit *counters* (FUN.md §9 NvN edges).
+- **Mass command needs flow fields** — one BFS per goal tile, cached outside
+  `world.state`, gives the whole roster wall-aware pathing (FUN.md §9). Grep
+  [`docs/API.md`](../../docs/API.md) for `astarGrid`/`floodFill` before citing.
+- **Export behavioural tolerances** (arrival radius, aggro range) as API so tests
+  share the sim's constants (FUN.md §9) — the roster's numbers live in one place.
+- **Redundancy is a lint.** The "remove-a-unit, did any strategy weaken?" check is a
+  skill-delta test (FUN.md law 2) you can script.
+
+## Fails when…
+
+- **Silhouette lies.** A "tank" that dies fast, a "skirmisher" that's slow — the read
+  breaks and composition becomes memorization ([[pattern-readability]]).
+- **Redundant units.** Dead slots the player never builds; the roster looks bigger
+  than it plays.
+- **A dominant unit.** One piece answers everything — the roster collapses to a spam
+  ([[system-build-diversity]] and [[system-counter-systems]] both die).
+- **Tier rot.** Early units strictly obsolete by mid-game, so half the cast is a
+  museum. Give each a lasting niche.
+
+## Verify
+
+- **[FUN.md §9](../../docs/FUN.md)** — every counter edge wins its NvN duel; commander
+  bot wins; walled units route around; ms/step at peak.
+- **[FUN.md law 2](../../docs/FUN.md)** — the redundancy lint: removing a unit weakens
+  some strategy; a mixed roster beats a mono spam.
+- Determinism: golden hash of a scripted battle across the roster.
+
+## Composes with
+
+- [[system-counter-systems]] — the matrix that connects the pieces into decisions.
+- [[system-faction-asymmetry]] — each faction is a distinct roster over shared roles.
+- [[system-enemy-archetypes]] — the enemy-side vocabulary; rosters and archetypes rhyme.
+- [[system-tech-tree]] — how the roster reveals over a match.
+
+## See also
+
+- [`docs/FUN.md`](../../docs/FUN.md) §9 — mass under command; duels as the balance test.
+- [[anchor-starcraft]], [[anchor-age-of-empires]] — legible rosters with role clarity.
+- [`sandboxes/pathfinding-demo`](../../sandboxes/pathfinding-demo) — the pathing the roster shares.

package/design/40-worldbuilding/README.md

@@ -0,0 +1,49 @@
+# 40-worldbuilding — theme, lore, faction, look
+
+The **SHAPE** stage's fiction half. Once the mechanic and the twist are set,
+these six kits give the design a *world* and a *look* — a setting that recolours
+the systems, the minimum viable lore that holds it together, factions that read
+at a glance, names in the house register, an art brief that survives the vision
+judge, and a way to tell the story with almost no text. Design here; **prove the
+look** in [`docs/JUDGE.md`](../../docs/JUDGE.md) and the `npm run palette` /
+`npm run feel` gates. The house aesthetic is **Kentō woodblock / Miyazaki-16** —
+elegant ink-and-washi craft, AA-verified — a consistent starting point, never a
+cage.
+
+The golden rule of the section: **the fiction must rhyme with the mechanic.** A
+theme, faction, or name that could be swapped out with zero mechanical change is
+a skin — bend deeper.
+
+| id | title | summary |
+|---|---|---|
+| [world-theme-vectors](theme-vectors.md) | Theme Vectors | Choosing a setting that *recolours* the systems, not skins them; theme as a twist vector — pick where fiction and mechanic rhyme. |
+| [world-worldbuilding-scaffold](worldbuilding-scaffold.md) | Worldbuilding Scaffold | From a setting to a coherent world — premise, rules, stakes, role, fantasy; the minimum viable lore a small game needs. |
+| [world-faction-identity](faction-identity.md) | Faction Identity | Making sides feel distinct in fiction — silhouette, values, colour, motif; the fiction companion to `system-faction-asymmetry`. |
+| [world-naming-and-tone](naming-and-tone.md) | Naming & Tone | Names, voice, register; the Kentō one-word restraint (lanternway, rootward, tarnholm, kintsugi) and text that trusts the player. |
+| [world-aesthetic-direction](aesthetic-direction.md) | Aesthetic Direction | Briefing the Kentō woodblock look — palette, contrast, depth, silhouette — to pass the readability + six-axis JUDGE bars. |
+| [world-narrative-delivery](narrative-delivery.md) | Narrative Delivery | Environmental / systemic / embedded storytelling with little text; show-don't-tell; let the systems author the story. |
+
+## The through-line
+
+```
+theme-vectors ─▶ worldbuilding-scaffold ─▶ naming-and-tone
+      │                    │                      │
+      └──▶ aesthetic-direction ◀── faction-identity
+                     │
+                     └──▶ narrative-delivery ──▶ (JUDGE / palette / feel)
+```
+
+Pick the theme, scaffold the world, name it, brief the look (splitting factions
+by hue and silhouette if there are sides), then let place and systems tell the
+story. Every arrow ends where the proof playbook begins.
+
+## See also
+
+- [`00-process/the-twist`](../00-process/the-twist.md) — theme is one of its six
+  vectors; this section is the deep dive on the fiction half.
+- [`30-systems/faction-asymmetry`](../30-systems/faction-asymmetry.md) — the
+  mechanical partner to `world-faction-identity`.
+- [`50-patterns/readability`](../50-patterns/readability.md) — the salience floor
+  every aesthetic brief must clear.
+- [`docs/JUDGE.md`](../../docs/JUDGE.md) · `docs/CONVENTIONS.md` (Kentō palette) —
+  where the look is proven.

package/design/40-worldbuilding/aesthetic-direction.md

@@ -0,0 +1,155 @@
+---
+id: world-aesthetic-direction
+title: Aesthetic Direction — briefing the Kentō woodblock look
+kind: worldbuilding
+tags: [art-direction, palette, kento, woodblock, readability, contrast, look, judge]
+summary: Art direction — the Kentō woodblock palette and how to brief a look that passes the readability + JUDGE bars (findable avatar, depth, one-world colour).
+use-when: You need to turn a theme into a concrete visual brief — palette, contrast, depth, silhouette — that survives the vision judge.
+composes-with: [world-theme-vectors, world-faction-identity, world-naming-and-tone]
+verify-with: docs/JUDGE.md
+---
+
+# Aesthetic Direction — briefing the Kentō woodblock look
+
+**What it is.** The **art brief**: the palette, contrast rules, depth plan, and
+silhouette language that give a game one coherent look. The house default is
+**Kentō woodblock / Miyazaki-16** — a small set of traditional-Japanese hues,
+AA-gated, that reads as elegant ink-and-washi craft. This module is how you brief
+a look that clears both the [[pattern-readability]] floor and the six-axis vision
+judge (`docs/JUDGE.md`), not just how to pick pretty colours.
+
+**Player fantasy / why it's fun.** The look is the *first* thing the player
+believes about the world — before a single mechanic fires. A frame that reads as
+*shipped, not debug* earns trust; a flat grey grid loses it in a second.
+
+## The Kentō palette
+
+Import `KENTO`, `MEADOW` (light), `DUSK` (dark) from `@hayao`
+([`docs/API.md`](../../docs/API.md)). It fuses the site's washi/sumi ink tokens
+with landscape hues loosely from Miyazaki-16. **Eight named accents**, each with
+a `Deep` tone for light grounds and a bright tone for dark:
+
+| Hue | Name | Reads as |
+|---|---|---|
+| vermilion | **shu** | alarm, aggression, sacred |
+| persimmon | **kaki** | warmth, harvest, rust |
+| ochre-gold | **ko** | wealth, age, earth |
+| pine green | **matsu** | life, growth, calm |
+| teal-cyan | **asagi** | water, cool, clarity |
+| indigo | **ai** | night, order, depth |
+| wisteria violet | **fuji** | magic, dusk, mystery |
+| dusty rose | **saku** | tenderness, transience |
+
+Neutrals run from shell-white *gofun* → *washi* → *kinako* → *stone* → body-ink
+*sumiSoft* → *sumi* → deepest *kuro*/*yohaku*. Pick **5–6 hues plus a ground** per
+game; alpha/tone variants via `withAlpha`/`mix` are welcome. **Every pairing is
+WCAG-AA verified — `npm run palette` is the gate.** The engine stays
+palette-agnostic; Kentō is a consistent starting point, never a restriction
+(`docs/CONVENTIONS.md`).
+
+## Vectors / options — dialing the look to the theme
+
+The palette is fixed-ish; the *composition* is where you express theme:
+
+| Lever | Poles | Serves |
+|---|---|---|
+| **Ground** | light `MEADOW` (washi) ↔ dark `DUSK` (sumi/kuro) | daytime/cosy ↔ night/dread; sets the whole mood |
+| **Accent count** | 2 (austere) ↔ 6 (rich) | tension of a lean frame vs a busy world |
+| **Value range** | wide (ink→shell) ↔ narrow | drama & focal points ↔ flat/foggy atmosphere |
+| **Line weight** | heavy ink outline ↔ soft edge | woodblock boldness ↔ painterly softness |
+| **Light** | flat ambient ↔ `LightLayer`+`PointLight` pools | even scene ↔ carved-out focal depth |
+
+Warm accents (*shu*, *kaki*, *ko*) push a scene toward harvest/dread/desperation;
+cool accents (*asagi*, *ai*, *fuji*) toward night/order/calm. Let the theme's
+register from [[world-theme-vectors]] pick the corner.
+
+## Method
+
+1. **Choose the ground** (`MEADOW` vs `DUSK`) from the theme's tone. This decision
+   colours everything after it.
+2. **Pick 5–6 accents** by *meaning*, not prettiness — one alarm hue, one focal
+   hue for the avatar, the rest for world & factions
+   ([[world-faction-identity]]). Reserve the highest-contrast pairing for the
+   player so the avatar out-contrasts the scenery (JUDGE axis 1).
+3. **Plan depth in three layers** — background / midground / foreground — *before*
+   placing anything. Emptiness (objects floating in a void) is the JUDGE's most
+   common failure (axis 2). Grade a sky, pin a horizon, layer ridges.
+4. **Give interactables an ink edge.** Pickups/actors carry a dark outline
+   (`stroke: KENTO.sumi` on light, `KENTO.gofun` rim on dark) plus a glow/pulse —
+   contrast lives in the *edge*, not the fill (`docs/CONVENTIONS.md`).
+5. **Set the silhouette language** — the shape rules that make avatar, enemies,
+   and pickups readable as black shapes ([[pattern-readability]]).
+6. **If lit, own the light.** A real `LightLayer` + `PointLight` carves a focal
+   point out of ambient dark; but multiply-lighting lowers contrast, so the
+   Kentō AA guarantee holds only *pre*-lighting — judge lit contrast from the
+   rendered PNG, and let the `lightingIssues` feel-gate (`npm run feel`) own it.
+7. **Render and judge.** Run `npm run judge <slug>`, *look* at the pixels, fix
+   every high-severity finding cosmetically (the golden hash must stay
+   unchanged), re-render until it reads shipped.
+
+## The JUDGE bar — brief to pass all six axes
+
+| Axis | The brief that passes it |
+|---|---|
+| **Readability** | Avatar on the reserved high-contrast pairing; threats warm-loud, pickups ink-edged |
+| **Depth & composition** | Three real layers; a focal point; breathing room — never a void |
+| **Palette harmony** | Every hue from the *one* Kentō set; a controlled value range, not all mid-tone |
+| **Juice restraint** | Particles/shake that *punctuate*; nothing seizure-bright ([[pattern-juice-choreography]]) |
+| **Motion clarity** | The eye tracks the important thing frame to frame |
+| **Chrome & finish** | HUD framed as DOM overlay; consistent margins; nothing clipped; the title invites |
+
+## Worked example — *lanternway*'s neighbourhood
+
+**Theme:** a keeper walking into the dusk (elegiac, small-scale).
+
+- **Ground:** `DUSK` — a graded night sky, pinned horizon, layered ridges (the
+  depth the JUDGE demands; the updrift lesson in `docs/JUDGE.md`).
+- **Accents:** *ko* (warm lantern glow, the focal/avatar hue) against *ai*/*fuji*
+  night; *shu* reserved for danger only. Five hues, one world.
+- **Light:** each lantern is a `PointLight` pool carving warmth out of the dark —
+  depth *and* the mechanic in one visual. Contrast judged from the PNG.
+- **Edges:** lanterns and the keeper carry a *gofun* rim so they read against the
+  dark ground.
+- **Result:** a frame that reads as an atmospheric ascent, not a debug void —
+  the exact gap the vision judge exists to close.
+
+## Aesthetic hook
+
+*This whole module is the aesthetic hook.* The one thing to internalise: **Kentō
+gives you harmony and AA for free, but not depth or contrast-under-light** — those
+you compose per scene and *prove from the rendered pixels*, never from the hexes
+(`docs/JUDGE.md` axis 2). Design in the palette; judge in the PNG.
+
+## Traps
+
+- **The debug void.** Objects on a flat grey field. Plan three layers first;
+  emptiness is the #1 judge failure.
+- **Palette clash.** Reaching outside the Kentō set for "one perfect blue."
+  Break the one-world rule and every frame muddies. Swap the *whole* palette or
+  stay in it.
+- **Contrast from hexes.** Trusting `npm run palette` AA under a `LightLayer` —
+  multiply kills it. Judge lit scenes from the PNG; let `lightingIssues` gate it.
+- **Fill without edge.** An accent shape flat on a same-family floor vanishes.
+  Ink outline + glow on anything interactive.
+- **Mid-tone mush.** All hues at one value = no focal point. Reserve the widest
+  value range for what matters most.
+- **Skipping the judge.** "Passes the gates" ≠ "looks shipped." Run
+  `npm run judge` and actually look.
+
+## Composes with
+
+- [[world-theme-vectors]] — supplies the register that picks the palette's corner.
+- [[world-faction-identity]] — each faction's owning hue is assigned from this
+  set; silhouette rules are briefed here.
+- [[pattern-readability]] — the salience floor this brief must clear.
+- [[pattern-juice-choreography]] — feedback that punctuates without smothering
+  (JUDGE axis 4).
+
+## See also
+
+- [`docs/JUDGE.md`](../../docs/JUDGE.md) — the six-axis rubric this module briefs
+  to; the `/judge` loop (`.claude/skills/judge/`).
+- `docs/CONVENTIONS.md` "Default palette is Kentō" — the palette, the ink-edge
+  rule, DOM chrome, and the `npm run palette` AA gate.
+- [`docs/API.md`](../../docs/API.md) — `KENTO`, `MEADOW`, `DUSK`, `withAlpha`,
+  `mix`, `LightLayer`, `PointLight`.

package/design/40-worldbuilding/faction-identity.md

@@ -0,0 +1,136 @@
+---
+id: world-faction-identity
+title: Faction Identity — making sides feel distinct in fiction
+kind: worldbuilding
+tags: [faction, identity, silhouette, motif, colour, values, fiction, asymmetry]
+summary: Making factions feel distinct in FICTION — silhouette, values, colour, motif; the fiction companion to system-faction-asymmetry's mechanical difference.
+use-when: Your design has two or more sides/factions and you need them to read as different worlds at a glance, not palette-swaps.
+composes-with: [world-aesthetic-direction, world-naming-and-tone, world-theme-vectors]
+anchors: [anchor-starcraft, anchor-shadow-of-mordor]
+verify-with: docs/JUDGE.md
+---
+
+# Faction Identity — making sides feel distinct in fiction
+
+**What it is.** [[system-faction-asymmetry]] makes factions play differently.
+This module makes them *feel* like different peoples. A faction reads when its
+**silhouette, values, colour, and motif** all say the same thing — so a player
+knows which side they're looking at from one frame, and knows what that side
+*believes* from one unit. Mechanical asymmetry without fictional identity is a
+stat-sheet; fictional identity without asymmetry is a costume.
+
+**Player fantasy / why it's fun.** Players don't main a faction for its numbers;
+they main it because it's *theirs*. Identity is what they're loyal to. A distinct
+faction is a distinct fantasy: the swarm, the disciplined line, the desperate
+salvagers.
+
+## The four identity channels
+
+Every faction needs a coherent answer on all four. When they agree, the faction
+is legible; when they clash, it's noise.
+
+| Channel | The question | Read at a glance? |
+|---|---|---|
+| **Silhouette** | Could you name the faction from a black shape? | Yes — shape is the fastest read |
+| **Values** | What does this people believe / fear / want? | Slower — read through behaviour & lore |
+| **Colour** | Which Kentō hue *owns* this faction? | Yes — one accent per side |
+| **Motif** | The repeated visual/verbal signature (a shape, a word, a ritual) | Yes — the thing that recurs |
+
+The strongest factions **map a value onto a mechanic onto a look** in one line:
+*the disciplined line* believes in order → fights in formation (mechanic) →
+straight silhouettes, indigo *ai* (look). Change any one and the other two feel
+wrong.
+
+## Vectors / options — where to source contrast
+
+Pick a *primary axis of difference* and let all four channels express it:
+
+| Contrast axis | Faction A pole | Faction B pole | Expresses through |
+|---|---|---|---|
+| **Order ↔ chaos** | rigid, geometric, few | teeming, organic, many | silhouette density; formation vs swarm |
+| **Growth ↔ decay** | living, verdant, *matsu* | rusted, salvaged, *kaki*/*ko* | material & motif |
+| **Sky ↔ earth** | tall, pale, airy | low, heavy, grounded | silhouette height; ground vs flight |
+| **Old ↔ new** | weathered, ritual, ink | sharp, forged, bright | tone & naming register |
+| **Predator ↔ prey** | angular, forward, few | rounded, defensive, many | shape language; posture |
+
+Two factions should sit at *opposite poles of the same axis* — that's what makes
+them read as a pair rather than two unrelated design docs. StarCraft's three sit
+on order↔chaos↔hybrid; each is a clean silhouette and a clean fantasy.
+
+## Method
+
+1. **Pick the contrast axis** that matches your mechanical asymmetry
+   ([[system-faction-asymmetry]]). If Faction A masses cheap units and B fields
+   few elites, your axis is *chaos ↔ order* — build fiction on that.
+2. **Write each faction's value in one sentence** — what they believe and fear.
+   This drives naming ([[world-naming-and-tone]]) and behaviour.
+3. **Assign one owning hue per faction** from the Kentō set. One accent each,
+   never shared — colour is the fastest faction read (see hook).
+4. **Design the silhouette rule.** A shape language each faction obeys:
+   straight-and-tall vs low-and-organic. Test it as black shapes — if you can't
+   tell them apart in silhouette, neither can the player mid-fight.
+5. **Choose the motif** — one recurring signature (a broken-lantern crest, a word
+   that only they use, a ritual gesture). It appears on units, HUD, and lore.
+6. **Cross-check the triangle.** Value ↔ mechanic ↔ look must agree for each
+   faction. A "peaceful" faction with the aggressive kit is a contradiction the
+   player feels but can't name.
+
+## Worked example
+
+**Axis:** growth ↔ decay, on a drowned-coast world.
+
+| | The Tidewardens | The Wracksalvage |
+|---|---|---|
+| **Value** | *keep the light; hold the line* | *take what the sea gives; owe nothing* |
+| **Silhouette** | tall, straight lanterns & robes | low, hunched, jury-rigged hulls |
+| **Colour** | indigo *ai* + shell *gofun* | persimmon *kaki* + rust *ko* |
+| **Motif** | the unbroken flame | the scavenged hook |
+| **Mechanic** | few, durable, defensive (holds ground) | many, cheap, opportunistic (swarms wrecks) |
+
+You can tell them apart as black shapes; you can tell them apart by a single
+hue; and each look *is* the mechanic. That's a legible pair.
+
+## Aesthetic hook
+
+Colour is the fastest faction read the JUDGE has an axis for (palette harmony).
+Give each faction **one owning accent** from Kentō's eight — indigo *ai* reads as
+disciplined and cool, persimmon *kaki* and rust *ko* as desperate and warm, pine
+*matsu* as living, vermilion *shu* as aggressive. Because all eight belong to one
+harmonised set (`npm run palette`, AA-gated), factions can be *distinct* without
+*clashing* — the whole frame stays one world, which is exactly the JUDGE's
+palette-harmony bar (`docs/JUDGE.md` axis 3). Keep silhouette contrast doing the
+heavy lifting so the sides read even where their pooled sprites share a lit
+scene — contrast lives in the *edge and shape*, not only the fill
+(`docs/CONVENTIONS.md`). Pair with [[world-aesthetic-direction]] to brief the
+look and [[pattern-readability]] to keep both sides salient in a crowd.
+
+## Traps
+
+- **Palette-swap factions.** Same silhouette, different hue. Players read them as
+  the same side in two colours. Silhouette first, colour second.
+- **Look that fights the mechanic.** A "gentle" faction with a hyper-aggressive
+  kit. The triangle (value ↔ mechanic ↔ look) must close.
+- **Shared accent.** Two factions on the same hue are indistinguishable at
+  distance. One owning accent each.
+- **Motif overload.** Five crests and three slogans dilute the one that matters.
+  One motif per faction, repeated.
+- **Fiction with no mechanical asymmetry.** If the sides play identically, the
+  identity is a costume — pair with [[system-faction-asymmetry]] or drop to one
+  faction.
+
+## Composes with
+
+- [[system-faction-asymmetry]] — the mechanical difference this module dresses;
+  they must be authored together.
+- [[world-aesthetic-direction]] — turns each faction's colour/silhouette rule
+  into a briefed, JUDGE-passing look.
+- [[world-naming-and-tone]] — faction names and the words only they use.
+- [[pattern-readability]] — keeps competing factions salient in a busy frame.
+
+## See also
+
+- [`docs/JUDGE.md`](../../docs/JUDGE.md) — readability & palette-harmony axes:
+  can you find and name each side instantly, in one world's colours?
+- [[anchor-starcraft]] — three rosters, one balance, three unmistakable
+  silhouettes. [[anchor-shadow-of-mordor]] — factions of *individuals* whose
+  identity is emergent memory.

package/design/40-worldbuilding/naming-and-tone.md

@@ -0,0 +1,130 @@
+---
+id: world-naming-and-tone
+title: Naming & Tone — the Kentō house restraint
+kind: worldbuilding
+tags: [naming, tone, voice, register, restraint, copy, evocative, ux-text]
+summary: Names, voice, and register — the Kentō house restraint of one-word evocative titles (lanternway, rootward, tarnholm, kintsugi) and text that trusts the player.
+use-when: You need to name the game, its places, factions, and mechanics — and set the voice for the little text a small game shows.
+composes-with: [world-worldbuilding-scaffold, world-faction-identity, world-narrative-delivery]
+verify-with: none
+---
+
+# Naming & Tone — the Kentō house restraint
+
+**What it is.** The **name** is the smallest, most-seen piece of worldbuilding —
+the title on the first screen, the word on every place and mechanic. **Tone** is
+the register of every string the game shows. The house style is *restraint*: one
+evocative word over a compound sentence, an implied world over an explained one,
+text that trusts the player to feel it. The examples name themselves in a breath
+— *lanternway*, *rootward*, *tarnholm*, *kintsugi* — and say almost nothing else.
+
+**Player fantasy / why it's fun.** A good name is a whole world compressed. Say
+*rootward* and the player already feels down, inward, growing. The name does the
+worldbuilding the text doesn't have to.
+
+## The house rule: one evocative word
+
+The Hayao lean is a **single coined or weathered word** that implies a direction
+or a place. It reads on a title screen, survives in a URL, and carries a mood
+without a subtitle.
+
+| Name | How it's built | What it implies at a glance |
+|---|---|---|
+| **lanternway** | lantern + way (a path) | a lit route through dark; keeping, walking |
+| **rootward** | root + -ward (toward) | descent, growth, inward, earth |
+| **tarnholm** | tarn (mountain lake) + holm (island) | a cold, small, isolated place |
+| **kintsugi** | the craft of gold-mending broken pottery | repair as beauty; breakage that heals |
+
+The technique: **fuse two small, concrete morphemes** (a thing + a direction, or
+a place + a place), or **borrow a real craft/place word** with the right weather
+on it. Avoid the fantasy-generator failure modes below.
+
+## Vectors / options — dialing the register
+
+Pick a register and hold it across *every* string, from the title to the
+game-over line:
+
+| Register | Feels like | Naming source | Fits themes |
+|---|---|---|---|
+| **Weathered / folk** | old, worn, quiet | real archaic words; place-suffixes (-holm, -mere, -fen) | stewardship, seasonal, elegiac |
+| **Coined-compound** | crafted, precise | two morphemes fused (root+ward) | most house games; clean & ownable |
+| **Craft-loan** | elegant, specific | a real craft term (kintsugi, kentō) | Japanese-craft register; on-brand |
+| **Mythic** | grand, absolute | invented proper nouns, capitalised | large-scale, conqueror-agency worlds |
+| **Plain / wry** | modern, light | ordinary words, a little dry | cosy, comedic, or tonal-twist games |
+
+The house default sits in the first three. Mythic and wry are available but pull
+*away* from the Kentō register — use them deliberately, matched to the theme.
+
+## Method
+
+1. **Name the game last, from the fantasy.** Once [[world-worldbuilding-scaffold]]
+   has the premise and role, the name is the compression of that feeling — not a
+   thing you pick first and rationalise.
+2. **Try the fuse.** Combine two concrete morphemes from the world (its material,
+   its direction, its place). Or borrow one weathered real word. Say it aloud.
+3. **Set one register** and write a *tone sheet* — 3–4 example strings (a title,
+   a prompt, a win line, a loss line) that fix the voice. Everything else matches.
+4. **Name places and factions in the same grammar.** If the game is *lanternway*,
+   its places are *the Duskmere*, *the Last Lamp* — not *Region 3*. Factions
+   inherit their value's register ([[world-faction-identity]]).
+5. **Name mechanics in-world where you can.** "Kindle," "mend," "ward" over
+   "activate," "repair," "buff." An in-fiction verb teaches and immerses at once.
+6. **Cut adjectives.** The house voice is nouns and verbs. If a string needs three
+   adjectives to land, the name or the scene isn't doing its job.
+
+## Worked example
+
+**World:** the drowned-coast keeper from [[world-worldbuilding-scaffold]].
+
+- **Title tries:** *saltway* (too plain), *The Last Keeper of Ys* (too much
+  subtitle), **lanternway** (fuse: lantern + way — a lit path; keeps the house
+  grammar). Ship the one-word fuse.
+- **Places:** *the Duskmere* (the drowning marsh), *the Far Lamp* (the last
+  lantern). Not "Level 5."
+- **Mechanics:** *kindle* (light), *ward* (hold the dark). In-world verbs.
+- **Tone sheet:** title *"lanternway."* · prompt *"the path ahead is dark."* ·
+  win *"the far lamp holds."* · loss *"the dark has the road."* Four strings,
+  one weathered voice, no adjectives to spare.
+
+## Aesthetic hook
+
+Tone is set by the **Kentō** register itself: the palette is *elegant Japanese
+craft* (the name *kentō* — 見当 — is the woodblock registration mark that aligns
+each colour pass), so the copy should share that restraint — spare, concrete,
+unhurried. Text is a **DOM overlay** in the house style, not `Text` nodes drawn
+into the scene (`docs/CONVENTIONS.md`), which frees the voice from HUD clutter:
+say less, and set it in the serif the JUDGE renders true (`docs/JUDGE.md` fonts).
+A title screen with one word in ink on washi *invites* (JUDGE chrome axis) far
+better than a paragraph of lore. Match the naming register to the palette
+register: weathered names for the woodblock look; save the neon-mythic voice for
+a deliberately swapped palette.
+
+## Traps
+
+- **Fantasy-generator soup.** *Zephyrvale of the Thornwilds*. Apostrophes,
+  double-vowels, and stacked proper nouns read as generated. One clean word beats
+  a compound epic.
+- **Subtitle crutch.** If the name needs *": A Tale of…"* to make sense, the name
+  isn't carrying its weight.
+- **Register drift.** A weathered title over jokey button text (or vice versa)
+  breaks the spell. One register, everywhere.
+- **UI-verb naming.** "Activate ability," "consume resource." Name it in-world or
+  the fiction leaks out through the buttons.
+- **Adjective pile-up.** The house voice trusts the noun. Three adjectives means
+  the scene isn't showing what the words are telling.
+
+## Composes with
+
+- [[world-worldbuilding-scaffold]] — the premise and role the name compresses.
+- [[world-faction-identity]] — faction names inherit the register and the value.
+- [[world-narrative-delivery]] — tone governs every string the world shows, and
+  restraint here is what lets the *systems* speak.
+
+## See also
+
+- [`docs/JUDGE.md`](../../docs/JUDGE.md) — chrome & finish: a spare, well-set
+  title *invites*; a wall of lore doesn't.
+- `docs/CONVENTIONS.md` — menus/titles/HUD are DOM overlays; Kentō is the house
+  palette and *kentō* the registration-mark namesake.
+- Example titles *lanternway*, *rootward*, *tarnholm*, *kintsugi* — the restraint
+  in one word (reference the *technique*, not the words themselves).