@wix/himalaya-cli 0.1618.0 → 0.1619.0

package/guides/android-ux.md

@@ -1,39 +1,76 @@
 # Designing a Himi App for Android
 
-Apply the official [Android design guidance](https://developer.android.com/design) throughout
-planning, implementation, and review. Keep the product intent shared with iOS; use Android-native
-expectations when they materially change navigation, back behaviour, feedback, or adaptation.
+Read this before you write `MOBILE-UX.md`, and again before you compose a screen. Each pattern
+below is a decision, the Himi field that implements it, and the Android page it comes from. Read
+it with `himi docs ios-ux` (https://apps.wix.com/_api/himi-serve/docs/ios-ux.md): iPhone and Android
+render the **same** descriptor, so a decision you make here is made for iPhone too.
 
-## Plan
+## What Android does for you, and what it cannot do
 
-- Define the Android back path for every flow, especially sheets, search, selection, and forms.
-- Design for compact and expanded windows from the start; Android's
-  [adaptive layout guidance](https://developer.android.com/design/ui/mobile/guides/layout-and-content/adapt-layout)
-  is the reference.
-- Make loading, empty, error, permission, offline, and destructive states actionable.
-- Plan TalkBack, scalable text, contrast, reduced motion, RTL, and touch targets. Use Android's
-  [accessibility guidance](https://developer.android.com/design/ui/mobile/guides/foundations/accessibility)
-  for the current requirements.
+A Himi screen is one descriptor that the Android shell renders with Jetpack Compose and
+Material 3. Three things are native without any work from you, and you should not redraw them:
 
-## Author
+- **Chrome the shell draws:** the navigation bar at the bottom, the top app bar and its title,
+  system and predictive Back, the search bar, bottom sheets and dialogs.
+- **Controls the renderer draws:** `Toggle` is a Material switch, `SegmentedControl` a
+  segmented button, `Picker`/`DatePicker`/`Menu`/`BottomSheet`/`AlertDialog` the Material ones.
+- **Your type scale:** typography tokens are emitted in `sp` and follow the user's font scale.
 
-- Express intent through Himi semantic components and tokens; let the Android renderer supply the
-  native interaction model rather than recreating Material chrome in the descriptor.
-- Prefer responsive grids, split views, and shell navigation. Use `defineView(surface)` only when
-  the screen's job differs by surface.
-- Treat `@himalaya/app-info` as an exceptional, asynchronous behavioural fallback—not a layout or
-  theme selector. Use capability availability for platform feature support.
+One thing it **cannot** do: give Android a different layout from iPhone. Lists, cards and inset
+sections draw the same on every renderer. Choose one structure and say so
+in `MOBILE-UX.md`. Per-platform *look* — type face, corner radius, spacing — is the
+`material` token overlay (see **Idiom overlay** in `himi docs ios-ux`), not a second screen.
+The overlay may change type face, radius and spacing; it may not change a brand colour.
+`himi render --platform android` changes the switch, the segmented button, and the type face.
+A list or a grid looks the same in the iPhone PNG. That is one descriptor, not a failed render.
 
-## Audit
+## Patterns
+
+| Decision | Do this on Android | Himi mapping | Android source |
+| --- | --- | --- | --- |
+| Top-level destinations | Navigation bar of three to five destinations on a phone. | `navigation` tabs in `config.ts` (`himi docs app-config`); the shell draws the bar. | [Navigation bar](https://m3.material.io/components/navigation-bar/guidelines) |
+| Screen title | Top app bar with the screen title. | Set the screen's `title`. Do not repeat it, or the app name, as Text in the body in any style. Today's Android shell leaves the top-bar title slot empty, so a body title would show twice on iPhone and still not as a bar title here. A group's name is the `Section` `header`. A render with no large heading at the top is correct when `title` is set. `himi render --platform android` draws the Material switch and segmented button. | [Top app bar](https://m3.material.io/components/top-app-bar/guidelines) |
+| Back | System Back, including the predictive back gesture, closes transient UI before it leaves the screen. | The shell handles Back. Plan the order in `MOBILE-UX.md`: an open sheet, search or selection closes first. | [Predictive back](https://developer.android.com/design/ui/mobile/guides/patterns/predictive-back) |
+| Completing a flow (Book, Pay, Confirm) | One filled button at the bottom of the content. | `stickyFooter` holding one `Button` with `style: "primary"` and `fullWidth: true`. The same footer serves iPhone. | [Buttons](https://m3.material.io/components/buttons/guidelines) |
+| Creating, adding, editing, saving | An action in the top app bar. | `topBar.items: [{ id, placement: "trailing", label, icon, onTap, role: "confirm" }]`. It is a top-app-bar action here and a bar button on iPhone. | [Top app bar](https://m3.material.io/components/top-app-bar/guidelines) |
+| Floating action button | Material's create affordance, but a shared screen also draws it on iPhone. | Prefer the `topBar.items` action. Use `Fab` only when the app is deliberately Android-first, and write down that iPhone shows it too. | [FAB](https://m3.material.io/components/floating-action-button/guidelines) |
+| Collections people choose by photo (products, books, portfolio, projects) | A lazy grid of image tiles, or a carousel of covers; the tile is the tap target. | `Grid` `columns: 2` (`columnsMedium: 3`, `columnsExpanded: 4`); a gallery `columns: 3`, `spacing: 2`; a shelf a horizontal `LazyList` sized so the next cover peeks at 360dp. Each tile is an `Image` (`fillWidth`, fixed `aspectRatio`, `contentMode: "fill"`, `placeholder`, `contentDescription`) with the name and price under it and `modifiers.onTap` on the tile; no `Card` or button per tile. The same grid renders on iPhone. | [Lazy grids](https://developer.android.com/develop/ui/compose/lists#lazy-grids), [Carousel](https://m3.material.io/components/carousel/guidelines) |
+| Lists and grouped content | List rows with supporting text; group related settings under a header. | `LazyList` of `ListItem` rows for a schedule or a service menu; `Section` (`header`, optional `inset: true`) for a group. Do not wrap each row in a `Card`. One featured object may be a single `Card`. Choices that may not fit the width, such as times, go in a `LazyList` with `horizontal: true`. The same structure renders on iPhone. | [Lists](https://m3.material.io/components/lists/guidelines) |
+| On/off, one of a few, pick a date | Switch, segmented button, menu or dialog picker. | `Toggle` (`label`, `value`): the `label` is the row drawn beside the switch. `SegmentedControl` with `options: [{ id, label }]` — `label` is required, and `title` on an option fails native decode and drops the whole screen. `Picker`, `DatePicker`. Group the rows in a `Section`, not a `Card`. | [Switch](https://m3.material.io/components/switch/guidelines), [Segmented buttons](https://m3.material.io/components/segmented-buttons/guidelines) |
+| A short task on top of a screen | A modal bottom sheet, dismissed by Back or the scrim. | `BottomSheet`. A new destination is a navigation instead. | [Bottom sheets](https://m3.material.io/components/bottom-sheets/guidelines) |
+| Destructive or blocking decision | A dialog that names the action. | `AlertDialog`; confirm or offer undo. | [Dialogs](https://m3.material.io/components/dialogs/guidelines) |
+| Success | A snackbar above the navigation bar. | `ui.snackbar` from the worker. | [Snackbar](https://m3.material.io/components/snackbar/guidelines) |
+| Search | A search bar in the top app bar, or a dedicated search screen. | `topBar.searchable` plus the page's own `SearchField` (or the row that holds it) with `hiddenPath: "$env:topBarSearch"`. The standard app shell draws that field; only a host with a native search handler hides it for the bar. A dedicated screen when search starts a new task (`himi docs recipe-search`). | [Search](https://m3.material.io/components/search/guidelines) |
+| Tablets, foldables, wide windows | List and detail side by side from the expanded width class (840dp and wider); a readable column for reading. | `SplitView`, `Grid` `columnsMedium`/`columnsExpanded`, `contentMaxWidth`. Render at 840px or wider and record the choice. | [Adaptive layouts](https://developer.android.com/design/ui/mobile/guides/layout-and-content/adapt-layout) |
+| Type and shape | The Material type scale and shape scale, following the user's font size. | Typography tokens from the built-in ramp, no raw sizes; a `material` overlay in `tokens.json` `idiom` with `"$system"` (Roboto) and Material radii, turned on by `idiom: { policy: "follow-surface" }` in `config.ts`. | [Typography](https://m3.material.io/styles/typography/applying-type) |
+| Touch targets | At least 48×48dp. | Use `Button`/`ListItem`; do not shrink a hit area. | [Accessibility](https://developer.android.com/design/ui/mobile/guides/foundations/accessibility) |
+| Edge to edge | Content draws under the system bars; nothing important sits behind them. | The shell applies the insets; keep the last row clear of `stickyFooter`. | [Edge-to-edge](https://developer.android.com/design/ui/mobile/guides/layout-and-content/edge-to-edge) |
+
+## Settings, copied as props
+
+A settings screen is one `Section` (`inset: true`, `header`), not a stack of `Card`s, and it has no `title1` Text in the body. A `Toggle`'s `label` is the row the renderer draws beside the switch. A `ListItem` `title` with the same word paints it a second time. A row that drills in stays a `ListItem`.
 
-- Drive the installed Android app—not only a phone-width render—through system Back from transient
-  UI, typed input and keyboard submit, completion, touch exploration/TalkBack, enlarged text, dark
-  scheme, error recovery, and compact plus expanded width. Record the result for every declared
-  state in `MOBILE-UX.md`'s acceptance matrix.
-- Check each documented Android variance against `MOBILE-UX.md` and its official source.
+## Plan
+
+In `MOBILE-UX.md` → `## Platform decisions`, fill the Android column of each row from the table
+above: navigation, title, back order, primary action, create/add, lists and grouped content, photo collections,
+controls, sheets and dialogs, search, expanded width, and type/idiom. Give the official URL.
+
+Also plan TalkBack labels on every icon and image, font scale, contrast in light and dark,
+reduced motion, right-to-left, and permission, offline and error states.
+
+## Audit
 
-## Route to official guidance
+Render each primary screen with `--platform android` at a compact width (`--width 360`) and at
+an expanded width (`--width 840`), in light and with `--scheme dark`. Check: the primary action
+in the footer or the top bar, no floating button unless the plan chose it, no hand-drawn
+controls, no heading and no app name added to stand in for the empty top-bar title, a schedule
+made of `ListItem` rows rather than a `Card` per row, products, books and photos as image tiles
+with every image filled and none stretched, a rail that shows part of its next item, a horizontal
+choice row that still shows its last item, and an expanded layout that is either adaptive or recorded as an
+intentional single column.
 
-- [Android design](https://developer.android.com/design)
-- [Adaptive layouts](https://developer.android.com/design/ui/mobile/guides/layout-and-content/adapt-layout)
-- [Accessibility](https://developer.android.com/design/ui/mobile/guides/foundations/accessibility)
+On an installed Android app, drive system Back from every transient UI, typed input and
+keyboard submit, completion, TalkBack, enlarged text, dark theme, error recovery, and compact
+plus expanded width. Record the result in the `MOBILE-UX.md` acceptance matrix; with no device,
+record `himi ux record --status unavailable` with the reason.

package/guides/component-reference.json

@@ -789,8 +789,11 @@
       "name": "Section",
       "category": "Structure & disclosure",
       "propsType": "SectionProps",
-      "bindings": [],
-      "propsSource": "export interface SectionProps {\n  header?: string;\n  footer?: string;\n  children?: Component[];\n  inset?: boolean;\n}"
+      "bindings": [
+        "header",
+        "footer"
+      ],
+      "propsSource": "export interface SectionProps {\n  /** Section caption — binding-aware (\"$service:\") on web, iOS and Android. */\n  header?: string;\n  /** Section caption — binding-aware (\"$service:\") on web, iOS and Android. */\n  footer?: string;\n  children?: Component[];\n  inset?: boolean;\n}"
     },
     {
       "name": "DisclosureGroup",

package/guides/component-reference.md

@@ -83,7 +83,7 @@ See also **[Modifiers](#modifiers)** (the `modifiers` block) and **[Actions](#ac
 | `Popover` | Overlays & menus | `presentedPath` |
 | `Chip` | Chips & selection | `selectedPath`, `tokenPath` |
 | `ChipsInput` | Chips & selection | `valuesPath` |
-| `Section` | Structure & disclosure | — |
+| `Section` | Structure & disclosure | `header`, `footer` |
 | `DisclosureGroup` | Structure & disclosure | `expandedPath` |
 | `LabeledContent` | Structure & disclosure | — |
 | `Label` | Structure & disclosure | — |
@@ -1565,7 +1565,9 @@ export interface ChipsInputProps {
 
 ```ts
 export interface SectionProps {
+  /** Section caption — binding-aware ("$service:") on web, iOS and Android. */
   header?: string;
+  /** Section caption — binding-aware ("$service:") on web, iOS and Android. */
   footer?: string;
   children?: Component[];
   inset?: boolean;

package/guides/designing-himi-screens.md

@@ -18,6 +18,35 @@ prescriptive layer that sits **above** the wiring guide: `himi docs tier-5-add-a
 > `.agents/skills/himalaya/examples/stocks-dashboard.descriptor.json` into the app — a
 > fully-composed screen to study.
 
+**A phone screen, before anything below.** Read `himi docs ios-ux` and `himi docs android-ux` too;
+they decide what a phone screen looks like, and this guide decides how to compose it.
+
+- **The title lives in the bar, not the body.** Set the screen's `title`; the shell draws it. Do
+  not open the body with the screen title, the app name or a greeting as `largeTitle`/`title1`
+  text. `himi render` does not draw the bar, so a PNG that starts with content is correct.
+- **A collection is rows, not a card per item.** A schedule, a service menu, a session list or a
+  settings group is `ListItem` rows — in a root `LazyList`, or in one `Section` with `inset: true`
+  and a `header`. Time, price, coach or duration go in the row's `subtitle`/`trailing`; a small
+  action (Book, Full) goes in `trailing`. One featured object may be a single `Card`.
+- **When people choose by the photo, the photo leads.** Products, books, a portfolio and projects
+  are image tiles, not rows with a small thumbnail: a `Grid` with `columns: 2` (`columnsMedium: 3`,
+  `columnsExpanded: 4`) for products and projects, `columns: 3` with `spacing: 2` and no captions
+  for a photo gallery, and a horizontal `LazyList` of covers for each shelf. A tile is one `Image`
+  (`fillWidth: true`, a fixed `aspectRatio`, `contentMode: "fill"`, `placeholder`,
+  `contentDescription`) with the name and price as text under it, and the whole tile is the tap
+  target (`modifiers.onTap`). No `Card` and no button on each tile. A collection without photos
+  stays rows.
+- **Choices that may not fit go sideways.** Days and times are a `LazyList` with
+  `horizontal: true`, so the last chip stays reachable at 390 points. Size a rail of covers or
+  cards so part of the next one shows at 390 points (a cover about 110 points wide, a card about
+  160), or nothing tells the reader the rail scrolls.
+- **A detail screen opens with its photos.** A product, a book or a project starts with its image
+  (a paged `Carousel` when there are several), edge to edge with a fixed height: the root `VStack`
+  has no padding, the image is its first child, and the name, price and options follow in a
+  `VStack` that carries the 16-point gutter.
+- **The step that finishes the task sits in `stickyFooter`** — one primary `Button`, not a button
+  inside the last card.
+
 ---
 
 ## 1. The materials at a glance
@@ -58,7 +87,8 @@ Screen root gets consistent padding — `padding: { leading: 16, trailing: 16,
 `surfacePrimary` root reads well. Tight, even spacing is most of what makes a screen look "designed."
 
 ### Typography — use the scale, don't invent
-`title1` for the one screen heading, `title3` for a sub-heading/stat, `body` for content, `caption`
+`title1` for a heading inside the body that is not the screen title (a featured card, an empty
+state, an onboarding page — the screen title itself is the screen's `title` field), `title3` for a sub-heading/stat, `body` for content, `caption`
 for secondary/meta, `bodyEmphasis` when you need weight inside body copy. Do **not** introduce new
 sizes or weights inline to "make it bigger" — that's a token change, deliberated once, not a per-screen
 decision.
@@ -190,10 +220,10 @@ tiles; `Card` to group a related cluster onto a raised `surfaceSecondary`; `Sect
 group; `Divider` for a hairline separation; `Spacer` to push apart within a row; `SplitView` for
 responsive master/detail. *Reach for `Card` to cluster, not to wrap every single element.*
 
-**Lists & collections** — `LazyList` for long/unbounded scrolls (virtualized); `Grid` for a 2-up gallery
-(`columns: 1, columnsMedium: 2`); `Table` for tabular rows; `Carousel`/`Pager` for swipeable panels;
+**Lists & collections** — `LazyList` for long/unbounded scrolls (virtualized); `Grid` for photo tiles
+(`columns: 2, columnsMedium: 3` for products, `columns: 3` for a photo gallery); `Table` for tabular rows; `Carousel`/`Pager` for swipeable panels;
 `Timeline` for chronological events. Compose rows as `ListItem` / `LabeledContent` / `DisclosureGroup`
-cells inside a `Card([VStack(spacing: 0)])`.
+cells in one `Section` with `inset: true` (or directly in a root `LazyList`) — never one `Card` per row.
 > For a feed/list *screen*, put a vertical worker-bound `LazyList` directly in a plain root
 > `VStack`, as the screen's only bound list: the root carries padding and a literal background at
 > most, is leading-aligned, starts with a child that is always shown, and holds no `Spacer` or
@@ -233,7 +263,8 @@ long-form Ricos content rather than flattening it into text rows.*
 **Inputs & forms** — field controls: `TextField` (with `keyboard`/`autoCapitalization`/`secure`),
 `SearchField`, `Toggle`, `Stepper`, `Slider`, `SelectionControl` (checkbox/radio),
 `Picker`/`WheelPicker`, `DatePicker`, `ColorPicker`, `OtpInput`, `ChipsInput`. *Reach for `Toggle` for
-on/off, `SelectionControl` for pick-from-set — not a row of `Button`s.*
+on/off, `SelectionControl` for pick-from-set — not a row of `Button`s.* A `Toggle`'s `label` is the
+row drawn beside the switch; a `ListItem` `title` with the same word paints it a second time.
 
 **Search** — use a dedicated search screen by default when search starts from a broader context
 (such as Home or a catalog); keep search inline when it only filters the list already on screen.
@@ -293,7 +324,7 @@ Use a live `title` binding to announce “Adding to cart” while pending; `load
 
 **Navigation** — `Tabs` / `SegmentedControl` to switch peer views; `Pager` + `PageControl` for
 full-width swipe; `StepIndicator` for a wizard's progress; `CollapsingHeader` for a large-title-to-inline
-scroll. *Reach for `SegmentedControl` for 2–4 in-content modes; `Tabs`/tab-bar for top-level sections.*
+scroll. *Reach for `SegmentedControl` for 2–4 in-content modes; `Tabs`/tab-bar for top-level sections.* Each option is `{ id, label }`. `label` is required — `title` on an option fails native decode and drops the whole screen. `title` belongs on `Button` and `ListItem`.
 > **`Pager` sizes each page to its natural content height** (it doesn't stretch to fill), and multi-line
 > text inside a page **truncates** — so onboarding/carousel slides need *short* titles + an explicit
 > `maxLines`, and you can't vertically center a slide with a `spacer()` inside the page (put the spacer
@@ -339,9 +370,10 @@ Concrete patterns lifted from real usage:
 - **Row with a leading label and trailing detail** — `hstack({ spacing: 8, children: [ icon, text, spacer(), trailingText ] })`. The `spacer()` does the push; don't hand-pad.
 - **Fill-width controls share a row** — put fill-width controls in **one** `HStack` and let them share it (weight/flex), rather than stacking `fillMaxWidth` elements. This is a real iOS↔Android parity requirement, not a preference — a full-width control alone in an HStack renders differently across platforms.
 - **A screen that owns its top bar (search beside back)** — set `topBar: { leading: "none" }` and put the row in `stickyHeader`: `hstack([ iconButton({ icon: "arrow_left", accessibilityLabel: "Back", action: { actionId: "nav.back", presentation: "back" } }), withModifiers(textField({ placeholder: "Search", … }), { weight: 1 }) ])`. With **both** set, every shell draws no bar and no back control of its own (iOS hides the system bar, Android floats no chevron and reserves no band, web hides its bar on every look), so the row is the only top bar. `leading: "none"` without a `stickyHeader` keeps the bar's title and trailing actions but drops the back control (and the hamburger, for that screen). System back — hardware, gesture, edge swipe, browser — still pops. Any other `leading` value keeps today's chrome; demo: `gallery_search_topbar`, linked from the gallery's "Lists & data".
-- **Cell list** — `card([ vstack({ spacing: 0, alignment: "leading", children: [ …ListItem cells… ] }) ])`. `spacing: 0` because the cells own their own dividers/padding.
+- **Cell list** — one `Section` with `inset: true` and a `header`, its children the `ListItem` cells; the cells own their own dividers and padding. A schedule, a service menu and a session list are this shape too, not a `Card` around each item.
+- **Photo tile** — `vstack({ spacing: 6, alignment: "leading", children: [ image({ url, fillWidth: true, aspectRatio: 0.8, contentMode: "fill", placeholder: "surfaceSecondary", contentDescription }) + cornerRadius 8, text(name, "body"), text(price, "callout", { color: "textSecondary" }) ] })` with `modifiers.onTap` on the stack, inside `grid({ columns: 2, columnsMedium: 3, columnsExpanded: 4, spacing: 12 })`. A shelf is the same tile at a fixed `width` (about 110) in `lazyList({ horizontal: true, spacing: 12 })`.
 - **Overlay** — `zstack({ alignment: "center", children: [ backdropImage(cornerRadius 12), withModifiers(label, { padding, background: { token: "accentPrimary" }, cornerRadius: 10 }) ] })`.
-- **Responsive** — `grid({ columns: 1, columnsMedium: 2, spacing: 12 })` for 1-up on phone / 2-up on tablet; `splitView({ primary, detail, primaryMaxWidth: 280 })` for master/detail that stacks on a phone; set `contentMaxWidth` in tokens so wide surfaces keep a readable column instead of running edge-to-edge.
+- **Responsive** — `grid({ columns: 1, columnsMedium: 2, spacing: 12 })` for wide cards, 1-up on phone / 2-up on tablet (photo tiles start at 2 on a phone); `splitView({ primary, detail, primaryMaxWidth: 280 })` for master/detail that stacks on a phone; set `contentMaxWidth` in tokens so wide surfaces keep a readable column instead of running edge-to-edge.
 - **Centered separator, not a flanked divider** — the classic "—— or ——" needs each `divider()` to take equal remaining width, and the HStack row-share only kicks in for controls with an intrinsic fill. **A bare `divider()` inside an HStack is a column separator, not a flanking line**: iOS, macOS, Android, web and React Native all draw it as a thin vertical rule the height of the row that takes no share of the width, which is right for a stats row (`12 | 340 | 87`) and wrong for "—— or ——". For "—— or ——", use a **centered caption**: `hstack({ children: [spacer(), text("or continue with", "caption", { color: "textSecondary" }), spacer()] })`, optionally over a single full-width `divider()`.
 
 > **Intrinsic-fill controls grab the row.** `Button` and `TextField` have an intrinsic FILL, so the next four idioms are about NOT letting that surprise you (they were the papercuts every off-repo app hit):
@@ -590,7 +622,7 @@ nicety. Don't animate everything: if every element moves, nothing reads as impor
   A screen full of `id`s and no `accessibility_label`s is testable but unusable with VoiceOver/TalkBack.
   It may be bound to worker state with `$service:<service>.<path>`; the web renderer keeps the
   resulting `aria-label` current as that state changes.
-- **Tap targets** stay comfortably large (don't shrink `button`/`icon` hit areas below ~44pt).
+- **Tap targets** stay comfortably large: at least 44pt on iOS and 48dp on Android — don't shrink `button`/`icon` hit areas below that.
 - **Contrast** comes from the token roles — pair `textPrimary`/`textSecondary` with the right surface,
   and provide the `highContrast` scheme value for load-bearing colors.
 - **Reduced motion** — §6.
@@ -672,6 +704,7 @@ Run this punch list on the screen (it's also a good reviewer checklist):
 - [ ] Verified in **both** light and dark (and highContrast for load-bearing color)?
 - [ ] RTL-safe — leading/trailing alignment + logical insets throughout?
 - [ ] Kit-clean — no hardcoded look a kit would override; `material`/gradient/background precedence respected?
+- [ ] Platform-clean — the shell draws the tab bar, title and Back (none redrawn in the body); the primary action sits in `stickyFooter` or a trailing `topBar.items` entry, not a `Fab` an iPhone would also show; switches, segmented choices, pickers, sheets and alerts are the native components (`himi docs ios-ux`, `himi docs android-ux`)?
 - [ ] Fast (§7b) — long or paged lists at the scroll root, stable row ids, `nav` on taps whose destination is fixed, short rails, fixed-size row images?
 
 ---
@@ -681,7 +714,7 @@ Run this punch list on the screen (it's also a good reviewer checklist):
 The demo gallery's `layout()` is a compact model of the
 principles:
 
-- **Type scale, not sizes** — `title1` heading, `body` content, `caption` secondary, colored via
+- **Type scale, not sizes** — `title1` for a heading inside a card, `body` content, `caption` secondary, colored via
   `textPrimary`/`textSecondary`/`accentPrimary` tokens (never hex), `maxLines: 1` to truncate.
 - **Card = cluster** — related copy grouped in `card([ vstack({ spacing: 4, alignment: "leading" }) ])`
   on `surfaceSecondary`, not scattered.

package/guides/getting-started.md

@@ -33,7 +33,8 @@ and template-preview journey below. Write the reconstruction plan, `SPEC.md`,
 same-site One App visitor binding, checks and hosted draft. Obtain the
 site owner's agreement before creating or updating an OAuth client for optional
 member flows; visitor reads and native email/password sign-in need no client.
-Before composing content, read `himi docs designing-himi-screens` and apply the
+Before composing content, read `himi docs ios-ux`, `himi docs android-ux` and
+`himi docs designing-himi-screens`, and apply the
 migration guide's screen-content contract: readable detail sections, stable rail
 and image sizing, grouped icon rows for More, native bottom clearance and distinct
 loading/empty/error states. Put the relevant cases in `MOBILE-UX.md` and verify

package/guides/himi-skill.md

@@ -56,7 +56,8 @@ and template-preview journey below. Write the reconstruction plan, `SPEC.md`,
 same-site One App visitor binding, checks and hosted draft. Obtain the
 site owner's agreement before creating or updating an OAuth client for optional
 member flows; visitor reads and native email/password sign-in need no client.
-Before composing content, read `himi docs designing-himi-screens` and apply the
+Before composing content, read `himi docs ios-ux`, `himi docs android-ux` and
+`himi docs designing-himi-screens`, and apply the
 migration guide's screen-content contract: readable detail sections, stable rail
 and image sizing, grouped icon rows for More, native bottom clearance and distinct
 loading/empty/error states. Put the relevant cases in `MOBILE-UX.md` and verify

package/guides/ios-ux.md

@@ -1,40 +1,119 @@
 # Designing a Himi App for iOS
 
-Apply [Apple Human Interface Guidelines](https://developer.apple.com/design/human-interface-guidelines/)
-while planning, building, and reviewing—not only at the end. Keep the task and brand shared with
-Android; respect iOS conventions when they alter a user's learned expectation.
+Read this before you write `MOBILE-UX.md`, and again before you compose a screen. Each pattern
+below is a decision, the Himi field that implements it, and the Apple page it comes from. Read
+it with `himi docs android-ux` (https://apps.wix.com/_api/himi-serve/docs/android-ux.md): iPhone
+and Android render the **same** descriptor, so a decision you make here is made for Android too.
+
+## What iOS does for you, and what it cannot do
+
+A Himi screen is one descriptor that the iOS shell renders with SwiftUI. Three things are
+native on iPhone without any work from you, and you should not redraw them:
+
+- **Chrome the shell draws:** the tab bar, the navigation bar and its title, Back and the edge
+  swipe, the search field in the bar, sheets and alerts.
+- **Controls the renderer draws:** `Toggle` is a `UISwitch`, `SegmentedControl` is a segmented
+  control, `Picker`/`DatePicker`/`Menu`/`BottomSheet`/`AlertDialog` are the system ones.
+- **Your type scale:** typography tokens scale with Dynamic Type.
+
+One thing it **cannot** do: give iPhone a different layout from Android. Lists, cards and inset
+sections draw the same on every renderer. Choose one structure and say so
+in `MOBILE-UX.md`; do not plan "inset grouped on iPhone, full-bleed on Android", because no Himi
+screen can deliver it. Per-platform *look* — type face, corner radius, spacing — is a token
+overlay (see **Idiom overlay** below), not a second screen. `himi render --platform ios` changes
+the switch, the segmented control, and the type face. A list or a grid looks the same in the
+Android PNG. That is one descriptor, not a failed render.
+
+## Patterns
+
+| Decision | Do this on iOS | Himi mapping | Apple source |
+| --- | --- | --- | --- |
+| Top-level destinations | Tab bar of three to five destinations; the shell draws it. | `navigation` tabs in `config.ts` (`himi docs app-config`). Never a row of buttons at the bottom of a screen. | [Tab bars](https://developer.apple.com/design/human-interface-guidelines/tab-bars) |
+| Screen title | Large title on a tab's root screen, collapsing as it scrolls; inline title on a pushed screen. | Set the screen's `title`; the shell makes a root screen's title large on its own. `topBar.titleDisplay: "large" \| "inline"` overrides it. Do not repeat the title, or the app name, as Text in the body in any style. A group's name is the `Section` `header`, not a heading above it. `himi render` does not draw that bar — pass `--platform ios` so the controls match iPhone, and judge the title by the `title` field. A PNG with no large heading at the top is correct when `title` is set. | [Navigation bars](https://developer.apple.com/design/human-interface-guidelines/navigation-bars) |
+| Back | Back button plus edge swipe; the system owns both. | Push with navigation actions; the shell adds Back. Only `topBar.leading: "none"` with a `stickyHeader` replaces the bar, and system back still works. | [Navigation and search](https://developer.apple.com/design/human-interface-guidelines/navigation-and-search) |
+| Completing a flow (Book, Pay, Confirm) | One prominent button at the bottom, above the home indicator. | `stickyFooter` holding one `Button` with `style: "primary"` and `fullWidth: true`, on a `surfacePrimary` background with padding. | [Buttons](https://developer.apple.com/design/human-interface-guidelines/buttons) |
+| Creating, adding, editing, saving | A bar button in the navigation bar, trailing. | `topBar.items: [{ id, placement: "trailing", label, icon, onTap, role: "confirm" }]`. It is a bar button on iPhone and a top-app-bar action on Android. | [Toolbars](https://developer.apple.com/design/human-interface-guidelines/toolbars) |
+| Floating action button | Not an iOS pattern. | Avoid `Fab` in a shared screen: it draws on iPhone too. Use the trailing `topBar.items` entry instead. | [Toolbars](https://developer.apple.com/design/human-interface-guidelines/toolbars) |
+| Grouped content (settings, profile, booking details) | Inset grouped sections with a header and footer. | `Section` with `inset: true`, `header`, `footer`; rows are `ListItem` (`accessory: "chevron"` to drill in). The same sections render on Android. | [Lists and tables](https://developer.apple.com/design/human-interface-guidelines/lists-and-tables) |
+| Collections people choose by photo (products, books, portfolio, projects) | A collection of image tiles; the tile is the tap target. | `Grid` `columns: 2` (`columnsMedium: 3`, `columnsExpanded: 4`); a gallery `columns: 3`, `spacing: 2`; a shelf of covers a horizontal `LazyList` sized so the next cover peeks at 390 points. Each tile is an `Image` (`fillWidth`, fixed `aspectRatio`, `contentMode: "fill"`, `placeholder`, `contentDescription`) with the name and price under it and `modifiers.onTap` on the tile; no `Card` or button per tile. A detail screen opens with its photos edge to edge. | [Collections](https://developer.apple.com/design/human-interface-guidelines/collections), [Images](https://developer.apple.com/design/human-interface-guidelines/images) |
+| Long collections without photos (schedule, services, settings-like lists) | A plain scrolling list; the row is the tap target. | Root `LazyList` of `ListItem` rows; one primary action per row at most; `pagination` for more. A class and a service are `ListItem`s, not one `Card` each. One featured object may be a single `Card`. Choices that may not fit the width, such as times, go in a `LazyList` with `horizontal: true`, so the last choice is reachable at 390 points. | [Lists and tables](https://developer.apple.com/design/human-interface-guidelines/lists-and-tables) |
+| On/off, one of a few, pick a date | The system switch, segmented control, picker. | `Toggle` (`label`, `value`): the `label` is the row drawn beside the switch. `SegmentedControl` with `options: [{ id, label }]` — `label` is required, and `title` on an option fails native decode and drops the whole screen. `Picker`, `DatePicker`. Never a row of buttons or a drawn switch. | [Toggles](https://developer.apple.com/design/human-interface-guidelines/toggles), [Segmented controls](https://developer.apple.com/design/human-interface-guidelines/segmented-controls) |
+| A short task on top of a screen | A sheet; Cancel and Done in its bar. | `BottomSheet`. A new destination is a push instead. | [Sheets](https://developer.apple.com/design/human-interface-guidelines/sheets) |
+| Destructive or blocking decision | An alert, with the destructive button styled as such. | `AlertDialog`, or a `ToolbarItem` with `role: "destructive"`. Confirm or offer undo. | [Alerts](https://developer.apple.com/design/human-interface-guidelines/alerts) |
+| Success | Brief, non-blocking feedback. | `ui.snackbar` from the worker, not an alert. | [Feedback](https://developer.apple.com/design/human-interface-guidelines/feedback) |
+| Search | A search field in the navigation bar. | `topBar.searchable` plus the page's own `SearchField` (or the row that holds it) with `hiddenPath: "$env:topBarSearch"`. The standard app shell draws that field; only a host with a native search handler hides it for the bar. A dedicated search screen when search starts a new task (`himi docs recipe-search`). | [Search fields](https://developer.apple.com/design/human-interface-guidelines/search-fields) |
+| iPad and wide windows | Sidebar or split view for collections; a readable column for reading. | `SplitView`, `Grid` `columnsMedium`/`columnsExpanded`, `contentMaxWidth` in tokens. Render at 834px and record the choice. | [Split views](https://developer.apple.com/design/human-interface-guidelines/split-views) |
+| Type | The system text styles, scaled by Dynamic Type. | Typography tokens from the built-in ramp: `largeTitle`, `title1`–`title3`, `headline`, `body`, `bodyEmphasis`, `callout`, `caption`, `footnote`. No raw sizes. | [Typography](https://developer.apple.com/design/human-interface-guidelines/typography) |
+| Touch targets | At least 44×44 points. | Use `Button`/`ListItem`; do not shrink an icon's hit area below that. | [Accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility) |
+
+## Settings, copied as props
+
+A settings screen is one `Section`, not a stack of `Card`s, and it has no `title1` Text in the body. The screen `title` is the heading. A `Toggle`'s `label` is the row the renderer draws beside the switch. A `ListItem` `title` with the same word paints it a second time. A row that drills in stays a `ListItem` (`title`, `accessory: "chevron"`).
+
+```jsonc
+"type": "Section",
+"props": { "inset": true, "header": "Preferences", "children": [ /* Toggle, then SegmentedControl */ ] }
+
+"type": "SegmentedControl",
+"props": {
+  "selectedId": "auto",
+  "options": [
+    { "id": "light", "label": "Light" },
+    { "id": "dark", "label": "Dark" },
+    { "id": "auto", "label": "Automatic" }
+  ]
+}
+```
+
+`Button` and `ListItem` take `title`. A segment takes `label`. Mixing those up is what drops the screen on device.
+
+## Idiom overlay — the iOS look without a second screen
+
+The brand stays the same on both phones. What may differ is the platform's dialect: the system
+face, softer or sharper corners, spacing. That lives in `tokens.json`, as a named overlay the
+iOS runtime merges over your base tokens:
+
+```jsonc
+// tokens.json — an overlay may only restyle tokens the base already declares
+"idiom": {
+  "ios":      { "typography": { "body": { "family": "$system", "size": 17, "weight": 400, "line": 1.3 } }, "radius": { "md": 10 } },
+  "material": { "typography": { "body": { "family": "$system", "size": 16, "weight": 400, "line": 1.5 } }, "radius": { "md": 12 } }
+}
+```
+
+```ts
+// config.ts — declaring the block turns it on; each phone picks its own overlay
+idiom: { policy: "follow-surface" },
+```
+
+`"$system"` is SF Pro on an iPhone and Roboto on Android. Keep each typography entry complete
+(`size`, `weight`, `line`), or the theme fails to decode on device. An overlay cannot change a
+brand colour (`accentPrimary`, `accentSecondary`, `accentSurface`, `textOnAccent`); that is
+deliberate, so one brand reads as one brand.
 
 ## Plan
 
-- Choose navigation around user destinations, with one clear primary action per screen.
-- Let the iOS shell own system navigation and chrome; do not reproduce bars or gestures in a
-  descriptor.
-- Specify input, confirmation, cancellation, destructive-action recovery, and empty states.
-- Include dynamic type, VoiceOver, contrast, reduced motion, and right-to-left content from the
-  first screen map. Use Apple's [accessibility guidance](https://developer.apple.com/design/human-interface-guidelines/accessibility)
-  for the current requirements.
-
-## Author
-
-- Use Himi semantic components, logical leading/trailing alignment, accessibility labels, and
-  token-based typography and colour. Native renderers preserve the expected iOS behaviour.
-- Preserve comfortably sized touch targets; Apple documents 44×44 points as the standard control
-  target.
-- Prefer responsive projection for iPad and macOS width. Use `defineView(surface)` only where the
-  content or task differs—not merely because the canvas is larger.
-- Use `@himalaya/app-info` only for a documented runtime behavioural fallback. It must not become
-  a layout switch.
+In `MOBILE-UX.md` → `## Platform decisions`, write one row for each of: navigation, title,
+back, primary action, create/add, lists and grouped content, photo collections, controls, sheets and alerts,
+search, expanded width, and type/idiom. Fill the Himi mapping with the field from the table
+above and the official source with its URL.
 
-## Audit
+Also plan Dynamic Type, VoiceOver labels on every icon and image, contrast in light and dark,
+reduced motion, and right-to-left, from the first screen map.
 
-- Drive the installed iOS app—not only a phone-width render—through back/cancel, typed input and
-  keyboard submit, completion, failure, Dynamic Type, VoiceOver, dark appearance, and reduced
-  motion. Record the result for every declared state in `MOBILE-UX.md`'s acceptance matrix.
-- Compare every deliberate iOS difference with the `MOBILE-UX.md` decision record.
+## Audit
 
-## Route to official guidance
+Render each primary screen with `himi render <screen> --device iphone --platform ios --png <file>`
+and again with `--scheme dark` and at `--device ipad --platform ios`. `--platform ios` draws the
+iPhone switch and segmented control. The navigation bar is still the shell's, so a missing title
+in the PNG is not a missing `title` field. Check: the screen's `title` is set, no heading and no
+app name in the body, a schedule is `ListItem` rows rather than a `Card` per row, products,
+books and photos are image tiles with every image filled and none stretched, a rail shows part of
+its next item, a horizontal choice row still shows its last item, the primary action in the footer or the bar
+(never floating), no hand-drawn switch or segmented control, and nothing hidden behind the home
+indicator.
 
-- [Navigation and hierarchy](https://developer.apple.com/design/human-interface-guidelines/navigation-and-search)
-- [Tab bars](https://developer.apple.com/design/human-interface-guidelines/tab-bars)
-- [Typography](https://developer.apple.com/design/human-interface-guidelines/typography)
-- [Accessibility](https://developer.apple.com/design/human-interface-guidelines/accessibility)
+On an installed iOS app, drive back and edge swipe, typed input and keyboard submit,
+completion, failure, Dynamic Type, VoiceOver and dark appearance. Record the result for every
+declared state in the `MOBILE-UX.md` acceptance matrix; with no device, record
+`himi ux record --status unavailable` with the reason.

package/guides/mobile-ux.md

@@ -18,7 +18,10 @@ the approved acceptance scenarios as the readiness bar for the private preview.
    data sources, platform envelope, screen catalogue, and non-goals.
 2. Write `MOBILE-UX.md`: task flows, every screen state, accessibility and localisation needs,
    motion, and platform decisions.
-3. Apply the iOS and Android guides while planning, then again while authoring and reviewing.
+3. Read `himi docs ios-ux` (https://apps.wix.com/_api/himi-serve/docs/ios-ux.md) and
+   `himi docs android-ux` (https://apps.wix.com/_api/himi-serve/docs/android-ux.md) in full
+   **before** filling `## Platform decisions`, then apply them again while authoring and
+   reviewing. They map each Apple and Material pattern to the Himi field that builds it.
 4. Build shared Himi screens from the contract. Keep the two documents with the app so the next
    author can extend the experience without rediscovering its decisions.
 
@@ -87,6 +90,14 @@ perform the customer task, says what is unavailable, and cannot write customer d
 ## Platform decisions
 | Shared intent | iOS behaviour | Android behaviour | Himi mapping | Official source |
 | --- | --- | --- | --- | --- |
+| Top-level navigation | | | | |
+| Title and back | | | | |
+| Primary action | | | | |
+| Create / add | | | | |
+| Lists and grouped content | | | | |
+| Controls, sheets, alerts | | | | |
+| Expanded width | | | | |
+| Type and idiom | | | | |
 
 ## Implementation acceptance
 | Flow or declared state | Trigger | Expected visible result | Primary CTA | Render / device evidence |
@@ -287,10 +298,16 @@ target file.
 Use the least expensive option that preserves the task:
 
 1. **One descriptor, responsive projection** — the normal case. Use semantic components, size
-   classes, grids, split views, and shell navigation.
-2. **One worker, surface-specific view** — use `defineView(surface)` when a phone, desktop, or
-   wrist answers a materially different question. See [authoring per surface](authoring-per-surface.md).
-3. **Tier-0 native screen** — use only when native APIs or interaction are the point of the screen.
+   classes, grids, split views, and shell navigation. The shell and the native controls already
+   look like iOS on an iPhone and like Material on Android.
+2. **Idiom overlay** — when iPhone and Android should differ in *look* (type face, radius,
+   spacing) but not in structure: a `tokens.json` `idiom` block with `ios` and `material`
+   overlays, turned on by `idiom: { policy: "follow-surface" }` in `config.ts`. It cannot change
+   brand colours. See `himi docs ios-ux` → Idiom overlay.
+3. **One worker, surface-specific view** — use `defineView(surface)` when a phone, desktop, or
+   wrist answers a materially different question. Surfaces are form factors (`phone`, `tablet`,
+   `desktop`, `watch`, …), not operating systems: there is no iPhone-only or Android-only view.
+4. **Tier-0 native screen** — use only when native APIs or interaction are the point of the screen.
 
 Do not create per-node OS conditionals in a descriptor. The wire model stays platform-blind.
 

package/guides/skill.md

@@ -9,6 +9,24 @@ description: Guide a business from a mobile-app idea to a browser-reviewed priva
 
 You are the customer's mobile-product partner and implementation agent. Take them from an idea to a working, **owner-private** web preview. Do not make the customer paste a long setup prompt or force them to understand Himalaya terminology.
 
+## Required design-guide reading for coding agents
+
+This page is long; if your tool shows only its start, read the rest from the saved output. Before
+you write `MOBILE-UX.md`, and again before you compose the first screen, fetch each of these four
+public guides by its own URL and read it in full (or `himi docs <id>` from the installed CLI):
+
+- https://apps.wix.com/_api/himi-serve/docs/mobile-ux.md — the product and UX contract.
+- https://apps.wix.com/_api/himi-serve/docs/ios-ux.md — Apple's patterns mapped to the Himi field that builds each one.
+- https://apps.wix.com/_api/himi-serve/docs/android-ux.md — Material's patterns mapped the same way.
+- https://apps.wix.com/_api/himi-serve/docs/designing-himi-screens.md — composing one screen from components and tokens.
+
+A grep or summarized excerpt does not satisfy this. The iOS and Android guides are what make the
+app native: the shell already draws the tab bar, title and Back on each platform, a shared `Fab`
+also draws on iPhone, lists render the same on every renderer, and per-platform look comes from a
+`tokens.json` `idiom` overlay, not from a second screen. Fill `## Platform decisions` from
+them, with each official source as a URL. Do not add a customer approval gate just for reading
+these public guides.
+
 ## One App migration route — before generic discovery
 
 When the user invokes `himi one-app migrate`, or you are continuing that user's
@@ -27,7 +45,8 @@ and template-preview journey below. Write the reconstruction plan, `SPEC.md`,
 same-site One App visitor binding, checks and hosted draft. Obtain the
 site owner's agreement before creating or updating an OAuth client for optional
 member flows; visitor reads and native email/password sign-in need no client.
-Before composing content, read `himi docs designing-himi-screens` and apply the
+Before composing content, read `himi docs ios-ux`, `himi docs android-ux` and
+`himi docs designing-himi-screens`, and apply the
 migration guide's screen-content contract: readable detail sections, stable rail
 and image sizing, grouped icon rows for More, native bottom clearance and distinct
 loading/empty/error states. Put the relevant cases in `MOBILE-UX.md` and verify
@@ -70,6 +89,11 @@ These are agent instructions, not a claim that the CLI enforces a reading or ret
    - **Write this skeleton into `MOBILE-UX.md`, then fill it in.** `himi validate --strict` and `himi ux audit --strict` read these exact headings and columns, so a plan written in your own structure fails the gate after approval, when rewriting it is most expensive. Keep both headings spelled as shown, give the acceptance table a `Primary CTA` column with one row per state and exactly one CTA per cell (`none` is an answer; a comma-, semicolon- or slash-separated list is not), and under `## Evidence` write the widths you actually rendered — one compact (at most 599px) and one wider (at least 600px); `himi render <screenId> --device iphone` renders 390px and `--device ipad` renders 834px. Your own sections (flows, states, accessibility, platform decisions) go around these. The full contract is `himi docs mobile-ux` (https://apps.wix.com/_api/himi-serve/docs/mobile-ux.md before the CLI is installed).
 
      ```markdown
+     ## Platform decisions
+     | Shared intent | iOS behaviour | Android behaviour | Himi mapping | Official source |
+     | --- | --- | --- | --- | --- |
+     | Primary action | <from ios-ux> | <from android-ux> | <stickyFooter or topBar.items> | <developer.apple.com/design/… and m3.material.io/… URLs> |
+
      ## Implementation acceptance
      | Flow or declared state | Trigger | Expected visible result | Primary CTA | Render / device evidence |
      | --- | --- | --- | --- | --- |

package/guides/tier-5-add-a-screen.md

@@ -159,6 +159,8 @@ one object either way.
 
 So a text-input reducer is `setDraft: (s, p) => ({ ...s, draft: String(p?.value ?? "") })`, bound with `onChange: { actionId: "tier5.notes.setDraft" }`.
 
+**Annotate that payload.** `defineService` gives an unannotated second parameter the type `never`, so `p.value` and `p.selectedId` fail `himi validate --strict` even when the read is the one in the table. Write the parameter's type: `setDraft: (s, p: { value?: unknown } | undefined) => ({ ...s, draft: String(p?.value ?? "") })`. A `SegmentedControl` handler names `selectedId` on that same type.
+
 **The payload argument can be absent.** A host calls the reducer with one merged object when
 `params`/`args` carry anything, and with **no argument at all** when both are empty — so the
 second parameter is `undefined`, not `{}`. A device always injects `{ value }` for the controls in

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wix/himalaya-cli",
-  "version": "0.1618.0",
+  "version": "0.1619.0",
   "type": "module",
   "description": "himi — the Himalaya authoring CLI. Build a Tier-5 content package on your own machine, push it to the production serve as a draft, preview it on web + Himi Player, and read worker logs back — the remote dev loop. Wraps @himalaya/serve-cli for transport.",
   "keywords": [
@@ -72,5 +72,5 @@
       "artifactId": "himalaya-cli"
     }
   },
-  "falconPackageHash": "53661afff21585080db36c8653b597e5ec6bbe96697d7157bf90ee05"
+  "falconPackageHash": "d9d834feab74f884aec00e986ae13ed5dcb2f5fea15f6ea9ac2e5796"
 }

package/templates/brandy/dev/index.ts

@@ -347,10 +347,11 @@ export default {
   config,
   homeScreenId: "site_home",
   screens: {
-    // A fresh copy per build: descriptors are pure functions of the site block.
+    // A fresh copy per build: descriptors are pure functions of the site block. A JSON round
+    // trip, not structuredClone: `himi test` builds screens in the contained realm, which withholds it.
     exact: {
-      ...Object.fromEntries(Object.keys(SCREENS).map((id) => [id, () => structuredClone(SCREENS[id])])),
-      himi_notification_settings: () => structuredClone(NOTIFICATIONS),
+      ...Object.fromEntries(Object.keys(SCREENS).map((id) => [id, () => JSON.parse(JSON.stringify(SCREENS[id]))])),
+      himi_notification_settings: () => JSON.parse(JSON.stringify(NOTIFICATIONS)),
     },
     templated: [],
   },