flet-box 1.0.7 → 1.0.8

package/docs/README.md

@@ -14,6 +14,7 @@ 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 |
 | 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.
@@ -50,6 +51,7 @@ Front cover (this page)
 → Animation helpers · tools/animation.md
 → Utilities guide · guides/utilities.md
 → The CLI · cli/README.md
+→ Clean UI · guides/clean-ui.md
 → Appendices (minification → mobile → compatibility → embedding → online updates)
 → The end of the book
 ```

package/docs/cli/README.md

@@ -62,6 +62,33 @@ http://localhost:8000
 
 The default project includes screens, an app bar, a drawer, routing, and the files needed to start experimenting.
 
+### Pointing the project at its repository
+
+`flet-box create` writes a GitHub Pages workflow into every project. Pass the
+repository with `--repo` and the same address is filled in everywhere it is
+needed:
+
+```bash
+flet-box create my-app --repo kuko53348/my-app
+```
+
+That sets `update.url` in `fletbox.config.json` (what an installed app polls for
+an over-the-air update), names the site at the top of
+`.github/workflows/build.yml`, and prints the address in the closing summary:
+
+```text
+⬆️  OTA updates: https://kuko53348.github.io/my-app/
+CI:      .github/workflows/build.yml publishes the web to GitHub Pages on every push.
+         It goes live at: https://kuko53348.github.io/my-app/
+         Enable it once: Settings → Pages → Source: GitHub Actions. The job prints the URL.
+```
+
+The first positional argument is always the project name; a flag that arrives
+before it is read as the name. Without `--repo` nothing is invented — the
+placeholder stays in both files and the workflow says which two to edit. The
+reason the workflow log, not the header, is the authority on the live address is
+explained in [The Pages address of a generated app](../guides/online-updates.md).
+
 ## Project templates
 
 FletBox provides four project templates.
@@ -500,6 +527,36 @@ command converts it anyway and says so in the report: keep the JPEG — or a Web
 from a tool that carries a codec — for that picture, and let `to-png` do the flat
 art, the logos and the icons.
 
+## Check the UI
+
+`flet-box check-ui` reads your app's own `src/` and reports the design mistakes a
+static pass can prove: a hand-typed color literal instead of a token, a size that
+is not on the 8-based scale, a tap target below the Fitts floor, a form field with
+no label, and text whose contrast against the fill it sits on is below WCAG AA.
+
+```bash
+flet-box check-ui                  # scan ./src
+flet-box check-ui --root ../my-app # scan another project
+flet-box check-ui --tokens         # print the measured token contrast table
+flet-box check-ui --strict         # contrast warnings fail too
+flet-box check-ui --json           # machine-readable findings
+```
+
+Aliases: `flet-box ui`, `flet-box checkUi`. The command exits `1` when it finds an
+error, or when it finds a warning with `--strict`, so it works as a CI gate.
+
+Every prop name the checker uses comes from the installed package's own prop
+registry, so it cannot invent an API while judging yours. The scale, the radii and
+the tap minimum are the framework's own numbers, read from its `scale` module —
+the same table the widget defaults are drawn from.
+
+What it deliberately does not judge: taste, hierarchy, and whether the screen
+solves the user's problem. `flet-box create` writes the rules as a skill file
+alongside the app, and that file says so.
+
+The full contract — the 21 rules, every finding code, and how to fix one — is
+[Chapter 12, Clean UI](../guides/clean-ui.md).
+
 ## Command reference
 
 
@@ -510,6 +567,7 @@ art, the logos and the icons.
 | `flet-box create <name> --full` | Creates a project with drawer and bottom navigation. |
 | `flet-box create <name> --sidebar` | Creates a desktop sidebar project. |
 | `flet-box create <name> --adaptive` | Creates a mobile and desktop project. |
+| `flet-box create <name> --repo <user>/<repo>` | Sets the GitHub Pages address, the OTA URL and the workflow header from the repo. |
 | `flet-box screen <name>` | Creates one screen. |
 | `flet-box screen <number>` | Creates up to ten screens. |
 | `flet-box component <name>` | Creates one component. |
@@ -529,6 +587,9 @@ art, the logos and the icons.
 | `flet-box to-png --dry-run` | Reports what would happen, writes nothing. |
 | `flet-box to-png --replace` | Deletes each source after its PNG was written and read back. |
 | `flet-box to-png --optimize` | Re-packs the PNGs already in the folder, and only when that makes them smaller. |
+| `flet-box check-ui` | Runs the clean-UI gate over `src/`: tokens, scale, tap targets, labels, contrast. |
+| `flet-box check-ui --tokens` | Prints the measured contrast of every color token, on the background and on the surface. |
+| `flet-box check-ui --strict` | Makes the contrast warnings fail the run, not just the errors. |
 | `flet-box pkg` | Opens the package manager. |
 | `flet-box --version` | Shows the CLI version. |
 | `flet-box --help` | Shows the command list. |
@@ -618,7 +679,7 @@ npm install --save-dev esbuild
 ## Continue reading
 
 - **Previous:** [FletBox utilities](../guides/utilities.md)
-- **Next:** [Minify and protect a FletBox build](../guides/minification-and-protection.md) — Appendix A
+- **Next:** [Clean UI](../guides/clean-ui.md) — Chapter 12
 - **Index:** [Guides index](../guides/README.md) · [The FletBox Book](../README.md)
 
 You are reading **Chapter 11 · The CLI**.

package/docs/guides/README.md

@@ -9,6 +9,8 @@ This directory is the **conceptual index** of FletBox: how to build apps, set up
 - **[Routing with FletBox](router.md)** — Chapter 9 · fixed paths, dynamic parameters, queries, history, and route subscriptions.
 - **[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.
 - **[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/clean-ui.md

@@ -0,0 +1,211 @@
+# Clean UI — the system contract
+
+A FletBox screen is not decorated, it is extended: every app copies the widget
+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.
+
+## The two gates
+
+A generated project has two checks, and they answer different questions:
+
+```bash
+npm run check      # is the API real? widgets, props, imports
+npm run ui         # does the screen follow these rules?
+npm run ui -- --tokens   # measured contrast of every token, on both surfaces
+npm run dev        # then look at it: the checker has no eyes
+```
+
+`npm run check` (`flet-box check-api`) is about correctness — an invented prop
+fails the build. `npm run ui` (`flet-box check-ui`) is about the system — a
+`padding: 21` is valid JavaScript and a design defect at the same time. Neither
+one replaces opening the page.
+
+## Where the rules live
+
+| 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`. |
+| `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. |
+
+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
+components it uses do not follow. The defaults and the checker read one table.
+
+## The scale
+
+| 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 |
+| 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 |
+
+Type steps are two apart on purpose: a 15 next to a 16 reads as a mistake, not
+as hierarchy. The same logic gives the scale its gaps — a value between two
+steps is a shape no other element in the app has.
+
+## Every number is a framework unit
+
+A number on a size prop is not a CSS pixel. It goes through `toREM`
+(`src/utils/units.js`) and reaches the page as `value / 16` rem, so `40` is 40px
+at the default base and 60px for a reader who raised their browser font to 24.
+That is what makes one build fit a phone, a tablet and a desktop, and it is why
+the Fitts floor here is 40 rem-units rather than the 44px the guidelines quote:
+a target written in rem obeys the accessibility setting, a fixed pixel shrinks
+in relative terms the moment the type grows.
+
+`toREM` also rewrites a length someone spelled out in pixels — `"8px 12px"`
+becomes `"0.5rem 0.75rem"` — while anything that is not made only of pixel
+tokens (`"50%"`, `"calc(100% - 8px)"`, `"2px solid red"`) passes through
+untouched.
+
+Pixels stay pixels where a pixel is the honest unit:
+
+- canvas backing stores (`QRCode`, `Chart`, `CircularBar`, `CircularChart`),
+- Maps' projected tile and pin space,
+- anything measured from the DOM (`offsetWidth`, `getBoundingClientRect`, scroll offsets),
+- the hairline `borderWidth`, and shadow depth (`SHADOW_LEVELS`), because a
+  shadow that scales with the font stops matching the surface it lifts,
+- a virtualised row's scroll math — `ListView` converts `itemSize + gap` through
+  the live root font size so the slot a row gets and the row's own box agree.
+
+The framework keeps this honest with its own gate, `scripts/check-widget-scale.mjs`
+(part of `npm test`): a length written straight to `el.style.*` that is neither
+`toREM(...)` nor measured geometry fails the build.
+
+## The 21 rules
+
+When two of them conflict, take them in this order: **consistency · clarity ·
+accessibility · usability · scalability · maintainability · conversion**.
+
+| # | Rule | What it forbids |
+| --- | --- | --- |
+| 00 | The two gates | Shipping a screen neither `check` nor `ui` has run against. |
+| 01 | System before component | Deciding a value case by case; define the token, then the component, then the screen. |
+| 02 | Consistency is sacred | An arbitrary difference — a second card radius, a second button height. |
+| 03 | Design tokens only | A hex literal, a `px` string, a value off the scale. |
+| 04 | Hierarchy in three seconds | More than one primary action competing on a screen. |
+| 05 | One purpose per screen | A screen that needs "and" to describe it. |
+| 06 | Reduce cognitive load | Choices with no default, fields that could be inferred, copy that explains the interface. |
+| 07 | Spacing communicates relationship | Related things sitting farther apart than unrelated ones. |
+| 08 | Typography is structure | More than one size per element, body copy centered, a line that runs past ~75 characters. |
+| 09 | Color carries meaning | Brand color used for decoration, or a destructive action in the same fill as a safe one. |
+| 10 | Depth is a scale | An `elevation` number on a widget that never reads it, or a hand-typed `boxShadow`. |
+| 11 | Accessibility is a floor | Text under WCAG AA contrast, a tap target under 40, an image with no `alt` decision. |
+| 12 | Every interaction has four states | A control or list with no loading, empty, error or success path. |
+| 13 | Forms prevent the error | Validation that only reports after a failed submit; an unlabeled field or toggle. |
+| 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. |
+
+## What `flet-box check-ui` proves
+
+The gate reads your `src/` and reports what a static pass can prove. Prop names
+come from the installed package's own registry, so it cannot invent an API while
+judging yours. Each finding carries a code, and the code maps to a rule above.
+
+### Errors (exit 1)
+
+| Code | Rule | What it catches |
+| --- | --- | --- |
+| `RAW_COLOR` | 03 | A color literal on a widget outside `src/database/themes.js`. |
+| `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`. |
+| `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. |
+| `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. |
+
+### Warnings (fail with `--strict`)
+
+| Code | Rule | What it catches |
+| --- | --- | --- |
+| `LOW_CONTRAST_SOFT` | 11 | Text that clears AA only because of its size. |
+| `LOW_CONTRAST_UI` | 11 | A graphic that carries meaning below 3:1. |
+| `LOW_CONTRAST_ON_SURFACE` | 11 | Text measured against `background` and `surface` at once, when the fill is inherited. |
+| `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 })`. |
+| `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. |
+| `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. |
+
+### Informational
+
+| Code | Rule | What it says |
+| --- | --- | --- |
+| `SMALL_PRESET` | 11 | `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. |
+
+## Running the gate
+
+```bash
+flet-box check-ui                 # scan ./src
+flet-box check-ui --root ../my-app  # scan another project
+flet-box check-ui --tokens        # print the measured token contrast table
+flet-box check-ui --strict        # warnings fail too
+flet-box check-ui --json          # machine-readable findings
+```
+
+Aliases: `flet-box ui`, `flet-box checkUi`. Exit code is `1` when an error is
+present (or a warning, with `--strict`), so it fits in CI as the app's
+`npm run ui`.
+
+`--tokens` is the one worth reading before you pick colors. It prints the
+measured ratio of every token against `background` and `surface` — for the
+palette in use, so switch the theme and read it again if you ship both. A brand
+color that looks fine and measures 2.15:1 (`colors.warning`, decoration only)
+becomes a number instead of an argument, and the table already tells you which
+tokens clear AA body text, which are large-text-or-UI only, and on which fill
+writing text is a mistake.
+
+## Fixing a finding
+
+Fix the code, not the checker. A finding you keep needs one sentence of
+justification — in the commit or in the file — because the next person, human or
+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.
+
+## 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.
+Run the gate, then open the page.
+
+## Related pages
+
+- [FletBox utilities](utilities.md) — the theme and layout helpers the tokens come from.
+- [Themes](../tools/theme.md) — `registerPalette`, the call that gets your brand onto the page.
+- [The CLI](../cli/README.md) — every command, including `check-api` and `unpack`.
+- [Widget structure](widget-structure.md) — how a widget is built, and where its defaults live.
+
+---
+
+## Continue reading
+
+- **Previous:** [The CLI](../cli/README.md) — Chapter 11
+- **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 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:** [The FletBox CLI](../cli/README.md)
+- **Previous:** [Clean UI](clean-ui.md) — Chapter 12
 - **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/online-updates.md

