@cavulsqa/create 2.9.2 → 2.10.0

package/templates/m3e-app/.claude/skills/m3-expressive/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: m3-expressive
+description: Material 3 Expressive UI in this app. Use for any screen, component, layout, animation, transition, sheet, dialog, menu, list, button, progress or loading state, colour or theme change, icon, or app-bar work - before writing markup.
+---
+
+# Material 3 Expressive
+
+This app is Material 3 Expressive end to end. Framework7 is only the navigation engine (router, tab
+views, page lifecycle); everything visible is an `M3*` component from `@cavulsqa/m3e-vue`, styled by
+`--md-sys-*` tokens from `@cavulsqa/m3e`. Expressive is not decoration: shape, spring and tonal
+colour say _what is happening_ - a selection rounds off, a sheet springs, progress waves while work
+moves. Every number comes from Google's Compose tokens; [sources.md](sources.md) links each spec.
+
+## Building a screen
+
+1. **Name the job in one sentence** and the nearest Google app that does it (Messages, Photos,
+   Settings, Files, Wallet). Open its pattern on m3.material.io from [sources.md](sources.md).
+2. **Pick the component** from [components.md](components.md). Every visible element is an `M3*`
+   component or Tailwind layout around one. Missing a component? It belongs in
+   `packages/m3e-vue`, built from its spec page - not a one-off in a module.
+3. **Wrap the route in `AppPage`** (`shared/components/page`): tab roots get the large flexible app
+   bar, pushed pages pass `back`. Layout rules: [layout.md](layout.md).
+4. **Choose shape, colour role and motion** - [shapes-type.md](shapes-type.md),
+   [color.md](color.md), [motion.md](motion.md). Each decision names its token.
+5. **Strings in both locales**, icons from Material Symbols (`<i-ms-name-rounded />`), filled
+   variant for a selected state.
+6. **Done means**: `vp check`, `pnpm type-check` and `vp test` pass; you checked light, dark, a 360dp
+   width, reduced motion, and RTL by reasoning or on screen; and you said plainly whether you saw it
+   run. Type-checking proves nothing about how a screen looks.
+
+## The rules every screen keeps
+
+- **Tokens only.** Colour is a role (`bg-surface-container-low`, `text-on-primary-container`),
+  corners are the shape scale (`rounded-lg`, `rounded-xl`), type is a style (`type-title-medium`),
+  shadows are levels (`shadow-1`..`shadow-5`). Tailwind's own palette is deleted from the theme, so
+  only roles resolve; a hex value belongs in `src/app/theme.config.ts` and nowhere else.
+- **Pairs travel together.** A container role always carries its `on-` role:
+  `bg-tertiary-container text-on-tertiary-container`. Text on a surface is `text-on-surface` or
+  `text-on-surface-variant`.
+- **Surfaces stack by container tone**, not by shadow: page `surface`, grouped content
+  `surface-container-low`, raised panels `surface-container`/`-high`. Shadows only on what floats.
+- **Overlays come from the services**: `useSnackbar`, `useDialog`, `useActionSheet` (auto-imported),
+  or `M3BottomSheet`/`M3Menu` with `v-model:open`. They register on the overlay stack, so Android
+  back and Escape close the top one. Never hand-build a modal.
+- **One tap target per row.** A list row's own button lives in `M3ListItem`'s `#action` slot, never
+  inside a clickable row.
+- **Motion is spatial or effects.** Position, size and shape use the spatial springs; colour and
+  opacity the effects springs. Never animate `width`/`top` of a large surface - `transform` and
+  `opacity`.
+- **Reduced motion keeps meaning, drops travel**: morphs and fades stay, rotation, bounce and slide
+  go. The tokens collapse spatial durations to 1 ms for you; JS-driven motion reads
+  `useReducedMotion()`.
+- **Every control is labelled**: icon buttons, FABs and switches take `label`; it becomes the
+  accessible name and tooltip.
+- **Empty is a state, not a blank.** `EmptyState` (shape, one sentence, the one action that fills it).
+  Waits under ~5 s show `M3LoadingIndicator`; known progress shows the wavy indicators.
+
+## Where things live
+
+| Need                          | Use                                                              |
+| ----------------------------- | ---------------------------------------------------------------- |
+| A screen                      | `AppPage` + modules/`<feature>`/views                            |
+| Section label                 | `SectionHeader`                                                  |
+| Theme state                   | `useThemeSettings()` - seed, variant, contrast, mode, motion     |
+| Shell navigation              | `useActiveTab()` (`show`, `open(tab, path)`), `useWindowClass()` |
+| Hide the bar on a pushed page | `AppPage back` does it; elsewhere `useHiddenNavigation()`        |
+| Decorative tone for a shape   | `TONE_CLASSES` from `shared/utils/tone`                          |
+| Live component examples       | the Gallery tab - `modules/gallery/components/sections`          |

package/templates/m3e-app/.claude/skills/m3-expressive/color.md

