flet-box 1.0.8 → 1.1.0

package/bin/utils/templates.js

@@ -1,5 +1,23 @@
 // bin/utils/templates.js
 
+import * as skills from "./skills.js";
+
+/**
+ * The plate behind everything a reader sees before the app paints: the PWA
+ * splash (`manifest.json`), the Android and iOS launch screens, the adaptive
+ * icon background, and the static `<meta name="theme-color">`.
+ *
+ * It is the dark palette's `surface` — the zinc scale the 2026-10 design rebuild
+ * moved to, replacing the indigo shell color that stayed in the scaffold and kept
+ * showing on installed PWAs long after the app itself had changed color. One
+ * value because a native splash cannot follow a theme; `applyPalette()` writes
+ * the live palette onto `<meta name="theme-color">` at runtime, so the bars do.
+ */
+export const SHELL_BRAND = "#18181b";
+
+/** `SHELL_BRAND` as the channels the icon and splash scripts composite with. */
+export const SHELL_BRAND_RGB = { r: 24, g: 24, b: 27 };
+
 export const indexHtml = (appName = "FletBox App") => `<!DOCTYPE html>
 <html lang="en">
 <head>
@@ -19,7 +37,7 @@ export const indexHtml = (appName = "FletBox App") => `<!DOCTYPE html>
     <meta property="og:description" content="${appName} built with Flet-Box.">
     <meta property="og:type" content="website">
 
-    <meta name="theme-color" content="#1a1a2e">
+    <meta name="theme-color" content="${SHELL_BRAND}">
 
     <!-- ============================================================
          GOOGLE ADSENSE (optional — disabled by default)
