flet-box 1.1.0 → 1.1.1

package/docs/widget/Stack.md

@@ -1,6 +1,6 @@
 # Stack
 
-Overlay container that lets children occupy the same box. It is relative by default so children can be positioned, and it supports a nine-point alignment.
+Overlay container: every child after the first paints in the same box, anchored by a nine-point `alignment` or by its own edges.
 
 ## When to use it
 
@@ -101,9 +101,10 @@ const stack = Stack({
 
 ## Tips
 
-- Stack is `position: "relative"` by default, which makes it a positioning context for absolute children.
-- `alignment` anchors children at one of nine points from top-left to bottom-right.
+- The first child stays in the flow and gives the stack its size; every child after it floats over that box.
+- `alignment` anchors the children that name no edges, at one of nine points from top-left to bottom-right. Top-left is the default.
 - Later children paint on top, so order them from back to front.
+- A child that names its own `top`/`right`/`bottom`/`left` keeps those, and a child that declares `position` is left alone — that is how a child stays in the flow.
 
 ## Accessibility
 
@@ -111,8 +112,8 @@ const stack = Stack({
 
 ## Behavior
 
-- The root is a plain block by default and children are laid out per `position` and `alignment`.
-- Set `width` and `height` (or `expand`) when the stack needs a definite size for layered content.
+- The root is a flex column, so `alignment` places the in-flow child too; an explicit `justifyContent` or `alignItems` wins over it.
+- The layers take no space. Give the stack a `width` and `height`, or make the first child the size you want the box to be, or there is nothing for them to sit on.
 
 ## Related widgets
 

package/docs/widget/Stepper.md

@@ -122,6 +122,8 @@ const checkout = Stepper({
 
 - Steps are clickable, so users can jump around; use onStepChange to validate a step before allowing the move.
 - variant: icons pulls each step's icon; circles and numbers ignore it.
+- A step's content is a live widget and a DOM node has one parent, so build the steps array where the Stepper is built: sharing one array between two steppers empties the first slot, and the widget warns when it happens.
+- orientation: vertical puts each label beside its marker; horizontal puts it underneath. showLabels: false hides it in both.
 
 ## Accessibility
 

package/docs/widget/Tooltip.md

@@ -116,11 +116,12 @@ const tip = Tooltip({
 
 - Attach it to any widget via child; the tooltip is a separate portal, so overflow hidden ancestors do not cut it off.
 - delay controls how long the pointer must rest before the tooltip appears; lower it for dense toolbars, raise it for error-prone hints.
-- The bubble is clamped to the viewport edges, so top/left placements can sit slightly inside the window bounds.
+- The bubble keeps to the device's safe area, so a placement is a request: an edge with no room for it gets the opposite edge instead.
 
 ## Accessibility
 
 - The wrapped child keeps its focus handlers, so keyboard users tabbing onto it get the same tooltip as mouse hover.
+- On a device that cannot hover the bubble stays hidden. iOS answers the first tap with a synthetic mouseenter and never sends the matching mouseleave, so a tap-shown tooltip is a bubble nothing can dismiss. Anything a tooltip explains has to be explained by the control's own label too.
 
 ## Behavior
 
@@ -128,6 +129,7 @@ const tip = Tooltip({
 - The wrapped child gains showTooltip, hideTooltip, updateContent, and updatePosition helpers for imperative control.
 - A pointer that leaves before the wait is over never shows the bubble: leaving clears the timer.
 - tooltipDelay is the old name of delay. When both are given, delay wins.
+- The requested position is a preference, not a promise: when the bubble would not fit between the trigger and the safe-area edge it is placed on the opposite side, and the arrow follows it.
 
 ## Related widgets
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flet-box",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Declarative, zero-dependency UI framework in vanilla JS — ship web, PWA, Android and iOS from one codebase",
   "type": "module",
   "main": "src/index.js",
@@ -19,7 +19,7 @@
     "dev": "node bin/cli.js run --hot",
     "build": "node bin/cli.js createBundle",
     "release": "node bin/cli.js release",
-    "test": "node scripts/check-widgets.mjs && node scripts/check-widget-scale.mjs && node scripts/check-prop-registry.mjs && node scripts/check-docs-props.mjs && node scripts/check-api-surface.mjs && node scripts/check-api-propscan.mjs && node scripts/check-router-base.mjs && node scripts/check-clean-ui.mjs && node scripts/check-skills.mjs && node scripts/check-ota-assets.mjs && node scripts/check-pwa-shell.mjs && node scripts/check-cli-install.mjs && python3 tools/snippets-creator-flet-box/build_snippets.py --check && node scripts/check-snippets.mjs",
+    "test": "node scripts/check-widgets.mjs && node scripts/check-widget-scale.mjs && node scripts/check-shared-helpers.mjs && node scripts/check-a11y.mjs && node scripts/check-prop-registry.mjs && node scripts/check-docs-props.mjs && node scripts/check-api-surface.mjs && node scripts/check-api-propscan.mjs && node scripts/check-time-helpers.mjs && node scripts/check-router-base.mjs && node scripts/check-clean-ui.mjs && node scripts/check-framework-ui.mjs && node scripts/check-skills.mjs && node scripts/check-app-types.mjs && node scripts/check-ota-assets.mjs && node scripts/check-pwa-shell.mjs && node scripts/check-cli-install.mjs && python3 tools/snippets-creator-flet-box/build_snippets.py --check && node scripts/check-snippets.mjs",
     "test:browser": "node scripts/run-browser-tests.mjs"
   },
   "keywords": [
@@ -47,6 +47,7 @@
   "devDependencies": {
     "chokidar": "^4.0.3",
     "esbuild": "^0.28.0",
+    "typescript": "^7.0.2",
     "ws": "^8.21.0"
   },
   "files": [

package/skills/fletbox-design/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: fletbox-design
-description: The design contract for a FletBox app - tokens only, one scale, three-tier hierarchy, a state for every interaction, measured contrast, composition that starts as a sentence, the dated visual tells that give away a template, destructive actions designed last. Use when creating, editing or reviewing any screen, form, list, dialog, hero or action control.
+description: The design contract for a FletBox app - tokens only, one scale, three-tier hierarchy, a state for every interaction, measured contrast, composition that starts as a sentence, the dated visual tells that give away a template, destructive actions designed last, and Part II, the visual atlas: six style archetypes with their surface ramps, accent budget, number-as-hero typography, nested radii, photo-and-sheet composition, control shapes, data widgets and per-genre recipes. Use when creating, editing or reviewing any screen, form, list, dialog, hero or action control, or when choosing how a screen should look.
 ---
 
 # Design — the system rules for a FletBox screen
@@ -82,7 +82,7 @@ No arbitrary values, no hex, no `px` strings. Every value comes from the scale.
 
 ```
 space    4 · 8 · 12 · 16 · 18 · 24 · 32 · 40 · 48 · 64 · 96
-radius   4 · 8 · 12 · 16 · 999 (pill)
+radius   4 · 8 · 12 · 16 · 20 · 24 · 999 (pill)
 type     12 caption · 14 body-small · 16 body · 18 subtitle · 24 title
          32 headline · 40 display-sm · 48 display
 weight   400 body · 500 label · 600 title · 700 headline
@@ -92,9 +92,11 @@ depth    elevation 0 · 1 · 2 · 3 · 4 · 5
 
 - The base unit is 4 and everything is a multiple of it (Playbook p.028). A value
   like 13, 19, 21 or 31 is not a design decision, it is drift. A radius between
-  two steps — the 20 beside the 16 — is the same drift on the corner
-  (`OFF_SCALE_RADIUS`), and it is what makes a rounded picture sit next to a
-  square button like two products.
+  two steps — the 15 beside the 16, the 18 beside a 24 — is the same drift on the
+  corner (`OFF_SCALE_RADIUS`), and it is what makes a rounded picture sit next to a
+  square button like two products. The scale reaches 24 because `Drawer`,
+  `DrawerItem` and the `Tabs` slider already default there: an app matching its own
+  widgets cannot be off-scale.
 - Never type a hex or `rgb()` outside `src/database/themes.js`
   (`RAW_COLOR`). If a token is missing, add it there.
 - Never build a color by appending alpha to a token — `colors.primary + "15"` is
@@ -205,7 +207,10 @@ unrelated things, and that difference is the whole message (Playbook p.013, p.02
 - Measure: 45-75 characters per line on desktop, 30-40 on mobile. A paragraph
   that runs the full width is unreadable at 1440 (p.076-078).
 - One typeface; two at the absolute maximum, and then headings against body
-  (p.075-076). Declare it once in the theme, never per `Text`.
+  (p.075-076). Declare it once — `loadFont("Inter", { weights: [400, 600] })` and
+  one `fontFamily` on the screen's root — never per `Text`. There is no font on
+  the theme: `fontFamily` is a routed prop, and the loader is what puts the bytes
+  behind the name.
 - `align: "left"` for every run of text and every list. `right` for numbers and
   prices, so magnitudes compare. `center` only for a short title or a lone CTA,
   never for a paragraph (p.018, p.094) — a centered paragraph is reported as
@@ -291,14 +296,17 @@ When accessibility and aesthetics conflict, accessibility wins. Every time.
   (p.022).
 - Every field has a visible `label`; a placeholder is a format hint, never a
   substitute (p.115). Every switch and checkbox has one too (`UNLABELED_TOGGLE`).
-- Every control that is only an icon gets a name: wrap it in
-  `Tooltip({ text, child })` or give it a visible label (`ICON_ONLY_CONTROL`).
+- Every control that is only an icon gets a name: `aria-label` on the control
+  itself, or a visible label beside it (`ICON_ONLY_CONTROL`). A `Tooltip` is a
+  description — it explains the control, it does not name it.
 - Every `Image` that carries information has `alt`; `alt: ""` is the correct
   answer for a decoration (`IMAGE_NO_ALT`).
 - Focus must be visible, keyboard must reach everything, and `Esc` must close
   whatever opened (`Modal({ closeOnEsc: true, showCloseButton: true })`).
 - Motion is optional content: respect a reduced-motion preference; never
-  auto-play a carousel or a banner.
+  auto-play a carousel or a banner. FletBox listens (`prefersReducedMotion()`,
+  `setMotionMode('reduce')`) and the engine obeys it, so a hand-written
+  `requestAnimationFrame` is the only way to ignore it — see `fletbox-motion`.
 
 ## 12 Every interaction has four states
 
@@ -309,7 +317,13 @@ all four, in the same component, before the screen counts as done.
 Column({ gap: 16, children: [
   loading ? Skeleton({ width: "100%", height: 48, count: 3 }) : null,
   !loading && rows.length === 0
-    ? EmptyState()                       // headline + illustration + tip + CTA
+    ? Column({ gap: 16, alignItems: "center", children: [
+        Icon({ name: "inbox", size: 48, color: colors.textSecondary }),
+        Text({ text: "No projects yet", size: 18, weight: "bold" }),
+        Text({ text: "Create one to see it here.", size: 14,
+               color: colors.textSecondary, align: "center" }),
+        Button({ text: "New project", onPress: create }),
+      ]})                                  // headline + illustration + tip + CTA
     : null,
   failed
     ? SnackBar({ message: "Could not load the list.", action: "Retry", onAction: retry })
@@ -439,10 +453,18 @@ broken" report, and none of them is something `npm run ui` can see:
 - **`alignItems: "center"` centers the block, not the text.** A paragraph that
   wraps inside a centered column becomes a ragged stripe: center the heading,
   left-align the copy (rule 08).
-- **There is no breakpoint prop, and none is needed.** Responsiveness is
-  `flex`, `wrap: true` and `maxWidth` — plus the rem contract: a number is a
-  fraction of the reader's font, so one build fits a phone and a desktop. A
-  screen built from two hard-coded layouts is two screens to maintain.
+- **Fluid first, breakpoint second.** `flex`, `wrap: true`, `maxWidth` and the rem
+  contract carry one screen from phone to desktop with no decision at all, and
+  that is the default. There is no breakpoint *prop* — when a shape genuinely
+  changes (one column into two, a rail into a drawer), the change is made in the
+  code that builds the tree, with the one table: `atLeast("md")` for the boolean,
+  `currentBreakpoint()` for the name, a per-step value function for a number that
+  really wants to be different at 400px and 1400px. `md` is 768, the same line
+  `AdaptiveScaffold` crosses, so a screen and its shell cannot disagree. Read the
+  width, never the user agent: `device.isMobile()` answers a platform question
+  (long-press, a native back gesture), not a layout one. A screen built from two
+  hard-coded layouts is two screens to maintain; a screen with one per-step value
+  where the shape truly changes is one.
 - Overlays go in a `Stack` with `stackPosition`, not in absolute coordinates on
   `Container({ pos: "absolute", top, left })`. The first survives a content
   change; the second is a pixel bomb in any language longer than English.
@@ -571,3 +593,357 @@ npm run dev        # look at the screen, at 375px and at 1440px
 
 Fix the code, not the checker. Then make the rule reusable: if the fix was right
 for this screen, it is a rule for every screen, and it belongs in this file.
+
+---
+
+# PART II — THE VISUAL ATLAS
+
+Rules 01-24 say what is legal. They do not say what to choose, and a screen that
+is merely legal looks like nothing. Part II is the menu: the looks that hold up
+for their own reasons, each reduced to the calls that produce it in this
+framework. It is read after the rules, never instead of them — every recipe below
+still has to pass `npm run check`, `npm run ui` and rules 01-24.
+
+Nothing here cites a trend, a screenshot or a mood board. Each rule states its
+mechanism — what the eye is actually doing, or what the CSS engine will and will
+not accept — so an edge case can be judged from the reason instead of from the
+precedent. Where a number appears it is either arithmetic (30), a measured ratio
+from this palette (03, 11, 35), or a size the framework ships.
+
+## 25 Three laws
+
+One accent, one surface family, one hero. These three hold across mobile and web,
+dark and light, and every genre; a screen that breaks any of them is not
+stylistically bold, it is unreadable in a new way.
+
+1. **One accent.** A neutral base plus exactly one saturated hue, spent on the
+   action and the selected state and nowhere else (26, 28). Two accents force the
+   eye to rank them, and it has no basis to rank them with.
+2. **One surface family.** Either a tinted dark ramp or a tinted paper; never a
+   black page with white cards, never a grey page with white cards (27).
+3. **One hero.** The screen has one element that is 3-5× the rest — usually a
+   number, once an image, rarely a word. Everything else is at reading size (29).
+
+Squint test for the three: if you can still tell which element is the hero, and
+how many colored things there are, the screen obeys them.
+
+## 26 Pick an archetype, then obey it
+
+Name the archetype in the commit or in `.fletbox/memory/` before the first
+widget. A screen that mixes two of them is what rule 02 calls an exception.
+
+| Archetype | Use it when | The tell you must get right |
+| --- | --- | --- |
+| Acid-on-black | finance, media, fitness, tools, anything glanceable | the accent is on one element only (28) |
+| Tinted paper | commerce, food, wellness, content | the page is a wash of the accent, not grey (27) |
+| Photo-bleed + sheet | travel, product detail, real estate, recipes | the sheet overlaps the photo, it does not sit under it (31) |
+| Bento dashboard | dashboards, smart-home, admin | one tile is double-size and it is the hero (33) |
+| Editorial luxury | watches, perfume, hotel, long-read | one serif, used for the name of the thing only (29) |
+| Single-hue field | a brand moment: splash, campaign, empty state | the whole page is one hue, the text is its darker plate (27) |
+
+The six are exhaustive of what survives review here. The look they are usually
+reached for instead — violet mesh gradient, glass on every card, a 3D blob behind
+the phone — is not a seventh archetype; it is in 36 as a dated tell, and it is the
+one most often mistaken for a style.
+
+## 27 Surfaces are never the extremes
+
+Pure black under pure white is the one pair that always loses: `#000000` against
+`#ffffff` measures 21:1, and an eye moving across a list at that ratio keeps
+catching on the edges of every glyph. A large bright surface glows for the same
+reason. So the extremes get replaced by steps, and the steps are where the
+hierarchy lives. The shipped dark palette already obeys this — `background`
+`#09090b`, `card` and `surface` `#18181b`, `border` `#27272a` — a three-step ramp
+of one near-black hue. Use the steps, do not invent a fourth.
+
+- **Dark.** Depth is a lighter plate, not a shadow: a shadow on a dark page is
+  invisible, so the only signal available is value. Two steps maximum between the
+  page and the topmost card; a third step is a bug, because nobody can tell step
+  three from step two. A hairline `colors.border` rim replaces the shadow on an
+  elevated card (rule 10: `Container` ignores `elevation` — pass `shadow` or
+  `borderColor` there, never a bare number).
+- **Paper.** The page is a low-chroma wash of the accent (`colors.primaryBg`
+  exists for exactly this), the card is `colors.card`, and the tile inside the
+  card is one step back. Grey page under white card is the wrong version of this
+  look and reads as a wireframe: grey is a neutral, so it separates the card from
+  nothing.
+- **Single-hue field.** One hue carries the screen and the text is a darker or
+  lighter plate of the same hue — never a second hue for contrast, because a
+  second hue is a second accent and 25 allows one. In this framework that means a
+  new token in `src/database/themes.js` per theme, not an inline mix:
+  `colors.primary + "22"` is `HAND_MIXED_COLOR` (rule 03).
+- **Never** a pure-`#fff` page under pure-`#000` text with nothing between: that
+  pair is the failure this section exists to prevent, and the shipped light page
+  is `#ffffff` only because `surface` is `#f8fafc` and does the separating.
+
+## 28 The accent budget
+
+The accent is a budget, not a color. It may appear on, and only on:
+
+1. the one primary action;
+2. the selected state of whatever chose it (chip, tab, nav icon, swatch);
+3. the hero number, when the number is the point.
+
+Everything else — headers, labels, icons, dividers, decorative plates — stays
+neutral. This is rule 09's "reserve the brand for things you can click" with the
+count added: three placements, and a fourth means one of them is not an accent.
+The mechanism is learning: a color that appears on non-clickable things stops
+being a cue, and the user stops reading it — so the CTA loses the very property
+that made it findable.
+
+- Secondary is the same ink, hollow: `variant: "outlined"` naming its own
+  `color:`, or `variant: "text"`. Never a second hue for the second button.
+- A gradient on the primary is legal only as **two shades of one hue** — a violet
+  button running `#9D70F6 → #5520FF`, both declared as tokens, is still one
+  accent. Cap any gradient at two hues: three is no longer a surface, it is an
+  event, and it competes with the CTA for the same attention (36).
+- Glow is the accent's only other permitted spend, and only on dark, because a
+  bloom over a light page is indistinguishable from a smudge:
+  `CircularBar({ glow: true, glowColor: colors.primary })`, or a tinted `shadow`
+  string on the CTA. One glowing element per screen.
+
+## 29 The number is the hero
+
+The composition every genre that shows a quantity should reach for: one oversized
+tabular numeral, its label above it in muted text, and nothing else on the screen
+competing. A magnitude read as a shape is understood faster than the same
+magnitude read digit by digit, which is why the number gets the size and not the
+heading.
+
+```js
+Column({ gap: 4, children: [
+  Text({ text: "Total balance", size: 12, weight: 500, color: colors.textSecondary, letterSpacing: 0.4 }),
+  Row({ alignItems: "flex-end", gap: 8, children: [
+    Text({ text: "26072", size: 40, weight: 700, color: colors.text, letterSpacing: -0.8, lineHeight: 1.1 }),
+    Text({ text: ".00", size: 18, weight: 500, color: colors.textSecondary }),
+    Text({ text: "+4.2%", size: 14, weight: 600, color: colors.successStrong }),
+  ]}),
+]})
+```
+
+- The jump is 3-5× the body size, and the numeral is the only element at that
+  size on the screen. Two heroes is zero heroes (rule 04).
+- Decimals and currency marks one step down and muted: the eye is meant to read
+  the magnitude first. `letterSpacing` goes slightly negative on big digits and
+  positive on small caps labels — never both the same.
+- Delta text is `colors.successStrong` / `colors.dangerStrong`, never the plate
+  tokens (rule 09: `colors.success` is 2.54:1 with white on it and is a dot).
+- Serif is a brand voice, not a font choice: one serif for the name of the thing
+  (product, hotel, edition), sans for everything readable, and never a serif
+  paragraph. Declare it once with `loadFont` and one `fontFamily` on the root,
+  not per `Text` (rule 08).
+- Uppercase with wide tracking is for a two-word label, never for a sentence,
+  and never for the body: tracking destroys the word shape that a reader
+  recognizes, so it costs speed everywhere it is not a single glance (rule 19's
+  eyebrow ban still applies to the label above a heading).
+
+## 30 Radius, nesting and the pill
+
+- Controls are pills: `borderRadius` = half the height. Cards are 16-24. Inner
+  thumbnails and tiles are 12-16, one step below their card.
+- **The nesting rule**, as arithmetic: `outer = inner + padding`. A 16-radius
+  tile inside 8 of padding needs a 24-radius card. Equal radii at both levels is
+  the failure — the inner corner and the outer corner curve on the same radius,
+  so the gap between them reads as a second box rather than as one plate.
+- A radius between two steps is `OFF_SCALE_RADIUS` (rule 03), and the reason is
+  perceptual, not bookkeeping: the corner is what people match by eye, so a 15
+  beside a 16 looks like a mistake even when nobody can say why. 20 and 24 are
+  steps, not neighbours — they are where the nesting rule lands, and where the
+  framework's own drawers and tab indicators sit.
+- One radius language per screen (rule 02). A pill button inside a 16-radius card
+  on a 24-radius sheet is three languages; pick the card radius and let the
+  controls be pills, since a pill is the one shape that reads as a control at any
+  card radius.
+
+```js
+Card({ borderRadius: 24, padding: 16, children:
+  Row({ gap: 12, alignItems: "center", children: [
+    Image({ src: thumb, width: 56, height: 56, borderRadius: 12, fit: "cover", alt: "" }),
+    Column({ gap: 2, children: [
+      Text({ text: title, size: 16, weight: 600, color: colors.text }),
+      Text({ text: subtitle, size: 12, color: colors.textSecondary }),
+    ]}),
+    Button({ text: "Add", variant: "filled", height: 36, borderRadius: 999 }),
+  ]}),
+})
+```
+
+## 31 Photo, scrim, sheet
+
+The composition of every photo-led genre — travel, product detail, real estate,
+recipes — and the one place a `Stack` earns its keep:
+
+```js
+Stack({ alignment: "bottom-left", height: 420, children: [
+  Image({ src: hero, fit: "cover", alt: "The room as booked", full: true,
+          maskImage: "linear-gradient(to top, rgba(0,0,0,0.75) 0%, transparent 55%)" }),
+  Card({ borderRadius: 24, padding: 20, margin: 16, child:
+    Text({ text: "From $128 a night", size: 18, weight: 600, color: colors.text }) }),
+]})
+```
+
+- The sheet **overlaps** the photograph's bottom edge; a card placed under a
+  photo is a caption, and a caption says the photo is the subject of the screen.
+- Words over a photograph need a scrim, and the scrim belongs on the image
+  (`maskImage`) or as its own plate (`colors.overlay`) — light text over one
+  unscrimmed photo is the finding rule 11 already names.
+- **Color harvest**: the page tint comes from the photograph's dominant hue, so
+  the image and the interface are the same color event instead of two arguments.
+  It is a token decision, so it goes into `src/database/themes.js` as a named
+  tint, not an inline hex.
+- **Glass is for the layer that floats over scrolling content** — the nav over a
+  feed, the sheet over a photo. `colors.glass` with `colors.glassBorder` and
+  `backdropFilter` on a solid page is a texture, not a hierarchy (rules 10, 19):
+  translucency only means anything when there is something moving behind it.
+  Translucency only means something when there is something moving behind it: a
+  glass panel over a photograph reads as a layer, the same panel over a gradient
+  reads as a smudge.
+
+## 32 The shape of each control
+
+| Job | The shape | The call |
+| --- | --- | --- |
+| choose 1 of 3-6 | pill row, one filled, rest hollow | `Chip({ variant: "filled" \| "outlined" })` in a `Row({ gap: 8, wrap: true })` |
+| switch 2 views of one object | segmented pill with a sliding plate | `Tabs({ variant: "pills", tabs, activeIndex, activeTextColor, buttonColor })` |
+| choose 1 of N with a preview | selection **tile**, not a radio list | `ListTile({ selected, selectedBgColor })`, or a 2-up `Row` of `Card`s |
+| pick a color/size | dot row, selected gets a ring | `Avatar({ shape: "circle", size: 28 })` row, ring via `borderColor` + `borderWidth` |
+| count then buy | stepper merged into the CTA | one `Row` of `Button`s inside the add-to-cart bar, not two actions |
+| navigate the app | bottom bar, active = accent + label | `BottomNavigation({ items, currentIndex, selectedColor, unselectedColor, showLabels: true })` |
+| a badge on an icon | dot, never a word | `Badge({ value, size, offset, borderColor: colors.background })` |
+
+- Selected state is **inverted**, not tinted: on dark, the selected chip goes
+  white-with-black-text among hollow dark chips. An inversion is seen before it
+  is read, and it survives a color-blind user; a slightly lighter grey is the
+  same hue at a value nobody can compare across a row.
+- Disabled is a desaturated gray token, not the same color at 40% opacity,
+  because opacity fades the text into whatever is behind it and changes its
+  contrast per surface. `colors.textDisabled` is already a different hue rather
+  than a fade for exactly that reason (rule 03).
+- Quantity, variant and price live in the same row as the action that spends them
+  (rule 15, Fitts). The same rule written as a label is cheaper still:
+  `Button({ text: "Add to cart · $34.21" })` — the decision and its cost are one
+  read instead of two.
+
+## 33 Data: the dial, the bento, the axis-less chart
+
+- **Dial as hero.** One KPI gets a ring, not a chart:
+  `CircularBar({ value, max, size: 180, strokeWidth: 14, lineCap: "round", label, subtitle, valueSize: 32, showValue: true })`.
+  The number sits inside the ring, so the gauge and the hero are one object and
+  one read. One per screen; a second ring is a decoration.
+- **Bento.** Two columns, mixed heights, uniform radius, one tile double-size and
+  that tile is the hero: `GridView({ columns: 2, spacing: 12 })` with tiles of
+  different `height`, or a `Row` + `Column` pair when the spans get awkward.
+  Gaps stay on the 4-scale (rule 03); dense is not the same as tight.
+- **Zero-label charts.** A sparkline with one number beats an axis:
+  `Chart({ type: "area", data, smooth: true, areaGradient: true, showGrid: false, showLabels: false, lineColor: colors.primary })`.
+  Gridlines ask the reader to measure; the delta text tells them the answer, and
+  the shape of the line carries the trend.
+- A chart's series color is the accent; its second series is a neutral, not a
+  second hue (rule 09). `Chart({ barColor })` and `lineColor` take tokens.
+- Skeletons, not spinners, and the shape of the skeleton is the shape of the
+  thing: `Skeleton({ count: 3, height: 72, borderRadius: 16, gap: 12 })` under a
+  list of 72-tall rows (rule 12).
+
+## 34 Genre recipes
+
+The moves each genre is made of. Each is a starting composition, not a
+permission slip: rules 01-24 still decide what ships.
+
+| Genre | The five moves |
+| --- | --- |
+| Onboarding | full-bleed image or one-hue field · one line at display size · dots or a ghost skip · one pill CTA at the bottom · nothing tappable else |
+| Dashboard | greeting + avatar · one hero number or card · 2-up tinted stat tiles · one chart, no axes · `BottomNavigation` |
+| Commerce list | pill search · horizontal `Chip` rail · 2-col `GridView` of image-first cards · price bold, strike-through muted · a circular add on the card |
+| Product detail | photo top half · sheet overlapping it with 24 top radius · dot swatch + size pills · sticky bar with price inside the CTA |
+| Wallet | dark ramp · card plate as the hero · signed rows, `+` in `successStrong`, `-` in `dangerStrong` · tabular amounts right-aligned |
+| Media player | artwork blurred as the page tint · square art · thin `ProgressBar` · circular transport row · no other chrome |
+| Social feed | story rail of `Avatar`s · full-bleed post cards · actions under the image, centered as a group · one accent for the like state only |
+| Travel | destination photo with scrim · date/guest pill row · horizontal card carousel with a peek of the next · price chip on the image |
+| Health | one or three rings · a 7-bar week strip · mint or lime accent on dark · the number inside the ring |
+| Settings | grouped rows, `ListTile` · leading icon in a tinted plate · trailing chevron or `Switch` · one section cap per group, no hairline between rows |
+| Web landing | transparent `AppBar` · display headline with one word in the accent · pill CTA + ghost pair · a three-number stat strip · card row below |
+
+## 35 Deriving a palette
+
+A theme is five roles, not five colors:
+
+```
+anchor   the darkest surface, never #000
+primary  the one hue the screen spends
+accent   a warm counter-hue, used at most once per screen
+wash     the tinted paper the page sits on
+ink      white or near-white, and its opacity tiers
+```
+
+- **Ramp, not swatch.** A family is 5-7 stops (base → tint → accent → shadow).
+  Build it as a ramp so a card, a tile and a plate can be three steps of one hue
+  instead of three hues — which is the only way 27's surface discipline is
+  possible without breaking 25's one-accent law.
+- **The light/dark pair rule**: for the same hue in both palettes, lift the
+  lightness and drop the saturation going dark. That is why this framework's dark
+  `dangerStrong` is `#fca5a5` where the light one is `#b91c1c` — the readable red
+  is the one that measures 4.5:1 *on that page*, which is rule 09's whole point.
+- **Shadows are tinted, never grey.** A real shadow is the page's own hue darkened
+  and made translucent, so the ambient shadow is a large blur at low alpha in that
+  hue (`0 5px 50px rgba(0,67,101,0.08)`). In FletBox that is a
+  `shadow: "0 20px 50px rgba(…)"` string on a `Container`/`Card` —
+  `colors.shadow` is the neutral default and is the flat version of the same idea
+  (rule 10).
+- Add the tokens to `src/database/themes.js` in **both** palettes. The gate that
+  checks the two palettes expose the same token names exists because a light-only
+  tint once deleted `colors.errorBg` out from under a running app; a token added
+  to one theme is a runtime `undefined` in the other.
+- Contrast is still the veto: `npm run ui -- --tokens` measures every pair. A
+  palette that looks right and measures 3.2:1 is a palette with a bug in it.
+
+## 36 The dated visual tells
+
+Rule 19 bans the template tells of copy and hierarchy. These are the *visual*
+ones, and each is named with the mechanism that dates it, so an edge case can be
+judged rather than obeyed.
+
+- **Violet mesh gradient behind the phone**, and the blurred 3D blob or sphere
+  floating in front of it. A decoration that carries no information reads as
+  stock the moment the eye finishes with it. There is no gradient page surface in
+  this framework anyway — `gradient` exists on `Button` and `AppBar`, which is the
+  system saying it is one element's surface (rule 19).
+- **Neumorphism**: extruded dials and pressed-in tiles. Its shadows are the only
+  depth cue, so the moment the surface changes the affordance disappears —
+  a control whose visibility depends on a light source is not a control.
+- **Glass over a solid page**, or glass on every card. See 31: translucency needs
+  something moving behind it, and a page of glass has no layer left to signal.
+- **Gradient-filled headline text.** `Text` has no gradient, and color running
+  across a word destroys the letter edges the reader is using. Emphasis comes
+  from weight and ink (rule 17).
+- **Hairline border + 6-8px radius + drop shadow on every card**, and a
+  `Divider` under every row: the three-piece card that separates everything and
+  therefore organizes nothing (rules 10, 19).
+- **Skeuomorphic props** — a rendered credit card as the hero of a wallet, a
+  photoreal watch bezel, isometric people, emoji as feature icons. They depict an
+  object instead of the user's own data, which is the one thing the screen has
+  that no stock art can supply.
+- **Default-blue SaaS**: a blue→indigo button, a grey page, white cards, no
+  accent discipline. It is not a color problem, it is a missing archetype
+  decision (26) — the palette was never tied to anything this product does.
+- **Three CTAs in a hero row**, and the floating-phone-on-a-plinth presentation:
+  both are portfolio staging, not interface.
+
+Deleting a tell is not a design: each one still owes its job to a rule —
+atmosphere to 27, hierarchy to 29, separation to 30, depth to 31, emphasis to 28.
+
+## 37 Choosing, in five questions
+
+Answer them before the first widget, in the commit message or the memory note.
+If two answers are "I don't mind", the screen is not being designed, it is being
+filled.
+
+1. Which archetype (26), and why does this product's genre point there?
+2. Which surface family, and which three steps of its ramp does this screen use (27)?
+3. Where is the accent spent — name the three placements (28)?
+4. What is the hero, and is it 3-5× everything else (25, 29)?
+5. Which tell from 36 is the one this screen is most likely to fall into, given
+   its genre and its imagery?
+
+Then run the loop in 24. Part II never overrides a rule from Part I: the atlas is
+the menu, the rules are the contract, and the checker has the last word on
+legality and the user has it on whether the screen is understood (23).