@@ -136,6 +136,54 @@ To configure it by hand, create `fletbox.config.json`:
 }
 ```
 
+## The Pages address of a generated app
+
+The URL you paste into `update.url` is not a guess: `flet-box create` knows the
+address the app will be published to and prints it when it finishes.
+
+```bash
+flet-box create my-app --repo kuko53348/my-app
+```
+
+That `--repo` (or the same value typed at the interactive prompt) does three
+things at once:
+
+- sets `update.url` in `fletbox.config.json` to `https://kuko53348.github.io/my-app/`;
+- writes that address into the header of the generated `.github/workflows/build.yml`;
+- prints it in the closing summary, with the one-time setting Pages needs.
+
+Without `--repo` nothing is invented. `fletbox.config.json` keeps the generic
+placeholder `https://TU-USUARIO.github.io/TU-REPO/`, the workflow header names a
+guess built from the folder name, and the workflow says so in its own comment:
+write the real address in both files that state it.
+
+**The workflow log is the authority.** The header names the address you typed at
+scaffold time; the `Where this lives` step prints the address the run *actually*
+belongs to, read from GitHub itself:
+
+```text
+site:    https://kuko53348.github.io/my-app/     <- from the running repo
+header:  https://TU-USUARIO.github.io/my-app/    <- from the file
+version: 1.0.3
+```
+
+When those two disagree, trust `site:`. They disagree when the repository was
+created with a different name than the folder, or when the app was never pushed.
+Note the owner is lower-cased: GitHub Pages serves the site under the
+lower-cased login, so `Kuko53348` in your remote is `kuko53348` in the URL.
+
+**A green run that 404s has one cause.** The deploy job can only write to Pages
+after you enable the destination once: **Settings → Pages → Build and deployment
+→ Source: GitHub Actions**. Until you do, every run succeeds and no site exists —
+which is exactly what the `Where this lives` step prints in the log, so a failed
+release is never mistaken for a broken bundle.
+
+The address is a **sub-path** (`/<repo>/`), and that is why the bundle uses
+relative asset paths: the same `www/` a phone polls for updates is the one served
+under any path, with no rebuild for a custom domain or a rename. If you do move to
+a custom domain, change `update.url` in `fletbox.config.json` and rebuild — the
+native shell keeps the old bundle until the manifest tells it otherwise.
+
 ## Shipping extra files (release assets)
 
 OTA swaps **one file**: `src/app.js`. Anything your app reads from disk at runtime — markdown pages, JSON data, per-tenant config — keeps the copy baked into the build the device installed. So an app installed three releases ago can run a bundle that was updated over the air and still be missing files the current catalog refers to. The symptom is not a crash, it is a "this page does not exist" for content that clearly exists online.

