flet-box 1.0.6 → 1.0.8

package/bin/utils/templates.js

@@ -55,7 +55,7 @@ export const indexHtml = (appName = "FletBox App") => `<!DOCTYPE html>
     <div id="root"></div>
     <script>
         if ('serviceWorker' in navigator) {
-            navigator.serviceWorker.register('/service-worker.js')
+            navigator.serviceWorker.register('./service-worker.js')
                 .then(reg => console.log('Service Worker registered', reg))
                 .catch(err => console.log('Service Worker registration error', err));
         }
@@ -64,112 +64,11 @@ export const indexHtml = (appName = "FletBox App") => `<!DOCTYPE html>
 </body>
 </html>`;
 
-export const appJs = () => `// app.js
-import { runApp, Scaffold, AppBar, BottomNavigation, colors, Icon, goTo, openDrawer } from 'flet-box';
-import { RootScreen } from './screens/RootScreen.js';
-import { HomeScreen } from './screens/HomeScreen.js';
-import { AboutScreen } from './screens/AboutScreen.js';
-import { DrawerMenu } from './components/layouts/DrawerMenu.js';
-
-// ========== CUSTOM APPBAR (commented out) ==========
-/*
-const CustomAppBar = () => {
-    return AppBar({
-        title: 'My App',
-        backgroundColor: colors.primary,
-        titleColor: '#ffffff',
-        centerTitle: true,
-        showBackButton: false,
-        leading: Icon({ 
-            name: 'menu', 
-            size: 24, 
-            color: '#ffffff',
-            onclick: () => openDrawer()
-        }),
-        actions: [
-            Icon({ name: 'search', size: 22, color: '#ffffff', onclick: () => console.log('Search') }),
-            Icon({ name: 'notifications', size: 22, color: '#ffffff', onclick: () => console.log('Notifications') })
-        ]
-    });
-};
-*/
-
-// ========== BOTTOM NAVIGATION (commented out) ==========
-/*
-const BottomNav = () => {
-    return BottomNavigation({
-        items: [
-            { icon: 'home', label: 'Home', route: '/home' },
-            { icon: 'favorite', label: 'Favorites', route: '/favorites' },
-            { icon: 'person', label: 'Profile', route: '/profile' }
-        ],
-        backgroundColor: colors.surface,
-        selectedColor: colors.primary
-    });
-};
-*/
-
-// ========== APPBAR PER ROUTE ==========
-const HomeAppBar = () => {
-    return AppBar({
-        title: 'Dashboard',
-        backgroundColor: colors.primary,
-        titleColor: '#ffffff',
-        centerTitle: true,
-        showBackButton: false,
-        leading: Icon({ 
-            name: 'menu', 
-            size: 24, 
-            color: '#ffffff',
-            onclick: () => openDrawer()
-        })
-    });
-};
-
-const AboutAppBar = () => {
-    return AppBar({
-        title: 'About',
-        backgroundColor: colors.primary,
-        titleColor: '#ffffff',
-        centerTitle: true,
-        showBackButton: true,
-        leading: Icon({ 
-            name: 'arrow_back', 
-            size: 24, 
-            color: '#ffffff',
-            onclick: () => goTo('/home')
-        })
-    });
-};
-
-// ========== ROUTES ==========
-const routes = {
-    '/': { body: RootScreen, appBar: false },
-    '/home': { body: HomeScreen, appBar: HomeAppBar() },
-    '/about': { body: AboutScreen, appBar: AboutAppBar() }
-    // Example with BottomNavigation (uncomment)
-    // '/favorites': { body: HomeScreen, appBar: HomeAppBar() },
-    // '/profile': { body: AboutScreen, appBar: AboutAppBar() }
-};
-
-const MyApp = () => {
-    return Scaffold({
-        routes: routes,
-        drawer: DrawerMenu(),
-        // bottomBar: BottomNav(),  // ← Uncomment to enable BottomNavigation
-        routerMode: 'hash',
-        backgroundColor: colors.background
-    });
-};
-
-runApp(MyApp, 'root');
-`;
-
-// The rest of the templates (rootScreenJs, homeScreenJs, aboutScreenJs, drawerMenuJs, themesJs, etc.)
-// remain the same as in your original file (they are already in English).
-// For brevity, I include them below as you already have them, but ensure no Spanish comments.
 
 export const rootScreenJs = () => `// screens/RootScreen.js