@@ -904,7 +922,7 @@ export const capacitorConfig = (appName, appId) => `${JSON.stringify(
     appId,
     appName,
     webDir: "www",
-    backgroundColor: "#1a1a2e",
+    backgroundColor: SHELL_BRAND,
     server: { androidScheme: "https", iosScheme: "https" },
   },
   null,
@@ -960,7 +978,7 @@ const densities = [
   ["xxhdpi", 144],
   ["xxxhdpi", 192],
 ];
-const background = { r: 26, g: 26, b: 46 };
+const background = { r: ${SHELL_BRAND_RGB.r}, g: ${SHELL_BRAND_RGB.g}, b: ${SHELL_BRAND_RGB.b} };
 
 for (const [density, size] of densities) {
   const directory = path.join(androidRes, \`mipmap-\${density}\`);
@@ -998,7 +1016,7 @@ const backgroundColor = /(<color name="ic_launcher_background">)#(?:[A-Fa-f0-9]{
 if (!backgroundColor.test(xml)) {
   throw new Error(\`Invalid adaptive icon background resource: \${backgroundPath}\`);
 }
-await writeFile(backgroundPath, xml.replace(backgroundColor, "$1#1a1a2e$2"));
+await writeFile(backgroundPath, xml.replace(backgroundColor, "$1${SHELL_BRAND}$2"));
 
 // SPLASH SCREENS
 // The launch theme (AppTheme.NoActionBarLaunch) shows @drawable/splash while the
@@ -1066,8 +1084,8 @@ const infoPlistPath = path.join(nativeAppDir, "Info.plist");
 const launchScreenPath = path.join(nativeAppDir, "Base.lproj", "LaunchScreen.storyboard");
 const logoPath = path.join(projectRoot, "assets", "logo.png");
 
-// Brand background, the same #1a1a2e as theme-color in index.html and manifest.json.
-const background = { r: 26, g: 26, b: 46 };
+// Brand background, the same value as theme-color in index.html and manifest.json.
+const background = { r: ${SHELL_BRAND_RGB.r}, g: ${SHELL_BRAND_RGB.g}, b: ${SHELL_BRAND_RGB.b} };
 const backgroundComponent = (value) => Number((value / 255).toFixed(6));
 
 const requireExists = async (target) => {
@@ -1245,8 +1263,8 @@ export const manifest = (appName = "FletBox App") => `{
   "scope": "./",
   "display": "standalone",
   "display_override": ["window-controls-overlay"],
-  "theme_color": "#1a1a2e",
-  "background_color": "#1a1a2e",
+  "theme_color": "${SHELL_BRAND}",
+  "background_color": "${SHELL_BRAND}",
   "orientation": "any",
   "icons": [
     {
@@ -1653,10 +1671,13 @@ framework from scratch:
 
 - \`AGENTS.md\` — the rules: FletBox syntax only, real widgets and props only, and the
   verification loop it must run after every edit.
-- \`.claude/skills/fletbox-clean-ui/SKILL.md\` — the design rules themselves, numbered
-  00 to 20 and measured: which token, which step of the scale, which contrast. The
-  same text is at \`.qoder/skills/fletbox-clean-ui/SKILL.md\` and as a Cursor rule in
-  \`.cursor/rules/fletbox-clean-ui.mdc\`.
+- \`skills/\` — four files, one per subject, mirrored into \`.claude/skills/\`,
+  \`.qoder/skills/\` and \`.cursor/rules/\` so any assistant reads the same contract:
+  \`fletbox-rules\` (FletBox only, look an API up before using it, the rem contract),
+  \`fletbox-design\` (the numbered design rules — tokens, the scale, hierarchy, the
+  four states, measured contrast, the dated tells), \`fletbox-motion\` (when a screen
+  may move and through which widget) and \`fletbox-memory\` (the journal that hands
+  progress from one AI to the next). \`AGENTS.md\` §0 is the index.
 - \`.claude/CLAUDE.md\`, \`.cursor/rules/fletbox.mdc\` — short pointers to \`AGENTS.md\` for
   Claude Code and Cursor.
 - \`.fletbox/api/cheatsheet.md\` — every widget and its real props, generated from the
@@ -1739,7 +1760,7 @@ run \`npm run ios:open\`.
 
 Replace \`assets/logo.png\` with a 1024×1024 logo before distributing; the icon,
 the launch images and the launch background are all generated from it. The
-launch background is the app brand color \`#1a1a2e\`, which lives in
+launch background is the app brand color \`${SHELL_BRAND}\`, which lives in
 \`scripts/sync-ios-assets.mjs\`.
 
 Capacitor uses a local HTTPS origin (\`https://localhost\`) in the Android and
@@ -2417,6 +2438,26 @@ export const agentsMd = (appName, template, version) =>
     'fixes every size and color you may use, and the checker in section 5',
     'proves you right or wrong in seconds.',
     '',
+    '## 0. Start here — the skills folder',
+    '',
+    'Everything this framework knows about building a professional screen is grouped',
+    'in four files under `skills/`, one per subject. They are copied byte-for-byte',
+    'into `.claude/skills/` and `.qoder/skills/` so those assistants load them',
+    'automatically, and into `.cursor/rules/` as pointer rules — `skills/` is the',
+    'text, the rest are mirrors of it. Open the file your task touches before',
+    'writing code, not after:',
+    '',
+    '| Skill | What it owns | Read it when |',
+    '| --- | --- | --- |',
+    '| [fletbox-rules](skills/fletbox-rules/SKILL.md) | FletBox syntax only: no widget or prop from React, Vue, Svelte or Flutter; look an API up before using it; the rem contract; aliases; cleanup; the two gates | always, first |',
+    '| [fletbox-design](skills/fletbox-design/SKILL.md) | the numbered design rules — tokens, the scale, hierarchy, the four states, measured contrast, the framework traps, the dated tells, density | any screen, form, list, dialog or hero |',
+    '| [fletbox-motion](skills/fletbox-motion/SKILL.md) | whether a thing may move at all, and through which of `AnimatedBox`, `AnimatedText`, `ParallaxBox` or `animate` | any transition, entrance, pulse or parallax |',
+    '| [fletbox-memory](skills/fletbox-memory/SKILL.md) | the journal that hands progress from one AI to the next | at the start and at the end of every session |',
+    '',
+    'Sections 1 to 7 below are the short version of those files, kept here because a',
+    'session that stops reading early still gets the rules that break the build. When',
+    'a summary here and a skill disagree, the skill is the longer argument and wins.',
+    '',
     '## 1. The API is a fact, not a guess',
     '',
     'Never invent a widget, prop, hook or helper. Look it up:',
@@ -2618,7 +2659,7 @@ export const agentsMd = (appName, template, version) =>
     'warning is allowed to stay only when you can justify it in one sentence.',
     '',
     '`npm run ui` proves what is *written*; the rules it cites are the numbered ones',
-    'in [.claude/skills/fletbox-clean-ui/SKILL.md](.claude/skills/fletbox-clean-ui/SKILL.md),',
+    'in [skills/fletbox-design/SKILL.md](skills/fletbox-design/SKILL.md),',
     'and that file is the part a checker cannot do — hierarchy, copy, whether the',
     'screen solves the problem. Read it before writing a screen, not after.',
     '',
@@ -2631,12 +2672,14 @@ export const agentsMd = (appName, template, version) =>
     '',
     '## 6. Memory — do not relearn the same thing',
     '',
-    'At the start of every session read `.fletbox/memory/MEMORY.md` and any entry it',
-    'points at. That is how this agent remembers the framework between chats instead',
-    'of rediscovering it each time.',
+    'The full format lives in [skills/fletbox-memory/SKILL.md](skills/fletbox-memory/SKILL.md).',
+    'The short version: at the start of every session read',
+    '`.fletbox/memory/MEMORY.md` and the entries it points at, including',
+    '`notes/current-status.md`. That is how this agent remembers the app between',
+    'chats — and between models — instead of rediscovering it each time.',
     '',
     '- When you learn something non-obvious about this app or the framework, write',
-    '  `.fletbox/memory/<kebab-case-topic>.md` with: what (fact or rule), **Why:**',
+    '  `.fletbox/memory/notes/<kebab-case-topic>.md` with: what (fact or rule), **Why:**',
     '  (the incident or constraint behind it), **How to apply:** (when it kicks in),',
     '  and an absolute date for anything time-bound.',
     '- Add a one-line pointer to it in `MEMORY.md`. Keep the index short.',
@@ -2669,7 +2712,7 @@ export const claudeMd = () =>
   [
     '# CLAUDE.md',
     '',
-    'The rules for this project live in [AGENTS.md](./AGENTS.md). Read it first and',
+    'The rules for this project live in [AGENTS.md](../AGENTS.md). Read it first and',
     'follow it exactly — FletBox syntax only, real props only.',
     '',
     'Two shortcuts replace guessing:',
@@ -2679,8 +2722,12 @@ export const claudeMd = () =>
     '  `--diff` lists the props that are documented but dead or used but undeclared.',
     '  `.fletbox/api/api.json` is the same surface for all widgets, as data.',
     '- Design is not improvised. The rules are a file: read',
-    '  [skills/fletbox-clean-ui/SKILL.md](skills/fletbox-clean-ui/SKILL.md) before',
-    '  writing a screen. `npm run ui` proves the part a checker can prove (tokens,',
+    '  [skills/fletbox-design/SKILL.md](skills/fletbox-design/SKILL.md) before writing',
+    '  a screen (the same text is mirrored to `.claude/skills/` and `.qoder/skills/`,',
+    '  so those loaders find it by themselves). The set is four files: `fletbox-rules`',
+    '  for the API contract, `fletbox-design` for the screen, `fletbox-motion` before',
+    '  anything moves, `fletbox-memory` for the journal.',
+    '  `npm run ui` proves the part a checker can prove (tokens,',
     '  the scale, 40px targets, labels, contrast) and cites the rule number it',
     '  broke; AGENTS.md §4 has the tables. Scale: 4 · 8 · 12 · 16 · 18 · 24 · 32 ·',
     '  40 · 48 · 64 · 96 spacing, radii 4/8/12/16/999, type 12 · 14 · 16 · 18 · 24',
@@ -2689,8 +2736,9 @@ export const claudeMd = () =>
     'After every edit: `npm run check` (does it exist), `npm run ui` (is it clean),',
     'then look at the screen — the checker has no eyes.',
     '',
-    'Memory: read `.fletbox/memory/MEMORY.md` before working, and write new entries',
-    'there when you learn something the next session should not rediscover.',
+    'Memory: read `.fletbox/memory/MEMORY.md` and `notes/current-status.md` before',
+    'working, and write what you learn there — `fletbox-memory` is the format — when',
+    'the next session should not have to rediscover it.',
     '',
   ].join('\n');
 
@@ -2711,8 +2759,8 @@ export const cursorRules = () =>
     '  `.fletbox/api/cheatsheet.md`, look it up: `flet-box unpack <Widget>` (or',
     '  `npm run check -- --props <Widget>`). If it is not listed, it does not exist —',
     '  do not invent it. `unpack --example` prints a call that is safe to paste.',
-    '- Design rules: read [fletbox-clean-ui.mdc](./fletbox-clean-ui.mdc) in this',
-    '  folder — the numbered clean-UI rules the agent is expected to follow. One',
+    '- Design rules: read [fletbox-design.mdc](./fletbox-design.mdc) in this',
+    '  folder — the numbered design rules the agent is expected to follow. One',
     '  brand color per screen, taken from the `colors` tokens — never a hex literal.',
     '  Sizes come from the scale only: 4 · 8 · 12 · 16 · 18 · 24 · 32 · 40 · 48 · 64',
     '  · 96 spacing, radii 4/8/12/16/999, type 12 · 14 · 16 · 18 · 24 · 32 · 40 · 48.',
@@ -2725,6 +2773,45 @@ export const cursorRules = () =>
     '',
   ].join('\n');
 
+/**
+ * The handover note every session rewrites instead of appending to. It ships
+ * filled with the scaffold's own state, so the first real session has the shape
+ * to copy, and `fletbox-memory` owns the rules for keeping it honest.
+ *
+ * @param {string} appName
+ * @param {string} template
+ * @returns {string}
+ */
+export const memoryStatusMd = (appName, template) => {
+  const today = new Date().toISOString().slice(0, 10);
+  return [
+    '# Status',
+    '',
+    'The handover file. Rewrite these lines as you work; do not append to them.',
+    'Whoever opens this next may be a different model with no memory of this',
+    'session, so "done" has to mean "verified" and "next" has to be a sentence,',
+    'not a mood.',
+    '',
+    `**Doing:** nothing yet. This is the fresh \`${template}\` scaffold of \`${appName}\`.`,
+    '',
+    '**Done and verified:** the app boots and both gates pass on the template as',
+    'created — `npm run check` (only real APIs) and `npm run ui` (tokens, the scale,',
+    'tap targets, labels, contrast). That is the baseline; anything under it is',
+    "whatever the next session changed.",
+    '',
+    '**Not done / half-done:** the screens and copy are the demo the template ships',
+    'with. They are placeholders until a real screen replaces them.',
+    '',
+    '**Next:** write one sentence about what this app is for, then delete the demo',
+    'screens it does not need.',
+    '',
+    '**Blocked:** none. Put the question to ask here the moment one exists.',
+    '',
+    `**Updated:** ${today} · scaffold.`,
+    '',
+  ].join('\n');
+};
+
 export const memoryIndexMd = (appName) =>
   [
     '# Memory index',
@@ -2732,6 +2819,7 @@ export const memoryIndexMd = (appName) =>
     `Persistent notes for the AI agent working on \`${appName}\`. One line per entry.`,
     'Read this at the start of every session; open the files it points at.',
     '',
+    '- [Current status](notes/current-status.md) — what is built now, what is verified, what is next: the handover between AIs',
     '- [Project baseline](notes/baseline.md) — template, flet-box version, verified commands',
     '',
   ].join('\n');
@@ -2805,500 +2893,44 @@ export const checkAppScript = (appName) =>
   ].join('\n');
 
 // ---------------------------------------------------------------------------