package/docs/tools/README.md

@@ -98,7 +98,7 @@ Helpers for shaping collections and generating data.
 
 - `parseMarkdown(md)`, `parseInlineMarkdown(md)` — reserved placeholders that pass text through unchanged (real rendering is `markdownToWidgets`/`parseInlineToWidgets`).
 - `markdownToWidgets(md)` / `parseMarkdownToWidgets(md)` — markdown string → widgets (alias names for the same function).
-- `tokenize(code)`, `generateHighlightedHtml(code)`, `highlightColors` — syntax highlighting.
+- `tokenize(code)`, `generateHighlightedHtml(code, palette?)`, `highlightColors` — syntax highlighting (light and dark token maps; the highlighter picks one from the active theme).
 - `escapeHtml(text)` — escape untrusted text before inserting it as HTML.
 
 ## Visual effects

package/docs/tools/animation.md

@@ -31,7 +31,7 @@ one style would otherwise fight, and the older animation would resume after the
 
 ## Widgets
 
-- `AnimatedBox({ animations, timing, delay, fillMode, child, top, right, bottom, left })` — animates a child widget. `animations` is an array of `{ effect, from, to, duration }` entries; effects include `backgroundColor`, `color`, `borderRadius`, `opacity`, `scale`, `translate`, `rotate`, `width`, `height`, spacing, `boxShadow`, and gradients.
+- `AnimatedBox({ animations, timing, delay, fillMode, child, top, right, bottom, left })` — animates a child widget. `animations` is an array of `{ effect, from, to, duration }` entries; each plays once and holds `to` at the end (add `reverse: true` to cycle back, and `loop: true` to repeat); effects include `backgroundColor`, `color`, `borderRadius`, `opacity`, `scale`, `translate`, `rotate`, `width`, `height`, spacing, `boxShadow`, and gradients.
 - `AnimatedText({ child, animations, sameTime, delayBetween, orientation })` — animates a `Text` widget (letters split per animation).
 - `MatrixRain({ chars, fontSize, speed, fadeAmount, resetProbability, useDynamicColor, position, zIndex })` — the falling-characters canvas effect (returns a `canvas`).
 - `ParallaxBox({ type, speed, direction, maxOffset, reverse, child })` — content that moves; `type` is `"scroll"`, `"mouse"`, or `"hover"`, `direction` is `"vertical"`, `"horizontal"`, or `"both"`.