@@ -0,0 +1,44 @@
+# Colour
+
+One seed (`BRAND_SEED` in `src/app/theme.config.ts`) generates every role in both modes through
+material-color-utilities' 2025 (Expressive) spec. The user can change seed, variant and contrast in
+the colour studio; `useThemeSettings()` persists it and repaints in one frame. Dark mode is a `.dark`
+class on `<html>` - both modes are always in the stylesheet, so switching regenerates nothing.
+
+## Roles to reach for
+
+| Purpose                                                     | Role                                                                 |
+| ----------------------------------------------------------- | -------------------------------------------------------------------- |
+| Page background                                             | `surface`                                                            |
+| Grouped content, list segments, cards on a page             | `surface-container-low`                                              |
+| Raised panels, the nav bar, bars over scrolled content      | `surface-container` / `-high`                                        |
+| Text fields, inactive tracks                                | `surface-container-highest`                                          |
+| Main emphasis (FAB, hero, selected nav)                     | `primary-container` + `on-primary-container`                         |
+| Strong action fill                                          | `primary` + `on-primary`                                             |
+| Selected or active but quiet (chips, list rows, indicators) | `secondary-container`                                                |
+| Contrasting accent, decorative variety                      | `tertiary-container`                                                 |
+| Snackbar, tooltips                                          | `inverse-surface` + `inverse-on-surface`, action `inverse-primary`   |
+| Errors and destructive                                      | `error`, `error-container`                                           |
+| Success, warning                                            | custom groups `success-*`, `warning-*` (theme.config `EXTRA_COLORS`) |
+| Hairlines                                                   | `outline-variant`; field borders `outline`                           |
+| Secondary text, icons                                       | `on-surface-variant`                                                 |
+
+Disabled content is `on-surface` at 38%, disabled containers `on-surface` at 10-12% - the components
+already do this.
+
+## Variants and the spec trap
+
+Material applies the 2025 rules only to **tonalSpot, expressive, vibrant, neutral**. `brand`
+(seed exact as `primary-container`, Theme Builder's "Match colour"), fidelity, content, monochrome,
+rainbow and fruitSalad silently use 2021 rules - `effectiveSpec(variant)` says which. The studio shows
+it to the user.
+
+## Rules
+
+- A new semantic colour is a custom group in `EXTRA_COLORS` (harmonised to the seed), then a role
+  name in `assets/css/theme/tailwind.css` - never a hex in a component.
+- Contrast is a user setting (standard / medium / high): never compensate a weak pair by hand-picking
+  a darker colour; fix the role choice.
+- Status needs more than colour: pair it with a shape or glyph (see `STATUS_LOOK` in the demo module).
+
+See [sources.md](sources.md) → Colour.

package/templates/m3e-app/.claude/skills/m3-expressive/components.md

@@ -0,0 +1,325 @@
+# Component catalogue
+
+Every component is auto-imported by `M3eResolver`; write the tag, never an import. Composables
+(`useSnackbar`, `useDialog`, `useActionSheet`, `useHaptics`, `useReducedMotion`) are auto-imported
+too. Each section names the spec page to read when a detail is not covered here.
+
+## Actions
+
+**`M3Button`** - `variant` filled | tonal | outlined | elevated | text, `size` xs | s | m | l | xl,
+`shape` round | square, `toggle` + `v-model:selected`, slots `#icon` (receives `selected`), `#trailing`.
+Hierarchy: one filled action per screen region; tonal for secondary; outlined/text below that. Size
+`s` is the default for in-content actions, `m` for a screen's primary action and sheet footers, `l`/`xl`
+for hero moments only. → buttons/specs
+
+**`M3IconButton`** - `label` required, `variant` standard | filled | tonal | outlined, `width` narrow |
+default | wide, `size`, `shape`, `toggle`. App-bar actions are `standard`; a toolbar's emphasised
+action is `filled`. → icon-buttons/specs
+
+**`M3ButtonGroup`** - `variant` standard (pressed button widens 15%, neighbours give way) or
+connected (2dp gaps, replaces segmented buttons; use toggle buttons inside for single select), `size`.
+→ button-groups/specs
+
+**`M3SplitButton`** - primary action + `#menu`; pair with `M3Menu` anchored inside the menu slot.
+→ split-button/specs
+
+**`M3Fab`** - `label` required, `size` small | default | medium | large, `color` *-container (default)
+or solid, `extended` (undefined = plain; true/false = extended FAB shown/collapsed - collapse on scroll
+down). One FAB per screen, for its single most important constructive action, in `AppPage`'s `#fab`.
+→ floating-action-button/specs, extended-fab/specs
+
+**`M3FabMenu` + `M3FabMenuItem`** - when the main action has 2-6 variants. Items take `index`
+(0 nearest the FAB). → fab-menu/specs
+
+**`M3FabMorph`** - Framework7's FAB morph as a container transform: the FAB grows into a floating
+toolbar of icon buttons (`variant="toolbar"`) or a panel (`panel`, with a scrim) and shrinks back.
+`v-model:open`, `label`, `#icon`, default slot with `{ close }`. Use it when the FAB opens a set of
+peer actions on one screen; variants of one action are a FAB menu.
+
+## Navigation
+
+**Scroll behaviour** - `src/app/scroll.config.ts` sets it for the whole app: `topAppBar:
+"enterAlways"` slides a small top app bar away with the content and back on the way up (the status
+strip stays covered, `#bottom` and sticky `M3ListGroup` titles move with it); `navigationBar:
+"hideOnScroll"` slides the navigation bar off while scrolling down. `AppPage` wires both; a page
+passes `scrollBehavior` to override the top bar. Outside `AppPage`, `M3TopAppBar`'s
+`scrollBehavior` and `useHideOnScroll(scroller)` give the same behaviour.
+
+**`M3Breadcrumbs`** - `items` (`{ label, href? }`), `@select`, `max` (the middle collapses into a
+menu past it), `label`. The last item is the current page. Fades the edge it overflows past.
+
+**`M3NavigationBar` / `M3NavigationRail` + `M3NavigationItem`** - the shell already renders these from
+`src/app/tabs.ts`; add a destination there. Items take `#icon="{ selected }"` (outlined → filled),
+`badge` (number or `true`). `@reselect` fires on tapping the current destination.
+→ navigation-bar/specs, navigation-rail/specs
+
+**`M3Tabs` + `M3Tab`** - `variant` primary (content-width indicator, optional `#icon`) for peer views
+of one subject; secondary for subdivisions inside a primary tab. `scrollable` beyond ~4 tabs.
+Arrow keys move. Swipeable pages: put the tabs in `AppPage`'s `#bottom` slot (pinned under the
+bar), the pages in `M3TabPanels` + `M3TabPanel value`, bind one `v-model` to both and pass both
+the same `createTabPager()` so the indicator follows the swipe. Give `M3TabPanels` a height; each
+page scrolls on its own. A carousel or swipe row inside a page keeps its own sideways drag.
+→ tabs/specs
+
+**`M3TopAppBar`** - rendered by `AppPage`. `small` for pushed pages, `medium`/`large` flexible for
+roots and long titles. Tapping the bar outside its buttons scrolls the page to the top (Android's
+status bar keeps taps for its shade); nav-bar reselect does the same. → app-bars/specs
+
+**`M3FloatingToolbar`** - page actions over content: `variant` standard | vibrant, `#fab`,
+`hideOnScroll`. Compose gives it no shadow (1dp with a FAB) - do not add one. **`M3DockedToolbar`** - a detail screen's persistent actions at the bottom edge.
+→ toolbars/specs
+
+## Containment
+
+**`M3List` + `M3ListItem`** - `variant` segmented (default; each row its own surface, 2dp apart) or
+standard. Items: `headline`, `supporting`, `overline`, `trailingText`, `multiline`, `clickable` or
+`href`, `selected`, `tone="destructive"`; slots `#leading` (icon, `M3Shape` avatar 40dp), `#trailing`
+(decoration), `#action` (a control with its own target). Swipe actions: `M3SwipeAction` buttons
+(`label`, `tone`, `@click`) in `#swipe-start` / `#swipe-end`; `swipe-full="end"` arms the outermost
+action past half the row (deletes, archives - pair with an undo snackbar), `v-model:swiped` reads
+the open side. One row open at a time; a tap outside closes it. Expandable items: put the hidden
+content in `#details` (`v-model:expanded`); `M3List accordion` keeps one open, as Framework7's
+accordion list does - FAQs, settings groups, order lines. `M3List sortable` is Framework7's
+sortable list: a drag handle on every item plus long-press-and-drag on the row; handle
+`@sort="(from, to) => (rows = moveItem(rows, from, to))"` and persist the order yourself. Not for
+`M3VirtualList`. → lists/specs
+
+**`M3Carousel`** - Compose's carousel, keyline for keyline: `items`, `label`, `variant`
+multi-browse (default; browsing many items - photos, products) | hero (one featured item at a time;
+a fling moves one) | uncontained (fixed `item-width`, coasts without snapping), `item-width`
+(preferred large width, 186), `item-spacing` 8, `content-padding` 16, `height`, `v-model:item`.
+Items are laid out full size and masked, so put a full-bleed picture in the slot and let it
+parallax; fade labels with `--m3-carousel-item-progress` and slide them with
+`--m3-carousel-mask-start`. The slot's `scrollTo` brings a tapped item forward. → carousel/specs
+
+**`M3Tree`** - Framework7's treeview from data: `items` (`{ id, label, supporting?, children?,
+lazy? }`), `label`, `mode` select (`v-model:selected`) | check (`v-model:checked` leaf ids,
+tri-state branches), `v-model:expanded`, `load` for lazy children, `#icon="{ node, expanded }"`,
+`#trailing`. Categories, charts of accounts, permission sets.
+
+**`M3DataTable`** - Framework7's data table: `rows`, `columns` (`{ key, label, value?, format?,
+numeric?, sortable?, width? }`), `row-key`, `label`, `v-model:sort` (sorts locally unless
+`:sort-locally="false"` - then sort in SQL from the model), `selectable` + `v-model:selected`,
+`max-height` + `sticky-first-column` for wide tables, `dense`, `#cell`, `#footer` (totals), `#empty`.
+For phones prefer a list with the key fields; use the table where rows are compared across columns.
+
+**`M3Card`** - `variant` elevated | filled | outlined; `clickable` makes the whole card one target -
+then put no other buttons inside. → cards/specs
+
+**`M3Divider`** - only where whitespace and surfaces do not already separate. → divider/specs
+
+## Overlays
+
+**`M3BottomSheet`** - `v-model:open`, `title`, `dismissible`, slots `#header`, default (scrolls),
+`#footer` (fixed actions). Spring-driven; drag from handle or top-scrolled content. Prefer it to a
+dialog for anything with more than one choice or any form. → bottom-sheets/specs
+
+**`M3StandardBottomSheet`** - the non-modal sheet beside the content (a map, a route, a player):
+`v-model:detent` peek | half | expanded (| hidden with `hideable`), `label`, `title`, `peekHeight`
+(56 by default - raise it to show the title), `half`. Drags anywhere until expanded, then the content
+scrolls; pulling down from the content's top brings it back. Fixed to the window: set
+`--m3-standard-sheet-inset-bottom` above a navigation bar and pad the page by the peek.
+
+**Action sheet** - `await useActionSheet().open({ title, supporting, quickActions, groups })` resolves
+the chosen id or null. Options with icons in segmented groups; `selected` shows a check, `tone:
+"destructive"` paints error. Icons are components wrapped in `markRaw`.
+
+**`M3Dialog` / `useDialog().confirm({...})`** - only for a decision that must interrupt: destructive
+confirmations, required choices. `destructive` paints the confirm action; `icon` centres the headline.
+→ dialogs/specs
+
+**`M3FullScreenDialog`** - Framework7's popup, M3's full-screen dialog: `v-model:open`, `title`,
+`confirm-label` (+ `confirm-disabled`), `#actions`, `@confirm`, `@close`. For a task that needs the
+whole phone screen - a new order, an intake form; from 600dp it becomes a basic dialog. While the
+form is dirty pass `:dismissible="false"` and ask in `@close` before discarding (`useDialog`
+confirmations draw above it).
+
+**`M3Menu` + `M3MenuItem` + `M3MenuGroup`** - anchored to an element ref (`:anchor`), `variant`
+standard | vibrant; groups give the expressive segmented look. `checkable` for single/multi select.
+A `#submenu` slot of items makes a cascading item (trailing arrow; opens beside it on tap, hover or
+the arrow key); choosing inside closes the whole chain, Back closes the submenu alone. Keep it one
+level deep on phones. → menus/specs
+
+**Snackbar** - `await useSnackbar().show({ message, action, duration })` resolves `action` |
+`dismissed` | `timeout`. One action max, never for errors that need a decision. Undo is the classic.
+→ snackbar/specs
+
+**In-app notification** - `await useNotification().show({ title, text, source, meta, icon, duration })`
+resolves `opened` | `dismissed` | `timeout` | `replaced`. Framework7's notification: a banner from the
+top for something that happened elsewhere (a new order, a finished sync) that the person may want
+to open; a snackbar is for feedback on what they just did. One at a time - a new one replaces it.
+
+**`M3SideSheet`** - `v-model:open`, `side` start | end, `title`; filters and secondary detail beside
+the content. **`M3ModalNavigationRail`** - the expressive replacement for the navigation drawer;
+closes itself once a destination is chosen. → side-sheets/specs, navigation-rail/specs
+
+**`M3Popover`** - Framework7's popover: any content anchored to an element. `anchor` (element),
+`v-model:open`, `label`, `side` bottom | top, `align` start | center | end, `modal` (scrim + focus
+trap); default slot gets `{ close }`. Flips and stays on screen, grows out of the anchor, closes on a
+tap outside, Escape or back, and focus returns to the anchor. For a few controls or an explanation
+tied to one element; a list of actions is `M3Menu`.
+
+**`M3Tooltip`** - plain (long-press, hover, focus; labels an icon button) or rich (`title`, text,
+actions; explains, never holds the only path to a task). Placed so it never leaves the screen.
+→ tooltips/specs
+
+## Date and time
+
+Values are strings end to end - `IsoDate` (`YYYY-MM-DD`) and `IsoTime` (`HH:mm`, 24-hour) - so no
+timezone or DST shift can move a picked day. Utilities (`formatIso`, `parseLocalDate`,
+`formatIsoTime`, `uses12Hour`...) are exported beside the components.
+
+**`M3DatePicker`** - `v-model`, `v-model:open`, `presentation` dialog (Material's modal, default) |
+sheet (Framework7's, one-handed). `modes` defaults to calendar + typed input in a dialog, calendar +
+wheel in a sheet. Edits a draft; only OK commits. `min`, `max`, `isDisabled`, `locale`, every label
+a prop. **`M3Calendar`** - the grid alone, inline or docked in a card: `v-model:value`, or
+`mode="range"` with `v-model:start` / `v-model:end`. → date-pickers/specs
+
+**`M3TimePicker`** - `v-model` `HH:mm`, `presentation` dialog | sheet, `modes` dial + keyboard
+(dialog) or dial + wheel (sheet), `hour12` (else the locale decides), `minuteStep`. The dial is
+**`M3ClockDial`**: 24-hour faces put 00 and 13-23 on the inner ring. → time-pickers/specs
+
+**`M3WeekStrip`** - the head of an agenda: `v-model` `IsoDate`, `label`, `marks` (`{ [IsoDate]:
+count }` for the dots), `markLabel`, `locale`, `firstDay`. Swipes week to week endlessly; pin it
+under the app bar through `AppPage`'s `#bottom`, the day's items in a list below. Inset with
+`--m3-week-strip-inset`, never padding.
+
+**`M3WheelPicker`** - Framework7's picker: drums over one band, `columns` of `{ key, label,
+options, flex, align, loop }`, `v-model` keyed by column; `loop` rolls a drum over at its ends. Built like Framework7's: native scroll-snap, flat rows, gradient fades in `--m3-wheel-surface`
+(the colour behind it) - no per-row 3D or masks, which made it lag on phones - and a
+tick per detent. **`M3DateWheel`** / **`M3TimeWheel`** are the ready date and time drums; put them in
+an `M3BottomSheet` with a draft when the choice needs confirming. No M3 spec - it is the F7 parity
+piece.
+
+## Photos
+
+**`M3PhotoBrowser`** - Framework7's photo browser: `photos` (`{ src, alt, caption?, width?, height? }`),
+`v-model:open`, `v-model:index`, `label`, `#actions` for the bar (share, delete). Swipe between,
+pinch or double-tap to zoom, pan when zoomed, swipe up or down to close; only neighbours load. Give
+`width`/`height` when known. It is drawn on black - call `useDarkStatusBar(() => open.value)` so the
+status bar icons turn light while it shows.
+
+**`M3Image`** - lazy image: `src`, `alt` (`""` when decorative), `width` + `height` or `ratio` to
+reserve its space, `placeholder` (a colour or a tiny image, drawn blurred), `fit`, `eager` for the
+first screen, `#error`. Fades in once decoded; cached pictures appear at once.
+
+**`M3Pager`** + **`M3PagerPage`** - Framework7's swiper as a pager on native scroll-snap: one page per
+swipe, `v-model:page`, `label`; dots underneath, or `#footer` with `{ page, count, progress, go,
+next, previous }` for Skip / Next. **`M3PageIndicator`** (`count`, `progress`, `@select`) is the
+dots alone; its pill follows the finger. Onboarding, a product's photos, a feature tour.
+
+## Lists at scale
+
+**`M3ListGroup` + `M3ListIndex`** - Framework7's contacts list and list index: groups whose titles
+stick under the app bar (`title`, `indexKey`; `groupKey(label)` folds accents and buckets digits
+under `#`), and an A–Z rail (`keys`, `label`) in `AppPage`'s `#fixed` slot that jumps as the finger
+drags. Pad the content ~24px at the end edge so rows clear the rail.
+
+**`M3InfiniteScroll`** - after a list: `:load` returns a promise and resolves `false` when there is
+no more; failures wait for the user's retry; `endText` closes the list; expose `reset()` after a new
+filter. Feed it from a repository with `LIMIT/OFFSET` (or a keyset) - never load everything to
+slice it in memory. **`M3Timeline` + `M3TimelineItem`** - an order's journey, a patient's visits:
+`title`, `time`, `supporting`, `state` done | current | upcoming, `#icon` for the current step,
+`stateLabel` so the state is read out.
+
+**`M3VirtualList`** - thousands of rows against the page's own scroller (the app bar still
+collapses): `items`, `itemSize` (number or function: 56 / 72 / 88 + 2 for the segment gap),
+`itemKey`, `inset`. Rows are recycled - row components must render from props alone; `recycle=false`
+keys by `itemKey` for rows with local state. **`M3PullToRefresh`** - `:refresh` returns a promise;
+the loading indicator fills with the pull and loops until it settles.
+
+## Progress
+
+**`M3Skeleton` + `M3SkeletonBlock` + `M3SkeletonText`** - Framework7's skeleton: placeholders in
+the shape of the content on its way, for loads you expect to take more than a moment (a list from
+the database, a detail screen). Mirror the real layout exactly - same rows, same type scales via
+`M3SkeletonText typescale` - so nothing jumps when it lands. `effect` wave (default) | pulse | none;
+set `--m3-skeleton-surface` to the colour behind the group. Use `M3LoadingIndicator` instead when
+there is no layout to predict.
+
+**`M3LoadingIndicator`** - waits up to a few seconds, or `progress` 0-1 for determinate. `contained`
+over content. Replaces every spinner. → loading-indicator/specs
+
+**`M3LinearProgress` / `M3CircularProgress`** - `value` 0-1 or omitted (indeterminate), `wavy` (default
+on), `thickness`; circular takes `gauge` and a centred slot. Linear sits 4dp in from the edges.
+→ progress-indicators/specs
+
+## Selection and input
+
+**`M3Switch`** (`icons`, `bothIcons`) for an instant on/off; **`M3Checkbox`** for items in a list
+or a form submitted later; **`M3Radio`** (`v-model` + `value`) for one of few visible options - more
+than ~5, use an action sheet. **`M3Slider`** - `size` xs..xl, `step`, `ticks`, `#icon` from m, `format`
+for the value bubble. **`M3RangeSlider`** - `v-model:start` / `v-model:end`, `startLabel` /
+`endLabel` (each handle is its own slider), `minDistance` keeps them apart. **`M3Stepper`** - Framework7's stepper for small counts (cart quantity, guests, a dose):
+`v-model`, `label`, `min`/`max`/`step` (decimals stay clean), `variant` outlined | tonal, `size` s | m,
+`editable` (type the value; a decimal comma is read), `format` for units. Holding a button repeats
+and speeds up across wide ranges. Use a slider when the exact value matters less than its position.
+**`M3Chip`** - `kind` assist | filter (`v-model:selected`) | input
+(`removable`) | suggestion. **`M3TextField`** - `variant` filled (default) | outlined, `supporting`,
+`error`, `maxlength` counter, `prefix`/`suffix`, `multiline`, `#leading`/`#trailing`; native
+attributes pass through. **`M3ExposedDropdown`** - Compose's exposed dropdown menu: `options`
+(`{ value, label, supporting?, disabled? }`), `v-model`, `label`; read-only it is a select (arrow
+keys, type-ahead), `editable` makes it Framework7's autocomplete (accent- and case-insensitive
+filter, bolded match, `limit`). For a remote source, `:filter="false"` + `v-model:query` +
+`loading`. Use it over radios past ~5 options, and over an action sheet when the field sits in a
+form. **`M3SmartSelect`** - Framework7's smart select, a list row that opens a sheet of options:
+`options`, `v-model` (an array with `multiple`), `label`, `placeholder`; search appears past
+`searchFrom` (10). Prefer it to the exposed dropdown for multi-choice and inside settings lists.
+**`M3SearchBar`** - `v-model`, `@search`, `#leading`/`#trailing`, for
+filtering what is already on screen. **`M3SearchView`** - the bar that opens into a full-screen
+view (`v-model`, `v-model:expanded`, `placeholder`; results in the default slot with `{ query }`,
+recent searches when the query is empty); use it for searching a whole data set.
+→ switch, checkbox, radio-button, sliders, chips, text-fields, search /specs
+
+## Charts
+
+`M3LineChart` (`area` for filled), `M3BarChart` (`stacked`) and `M3DonutChart` - plain SVG, no
+library: `labels` + `series` (`{ label, values, color? }`, `null` breaks a line) or `segments`
+(`{ label, value }`), `label` (the accessible name), `format` for numbers (use
+`Intl.NumberFormat` compact). Colours come from the theme's roles; touching reads values;
+screen readers get a hidden table. Lines for change over time, bars to compare categories, a
+donut for parts of one whole (at most ~6 segments). Feed them aggregates from SQL, never raw rows.
+
+## Forms
+
+**`M3TextEditor`** - Framework7's text editor: `v-model` HTML, `label`, `placeholder`, `toolbar`
+(commands and `"|"`), `labels` for i18n. Bold, italic, underline, strikethrough, lists, links
+(through a popover), clear formatting. Its HTML is sanitised in and out (`sanitizeHtml` is exported
+
+- run it again wherever stored HTML is rendered with `v-html`). Use a plain multiline `M3TextField`
+  unless formatting is the point.
+
+**`M3SignaturePad`** - proof of delivery: `v-model:strokes` (fractions of the pad, so a draft or a
+rotation redraws it sharp), `height`, `label`, `placeholder`; ref methods `undo()`, `clear()`,
+`toDataURL(type, background)` for the upload, `toSvg()`. Always pair it with a typed name - signing
+has no keyboard path.
+
+**`M3ColorPicker`** - `v-model` `#rrggbb`, hue / chroma / tone sliders in HCT with previewing tracks,
+a hex field, optional `swatches`. Put it in a sheet with a draft and apply on confirm when the
+colour drives something expensive, such as the app theme.
+
+**`useFormDraft(key, state, options)`** - keeps what is typed into a form as a draft (debounced,
+written at once when the app goes to the background) and restores it when the form opens again.
+Returns `{ restored, savedAt, error, clear, flush }`; call `clear()` on submit or discard. `storage`
+takes any async store (default `localStorage`), `version` drops drafts from an older form, `maxAge`
+expires them. Never draft passwords or card numbers - give it only the fields worth keeping.
+
+## Messages
+
+**`M3Messages`** - a conversation: `messages` (`{ id, sent, at, text?, author?, avatar?, status?,
+image? }`, oldest first), `label`, `locale`, `authors` for a group (names and avatars), `typing`
+(`true` or `{ author }`), label props for i18n. It scrolls with the page: opens at the newest,
+follows new ones while the reader is there, keeps their place otherwise and counts what arrived.
+Older history goes in `#before` as `<M3InfiniteScroll edge="start">` - page it, never pass
+thousands. `@hold` (long-press) for a message menu via `useActionSheet`, `@press` for an image,
+`@retry` for a failed send. Give images `width`/`height` so nothing jumps as they load.
+**`M3MessageBar`** - the composer, in `AppPage`'s `#fixed`: `v-model`, `label`, `@send` (trimmed
+text; it clears itself), `#leading` (attach), `#trailing` (emoji), `#idle` (stands in for send
+while empty), `enterSends` for hardware keyboards. It publishes its height for `M3Messages`; zero
+the page's own bottom padding (`.page-content { padding-bottom: 0 }`) on a chat page.
+
+## Shape and decoration
+
+**`M3Shape`** - masks its content to one of the 35 shapes (square box). **`M3ShapeMorph`** - an SVG
+shape that springs into the next when `shape` changes; fills with `currentColor`. **`M3Badge`** -
+dot or count on its slot. Details: [shapes-type.md](shapes-type.md).

