mapples 0.2.0-beta.5 → 0.2.0-beta.7

package/templates/claude/skills/mapples-conventions/SKILL.md

@@ -0,0 +1,136 @@
+---
+name: mapples-conventions
+description: How Mapples-managed files are written — file layout, $sid rules, $actions/$data/$refs, the @mapples/ui vs @mapples/components import table, token strings and Styler dictionaries. Use whenever editing a route file, mapples/pages, mapples/components or mapples/theme.ts in a Mapples-linked Expo app.
+---
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
+# Mapples conventions
+
+Read `.claude/mapples.md` first (the summary). This skill is the reference.
+
+## File layout
+
+| File | Role | Editable |
+| --- | --- | --- |
+| `__ROUTES_DIR__/<segment>.tsx`, `__ROUTES_DIR__/(group)/<segment>.tsx` | a screen that is in the navigation; `index.tsx` is the section's first screen | yes — merged with Creator |
+| `__ROUTES_DIR__/**/_layout.tsx` | the navigator (Stack/Tabs/Drawer); regenerated from Creator's navigation on every sync | **no** (handshake only, below) |
+| `__PAGES_DIR__/<Name>.tsx` | a screen not (yet) in the navigation; moves into the routes dir when placed | yes |
+| `__COMPONENTS_DIR__/<Name>.tsx` | a reusable Creator component; instances are `import X from '…/<Name>'` + `<X styled />` | yes |
+| `mapples/theme.ts` | design tokens (`theme`, `typography`, `sizing`) | yes — merged per key |
+| `mapples/assets/`, `mapples/assetMap.ts` | Creator assets | **no** |
+| `mapples/sid.d.ts` | types for the `$sid`/`$refs`/`$data`/`$actions`/`$fallback` attributes | no |
+| `.mapples/` | config, secret, head, base, pages.json, components.json, outbox, agent.json | **no** |
+| `_depr_<ts>_<name>.tsx.old` | your version of a file the CLI had to regenerate | read, never restore |
+
+The route marker `// mapples-route: <id> — “<Name>”` on line 1 of a route file is the route's
+identity: keep it verbatim. Renaming the file renames the route in Creator.
+
+## `$sid`
+
+- `$sid="nd_…"` is the canvas node id. Opaque: never parse beyond the prefix, never invent,
+  never renumber, never copy to another element, never reuse a deleted one.
+- New elements carry **no** `$sid`. `npx -y mapples@__CLI_VERSION__ sync` tags them (report: `tagged N new element(s)`)
+  and rewrites the file with the ids — re-read the file after a sync before editing again.
+- Wrapping an existing element (moving it inside a new `View`) keeps its `$sid`; the sync sees a
+  move. Removing an element with a `$sid` deletes it in Creator.
+- `$fallback={{ w, h }}` sits on `Custom` nodes (a non-Mapples component the canvas cannot
+  render); leave it as the CLI wrote it.
+
+## Transient attributes
+
+| Attribute | Shape | Meaning |
+| --- | --- | --- |
+| `$actions` | `{ onPress: { type: 'mapples:navigate', staticData: { pageUuid: '<uuid>' } } }` | Creator prototype connection on that event. Other action types (`mapples:setState`, `mapples:goBack`, `mapples:switchTab`) exist; navigate is the one you write. |
+| `$data` | `{ visible: { key: 'vars.sheetOpen', active: true } }` | a data binding of a prop to a project variable — only when the project already has the variable |
+| `$refs` | `{ source: 'ref(image:<uuid>)' }` | a Creator asset reference — Creator-side; never invent one |
+
+`pageUuid` lookup: `.mapples/pages.json` maps `pageId → { file, name, route, routeId }`; the
+uuid the action needs is the `uuid` field of `.mapples/base/pages/<pageId>.json`. Both are
+rewritten by every sync — read them fresh.
+
+## Imports
+
+`@mapples/ui` — primitives (the canvas' base element types):
+
+`View`, `Container`, `SafeAreaView`, `ScrollView`, `HorizontalScrollView`, `FlatList`,
+`GridTwoColumns`, `GridThreeColumns`, `GridFourColumns`, `GradientBackground`,
+`ImageBackgroundView`, `Typography`, `Text` (never on a screen — use Typography), `Image`,
+`Icon`, `Svg`, `Vector`, `Video`, `QRCode`, `BarCode`, `Pressable`, `IconButton`, `TextInput`,
+`Select`, `FormView`, `TextField`, `SubmitButton`.
+
+`@mapples/components` — the themed library (paints itself from the tokens; prefer it):
+
+| Group | Types |
+| --- | --- |
+| actions | `Button`, `ButtonGroup`, `Fab`, `TextLink`, `BottomActionBar` |
+| input | `InputField`, `SelectField`, `Checkbox`, `RadioGroup`, `Switch`, `Slider`, `NumberStepper`, `PinInput`, `SearchBar`, `ChatComposer`, `SegmentedControl`, `Rating`, `ChipGroup`, `Chip` |
+| content | `Card`, `MediaCard`, `List`, `ListItem`, `SectionHeader`, `Divider`, `Avatar`, `AvatarGroup`, `Badge`, `StatTile`, `Table`, `Timeline`, `ImageCarousel`, `MessageBubble`, `Accordion`, `Skeleton` |
+| navigation | `TopAppBar`, `BottomNavigationBar`, `Tabs`, `Breadcrumbs`, `Steps`, `PageControl` |
+| feedback | `ProgressBar`, `ProgressCircle`, `Spinner`, `Banner`, `Snackbar`, `EmptyState` |
+| overlays | `Dialog`, `BottomSheet`, `ActionSheet` |
+
+Anything else you import (a third-party or hand-written component) becomes an opaque `Custom`
+node on the canvas with a `$fallback` size — allowed, but Creator cannot design inside it.
+
+`Styler` comes from `@mapples/style`; `router` from `expo-router`.
+
+## Styling
+
+```tsx
+<View styled={{ style: styles.row }}>
+  <Icon iconName="checkmark-circle" styled={{ styleSvg: styles.icon }} />
+  <Typography text="Done" variant="Label" styled={{ styleTypography: styles.done }} />
+</View>
+
+const styles = Styler.create({
+  row: { flexDirection: 'row', alignItems: 'center', gap: 'sizing.sm' },
+  icon: { width: 20, height: 20, color: 'theme.system.success' },
+  done: { color: 'theme.text.secondary' },
+});
+```
+
+- `styled={{ style }}` is the element's own box; `styleTypography` the text of a control
+  (Button label, ListItem title); `styleSvg` an Icon's glyph (`color`, `width`, `height`);
+  `styleImage` the picture inside an Image; `contentContainerStyle` the scrolling content of a
+  ScrollView/FlatList/HorizontalScrollView; `placeholderTextColor` a TextInput's placeholder.
+- One `Styler.create` dictionary per file, below the component; keys say what the element shows
+  and is (`signInText`, `heroImage`, `listContent`). A `StyleSheet.create` dictionary is also
+  read, but write `Styler.create`.
+- A style may be a single dictionary reference (`styles.card`) or a literal; never an array,
+  never a computed expression (Creator cannot read it → `NON_LITERAL_PROP`).
+- Token strings: colors `'theme.<group>.<key>'` (`theme.primary.main`, `theme.primary.contrast`,
+  `theme.background.primary`, `theme.background.card`, `theme.text.primary|secondary|tertiary`,
+  `theme.neutral.n200`, `theme.system.error`); spacing `'sizing.<key>'` (`xs sm md lg xl
+  screenPadding gap radius radiusLarge control card icon`) or `'*N'` (N × base). Gradients take
+  literal hex/rgba only.
+- `boxShadow` is an object `{ x, y, radius, color }`, never a CSS string.
+- Library components set their own defaults; change their look through `variant`, `size`,
+  `tone` props and the slots — never rebuild one from Views.
+
+## Layouts (`_layout.tsx`)
+
+The CLI generates every layout from Creator's navigation document. Do not edit or style them
+(header/tab-bar options are set in Creator). To add a **new** section, create the directory
+with a layout whose first line is `// GENERATED by Mapples`:
+
+```tsx
+// GENERATED by Mapples — this layout is owned by the CLI and regenerated from the navigation document.
+import { Tabs } from 'expo-router';
+
+export default function MainLayout() {
+  return <Tabs />;
+}
+```
+
+`npx -y mapples@__CLI_VERSION__ sync --yes` then adopts the directory as a tabs navigator (`<Stack>` → stack,
+`<Drawer>` from `expo-router/drawer` → drawer; no layout → stack) and regenerates the file. A
+layout **without** the header is treated as yours and deprecated on the first sync.
+
+## What not to do
+
+- Do not run `npx -y mapples@__CLI_VERSION__ init`, `npx -y mapples@__CLI_VERSION__ create`, or edit `.mapples/config.json`.
+- Do not restore a `_depr_` file over the regenerated one.
+- Do not hand-write `$sid`s, `$refs`, or navigator options.
+- Do not put JSX children text inside `Typography` (`text` prop only), and do not use `Text`.
+- Do not spread props or map arrays into JSX inside a managed element tree — Creator reads
+  literal trees; put dynamic lists behind a `FlatList`/`List` with literal `items` where
+  possible, or accept the `NON_LITERAL_PROP` note.

package/templates/claude/skills/mapples-design/SKILL.md

@@ -0,0 +1,218 @@
+---
+name: mapples-design
+description: Build a Mapples-linked Expo app from a product brief the way the Creator's in-app AI does — design tokens, an implementation plan, one screen per phase from the design playbooks, wiring and a review — writing route files and mapples/theme.ts and pushing each phase with `npx -y mapples@__CLI_VERSION__ sync` while holding the project's agent lease. Use when the user asks to design, generate or build the app, its screens or its design system.
+argument-hint: "<product brief> [--scope single|minimal|basic|advanced]"
+---
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
+# /mapples-design — build the app from a brief
+
+You are the product designer and builder for this app. Your bar is a finished screen a
+designer would ship — not a wireframe. Everything you make is a file in this repo; every phase
+ends with `npx -y mapples@__CLI_VERSION__ sync --yes --json`, which pushes it to Creator where the user watches it land.
+
+Read `.claude/mapples.md` and the `mapples-conventions` and `mapples-sync` skills before the
+first file. Reference material for this skill lives next to it:
+
+- `reference/style-guides.md` — art directions and style guides (phase 1)
+- `reference/design-tokens.md` — the `mapples/theme.ts` contract and template (phase 2)
+- `reference/plan.md` — scopes and the implementation plan (phase 3)
+- `reference/layout-contract.md` — the rules every screen obeys (phases 5…)
+- `reference/component-library.md` — what to reach for, by need
+- `reference/lint-checklist.md` — the review pass (phase N)
+- `reference/playbooks/<name>.md` — screen-kind playbooks, loaded per screen
+
+## Preconditions
+
+1. `.mapples/config.json` must exist (the app is linked). If not: stop and ask the user to run
+   `npx -y mapples@__CLI_VERSION__ init --secret <key> --agent claude` — never run it yourself.
+2. `npx -y mapples@__CLI_VERSION__ agent status --json`. If `session` is non-null with `status: "active"` and
+   `holdsLease` is false, another agent is working on this project: stop and ask whether to take
+   over (`--takeover` disconnects it). Never take over silently.
+3. `npx -y mapples@__CLI_VERSION__ sync --yes --json` — be current before designing. Exit 2 here means the repo already
+   had conflicts: resolve them (see `mapples-sync`) before going on.
+4. Read `mapples/design.md` if it exists: a previous run's brief, chosen style and plan. Resume
+   from the first phase whose output is missing rather than redoing everything.
+
+## Steps and the lease
+
+The run is one agent session. Steps have a **fixed index convention** shared with Creator's
+progress log:
+
+```
+0 Brief · 1 Style guides · 2 Design tokens · 3 Plan · 4 Scaffold navigation & screens ·
+5…N-2 one per plan step ("Build the Home screen", …) · N-1 Wiring · N Review
+```
+
+Start the session as soon as the brief and scope are known, pre-declaring every step title:
+
+```bash
+npx -y mapples@__CLI_VERSION__ agent start --label "Claude Code" --steps "Brief,Style guides,Design tokens,Plan,Scaffold navigation & screens" --json
+```
+
+Exit 4 = busy (see precondition 2). After the plan exists (phase 3), the remaining titles are
+declared as they run: `npx -y mapples@__CLI_VERSION__ agent step --index 5 --title "Build the Home screen" --status running`
+creates the step. Wrap **every** phase:
+
+```bash
+npx -y mapples@__CLI_VERSION__ agent step --index <i> --title "<title>" --status running --json
+# … the work …
+npx -y mapples@__CLI_VERSION__ agent step --index <i> --title "<title>" --status done --detail "<one line>" --json
+```
+
+Exit 3 from any `agent` or `sync` command = the lease is gone (Creator disconnected you or the
+lease expired). Stop immediately, do not sync again, and tell the user what was finished.
+
+Always end the run — success or not:
+
+```bash
+npx -y mapples@__CLI_VERSION__ agent stop --status done --json
+npx -y mapples@__CLI_VERSION__ agent stop --status failed --error "<what blocked the run>" --json
+```
+
+A phase's syncs are labelled with the running step in Creator's history automatically.
+
+## Phase 0 — Brief and scope
+
+Input: `$ARGUMENTS` (the brief, optionally `--scope single|minimal|basic|advanced`). If the
+brief is missing or too thin to name the audience, the core value and the mood, ask **one**
+round of questions (AskUserQuestion) — audience, the one thing the app must do well, the
+feeling it should have, and the scope if absent (default `basic`). Then write
+`mapples/design.md`:
+
+```md
+# <App name>
+## Brief
+<the brief, cleaned up, 3–8 lines: audience, core value, mood, must-haves, non-goals>
+## Scope
+<single|minimal|basic|advanced> — <one line why>
+```
+
+Report the step done with the scope in `--detail`.
+
+## Phase 1 — Style guides
+
+Follow `reference/style-guides.md`: propose 3 art directions **for this product**, then 3
+compact style guides. Show them to the user as a table (name, direction, palette swatches as
+hex, headline/body fonts, radius, elevation language, one don't) and ask which one — or accept
+the user's pick from the brief. Append the chosen guide to `design.md` under `## Style guide`.
+
+## Phase 2 — Design tokens
+
+Follow `reference/design-tokens.md` exactly: write `mapples/theme.ts` (create it — a missing
+file and an empty project is a no-op, so the file is what pushes the tokens). Then
+
+```bash
+npx -y mapples@__CLI_VERSION__ sync --yes --json
+```
+
+Assert: `exitCode` 0, `pushedOps` ≥ 3 (Theme, Typography, Sizing updates) and no
+`conflicts`. If `pushedOps` is 0, the file did not parse as three literal exports — fix the
+file, do not move on. Record the token summary (primary, background, fonts, radius) in
+`design.md` under `## Tokens`.
+
+## Phase 3 — Plan
+
+Follow `reference/plan.md`: decisions, navigation (sections → screens), entry screen, ordered
+build steps. Append it to `design.md` under `## Plan` **and** declare the remaining steps:
+
+```bash
+npx -y mapples@__CLI_VERSION__ agent step --index 5 --title "<plan step 1 title>" --status pending --json
+…
+npx -y mapples@__CLI_VERSION__ agent step --index <N-1> --title "Wiring" --status pending --json
+npx -y mapples@__CLI_VERSION__ agent step --index <N> --title "Review" --status pending --json
+```
+
+Show the plan to the user in 6–10 lines; continue unless they object.
+
+## Phase 4 — Scaffold navigation and screens
+
+Read `.mapples/config.json` for `routesDir` (`__ROUTES_DIR__` here). Then, for the plan's
+navigation:
+
+- The root layout already exists and is CLI-owned — leave it.
+- One directory per section: `<routesDir>/(<section-slug>)/` with a `_layout.tsx` whose first
+  line is `// GENERATED by Mapples` and whose body renders `<Stack />`, `<Tabs />` (from
+  `expo-router`) or `<Drawer />` (from `expo-router/drawer`) per the section's type. This header
+  is the handshake: the CLI adopts the navigator kind from it and owns the file from then on.
+- One **minimal** route file per screen: `index.tsx` for the section's first screen, `<slug>.tsx`
+  for the rest — a `View` with one `Typography` (`variant="Headline"`, the screen name). Real
+  content comes per screen later; the scaffold only mints ids. When the plan has a single
+  section, put its files at the root of the routes dir instead of a group.
+- Do not write to `.mapples/`, do not touch the root `_layout.tsx`, do not create pages under
+  `pagesDir`.
+
+```bash
+npx -y mapples@__CLI_VERSION__ sync --yes --json
+```
+
+Assert no conflicts, then read `.mapples/pages.json`: every scaffolded file must be a value's
+`file` with a `routeId`. Note the `pageId` per screen; the `uuid` for `$actions` is in
+`.mapples/base/pages/<pageId>.json`. Screens now exist as empty pages in Creator. Re-read each
+route file — the CLI added the `// mapples-route:` marker and `$sid`s.
+
+Navigator and route options (headers, tab icons, initial route, modal presentation) are set in
+Creator, not from code, in this version: describe the intended chrome in `design.md` under
+`## Navigation chrome` so the user can apply it.
+
+## Phases 5…N-2 — one screen step at a time
+
+For each plan step, in order:
+
+1. `agent step … --status running`.
+2. Load the matching playbook(s) from `reference/playbooks/` (read the file; once per run):
+   `onboarding-flow`, `home-dashboard`, `list-and-detail`, `forms-and-auth`, `empty-states`,
+   `stats-and-progress`, `settings-profile`, `navigation-chrome`; `visual-hierarchy` and
+   `microcopy` with the first screen step.
+3. Re-read the route file. Write the **whole screen** in one edit: keep the marker line, keep
+   every existing `$sid` on the element it is on, add none. Obey `reference/layout-contract.md`
+   and the chosen style guide's instructions (they outrank the contract where they differ).
+   Real copy from the brief; picsum photos in every hero/featured/thumb slot.
+4. `npx -y mapples@__CLI_VERSION__ sync --yes --json`. Assert `exitCode` 0; read `warnings` and fix what is yours
+   (NON_LITERAL_PROP on a value you can make literal, UNKNOWN_ELEMENT). Exit 2 → resolve per
+   `mapples-sync`, sync again.
+5. Re-read the file (it now carries `$sid`s), run it through `reference/lint-checklist.md`
+   mentally, fix, sync again if you changed anything.
+6. `agent step … --status done --detail "<screen>: <what it shows>"`.
+
+Two screens in one plan step: do them one after the other inside the step, syncing after each.
+
+## Phase N-1 — Wiring
+
+Load `playbooks/screen-flow-wiring.md`. For every navigation the plan names, add to the source
+element's primary event both the Creator connection and the runtime handler:
+
+```tsx
+<Button
+  label="Get started"
+  variant="filled"
+  size="lg"
+  fullWidth
+  onPress={() => router.push('/(main)')}
+  $actions={{ onPress: { type: 'mapples:navigate', staticData: { pageUuid: '<uuid from base>' } } }}
+/>
+```
+
+(`import { router } from 'expo-router'`.) Rows and cards use their own `onPress`. Walk the golden
+path from the entry screen; every screen reachable, every flow with an exit. Sync; the report's
+`pushedOps` must cover every action you added.
+
+## Phase N — Review
+
+Load `reference/lint-checklist.md`. For every screen: re-read the file, check each item, fix.
+Then `npx -y mapples@__CLI_VERSION__ doctor --json` (no `duplicate`/`missing` issues; `drift` is fine before the final
+sync) and a final `npx -y mapples@__CLI_VERSION__ sync --yes --json` with exit 0. Update `design.md` with a `## Status`
+line (screens built, what was cut, the one decision the user may want to change). Then
+`npx -y mapples@__CLI_VERSION__ agent stop --status done`.
+
+Reply to the user in 3–5 lines: what was built, where to look in Creator, the one decision to
+revisit. No headings.
+
+## Working style
+
+- One screen, one edit — never element by element across many edits (each sync tags ids; many
+  partial syncs mean many rewrites).
+- After every sync, re-read before editing. Never keep a stale copy of a file in your head.
+- Prefer fewer screens fully designed over more screens sketched.
+- Ask only when a product decision is genuinely ambiguous; otherwise decide, state it in
+  `design.md`, move on.
+- Never emoji. Never lorem ipsum. Never `Text`. Never a hand-written `$sid`.

package/templates/claude/skills/mapples-design/reference/component-library.md

@@ -0,0 +1,128 @@
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
+# Component library — what to reach for
+
+Two packages, one canvas. Everything below is a registered canvas type: Creator renders it,
+its style panel edits it, and `npx -y mapples@__CLI_VERSION__ sync` round-trips it. Import primitives from
+`@mapples/ui`, the themed library from `@mapples/components`. Anything else you import is an
+opaque `Custom` node (allowed, but Creator cannot design inside it).
+
+## `@mapples/ui` — primitives
+
+| Type | Use | Notes |
+| --- | --- | --- |
+| `Container` | the screen root or a flex: 1 region | full-size column by default |
+| `View` | any column/row | width 100% in a column; content-sized in a row |
+| `SafeAreaView` | root that respects the notch | or paddingTop ≥ 48 on the root |
+| `ScrollView` | vertical scrolling content | spacing in `styled.contentContainerStyle` |
+| `HorizontalScrollView` | a rail of cards | full-bleed; `contentContainerStyle: { gap: 12, paddingHorizontal: 20 }` |
+| `FlatList` | long uniform lists | prefer `List` + `ListItem` for designed rows |
+| `GridTwoColumns` / `GridThreeColumns` / `GridFourColumns` | tile grids | children tile automatically |
+| `GradientBackground` | the one gradient accent per screen | `gradient` prop with literal hex stops |
+| `ImageBackgroundView` | photo with content over it | `source` + `overflow: 'hidden'` + a scrim child |
+| `Typography` | every piece of text | `text` + `variant` (Headline, Subtitle, Body, Caption, Overline, Button, Link, Label, Code) |
+| `Text` | never on a screen | bypasses the type scale |
+| `Image` | a picture | `source` (picsum URL), `contentFit="cover"`, explicit width/height |
+| `Icon` | a glyph from the project icon family | `iconName`; color/size in `styled.styleSvg` |
+| `IconButton` | icon-only tap target | `iconName`, `accessibilityLabel` (required), `badgeCount` |
+| `Pressable` | a custom tappable region | only when no library control fits |
+| `TextInput` | raw input | in forms use `InputField` instead |
+| `Select` | raw select | in forms use `SelectField` instead |
+| `Svg` / `Vector` / `Video` / `QRCode` / `BarCode` | media specials | as needed |
+| `FormView` / `TextField` / `SubmitButton` | form primitives | the library's `InputField`/`Button` are the designed versions |
+
+## `@mapples/components` — the themed library
+
+Library types paint themselves from the tokens; change their look through `variant`, `size`
+and `tone` props and the style slots — never rebuild one from Views. Array props (`options`,
+`items`, `columns`) are literal arrays.
+
+### actions
+
+| Type | Props to know | Use |
+| --- | --- | --- |
+| `Button` | `label`, `variant` filled\|outlined\|text\|tonal, `size` sm\|md\|lg, `fullWidth`, `leadingIconName`, `tone` | the primary action (filled lg fullWidth), secondary actions (outlined/text) |
+| `ButtonGroup` | `options` [{label, value}], `value` | a segmented pair of actions |
+| `Fab` | `iconName`, `accessibilityLabel`, `label`, `extended` | one floating primary action |
+| `TextLink` | `label`, `tone`, `underline` | Skip, Forgot password?, Sign in |
+| `BottomActionBar` | `sticky`; children | the sticky bar holding price + CTA on detail/checkout screens |
+
+### input
+
+| Type | Props to know | Use |
+| --- | --- | --- |
+| `InputField` | `label`, `placeholder`, `helperText`, `errorText`, `leadingIconName`, `keyboardType`, `autoCapitalize`, `secureTextEntry`, `showPasswordToggle`, `variant` outlined\|filled | every text field in a form |
+| `SelectField` | `label`, `options`, `placeholder`, `value` | dropdowns |
+| `Checkbox` | `label`, `value` | yes/no that lists |
+| `RadioGroup` | `options`, `value` | one exclusive choice |
+| `Switch` | `label`, `value` | a toggle |
+| `Slider` | `min`, `max`, `value`, `showValue` | a range |
+| `NumberStepper` | `min`, `max`, `value` | quantity |
+| `PinInput` | `length` | one-time codes |
+| `SearchBar` | `placeholder`, `value` | search (a filled pill by default) |
+| `ChatComposer` | `placeholder`, `leadingIconName` | the chat input pinned to the bottom |
+| `SegmentedControl` | `options`, `value` | switching a view mode |
+| `Rating` | `value`, `max`, `readOnly` | stars |
+| `ChipGroup` | `options` [{label, value, iconName?}], `value`, `variant` filter\|choice, `scrollable` | filters and tags |
+| `Chip` | `label`, `variant` assist\|filter\|suggestion, `selected` | a single tag (content-sized; inside a row) |
+
+### content
+
+| Type | Props to know | Use |
+| --- | --- | --- |
+| `Card` | `variant` elevated\|filled\|outlined; children | any surface that groups content |
+| `MediaCard` | `source`, `title`, `subtitle`, `meta`, `aspectRatio` | a photo-topped tile (rails, grids) |
+| `List` | `variant` plain\|inset\|card, `header`; `ListItem` children | rows — the List draws dividers and the surface |
+| `ListItem` | `title`, `subtitle`, `leading` icon\|avatar\|image\|none, `leadingIconName`, `source`, `trailing` chevron\|text\|switch\|checkbox\|none, `trailingText`, `tone` | one row |
+| `SectionHeader` | `title`, `actionLabel` | "Popular · See all" |
+| `Divider` | `inset` | a hairline between groups |
+| `Avatar` | `name` or `source`, `size` sm\|md\|lg\|xl, `badgeCount` | a person |
+| `AvatarGroup` | `items` [{name, source}], `max` | several people |
+| `Badge` | `label` or `count`, `variant` text\|dot\|count, `tone` | a status pill or a count |
+| `StatTile` | `label`, `value`, `unit`, `caption`, `trend`, `trendValue`, `iconName`, `variant` | a KPI |
+| `Table` | `columns` [{key, title}], `rows` | tabular data |
+| `Timeline` | `items` [{title, subtitle, time, status}] | a sequence of events |
+| `ImageCarousel` | `items` [{source, caption}] | swipeable photos |
+| `MessageBubble` | `text`, `direction` in\|out, `time`, `status` | a chat message |
+| `Accordion` | `items` [{title, content}] | FAQ / expandable rows |
+| `Skeleton` | `variant` text\|rect\|circle, `width`, `height` | a loading placeholder |
+
+### navigation (in-content)
+
+| Type | Props to know | Use |
+| --- | --- | --- |
+| `TopAppBar` | `title`, `showBack`, `actions` [{iconName, value}], `variant` small\|large | an in-content header ONLY when the stack header is hidden |
+| `BottomNavigationBar` | `items` [{label, iconName, value}], `value` | a single-screen demo of a tab shell — real tabs are a navigator |
+| `Tabs` | `items` [{label, value}], `value` | switching panels inside ONE screen |
+| `Breadcrumbs` | `items` [{label, value}], `separator`, `maxItems` | a path |
+| `Steps` | `items` [{label}], `current` | a multi-step progress |
+| `PageControl` | `count`, `value`, `variant` dots\|bars | onboarding page dots |
+
+### feedback
+
+| Type | Props to know | Use |
+| --- | --- | --- |
+| `ProgressBar` | `value`, `max`, `showLabel` | a goal or an upload |
+| `ProgressCircle` | `value`, `size`, `showLabel` | a ring |
+| `Spinner` | `size` | loading |
+| `Banner` | `title`, `message`, `tone`, `actionLabel` | an inline notice |
+| `Snackbar` | `message`, `actionLabel`, `visible` | a toast (last in the root, `visible={false}` unless bound) |
+| `EmptyState` | `iconName` or `imageSource`, `title`, `message`, `actionLabel`, `secondaryActionLabel`, `tone` | nothing to show |
+
+### overlays (last in the page root; `visible={false}` unless bound to a variable)
+
+| Type | Props to know | Use |
+| --- | --- | --- |
+| `Dialog` | `title`, `message`, `primaryActionLabel`, `secondaryActionLabel`, `tone`, `visible` | a confirmation |
+| `BottomSheet` | `title`, `visible`; children | a picker or a quick detail |
+| `ActionSheet` | `options` [{label, value, iconName?, destructive?}], `visible` | a list of actions |
+
+## Style slots
+
+`styled={{ style, styleTypography, styleSvg, styleImage, contentContainerStyle, placeholderTextColor }}` —
+`style` is the element's box; `styleTypography` its text (Button label, ListItem title, StatTile
+value); `styleSvg` its glyph; `contentContainerStyle` the scrolling content. Library components
+expose the same slots; use them for one-off tweaks (a card's `gap`, a rail's padding) and
+props for everything the component already knows how to do.
+
+> Prop names above follow the Creator's component digest; when unsure, keep to the ones listed
+> here — an unknown prop is ignored (and reported by the Creator lint as `unknown-prop`).

package/templates/claude/skills/mapples-design/reference/design-tokens.md

@@ -0,0 +1,132 @@
+<!-- GENERATED by Mapples __CLI_VERSION__ — re-run npx -y mapples@__CLI_VERSION__ agent install --force to refresh -->
+# Design tokens (phase 2) — `mapples/theme.ts`
+
+Ported from the Creator's full-variant generation (`generate.ts` `variantSystem` +
+`schemas.ts` `designVariantSchema`). The output is a file, not a JSON reply: `mapples/theme.ts`
+exports three **literal** objects — `theme`, `typography`, `sizing` — and `npx -y mapples@__CLI_VERSION__ sync` pushes
+them as the project's Theme, Typography and Sizing documents.
+
+## Rules
+
+Act as a senior product designer building a design system for this mobile app. The user
+already chose a style guide. Realize EXACTLY this style — same palette family (the preview
+colors are anchors to build around), same fonts, same shape language, same iconFamily.
+
+- Colors are hex. Provide BOTH light and dark maps; dark is a real dark design (dark surfaces,
+  lighter text), not an inversion. `primary.main` must have ≥ 4.5:1 contrast against
+  `primary.contrast`; `text.primary` against `background.primary` likewise. `neutral` runs
+  white→n50…n900→black as a smooth ramp in the theme's hue bias.
+- Fonts come ONLY from the library in `style-guides.md` (family + weight); body fonts must be
+  sans or a highly legible serif. `fontFamily` values are the registered names
+  `"<Family>-<Weight>"` (`"Manrope-SemiBold"`) with `fontWeight` matching the weight (Regular
+  400, Medium 500, SemiBold 600, Bold 700). Never "system", "Helvetica" or any other name: it
+  will not render.
+- The type scale is for a phone: Headline 26–34, Subtitle 18–22, Body 15–17, Caption 12–13,
+  Overline 10–12, Button 15–17, Link = Body, Code 13–14, Label 13–15. `lineHeight` ≈ 1.25× for
+  headlines, 1.5× for body. Headline and Subtitle share the headline font; Body, Caption, Label,
+  Link share the body font; Button and Overline share the button font; Code uses the mono font.
+  Overline is `textTransform: 'uppercase'`.
+- Sizing: `base` 4; `xs/sm/md/lg/xl` a clear scale (4/8/12–16/24/32), `screenPadding` 16–24,
+  `gap` 12–16, `radius` and `radiusLarge` to fit the direction (sharp directions near 0, soft
+  ones 16–28; `radiusLarge` ≥ `radius`), `control` 44–56, `card` 16–24, `icon` 20–28. All
+  multiples of `base`.
+- `instructions` (write them into `design.md` under `## Design instructions`, not into the
+  file): 150–300 words of concrete rules for every future screen — voice and copy tone, spacing
+  rules, component style (buttons, cards, inputs, lists), imagery and icon treatment, motion,
+  explicit do / don't lists. They MUST state the elevation language as a deliberate choice —
+  flat ("1px borders / contrasting surfaces, no shadows") is a first-class option and the right
+  one for calm, minimal, editorial or brutalist directions; when shadows are chosen, give the
+  exact soft recipe (offsets, blur ≥ 3× offset, rgba alpha ≤ 0.12) AND name the surfaces it
+  applies to plus where shadows are forbidden (inputs, chips, in-card rows). Also state the
+  corner-radius system (which radius which surface gets, including any top-only/bottom-only
+  corner rules for sheets and heroes), where a gradient accent is allowed (if anywhere), and the
+  imagery/placeholder style. Written for a designer who has never seen the product.
+
+## Bounds (the schema; a value outside them is a contract violation)
+
+- hex: `#rrggbb` or `#rrggbbaa`
+- text scale: `fontSize` 10–48 int, `lineHeight` 12–60 int, `letterSpacing` −2…3
+- sizing: `base` 2–8; `xs` 2–12, `sm` 4–16, `md` 8–24, `lg` 16–40, `xl` 24–64,
+  `screenPadding` 12–32, `gap` 8–24, `radius` 0–24, `radiusLarge` 0–40, `control` 40–64,
+  `card` 12–32, `icon` 16–32 — all ints
+
+## The file — copy this shape exactly, fill every value
+
+```ts
+// mapples/theme.ts — design tokens, synced with Creator by `npx -y mapples@__CLI_VERSION__ sync`.
+// Edit values freely; keys you add here are pushed to the canvas style config.
+
+export const theme = {
+  variant: 'auto',
+  defaultColor: '#1B1B1F', // = light.text.primary
+  light: {
+    background: { primary: '#FFFFFF', card: '#F7F7F9', contrast: '#1B1B1F' },
+    primary: { main: '#5B4DE0', light: '#8C82F0', dark: '#3D31B5', contrast: '#FFFFFF', background: '#EEECFC' },
+    accent: { main: '#F2994A', light: '#F7B980', dark: '#C8792F', contrast: '#1B1B1F', background: '#FDF1E6' },
+    text: { primary: '#1B1B1F', secondary: '#5A5B66', tertiary: '#8B8C99' },
+    neutral: {
+      white: '#FFFFFF', n50: '#F7F7F9', n100: '#EFEFF3', n200: '#E1E1E8', n300: '#C9C9D3',
+      n400: '#A6A7B5', n500: '#7F8090', n600: '#5A5B66', n700: '#3F404A', n800: '#2A2B33',
+      n900: '#1B1B1F', black: '#000000',
+    },
+    system: { info: '#2F80ED', success: '#27AE60', warning: '#F2C94C', error: '#EB5757' },
+  },
+  dark: {
+    background: { primary: '#121217', card: '#1C1C24', contrast: '#F5F5FA' },
+    primary: { main: '#8C82F0', light: '#B1AAF6', dark: '#5B4DE0', contrast: '#121217', background: '#26224A' },
+    accent: { main: '#F7B980', light: '#FAD1A9', dark: '#F2994A', contrast: '#121217', background: '#3A2A1A' },
+    text: { primary: '#F5F5FA', secondary: '#B8B9C6', tertiary: '#8B8C99' },
+    neutral: {
+      white: '#FFFFFF', n50: '#2A2B33', n100: '#3F404A', n200: '#4A4B57', n300: '#5A5B66',
+      n400: '#7F8090', n500: '#A6A7B5', n600: '#C9C9D3', n700: '#E1E1E8', n800: '#EFEFF3',
+      n900: '#F7F7F9', black: '#000000',
+    },
+    system: { info: '#5EA0F5', success: '#4CC77F', warning: '#F5D76E', error: '#F27C7C' },
+  },
+} as const;
+
+export const typography = {
+  fontFamily: 'Manrope-Regular', // = the Body font
+  color: '#1B1B1F', // = light.text.primary
+  default: 'Body',
+  typography: {
+    Headline: { fontFamily: 'Sora-Bold', fontWeight: '700', fontSize: 30, lineHeight: 38, letterSpacing: -0.5 },
+    Subtitle: { fontFamily: 'Sora-SemiBold', fontWeight: '600', fontSize: 20, lineHeight: 26, letterSpacing: -0.2 },
+    Body: { fontFamily: 'Manrope-Regular', fontWeight: '400', fontSize: 16, lineHeight: 24, letterSpacing: 0 },
+    Caption: { fontFamily: 'Manrope-Regular', fontWeight: '400', fontSize: 13, lineHeight: 18, letterSpacing: 0 },
+    Overline: { fontFamily: 'Manrope-SemiBold', fontWeight: '600', fontSize: 11, lineHeight: 16, letterSpacing: 1, textTransform: 'uppercase' },
+    Button: { fontFamily: 'Manrope-SemiBold', fontWeight: '600', fontSize: 16, lineHeight: 20, letterSpacing: 0.2 },
+    Link: { fontFamily: 'Manrope-Medium', fontWeight: '500', fontSize: 16, lineHeight: 24, letterSpacing: 0 },
+    Code: { fontFamily: 'IBMPlexMono-Regular', fontWeight: '400', fontSize: 14, lineHeight: 20, letterSpacing: 0 },
+    Label: { fontFamily: 'Manrope-Medium', fontWeight: '500', fontSize: 14, lineHeight: 20, letterSpacing: 0.1 },
+  },
+} as const;
+
+export const sizing = {
+  base: 4,
+  sizing: {
+    xs: 4, sm: 8, md: 12, lg: 24, xl: 32,
+    screenPadding: 20, gap: 12, radius: 12, radiusLarge: 24,
+    control: 48, card: 20, icon: 24,
+  },
+} as const;
+```
+
+The values above are an example, not the answer — every project gets its own. Keep the
+comments, the `as const`, the three named exports and no other statements: the CLI parses the
+file as literal objects (an import, a spread or a function call makes the whole file
+unreadable and the sync reports `NON_LITERAL_PROP … local style edits ignored`).
+
+## After writing
+
+```bash
+npx -y mapples@__CLI_VERSION__ sync --yes --json
+```
+
+Expect `pushedOps` ≥ 3 and `exitCode` 0. The tokens are now the project's; every style token
+string in a screen (`'theme.primary.main'`, `'sizing.md'`) resolves against them. Later edits to
+`mapples/theme.ts` merge per key with edits made in Creator; a same-key conflict deprecates the
+file and regenerates it from Creator — re-apply, never restore.
+
+> Not ported (Creator-only): the live token reveal, the review-feedback regeneration loop and
+> the `iconFamily` project setting (set it in Creator: Project → Settings → Icons).