flet-box 1.0.9 → 1.1.1

package/docs/README.md

@@ -16,7 +16,8 @@ This documentation is one continuous book. Start at **Chapter 0** and follow the
 | 9 | [State, Router & Services](guides/state.md) | Shared state, navigation routes, storage, and HTTP | Intermediate |
 | 10 | [Tools & Utilities](tools/README.md) | The helper functions that ship with the framework | Intermediate |
 | 11 | [The CLI](cli/README.md) | Create, run, and build projects with `flet-box` | Intermediate |
-| 12 | [Clean UI](guides/clean-ui.md) | The design system every app ships with and the gate that enforces it | Intermediate |
+| 12 | [Clean UI](guides/clean-ui.md) | The four skills every app ships with, the design system they hold, and the gate that enforces it | Intermediate |
+| 13 | [Accessibility](guides/accessibility.md) | The focus ring, the keyboard pass over every press, the roles the widgets declare, and the overlays that hold the keyboard | Intermediate |
 | A | [Appendices](guides/minification-and-protection.md) | Minification, mobile, compatibility, embedding, online updates (OTA) | Advanced |
 
 > **Levels.** *Beginner:* start here and read in order. *Intermediate:* continue in order — you are comfortable with widgets. *Advanced:* for when you ship, skip on a first read.
@@ -54,6 +55,7 @@ Front cover (this page)
 → Utilities guide · guides/utilities.md
 → The CLI · cli/README.md
 → Clean UI · guides/clean-ui.md
+→ Accessibility · guides/accessibility.md
 → Appendices (minification → mobile → compatibility → embedding → online updates)
 → The end of the book
 ```

package/docs/cli/README.md

@@ -275,6 +275,7 @@ A typical generated project looks like this:
 ```text
 my-app/
 ├── index.html
+├── jsconfig.json
 ├── package.json
 ├── capacitor.config.json
 ├── manifest.json
@@ -301,7 +302,23 @@ my-app/
 
 The exact folders depend on the selected template.
 