package/docs/tools/markdown.md

@@ -24,9 +24,9 @@ import { parseMarkdown, markdownToWidgets, escapeHtml } from "flet-box";
 | `parseMarkdown` | `parseMarkdown(text)` | `string` | Reserved API: currently returns the input unchanged. Use `markdownToWidgets`. |
 | `parseInlineMarkdown` | `parseInlineMarkdown(text)` | `string` | Reserved API: currently returns the input unchanged. Use `parseInlineToWidgets`. |
 | `tokenize` | `tokenize(code)` | `{ type, value }[]` | Split code into token objects. |
-| `generateHighlightedHtml` | `generateHighlightedHtml(code)` | `string` | Code → highlighted HTML. |
+| `generateHighlightedHtml` | `generateHighlightedHtml(code, palette?)` | `string` | Code → highlighted HTML. Picks the light or dark token map automatically; pass a map to override. |
 | `escapeHtml` | `escapeHtml(text)` | `string` | Escape `<`, `>`, `&`, quotes so text is safe as HTML. |
-| `highlightColors` | const | `Record<string, string>` | The token color map used by the highlighter. |
+| `highlightColors` | const | `Record<string, string>` | The dark-theme token map (One Dark scale). |
 
 `markdownToWidgets` options: `{ codeMaxHeight?: number, codeFontSize?: number }`.
 