package/templates/m3e-app/.claude/skills/m3-expressive/layout.md

@@ -0,0 +1,42 @@
+# Layout
+
+## The shell
+
+- Window classes from `useWindowClass()`: compact < 600dp, medium < 840, expanded < 1200, large.
+  Key layout on these, never on device type - a phone in landscape is medium.
+- Compact: `M3NavigationBar` floats at the bottom; the shell writes `--app-nav-offset` (64px while
+  visible) and `--app-bottom-inset` (offset + gesture area). Anything floating above content uses
+  them; nothing measures the bar.
+- Medium and up: `M3NavigationRail` beside the views, expandable from its menu button.
+- Pushed pages hide the bar (`AppPage back`), the rail stays.
+
+## Page anatomy (`AppPage`)
+
+```vue
+<AppPage :title="t('feature.title')" name="feature">            <!-- large flexible bar -->
+  <template #actions><M3IconButton :label="…"><i-ms-search-rounded /></M3IconButton></template>
+  <SectionHeader :title="t('feature.section')" />
+  <M3List variant="segmented" inset>…</M3List>
+  <template #fab><M3Fab :label="…"><i-ms-add-rounded /></M3Fab></template>
+  <template #fixed><MyFeatureSheet v-model:open="open" /></template>
+</AppPage>
+```
+
+A pushed page: `<AppPage :title back>` (small bar, back button, bar hidden); `variant="medium"` for a
+long title. Sheets and toolbars that must not scroll go in `#fixed`.
+
+## Spacing and rhythm
+
+- Content gutters 16dp (`px-4`, `mx-4`, `inset` on lists); section labels 24dp (`px-6`).
+- Between blocks 12-24dp; inside a block 8-16dp. Segments 2dp apart.
+- Touch targets ≥ 48dp - the components extend small visuals with an invisible target.
+- At most ~840dp of reading width on large windows: wrap long content in `max-w-[52rem] mx-auto`.
+
+## Placement
+
+- One FAB, bottom-end, in `#fab`. With a floating toolbar, the FAB goes in the toolbar's `#fab`.
+- Destructive actions go behind a menu or the end of an action sheet, never next to the main action.
+- A detail screen's state changes go in `M3DockedToolbar` (connected button group).
+- Forms of more than two fields open in an `M3BottomSheet` with the submit button in `#footer`.
+
+See [sources.md](sources.md) → Layout.

