flet-box 1.0.8 → 1.1.0

package/docs/README.md

@@ -4,6 +4,8 @@ FletBox is a tiny UI framework: you describe your screen with plain JavaScript *
 
 This documentation is one continuous book. Start at **Chapter 0** and follow the "Continue reading" links at the bottom of every page; each page teaches you something real and links to the next.
 
+> **Want to see before you read?** The [live widget gallery](https://kuko53348.github.io/flet-box-widgets-exemples/) runs in the browser: one page per widget, every example rendered, with the exact call printed under it and a light/dark toggle. It is the same code the chapters describe, so it doubles as the answer to "what does this look like when it is real?".
+
 ## The reading path
 
 | # | Chapter | What you learn | Level |
@@ -14,7 +16,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 |
+| 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 |
 | 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.

package/docs/cli/README.md

@@ -448,7 +448,7 @@ Capacitor template with different slots keeps working. It:
   status bar style ignored.
 
 The script is idempotent: running it twice leaves identical files. The brand
-color `#1a1a2e` is defined at the top of the script.
+color `#18181b` is defined at the top of the script.
 
 ## Convert asset images to PNG
 

package/docs/guides/README.md

@@ -10,7 +10,9 @@ 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 25 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

@@ -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 25 numbered rules below — tokens, the scale, hierarchy, the four states, measured contrast, composition, the framework traps, the dated tells, density. |
+| `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 25 numbered sections. 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
@@ -80,7 +93,7 @@ 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 25 rules
 
 When two of them conflict, take them in this order: **consistency · clarity ·
 accessibility · usability · scalability · maintainability · conversion**.
@@ -104,10 +117,14 @@ 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. |
 
 ## What `flet-box check-ui` proves
 
@@ -123,12 +140,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,17 +157,17 @@ 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 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. |
+| `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. |
@@ -190,7 +207,8 @@ right twice, it is a defect in the scale, not in the app.
 
 `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

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

@@ -331,6 +331,37 @@ A PWA needs:
 
 PWA installation depends on browser and platform support.
 
+### The browser chrome follows the theme
+
+Once installed, Android and iOS paint two more surfaces you do not control from
+CSS: the status bar at the top and the navigation bar at the bottom. Chrome takes
+both from `<meta name="theme-color">` in the document — a value it reads once per
+page, unless the page rewrites it.
+
+FletBox rewrites it. Every `setTheme`, `registerPalette` and system-preference
+change updates that single meta tag with the live `colors.surface`, the color the
+`AppBar` and the `BottomNavigation` are painted with, so the bars meet the app
+instead of sitting against it. It also sets `color-scheme` on the root element,
+which is what tells the operating system to draw dark scrollbars, dark form
+controls and light status-bar glyphs on a dark page.
+
+That means the colors in `manifest.json` are only the **splash screen** — the
+plate shown while the app boots:
+
+```json
+{
+  "theme_color": "#18181b",
+  "background_color": "#18181b"
+}
+```
+
+Leave them at the brand color generated by `flet-box create` (the dark palette's
+surface) and let the runtime handle the rest. There is no manifest field for a
+per-theme bar color, and an installed app keeps the manifest copy it was
+installed with, so editing these two lines does not recolor a home-screen icon
+that is already there — reinstall, or let the first paint of the new version
+update the document.
+
 ## Desktop options
 
 Capacitor targets Android and iOS. For desktop packaging, consider a desktop shell such as Electron or Tauri around the same `dist` output.

package/docs/tools/theme.md

@@ -122,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.
+- Switching a theme also repaints the browser's own chrome: the `<meta name="theme-color">` the installed PWA takes for its status and navigation bars, and the root `color-scheme` that decides how the OS draws scrollbars and form controls. Both read the live palette, so an app that changes `colors.surface` changes its system bars with it — see [Mobile and platforms](../guides/mobile-and-platforms.md#the-browser-chrome-follows-the-theme).
 - `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/README.md

@@ -13,6 +13,8 @@ If you have never used FletBox, begin with [Start here](START_HERE.md), then fol
 
 Related guides: [Build your first FletBox app](../guides/app-templates.md) · [Routing with FletBox](../guides/router.md) · [FletBox CLI](../cli/README.md).
 
+Every page here has a live twin: **[the widget gallery](https://kuko53348.github.io/flet-box-widgets-exemples/)** renders each example in the browser and prints the call that made it under the result, so you can read a property table and see the same prop move something.
+
 ## The reading path
 
 ### Chapter 1 · First steps: the core mental model

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flet-box",
-  "version": "1.0.8",
+  "version": "1.1.0",
   "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-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-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:browser": "node scripts/run-browser-tests.mjs"
   },
   "keywords": [
@@ -53,6 +53,7 @@
     "bin/",
     "src/",
     "docs/",
+    "skills/",
     "README.md",
     "LICENSE"
   ],