@origingame/engine 0.2.0 → 0.4.0

package/knowledge/skills/og-taste/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: og-taste
-description: Art direction for a game on Origin Engine — choosing a style from the premise (genre, mood, era, audience) out of a 37-style catalogue and binding it as a look (post stack, stylisation, material defaults, skin) with a UI skin, a palette and a type ramp; composition and hierarchy on the play surface, colour, typography, motion, feedback and consistency; atmosphere (fog, sky, time of day, weather, water); the anti-patterns that make a game look like a web form; and the checklist to run (with og run captures and dump_ui) before calling a game done. Use when starting a game's look, building or reviewing any screen or HUD, or when a game "works but looks generic".
+description: Art direction for a game on Origin Engine — choosing a style from the premise (genre, mood, era, audience) out of a 37-style catalogue and binding it as a look (post stack, stylisation, material defaults, the UI style) with a palette and a type ramp; composition and hierarchy on the play surface, colour, typography, motion, feedback and consistency; atmosphere (fog, sky, time of day, weather, water); the anti-patterns that make a game look like a web form; and the checklist to run (with og run captures and dump_ui) before calling a game done. Use when starting a game's look, building or reviewing any screen or HUD, or when a game "works but looks generic".
 ---
 
 A game is judged in its first second, before anyone reads a word. The
-engine's UI is correct by default and characterless by default: the platform
-tokens are grey glass that suits a settings page. This skill is how to give a
-game a look of its own and keep it consistent. The mechanics are og-ui's
-(skins, motion and sounds are og-ui §6) and the amounts of game feel
+engine's UI is correct by default and characterless by default: its
+placeholder style, `prototype`, is greys and square corners meant to be
+replaced, and the game's UI never borrows the Origin platform's look. This
+skill is how to give a game a look of its own and keep it consistent. The
+mechanics are og-ui's (styles, motion and sounds are og-ui §6) and the amounts of game feel
 og-feel's; this is the taste.
 
 ## What works
@@ -57,11 +58,16 @@ for a new game and writes the result (`--look <slug>` names it instead):
 `assets/looks/<game>.ogt` extending the preset, named by `GameDesc.look`,
 with a README section on changing it. For a game that exists, write the
 same file by hand (§12) and add `look: "looks/<game>.ogt"` to `og.game`.
-The entry also names the palette rules, the asset specs and the skin pack
-that matches it. Then pick **one** starting skin. The six packs in the engine's
-`templates/ui-kit/assets/skins/` are starting points, not the only looks:
-
-| Pack | Premises it fits | Signature | Start look (§12) |
+The entry also names the palette rules, the asset specs and the UI style
+its preset carries (the look's `ui` line, §12), so a game that extends a
+preset is dressed by it from the first frame. The game's UI follows the
+game's art, never the Origin platform's: without a style it draws in the
+engine's placeholder `prototype` (greys, near-square corners, a cyan focus
+ring), and `og polish` warns when a game ships in it. The six built-in
+styles in the engine's `templates/styles/` are starting points, not the
+only looks:
+
+| Style | Premises it fits | Signature | Start look (§12) |
 |---|---|---|---|
 | `pixel` | platformers, roguelikes, retro shooters, jam games | square frames, 2 px bevels, hard shadows, a bitmap face | `16bit-pixel` |
 | `cartoon` | casual, match-3, party, kids, idle | thick outlines, cream panels, squash on press, pops | `bold-comic-illustration` |
@@ -70,88 +76,90 @@ that matches it. Then pick **one** starting skin. The six packs in the engine's
 | `paper` | narrative, puzzle, cosy, mystery, word games | off-white sheets, ink outlines, soft shadows, one red | `pencil-hatching` |
 | `neon` | arcade, rhythm, racing, synthwave | dark glass, glowing tubes, italic display | `neon-vector` |
 