package/templates/m3e-app/.claude/skills/m3-expressive/motion.md

@@ -0,0 +1,51 @@
+# Motion
+
+M3 Expressive motion is physics: springs with a damping ratio and a stiffness. **Spatial** springs
+move position, size, rotation and shape and may overshoot; **effects** springs change colour and
+opacity and never do. Speed follows the size of what moves: **fast** for small components, **default**
+for partial-screen surfaces (sheets, menus), **slow** for full-screen moves.
+
+## The tokens
+
+| Token                         | Expressive ζ / k            | CSS easing var                        | Duration var                    |
+| ----------------------------- | --------------------------- | ------------------------------------- | ------------------------------- |
+| fast spatial                  | 0.6 / 800 (≈9.5% overshoot) | `--md-sys-motion-spring-fast-spatial` | `…-fast-spatial-duration` 350ms |
+| default spatial               | 0.8 / 380                   | `…-default-spatial`                   | 500ms                           |
+| slow spatial                  | 0.8 / 200                   | `…-slow-spatial`                      | 650ms                           |
+| fast / default / slow effects | 1.0 / 3800, 1600, 800       | `…-fast-effects` etc.                 | 150 / 200 / 300ms               |
+
+Spatial easings are generated `linear()` curves that keep the overshoot; effects are the official
+beziers. Tailwind: `ease-fast-spatial`, `ease-default-effects`… with `duration-spring-fast`,
+`duration-spring-default`, `duration-spring-slow`. Legacy tokens (`--md-sys-motion-easing-emphasized-
+decelerate`, `--md-sys-motion-duration-medium2`…) remain for transitions that are not physical moves:
+dialogs entering, fades.
+
+## Choosing the mechanism
+
+- **CSS transition on a token** - state changes nobody interrupts: a toggle, a selected tab indicator,
+  a chip check, a list row rounding off.
+- **`animateSpring`** (`@cavulsqa/m3e`) - anything a gesture drives or that can reverse mid-flight:
+  sheets, drags, interrupted opens. It carries velocity into the new target; a CSS transition restarts
+  from zero and stutters.
+- **`useFrame`** (`@cavulsqa/m3e-vue`) - continuous drawing (progress, loaders). One shared rAF loop;
+  pause when off screen with `useInView`.
+- **Vue `<Transition>` / `<TransitionGroup>`** - enter/leave of elements, with the tokens above.
+
+## Patterns already in the app
+
+- Page change: `m3e-axis` shared-axis X (`assets/css/layout/transitions.css`) - slide 64px on slow
+  spatial, fade-through. Do not set per-route transitions.
+- Press: shapes tighten on default effects (no bounce); selection reshapes on spatial.
+- Enter from a FAB or anchor: scale/translate from that corner, stagger 15-30ms per item.
+- Exit is always shorter than enter and accelerates.
+
+## Rules
+
+- Animate `transform` and `opacity`. A layout property may animate only on a small element (a button's
+  padding in a group); never on a page-sized surface.
+- Under reduced motion spatial durations are 1 ms (not 0 - `transitionend` must still fire); keep
+  fades and morphs, drop rotation, bounce and travel. JS motion passes `instant: reduced.value`.
+- Haptics accompany a confirmed state change (`useHaptics().tick()` on a toggle, `confirm()` on a
+  completed action), never scrolling or hovering.
+
+See [sources.md](sources.md) → Motion.