-// Clean-UI skill
+// Skills
 // ---------------------------------------------------------------------------
-// The design-system contract, merged from two sources and then measured against
-// this framework: Angelene Wallis, "No bullshit guide to UX" (2022), and "The UI/
-// UX Playbook" (uxpeak, 144 pages). Every number is either one the books state or
-// one read off the installed palette; every prop named here exists in the API the
-// app is generated with. The rules are numbered so `flet-box check-ui` can cite
-// them, and so the agent can quote one back when it breaks one on purpose.
-//
-// Two halves, always kept in agreement: what the checker proves statically, and
-// what only a person can see. The skill names both so the agent never claims the
-// checker covers more than it does.
-export const cleanUiSkill = () =>
+// The text lives in the package-root skills/ folder, one kebab-case directory per
+// subject (rules, design, motion, memory) with a SKILL.md inside. A real file keeps
+// the contract editable, diffable, and checkable by scripts/check-skills.mjs, which
+// proves every widget and prop a skill names actually exists. The design rules come
+// from Angelene Wallis, "No bullshit guide to UX" (2022), and "The UI/UX Playbook"
+// (uxpeak), measured against this framework: every number is read off the installed
+// palette or src/tools/scale.js, and they are numbered so `flet-box check-ui` can
+// cite the one it broke.
+
+/**
+ * Cursor has no skills folder, so every skill also ships as a pointer rule: its own
+ * frontmatter description as the trigger, and the path an agent must open. One text,
+ * three loaders, never three edits — and no summary that can drift from the skill.
+ *
+ * @param {string} name kebab-case skill folder name
+ * @param {{alwaysApply?: boolean, globs?: string}} [options]
+ * @returns {string}
+ */
+export const skillCursorRule = (name, options = {}) =>
   [
     "---",
-    "name: fletbox-clean-ui",
-    "description: Design-system contract for a FletBox app - tokens only, one scale, three-tier hierarchy, a state for every interaction, measured contrast, destructive actions designed last. Use when creating, editing or reviewing any screen, form, list, dialog or action control.",
+    `description: ${skills.skillDescription(name).split(" - ")[0]}`,
+    `globs: ${JSON.stringify(options.globs || "src/**/*.js")}`,
+    `alwaysApply: ${options.alwaysApply ? "true" : "false"}`,
     "---",
     "",
-    "# Clean UI — the system rules",
-    "",
-    "You are not decorating screens. You are extending a system that every later",
-    "screen will copy. A decision that cannot be restated as a rule is a defect, not",
-    "a style.",
-    "",
-    "When two goals conflict, take them in this order:",
-    "",
-    "1 Consistency · 2 Clarity · 3 Accessibility · 4 Usability · 5 Scalability",
-    "· 6 Maintainability · 7 Conversion",
-    "",
-    "Never optimize for aesthetics alone. Beauty is what is left when the system is",
-    "correct; it is an outcome, never a target you can hit directly.",
-    "",
-    "## 00 The two gates",
-    "",
-    "```bash",
-    "npm run check      # the API is real: widgets, props, imports",
-    "npm run ui         # the screen follows these rules (codes map to rule numbers)",
-    "npm run ui -- --tokens   # measured contrast of every token, on both surfaces",
-    "npm run dev        # then look at it: the checker has no eyes",
-    "```",
-    "",
-    "A finding you keep needs one sentence of justification, in the commit or in",
-    "`.fletbox/memory/`. If that sentence is \"the design wants it\", the design is",
-    "what needs writing down, because the next screen will copy it.",
-    "",
-    "Sources, cited as `NBG p.N` (No bullshit guide to UX) and `Playbook p.N`",
-    "(The UI/UX Playbook; the PDF page — the printed folio is one lower). Every",
-    "number below is either stated by one of them or measured on this palette.",
-    "Every prop in every call below exists in `.fletbox/api/api.json`.",
-    "",
-    "## 01 System before component",
-    "",
-    "Define the token, then the component, then the screen. In that order, always.",
-    "Components are outputs; the system is the source of truth.",
-    "",
-    "- A screen that needs a value the system does not have adds a token to",
-    "  `src/database/themes.js`. It does not write the value inline.",
-    "- A component that needs a special exception: challenge the exception first, and",
-    "  if it survives, change its siblings too. Two components solving one problem",
-    "  differently get unified, not documented.",
-    "- If you cannot say which rule a decision follows, do not make it.",
-    "",
-    "## 02 Consistency is sacred",
-    "",
-    "No arbitrary differences. If a person learns one pattern here, they must not",
-    "relearn it anywhere else (Playbook p.038).",
-    "",
-    "- One button scheme for the whole app: the primary is `variant: \"filled\"`, the",
-    "  secondary `variant: \"outlined\"`, the tertiary `variant: \"text\"`. Never a",
-    "  per-card button color chosen to match the picture — people then wonder whether",
-    "  each button does something different (p.040-041).",
-    "  A filled `Button` defaults to `bgColor: colors.surface` with `colors.text` on",
-    "  it, so the primary action must name the brand pair: `bgColor: colors.primary`",
-    "  and `color: colors.onPrimary`. An outlined one must name its border (`color:`),",
-    "  or it inherits the surface it sits on and disappears.",
-    "- One radius language per screen. A rounded picture next to a square button reads",
-    "  as two products (p.039).",
-    "- One icon family, one weight, one size per screen. The one allowed mix is state:",
-    "  a selected tab filled, unselected tabs outlined (p.045-046).",
-    "- Cards in the same row share a height. When the copy is uncontrollable, fix the",
-    "  height and bottom-align the action; the empty space goes in the middle",
-    "  (p.043-044).",
-    "- Same purpose, same shape: identical inputs get the same `height`,",
-    "  `borderRadius`, states and validation behavior (rule 13).",
-    "- Images inside a repeated card sit in the same slot, same size, same crop",
-    "  (`fit`, `shape`), whatever the picture is (p.042).",
-    "",
-    "## 03 Design tokens only",
-    "",
-    "No arbitrary values, no hex, no `px` strings. Every value comes from the scale.",
-    "",
-    "```",
-    "space    4 · 8 · 12 · 16 · 18 · 24 · 32 · 40 · 48 · 64 · 96",
-    "radius   4 · 8 · 12 · 16 · 999 (pill)",
-    "type     12 caption · 14 body-small · 16 body · 18 subtitle · 24 title",
-    "         32 headline · 40 display-sm · 48 display",
-    "weight   400 body · 500 label · 600 title · 700 headline",
-    "line     1.5-1.6 body · 1.2-1.3 heading",
-    "depth    elevation 0 · 1 · 2 · 3 · 4 · 5",
-    "```",
-    "",
-    "- The base unit is 4 and everything is a multiple of it (Playbook p.028). A value",
-    "  like 13, 19, 21 or 31 is not a design decision, it is drift.",
-    "- Never type a hex or `rgb()` outside `src/database/themes.js`",
-    "  (`RAW_COLOR`). If a token is missing, add it there.",
-    "- Never build a color by appending alpha to a token — `colors.primary + \"15\"` is",
-    "  a one-off shade the rest of the app cannot reuse (`HAND_MIXED_COLOR`). The",
-    "  tints exist: `colors.primaryBg`, `colors.errorBg`, `colors.successBg`,",
-    "  `colors.warningBg`, `colors.infoBg`.",
-    "- A frosted surface is `colors.glass` with `colors.glassBorder` and a",
-    "  `backdropFilter`; it is translucent on purpose, so put it over imagery,",
-    "  not over body text. A hand-written `rgba()` is a `RAW_COLOR` like any other.",
-    "- Text on a brand fill is `colors.onPrimary`, never a literal white.",
-    "- Tap targets are at least 40 on a side (`SMALL_TAP_TARGET`). Reach it with",
-    "  `height`, not with padding. The books argue this qualitatively (Fitts, p.099);",
-    "  40 is the floor this system enforces and 44 is what a phone primary action",
-    "  gets.",
-    "- `size: \"small\"` on a `Button` is for dense secondary actions, never for the one",
-    "  thing a phone screen asks for.",
-    "",
-    "## 04 Hierarchy must be obvious in three seconds",
-    "",
-    "A person must answer three questions without reading: what is this, what",
-    "matters, what happens next. There are exactly four levers — size, color, weight,",
-    "position (Playbook p.007). If everything is emphasized, nothing is.",
+    `Read [skills/${name}/SKILL.md](../../skills/${name}/SKILL.md) before the work it`,
+    "describes. The same bytes sit at `.claude/skills/…` and `.qoder/skills/…` so the",
+    "loaders find them automatically, and that mirror is generated — edit the file",
+    "above and regenerate, never the copy.",
     "",
-    "- One primary action per screen. One secondary. Everything else is tertiary.",
-    "  Never two filled buttons on one view (`MULTIPLE_PRIMARY_ACTIONS`).",
-    "- Actions rank by emphasis, information ranks by size: the secondary button keeps",
-    "  the same `height` as the primary and loses color (p.008); the data gets the",
-    "  size ladder (p.088). That is how p.008 and p.088 stop contradicting each other.",
-    "- In a stat card the value is the largest and darkest text and the label is",
-    "  smaller and muted. Never the inverse (p.010).",
-    "- Darkness means importance: heading darker than body, body muted. Never let a",
-    "  thumbnail outsize the price (p.009, p.011).",
-    "- Never render a detail panel as uniform label:value rows — it has no hierarchy",
-    "  and cannot be scanned. Promote the one value that matters, demote the rest,",
-    "  add an icon per row (p.012).",
-    "- Before building, list the elements and rank them by user importance; then map",
-    "  size, color, weight and position onto that ranking (p.010).",
+    "A summary of the skill here would only drift, so this rule is only a pointer.",
     "",
-    "## 05 One purpose per screen",
+    "Never invent a widget or prop: `flet-box unpack <Widget>` prints the real ones.",
     "",
-    "Write the sentence first: \"this screen lets <who> do <what>\". If it needs an",
-    "\"and\", split the screen (NBG pp.40-43).",
-    "",
-    "- Conflicting goals reduce usability. A task screen carries nothing that does not",
-    "  serve the task: no promo panel, no second call to action (Playbook p.127).",
-    "- Decorative imagery next to a form is allowed only when it is action-free — no",
-    "  text overlay, no button — and it still has to be about this product, not merely",
-    "  pretty (p.128).",
-    "- Navigation exposes what the job needs and nothing else. Every extra link is a",
-    "  decision taken before the user made theirs.",
-    "",
-    "## 06 Reduce cognitive load",
-    "",
-    "People recognize; they must never memorize, guess or interpret.",
-    "",
-    "- Chunk to about four items per group and cap a visible group at 7; past that,",
-    "  truncate and expose one action — \"Show all 21 amenities\" (Playbook p.101).",
-    "  The 7±2 figure is a myth in its loosest form; plan on four and the group still",
-    "  holds when someone adds a fifth.",
-    "- Recognition over recall: common icons, common words, state visible on screen",
-    "  rather than in memory (p.104). \"Continue watching\" beats \"remember where you",
-    "  stopped\".",
-    "- Do not hide choices behind a control that must be opened to be seen: variants",
-    "  as swatches, quantity as a stepper, not a nested menu (p.107-108).",
-    "- Never oversimplify into vagueness either: a switch with an icon and no words is",
-    "  not clean, it is unreadable (p.014).",
-    "- If no user has shown they need a feature, remove it rather than park it behind",
-    "  a toggle (NBG p.136).",
-    "",
-    "## 07 Spacing communicates the relationship",
-    "",
-    "Whitespace is functional, not decorative. Related things sit closer than",
-    "unrelated things, and that difference is the whole message (Playbook p.013, p.029).",
-    "",
-    "- Field pattern: label to its own input `12`, that field to the next label `32`.",
-    "  Equal spacing at both levels makes label ownership ambiguous (p.013).",
-    "- Card padding is `16`; the rhythm between cards is `16` or `24`; sections",
-    "  separate at `24` or `32`; page blocks at `48`. Never mix two rhythms in one list.",
-    "- Start a layout with more room than you think you need and tighten it; clutter",
-    "  is easier to see than cramp is to undo (p.025-027).",
-    "- Do not stretch a form or a checkout to the viewport. 1440 is a canvas size, not",
-    "  a target; give the card the width it needs and let the margin carry the rest",
-    "  (p.129-130). `Container({ maxWidth: 480 })` around a form, `fullWidth: true`",
-    "  only on the button inside it.",
-    "- Layout is `useState` bindings, `flex`, `gap` and `wrap`. An absolute offset is",
-    "  for overlays, and then through `stackPosition`, not raw coordinates.",
-    "",
-    "## 08 Typography is structure",
-    "",
-    "- Body is `size: 16` (Playbook p.090). Nothing that must be read goes below 12;",
-    "  the book contradicts itself between 12 (p.090) and 10 (p.096) — 12 is the floor",
-    "  here.",
-    "- Heading: bigger, heavier, darker, tighter. Body: smaller, regular, muted,",
-    "  looser. Never the same weight for both, never extra-light for body (p.084-087).",
-    "- Line-height: 1.5-1.6 on body, 1.2-1.3 on headings; a 32px heading sits at about",
-    "  1.25 (p.091-092). A heading never gets more air than a paragraph.",
-    "- Measure: 45-75 characters per line on desktop, 30-40 on mobile. A paragraph",
-    "  that runs the full width is unreadable at 1440 (p.076-078).",
-    "- One typeface; two at the absolute maximum, and then headings against body",
-    "  (p.075-076). Declare it once in the theme, never per `Text`.",
-    "- `align: \"left\"` for every run of text and every list. `right` for numbers and",
-    "  prices, so magnitudes compare. `center` only for a short title or a lone CTA,",
-    "  never for a paragraph (p.018, p.094).",
-    "- Long copy becomes scannable copy: a short lead, a heading, then one item per",
-    "  feature with an icon, a bold name and two lines of body; four or more items go",
-    "  in a two-column grid (p.123-125).",
-    "",
-    "## 09 Color carries meaning",
-    "",
-    "- One brand color per screen, and it is the color of the one action the screen",
-    "  asks for. A second accent on the same view means one of them is wrong.",
-    "- Reserve the brand for things you can click. Headers, labels and icons stay",
-    "  neutral — brand color on a decorative surface teaches people that color means",
-    "  nothing (Playbook p.066-067).",
-    "- Backgrounds are neutral (`colors.background`, `colors.surface`, `colors.card`);",
-    "  color belongs in the action, not the wall (p.067-068). A dark theme is equally",
-    "  valid; offer both, because dark mode is expected, not a bonus (p.070).",
-    "- Feedback colors are fixed and never redefined: `colors.success`,",
-    "  `colors.warning`, `colors.danger`, `colors.info`. Red is error, green is",
-    "  success, amber is warning; never pink for success, never green for delete.",
-    "- The signal red and the readable red are different tokens. `colors.danger`",
-    "  (#ef4444) is for a badge, a border, an icon: as words on a white page it",
-    "  measures 3.76:1 and that is not AA. `colors.dangerStrong` (#b91c1c) is the red",
-    "  you may read and press — 6.47:1 as words on white, 6.47:1 with white written on",
-    "  it, 5.42:1 inside `colors.errorBg`. Same for the others: `colors.warning`",
-    "  (2.15:1 with white on it) and `colors.success` (2.54:1) are plates and dots,",
-    "  never a sentence — `colors.warningStrong` (5.02:1) and `colors.successStrong`",
-    "  (5.48:1) are the readable ones, in either direction. Measure any pair you are",
-    "  about to ship: `npm run ui -- --tokens`.",
-    "- Never carry meaning in color alone — a color-blind person and a phone in",
-    "  sunlight both lose it. Pair the color with an icon and a word (p.070): a status",
-    "  chip is `Badge` plus text, a field error is `error` plus `showValidationMessage`.",
-    "- Hierarchy inside a fill comes from opacity, not from a second hue.",
-    "",
-    "## 10 Depth is a scale",
-    "",
-    "- `elevation: 0-5` is the shadow scale the framework ships (`SHADOW_LEVELS`), and",
-    "  these widgets read it: `Accordion`, `AppBar`, `BottomNavigation`, `Button`,",
-    "  `Card`, `Chip`, `Drawer`, `FloatingActionButton`, `ListTile`, `Modal`, `SnackBar`.",
-    "  Elsewhere — `Container` and `ListView` included — the number reaches",
-    "  `style.boxShadow` as a bare number, CSS drops it, and the box stays flat",
-    "  without saying so: pass a `shadow: \"0 12px 32px rgba(15,23,42,0.12)\"` string",
-    "  there instead (`DEAD_ELEVATION`).",
-    "- Anything that floats gets depth: a dropdown, a menu, a modal, a card on a map.",
-    "  A shadowless layer merges with the page and the user cannot tell what is on top",
-    "  (p.050-051).",
-    "- Soft, not harsh: depth comes from a wide blur at low opacity, and the shadow",
-    "  is tinted toward the background hue, never pure grey or black (p.052-054).",
-    "- Do not put a white card on a white page — the interface goes flat. Page",
-    "  `colors.background`, card `colors.card` (p.056-057).",
-    "- Borders are thin and rare. Separation comes from space and surface, not from a",
-    "  rule under every row; a bordered list of everything reads as busy and dated",
-    "  (p.059-061).",
-    "- Glass and blur are a brand decision, and they never survive a light background:",
-    "  text on frosted glass over white loses the contrast war (p.063-065).",
-    "",
-    "## 11 Accessibility is a floor, not a feature",
-    "",
-    "When accessibility and aesthetics conflict, accessibility wins. Every time.",
-    "",
-    "- Text needs 4.5:1 against what it sits on; large text (24px, or 18px bold) and",
-    "  meaningful graphics need 3:1. Disabled text is exempt. The book agrees: its",
-    "  passing examples measure 4.8-6.54:1 and its failures 1.81-2.84:1 (p.021), and",
-    "  #626262 is the lightest grey that survives on white (p.086).",
-    "- Measure instead of arguing: `npm run ui -- --tokens`. On this palette `text` is",
-    "  17.85:1, `textSecondary` 4.76:1, `textDisabled` 2.56:1 (decoration only), and",
-    "  the brand pair `onPrimary` on `primary` is 4.55:1 — which is why `primary` may",
-    "  carry a button label and not a paragraph. By hand:",
-    "  `color(\"#0f172a\").contrastRatio(\"#ffffff\")` answers 17.85.",
-    "- Text over a photograph needs a scrim: a dark overlay or a blurred plate under",
-    "  the words. Light text over one dark photo proves nothing about the next photo",
-    "  (p.022).",
-    "- Every field has a visible `label`; a placeholder is a format hint, never a",
-    "  substitute (p.115). Every switch and checkbox has one too (`UNLABELED_TOGGLE`).",
-    "- Every control that is only an icon gets a name: wrap it in",
-    "  `Tooltip({ text, child })` or give it a visible label (`ICON_ONLY_CONTROL`).",
-    "- Every `Image` that carries information has `alt`; `alt: \"\"` is the correct",
-    "  answer for a decoration (`IMAGE_NO_ALT`).",
-    "- Focus must be visible, keyboard must reach everything, and `Esc` must close",
-    "  whatever opened (`Modal({ closeOnEsc: true, showCloseButton: true })`).",
-    "- Motion is optional content: respect a reduced-motion preference; never",
-    "  auto-play a carousel or a banner.",
-    "",
-    "## 12 Every interaction has four states",
-    "",
-    "A control that handles only the happy path is unfinished (NBG pp.94-97). Write",
-    "all four, in the same component, before the screen counts as done.",
-    "",
-    "```js",
-    "Column({ gap: 16, children: [",
-    "  loading ? Skeleton({ width: \"100%\", height: 48, count: 3 }) : null,",
-    "  !loading && rows.length === 0",
-    "    ? EmptyState()                       // headline + illustration + tip + CTA",
-    "    : null,",
-    "  failed",
-    "    ? SnackBar({ message: \"Could not load the list.\", action: \"Retry\", onAction: retry })",
-    "    : null,",
-    "  !loading && rows.length > 0 ? ListView({ children: rows }) : null,",
-    "]})",
-    "```",
-    "",
-    "- Empty has four parts: a solution-oriented headline, an illustration, two",
-    "  concrete tips, one primary action. \"You have no projects\" is a dead end, not a",
-    "  state (Playbook p.135-136).",
-    "- Loading appears before the wait, not after it: a `Skeleton` at once beats a",
-    "  spinner two seconds later (NBG p.134, Doherty).",
-    "- Error does exactly three things: says what went wrong in the user's words,",
-    "  gives the way back, keeps the visual style of the app. Show the code, keep the",
-    "  navigation, offer links (p.137-138). Never an error code alone, never a shrug.",
-    "- Success confirms in place — a `SnackBar`, not a new screen — and offers the",
-    "  next step while it is there.",
-    "- Progress is honest. Show real progress or show a `Skeleton`; a bar that lies",
-    "  buys one visit and costs the next one (NBG defends inflating them; do not).",
-    "",
-    "## 13 Forms: prevent the error, do not report it",
-    "",
-    "- Ask for 3 to 7 things at once. More than that is more than one step, and a step",
-    "  the user can see: `Stepper({ steps, activeStep, onFinish })` (NBG pp.40-43).",
-    "- Width fits the data: CVC is 3 or 4 characters, so the field is short; card",
-    "  number and name run full width; pair Expiry with CVC on one row (p.115-116).",
-    "- A column of three or more fields lives inside a cap — `Container({ maxWidth:",
-    "  480 })`. A field as wide as the window answers \"type anything\" and the eye",
-    "  loses the next line (`UNCONSTRAINED_FORM_WIDTH`).",
-    "- A fixed-length code gets one box per character in enlarged type, not one long",
-    "  field (p.114).",
-    "- `Input({ label, placeholder, required, maxLength, validation, type })`:",
-    "  placeholder carries the format (\"MM/YY\", \"12345\"), `maxLength` and `type`",
-    "  constrain the input, and validation runs inline as they type, not on submit",
-    "  (p.119).",
-    "- No \"Confirm password\" field. It adds cost, repeats the same typo twice, and",
-    "  buys a false sense of safety. One field, `passwordToggle: true`, and a strength",
-    "  line under it (p.117-119).",
-    "- Good defaults and autofill remove keystrokes: prefill the country, the saved",
-    "  address, the last card (p.105).",
-    "- Required fields are marked, and the label of the submit button names the",
-    "  outcome — \"Pay $65\", not \"Submit\" (p.115).",
-    "- Never clear a form because one field failed. Keep what they typed.",
-    "",
-    "## 14 Destructive actions are designed last, and carefully",
-    "",
-    "- The button carries the verb: \"Delete 3 files\", never \"OK\" or \"Yes\"",
-    "  (`GENERIC_ACTION_LABEL`) (Playbook p.121).",
-    "- Destructive is red — `colors.dangerStrong` for the words, `colors.danger` for",
-    "  the dot beside them — because green reads safe and a person presses it twice",
-    "  (`DESTRUCTIVE_COLOR`) (p.120). `colors.danger` alone is 3.76:1 as a label.",
-    "- Order in a two-button row: Cancel on the left, destructive on the right. Left",
-    "  is what a reading eye hits first (`CONFIRM_ORDER`) (p.121-122).",
-    "- The dialog states reversibility: \"This action cannot be undone.\" Say it even",
-    "  when it can, and then offer the way back.",
-    "- `AlertDialog({ title, message, confirmText, cancelText, showCancel, onCancel, onConfirm, onClose })`",
-    "  always leaves an escape: a Cancel, and an X on any layer that can be opened.",
-    "- Undo is cheaper than a warning. If the action is reversible, let people undo it",
-    "  instead of interrupting them to confirm it (NBG pp.116-118).",
-    "- On a phone, a destructive action is not in the thumb zone; the thing you do",
-    "  often is (p.133-135).",
-    "",
-    "## 15 Reduce interaction cost",
-    "",
-    "Interaction cost is cognitive effort + physical effort + time (Playbook p.098).",
-    "Count it, then cut it: reading, scrolling, searching, deciding, clicking, typing,",
-    "waiting, remembering (p.099).",
-    "",
-    "- Count the steps in the main flow and delete every one that does not change the",
-    "  outcome (p.105). Three is a target; one is better.",
-    "- Put the action next to the thing it acts on: the CTA beside the quantity",
-    "  stepper, the row action inside the row (p.108, Fitts).",
-    "- Keep the control that runs all the time in a fixed, reachable place — a player",
-    "  bar at the bottom, a primary tab at the thumb (p.100, p.133-135).",
-    "- Show the content instead of a door to the content: three real cards beat a",
-    "  banner that says \"Explore now\" (p.111-113).",
-    "- One click where a confirmation is not needed. Two where it is.",
-    "",
-    "## 16 Respect the platform",
-    "",
-    "- Use the words, icons and gestures people already brought with them (NBG p.131,",
-    "  Jakob's law). An invented gesture is a bug report waiting to be written.",
-    "- iOS, Android and web each have conventions; meet them instead of overriding",
-    "  them with a custom pattern. A back that lands where the user expects, a sheet",
-    "  that dismisses down, a form that advances on Enter.",
-    "- Break a convention only when the measurement says the convention is wrong here,",
-    "  and write that measurement down.",
-    "",
-    "## 17 The review",
-    "",
-    "When asked to review a screen, answer in this order, and say why every time:",
-    "",
-    "1 Goal — what the screen is for, and whether it is one goal.",
-    "2 UX problems — cost, states, recall, flow.",
-    "3 UI problems — hierarchy, spacing, type, color, depth.",
-    "4 System violations — the values that are not tokens, the component that is an",
-    "  exception.",
-    "5 Accessibility violations — measured ratios, targets, labels, focus.",
-    "6 Consistency violations — what this screen does differently for no reason.",
-    "7 Scalability risk — what breaks when this screen has eleven siblings.",
-    "8 Fix — the call, not the mood. Then the rule it establishes.",
-    "9 Score — see below.",
-    "",
-    "Score the seven axes 0-100, but only against evidence, never against taste:",
-    "an axis starts at 100 and loses 10 for every open finding of its own codes, so",
-    "the number is a count and not an opinion. Below 85 on any axis means the fix is",
-    "a rule change, not a pixel move. An axis with no findings and no evidence is",
-    "unmeasured, not perfect — say so.",
-    "",
-    "| Axis | Its codes (from `npm run ui`) |",
-    "| --- | --- |",
-    "| Consistency | OFF_SCALE_SPACING · OFF_SCALE_RADIUS · OFF_SCALE_TYPE · RAW_COLOR · HAND_MIXED_COLOR · DEAD_ELEVATION |",
-    "| Accessibility | LOW_CONTRAST · LOW_CONTRAST_UI · SMALL_TAP_TARGET · UNLABELED_FIELD · UNLABELED_TOGGLE · ICON_ONLY_CONTROL · IMAGE_NO_ALT |",
-    "| Usability | CROWDED_FORM · LIST_WITHOUT_STATE · UNCONSTRAINED_FORM_WIDTH |",
-    "| Hierarchy | MULTIPLE_PRIMARY_ACTIONS · CENTERED_BODY_TEXT · GENERIC_ACTION_LABEL · DESTRUCTIVE_COLOR · CONFIRM_ORDER |",
-    "| Scalability | every token that had to be added to make the screen pass |",
-    "| Conversion | the label of the primary action, counted in words and in steps |",
-    "| Visual quality | measured only by the axes above; state what you looked at |",
-    "",
-    "## 18 Where these books are wrong",
-    "",
-    "Both are worth more read than copied. The parts that do not survive measurement:",
-    "",
-    "- The Playbook bans pure black on white and pure white on dark (p.083). This",
-    "  system puts white text on deep brand fills, and the ratio is what decides —",
-    "  4.55:1 there, not the rule of thumb.",
-    "- p.008 says a secondary button keeps the primary's size; p.088 says size is",
-    "  the hierarchy lever. Both are right about different things: emphasis ranks",
-    "  actions, size ranks information.",
-    "- p.079 marks center-aligned body as good; p.094 says center is for titles only.",
-    "  The later rule is the readable one.",
-    "- p.103 bans pop-ups as distractions; p.120 requires one to confirm a deletion.",
-    "  Reconciled: never unsolicited, always on destructive.",
-    "- p.019 (gutter 70, margin 79, overlay 17%) and p.052-054 (Y:12, blur:48,",
-    "  #E9E9E9) are one designer's Figma fields in a screenshot, not a scale.",
-    "  Do not harvest them as thresholds.",
-    "- The Playbook's own sign-up example (p.127) is white on a pale blue fill that",
-    "  fails its own contrast chapter. Copy the rule, never the screenshot.",
-    "- \"7 ± 2\" (p.101) is Miller's number quoted loosely; chunk size is a design",
-    "  choice, and four is the one that survives a fifth item.",
-    "- NBG defends inflating progress bars (its \"little lie\"). Do not.",
-    "- Neither book states a tap-target size in px. Fitts gives the direction; 40 is",
-    "  this system's floor, and the number to defend if someone asks.",
-    "",
-    "## 19 What no checker can see",
-    "",
-    "`npm run ui` cannot tell you whether the screen is understood. For that:",
-    "",
-    "- Ask one person to do one task and stay quiet while they do it. Their first three",
-    "  sentences are the specification.",
-    "- Watch where the pointer hesitates and where it misclicks: that is where the",
-    "  layout is lying about what is tappable.",
-    "- Five people find most of what is broken. Two rounds of five beat one round of",
-    "  ten.",
-    "- Write what you saw into `.fletbox/memory/`, or the next session designs this",
-    "  screen again from taste.",
-    "",
-    "## 20 The loop",
-    "",
-    "```bash",
-    "npm run check",
-    "npm run ui",
-    "npm run dev        # look at the screen, at 375px and at 1440px",
-    "```",
-    "",
-    "Fix the code, not the checker. Then make the rule reusable: if the fix was right",
-    "for this screen, it is a rule for every screen, and it belongs in this file.",
-    "",
-  ].join('\n');
-
-// Cursor has no skills folder, so the same rules ship as one always-apply rule
-// that loads the skill file instead of duplicating it.
-export const cleanUiCursorRule = () =>
-  [
-    '---',
-    'description: Clean-UI rules for every screen - tokens, the 8-based scale, tap targets, states',
-    'globs: "src/**/*.js"',
-    'alwaysApply: true',
-    '---',
-    '',
-    'Design a screen, do not decorate one. The full rules are in',
-    '[.claude/skills/fletbox-clean-ui/SKILL.md](../../.claude/skills/fletbox-clean-ui/SKILL.md)',
-    '- read it before writing a screen, form, list or dialog.',
-    '',
-    '- One screen, one job, one primary action; secondaries are `Button({ variant: "text" })`.',
-    '- Colors come from `colors.*` only. Never a hex literal outside `src/database/themes.js`.',
-    '  `colors.onPrimary` writes on a brand fill; `colors.primaryBg` is the brand tint.',
-    '- Sizes come from the scale: 4 - 8 - 12 - 16 - 18 - 24 - 32 - 48 space, 4 / 8 / 12 / 16 /',
-    '  999 radius, 12 / 14 / 16 / 18 / 24 / 32 type.',
-    '- Anything pressable is at least 40px on a side, and 44 is the number to aim at.',
-    '- Every interaction shows loading, done, failed and empty; errors say the problem and',
-    '  the way out in the user\'s own words.',
-    '- Verify with `npm run check` then `npm run ui` (add `-- --tokens` to read the measured',
-    '  contrast table), and then look at the screen - the checker has no eyes.',
-    '',
-  ].join('\n');
+  ].join("\n");
 
 /**
  * The app-side twin of scripts/check-app.mjs for the clean-UI gate. Same