+// This screen is a reference implementation of the app's own design contract:
+// colors only from the tokens, spacing/radius/type only from the scale, one
+// filled action per screen. The gate that enforces it is 'npm run ui'.
 import { Container, Column, Text, Button, Icon, colors, goTo } from 'flet-box';
 
 export const RootScreen = () => {
@@ -177,41 +76,60 @@ export const RootScreen = () => {
         flex: 1,
         justifyContent: 'center',
         alignItems: 'center',
-        padding: 20,
+        padding: 24,
         backgroundColor: colors.background,
         child: Column({
-            gap: 28,
+            gap: 24,
             alignItems: 'center',
             children: [
                 Container({
-                    width: 80,
-                    height: 80,
-                    borderRadius: 20,
-                    backgroundColor: colors.primary + '15',
+                    width: 96,
+                    height: 96,
+                    borderRadius: 16,
+                    backgroundColor: colors.primaryBg,
                     justifyContent: 'center',
                     alignItems: 'center',
                     child: Icon({ name: 'rocket_launch', size: 48, color: colors.primary })
                 }),
-                Text({ 
-                    text: 'FletBox', 
-                    size: 36, 
-                    weight: 'bold', 
-                    color: colors.primary, 
-                    align: 'center' 
-                }),
-                Text({ 
-                    text: 'Ultra-lightweight UI framework for vanilla JavaScript', 
-                    size: 14, 
-                    color: colors.textSecondary, 
-                    align: 'center' 
+                Column({
+                    gap: 8,
+                    alignItems: 'center',
+                    children: [
+                        Text({ text: 'FletBox', size: 40, weight: 'bold', color: colors.text }),
+                        // A lead is a sentence, not a paragraph: at desktop width this
+                        // line would sit on 120 characters and no eye can track it.
+                        Text({
+                            text: 'A screen, in plain JavaScript.',
+                            size: 16,
+                            color: colors.textSecondary,
+                            align: 'center'
+                        })
+                    ]
                 }),
-                Button({ 
-                    text: 'Get Started →', 
-                    iconRight: 'arrow_forward',
-                    bgColor: colors.primary, 
-                    color: '#ffffff', 
-                    padding: '10px 28px',
-                    onPress: () => goTo('/home') 
+                Column({
+                    gap: 12,
+                    alignItems: 'stretch',
+                    maxWidth: 280,
+                    children: [
+                        // A filled Button defaults to colors.surface, not to the brand:
+                        // the primary action has to name the fill it wants.
+                        Button({
+                            text: 'See the design system',
+                            iconRight: 'arrow_forward',
+                            bgColor: colors.primary,
+                            color: colors.onPrimary,
+                            fullWidth: true,
+                            onPress: () => goTo('/home')
+                        }),
+                        // One accent per screen: everything that is not the ask is quiet.
+                        Button({
+                            text: 'Preferences',
+                            variant: 'text',
+                            color: colors.text,
+                            fullWidth: true,
+                            onPress: () => goTo('/about')
+                        })
+                    ]
                 })
             ]
         })
@@ -222,7 +140,10 @@ export default RootScreen;
 `;
 
 export const homeScreenJs = () => `// screens/HomeScreen.js
-import { Container, Column, Text, Button, Icon, colors, goTo } from 'flet-box';
+// The screen that shows what the app is built on. Every number on this page is a
+// member of the framework's own scale, so the page documents the system it uses:
+// change one to an off-scale value and 'npm run ui' reports it.
+import { Container, Column, Row, Text, Icon, Chip, colors } from 'flet-box';
 
 // ========== GOOGLE ADMOB (optional — disabled by default) ==========
 // AdMob shows native ads in Android/iOS builds. To enable it:
@@ -238,70 +159,137 @@ import { Container, Column, Text, Button, Icon, colors, goTo } from 'flet-box';
 // import { AdMob } from 'flet-box';
 // =====================================================================
 
+const SPACING_STEPS = [4, 8, 12, 16, 24, 32, 48, 64];
+
+const TYPE_STEPS = [
+    { size: 12, label: 'Caption' },
+    { size: 14, label: 'Body' },
+    { size: 18, label: 'Title' },
+    { size: 24, label: 'Headline' },
+    { size: 32, label: 'Display' }
+];
+
+// Three roles, and each one says when it is allowed on the page. A fourth would
+// be decoration looking for a reason.
+const COLOR_ROLES = [
+    { token: 'primary', text: 'Brand', note: 'the one action this screen asks for' },
+    { token: 'successStrong', text: 'Feedback', note: 'status, never ornament' },
+    { token: 'dangerStrong', text: 'Danger', note: 'the red that carries words' }
+];
+
 export const HomeScreen = () => {
     return Container({
         flex: 1,
-        justifyContent: 'center',
-        alignItems: 'center',
         padding: 24,
+        overflow: 'auto',
         backgroundColor: colors.background,
         child: Column({
-            gap: 32,
-            alignItems: 'center',
+            gap: 24,
+            // A reading column, not a full-width one: at 1400px a line of body
+            // text becomes unreadable, so the measure is capped and centred.
+            maxWidth: 640,
+            margin: '0 auto',
             children: [
-                Container({
-                    width: 96,
-                    height: 96,
-                    borderRadius: 24,
-                    backgroundColor: colors.primary + '15',
-                    justifyContent: 'center',
-                    alignItems: 'center',
-                    child: Icon({ name: 'rocket_launch', size: 56, color: colors.primary })
+                Column({
+                    gap: 8,
+                    children: [
+                        Text({ text: 'The system this app is built on', size: 32, weight: 'bold', color: colors.text }),
+                        Text({
+                            text: 'Three roles, one rhythm, one type scale. Nothing here is typed by hand.',
+                            size: 16,
+                            color: colors.textSecondary
+                        })
+                    ]
                 }),
-                Text({ 
-                    text: 'Welcome to FletBox', 
-                    size: 32, 
-                    weight: 'bold', 
-                    color: colors.text, 
-                    align: 'center' 
+                Column({
+                    gap: 12,
+                    children: [
+                        Text({ text: 'Spacing', size: 18, weight: 'bold', color: colors.text }),
+                        Row({
+                            gap: 12,
+                            alignItems: 'end',
+                            // Eight squares plus their labels need ~300 units. Without
+                            // wrapping they overflow a narrow column — a sidebar on a
+                            // small window, or this same screen beside a desktop nav.
+                            wrap: true,
+                            children: SPACING_STEPS.map((step) =>
+                                Column({
+                                    // Column is a 100%-wide block by default — the
+                                    // right answer for a page, the wrong one for eight
+                                    // cells in a row, where it makes them share the
+                                    // width out and the squares drift apart.
+                                    width: 'auto',
+                                    gap: 8,
+                                    alignItems: 'center',
+                                    children: [
+                                        Container({
+                                            width: step,
+                                            height: step,
+                                            borderRadius: 4,
+                                            backgroundColor: colors.primaryBg,
+                                            border: '1px solid ' + colors.border
+                                        }),
+                                        Text({ text: String(step), size: 12, color: colors.textSecondary })
+                                    ]
+                                })
+                            )
+                        }),
+                        Text({
+                            text: 'These are framework units, not pixels: raise the browser font size and every square, gap and corner grows with the text.',
+                            size: 14,
+                            color: colors.textSecondary
+                        })
+                    ]
                 }),
-                Text({ 
-                    text: 'Choose a section to explore:', 
-                    size: 16, 
-                    color: colors.textSecondary, 
-                    align: 'center' 
+                Column({
+                    gap: 12,
+                    children: [
+                        Text({ text: 'Type', size: 18, weight: 'bold', color: colors.text }),
+                        Column({
+                            gap: 8,
+                            children: TYPE_STEPS.map((step) =>
+                                Row({
+                                    gap: 12,
+                                    alignItems: 'center',
+                                    children: [
+                                        Text({ text: step.label, size: step.size, weight: 'bold', color: colors.text }),
+                                        Text({ text: String(step.size), size: 12, color: colors.textSecondary })
+                                    ]
+                                })
+                            )
+                        })
+                    ]
                 }),
                 Column({
                     gap: 12,
-                    alignItems: 'stretch',
-                    style: { width: '100%', maxWidth: 280 },
                     children: [
-                        Button({ 
-                            text: '🏠 Home', 
-                            iconRight: 'arrow_forward',
-                            bgColor: colors.primary, 
-                            color: '#ffffff',
-                            padding: '12px 20px',
-                            fullWidth: true,
-                            onPress: () => goTo('/home') 
-                        }),
-                        Button({ 
-                            text: 'ℹ️ About', 
-                            iconRight: 'arrow_forward',
-                            variant: 'outlined',
-                            color: colors.info,
-                            padding: '12px 20px',
-                            fullWidth: true,
-                            onPress: () => goTo('/about') 
-                        }),
-                        Button({ 
-                            text: '← Back to Root', 
-                            iconLeft: 'arrow_back',
-                            variant: 'text',
-                            color: colors.textSecondary,
-                            padding: '12px 20px',
-                            fullWidth: true,
-                            onPress: () => goTo('/') 
+                        Text({ text: 'Color roles', size: 18, weight: 'bold', color: colors.text }),
+                        Column({
+                            gap: 8,
+                            children: COLOR_ROLES.map((role) =>
+                                Row({
+                                    gap: 12,
+                                    alignItems: 'center',
+                                    padding: 12,
+                                    borderRadius: 12,
+                                    backgroundColor: colors.surface,
+                                    children: [
+                                        Icon({ name: 'palette', size: 24, color: colors[role.token] }),
+                                        Column({
+                                            gap: 4,
+                                            flex: 1,
+                                            children: [
+                                                Text({ text: role.text, size: 16, weight: 'bold', color: colors.text }),
+                                                Text({ text: role.note, size: 14, color: colors.textSecondary })
+                                            ]
+                                        }),
+                                        // The token name is the lesson; a Chip is how a
+                                        // framework value gets shown without becoming a
+                                        // colour of its own.
+                                        Chip({ label: role.token, variant: 'outlined', color: colors.textSecondary, size: 12 })
+                                    ]
+                                })
+                            )
                         })
                     ]
                 })
@@ -323,84 +311,191 @@ export default HomeScreen;
 `;
 
 export const aboutScreenJs = () => `// screens/AboutScreen.js
-import { Container, Column, Row, Text, Button, Icon, colors, goTo } from 'flet-box';
+// Preferences, written the way the rest of the app should be written: state that
+// survives a re-render, a control that names itself, validation that speaks
+// instead of disabling, and one filled button per screen.
+import {
+    Container,
+    Column,
+    Row,
+    Text,
+    Button,
+    Input,
+    Dropdown,
+    Switch,
+    Slider,
+    Divider,
+    Tooltip,
+    Icon,
+    SnackBar,
+    AlertDialog,
+    Storage,
+    colors,
+    useState,
+    setTheme,
+    getTheme,
+    setBaseFontSize,
+    getBaseFontSize
+} from 'flet-box';
+
+// Key-based RAM keeps a value across re-renders and hot reloads; localStorage is
+// what keeps a choice across sessions. A preferences screen that writes neither
+// is a form that lies, so the size is read back at boot — before the first
+// render, and before the draft below seeds itself from the live value.
+const storedSize = Storage.getData('baseFontSize');
+if (storedSize) setBaseFontSize(storedSize);
+
+const [draftSize, setDraftSize] = useState('prefFontSize', getBaseFontSize());
+
+// The destructive action is built once, at module scope. The dialog puts Cancel
+// first on its own: the way out is the first thing the eye lands on.
+const resetDialog = AlertDialog({
+    title: 'Reset the text size?',
+    message: 'It goes back to 16, the size this browser asks for.',
+    variant: 'danger',
+    confirmText: 'Reset',
+    cancelText: 'Keep it',
+    onConfirm: () => {
+        setDraftSize(16);
+        setBaseFontSize(16);
+        // Resetting is the absence of a preference, not a new one: the key goes
+        // away, so the next boot answers to the browser again.
+        Storage.deleteData('baseFontSize');
+        SnackBar({ message: 'Text size reset', type: 'success' }).show();
+    }
+});
+
+// Validation runs before the action, so the error is a message and never a
+// disabled button the user has to discover.
+const save = (name, region) => {
+    if (name.length === 0) {
+        return SnackBar({ message: 'Give the profile a name first', type: 'error' }).show();
+    }
+    const size = draftSize.valueOf();
+    setBaseFontSize(size);
+    Storage.saveData('baseFontSize', size);
+    Storage.saveData('displayName', name);
+    Storage.saveData('region', region.valueOf());
+    SnackBar({ message: 'Preferences saved', type: 'success' }).show();
+};
 
 export const AboutScreen = () => {
+    const [name, setName] = useState('prefName', Storage.getData('displayName') || '');
+    const [region, setRegion] = useState('prefRegion', Storage.getData('region') || '');
+    const isDark = getTheme() === 'dark';
+    const size = draftSize.valueOf();
+
     return Container({
         flex: 1,
-        justifyContent: 'center',
-        alignItems: 'center',
         padding: 24,
+        overflow: 'auto',
         backgroundColor: colors.background,
         child: Column({
-            gap: 32,
-            alignItems: 'center',
+            gap: 24,
+            maxWidth: 480,
+            margin: '0 auto',
             children: [
-                Container({
-                    width: 96,
-                    height: 96,
-                    borderRadius: 24,
-                    backgroundColor: colors.primary + '15',
-                    justifyContent: 'center',
-                    alignItems: 'center',
-                    child: Icon({ name: 'rocket_launch', size: 56, color: colors.primary })
+                Column({
+                    gap: 8,
+                    children: [
+                        Text({ text: 'Preferences', size: 32, weight: 'bold', color: colors.text }),
+                        Text({
+                            text: 'Every control writes a real framework value: the slider moves the base font, the whole app rescales, and Save remembers it for the next visit.',
+                            size: 16,
+                            color: colors.textSecondary
+                        })
+                    ]
                 }),
-                Text({ 
-                    text: 'Welcome to FletBox', 
-                    size: 32, 
-                    weight: 'bold', 
-                    color: colors.text, 
-                    align: 'center' 
+                Input({
+                    label: 'Display name',
+                    placeholder: 'How the app should greet you',
+                    value: name.valueOf(),
+                    required: true,
+                    onChange: (value) => setName(value)
                 }),
-                Text({ 
-                    text: 'A simple and fast UI framework for building web apps with pure JavaScript.', 
-                    size: 16, 
-                    color: colors.textSecondary, 
-                    align: 'center',
-                    style: { maxWidth: 400 }
+                Dropdown({
+                    label: 'Region',
+                    options: [
+                        { value: 'cl', label: 'Chile' },
+                        { value: 'es', label: 'Spain' },
+                        { value: 'mx', label: 'Mexico' }
+                    ],
+                    placeholder: 'Where you are',
+                    value: region.valueOf(),
+                    onChange: (value) => setRegion(value)
                 }),
-                Container({
-                    marginTop: 16,
-                    padding: 20,
-                    borderRadius: 16,
-                    backgroundColor: colors.surface,
-                    style: { width: '100%', maxWidth: 400 },
-                    child: Column({
-                        gap: 12,
-                        children: [
-                            Text({ text: '✨ What is FletBox?', size: 18, weight: 'bold', color: colors.primary }),
-                            Text({ text: 'FletBox helps you create web apps easily. No complex tools. Just write JavaScript.', size: 14, color: colors.textSecondary }),
-                            Container({ height: 1, backgroundColor: colors.border, marginVertical: 8 }),
-                            Row({ gap: 12, alignItems: 'center', children: [
-                                Icon({ name: 'check_circle', size: 20, color: colors.success }),
-                                Text({ text: 'Zero dependencies - lightweight', size: 14, color: colors.text })
-                            ] }),
-                            Row({ gap: 12, alignItems: 'center', children: [
-                                Icon({ name: 'check_circle', size: 20, color: colors.success }),
-                                Text({ text: '40+ ready-to-use widgets', size: 14, color: colors.text })
-                            ] }),
-                            Row({ gap: 12, alignItems: 'center', children: [
-                                Icon({ name: 'check_circle', size: 20, color: colors.success }),
-                                Text({ text: 'Built-in navigation (router)', size: 14, color: colors.text })
-                            ] }),
-                            Row({ gap: 12, alignItems: 'center', children: [
-                                Icon({ name: 'check_circle', size: 20, color: colors.success }),
-                                Text({ text: 'Dark / Light theme', size: 14, color: colors.text })
-                            ] }),
-                            Row({ gap: 12, alignItems: 'center', children: [
-                                Icon({ name: 'check_circle', size: 20, color: colors.success }),
-                                Text({ text: 'Hot reload for fast development', size: 14, color: colors.text })
-                            ] })
-                        ]
-                    })
+                Divider(),
+                // A toggle that never says what it switches is a mystery control: the
+                // label is part of the Switch, and the row is the tap target.
+                Switch({
+                    label: 'Dark theme',
+                    value: isDark,
+                    activeColor: colors.primary,
+                    onPress: (value) => setTheme(value ? 'dark' : 'light')
+                }),
+                Column({
+                    gap: 8,
+                    children: [
+                        Row({
+                            gap: 12,
+                            alignItems: 'center',
+                            children: [
+                                Text({ text: 'Text size', size: 16, weight: 'bold', color: colors.text }),
+                                Text({ text: size + 'px', size: 14, color: colors.textSecondary })
+                            ]
+                        }),
+                        Slider({
+                            min: 14,
+                            max: 22,
+                            step: 1,
+                            value: size,
+                            color: colors.primary,
+                            onPress: (value) => setDraftSize(value)
+                        }),
+                        Text({
+                            text: '16 is what the browser asks for. Anything larger is the reader asking to be readable.',
+                            size: 14,
+                            color: colors.textSecondary
+                        })
+                    ]
                 }),
-                Button({ 
-                    text: 'Back to Root', 
-                    iconLeft: 'arrow_back',
-                    variant: 'outlined',
-                    bgColor: colors.info, 
-                    color: colors.info, 
-                    onPress: () => goTo('/') 
+                Divider(),
+                Column({
+                    gap: 12,
+                    children: [
+                        // One filled button per screen: it is the thing this screen asks
+                        // for, and it is the only control on the page that stretches —
+                        // a full-width target is a decision, not a layout default.
+                        Button({
+                            text: 'Save preferences',
+                            iconLeft: 'check',
+                            bgColor: colors.primary,
+                            color: colors.onPrimary,
+                            fullWidth: true,
+                            onPress: () => save(name.valueOf(), region.valueOf())
+                        }),
+                        Row({
+                            gap: 12,
+                            alignItems: 'center',
+                            children: [
+                                // A second, quieter action: text variant, danger token,
+                                // and it asks before it destroys.
+                                Button({
+                                    text: 'Reset the size',
+                                    iconLeft: 'restart_alt',
+                                    variant: 'text',
+                                    color: colors.dangerStrong,
+                                    onPress: () => resetDialog.open()
+                                }),
+                                // An icon alone says nothing; the Tooltip is its name.
+                                Tooltip({
+                                    text: 'Resetting the size is not undoable from this screen',
+                                    position: 'right',
+                                    child: Icon({ name: 'help_outline', size: 24, color: colors.textSecondary })
+                                })
+                            ]
+                        })
+                    ]
                 })
             ]
         })
@@ -416,8 +511,9 @@ import { Drawer, DrawerItem, Container, Column, Text, Icon, colors, closeDrawer
 export const DrawerMenu = () => {
     return Drawer({
         header: Container({
-            padding: 28,
-            backgroundColor: colors.primary,
+            padding: 24,
+            backgroundColor: colors.surface,
+            borderBottom: \`1px solid \${colors.border}\`,
             child: Column({
                 gap: 12,
                 alignItems: 'center',
@@ -425,39 +521,39 @@ export const DrawerMenu = () => {
                     Container({
                         width: 60,
                         height: 60,
-                        borderRadius: 30,
-                        backgroundColor: '#ffffff',
+                        borderRadius: 999,
+                        backgroundColor: colors.primaryBg,
                         justifyContent: 'center',
                         alignItems: 'center',
                         child: Icon({ name: 'rocket_launch', size: 32, color: colors.primary })
                     }),
-                    Text({ text: 'FletBox', size: 18, weight: 'bold', color: '#ffffff' }),
-                    Text({ text: 'UI Framework', size: 12, color: 'rgba(255,255,255,0.8)' })
+                    Text({ text: 'FletBox', size: 18, weight: 'bold', color: colors.text }),
+                    Text({ text: 'Starter app', size: 12, color: colors.textSecondary })
                 ]
             })
         }),
         body: [
             DrawerItem({ 
-                icon: 'dashboard', 
-                label: 'Dashboard', 
+                icon: 'palette', 
+                label: 'Design system', 
                 route: '/home',
                 onPress: () => closeDrawer()
             }),
             DrawerItem({ 
-                icon: 'info', 
-                label: 'About', 
+                icon: 'tune', 
+                label: 'Preferences', 
                 route: '/about',
                 onPress: () => closeDrawer()
             }),
             DrawerItem({ 
                 icon: 'home', 
-                label: 'Root', 
+                label: 'Start here', 
                 route: '/',
                 onPress: () => closeDrawer()
             })
         ],
         footer: Container({
-            padding: 20,
+            padding: 16,
             borderTop: \`1px solid \${colors.border}\`,
             child: Text({ 
                 text: 'Version 1.0.0', 
@@ -473,12 +569,39 @@ export default DrawerMenu;
 `;
 
 export const themesJs = () => `// database/themes.js
-export let colors = {
-    primary: '#6366f1',
+// The app's whole design system lives here. Every value is measured with the
+// framework's own \`color().contrastRatio()\` against the surface it is written on:
+// the number sits next to the pair that needs it, because a token that cannot
+// carry AA text is decoration, not a color.
+import { registerPalette } from 'flet-box';
+
+export const lightColors = {
+    // #6366f1 put white on 4.47:1 — a hair under AA. Two units darker measures
+    // 4.55:1, the same indigo, and every brand button passes.
+    primary: '#6165ef',
     secondary: '#8b5cf6',
     success: '#10b981',
     warning: '#f59e0b',
+    // The error signal: a badge, a border, an icon. 3.76:1 as words on this page,
+    // so it is never the label of a button.
     danger: '#ef4444',
+    // The readable red, both ways: 6.47:1 as words on white, 6.47:1 with white
+    // written on it, 5.42:1 inside \`errorBg\`. Use it for the words and the plate.
+    dangerStrong: '#b91c1c',
+    // The readable green and amber: 5.48:1 and 5.02:1, in both directions, so
+    // they may be a label, an icon that carries meaning, or a plate.
+    successStrong: '#047857',
+    warningStrong: '#b45309',
+    // \`*Plate\` is the fill white words sit on. On this page it is the same tone
+    // as the matching Strong, and it is a separate name because on a dark page the
+    // two part ways: the readable red goes light, the plate goes dark.
+    dangerPlate: '#b91c1c',
+    successPlate: '#047857',
+    warningPlate: '#b45309',
+    // \`info\` (#3b82f6) carries white at 3.68:1, so a filled chip or a tooltip in
+    // the info hue needs this one: 6.70:1 in both directions.
+    infoStrong: '#1d4ed8',
+    infoPlate: '#1d4ed8',
     info: '#3b82f6',
     background: '#ffffff',
     surface: '#f8fafc',
@@ -486,10 +609,23 @@ export let colors = {
     textSecondary: '#64748b',
     textDisabled: '#94a3b8',
     border: '#e2e8f0',
-    white: '#ffffff',
-    black: '#000000',
     overlay: 'rgba(0, 0, 0, 0.5)',
-    shadow: 'rgba(0, 0, 0, 0.1)'
+    shadow: 'rgba(0, 0, 0, 0.1)',
+    // What to write on a brand fill, and the soft tints that replace
+    // \`colors.primary + '15'\`.
+    onPrimary: '#ffffff',
+    primaryBg: '#eef2ff',
+    // The translucent surface for a card with \`backdropFilter\`. A token, so the
+    // app never hand-writes an \`rgba()\` the clean-UI gate would reject.
+    glass: 'rgba(255, 255, 255, 0.66)',
+    glassBorder: 'rgba(255, 255, 255, 0.75)',
+    error: '#ff3b30',
+    errorBg: '#ffe5e5',
+    successBg: '#e5f5e5',
+    warningBg: '#fff5e5',
+    infoBg: '#e5f5ff',
+    divider: '#eeeeee',
+    card: '#ffffff'
 };
 
 export const darkColors = {
@@ -497,7 +633,23 @@ export const darkColors = {
     secondary: '#a78bfa',
     success: '#34d399',
     warning: '#fbbf24',
+    // On a dark page the light red is the readable one: 6.45:1 against the
+    // background. The plate a person presses goes the other way.
     danger: '#f87171',
+    // \`*Strong\` is the answer to "what may I write words in?" and on this page
+    // that is the light end of the ladder: 9.41:1, 11.71:1, 12.38:1 on the
+    // background — all AA, and a step clearer than the signal tone above.
+    dangerStrong: '#fca5a5',
+    successStrong: '#6ee7b7',
+    warningStrong: '#fcd34d',
+    // \`*Plate\` is the fill with white words on it, and that has to go dark here:
+    // 10.02:1, 9.11:1, 9.07:1. These are the tones that used to hide inside
+    // \`*Strong\`, which is why a delete written in \`dangerStrong\` was invisible.
+    dangerPlate: '#7f1d1d',
+    successPlate: '#14532d',
+    warningPlate: '#78350f',
+    infoStrong: '#93c5fd',
+    infoPlate: '#1e40af',
     info: '#60a5fa',
     background: '#0f172a',
     surface: '#1e293b',
@@ -505,46 +657,28 @@ export const darkColors = {
     textSecondary: '#94a3b8',
     textDisabled: '#64748b',
     border: '#334155',
-    white: '#ffffff',
-    black: '#000000',
     overlay: 'rgba(0, 0, 0, 0.6)',
-    shadow: 'rgba(0, 0, 0, 0.3)'
-};
-
-let currentTheme = 'light';
-const listeners = [];
-
-export const setTheme = (themeName) => {
-    const theme = themeName === 'dark' ? darkColors : colors;
-    currentTheme = themeName;
-    Object.keys(theme).forEach(key => { 
-        if (colors.hasOwnProperty(key)) {
-            colors[key] = theme[key];
-        }
-    });
-    const root = document.documentElement;
-    Object.keys(colors).forEach(key => {
-        root.style.setProperty(\`--color-\${key}\`, colors[key]);
-    });
-    listeners.forEach(cb => cb(colors, themeName));
-};
-
-export const getTheme = () => currentTheme;
-export const toggleTheme = () => {
-    const newTheme = currentTheme === 'light' ? 'dark' : 'light';
-    setTheme(newTheme);
-    return newTheme;
-};
-export const subscribeTheme = (callback) => {
-    listeners.push(callback);
-    return () => { const i = listeners.indexOf(callback); if(i > -1) listeners.splice(i, 1); };
+    shadow: 'rgba(0, 0, 0, 0.3)',
+    // #818cf8 is a light fill: white on it is 2.98:1, the page's own ink is 5.98:1.
+    onPrimary: '#0f172a',
+    primaryBg: '#1e1b4b',
+    glass: 'rgba(30, 41, 59, 0.66)',
+    glassBorder: 'rgba(226, 232, 240, 0.22)',
+    error: '#f87171',
+    errorBg: '#3b1113',
+    successBg: '#0c2f22',
+    warningBg: '#33230a',
+    infoBg: '#12263c',
+    divider: '#1e293b',
+    card: '#1e293b'
 };
 
-const initTheme = () => {
-    const root = document.documentElement;
-    Object.keys(colors).forEach(key => root.style.setProperty(\`--color-\${key}\`, colors[key]));
-};
-initTheme();
+// Declaring a palette paints nothing by itself: every widget reads the
+// framework's live \`colors\`, so the tokens have to be registered into it.
+// Registration deliberately does not pick a theme — whether the app is dark is
+// the reader's answer (\`setTheme\`, \`toggleTheme\`), not the designer's.
+registerPalette('light', lightColors);
+registerPalette('dark', darkColors);
 `;
 
 export const runSh = () => `#!/bin/bash
@@ -686,17 +820,40 @@ self.addEventListener('fetch', event => {
         const hit = await cache.match(req);
         if (hit) return hit;
       }
+
+      // A page load that neither the host nor the cache can answer must still
+      // boot the app: the router takes the URL from there. Asset requests keep
+      // their own failure, because replacing a missing image with a document is
+      // how a broken site becomes an undebuggable one.
+      const shell = async () => {
+        if (req.mode !== 'navigate') return null;
+        const cached = await cache.match(BASE + 'index.html');
+        if (cached) return cached;
+        try {
+          const fresh = await fetch(BASE + 'index.html', { cache: 'no-store' });
+          return fresh.ok ? fresh : null;
+        } catch (err) {
+          return null;
+        }
+      };
+
       try {
         const fresh = await fetch(req, { cache: 'no-store' });
-        if (fresh.ok) cache.put(req, fresh.clone());
-        return fresh;
+        if (fresh.ok) {
+          cache.put(req, fresh.clone());
+          return fresh;
+        }
+        // A host without SPA rewrites (GitHub Pages, a plain bucket) answers an
+        // unknown path with its own 404 page. That is a response, not an error,
+        // so a fallback living in the catch below never runs and every reload of
+        // a deep link shows "Page not found" while the app is perfectly healthy.
+        const fallback = await shell();
+        return fallback || fresh;
       } catch (err) {
         const cached = await cache.match(req);
         if (cached) return cached;
-        if (req.mode === 'navigate') {
-          const shell = await cache.match(BASE + 'index.html');
-          if (shell) return shell;
-        }
+        const fallback = await shell();
+        if (fallback) return fallback;
         return Response.error();
       }
     })()
@@ -711,6 +868,9 @@ export const packageJson = (name) => `{
   "scripts": {
     "dev": "bash run.sh",
     "check": "node scripts/check-app.mjs",
+    "ui": "node scripts/check-ui.mjs",
+    "fix": "flet-box audit-fix",
+    "api": "flet-box unpack --all --md",
     "build": "flet-box createBundle www",
     "start": "npm run dev",
     "android:init": "npm run build && cap add android",
@@ -1081,8 +1241,8 @@ export const manifest = (appName = "FletBox App") => `{
   "name": ${JSON.stringify(appName)},
   "short_name": ${JSON.stringify(appName.slice(0, 12))},
   "description": ${JSON.stringify(`${appName} built with Flet-Box`)},
-  "start_url": "/",
-  "scope": "/",
+  "start_url": "./",
+  "scope": "./",
   "display": "standalone",
   "display_override": ["window-controls-overlay"],
   "theme_color": "#1a1a2e",
@@ -1121,58 +1281,117 @@ export const manifest = (appName = "FletBox App") => `{
 }
 `;
 
-// GitHub Actions workflow that builds web + Android + iOS in ONE run.
-// Placed at .github/workflows/ (the only location GitHub reads), NOT inside www/.
+// GitHub Actions workflow that builds and publishes the WEB. Two jobs, the way
+// the docs site does it: `build` checks and bundles `www/` and only *uploads* it,
+// `deploy` is the sole job that can touch Pages — so a build that fails leaves
+// the live site alone. The native builds are a second file (build-native.yml)
+// that only runs when started by hand.
 // NOTE: every GitHub `${{ }}` expression is escaped as `\${{ }}` because this is
 // a JS template literal — an unescaped `${` would be parsed as interpolation.
-export const githubWorkflow = (appName = "FletBox App", appId = "com.fletbox.app") => {
-  const slug = appName
+//
+// `siteUrl` is the Pages address `flet-box create` derived from `--repo`. It is
+// written into the file as text, at the top, the way the docs repo states its
+// own: whoever opens build.yml on GitHub reads where this app lives before
+// reading a single step. Anything that is not an http(s) URL is refused, so a
+// caller that passes the wrong thing gets the placeholder rather than a lie —
+// and the placeholder keeps `TU-USUARIO` visible, because that is the one string
+// the developer must edit.
+export const githubWorkflow = (appName = "FletBox App", siteUrl = null) => {
+  const slug = String(appName)
     .toLowerCase()
-    .replace(/[^a-z0-9]+/g, "-")
-    .replace(/^-+|-+$/g, "")
-    .slice(0, 40) || "fletbox-app";
-  return `name: Build ${appName}
-
-# One push (or manual trigger) fans out into three parallel jobs:
-#   web     -> bundles the PWA; publishes to GitHub Pages ONLY on release
-#              tags (v*), which is what triggers OTA self-updates
-#   android -> compiles a debug APK and uploads it as an artifact
-#   ios     -> compiles a simulator .app and uploads it as an artifact
-# All three run at the same time on separate runners.
+    .replace(/[^a-z0-9._-]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "fletbox-app";
+  const site = /^https?:\/\//i.test(String(siteUrl || ""))
+    ? String(siteUrl).replace(/\/?$/, "/")
+    : `https://TU-USUARIO.github.io/${slug}/`;
+  // Only when the owner is still a guess: the address lives in two files, and a
+  // developer who edits one and not the other ships an app that polls a site
+  // that is not where the bundle is.
+  const todo = site.includes("TU-USUARIO")
+    ? `# The owner above is a placeholder: this project was created without \`--repo\`,
+# so the folder name is only a guess at the repo name. Write the real address in
+# both files that state it — this header, and fletbox.config.json (update.url),
+# which is the URL an installed app polls for an update.
+`
+    : "";
+  return `name: Deploy ${appName}
+
+# This app goes live at:
+#   ${site}
+${todo}#
+# Web: AUTOMATIC. Every push to main (and every manual run) builds a fresh site;
+# only the deploy job can touch Pages, so a broken bundle never replaces the
+# live one. Enable the destination once: Settings -> Pages -> Build and
+# deployment -> Source: GitHub Actions. Until you do, runs are green and no site
+# exists — the "Where this lives" step below says so in the log.
+#
+# Android and iOS are NOT here: they live in build-native.yml and run only when
+# you start them, because a macOS runner is not free.
+#
+# One consequence to know about: this Pages site is also what an installed app
+# polls for an OTA update (www/config.json), and the app compares the bundle
+# hash, not the version. So the manifest is left out of every build whose commit
+# carries no \`v*\` tag (see "Ship the update feed only when this commit is a
+# release" below): the site is live on every push, while installed apps keep
+# running the last \`flet-box release\`.
+#
+# Publishing a release: push main, then \`git tag -a v1.2.3 && git push origin
+# v1.2.3\`, then Actions -> this workflow -> Run workflow. The manual run deploys
+# the tagged commit, and it is the run that puts config.json on the site. The tag
+# itself cannot deploy: GitHub refuses Pages deployments that start from a tag.
+
 on:
   push:
     branches: [ main ]
-    tags: [ 'v*' ]
-  pull_request:
-    branches: [ main ]
+    # Deliberately NO tags: trigger. The github-pages environment only accepts
+    # deployments from the default branch, so a run that starts from a tag fails
+    # at the deploy job with "Tag v1.0.0 is not allowed to deploy to github-pages
+    # due to environment protection rules". A release is therefore made by
+    # pushing main and then running this workflow again, by hand, once the tag
+    # exists: that run is on main, and it sees the tag on HEAD.
   workflow_dispatch:
 
-# Cancel superseded runs on the same branch to save Actions minutes.
+# The deploy job needs Pages write access; it is declared once, for the file.
+permissions:
+  contents: read
+  pages: write
+  id-token: write
+
+# Allow only one concurrent deployment, skipping runs queued between the run
+# in-progress and the latest queued. Do NOT cancel in-progress: a production
+# deployment is allowed to finish, because the site that is live while it runs is
+# the previous one, and a cancelled deploy leaves Pages holding a half-written
+# artifact.
 concurrency:
-  group: \${{ github.workflow }}-\${{ github.ref }}
-  cancel-in-progress: true
+  group: pages
+  cancel-in-progress: false
 
-# The generated app depends on the public \`flet-box\` npm package. If you are
-# developing against a local copy, publish it (or vendor it) before these jobs
-# can \`npm install\` it. package-lock.json is gitignored, so we use npm install.
+# The generated app depends on the public \`flet-box\` npm package. If you
+# develop against a local copy, publish it (or vendor it) before these jobs can
+# \`npm install\` it. package-lock.json is gitignored, so we use npm install.
 
 jobs:
-  # ---------- WEB: bundle + GitHub Pages preview ----------
-  web:
-    name: Web (Pages)
+  # ---------- BUILD: check, bundle, upload. Nothing here reaches Pages. ----------
+  build:
+    name: Build site
     runs-on: ubuntu-latest
-    permissions:
-      contents: read
-      pages: write
-      id-token: write
-    environment:
-      name: github-pages
-      url: \${{ steps.deployment.outputs.page_url }}
     steps:
       - uses: actions/checkout@v5
+        with:
+          # The release decision below reads the tags pointing at this commit, and
+          # a shallow checkout of one commit does not fetch them by itself.
+          fetch-tags: true
+
+      # Registers the Pages integration for this run and reports the site's base
+      # path, which is /<repo>/ for a project site and empty on a custom domain.
+      # It belongs in the build job, before the artifact is uploaded.
+      - name: Setup Pages
+        uses: actions/configure-pages@v5
 
       - uses: actions/setup-node@v5
         with:
+          # 22 is the current LTS. 20 is EOL, and the runner says so on every
+          # build of a generated app.
           node-version: 22
 
       - name: Install dependencies
@@ -1183,28 +1402,108 @@ jobs:
       - name: Check app API usage (npm run check)
         run: npm run check
 
-      - name: Bundle web app (flet-box createBundle www)
+      - name: Build site (flet-box createBundle www)
         run: npm run build
 
-      # Pages is the OTA update source (www/config.json), so it is published
-      # ONLY for release tags (v*) created by \`flet-box release\`. Ordinary
-      # pushes still build (to catch breakage in CI) but never publish an
-      # update, so test builds cannot reach installed apps.
+      # Printed before the deploy, because this is the address the whole workflow
+      # is about, and because a missing Pages setting otherwise shows up as a
+      # green run with no site: Pages lower-cases the owner, hence the tr.
+      # The file header names one address too; this is the authority, because it
+      # reads the repo the run actually belongs to — they disagree when the repo
+      # was created with a different name than the folder, or never pushed.
+      - name: Where this lives
+        run: |
+          owner=$(printf '%s' "$GITHUB_REPOSITORY_OWNER" | tr '[:upper:]' '[:lower:]')
+          repo=\${GITHUB_REPOSITORY#*/}
+          echo "  site:    https://$owner.github.io/$repo/"
+          echo "  header:  ${site}"
+          echo "  version: $(node -p "require('./package.json').version")"
+          echo "  If a green run leaves that 404, the source is wrong:"
+          echo "  Settings -> Pages -> Build and deployment -> Source: GitHub Actions"
+
+      # www/config.json is the OTA manifest: an installed app fetches it and
+      # compares its \`hash\` with the bundle it is running, so publishing it from
+      # an ordinary push would offer that unfinished build to every device that
+      # checks for updates. Dropping the file makes the poll fail as "not
+      # deployed yet" (see bin/ota/loader.js), which is the behaviour wanted:
+      # the site is live for reading, the release feed stays on tagged builds.
+      #
+      # The decision reads the commit, not the ref: a tag push cannot deploy (the
+      # environment refuses it), so \`github.ref\` is always a branch here. To
+      # publish a release, push main, tag that commit, then run this workflow by
+      # hand from Actions - the manual run is on main and sees the tag.
+      - name: Ship the update feed only when this commit is a release
+        run: |
+          tag=$(git tag --points-at HEAD --list 'v*' | sort -V | tail -1)
+          if [ -n "$tag" ]; then
+            echo "  ota:     $tag is on this commit: config.json ships, installed apps may update"
+          else
+            rm -f www/config.json
+            echo "  ota:     web-only: no v* tag on $(git rev-parse --short HEAD), manifest left out"
+          fi
+
       - name: Upload Pages artifact
-        if: startsWith(github.ref, 'refs/tags/v')
         uses: actions/upload-pages-artifact@v5
         with:
           path: www
 
-      # Enable Pages first: Settings -> Pages -> Source = "GitHub Actions".
+  # ---------- DEPLOY: the only job with a path to Pages ----------
+  deploy:
+    name: Deploy to Pages
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: github-pages
+      url: \${{ steps.deployment.outputs.page_url }}
+    steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        if: startsWith(github.ref, 'refs/tags/v')
         uses: actions/deploy-pages@v5
 
+      # The address in the job log and as a run annotation, so it is readable
+      # from the workflow list without opening anything.
+      - name: Published
+        run: |
+          echo "  live at: \${{ steps.deployment.outputs.page_url }}"
+          echo "::notice title=Site published to GitHub Pages::\${{ steps.deployment.outputs.page_url }}"
+`;
+};
+
+// Native builds: the same two jobs, but they run ONLY when started by hand from
+// Actions -> Run workflow, with a choice of platform. A push never pays for a
+// macOS runner, and `flet-box build android|ios` already covers a local build.
+export const nativeWorkflow = (appName = "FletBox App") => {
+  const slug = appName
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "")
+    .slice(0, 40) || "fletbox-app";
+  return `name: Build ${appName} — native (manual)
+
+# Nothing in here runs on a push. Start it by hand: Actions -> "${appName} —
+# native (manual)" -> Run workflow, then pick the platform. Each job bundles the
+# web first, because that bundle is what Capacitor copies into the app.
+
+on:
+  workflow_dispatch:
+    inputs:
+      platform:
+        description: "What to build"
+        type: choice
+        options:
+          - android
+          - ios
+          - both
+        default: android
+
+permissions:
+  contents: read
+
+jobs:
   # ---------- ANDROID: debug APK ----------
   android:
     name: Android (APK)
+    if: inputs.platform == 'android' || inputs.platform == 'both'
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v5
@@ -1246,9 +1545,19 @@ jobs:
           path: android/app/build/outputs/apk/debug/app-debug.apk
           if-no-files-found: error
 
+      # An artifact has no public URL: it is on the run page, and this prints
+      # which run. The debug APK installs as it is; a release one would have to be
+      # signed with your own keystore first.
+      - name: Where the APK is
+        run: |
+          echo "  artifact: ${slug}-android-debug"
+          echo "  download: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
+          echo "::notice title=APK ready::${slug}-android-debug, on this run page"
+
   # ---------- iOS: simulator build ----------
   ios:
     name: iOS (simulator)
+    if: inputs.platform == 'ios' || inputs.platform == 'both'
     runs-on: macos-latest
     steps:
       - uses: actions/checkout@v5
@@ -1295,6 +1604,12 @@ jobs:
           name: ${slug}-ios-simulator
           path: ios/App/build/Build/Products/Debug-iphonesimulator/App.app
           if-no-files-found: error
+
+      - name: Where the build is
+        run: |
+          echo "  artifact: ${slug}-ios-simulator"
+          echo "  download: $GITHUB_SERVER_URL/$GITHUB_REPOSITORY/actions/runs/$GITHUB_RUN_ID"
+          echo "::notice title=Simulator build ready::${slug}-ios-simulator, on this run page"
 `;
 };
 
@@ -1318,7 +1633,9 @@ package-lock.json
 
 export const readme = (name, _template, appId) => `# ${name}
 
-FletBox app with 3 screens: Root, Home and About, plus Drawer menu.
+FletBox app with 3 screens: Root, Home (the design system) and About
+(preferences), plus Drawer menu. Read \`src/screens/HomeScreen.js\` first: it is
+the contract this app is built on, and \`npm run ui\` enforces it.
 The generated Capacitor configuration uses package id \`${appId}\`.
 
 ## Quick Start
@@ -1336,22 +1653,39 @@ 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\`.
 - \`.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
   installed package. This is the lookup an agent reads instead of the framework.
+- \`.fletbox/api/api.json\` — the same surface as data: per prop its engine target,
+  default, aliases and a \`sample\` value the types prove works. Write calls from this.
 - \`.fletbox/memory/\` — notes the agent keeps between sessions, so it does not
   rediscover the same thing twice.
 - \`scripts/check-app.mjs\` — the gate that catches hallucinated APIs.
+- \`scripts/check-ui.mjs\` — the gate that catches an unclean screen.
 
 \`\`\`bash
 npm run check                      # scan src/ for invented widgets, props, imports
 npm run check -- --props Button    # print the real props of one widget
 npm run check -- --list            # print every public export
+npm run ui                         # clean-UI gate: tokens, scale, tap targets, labels,
+                                   # contrast — each finding cites the rule it broke
+npm run ui -- --tokens             # measured contrast of every token, on both surfaces
+npm run ui -- --strict             # warnings (a one-off tint, an image with no alt) fail too
+npm run fix                        # rewrite typos it can prove (imports, prop keys)
+npm run api                        # regenerate .fletbox/api/api.json and api.md
+flet-box unpack Button             # each prop, where it really goes, and what is dead
+flet-box unpack Button --example   # a paste-ready call using only verified props
+flet-box unpack Modal --diff       # where types, engine, docs and code disagree
 \`\`\`
 
-\`npm run check\` exits non-zero on a real error and also runs in CI. If you upgrade
-\`flet-box\`, regenerate the cheatsheet with \`flet-box check-api --emit-api\`.
+\`npm run check\` and \`npm run ui\` exit non-zero on a real error and also run in CI. If
+you upgrade \`flet-box\`, regenerate the cheatsheet with \`flet-box check-api --emit-api\`
+and the machine-readable surface with \`npm run api\`.
 
 ## Android
 
@@ -1414,29 +1748,51 @@ CORS configuration and use HTTPS for the remote service.
 
 ## Continuous Integration (GitHub Actions)
 
-Every project ships with \`.github/workflows/build.yml\`. Once the repo is on
-GitHub, each push to \`main\` (or a manual **Run workflow**) fans out into three
-parallel jobs:
+Two workflow files ship with the project, and they answer to different triggers:
 
-- **web** — bundles the app into \`www/\` and deploys it to **GitHub Pages** so you
-  can view it in a browser.
-- **android** — compiles a debug **APK** and uploads it as a run artifact.
-- **ios** — compiles an unsigned **simulator .app** and uploads it as an artifact.
+- \`.github/workflows/build.yml\` — **the web, automatic**. Every push to \`main\`
+  (and a manual run) builds \`www/\` and publishes it to **GitHub Pages**, in two
+  jobs: **Build site** checks the app, bundles it and uploads the result; **Deploy
+  to Pages** is the only job that can replace the live site, so a bundle that
+  fails to build leaves the current one running. A \`v*\` tag is deliberately not
+  a trigger: the Pages environment refuses a run that starts from a tag, so the
+  release is deployed by running this workflow again after tagging.
+- \`.github/workflows/build-native.yml\` — **Android and iOS, manual only**. Nothing
+  runs on a push. Open **Actions → "… — native (manual)" → Run workflow** and pick
+  \`android\`, \`ios\` or \`both\`. Each job uploads its build as a run artifact and
+  prints the artifact name and the run URL in its own log.
 
-### Run it on the web (one-time setup)
+### Publish the web (one-time setup)
 
 1. Push this project to a GitHub repository.
 2. Open **Settings → Pages** in that repo.
-3. Set **Source** to **GitHub Actions** (not "Deploy from a branch").
-4. Push to \`main\`, or open the **Actions** tab and click **Run workflow**.
-
-The site goes live at \`https://<your-user>.github.io/<repo-name>/\`. That is a
-sub-path, so \`index.html\` uses relative asset paths and works without changes.
+3. Set **Source** to **GitHub Actions** (not "Deploy from a branch"). Skip this
+   and the deploy step fails on every push.
+4. Push. The **Where this lives** step prints the address before the deploy runs,
+   and the **Published** step prints it again as a run annotation, so you do not
+   have to hunt for the environment box under the job.
+
+The address this project publishes to is written at the top of
+\`.github/workflows/build.yml\`. \`flet-box create <name> --repo <user>/<repo>\`
+fills it in from the repo; without \`--repo\` it stays
+\`https://TU-USUARIO.github.io/<name>/\`, and the header says which two files to
+edit. That is a sub-path, so \`index.html\` uses relative asset paths and works
+without changes.
+
+**Why a push does not update anyone's app:** this same address is the OTA feed
+installed apps poll, and the update check compares bundle **hashes**, not version
+numbers. So the workflow leaves \`www/config.json\` out of every artifact that is
+not a \`v*\` tag: the site is live for reading, while a device keeps running the
+last \`flet-box release\` until a tag publishes a manifest. The **Where this
+lives** step prints which of the two a given run was. Cut a release with
+\`flet-box release --patch --push\` when the app is worth updating.
 
 ### Download the mobile artifacts
 
-Open the workflow run in the **Actions** tab; the Android APK and the iOS
-\`.app\` are listed under **Artifacts** at the bottom of the run summary.
+Start it by hand — **Actions → "… — native (manual)" → Run workflow**, pick a
+platform — and open that run: the Android APK and the iOS \`.app\` are listed
+under **Artifacts** at the bottom of the run summary, and the job's own log prints
+the artifact name plus the URL of the run it belongs to.
 
 > The workflow installs dependencies with \`npm install\`, which resolves the
 > \`flet-box\` package from npm. If you develop against a local copy of the
@@ -1514,10 +1870,19 @@ updates:
 - Replace \`TU-USUARIO\` with your GitHub username and \`TU-REPO\` with the
   repository name, or set \`update.url\` to any HTTPS host that serves your
   \`config.json\` + bundle.
-- Enable GitHub Pages: **Settings → Pages → Source: GitHub Actions**.
+- Enable GitHub Pages: **Settings → Pages → Source: GitHub Actions**. Without
+  that the deploy step is green and no site exists.
 - Cut a release with \`flet-box release --push\` (bumps the version, rebuilds
   \`www/\`, commits and tags \`vX.Y.Z\`). CI then deploys \`www/\` and installed
   apps self-update the next time they open.
+- A plain \`git push\` also deploys \`www/\` — that is the preview, and the job
+  prints the address. It never publishes \`www/config.json\`, because that file
+  is the update feed and the app compares bundle **hashes**: without it an
+  installed app finds no manifest and stays on the last release. Do not "fix"
+  that gate; the release tag is the only thing that should reach users.
+- Android and iOS are not built on a push. Start
+  \`.github/workflows/build-native.yml\` from **Actions → Run workflow** and pick
+  \`android\`, \`ios\` or \`both\`.
 - The update URL is also reflected in \`www/config.json\` after \`flet-box
   createBundle www\`; it is baked into Android/iOS builds at \`cap sync\` time.
 - Only web files are updated OTA. Native changes (plugins, permissions,
@@ -1525,9 +1890,13 @@ updates:
 
 ## Features
 
-- Welcome screen with rocket icon
-- Dashboard screen with welcome message
-- About screen with framework info
+- Root screen: one filled action, one quiet one
+- Home screen: the spacing rhythm, the type scale and the three color roles,
+  drawn from the framework's own scale
+- About screen: \`useState\`, an \`Input\`, a \`Dropdown\`, a labelled \`Switch\`,
+  a \`Slider\` that moves the base font size, a \`SnackBar\` reply and an
+  \`AlertDialog\` before the destructive action
+- Neutral app bar with a theme toggle that carries a \`Tooltip\` name
 - Drawer menu for navigation
 - PWA icons and Capacitor Android launcher/splash assets
 - Capacitor iOS project, icon and launch screen assets
@@ -1562,22 +1931,91 @@ MIT
 
 // Additional screen for adaptive template
 export const profileScreenJs = () => `// screens/ProfileScreen.js
-import { Container, Column, Text, Icon, colors } from 'flet-box';
+import { Container, Column, Row, Text, Icon, Divider, colors, Storage, goTo } from 'flet-box';
+
+// Two words, from whatever the reader typed on the Preferences screen.
+const initials = (name) =>
+    name.trim().split(/\\s+/).slice(0, 2).map((word) => word[0]).join('').toUpperCase();
+
+const linkRow = (icon, label, note, route) => Container({
+    padding: 16,
+    cursor: 'pointer',
+    child: Row({
+        gap: 12,
+        alignItems: 'center',
+        children: [
+            Icon({ name: icon, size: 20, color: colors.textSecondary }),
+            Column({
+                flex: 1,
+                gap: 4,
+                alignItems: 'stretch',
+                children: [
+                    Text({ text: label, size: 16, color: colors.text }),
+                    Text({ text: note, size: 12, color: colors.textSecondary })
+                ]
+            }),
+            Icon({ name: 'chevron_right', size: 20, color: colors.textSecondary })
+        ]
+    }),
+    onclick: () => goTo(route)
+});
 
 export const ProfileScreen = () => {
+    const name = Storage.getData('displayName') || '';
+
     return Container({
         flex: 1,
-        justifyContent: 'center',
-        alignItems: 'center',
         padding: 24,
         backgroundColor: colors.background,
         child: Column({
-            gap: 20,
-            alignItems: 'center',
+            gap: 24,
+            alignItems: 'stretch',
+            maxWidth: 480,
+            margin: '0 auto',
             children: [
-                Icon({ name: 'person', size: 80, color: colors.primary }),
-                Text({ text: 'User Profile', size: 28, weight: 'bold', color: colors.text }),
-                Text({ text: 'This is your profile page.', size: 16, color: colors.textSecondary })
+                Row({
+                    gap: 16,
+                    alignItems: 'center',
+                    children: [
+                        Container({
+                            width: 64,
+                            height: 64,
+                            borderRadius: 999,
+                            backgroundColor: colors.primaryBg,
+                            display: 'flex',
+                            alignItems: 'center',
+                            justifyContent: 'center',
+                            child: Text({
+                                text: initials(name) || 'P',
+                                size: 24,
+                                weight: 'bold',
+                                color: colors.primary
+                            })
+                        }),
+                        Column({
+                            flex: 1,
+                            gap: 4,
+                            alignItems: 'stretch',
+                            children: [
+                                Text({ text: name || 'No name yet', size: 18, weight: 'bold', color: colors.text }),
+                                Text({
+                                    text: name ? 'Saved on this device' : 'Add one under Preferences',
+                                    size: 14,
+                                    color: colors.textSecondary
+                                })
+                            ]
+                        })
+                    ]
+                }),
+                Divider(),
+                Column({
+                    gap: 4,
+                    alignItems: 'stretch',
+                    children: [
+                        linkRow('tune', 'Preferences', 'name, region, theme and text size', '/about'),
+                        linkRow('palette', 'Design system', 'the spacing, type and color scales', '/home')
+                    ]
+                })
             ]
         })
     });
@@ -1598,38 +2036,70 @@ export { AboutScreen } from './AboutScreen.js';${
 
 // Layout components
 export const appBarComponentJs = () => `// components/layouts/AppBarComponent.js
-import { AppBar, Icon, colors, openDrawer } from 'flet-box';
+import { AppBar, Icon, Tooltip, colors, openDrawer, toggleTheme, getTheme } from 'flet-box';
 
+// The bar is neutral — the surface token, not the brand — because a coloured strip
+// on every screen competes with the one action the screen is asking for. One
+// elevation step is enough to keep it off the page.
+//
+// It reads the theme instead of subscribing to it: setTheme() re-renders the app,
+// so a component that subscribed would add a listener on every render and never
+// remove it.
 export const AppBarComponent = ({ title, isMobile = false, showBack = false, onBack }) => {
+    const isDark = getTheme() === 'dark';
+
     return AppBar({
         title: title,
-        backgroundColor: colors.primary,
-        titleColor: '#ffffff',
-        centerTitle: true,
+        backgroundColor: colors.surface,
+        titleColor: colors.text,
+        iconColor: colors.text,
+        centerTitle: false,
         showBackButton: showBack,
-        leading: isMobile ? Icon({
-            name: 'menu',
-            size: 24,
-            color: '#ffffff',
-            onclick: () => openDrawer()
+        leading: isMobile ? Tooltip({
+            text: 'Open the menu',
+            position: 'bottom',
+            child: Icon({
+                name: 'menu',
+                size: 24,
+                height: 40,
+                color: colors.text,
+                onclick: () => openDrawer()
+            })
         }) : null,
+        // An icon-only control still needs a name: the Tooltip is what says so.
+        actions: [
+            Tooltip({
+                text: isDark ? 'Switch to light' : 'Switch to dark',
+                position: 'bottom',
+                child: Icon({
+                    name: isDark ? 'light_mode' : 'dark_mode',
+                    size: 24,
+                    height: 40,
+                    color: colors.text,
+                    onclick: () => toggleTheme()
+                })
+            })
+        ],
         onBackPress: onBack,
-        elevation: 2
+        elevation: 1
     });
 };
 `;
 
 export const bottomNavJs = () => `// components/layouts/BottomNav.js
-import { BottomNavigation, colors, goTo } from 'flet-box';
+import { BottomNavigation, colors, goTo, getCurrentPath } from 'flet-box';
 
-export const BottomNav = ({ items = [], currentRoute } = {}) => {
+// Scaffold re-runs this on every route change, which is why the current path is
+// read here rather than passed in by the app.
+export const BottomNav = ({ items = [] } = {}) => {
     const defaultItems = [
-        { icon: 'home', label: 'Home', route: '/home' },
-        { icon: 'info', label: 'About', route: '/about' }
+        { icon: 'home', label: 'Start', route: '/' },
+        { icon: 'palette', label: 'System', route: '/home' },
+        { icon: 'tune', label: 'Preferences', route: '/about' }
     ];
     const navItems = items.length ? items : defaultItems;
     // BottomNavigation selects a tab by index, not by route.
-    const currentIndex = Math.max(0, navItems.findIndex((item) => item.route === currentRoute));
+    const currentIndex = Math.max(0, navItems.findIndex((item) => item.route === getCurrentPath()));
     return BottomNavigation({
         items: navItems,
         currentIndex,
@@ -1641,53 +2111,54 @@ export const BottomNav = ({ items = [], currentRoute } = {}) => {
 `;
 
 export const sidebarJs = () => `// components/layouts/Sidebar.js
-import { Container, Column, Row, Text, Icon, colors, goTo } from 'flet-box';
+import { Container, Column, Row, Text, Icon, colors, goTo, getCurrentPath } from 'flet-box';
 
-export const Sidebar = ({ items = [], currentRoute } = {}) => {
+// Scaffold re-runs this on every route change, so the active item can read the
+// route itself instead of being rebuilt by the app.
+export const Sidebar = ({ items = [] } = {}) => {
     const defaultItems = [
-        { icon: 'dashboard', label: 'Dashboard', route: '/home' },
-        { icon: 'info', label: 'About', route: '/about' },
-        { icon: 'home', label: 'Root', route: '/' }
+        { icon: 'home', label: 'Start here', route: '/' },
+        { icon: 'palette', label: 'Design system', route: '/home' },
+        { icon: 'tune', label: 'Preferences', route: '/about' }
     ];
     const menuItems = items.length ? items : defaultItems;
-    return Container({
-        width: 260,
+    const currentRoute = getCurrentPath();
+    // Scaffold puts this in a flex row *below* the app bar and sizes it with
+    // leftNavBarWidth, so the sidebar has to stay in flow. A position: fixed
+    // panel escapes that box: its header ends up hidden behind the bar and the
+    // width prop stops meaning anything.
+    return Column({
+        height: '100%',
         backgroundColor: colors.surface,
         borderRight: \`1px solid \${colors.border}\`,
-        height: '100vh',
-        position: 'fixed',
-        left: 0,
-        top: 0,
-        child: Column({
-            children: [
-                Container({
-                    padding: 24,
-                    backgroundColor: colors.primary,
-                    child: Column({
-                        alignItems: 'center',
-                        children: [
-                            Icon({ name: 'rocket_launch', size: 40, color: '#ffffff' }),
-                            Text({ text: 'FletBox', size: 20, weight: 'bold', color: '#ffffff', marginTop: 12 })
-                        ]
-                    })
+        children: [
+            Container({
+                padding: 24,
+                borderBottom: \`1px solid \${colors.border}\`,
+                child: Column({
+                    alignItems: 'center',
+                    children: [
+                        Icon({ name: 'rocket_launch', size: 40, color: colors.primary }),
+                        Text({ text: 'FletBox', size: 18, weight: 'bold', color: colors.text, marginTop: 12 })
+                    ]
+                })
+            }),
+            ...menuItems.map(item => Container({
+                padding: '12px 16px',
+                cursor: 'pointer',
+                backgroundColor: currentRoute === item.route ? colors.primaryBg : 'transparent',
+                borderLeft: currentRoute === item.route ? \`3px solid \${colors.primary}\` : 'none',
+                child: Row({
+                    gap: 12,
+                    alignItems: 'center',
+                    children: [
+                        Icon({ name: item.icon, size: 20, color: currentRoute === item.route ? colors.primary : colors.textSecondary }),
+                        Text({ text: item.label, size: 14, weight: currentRoute === item.route ? 'bold' : 'normal', color: colors.text })
+                    ]
                 }),
-                ...menuItems.map(item => Container({
-                    padding: '12px 20px',
-                    cursor: 'pointer',
-                    backgroundColor: currentRoute === item.route ? \`\${colors.primary}15\` : 'transparent',
-                    borderLeft: currentRoute === item.route ? \`3px solid \${colors.primary}\` : 'none',
-                    child: Row({
-                        gap: 12,
-                        alignItems: 'center',
-                        children: [
-                            Icon({ name: item.icon, size: 20, color: currentRoute === item.route ? colors.primary : colors.textSecondary }),
-                            Text({ text: item.label, size: 14, color: currentRoute === item.route ? colors.primary : colors.text })
-                        ]
-                    }),
-                    onclick: () => goTo(item.route)
-                }))
-            ]
-        })
+                onclick: () => goTo(item.route)
+            }))
+        ]
     });
 };
 `;
@@ -1698,21 +2169,22 @@ import { Drawer, DrawerItem, Container, Column, Text, Icon, colors, closeDrawer
 
 export const DrawerMenu = ({ items = [] } = {}) => {
     const defaultItems = [
-        { icon: 'dashboard', label: 'Dashboard', route: '/home' },
-        { icon: 'info', label: 'About', route: '/about' },
-        { icon: 'home', label: 'Root', route: '/' }
+        { icon: 'home', label: 'Start here', route: '/' },
+        { icon: 'palette', label: 'Design system', route: '/home' },
+        { icon: 'tune', label: 'Preferences', route: '/about' }
     ];
     const menuItems = items.length ? items : defaultItems;
     return Drawer({
         header: Container({
-            padding: 28,
-            backgroundColor: colors.primary,
+            padding: 24,
+            backgroundColor: colors.surface,
+            borderBottom: \`1px solid \${colors.border}\`,
             child: Column({
                 alignItems: 'center',
                 children: [
-                    Icon({ name: 'rocket_launch', size: 48, color: '#ffffff' }),
-                    Text({ text: 'FletBox', size: 18, weight: 'bold', color: '#ffffff', marginTop: 12 }),
-                    Text({ text: 'UI Framework', size: 12, color: 'rgba(255,255,255,0.8)' })
+                    Icon({ name: 'rocket_launch', size: 40, color: colors.primary }),
+                    Text({ text: 'FletBox', size: 18, weight: 'bold', color: colors.text, marginTop: 12 }),
+                    Text({ text: 'Starter app', size: 12, color: colors.textSecondary })
                 ]
             })
         }),
@@ -1723,7 +2195,7 @@ export const DrawerMenu = ({ items = [] } = {}) => {
             onPress: () => closeDrawer()
         })),
         footer: Container({
-            padding: 20,
+            padding: 16,
             borderTop: \`1px solid \${colors.border}\`,
             child: Text({ text: 'Version 1.0.0', size: 12, color: colors.textSecondary, align: 'center' })
         })
@@ -1734,6 +2206,10 @@ export const DrawerMenu = ({ items = [] } = {}) => {
 // App templates (blank, basic, full, sidebar, adaptive)
 export const blankAppJs = () => `// app.js - Blank template
 import { runApp, Container, Text, colors } from 'flet-box';
+// Registers this app's design tokens. Without it every screen paints
+// with the framework's own palette, and the file that looks like the design
+// system is decoration.
+import './database/themes.js';
 
 const App = () => Container({
     flex: 1,
@@ -1747,7 +2223,11 @@ runApp(App, 'root');
 `;
 
 export const basicAppJs = () => `// app.js - Basic template (AppBar + Drawer)
-import { runApp, Scaffold, colors } from 'flet-box';
+import { runApp, Scaffold, colors, useState, dimensions } from 'flet-box';
+// Registers this app's design tokens. Without it every screen paints
+// with the framework's own palette, and the file that looks like the design
+// system is decoration.
+import './database/themes.js';
 import { AppBarComponent } from './components/layouts/AppBarComponent.js';
 import { DrawerMenu } from './components/layouts/DrawerMenu.js';
 
@@ -1762,12 +2242,21 @@ const routes = {
     '/about': AboutScreen
 };
 
-const MyApp = () => Scaffold({
-    routes,
-    appBar: AppBarComponent({ title: 'FletBox', isMobile: false }),
-    drawer: DrawerMenu(),
-    backgroundColor: colors.background
-});
+// The drawer is only reachable through the AppBar's menu button, so the shell has
+// to know whether it is on a phone. Key-based state keeps the width across
+// re-renders; the resize listener is registered once, at module scope.
+const [viewportWidth, setViewportWidth] = useState('viewportWidth', dimensions.getWidth());
+dimensions.addListener(({ width }) => setViewportWidth(width));
+
+const MyApp = () => {
+    const isMobile = viewportWidth.valueOf() < 768;
+    return Scaffold({
+        routes,
+        appBar: AppBarComponent({ title: 'FletBox', isMobile }),
+        drawer: DrawerMenu(),
+        backgroundColor: colors.background
+    });
+};
 
 runApp(MyApp, 'root');
 `;
@@ -1775,6 +2264,10 @@ runApp(MyApp, 'root');
 export const fullAppJs =
   () => `// app.js - Full template (AppBar + Drawer + BottomNav)
 import { runApp, Scaffold, colors, useState, dimensions } from 'flet-box';
+// Registers this app's design tokens. Without it every screen paints
+// with the framework's own palette, and the file that looks like the design
+// system is decoration.
+import './database/themes.js';
 import { AppBarComponent } from './components/layouts/AppBarComponent.js';
 import { DrawerMenu } from './components/layouts/DrawerMenu.js';
 import { BottomNav } from './components/layouts/BottomNav.js';
@@ -1803,7 +2296,9 @@ const MyApp = () => {
         routes,
         appBar: AppBarComponent({ title: 'FletBox', isMobile }),
         drawer: DrawerMenu(),
-        bottomBar: isMobile ? BottomNav() : null,
+        // A function, not an element: Scaffold re-runs it on each route change,
+        // which is what keeps the active tab lit.
+        bottomBar: isMobile ? () => BottomNav() : null,
         backgroundColor: colors.background
     });
 };
@@ -1813,6 +2308,10 @@ runApp(MyApp, 'root');
 
 export const sidebarAppJs = () => `// app.js - Sidebar template (desktop only)
 import { runApp, Scaffold, colors } from 'flet-box';
+// Registers this app's design tokens. Without it every screen paints
+// with the framework's own palette, and the file that looks like the design
+// system is decoration.
+import './database/themes.js';
 import { AppBarComponent } from './components/layouts/AppBarComponent.js';
 import { Sidebar } from './components/layouts/Sidebar.js';
 import { RootScreen, HomeScreen, AboutScreen } from './screens/index.js';
@@ -1826,7 +2325,9 @@ const routes = {
 const MyApp = () => Scaffold({
     routes,
     appBar: AppBarComponent({ title: 'FletBox', isMobile: false }),
-    leftNavBar: Sidebar(),
+    // A function, not an element: Scaffold re-runs it on each route change,
+    // which is what keeps the active row lit.
+    leftNavBar: () => Sidebar(),
     backgroundColor: colors.background
 });
 
@@ -1836,6 +2337,10 @@ runApp(MyApp, 'root');
 export const adaptiveAppJs =
   () => `// app.js - Adaptive template (mobile + desktop)
 import { runApp, Scaffold, colors, useState, dimensions } from 'flet-box';
+// Registers this app's design tokens. Without it every screen paints
+// with the framework's own palette, and the file that looks like the design
+// system is decoration.
+import './database/themes.js';
 import { AppBarComponent } from './components/layouts/AppBarComponent.js';
 import { DrawerMenu } from './components/layouts/DrawerMenu.js';
 import { BottomNav } from './components/layouts/BottomNav.js';
@@ -1860,6 +2365,16 @@ const routes = {
 const [viewportWidth, setViewportWidth] = useState('viewportWidth', dimensions.getWidth());
 dimensions.addListener(({ width }) => setViewportWidth(width));
 
+// One menu, three surfaces: the drawer and the bottom bar on a phone, the
+// sidebar on a desktop. The labels stay short because the bottom bar has to fit
+// all four across a 360px screen.
+const menu = [
+    { icon: 'home', label: 'Start', route: '/' },
+    { icon: 'palette', label: 'System', route: '/home' },
+    { icon: 'tune', label: 'Preferences', route: '/about' },
+    { icon: 'person', label: 'Profile', route: '/profile' }
+];
+
 const MyApp = () => {
     // Structural read of the keyed viewport state, so crossing the breakpoint
     // re-renders the shell (drawer + bottom bar <-> sidebar).
@@ -1867,9 +2382,11 @@ const MyApp = () => {
     return Scaffold({
         routes,
         appBar: AppBarComponent({ title: 'FletBox', isMobile }),
-        drawer: isMobile ? DrawerMenu() : null,
-        bottomBar: isMobile ? BottomNav() : null,
-        leftNavBar: !isMobile ? Sidebar() : null,
+        drawer: isMobile ? DrawerMenu({ items: menu }) : null,
+        // Functions, not elements: Scaffold re-runs them on each route change,
+        // which is what keeps the active item lit.
+        bottomBar: isMobile ? () => BottomNav({ items: menu }) : null,
+        leftNavBar: !isMobile ? () => Sidebar({ items: menu }) : null,
         backgroundColor: colors.background
     });
 };
@@ -1896,7 +2413,8 @@ export const agentsMd = (appName, template, version) =>
     '',
     'This file is the contract. Read it before writing any code in this project.',
     'You do **not** need to read the whole framework to work here — sections 1 to 3',
-    'tell you where the authoritative answers live, and the checker in section 4',
+    'tell you where the authoritative answers live, the design system in section 4',
+    'fixes every size and color you may use, and the checker in section 5',
     'proves you right or wrong in seconds.',
     '',
     '## 1. The API is a fact, not a guess',
@@ -1907,8 +2425,11 @@ export const agentsMd = (appName, template, version) =>
     '| --- | --- |',
     '| Which widgets exist and which props each accepts | `.fletbox/api/cheatsheet.md` (generated, covers every widget) |',
     '| Everything for one widget | `npm run check -- --props <Widget>` |',
+    '| Whether a prop actually reaches the DOM, or is typed but dead | `flet-box unpack <Widget>` |',
+    '| A call that is safe to paste | `flet-box unpack <Widget> --example` |',
     '| Prose, types and a worked example | `node_modules/flet-box/docs/widget/<Widget>.md` |',
     '| Every public export of the package | `npm run check -- --list` |',
+    '| The whole surface as data, to build calls from | `.fletbox/api/api.json` |',
     '',
     '**If a name is not in those files, it does not exist.** A prop that silently',
     'does nothing is worse than a compile error: it renders as a broken layout and',
@@ -1917,6 +2438,10 @@ export const agentsMd = (appName, template, version) =>
     '- Do not edit `node_modules/flet-box`. It is a dependency, not source.',
     '- The cheatsheet is generated output. Regenerate it with',
     '  `flet-box check-api --emit-api` after upgrading the package; never hand-edit it.',
+    '- `.fletbox/api/api.json` and `api.md` are generated the same way:',
+    '  `npm run api`. They carry one entry per prop with its engine target, default,',
+    '  aliases and a `sample` value, so a call can be written from data instead of',
+    '  memory.',
     '',
     '## 2. FletBox syntax only — no other framework',
     '',
@@ -1968,8 +2493,10 @@ export const agentsMd = (appName, template, version) =>
     '  routes,',
     "  appBar: AppBarComponent({ title: 'FletBox', isMobile }),",
     '  drawer: isMobile ? DrawerMenu() : null,',
-    '  bottomBar: isMobile ? BottomNav() : null,',
-    '  leftNavBar: !isMobile ? Sidebar() : null,   // NOT `sidebar:`',
+    '  // Functions, not elements: Scaffold re-runs a bar on every route change,',
+    '  // which is how the active item learns where the reader is.',
+    '  bottomBar: isMobile ? () => BottomNav() : null,',
+    '  leftNavBar: !isMobile ? () => Sidebar() : null,   // NOT `sidebar:`',
     '  leftNavBarWidth: 240,',
     "  fab: isMobile ? ActionButton({ icon: 'add', onPress: open }) : null,",
     '  body: isMobile ? null : HomeScreen(),',
@@ -2006,7 +2533,73 @@ export const agentsMd = (appName, template, version) =>
     'broken, prove it with a minimal repro and record the finding in memory** — do',
     'not work around it silently.',
     '',
-    '## 4. Verification loop (required)',
+    '## 4. Design system — one scale, three colors',
+    '',
+    'A screen is designed, not decorated. Every size and every color on this app',
+    'comes from the two lists below. A value outside them is a bug you have to',
+    'justify, and `padding: 13` or `#4f46e5` written by hand is the usual sign a',
+    'screen drifted away from the rest.',
+    '',
+    '**Color: three roles, no more.**',
+    '',
+    '| Role | Token | Where it may appear |',
+    '| --- | --- | --- |',
+    '| Brand | `colors.primary` | the one action the screen asks for: primary button, active tab, focus ring, links |',
+    '| Emphasis | `colors.secondary` | a deliberate second voice: gradients, badges, a highlighted stat |',
+    '| Feedback | `colors.success` / `colors.warning` / `colors.danger` / `colors.dangerStrong` | status only — never as decoration; the last one is the red you may write words in |',
+    '',
+    'Everything else is neutral: `colors.background`, `colors.surface`,',
+    '`colors.card`, `colors.text`, `colors.textSecondary`, `colors.textDisabled`,',
+    '`colors.border`, `colors.divider`, plus the `gray50`…`gray900` ramp. Rules:',
+    '',
+    '- A screen uses **one** brand color. Two accent colors competing on one view',
+    '  means one of them is wrong.',
+    '- Never type a hex or `rgb()` literal. If a token is missing, add it to a',
+    '  `theme.js` in this app that re-exports `colors` — do not scatter the value.',
+    '- A frosted surface is `colors.glass` with `colors.glassBorder` plus a',
+    '  `backdropFilter`. It reads through to whatever is behind it, so there',
+    '  should be imagery or a gradient there, never body copy.',
+    '- Text on a dark or brand fill is white, and it stays white: hierarchy comes',
+    '  from size and weight, not from fading the ink to `rgba(255,255,255,.72)` —',
+    '  faded white on `colors.primary` measures 3.16:1 and stops being body text.',
+    '- `error` ≡ `danger`, and `*Bg` variants exist for alert fills. As **words**,',
+    '  `colors.danger` is 3.76:1 on white and fails AA: write `colors.dangerStrong`',
+    '  for the label of a delete or an inline error (6.47:1 on white, 5.42:1 inside',
+    '  `colors.errorBg`), and keep `colors.danger` for the dot, the border, the icon.',
+    '  Same reason `colors.warning` and `colors.success` are plates, never sentences.',
+    '  Measure any pair before arguing about it: `npm run ui -- --tokens`.',
+    '',
+    '**Space and type: an 8-based scale.** Use these numbers and nothing between',
+    'them. They are plain props (`padding`, `gap`, `margin`, `width`, `height`,',
+    '`size`, `radius`) — the factory takes the number, no unit and no `px` string.',
+    '',
+    '```',
+    'spacing   4  ·  hairline, icon inset',
+    '          8  ·  tight gaps, chip padding',
+    '         12  ·  control padding (input/button height − text)',
+    '         16  ·  default card padding, section gap, screen gutter',
+    '         18  ·  card-to-card rhythm on a dense grid',
+    '         24  ·  between sections, page gutter',
+    '         32  ·  between page blocks',
+    '         40  ·  the smallest tap target, a roomy control',
+    '         48  ·  hero spacing',
+    '         64 / 96  ·  a full-bleed section, a landing hero',
+    'radius     4 / 8 / 12 / 16 / 999 (pill)',
+    'type      12 caption · 14 body-small · 16 body · 18 subtitle · 24 title',
+    '          32 headline · 40 / 48 display (a hero, a big number)',
+    'weight    400 body · 500 label · 600 title · 700 headline',
+    'line-height  1.5 body · 1.2 heading',
+    '```',
+    '',
+    '- Padding inside a card is `16`; the gap between cards is `16` or `24`. Never',
+    '  mix the two on the same list.',
+    '- One text size per element, one weight per role. If a label and its value are',
+    '  the same size, the hierarchy is carried by color, not by a fourth size.',
+    '- Tap targets are at least `40` on a side; get there with `height`, not padding.',
+    '- `useState` bindings, `flex` and `gap` do the layout. Reach for an absolute',
+    '  offset only for overlays, and use `stackPosition` rather than raw coordinates.',
+    '',
+    '## 5. Verification loop (required)',
     '',
     'After every edit, before you say a task is done:',
     '',
@@ -2014,14 +2607,29 @@ export const agentsMd = (appName, template, version) =>
     'npm run check          # static gate: invented widgets/props, positional args,',
     '                       # foreign imports, and broken imports between your own',
     '                       # modules (a name a file never exports)',
+    'npm run ui             # clean-UI gate: the tokens and the scale above, 40px',
+    '                       # targets, labels, contrast — every finding cites the',
+    '                       # rule number it broke',
     'npm run dev            # serve on :8000 — check the UI actually renders',
     '```',
     '',
-    '`npm run check` exits non-zero on a real error. Fix the code, not the checker.',
-    'It reads the installed package, so it is always in sync with what runs. A',
+    'Both gates read the installed package, so they are always in sync with what',
+    'runs. They exit non-zero on a real error: fix the code, not the checker. A',
     'warning is allowed to stay only when you can justify it in one sentence.',
     '',
-    '## 5. Memory — do not relearn the same thing',
+    '`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),',
+    '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.',
+    '',
+    'When the error is a mistyped name, `npm run fix` rewrites it for you — a',
+    'relative path that does not resolve, a name the target module never exports,',
+    'an identifier used without its `import`, and a prop key the API does not know',
+    '(`chilldren` → `children`, `bgColr` → `bgColor`). It only rewrites when exactly',
+    'one real name is close enough; anything ambiguous is printed untouched for you',
+    'to decide. Run `npm run check` again after it, and read the diff.',
+    '',
+    '## 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',
@@ -2036,13 +2644,18 @@ export const agentsMd = (appName, template, version) =>
     '  to be wrong rather than appending a correction beside it.',
     '- Commit memory files with the code change they describe.',
     '',
-    '## 6. Commands',
+    '## 7. Commands',
     '',
     '| Command | What it does |',
     '| --- | --- |',
     '| `npm run dev` | static dev server on port 8000 |',
     '| `npm run check` | anti-hallucination gate over `src/` |',
+    '| `npm run fix` | rewrite mistyped imports and prop names it can prove |',
     '| `npm run check -- --props Button` | print the real props of a widget |',
+    '| `flet-box unpack Button` | everything Button accepts **and that actually works** |',
+    '| `flet-box unpack Button --example` | a paste-ready call using only live props |',
+    '| `flet-box unpack Button --diff` | doc vs code gaps: dead, invented, undocumented |',
+    '| `npm run api` | rebuild `.fletbox/api/api.json` + `api.md` for the whole surface |',
     '| `npm run build` | esbuild bundle into `dist/` |',
     '| `flet-box build android` / `ios` | Capacitor native build |',
     '| `flet-box run-native android` | compile and launch on device/emulator |',
@@ -2057,8 +2670,24 @@ export const claudeMd = () =>
     '# CLAUDE.md',
     '',
     'The rules for this project live in [AGENTS.md](./AGENTS.md). Read it first and',
-    'follow it exactly — FletBox syntax only, real props only, `npm run check` after',
-    'every edit.',
+    'follow it exactly — FletBox syntax only, real props only.',
+    '',
+    'Two shortcuts replace guessing:',
+    '',
+    '- `flet-box unpack <Widget>` prints every prop the widget really honors, with',
+    '  its type, default and engine target. `--example` gives a call you can paste,',
+    '  `--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,',
+    '  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',
+    '  · 32 · 40 · 48.',
+    '',
+    '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.',
@@ -2079,9 +2708,18 @@ export const cursorRules = () =>
     '- Widgets are function calls returning an element: `Text({ text: "Hi", size: 18 })`.',
     '  No JSX, no positional args, no Flutter/Vue/Svelte/React syntax or imports.',
     '- Before using a widget or prop you have not just seen in',
-    '  `.fletbox/api/cheatsheet.md`, look it up: `npm run check -- --props <Widget>`.',
-    '  If it is not listed, it does not exist — do not invent it.',
-    '- Run `npm run check` after every change and fix what it reports.',
+    '  `.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',
+    '  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.',
+    '  See AGENTS.md §4.',
+    '- Run `npm run check` after every change (does this API exist) and `npm run ui`',
+    '  (is this screen clean: tokens, scale, 40px targets, labels, contrast). Fix',
+    '  what they report; a warning stays only with a one-sentence reason.',
     '- Check `.fletbox/memory/MEMORY.md` at session start; record new non-obvious',
     '  findings there instead of re-deriving them.',
     '',
@@ -2165,3 +2803,547 @@ export const checkAppScript = (appName) =>
     'process.exit(exitCode);',
     '',
   ].join('\n');
+
+// ---------------------------------------------------------------------------
+// Clean-UI skill
+// ---------------------------------------------------------------------------
+// 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 = () =>
+  [
+    "---",
+    "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.",
+    "---",
+    "",
+    "# 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.",
+    "",
+    "- 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).",
+    "",
+    "## 05 One purpose per screen",
+    "",
+    "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');
+
+/**
+ * The app-side twin of scripts/check-app.mjs for the clean-UI gate. Same
+ * resolution dance, because the package exports map only publishes "." and
+ * "./package.json".
+ *
+ * @param {string} appName
+ * @returns {string}
+ */
+export const checkUiScript = (appName) =>
+  [
+    '// scripts/check-ui.mjs',
+    `// Clean-UI gate for ${appName}: tokens, the 8-based scale, tap targets, field`,
+    '// labels and measured WCAG contrast, checked by the installed flet-box.',
+    '//',
+    '//   npm run ui              scan src/ and fail on a real finding',
+    '//   npm run ui -- --tokens  print the measured contrast of every token',
+    '//   npm run ui -- --strict  contrast warnings fail the run too',
+    '//   npm run ui -- --json    machine-readable findings',
+    '',
+    "import path from 'node:path';",
+    "import { createRequire } from 'node:module';",
+    "import { pathToFileURL } from 'node:url';",
+    '',
+    "const require = createRequire(import.meta.url);",
+    '',
+    'function resolvePackage() {',
+    "  const candidates = [path.resolve(process.cwd(), 'node_modules/flet-box')];",
+    '  try {',
+    "    candidates.push(path.dirname(require.resolve('flet-box/package.json')));",
+    '  } catch {',
+    '    /* not installed yet */',
+    '  }',
+    "  const fs = require('fs');",
+    '  for (const dir of candidates) {',
+    "    if (fs.existsSync(path.join(dir, 'bin/commands/checkUi.js'))) return dir;",
+    '  }',
+    "  console.error('flet-box package not found. Run: npm install');",
+    '  process.exit(1);',
+    '}',
+    '',
+    "const checker = path.join(resolvePackage(), 'bin', 'commands', 'checkUi.js');",
+    "const { checkUi } = await import(pathToFileURL(checker).href);",
+    '',
+    "const { exitCode } = await checkUi(process.argv.slice(2));",
+    'process.exit(exitCode);',
+    '',
+  ].join('\n');