package/templates/m3e-app/.claude/skills/m3-expressive/shapes-type.md

@@ -0,0 +1,48 @@
+# Shape and type
+
+## Corner scale
+
+| Tailwind               | Token                 | dp   | Typical use                                       |
+| ---------------------- | --------------------- | ---- | ------------------------------------------------- |
+| `rounded-xs`           | extra-small           | 4    | inner corners of segmented lists, menus, snackbar |
+| `rounded-sm`           | small                 | 8    | chips, small thumbnails                           |
+| `rounded-md`           | medium                | 12   | cards, inner panels                               |
+| `rounded-lg`           | large                 | 16   | outer corners of segments, grouped blocks         |
+| `rounded-lg-increased` | large-increased       | 20   | medium FAB                                        |
+| `rounded-xl`           | extra-large           | 28   | sheets, dialogs, hero blocks                      |
+| `rounded-xl-increased` | extra-large-increased | 32   | large hero surfaces                               |
+| `rounded-2xl`          | extra-extra-large     | 48   | full-bleed media corners                          |
+| `rounded-full`         | full                  | pill | buttons, chips at rest, indicators                |
+
+Nested corners stay concentric: inner radius = outer radius − padding.
+
+## The shape library
+
+35 shapes (`MATERIAL_SHAPES`): circle, square, slanted, arch, fan, arrow, semiCircle, oval, pill,
+triangle, diamond, clamShell, pentagon, gem, sunny, verySunny, cookie4Sided, cookie6Sided,
+cookie7Sided, cookie9Sided, cookie12Sided, ghostish, clover4Leaf, clover8Leaf, burst, softBurst,
+boom, softBoom, flower, puffy, puffyDiamond, pixelCircle, pixelTriangle, bun, heart. All visible in
+Gallery → Shapes.
+
+- **Use shapes for identity and emphasis, not for controls**: avatars and leading icons in lists
+  (`M3Shape` 40dp with `TONE_CLASSES`), hero art, empty states, status marks, selected swatches.
+- **Morph to mark a change of state**: `M3ShapeMorph` springs between two shapes - selection, a step
+  completing, a status advancing.
+- **Rounded shapes for calm, spiky (burst, boom) for celebration or alerts** - sparingly.
+- A shape needs a square box; a photo cut to a shape uses `M3Shape` around the `<img>`.
+
+## Type
+
+Google Sans Flex (self-hosted, `rond.css` - weight + roundness axes) for every style. Utilities:
+`type-<style>` and `type-<style>-emphasized`, styles display/headline/title/body/label ×
+large/medium/small. Sizes are in rem, so the user's font scale applies.
+
+- Titles of screens: the app bar owns them. In content, `type-title-medium` for card titles,
+  `type-title-small-emphasized` (primary) for section labels, `type-body-large` for list headlines,
+  `type-body-medium` for supporting text, `type-label-large` for button-like labels.
+- **Emphasized** styles are for the one thing on a surface that should land first: a total, a hero
+  headline, a selected value - not for every heading.
+- `font-rounded` (ROND 100) belongs to display and headline moments in heroes and totals, never body.
+- Numbers that change in place get `tabular-nums`.
+
+See [sources.md](sources.md) → Shape, Typography.