@@ -61,7 +61,7 @@ const safe = escapeHtml(userInput); // safe to put into innerHTML
 - `markdownToWidgets` builds real widget elements (headings, paragraphs, code blocks, lists) that you can place inside any container — this is what the `Markdown` widget uses.
 - `parseMarkdown` and `parseInlineMarkdown` are reserved placeholders that currently pass text through unchanged; the widget rendering is `markdownToWidgets`/`parseInlineToWidgets`.
 - `escapeHtml` should be used for **any** text you insert into the DOM that you did not write yourself. Never trust raw input.
-- `tokenize` returns flat token objects and is the base for custom highlighters; `highlightColors` lets you theme them.
+- `tokenize` returns flat token objects and is the base for custom highlighters; `generateHighlightedHtml` reads the active theme, and its second argument accepts a token map when you paint your own surface.
 
 ## Related pages
 - [Themes](theme.md) — previous chapter.

package/docs/tools/theme.md

@@ -11,7 +11,7 @@ FletBox ships a built-in color system: `colors` is the palette of the current th
 ## Import
 
 ```javascript
-import { colors, setTheme, toggleTheme, subscribeTheme, ThemeProvider } from "flet-box";
+import { colors, setTheme, registerPalette, toggleTheme, subscribeTheme, ThemeProvider } from "flet-box";
 ```
 
 ## Functions