-```ts
-const skin = og.load.skin(world, "skins/fantasy/skin.ogt");
-if (skin.ok) og.ui.configure(world, { skin: skin.value });
+```text
+ui "fantasy"                     # in the game's look: a built-in style by slug
+ui "styles/harbour/style.ogt"    # or the game's own
 ```
 
-Make it the game's own by changing the skin file, never by passing colours
-to individual calls: copy the pack directory into the game's
-`assets/skins/<game>/` (`cp -R .../skins/fantasy assets/skins/<game>`) and
-load `skins/<game>/skin.ogt`. Nothing in it needs rewriting: the ids in a
-skin file are read relative to the file first (`atlas "atlas.png"`, `body
-"Newsreader-Medium.ttf"`), then from `assets/` (`skins/fantasy/atlas.png`
-still works). The one asset outside the pack is its CJK `fallback`,
-`fonts/NotoSansSC-Regular-subset.ttf` (2.5 MB, shared by every pack, so
-not copied six times): a project made by `npm create @origingame/game`
-has it at that id; otherwise point the line at the game's own CJK font,
-or delete it when the game shows no Chinese, Japanese or Korean (the cook
-names the line it cannot find). Then change `palette` (start with
-`accent`, `bg`, `surface`, `fg`), `ramp` and `fonts` (any OFL font beside
-the skin file), and redraw the atlas if the frames should change (`og skin
-pack`, og-ui §6). The art in the art direction of the
-world (sprites, backgrounds) and the skin must agree: a pixel-art world in a
+Make it the game's own by changing the style file, never by passing colours
+to individual calls: copy the built-in's directory into the game's
+`assets/styles/<game>/` (`cp -R .../templates/styles/fantasy
+assets/styles/<game>`) and name it in the look (`ui
+"styles/<game>/style.ogt"`). Nothing in it needs rewriting: the ids in a
+style file are read relative to the file first (`atlas "atlas.png"`, `body
+"Newsreader-Medium.ttf"`), then from `assets/`. A style is complete: it
+names every palette role and the four radii (`small`, `control`, `bar`,
+`panel`), so nothing of it comes from anywhere else. Then change `palette`
+(start with `primary`, `backdrop`, `panel`, `ink`), `radius`, `ramp` and
+`fonts` (any OFL font beside the style file), and redraw the atlas if the
+frames should change (`og style pack`, og-ui §6). A game that shows Chinese,
+Japanese or Korean adds a `fallback` font to its style (or its string
+table's `fonts` line, og-i18n). For a quick re-colour without a copy,
+`og.ui.configure(world, { primaryColor })` derives the primary's hover,
+pressed and soft tones and the ink on it. The art direction of the world
+(sprites, backgrounds) and the style must agree: a pixel-art world in a
 neon UI reads as two games.
 
 ## 2. Composition and hierarchy
 
 - **What the eye reads first**: decide the one thing per screen (the score on
   results, Play on the title, the health on a HUD) and make it the biggest,
-  the brightest or the only accent-coloured thing. If two things compete,
+  the brightest or the only thing in the primary colour. If two things compete,
   shrink one.
 - **The play surface is the hero**: a HUD sits in the corners and edges
   (anchors `topLeft`, `topRight`, `bottom`), never across the middle. Keep
   the centre third free during play.
-- **HUD weight**: at most three HUD groups visible at once; each is a capsule
-  with an icon and a number, not a panel with labels. Move rarely needed
+- **HUD weight**: at most three HUD groups visible at once; each is a HUD box
+  (`frame: "hud"`) with an icon and a number, not a panel with labels. Move rarely needed
   information behind pause.
 - **Safe area**: everything interactive inside `og.ui.frameViewport().safeArea`
   plus the density gutter; anchors do this for you, absolute positions do not.
 - **Phone vs desktop**: on `phonePortrait` the thumb zone is the bottom third:
   primary actions go there, touch controls at least 44 CSS px apart; titles
-  shrink one step (`displayMd` instead of `displayLg`). On desktop, menus sit
+  shrink one step (`xl2` instead of `xl3`). On desktop, menus sit
   centred or left, never full-width.
 - **Grouping**: spacing does the grouping. Related things are `space.sm`
   apart, groups `space.lg` or more. Do not draw a box around everything.
 
 ## 3. Colour
 
-- **Limited palette**: a ground (`bg`), one or two surfaces, one ink (`fg`)
-  with a muted ink, **one accent**, and the status colours. That is the whole
-  palette; a skin declares exactly these.
-- **One accent**, used for the one primary action per screen, earned stars,
-  the player's own row and focus. If everything is accent, nothing is.
+- **Limited palette**: a ground (`backdrop`), one or two surfaces (`panel`,
+  `panelRaised`), one ink (`ink`) with a muted ink (`inkMuted`), **one
+  primary**, and the status colours. That is the whole palette; a style
+  declares these and the roles derived from them.
+- **One primary**, used for the one primary action per screen, earned stars,
+  the player's own row and focus. If everything is primary, nothing is.
 - **Value before hue**: check the screen in greyscale. Text, the primary
   button and the player character must separate from their ground by value
   alone (body text at least 4.5:1; the packs' test enforces it for theirs:
   every label ink, every button label in every state, a text field's
-  placeholder, which draws in `fgSubtle` on the field's frame, and an
-  accent badge, `accentInk` on `accentSoft` over a panel (the results
+  placeholder, which draws in `inkFaint` on the field's frame, and a
+  primary badge, `highlight` on `primarySoft` over a panel (the results
   screen's "New best"), and a status badge in each of `success`, `warn`,
   `danger` and `info` (the tone's own ink on its 16 % tint), so a copied
-  pack whose `fgSubtle`, `fill`, `accentInk`, `accentSoft` or a status
+  style whose `inkFaint`, `control`, `highlight`, `primarySoft` or a status
   colour moves must keep those pairs at 4.5:1 too. The status colours are
   also the meters', toasts' and status dots' colours: on a cream panel they
-  are deep (the cartoon pack's warn is `#7b5102`, not a bright amber that
-  read 1.63:1), on a dark one light (a red under a dark pack's panel is a
+  are deep (the cartoon style's warn is `#7b5102`, not a bright amber that
+  read 1.63:1), on a dark one light (a red under a dark style's panel is a
   salmon such as `#ff8080`). Make them for the panels; a badge placed on
-  the other side of the scale (a light pack's badge straight on its dark
+  the other side of the scale (a light style's badge straight on its dark
   stage) moves its own ink towards white or black until it reads there,
   and the neutral badge does the same on its `fill`, so neither needs a
-  second palette. A game's copied skin is held to the same bars: the
+  second palette. A game's own style is held to the same bars: the
   engine's `pack_contrast.rs` measures the archetypes' and examples'
-  skins too, and their fixes were value, not hue (pathguard's lantern
+  styles too, and their fixes were value, not hue (pathguard's lantern
   orange deepened under a cream label, sparkorb's gold to a burnished
   amber under its cream ink, lampdive's plum fill darkened under its
   placeholder, Lantern Vale's status colours taken back to the fantasy
-  pack's deep ones);
+  style's deep ones);
   it also reads the primary and secondary labels from a rendered frame,
   where thin strokes may never reach their colour: a pixel font's one-pixel
-  strokes fall between pixels and took half their ink, so the pixel pack
+  strokes fall between pixels and took half their ink, so the pixel style
   thickens them with `textWeight body 0.5` and cooks DotGothic16 at
-  `px_range 8`; a copy of the pack made before that needs both lines).
+  `px_range 8`; a copy of the style made before that needs both lines).
 - Saturated colour on large areas tires the eye: keep saturation for small
-  things (the accent, icons, effects) and keep grounds calmer.
+  things (the primary, icons, effects) and keep grounds calmer.
 - Status colours mean status: never use `danger` red as decoration.
 
 ## 4. Typography
@@ -163,22 +171,22 @@ neon UI reads as two games.
 - **Numerals**: scores, timers, prices and stats in the numeric role
   (`font: "mono"`), so digits do not jitter as they count; big scores in the
   display face. Count them with `og.ui.counter`, never by setting text.
-- **A ramp, not sizes**: use the skin's steps (`displayLg`, `xl`, `body`,
+- **A ramp, not sizes**: use the style's steps (`xl3`, `xl`, `body`,
   `meta`); three or four steps per screen at most. Each step carries its
-  tracking (display sizes tighten, as the tokens do; a skin's `ramp` line
+  tracking (display sizes tighten; a style's `ramp` line
   takes it as its fourth number after the CJK leading), and it is applied
   to Latin text only.
-- Headings get `heading: true` so the skin's flourish frames them.
+- Headings get `heading: true` so the style's flourish frames them.
 
 ## 5. Motion
 
 - Every change of state moves; nothing pops in or out without a transition
   unless reduced motion is on.
-- **Durations 120 to 300 ms** for UI (the skin's `durations`), up to 700 ms
+- **Durations 120 to 300 ms** for UI (the style's `durations`), up to 700 ms
   for a screen transition, longer only for rewards. **Never linear**: ease
   out on arrival, ease in on exit.
 - **Anticipation and follow-through**: a press squashes before the action
-  (`press` in the skin), a reward overshoots and settles (`pop`, `motion.pop`).
+  (`press` in the style), a reward overshoots and settles (`pop`, `motion.pop`).
 - **Stagger**: a panel's controls arrive one after another (`motion.stagger`
   30–60 ms), not all at once.
 - **Screens change through a transition** (`og.ui.screenTransition`): fade
@@ -190,22 +198,22 @@ neon UI reads as two games.
 ## 6. Feedback
 
 Every input is answered **on the same tick** (og-feel §1) by a visual and a
-sound: hover (the skin's lift or highlight), press (squash, the `press`
+sound: hover (the style's lift or highlight), press (squash, the `press`
 sound), success (a toast, a burst, `success`), refusal (a disabled button
 shakes and plays `error` by itself; a wrong answer or a locked door shakes
 its element with `og.ui.shake` and the `error` sound; never silently ignore
 a press, and never shake the camera for it). Hand the UI its sounds with
 `og.ui.configure(world, { sounds: { hover, press, open, close, success, error } })`
-or the skin's `sound` lines. Results land with a count-up, stars with a
+or the style's `sound` lines. Results land with a count-up, stars with a
 `og.ui.burst`, rewards with a pop.
 
 ## 7. Consistency
 
-- **One skin per game.** Every screen, dialog and HUD uses it.
-- **One radius scale**: the skin's `radius`; never pass radii by hand.
-- **One shadow direction**: the skin's shadows all fall the same way (down);
+- **One style per game.** Every screen, dialog and HUD uses it.
+- **One radius scale**: the style's `radius`; never pass radii by hand.
+- **One shadow direction**: the style's shadows all fall the same way (down);
   in-world shadows should agree.
-- **One icon set**: the skin's `icons`; do not mix icon styles.
+- **One icon set**: the style's `icons`; do not mix icon styles.
 - **One transition kind** for screen changes, one entrance for dialogs.
 
 ## 8. Atmosphere
@@ -255,15 +263,16 @@ Each of these is a defect, not a style choice:
 - the HUD as a toolbar: a full-width bar of labelled boxes across the top;
 - labels instead of icons on the HUD ("Health: 72/100" instead of a heart
   and a bar);
-- every colour saturated, or every button in the accent;
+- every colour saturated, or every button in the primary colour;
 - a settings-page layout (left-aligned form rows) for a title screen.
 
 ## 10. The checklist before a game is done
 
 Run each item; each is checkable from a scripted run.
 
-1. **A skin is configured**: `og.ui.theme(world).skin` is not empty (log it
-   from a command, or read it in a playtest through a `facts` field).
+1. **A style is configured**: `og.ui.theme(world).style` is not empty and
+   not `prototype` (log it from a command, or read it in a playtest through
+   a `facts` field).
 2. **Title, pause and results screens captured**: `og run --headless --commands
    "0.5:show:title;1.5:screenshot:title.png;…"` (with the game's own commands);
    look at each capture in greyscale: the one thing per screen reads first.
@@ -277,7 +286,7 @@ Run each item; each is checkable from a scripted run.
    `og run --size 1170x2532`) and check in `dump_ui` that every control is at
    least 44 × 44 CSS px and nothing leaves the safe area.
 6. **Text legible**: body text at 13 px or more in `dump_ui` heights (a line
-   of at least 16 px); the skin passes 4.5:1 (the packs' test, or the same
+   of at least 16 px); the style passes 4.5:1 (the built-ins' test, or the same
    check over your atlas).
 7. **Motion present**: captures 100 ms apart after `show:` differ (an
    entrance), and a score `dump_ui` text read twice during the results
@@ -290,7 +299,7 @@ Run each item; each is checkable from a scripted run.
 10. **Reduced motion**: with `reducedMotion: true` the captures show fades
     only, and nothing is missing.
 11. **CJK**: switch the language to Chinese in settings and capture: no
-    missing-glyph boxes (the skin's fallback font covers it).
+    missing-glyph boxes (the style's or the string table's fallback font covers it).
 12. **None of section 9** is visible in any capture.
 13. **`og polish .` scores taste 90 or more** where it applies, and every
     finding left is one you read in the frames and can name a reason for
@@ -303,7 +312,7 @@ occupancy, screen transitions, UI sounds, locale keys) from the frames, the
 UI trees and the run's audio, with og-feel's measures beside it; og-build §5
 is the one list of its measures, thresholds and fixes. The numbers cannot
 judge a style: read the frames before changing anything, and fix the cause
-in the skin or the template, never per call.
+in the style or the template, never per call.
 
 ## 12. Style catalogue: looks
 
@@ -311,7 +320,7 @@ A style is chosen once per game and then held by data, not by habit: the
 **look** (`assets/looks/<game>.ogt`, an `.ogt` of `type look`) binds the
 frame's whole treatment (tone mapping and exposure, the post stack, the
 stylisation primitives, material defaults such as toon shading and
-outlines, fog and sky, the UI skin and the antialiasing) in one diffable
+outlines, fog and sky, the UI style and the antialiasing) in one diffable
 file. The engine ships the primitives and the presets; the taste is in
 which one you pick and how you tune it.
 
@@ -320,7 +329,7 @@ describes 37 styles in four families (pixel and retro, paint and line,
 shape and material, 3D rendering). For each: a one-line descriptor, three
 checks a critic can judge on a captured frame, the premises it fits
 (genre, mood, era, audience, as §1 asks them), the preset it maps to, the
-skin pack, palette constraints, asset specs (logical resolution, sprite
+UI style (`ui`), palette constraints, asset specs (logical resolution, sprite
 scale, face budget, outline width, texture density) and an art-bible
 direction. Match the premise's four answers against `premise`, shortlist
 two, and choose by the checks you can actually hold for the whole game.
@@ -344,7 +353,7 @@ version 1
 ---
 name "Harbour at dusk"
 extends "anime-cel-3d"          # the preset's slug (templates/looks/<slug>.ogt)
-skin "skins/harbour/skin.ogt"   # the game's own copy of the style's skin pack
+ui "styles/harbour/style.ogt"   # the game's own UI style (the preset names a built-in)
 RenderSettings {
   toneMapping agx
   exposure 1.1
@@ -455,8 +464,8 @@ middle ground.
 
 Name it in the game (`og.game({ look: "looks/harbour.ogt", … })`) and it
 is applied after the first scene spawns and before `start` runs (so
-`start` may still change any field, and reads the look's skin from
-`og.render.look(world)?.skin`); switch looks at a tick with
+`start` may still change any field, and reads the look's UI style from
+`og.render.look(world)?.style`); switch looks at a tick with
 `og.load.look` and `og.render.applyLook` (a flashback, a photo mode, an
 area's mood). A look's `MaterialStyle` reaches every lit material that
 leaves the field at its default; a material that must stay as made (a
@@ -492,7 +501,7 @@ in its style step (`docs/platform-asks.md` in the engine repository): the
 catalogue entry chosen from the premise, the look written, and the
 entry's three checks handed to the critic that reads the frames.
 
-| Slug | Family | Style | Support | Skin |
+| Slug | Family | Style | Support | UI |
 |---|---|---|---|---|
 | `expressionist-painting` | Paint and line | Expressionist paint | content | `paper` |
 | `bold-comic-illustration` | Paint and line | Bold comic illustration | full | `fantasy` |

package/knowledge/skills/og-ui/SKILL.md

@@ -1,11 +1,12 @@
 ---
 name: og-ui
-description: Game screens and HUDs on Origin Engine with og.ui — which screen template to pick (title, pause, settings, five HUDs, cutscene, shop, inventory, level select, results, leaderboard, tutorial, loading, dialogs, toasts), how to feed it data and read what it answers, the widget set beneath, focus for keyboard and gamepad, accessibility (the screen-reader mirror), phones, touch gestures and the safe area, text (fields, text areas, selection and the clipboard, input methods, ellipsis, kerning, shaping, font fallback), and the look: skins (style packs) and how their frames tile, count-ups, bursts, shakes, screen transitions and UI sounds. Use when building or changing menus, HUDs or any UI in a project with a project.ogt.
+description: Game screens and HUDs on Origin Engine with og.ui — which screen template to pick (title, pause, settings, five HUDs, cutscene, shop, inventory, level select, results, leaderboard, tutorial, loading, dialogs, toasts), how to feed it data and read what it answers, the widget set beneath, focus for keyboard and gamepad, accessibility (the screen-reader mirror), phones, touch gestures and the safe area, text (fields, text areas, selection and the clipboard, input methods, ellipsis, kerning, shaping, font fallback), and the look: UI styles (a look's `ui` line, the six built-ins, the game's own) and how their frames tile, count-ups, bursts, shakes, screen transitions and UI sounds. Use when building or changing menus, HUDs or any UI in a project with a project.ogt.
 ---
 
 `og.ui` is the engine's immediate-mode UI: a system describes the tree every
-tick, the engine lays it out, draws it in the platform's design tokens and
-answers the probe (`dump_ui`, `touch_move_to`, `move_to_text`). The API
+tick, the engine lays it out, draws it in the game's UI style (a look's
+`ui` line; the `prototype` placeholder without one, never the platform's
+tokens) and answers the probe (`dump_ui`, `touch_move_to`, `move_to_text`). The API
 reference is `reference/ui.md`; this skill is how to use it well.
 
 ## What works
@@ -14,7 +15,7 @@ Two games written from this package alone (`examples/lantern-vale`,
 `examples/hollowbell`) used the main menu, pause, cutscene, shop and
 results templates (the results with a localised Best and New best) and a
 text field with input-method composition, and none needed wiring beyond
-its desc; a skin pack copied into the game restyled every screen, and
+its desc; a style copied into the game restyled every screen, and
 `og polish` measured taste 99 for both. The Kestrel Stair
 (`examples/kestrel-stair`) used the cutscene, tutorial overlay,
 inventory with drag and drop, level select, leaderboard with its honest
@@ -50,14 +51,14 @@ if (r.closed) state.screen = "map";
 Screenshots of every template at desktop (1280×720) and on a phone in portrait
 (390×844 at 3×) are in the engine repository under `templates/ui-kit/screens/`;
 the full-size reference frames are `crates/og-ui/references/metal/kit-*.png`,
-and every style pack's screens on a phone `kit-skin-<pack>-phone.png`.
+and every style pack's screens on a phone `kit-style-<pack>-phone.png`.
 
 | The game needs | Call | It answers |
 |---|---|---|
 | A title screen | `og.ui.mainMenu(id, { title, subtitle, items, footer, instant })` (`instant` while it is the screen the game opens on: §6) | `selected`: the item id |
 | Pause | `og.ui.pauseMenu(id, { open, items })` (Resume, Settings, Quit by default) | `selected`; Back answers `resume` |
-| Settings | `og.ui.settingsScreen(id, { open, settings, languages, onChange, onSave })` | the new `GameSettings`, `changed`, `closed` |
-| A platformer HUD | `og.ui.platformerHud(id, { lives, maxLives, coins, score, level, timeLeft, touch })` (what it is not given it does not draw: `maxLives: 0` no hearts, no `coins` or `score` no capsule for them; the words `pauseLabel`, `jumpLabel` from the string table, og-i18n §2) | `paused`, `moveX`, `action: "jump"` |
+| Settings | `og.ui.settingsScreen(id, { open, settings, languages, world, onChange, onSave })` (with `world`, a new graphics preset is applied: `og.render.applyQuality`) | the new `GameSettings`, `changed`, `closed` |
+| A platformer HUD | `og.ui.platformerHud(id, { lives, maxLives, coins, score, level, timeLeft, touch })` (what it is not given it does not draw: `maxLives: 0` no hearts, no `coins` or `score` no box for them; the words `pauseLabel`, `jumpLabel` from the string table, og-i18n §2) | `paused`, `moveX`, `action: "jump"` |
 | A shooter HUD | `og.ui.shooterHud(id, { health, armor, ammo, reserve, abilities, map, touch })` (the words `killsLabel`, `fireLabel`, `pauseLabel`) | `paused`, `action` (ability id, `fire`), stick |
 | A puzzle HUD | `og.ui.puzzleHud(id, { level, score, target, stars, moves, timeLeft })` (the words `movesLabel`, `targetLabel` with `{target}`, `pauseLabel`) | `paused` |
 | An idle or incremental HUD | `og.ui.idleHud(id, { currencies, generators })` (the words `tapLabel`, `levelLabel` with `{level}`, `rateLabel` with `{rate}`, `pauseLabel`) | `action: "tap"` or `"buy:<id>"` |
@@ -118,13 +119,15 @@ wire. On a Mac (`Viewport.macKeys`: the web shell sets it from the
 browser's platform, a native host on macOS) Cmd+A, C, X, Z are the
 shortcuts, Cmd+←/→ go to the line's ends, Option+←/→ (and
 Option+Backspace or Delete) move by words, and Ctrl takes the emacs keys
-(A/E the line's ends, F/B a character, N/P a line, D/H delete one, K to
-the paragraph's end, U to its start, W the word before); elsewhere Ctrl
+(A/E the line's ends, F/B a character, N/P a line, D/H delete one, K
+kills to the paragraph's end, U to its start, W the word before, Y yanks
+what they killed, T transposes); elsewhere Ctrl
 takes the shortcuts and moves by words. Words are Unicode's (UAX #29):
 `can't` is one, each Chinese character is one, Thai moves a cluster at a
 time. The caret and Backspace step over a whole grapheme cluster (`é`
-typed as e and an accent, an emoji with its skin tone), and ←/→ move as
-they point: in Hebrew or Arabic ← goes on in the text. A double click selects a word and a triple
+typed as e and an accent, an emoji with its skin tone), and ←/→ move on
+screen: in Hebrew or Arabic ← goes on in the text, and across the edge of
+a Hebrew word in a Latin line the caret goes where the arrow points. A double click selects a word and a triple
 click the line, Shift+Z or Y redoes (typing undoes a word at a time, an
 input method's commit at a time), and a drag past an area's edge scrolls
 it. A text the game sets starts the field's undo history again. Script a
@@ -143,9 +146,9 @@ its own names `coin`, `gear`, `fire`…, and every kit screen draws them) loads
 { font } })`; `og.ui.icon(id, "heart", { size, tint })` and `[icon=heart]`
 then draw crisp distance-field glyphs at any size in their ink. A texture
 grid (`icons: { texture, columns, rows, names }`) still works for painted
-icons. Icons sit in `fgMuted` or `fgSubtle` (design language: icons are
-neutral). Sets name their icons differently (iconoir's `coins` and
-`fire-flame`, the skin grids' `coin` and `fire`): an unknown name draws an
+icons. Icons sit in `inkMuted` or `inkFaint` (icons stay neutral; colour
+is for state). Sets name their icons differently (iconoir's `coins` and
+`fire-flame`, the style grids' `coin` and `fire`): an unknown name draws an
 empty slot and warns, so a template that may meet either asks
 `og.ui.hasIcon(name)` first and draws its fallback, or names an icon twice
 in its set (`icon "coin" "coins"`). A path's `stroke-linejoin` is kept
@@ -256,7 +259,11 @@ phone), down past it. Every HUD template and any HUD built from
 `og.ui.anchor` groups gets this; a corner drawn another way (screen
 sprites, a row placed by hand) reads `covered` itself, so put a game's own
 HUD in anchored groups. Preview it
-with `og.ui.previewViewport(world, { ..., covered: { x: 12, y: 12, width: 40, height: 40 } })`.
+with `og.ui.previewViewport(world, { ..., covered: { x: 12, y: 12, width: 40, height: 40 } })`,
+or give a native run the page's cover from outside the game with the
+command `cover:12,12,40,40` (`og run --setup cover:12,12,40,40`; a
+playtest's `setup: "cover:12,12,40,40"`, og-build §6), `cover:none`
+clearing it.
 `og.ui.frameViewport().breakpoint` is `phonePortrait`, `phoneLandscape`,
 `tablet` or `desktop`; templates rearrange themselves by it (tabs become a
 select, side panels move under, touch controls appear when `touch` is set).
@@ -284,46 +291,60 @@ fingers with `touch_start` for the first and `touch:1:down:<x,y>` /
 `touch:1:move:<x,y>` / `touch:1:up` for the second
 (`templates/ui-kit/tests/gestures.og.ts`).
 
-## 6. Theming: skins, motion, transitions, sounds
-
-The default look is the platform's tokens; a game should have its own. A
-**skin** (`og.load.skin`, an `.ogt` of `type skin`) replaces the palette,
-radii, type ramp, durations, fonts and icons, and dresses every element
-class in nine-slice frames from its atlas (panel, card, button with hover,
-pressed and disabled, field, slot, tooltip, HUD capsule, progress track and
-fill), with ornaments (panel corners, the divider, a heading flourish), a
-panel texture, shadows and glows, press squash and hover lift, entrances and
-sounds. Choosing one is og-taste §1. Six packs to start from are in
-the engine repository under `templates/ui-kit/assets/skins/` (`pixel`,
-`cartoon`, `fantasy`, `scifi`, `paper`, `neon`; copy the directory into the
-game's `assets/skins/` and rename it at will: a skin's ids are read
-relative to its file first, then from `assets/`; og-taste §1 has the one
-line to check, the CJK `fallback`):
+## 6. Styles: the look of the game's UI, motion, transitions, sounds
+
+The game's UI follows the game's art, never the Origin platform's look:
+the engine has no house style to fall back on. Without a style a UI draws
+in **prototype**, the engine's placeholder: greys, near-square corners and
+a cyan focus ring, meant to be replaced. `og polish` warns when a game
+ships in it. A **style** (`og.load.style`, an `.ogt` of `type style`) is
+complete: its scheme, every palette role (`backdrop`, `panel`, `ink`,
+`inkMuted`, `primary`, `focus`, `hud`, `danger`, ...), the four radii
+(`small`, `control`, `bar`, `panel`), the type ramp, durations, fonts and
+icons. It dresses every element class in nine-slice frames from its atlas
+(panel, card, button with hover, pressed and disabled, field, slot,
+tooltip, HUD box, progress track and fill), with ornaments (panel corners,
+the divider, a heading flourish), a panel texture, shadows and glows,
+press squash and hover lift, entrances and sounds. Choosing one is
+og-taste §1.
+
+The usual way in is the game's look (og-taste §12): its `ui` line names
+the style, and every catalogue preset already names one. `ui "pixel"` is a
+built-in style by slug (`pixel`, `cartoon`, `fantasy`, `scifi`, `paper`,
+`neon`; `og cook` bundles the one a look names). `ui
+"styles/<name>/style.ogt"` is the game's own, and a game's
+`assets/styles/<slug>/style.ogt` wins over the built-in of that slug.
+To make one from a built-in, copy `templates/styles/<slug>/` of the
+engine repository into the game's `assets/styles/<name>/` and change it
+at will: a style's ids are read relative to its file first, then from
+`assets/`. A style file must name every palette role and all four radii;
+`og cook` lists the ones missing. Loading one by hand:
 
 ```ts
-const skin = og.load.skin(world, "skins/fantasy/skin.ogt");   // atlas, fonts, icons load with it
+const style = og.load.style(world, "styles/fantasy/style.ogt");   // atlas, fonts, icons load with it
 og.ui.configure(world, {
-  skin: skin.ok ? skin.value : null,
-  contrast: "high",                  // still applies over a skin
+  style: style.ok ? style.value : null,
+  contrast: "high",                  // still applies over a style
   reducedMotion: settings.reducedMotion,   // every motion becomes a fade
   sounds: { hover, press, open, close, success, error },  // og.load.sound handles, played on the ui bus
 });
-og.ui.configure(world, { reducedMotion: true });   // later, from the settings: the skin, fonts and sounds stay
+og.ui.configure(world, { reducedMotion: true });   // later, from the settings: the style, fonts and sounds stay
+og.ui.configure(world, { primaryColor: "#e0553b" });   // re-colour the style's primary; hover, pressed and the ink on it follow
 ```
 
 `configure` takes a partial UiDesc: a field left out keeps the value the
-last call gave it (or the skin a look applied, `GameDesc.look` and
-`og.render.applyLook`), and `null` clears one (`skin: null` is the
-platform tokens again). A UI left with no font at all warns that it draws
+last call gave it (or the style a look applied, `GameDesc.look` and
+`og.render.applyLook`), and `null` clears one (`style: null` is the
+prototype style again). A UI left with no font at all warns that it draws
 no text.
 
-A skin's `slice` line says how a frame's edges and centre fill: `stretch`
+A style's `slice` line says how a frame's edges and centre fill: `stretch`
 (the default), `repeat` (tiled at the art's size from the corner, the last
 tile cut) or `round` (a whole number of tiles resized to fit, as CSS
 `round`): tile patterned borders (a rope, a rivet row, a pixel bevel),
 stretch plain ones. `glass <part> <blur> <fill> [tint]` makes a part glass:
 the game behind it blurred (`blur` CSS px), tinted by the part's fill, under
-its frame drawn at `fill` opacity (the scifi pack's dialogs:
+its frame drawn at `fill` opacity (the scifi style's dialogs:
 `glass panel 16 0.85 0.15`). Glass blurs the scene and the UI drawn under
 it (a HUD under a glass dialog); it costs a frame copy and a blur pyramid
 when any is on screen (about 0.8 ms at 1280×720 on an M4 Pro), and one more
@@ -335,43 +356,44 @@ translucent fills (secondary buttons, chips, tracks) flat. Your own
 see-through overlays should follow: read `og.ui.frameTheme().reducedTransparency`
 (and `reducedMotion`) and draw them opaque.
 
-A skin of the game's own art: draw each part as a nine-patch PNG
+A style of the game's own art: draw each part as a nine-patch PNG
 (`panel.9.png`, `button.9.png`, `buttonHover.9.png`, ..., `soft.9.png`: the
 art inside a one-pixel border whose top row and left column mark in opaque
 black what stretches) and any ornament as a plain PNG (`corner.png`,
-`divider.png`, `flourish.png`, `tile.png`) in the skin's directory, then
-`og skin pack assets/skins/<name>`: it packs them into `atlas.png` and
-writes the skin file's `atlas`, `slice` and `soft` lines and the ornaments'
-regions, keeping every other line (palette, fonts, a slice's `tint` or
+`divider.png`, `flourish.png`, `tile.png`) in the style's directory, then
+`og style pack assets/styles/<name>`: it packs them into `atlas.png` and
+writes the style file's `atlas`, `slice` and `soft` lines and the ornaments'
+regions, keeping every other line (palette, radii, fonts, a slice's `tint` or
 `repeat`). Re-run it after redrawing a part.
 
-Never pass hex colours for chrome: use `{ token: "accent" }`, `"fgMuted"`,
-`"surface"` and the type steps (`displayLg`, `xl`, `meta`); the skin's
-palette answers them. A container that should look like a HUD capsule or a
-card takes `frame: "capsule"` (or `"card"`, `"slot"`…) in its desc; titles
-take `heading: true`. Without a skin both are plain.
+Never pass hex colours for chrome: use `{ token: "primary" }`, `"inkMuted"`,
+`"panel"` and the type steps (`xl3`, `xl`, `meta`); the style's
+palette answers them. A container that should look like a HUD box or a
+card takes `frame: "hud"` (or `"card"`, `"slot"`…) in its desc; titles
+take `heading: true`. Without a frame atlas both are plain fills at the
+style's radii.
 
 Motion and juice, all by the tick and in the UI state:
 
 | Want | Call |
 |---|---|
-| A score, coins or a reward counting up | `og.ui.counter(id, value, { from: 0, font: "display", step: "displayLg" })` |
+| A score, coins or a reward counting up | `og.ui.counter(id, value, { from: 0, font: "display", step: "xl3" })` |
 | Sparks when a star or reward lands | `og.ui.burst({ count: 10 })` right after the element |
 | A panel or item popping in | `og.ui.transition(id, show, { kind: "pop" })` (also `fade`, `slideUp`…, `scale`) |
 | A change of game screen | `const s = og.ui.screenTransition("Screens", state.screen, { kind: "iris" }).shown;` then build `s` (`fade`, `wipe`, `iris`, `dissolve`, `slide`; a colour or a texture) |
-| A wrong answer, a locked door, a refused purchase | `og.ui.shake({ sound: true })` right after the element, once, on the tick it happens: it swings three times and comes to rest by itself (the skin's `motion.shake`, else 6 px), with the `error` sound |
+| A wrong answer, a locked door, a refused purchase | `og.ui.shake({ sound: true })` right after the element, once, on the tick it happens: it swings three times and comes to rest by itself (the style's `motion.shake`, else 6 px), with the `error` sound |
 
 `screenTransition` keeps the previous screen in `shown` for the closing
 half of its duration, switches at full cover, then reveals the new one.
 Build `shown`, not the requested screen; `dump_ui` therefore lists the old
 screen until the midpoint. The cover itself does not block input. A new
-panel's own skin entrance starts when that panel is first built, and
+panel's own style entrance starts when that panel is first built, and
 ignores presses until it arrives (§4): the closing half of a wipe plus
 that entrance explains why a press just after the switch can be lost.
 
-Skins add the rest themselves: dialog and panel entrances with staggered
+Styles add the rest themselves: dialog and panel entrances with staggered
 controls, hover lift and press squash on springs (the `hoverSpring 1 350` and `pressSpring 0.55 120` lines of a
-skin's `motion` block: damping ratio and response in ms; below 1 bounces), eased progress bars, toasts flying in,
+style's `motion` block: damping ratio and response in ms; below 1 bounces), eased progress bars, toasts flying in,
 a shake and the error sound on a press of a disabled button. Reduced motion
 keeps every shake still and turns the rest into fades. The screen the game
 opens on is built settled (`instant: true` on its `mainMenu`, `anchor` or
@@ -388,7 +410,7 @@ scripts are shaped (Arabic joins, Devanagari conjuncts) and every font's
 kerning pairs apply. What a game sets:
 
 ```ts
-og.ui.label("Quest", quest.text, { width: { kind: "grow" }, maxLines: 2, ellipsis: true, color: { token: "fgMuted" } });   // cut with … on the last line
+og.ui.label("Quest", quest.text, { width: { kind: "grow" }, maxLines: 2, ellipsis: true, color: { token: "inkMuted" } });   // cut with … on the last line
 og.ui.label("Gold", gold, { font: "rounded", step: "xl", nowrap: true });   // body, display, mono or rounded
 ```
 
@@ -430,7 +452,7 @@ script text with `type:`, not `key_down`.
 
 Fonts (the one rule for every label, field and button):
 
-1. The role's font (body, display, mono, rounded; the skin's or
+1. The role's font (body, display, mono, rounded; the style's or
    `og.ui.configure`'s) when it has every character: the whole label in it.
 2. Else the first of the locale's fonts (its string table's `fonts` line)
    that has every character: the whole label in that face, its Latin and
@@ -439,9 +461,9 @@ Fonts (the one rule for every label, field and button):
 3. Else run by run: each run of the label from the first font that has it,
    the role's font first, then the locale's fonts, `UiDesc.fallbackFonts`
    (a Hebrew or Devanagari face, a CJK face cooked with `runtime true`) and
-   the skin's `fallback`; a letter and its accents stay in one face. A
+   the style's `fallback`; a letter and its accents stay in one face. A
    CJK-only subset (lantern-vale's `tools/subset-font.py`) gives this: the
-   Latin in the skin's face, the Chinese in Noto, on one line.
+   Latin in the style's face, the Chinese in Noto, on one line.
 
 So choose by the subset: keep Latin in the CJK subset for one face per
 label, leave it out to keep the game's Latin face beside CJK. Tracking