package/templates/m3e-app/.claude/skills/m3-expressive/sources.md

@@ -0,0 +1,53 @@
+# Official sources
+
+m3.material.io renders in the browser only (fetching returns an empty shell): open it in a browser
+tool. When the spec page and androidx source disagree, the androidx token files win - they are
+generated from the same design-token database and are newer.
+
+## Foundations
+
+- Overview and blog: https://m3.material.io/blog/building-with-m3-expressive
+- Motion theming: https://m3.material.io/blog/m3-expressive-motion-theming
+- State layers: https://m3.material.io/foundations/interaction/states/state-layers
+- Accessibility: https://m3.material.io/foundations/accessible-design/overview
+- Layout and window size classes: https://m3.material.io/foundations/layout/applying-layout ·
+  https://developer.android.com/develop/ui/compose/layouts/adaptive/use-window-size-classes
+
+## Styles
+
+- Motion: https://m3.material.io/styles/motion/overview/how-it-works ·
+  specs and web curves: https://m3.material.io/styles/motion/overview/specs ·
+  transitions: https://m3.material.io/styles/motion/transitions/transition-patterns
+- Colour: https://m3.material.io/styles/color/roles ·
+  https://m3.material.io/styles/color/choosing-a-scheme ·
+  https://m3.material.io/styles/color/dynamic-color/overview ·
+  custom colours: https://m3.material.io/styles/color/advanced/define-new-colors
+- Shape: https://m3.material.io/styles/shape/corner-radius-scale ·
+  https://m3.material.io/styles/shape/shape-morph
+- Typography: https://m3.material.io/styles/typography/type-scale-tokens ·
+  https://m3.material.io/styles/typography/fonts
+- Elevation: https://m3.material.io/styles/elevation/tokens
+
+## Components (append `/specs` or `/guidelines`)
+
+`https://m3.material.io/components/<name>/specs` for: buttons, icon-buttons, button-groups,
+split-button, floating-action-button, extended-fab, fab-menu, loading-indicator,
+progress-indicators, toolbars, navigation-bar, navigation-rail, app-bars, search, bottom-sheets,
+side-sheets, dialogs, menus, lists, carousel, chips, sliders, switch, tabs, snackbar, cards,
+text-fields, checkbox, radio-button, badges, divider, tooltips, date-pickers, time-pickers.
+
+## Source of the numbers
+
+- Compose token files:
+  https://github.com/androidx/androidx/tree/androidx-main/compose/material3/material3/src/commonMain/kotlin/androidx/compose/material3/tokens
+- Shapes: …/material3/MaterialShapes.kt · loader: …/LoadingIndicator.kt · wavy: …/WavyProgressIndicator.kt
+  (same folder as above, without `/tokens`)
+- Colour library: https://github.com/material-foundation/material-color-utilities/tree/main/typescript
+- MDC-Android component docs (before/after numbers):
+  https://github.com/material-components/material-components-android/tree/master/docs/components
+
+## Where a spec lands in this repo
+
+`packages/m3e` holds the tokens and geometry (each file's JSDoc links its source);
+`packages/m3e-vue` the components (each SFC's JSDoc links its spec page). Extend those, then use the
+result here.