@@ -19,6 +19,7 @@ import { colors, setTheme, toggleTheme, subscribeTheme, ThemeProvider } from "fl
 | Function | Signature | Returns | Description |
 | --- | --- | --- | --- |
 | `setTheme` | `setTheme('light' \| 'dark')` | `Record<string, string>` | Switch the active palette. |
+| `registerPalette` | `registerPalette(themeName, palette)` | `Record<string, string>` | Merge brand tokens into a named palette and repaint the page. |
 | `getTheme` | `getTheme()` | `string` | The active theme name. |
 | `toggleTheme` | `toggleTheme()` | `string` | Flip light/dark and return the new name. |
 | `getColor` | `getColor(name, opacity?)` | `string` | Resolve a token (optionally with alpha). |
@@ -38,9 +39,47 @@ Every token is available on `colors`:
 - **Surfaces:** `background`, `surface`, `card`, `overlay`.
 - **Text:** `text`, `textSecondary`, `textDisabled`, `divider`, `border`, `shadow`.
 - **Tints:** `gray50` … `gray900`, plus the soft backgrounds `errorBg`, `successBg`, `warningBg`, `infoBg`.
+- **Glass:** `glass` (the translucent surface) and `glassBorder` (its rim), meant to pair with `backdropFilter`. Light is white glass, dark is a slate pane with a light rim.
 
 The `dark` palette overrides the surface/text tokens; `gray*` and brand colors also shift to keep contrast. Read [the palette walkthrough](../guides/utilities.md) for usage patterns.
 
+## Brand colors: `registerPalette`
+
+A generated app ships a `src/database/themes.js` with its own `lightColors` and
+`darkColors` objects. Assigning onto `colors` from that file changes nothing:
+every widget reads the framework's live `colors`, and the next theme switch
+re-applies a registered palette over whatever you wrote there. The call that
+reaches the page is `registerPalette`:
+
+```javascript
+import { registerPalette } from "flet-box";
+import { lightColors, darkColors } from "./database/themes.js";
+
+registerPalette("light", lightColors);
+registerPalette("dark", darkColors);
+```
+
+What it does:
+
+- **Merges**, it does not replace. Tokens you leave out keep the framework's
+  value, so a palette that only carries `primary` and `surface` stays legal.
+- **Repaints when that palette is on screen.** If the name matches the active
+  theme the tokens are applied, the `--color-*` custom properties are rewritten,
+  and theme subscribers are notified. Registering the other theme only stores it
+  for the next `setTheme`.
+- **Never writes the theme preference.** Supplying your brand is not the user
+  choosing light or dark; that is the one difference from `setTheme`.
+- **A token the framework has never heard of is added to `colors`**, so
+  `colors.brandSand` resolves in your own code. Widgets will still not use it —
+  they read the tokens they know — and because the built-in palettes do not
+  carry it, a custom key keeps its registered value across a theme switch unless
+  you register it in both palettes.
+
+Run it once, at startup, before the first screen renders. The generated app does
+it at the bottom of `src/database/themes.js` — the same file that declares
+`lightColors` and `darkColors` — so a project that edits its brand colors is
+already correct without touching `src/app.js`.
+
 ## Examples
 
 ### Everyday example