-## A complete beginner workflow
+### Autocomplete without TypeScript
+
+`jsconfig.json` is not a build step: it tells the editor's own JavaScript
+language service to read `flet-box`'s bundled `src/index.d.ts`. With `checkJs`
+on, VS Code, Cursor and any editor that understands `jsconfig.json` autocomplete
+every widget, prop, colour token and helper — and underline a prop that does not
+exist, which is the same error `npm run check` reports from the command line.
+
+Nothing is installed and nothing is compiled. The framework keeps the promise
+honest with `scripts/check-app-types.mjs`, which creates all five templates and
+requires zero diagnostics over their `src/` — a starter that produces red
+squiggles fails `npm test`.
+
+```bash
+npm run check   # the gate: real API, real props, real imports
+```
+
 
 ```bash
 # 1. Create the project

package/docs/guides/README.md

@@ -10,7 +10,12 @@ This directory is the **conceptual index** of FletBox: how to build apps, set up
 - **[Frontend services](frontend-services.md)** — Chapter 9 · the practical walkthrough of the three storage layers (`RamStore`, `Session`, `Storage`) and the HTTP client.
 - **[FletBox utilities](utilities.md)** — Chapter 10 · layout/theme/format helpers and validator tools.
 - **[The CLI](../cli/README.md)** — Chapter 11 · create, run, and build projects with `flet-box`.
-- **[Clean UI](clean-ui.md)** — Chapter 12 · the token scale, the 21 rules, and the `flet-box check-ui` gate that enforces them.
+- **[Clean UI](clean-ui.md)** — Chapter 12 · the four skills `flet-box create`
+  installs, the token scale, the numbered rules (00–24 enforced, 25–37 the
+  visual atlas), and the `flet-box check-ui` gate that enforces them.
+- **[Accessibility](accessibility.md)** — Chapter 13 · the focus ring, the
+  keyboard pass over every press, the roles and states the widgets declare, and
+  the overlays that hold the keyboard.
 - **[Widget structure](widget-structure.md)** — the canonical, modular shape every widget follows (and how new ones are added).
 
 ## Appendices (Advanced — for shipping)

package/docs/guides/accessibility.md

@@ -0,0 +1,282 @@
+# Accessibility: the engine's half and your screen's half
+
+A FletBox control is a `div` that the framework teaches to behave like a
+`button`. That is what makes the syntax pleasant — `Container({ onPress })`
+instead of a stylesheet and three event listeners — and it is also where
+accessibility is won or lost. Three things have to be true for someone with no
+pointer: the control must be **reachable** (Tab), **operable** (Enter and
+Space), **announced** (a role and a name), and the person must be able to see
+**where they are** (a focus ring). An overlay owes a fourth: hold the keyboard
+while it is open, and give it back when it closes.
+
+The engine already does all four. This chapter is about the half it cannot do
+for you, and about the two ways an app destroys the half it was given.
+
+## 1. The focus ring is a stylesheet, not a paint
+
+A focus ring is not a decoration — it is a *state*, and a state can only live in
+a stylesheet. `src/utils/focusRing.js` appends one `<style id="fletbox-focus-ring">`
+to `<head>` the first time any widget is created, and never appends a second:
+
+```css
+:where(a[href], button, input, select, textarea, summary, [tabindex]:not([tabindex="-1"])):focus-visible {
+  outline: 2px solid var(--color-focusRing, #1d4ed8);
+  outline-offset: 2px;
+}
+```
+
+Three deliberate choices, each worth knowing when you want something different:
+
+- **`:focus-visible`, not `:focus`.** A click with a mouse does not ring; the
+  keyboard does. That is the browser's own distinction, not the framework's.
+- **`:where(…)` keeps specificity at zero.** One class of yours overrides it,
+  and no `!important` is needed anywhere.
+- **The color is a token.** `--color-focusRing` is written by `applyPalette` for
+  every theme, so the ring moves with the theme instead of being a literal that
+  only suits one background. The light palette's `#1d4ed8` is 6.4:1 on the page,
+  the dark one's `#93c5fd` is 11:1, and the literal after the comma in the rule
+  is the boot value a page shows before the first `setTheme`.
+
+The widths are pixels on purpose, next to `SHADOW_LEVELS` and the hairline
+`borderWidth`: a 1px ring is invisible and a 6px one is a blob, whatever the
+reader's font size is.
+
+### The one thing an app must never do
+
+```javascript
+// Never. An inline declaration outranks every stylesheet rule, including the
+// engine's, so this is what "the focus ring does not work" looks like in code.
+element.style.outline = "none";
+
+// Never, for the same reason, anywhere in a global stylesheet:
+// *:focus { outline: none; }
+```
+
+If you do not like the ring's colour, change the token — or override the rule
+with one class of your own, which `:where()` makes possible:
+
+```javascript
+import { registerPalette } from "flet-box";
+
+// The token is part of the palette, so both themes move it and nothing is
+// overridden behind the framework's back. A registered palette repaints only
+// when it is the one on screen.
+registerPalette("light", { focusRing: "#0f766e" });
+registerPalette("dark", { focusRing: "#5eead4" });
+```
+
+```css
+/* or, for one component only: a class beats :where(...) whatever the order */
+.chart:focus-visible { outline-color: var(--color-primary); }
+```
+
+### A field rings as a whole control
+
+`Input` is a wrapper with a border, an icon and sometimes a reveal button, and
+the native `<input>` inside it is only part of the control. A ring around the
+text box alone draws a box *inside* the thing it is supposed to mark. So the
+rule has a second pair:
+
+```css
+:where([data-fb-field]):has(> input:focus-visible) {
+  outline: 2px solid var(--color-focusRing, #1d4ed8);
+  outline-offset: 2px;
+}
+:where([data-fb-field]) > input:focus-visible {
+  outline: none;
+}
+```
+
+The `outline: none` there is a *rule*, at zero specificity, which any app can
+still override — that is the whole difference between silencing the inner box
+and killing the ring. The marker (`data-fb-field`) is written by `Input`; if you
+build your own composite field (a text box with a button inside), put the same
+marker on the wrapper and the ring lands where the control is.
+
+And keep the two jobs apart: **the border is validation, the ring is focus.**
+A field that paints focus by recolouring its rim, or by adding a `box-shadow`,
+puts two indicators where one belongs and loses the validation state the moment
+someone types.
+
+## 2. A press is a press, however it arrives
+
+Give any widget a click handler as a prop and the engine runs a keyboard pass
+over it — `src/widget-factory/effects.js`:
+
+- it sets `role="button"` **if you have not set a role**;
+- it sets `tabIndex = 0` **if you have not set one** (an explicit `-1` is your
+  decision to keep the element off the Tab path, and it is respected);
+- Enter and Space fire the same handler a pointer fires, with Space's default
+  (scrolling the page) cancelled and a held key counted as one press;
+- a nested control keeps its own keys — Enter on a `Button` inside a pressable
+  `Card` presses the button and the card, not twice the card;
+- native `button`/`a[href]` are left alone, and disabled controls are not made
+  Tab stops.
+
+```javascript
+Container({ onPress: openDetails, children: [Text({ text: "Details" })] });
+// role="button", tabIndex=0, Enter and Space → openDetails
+```
+
+The one way an app defeats this is to attach the handler to the element after
+the widget was built. The pass runs during construction; a handler assigned
+afterwards leaves a control with a click, no role, no Tab stop and no keyboard:
+
+```javascript
+const card = Container({ children: [Text({ text: "Details" })] });
+card.onclick = openDetails; // mouse-only: the engine already ran
+```
+
+Express the control with a prop instead — `onPress` (or `onClick`) on any
+widget — and the engine sees it.
+
+### An icon is decoration until it is a control
+
+`Icon` has two lives, and it picks one by itself:
+
+- `Icon({ name: "search" })` — no name for a reader, so it is marked
+  `aria-hidden="true"` and kept off the Tab path. Correct inside a `Button`
+  that already has text.
+- `Icon({ name: "search", onPress: focusSearch, "aria-label": "Search" })` — a
+  named, pressable icon keeps `role="button"` and is read as "Search, button".
+
+An icon-only control with no `aria-label` is read as "button", which is the
+worst of both worlds: reachable, operable, and anonymous. The places where the
+framework wires a glyph up for you already name it — the `AppBar` back arrow,
+`Input`'s `onIconPress` and reveal button, and the menu icon a `Scaffold`
+connects to its drawer.
+
+## 3. Names, roles and states the widgets already declare
+
+You can pass `role` and `tabIndex` as ordinary props, and any `aria-*`
+attribute reaches the element verbatim (`"aria-label": "…"`). Everything below
+is already in place; the table exists so you know what not to duplicate.
+
+| Widget | Role | States it keeps in sync |
+| --- | --- | --- |
+| `Button`, `Container` with `onPress` | `button` | — (engine pass) |
+| `Switch` | `switch` | `aria-checked` |
+| `Checkbox` | `checkbox` | `aria-checked` |
+| `Radio` / `Rating` | `radio` / `radiogroup` | `aria-checked` |
+| `Slider` | `slider` | `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, `aria-orientation` |
+| `ProgressBar`, `CircularBar` | `progressbar` | `aria-valuemin`, `aria-valuemax`, `aria-valuenow`, `aria-busy` while indeterminate |
+| `Dropdown` | `combobox` | `aria-expanded`, `aria-controls`, `aria-activedescendant`, `aria-invalid`, `aria-labelledby` |
+| `Dropdown` list | `listbox` / `option` | `aria-selected` |
+| `Tabs` | `tablist` / `tab` / `tabpanel` | `aria-selected`, roving `tabIndex`, `aria-controls` |
+| `Accordion` | `button` / `region` | `aria-expanded`, `aria-controls` |
+| `Pagination` | `navigation` | `aria-current="page"` |
+| `Stepper` | — | `aria-current="step"` |
+| `BottomNavigation` | — | `aria-current="page"` |
+| `Modal`, `BottomSheet`, `Drawer` | `dialog` | `aria-modal="true"` |
+| `SnackBar` | live region | `aria-live="polite"`, `"assertive"` for error and warning |
+| `Tooltip` | `tooltip` | `aria-describedby` on the trigger while shown |
+| `Maps` | `application` | — |
+| `CircularChart` | `img` | give it an `aria-label`; it is a picture of data |
+
+Composite widgets answer the keyboard the way their ARIA pattern says: `Tabs`,
+`Dropdown`, `Rating` and `Slider` move with the arrow keys, take `Home` and
+`End`, and keep a single Tab stop per group. The Dropdown's options are
+deliberately *not* Tab stops — the selector holds focus, the arrows move the
+highlight and `aria-activedescendant` names the row.
+
+What is left for you is **naming**: a visible `label` where the widget has one
+(`Input`, `Dropdown`), `text` for a button (`"Save"` is a name; `"OK"` is not —
+see the clean-UI rule about generic action labels), `alt` on images, and
+`aria-label` for anything that has no visible words of its own.
+
+## 4. An invalid field says so in two places
+
+A red rim is the visual half. The other half is the state and the reason, and
+`Input` keeps them together: while a message is showing, the field carries
+`aria-invalid="true"` and an `aria-describedby` pointing at the message, which
+is a `polite` live region; when the value becomes valid, all three leave
+together. A described-by pointing at a `display: none` node would be a control
+claiming a description it does not have.
+
+```javascript
+const email = Input({ label: "Email", validation: "email", required: true });
+
+// submit
+const { valid, message } = email.validate(); // paints, links and announces
+```
+
+Use `validate()` (or `setValue()`, which validates) rather than colouring a rim
+by hand: `showValidationMessage` decides whether the reason is on screen, and a
+ring with no message tells a reader "wrong" and nothing else.
+
+## 5. Overlays hold the keyboard, then give it back
+
+`Modal`, `BottomSheet` and `Drawer` share one scope (`src/utils/focusScope.js`),
+and one implementation on purpose:
+
+- focus moves into the panel when it opens — the first control, or the panel
+  itself (`tabIndex="-1"`) when it has none, so an alert with two lines of text
+  still takes the keyboard;
+- Tab and Shift+Tab cycle **inside** the panel instead of walking out behind
+  the scrim into a page the person can no longer see;
+- Escape closes it (each overlay already listens);
+- closing hands focus back to whatever was focused before, and skips that if the
+  element has left the page (a route change replaced it).
+
+The trap and the ring read the same list of reachable elements — `a[href]`,
+`button`, `input`, `select`, `textarea`, `summary` and anything on the Tab path
+— so a stop you can Tab to is always a stop that shows a ring.
+
+For an app, the contract is simply: open and close these through their props and
+refs, and do not build a full-screen scrim by hand with its own Escape listener.
+
+## 6. Verify it with the keyboard
+
+Five minutes, no screen reader needed:
+
+1. Press Tab from the top of the screen. Every control gets a ring; nothing is
+   skipped and nothing rings twice.
+2. Press Enter and Space on each control. The same thing happens as with a click.
+3. Focus a field and type. The rim stays put until there is a verdict.
+4. Submit an invalid form. The message is under the field, the field says
+   `aria-invalid`, and the message disappears with the fix.
+5. Open a modal. Tab to the last control and press Tab once more: focus is back
+   at the first, not behind the scrim.
+6. Press Escape. Focus is back on whatever opened it.
+7. Repeat 1–6 with a screen reader (VoiceOver: `Cmd+F5`; TalkBack on Android) and
+   listen for names: "Search, button", "Email, invalid entry, Invalid email
+   address".
+
+Then let the gates do what they do:
+
+```bash
+npm run check    # the API is real: widgets, props, imports
+npm run ui       # names, labels, tap targets, contrast:
+                 #   UNLABELED_FIELD, UNLABELED_TOGGLE, ICON_ONLY_CONTROL,
+                 #   IMAGE_NO_ALT, SMALL_TAP_TARGET, LOW_CONTRAST*, UNREADABLE
+npm run dev      # then Tab through it; the checker has no keyboard
+```
+
+In the framework repository itself, `node scripts/check-a11y.mjs` runs inside
+`npm test` and holds the invariants of this chapter: nothing writes an inline
+`outline`; the ring rule is injected and carries the token; both palettes define
+`focusRing`; the pressable path sets role, Tab stop and Enter/Space and releases
+its listener; every overlay that reads Escape also traps focus; the trap and the
+ring agree on what is reachable; and no handler is attached after the factory
+returned. Every one of those rules has been proven to fail on the bug it
+forbids. The runtime half lives in `/tests/a11y.html`.
+
+## See also
+
+- [Clean UI](clean-ui.md) — the design rules this chapter's checklist comes from.
+- [Themes](../tools/theme.md) — `registerPalette`, the call that moves the ring.
+- [Input](../widget/Input.md) — the props used above.
+- [Modal](../widget/Modal.md) · [BottomSheet](../widget/BottomSheet.md) ·
+  [Drawer](../widget/Drawer.md) — the three overlays and what they return.
+- [Widget structure](widget-structure.md) — where a widget's defaults and
+  disposers live.
+
+---
+
+## Continue reading
+
+- **Previous:** [Clean UI](clean-ui.md) — Chapter 12
+- **Next:** [Minify and protect a FletBox build](minification-and-protection.md) — Appendix A
+- **Index:** [Guides index](README.md) · [The FletBox Book](../README.md)
+
+You are reading **Chapter 13 · Accessibility**.

package/docs/guides/clean-ui.md

@@ -5,8 +5,9 @@ defaults, and every later screen copies the screen before it. This page is the
 contract that makes the copy look like one product — the numbers, the tokens,
 and the two commands that prove a screen obeys them.
 
-It is the published version of the rule file that ships inside every generated
-app, so the app's agent and the framework's documentation cannot disagree.
+It is the published version of the `fletbox-design` skill — one of four files in
+the framework's `skills/` folder that `flet-box create` copies into every app — so
+the app's agent and the framework's documentation cannot disagree.
 
 ## The two gates
 
@@ -26,12 +27,24 @@ one replaces opening the page.
 
 ## Where the rules live
 
+A generated app is handed four skills — one file per subject, in a visible
+`skills/` folder at its root, mirrored byte for byte to `.claude/skills/` and
+`.qoder/skills/` because that is where those assistants load a skill from, and
+pointed at from one `.cursor/rules/<name>.mdc` each:
+
+| Skill | What it owns |
+| --- | --- |
+| `fletbox-rules` | The working contract: FletBox syntax only, never invent an API and the four ways to look one up, the rem rule, aliases, cleanup, the two gates, the memory duty. |
+| `fletbox-design` | The numbered rules below — tokens, the scale, hierarchy, the four states, measured contrast, composition, the framework traps, the dated tells, density (00–24), then the visual atlas of looks that hold up, each reduced to calls this framework makes (25–37). |
+| `fletbox-motion` | Whether a thing may move at all, and through which of `AnimatedBox`, `AnimatedText`, `ParallaxBox` or `animate`. |
+| `fletbox-memory` | The `.fletbox/memory/` journal that hands progress from one AI to the next. |
+
 | Home | What it holds |
 | --- | --- |
-| `.claude/skills/fletbox-clean-ui/SKILL.md` | The 21 numbered rules below, written for the agent that builds the screen. Mirrored to `.qoder/skills/…` and `.cursor/rules/fletbox-clean-ui.mdc`. |
+| `skills/fletbox-design/SKILL.md` (framework) → `skills/…`, `.claude/skills/…`, `.qoder/skills/…` (app) | The rules as the agent reads them, in 38 numbered sections across two parts. The app's copies are generated; edit the framework file and regenerate, never the mirror. |
 | `AGENTS.md` §4 of the app | The short version: one brand color per screen, no hex literals, spacing and radius only from the scale. |
 | `src/tools/scale.js` in the framework | The tables themselves — `SPACING_SCALE`, `RADIUS_SCALE`, `TYPE_SCALE`, `TAP_MINIMUM`, `PILL`, `LABEL_TEXT`. |
-| `bin/commands/checkUi.js` | The gate. It re-exports those same tables instead of keeping its own copy. |
+| `bin/commands/checkUi.js` | The gate. It re-exports those same tables instead of keeping its own copy, and `scripts/check-skills.mjs` fails when a skill and the gate stop naming the same codes. |
 
 That last line matters more than it looks. A gate that carries its own numbers
 drifts from the widgets, and the app then gets told to be clean by values the
@@ -42,7 +55,7 @@ components it uses do not follow. The defaults and the checker read one table.
 | Dimension | Allowed values |
 | --- | --- |
 | Spacing | `0 · 4 · 8 · 12 · 16 · 18 · 24 · 32 · 40 · 48 · 64 · 96` |
-| Radius | `0 · 4 · 8 · 12 · 16 · 999` — `999` is a pill, `0` a flush edge; both are decisions |
+| Radius | `0 · 4 · 8 · 12 · 16 · 20 · 24 · 999` — `999` is a pill, `0` a flush edge; both are decisions. 20 and 24 are on the scale because the nesting rule (`outer = inner + padding`) lands there and `Drawer`, `DrawerItem` and the `Tabs` indicator default there |
 | Type | `12 · 14 · 16 · 18 · 24 · 32 · 40 · 48` |
 | Tap minimum | `40` — Fitts: the smallest pressable box a finger reliably hits |
 | Label text | `14` — the reading size a control's own label may not fall under |
@@ -80,9 +93,17 @@ The framework keeps this honest with its own gate, `scripts/check-widget-scale.m
 (part of `npm test`): a length written straight to `el.style.*` that is neither
 `toREM(...)` nor measured geometry fails the build.
 
-## The 21 rules
+## The rules
+
+The skill numbers its rules 00–37 and splits them in two parts. **00–24 are the
+enforceable contract**: each one is cited by at least one `check-ui` code, so
+`npm run ui` can fail a screen for breaking it, and `scripts/check-skills.mjs`
+fails if a code loses its rule. **25–37 are the visual atlas** — the archetypes,
+the accent budget, the surfaces, the dated tells — judgement about what to
+choose, which no static pass can prove. The atlas lives only in the skill; this
+page indexes it by number and does not copy it, so the two cannot drift.
 
-When two of them conflict, take them in this order: **consistency · clarity ·
+When two rules conflict, take them in this order: **consistency · clarity ·
 accessibility · usability · scalability · maintainability · conversion**.
 
 | # | Rule | What it forbids |
@@ -104,10 +125,37 @@ accessibility · usability · scalability · maintainability · conversion**.
 | 14 | Destructive actions designed last | A delete that is the closest, fastest, most colorful thing on the screen. |
 | 15 | Reduce interaction cost | Taps, scrolls and keystrokes that carry no information. |
 | 16 | Respect the platform | Fighting the browser's own conventions — back, scroll, text selection. |
-| 17 | The review | Shipping before reading your own diff as the user. |
-| 18 | Where these books are wrong | Following a guideline that measurement disagrees with. |
-| 19 | What no checker can see | Taste, hierarchy in the wild, whether the screen solves the problem. |
-| 20 | The loop | Fixing the checker instead of the code, or leaving a rule you had to break undocumented. |
+| 17 | Composition starts as a sentence | A screen that begins as "a hero, then three cards, then a footer" instead of a decision the page carries. |
+| 18 | The framework traps | `Container` assumed invisible, a `flex: 1` with no sibling, `alignItems: "center"` mistaken for centered text, absolute coordinates where a `Stack` belongs. |
+| 19 | The dated tells | An eyebrow label, `01 · 02 · 03`, glass everywhere, resting shadows, a hairline `Divider` under every row, copy that says "seamless". |
+| 20 | Density is one dial | Two rhythms in one screen — a gap, a padding and a body size chosen three different times. |
+| 21 | The review | Shipping before reading your own diff as the user. |
+| 22 | Where these books are wrong | Following a guideline that measurement disagrees with. |
+| 23 | What no checker can see | Taste, hierarchy in the wild, whether the screen solves the problem. |
+| 24 | The loop | Fixing the checker instead of the code, or leaving a rule you had to break undocumented. |
+
+### Part II — the visual atlas, 25–37
+
+Read these after the table, never instead of it: every recipe still has to pass
+`npm run check` and `npm run ui`. They are indexed here so a rule number in a
+review comment points somewhere, and they are written out in full in
+`skills/fletbox-design/SKILL.md`.
+
+| # | Rule | What it decides |
+| --- | --- | --- |
+| 25 | Three laws | One accent, one surface family, one hero — across mobile, web, both themes. |
+| 26 | Pick an archetype | Acid-on-black, tinted paper, photo-bleed, bento, editorial, single-hue field — name one before the first widget. |
+| 27 | Surfaces are never the extremes | No pure black under pure white: the steps between them are where hierarchy lives. |
+| 28 | The accent budget | How much saturated hue a screen may spend, and on what. |
+| 29 | The number is the hero | The one element at 3–5× the rest, and why it is usually a number. |
+| 30 | Radius, nesting and the pill | `outer = inner + padding`, and when a pill is a decision. |
+| 31 | Photo, scrim, sheet | The sheet overlaps the photo, the scrim earns the text over it. |
+| 32 | The shape of each control | Which control carries which affordance, from the widgets that exist. |
+| 33 | Data widgets | The dial, the bento tile, the axis-less chart. |
+| 34 | Genre recipes | What a finance, commerce, travel or wellness screen actually uses. |
+| 35 | Deriving a palette | Building a hue family from one accent without leaving contrast behind. |
+| 36 | The dated visual tells | What reads as 2021, and what to choose instead. |
+| 37 | Choosing, in five questions | How to land on an archetype and a palette for a brief. |
 
 ## What `flet-box check-ui` proves
 
@@ -123,12 +171,12 @@ judging yours. Each finding carries a code, and the code maps to a rule above.
 | `OFF_SCALE_SPACING` | 07 | A padding, margin, gap or size off the spacing scale — including inside a `"12px 20px"` shorthand. |
 | `OFF_SCALE_RADIUS` | 03 | A corner radius that is not a scale step. |
 | `OFF_SCALE_TYPE` | 08 | A font size off the type scale. |
-| `SMALL_TAP_TARGET` | 11 | A pressable widget under the Fitts floor, including a bare `Icon` with `onPress`. |
+| `SMALL_TAP_TARGET` | 03 | A pressable widget under the Fitts floor, including a bare `Icon` with `onPress`. The floor is a scale value, so rule 03 owns it. |
 | `LOW_CONTRAST` | 11 | Text measured below AA against the fill it actually sits on. |
 | `UNLABELED_FIELD` | 13 | An `Input` or `Dropdown` with neither a `label` nor a `placeholder`. |
-| `UNLABELED_TOGGLE` | 13 | A `Switch`, `Checkbox` or `Radio` with nothing to say what it toggles. |
+| `UNLABELED_TOGGLE` | 11 | A `Switch`, `Checkbox` or `Radio` with nothing to say what it toggles. |
 | `DESTRUCTIVE_COLOR` | 14 | A delete/remove verb rendered in the brand fill instead of the danger one. |
-| `UNREADABLE` | — | A file the scanner could not parse, reported rather than skipped. |
+| `UNREADABLE` | 00 | A file the scanner could not parse, reported rather than skipped — and nothing else in that file was judged. |
 
 ### Warnings (fail with `--strict`)
 
@@ -140,20 +188,20 @@ judging yours. Each finding carries a code, and the code maps to a rule above.
 | `HAND_MIXED_COLOR` | 03 | `colors.primary + "22"` — a one-off shade no other screen can reuse. |
 | `DEAD_ELEVATION` | 10 | A numeric `elevation` on a widget that never reads it: CSS drops the bare number and the box stays flat in silence. |
 | `IMAGE_NO_ALT` | 11 | An `Image` with no `alt` — `alt: ""` is a decision, a missing prop is an oversight. |
-| `ICON_ONLY_CONTROL` | 15 | A pressable glyph with no name; wrap it in `Tooltip({ text, child })`. |
+| `ICON_ONLY_CONTROL` | 11 | A pressable glyph with no accessible name; give it `aria-label` (a `Tooltip` is a description, not a name). |
 | `CENTERED_BODY_TEXT` | 08 | A paragraph centered; a paragraph needs a left edge to find the next line. |
-| `GENERIC_ACTION_LABEL` | 06 | "OK", "Submit", "Click here" — a label that says nothing about what pressing it does. |
+| `GENERIC_ACTION_LABEL` | 14 | "OK", "Submit", "Click here" — a label that says nothing about what pressing it does. |
 | `CONFIRM_ORDER` | 14 | A destructive button placed before Cancel in the same row. |
-| `UNCONSTRAINED_FORM_WIDTH` | 08 | A form block whose fields run to the full width of a desktop window. |
+| `UNCONSTRAINED_FORM_WIDTH` | 13 | A form block whose fields run to the full width of a desktop window. |
 
 ### Informational
 
 | Code | Rule | What it says |
 | --- | --- | --- |
-| `SMALL_PRESET` | 11 | `size: "small"` on a control that is the screen's main action (~30px). |
+| `SMALL_PRESET` | 03 | `size: "small"` on a control that is the screen's main action (~30px). |
 | `CROWDED_FORM` | 06 | Many fields in one file: group them, or split the task. |
 | `LIST_WITHOUT_STATE` | 12 | A list with no loading, empty or failed state in this file. |
-| `MULTIPLE_PRIMARY_ACTIONS` | 04 | Several filled buttons on one screen. |
+| `MULTIPLE_PRIMARY_ACTIONS` | 04 | More than one filled button in one view; keep one and make the rest outlined or text. |
 
 ## Running the gate
 
@@ -186,11 +234,26 @@ agent, will otherwise copy the exception as if it were the rule.
 And a rule you had to break is information about the rule: if the exception was
 right twice, it is a defect in the scale, not in the app.
 
+## The framework runs this gate on itself
+
+A widget cannot ship a default that the gate would reject in your app, because
+`npm test` runs the same checker over the framework's `src/`
+(`scripts/check-framework-ui.mjs`). It found real defects the first time: a tab
+badge wrote white on the signal red (2.77:1 in the dark theme), a `ListTile`
+description borrowed the disabled grey (2.57:1), a dialog painted two filled
+buttons at once, and eleven defaults sat off the scale.
+
+The list of accepted findings lives in `scripts/framework-ui-baseline.json` and
+is shrink-only: every entry carries the reason it is not a defect, and
+`--write-baseline` exits `1` while any entry has no justification. A new finding
+has to be fixed, not snapshotted.
+
 ## What no checker can see
 
 `check-ui` has no eyes. It cannot tell you that the screen is ugly, that the
 hierarchy reads wrong at a glance, or that the flow does not solve the user's
-problem. Those are rules 17 and 19, and they are the ones that need a person.
+problem. Those are rules 17, 19, 21 and 23 — composition, the tells, the review
+and this section — and they are the ones that need a person.
 Run the gate, then open the page.
 
 ## Related pages
@@ -205,7 +268,7 @@ Run the gate, then open the page.
 ## Continue reading
 
 - **Previous:** [The CLI](../cli/README.md) — Chapter 11
-- **Next:** [Minify and protect a FletBox build](minification-and-protection.md) — Appendix A
+- **Next:** [Accessibility](accessibility.md) — Chapter 13
 - **Index:** [Guides index](README.md) · [The FletBox Book](../README.md)
 
 You are reading **Chapter 12 · Clean UI**.

package/docs/guides/minification-and-protection.md

@@ -255,6 +255,6 @@ Minification reduces the web payload inside the native application. It does not
 
 ## Continue reading
 
-- **Previous:** [Clean UI](clean-ui.md) — Chapter 12
+- **Previous:** [Accessibility](accessibility.md) — Chapter 13
 - **Next:** [Build FletBox for mobile and other platforms](mobile-and-platforms.md) — Appendix B
 - **Index:** [Guides index](README.md) · [The FletBox Book](../README.md)

package/docs/guides/mobile-and-platforms.md

@@ -75,6 +75,44 @@ Your Capacitor configuration must point `webDir` to that output directory, commo
 
 The exact configuration file may be `capacitor.config.ts`, `capacitor.config.json`, or another format depending on how Capacitor was initialized.
 
+### The safe area
+
+Every app `flet-box create` writes carries `viewport-fit=cover` in `index.html`,
+which lets the web view paint behind the notch and the home indicator. That is
+what a full-bleed app wants, but it only looks right if content steps back from
+those edges, so the framework reads `env(safe-area-inset-*)` wherever a widget
+touches a screen edge: the [AppBar](../widget/AppBar.md) adds the top inset to
+its own padding, the [Drawer](../widget/Drawer.md) pads its panel and the
+[Tooltip](../widget/Tooltip.md) measures the same box before it picks the side
+its bubble goes on, so a header never sits under the status bar, a footer never
+under the gesture bar and a tooltip never flips into either. The
+value is `0` on a device with no inset, so nothing is configured per platform and
+a desktop browser is untouched.
+
+A screen that pins its own content to an edge — a hand-built tab bar, a floating
+action row — has to ask for the same inset. A length prop accepts the expression
+as it stands, because only a value made purely of pixels is converted to rem:
+
+```js
+Container({
+  paddingBottom: "calc(16px + env(safe-area-inset-bottom, 0px))",
+  children: [/* tabs */],
+});
+```
+
+### Hover does not exist here
+
+A touch screen has no resting pointer, and iOS answers the first tap on an
+element with a synthetic `mouseenter` that no `mouseleave` ever follows. So a
+hover-only affordance on a phone is one that appears and then cannot be
+dismissed, which is why [Tooltip](../widget/Tooltip.md) binds its hover path only
+when `matchMedia("(hover: hover)")` matches and stays reachable through keyboard
+focus everywhere else. The same test is the one to copy for a custom hover card,
+peek row or mouse-following cursor: gate it on the media query, and give the
+information a home the finger can reach — the control's own label, a
+[SnackBar](../widget/SnackBar.md), or a
+[BottomSheet](../widget/BottomSheet.md).
+
 ## Install Capacitor
 
 ```bash
@@ -225,6 +263,19 @@ Both platforms serve the app from a local HTTPS origin
 `capacitor.config.json`. A remote API has to allow that origin in its CORS
 configuration.
 
+### Text fields do not zoom the page
+
+iOS magnifies the whole viewport when a text control whose computed font size is
+under 16px receives focus, which reads as the screen growing and staying
+deformed after you type. FletBox floors the field text at 16px on iOS only: a
+`medium` or `small` field renders slightly larger there, while its box, label
+and icons keep the design's sizes. A reader who raises the browser font still
+gets a larger field, because the floor bounds the field's rem value instead of
+replacing it.
+
+Nothing has to be configured in the app, and the viewport is left alone: adding
+`maximum-scale=1` would stop the zoom by also blocking pinch-to-zoom.
+
 ### Add iOS to the project
 
 ```bash