@@ -83,6 +122,7 @@ runApp(ThemeProvider({ children: ThemedApp() }), "root");
 ## Notes
 
 - The shared palette tokens are updated across all widgets when you switch themes; widgets referencing `colors.*` at build time pick up the active palette.
+- `colors.glass` is genuinely see-through: its contrast depends on whatever is behind it, so use it over photography or gradients with a scrim, and keep body copy off the most colourful part of the backdrop. The dark token is a dark pane, not white glass.
 - `watchSystemTheme()` and `applySystemTheme()` read `prefers-color-scheme`; both return/need cleanup to release listeners.
 - `subscribeTheme(callback)` fires with the new palette object — remember to unsubscribe when a feature is destroyed.
 

package/docs/widget/Accordion.md

@@ -63,6 +63,9 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/AdMob.md

@@ -31,7 +31,7 @@ const banner = AdMob({
 | `margin` | `number` | Space outside the widget, between it and its neighbors. |
 | `interstitialId` | `string` | AdMob interstitial ad unit id. |
 | `rewardedId` | `string` | AdMob rewarded ad unit id. |
-| `autoShow` | `boolean` | Shows the ad automatically when it is ready. |
+| `autoShow` | `boolean` | Shows the banner automatically on mount. false silences only the mount; show() still asks for the ad. |
 | `autoInitialize` | `boolean` | The `autoInitialize` value for the widget. |
 | `width` | `Size` | Width of the widget. A number is pixels; a string uses any CSS unit. |
 | `height` | `Size` | Height of the widget. A number is pixels; a string uses any CSS unit. |
@@ -62,6 +62,9 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/AdSense.md

@@ -56,6 +56,9 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/AnimatedBox.md

@@ -50,6 +50,9 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |
@@ -96,9 +99,9 @@ const toast = AnimatedBox({
 ## Tips
 
 - Each animation is { effect, from, to } where effect is a CSS property like opacity,
-- scale, translateY, or backgroundColor.
-- Set timing (ease, ease-out, linear) and delay at the widget level; per-step reverse
-- cycles the animation back instead of running it once.
+- scale, translateY, or backgroundColor. It runs once and holds `to` at the end.
+- Set timing (ease, ease-out, linear) and delay at the widget level; add reverse: true
+- to cycle back to `from`, together with loop: true for a breathing pulse.
 - top, right, bottom, and left are forwarded to the child as positioning hints for
 - layout systems.
 

package/docs/widget/AnimatedText.md

@@ -46,6 +46,9 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/Audio.md

@@ -53,6 +53,9 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/Avatar.md

@@ -50,6 +50,9 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/Badge.md

@@ -52,6 +52,9 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |

package/docs/widget/Button.md

@@ -59,6 +59,9 @@ Every widget also accepts these shared props — see [common props](COMMON_PROPS
 | `borderRadius` | `number \| string` | Rounds the corners of the widget. |
 | `elevation` | `number` | Shadow depth. Higher values lift the widget off the page. |
 | `shadow` | `string` | Raw CSS `box-shadow` value, for a custom shadow. |
+| `filter` | `string` | Raw CSS `filter` value applied to the widget itself, e.g. `blur(4px)`. |
+| `backdropFilter` | `string` | Raw CSS `backdrop-filter` value: what sits behind the widget is blurred through it, which is what makes a translucent card frosted glass. |
+| `maskImage` | `string` | Raw CSS `mask-image` value, used to fade a widget out at its edges instead of cutting it. |
 | `opacity` | `number` | Opacity from 0 (invisible) to 1 (fully opaque). |
 | `visible` | `boolean` | Whether the widget is rendered and visible. |
 | `disabled` | `boolean` | Disables interaction and shows the non-interactive state. |