@rokkit/cli 1.1.12 → 1.1.13

package/README.md

@@ -135,3 +135,21 @@ lib/
 ---
 
 Part of [Rokkit](https://github.com/jerrythomas/rokkit) — a Svelte 5 component library and design system.
+
+## AI skills
+
+Rokkit ships curated AI skills (SKILL.md guides) that teach coding agents how to
+use the library well — theming with the named-token system and building UI with
+the components.
+
+```bash
+rokkit skills list                       # see the catalog
+rokkit skills add semantic-styles-rokkit # install one
+rokkit skills add                        # interactive multi-select
+rokkit skills add --all                  # install everything
+rokkit skills add <name> --force         # overwrite an existing install
+```
+
+Skills install into your project's `.claude/skills/<name>/`, so they're shared
+with your team via version control. Browse the source under
+[`packages/cli/skills/`](./skills).

package/dist/src/init.d.ts

@@ -77,12 +77,20 @@ export function generateUnoConfig(): string;
 export function generateAppCssImports(themes: string[]): string[];
 /**
  * Generate the flash-prevention script for app.html.
- * Returns null when no script is needed (system switcher).
+ *
+ * Themes flip on `[data-mode="dark"]` only — there is no `@media
+ * (prefers-color-scheme)` fallback — so every switcher needs a script that
+ * resolves the mode pre-paint (mirrors `@rokkit/unocss`'s `themeHook`):
+ * - `system` tracks the OS preference directly (no persisted toggle).
+ * - `manual` / `full` read the persisted mode and resolve a stored-or-default
+ *   `'system'`/`'auto'` against the OS preference (default: follow the OS).
+ *
  * @param {string} switcher — 'system' | 'manual' | 'full'
  * @param {string} [storageKey='rokkit-theme']
- * @returns {string | null}
+ * @param {string} [defaultStyle='rokkit']
+ * @returns {string} the `<script>` tag to inject after `<body>`
  */
-export function generateInitScript(switcher: string, storageKey?: string, defaultStyle?: string): string | null;
+export function generateInitScript(switcher: string, storageKey?: string, defaultStyle?: string): string;
 /**
  * Interactive init command — prompts the user, writes config files.
  * @param {Record<string, unknown>} [_opts]

package/dist/src/skills.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Parse `name` and `description` from a SKILL.md YAML frontmatter block.
+ * @param {string} md
+ * @returns {{ name: string, description: string }}
+ */
+export function parseFrontmatter(md: string): {
+    name: string;
+    description: string;
+};
+/**
+ * Read the bundled skill catalog (derived from each SKILL.md's frontmatter).
+ * @param {{ skillsDir?: string }} [opts]
+ * @returns {Array<{ name: string, description: string }>}
+ */
+export function listSkills({ skillsDir }?: {
+    skillsDir?: string;
+}): Array<{
+    name: string;
+    description: string;
+}>;
+/**
+ * Copy named skills into <cwd>/.claude/skills/<name>/ (idempotent).
+ * @param {string[]} names
+ * @param {{ cwd?: string, force?: boolean, skillsDir?: string }} [opts]
+ * @returns {Array<{ name: string, status: 'added' | 'skipped' | 'unknown' }>}
+ */
+export function installSkills(names: string[], { cwd, force, skillsDir }?: {
+    cwd?: string;
+    force?: boolean;
+    skillsDir?: string;
+}): Array<{
+    name: string;
+    status: "added" | "skipped" | "unknown";
+}>;
+/**
+ * Print the catalog, marking already-installed skills.
+ * @param {{ skillsDir?: string, cwd?: string }} [opts]
+ */
+export function runSkillsList({ skillsDir, cwd }?: {
+    skillsDir?: string;
+    cwd?: string;
+}): Promise<void>;
+/**
+ * Resolve which skills to install, then copy and report.
+ * @param {string[]} names
+ * @param {{ all?: boolean, force?: boolean, skillsDir?: string, cwd?: string }} [opts]
+ */
+export function runSkillsAdd(names: string[], { all, force, skillsDir, cwd }?: {
+    all?: boolean;
+    force?: boolean;
+    skillsDir?: string;
+    cwd?: string;
+}): Promise<void>;
+/**
+ * CLI entry for `rokkit skills` subcommands.
+ * @param {'list' | 'add'} sub
+ * @param {{ _?: string[], all?: boolean, force?: boolean }} [opts]
+ */
+export function skillsCommand(sub: "list" | "add", opts?: {
+    _?: string[];
+    all?: boolean;
+    force?: boolean;
+}): Promise<void>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@rokkit/cli",
-  "version": "1.1.12",
+  "version": "1.1.13",
   "description": "Command line utilities for icon bundling and conversion.",
   "repository": {
     "type": "git",
@@ -36,6 +36,7 @@
   "files": [
     "lib/**/*",
     "src/**/*.js",
+    "skills/**",
     "dist/**/*.d.ts",
     "README.md",
     "package.json",

package/skills/rokkit-components/SKILL.md

@@ -0,0 +1,415 @@
+---
+name: rokkit-components
+description: Use when building UI with Rokkit components in a Svelte 5 app — the data-first contract (items, bindable value, fields field-mapping, onchange/onselect), snippet-based customization, built-in keyboard navigation + ARIA, and which component to reach for (List, Tree, Select, MultiSelect, Menu, Table, Tabs, Toggle).
+---
+
+# Rokkit Components — Usage
+
+Rokkit components are data-first: you pass an array, bind a value, and the component
+handles rendering, keyboard navigation, and accessibility out of the box. You extend
+behavior through the `fields` prop (remap data keys) and named snippets (customize
+rendering) — not by modifying components or writing boilerplate.
+
+Import from `@rokkit/ui`:
+
+```svelte
+import { List, Tree, Select, MultiSelect, Menu, Table, Tabs, Toggle } from '@rokkit/ui'
+```
+
+---
+
+## The data-first contract
+
+Every Rokkit component follows a consistent API:
+
+| Prop | Purpose |
+|------|---------|
+| `items` / `options` / `data` | The data array to render |
+| `bind:value` | Bindable selected value (or values array for MultiSelect) |
+| `fields` | Remap your data's key names to component semantic keys |
+| `onchange` / `onselect` | Callback fired when selection changes |
+
+Primitive arrays (strings, numbers) work without any transformation:
+
+```svelte
+<script>
+  import { List } from '@rokkit/ui'
+
+  const nav = ['Dashboard', 'Reports', 'Settings']
+  let value = $state(null)
+</script>
+
+<List items={nav} bind:value onselect={(v) => console.log('selected:', v)} />
+```
+
+Object arrays are equally direct — use `fields` only when your key names differ from defaults:
+
+```svelte
+<script>
+  import { Select } from '@rokkit/ui'
+
+  const countries = [
+    { code: 'us', name: 'United States' },
+    { code: 'gb', name: 'United Kingdom' }
+  ]
+  let value = $state(null)
+</script>
+
+<!-- fields remaps 'name' → label slot, 'code' → value slot -->
+<Select items={countries} fields={{ label: 'name', value: 'code' }} bind:value />
+```
+
+**Prop naming note:** `List`, `Tree`, `Select`, `MultiSelect`, and `Menu` all take `items`.
+`Tabs` and `Toggle` take `options`. `Table` takes `data`.
+
+---
+
+## Field mapping (fields)
+
+The `fields` prop is a plain object that maps **semantic slot names** → **your data's key names**.
+It never mutates your data — it is only a read instruction for the component.
+
+### Default field keys
+
+These are the raw key names each component reads by default. Override only the ones that differ in your data.
+
+| Semantic slot | Default key | Used by |
+|---------------|-------------|---------|
+| `label` / `text` | `'label'` / `'text'` | display text (see note) |
+| `value` | `'value'` | selection value |
+| `icon` | `'icon'` | icon CSS class |
+| `children` | `'children'` | nested items array |
+| `href` | `'href'` | URL (renders as `<a>`) |
+| `disabled` | `'disabled'` | disabled state |
+| `expanded` | `'expanded'` | initial expand state |
+| `type` | `'type'` | `'separator'` / `'spacer'` markers |
+| `snippet` | `'snippet'` | per-item named snippet override |
+| `badge` | `'badge'` | badge / count indicator |
+| `description` | `'description'` | secondary subtitle text |
+
+> **Text field note:** `List` / `Tree` / `Menu` read `item.label` by default.
+> `Select` / `MultiSelect` also read `item.label` (they use `fields.label || 'label'`
+> internally). Tabs reads `item.text` or `item.label`. `Toggle` reads `item.text`
+> (with `label` as fallback). When in doubt, provide both keys or use `fields`.
+
+### Remapping example
+
+Your API returns `{ id, title, subitems }`. Map to Rokkit slots with `fields`:
+
+```svelte
+<List
+  items={apiData}
+  fields={{ value: 'id', label: 'title', children: 'subitems' }}
+  bind:value
+/>
+```
+
+### Table columns
+
+`Table` uses a separate `columns` array to define column shapes. Row-level identity
+is set via `fields={{ value: 'id' }}` (defaults to `'id'`):
+
+```svelte
+<script>
+  import { Table } from '@rokkit/ui'
+
+  const columns = [
+    { name: 'name',   label: 'Full Name', sortable: true },
+    { name: 'role',   label: 'Role',      sortable: true },
+    { name: 'active', label: 'Active',    sortable: false, align: 'center' }
+  ]
+  const rows = [
+    { id: 1, name: 'Alice', role: 'Admin', active: true },
+    { id: 2, name: 'Bob',   role: 'Editor', active: false }
+  ]
+  let value = $state(null)
+</script>
+
+<Table data={rows} {columns} bind:value />
+```
+
+---
+
+## Snippet customization
+
+Snippets let you replace inner rendering without changing the component's
+wrapper, ARIA structure, or keyboard handling. The component always owns the
+interactive container (`<button>`, `<a>`, tab panel, etc.) — snippets control
+the **inner content** only.
+
+### itemContent — List, Tree, Menu (and Toggle, for option labels)
+
+The most common override. Receives a `ProxyItem` instance:
+
+```svelte
+<List {items} bind:value onselect={(v) => (value = v)}>
+  {#snippet itemContent(proxy)}
+    {#if proxy.icon}
+      <span class={proxy.icon} aria-hidden="true"></span>
+    {/if}
+    <span class="flex-1">{proxy.label}</span>
+    {#if proxy.get('badge')}
+      <span class="ml-auto text-xs text-ink-mute">{proxy.get('badge')}</span>
+    {/if}
+  {/snippet}
+</List>
+```
+
+### groupContent — List, Menu (not Tree — tree nodes use itemContent)
+
+Overrides the group header button content (the expand/collapse header row):
+
+```svelte
+<List {items} collapsible bind:value>
+  {#snippet groupContent(proxy)}
+    <span class={proxy.icon}></span>
+    <span>{proxy.label}</span>
+    <span class={proxy.expanded ? 'i-lucide:chevron-down' : 'i-lucide:chevron-right'}></span>
+  {/snippet}
+</List>
+```
+
+### ProxyItem API (passed to all content snippets)
+
+| Property / method | Description |
+|-------------------|-------------|
+| `proxy.label` | Mapped display text |
+| `proxy.icon` | Mapped icon CSS class |
+| `proxy.value` | The original raw item (object or primitive) |
+| `proxy.href` | Mapped href |
+| `proxy.disabled` | Whether this item is disabled |
+| `proxy.expanded` | Expand state for groups/nodes (reactive `$state`) |
+| `proxy.hasChildren` | True when the item has a `children` array |
+| `proxy.get('key')` | Read any field by semantic or raw name |
+
+### Select and MultiSelect snippets
+
+Select and MultiSelect do not expose a trigger or chips snippet — the trigger face
+and selected chips are rendered from `fields`/`label` and are not consumer-overridable.
+
+Both components support `itemContent` and `groupContent` for the **dropdown options**,
+using the same `ProxyItem` API as `List`:
+
+```svelte
+<Select {items} bind:value>
+  {#snippet itemContent(proxy)}
+    {#if proxy.icon}
+      <span class={proxy.icon} aria-hidden="true"></span>
+    {/if}
+    <span>{proxy.label}</span>
+    {#if proxy.get('description')}
+      <span class="text-xs text-ink-mute ml-auto">{proxy.get('description')}</span>
+    {/if}
+  {/snippet}
+</Select>
+```
+
+The same `itemContent` / `groupContent` patterns work identically on `MultiSelect`.
+
+### Tabs snippets
+
+`Tabs` supports `tabPanel` (receives one `ProxyItem` argument) and `itemContent`
+(for the tab trigger button content). Access panel data via `proxy.get('key')`:
+
+```svelte
+<Tabs {options} bind:value>
+  {#snippet tabPanel(proxy)}
+    <div class="p-4">
+      <h2 class="text-ink font-medium">{proxy.label}</h2>
+      <div>{proxy.get('content')}</div>
+    </div>
+  {/snippet}
+</Tabs>
+```
+
+`Tabs` also supports an `empty` snippet (no arguments) rendered when `options` is empty.
+
+### Per-item named snippets (List)
+
+Set `item.snippet = 'name'` on specific items to route them to a named snippet.
+Other items fall back to `itemContent`:
+
+```svelte
+<script>
+  const items = [
+    { label: 'Apple',  snippet: 'fruit' },
+    { label: 'Carrot', snippet: 'veggie' }
+  ]
+</script>
+
+<List {items}>
+  {#snippet fruit(proxy)}
+    <span class="i-lucide:apple"></span>
+    <span>{proxy.label}</span>
+  {/snippet}
+  {#snippet veggie(proxy)}
+    <span class="i-lucide:carrot"></span>
+    <span>{proxy.label}</span>
+  {/snippet}
+</List>
+```
+
+---
+
+## Keyboard navigation & accessibility
+
+Rokkit components are accessible out of the box — no extra wiring required as a consumer.
+The navigator pattern handles keyboard events on the component's root or dropdown container.
+
+### What you get for free
+
+| Component | Keys | ARIA |
+|-----------|------|------|
+| List / Tree | `↑↓` move focus, `↵`/`Space` select, `→`/`←` expand/collapse groups, `Home`/`End`, typeahead `a-z` | `role="navigation"`, `aria-current="page"` on active link |
+| Select / MultiSelect | `↑↓` navigate dropdown, `↵` select/toggle, `Esc` close, `Home`/`End` | `role="combobox"`, `aria-expanded`, `aria-selected` |
+| Menu | `↑↓` navigate items, `↵`/`Space` select, `Esc` close + return focus | `role="menu"`, `role="menuitem"` |
+| Tree | `↑↓` navigate, `→` expand/enter first child, `←` collapse/go to parent | `role="tree"`, `role="treeitem"`, `aria-expanded`, `aria-selected` |
+| Table | `↑↓` between rows, `↵`/`Space` select | `role="grid"`, `aria-sort` on sortable columns, `aria-selected` on rows |
+| Tabs | `←`/`→` (horizontal) or `↑`/`↓` (vertical) between tabs, `↵`/`Space` select | `role="tablist"`, `role="tab"`, `role="tabpanel"`, `aria-selected`, `aria-controls` |
+| Toggle | `←`/`→` between options, `↵`/`Space` select | `role="radiogroup"`, `role="radio"`, `aria-checked` |
+
+### Focus management note
+
+The components sync `bind:value` to DOM focus automatically — when `value` changes
+programmatically, the component moves keyboard focus to the matching item. You do not
+need to call `focus()` yourself.
+
+### Interactive elements inside snippets
+
+If your `itemContent` snippet contains its own interactive elements (inputs, buttons),
+stop propagation to prevent the navigator from also triggering selection:
+
+```svelte
+<List {items}>
+  {#snippet itemContent(proxy)}
+    <span class="flex-1">{proxy.label}</span>
+    <button
+      onclick={(e) => { e.stopPropagation(); doAction(proxy.value) }}
+    >
+      Action
+    </button>
+  {/snippet}
+</List>
+```
+
+Do NOT add an `onclick` on elements that also carry `data-path` — the navigator
+intercepts those clicks and would double-fire.
+
+---
+
+## Which component when
+
+| Need | Component | Data prop | Callback |
+|------|-----------|-----------|----------|
+| Vertical navigable list (sidebar nav, option list) | `List` | `items` | `onselect` |
+| Hierarchical tree with expand/collapse | `Tree` | `items` | `onselect` |
+| Dropdown single selection | `Select` | `items` | `onchange` |
+| Dropdown multi-selection with chips | `MultiSelect` | `items` | `onchange` |
+| Contextual action menu (dropdown actions) | `Menu` | `items` | `onselect` |
+| Flat data table with columns + row selection | `Table` | `data` | `onselect` |
+| Tabbed panels (horizontal or vertical) | `Tabs` | `options` | `onchange` |
+| Compact mode/view switcher (segmented control) | `Toggle` | `options` | `onchange` |
+
+**Use `List` not `Select`** when the options are always visible (sidebar, settings panel).
+**Use `Select` not `List`** when screen space is limited and the dropdown can close.
+**Use `Toggle` not `Tabs`** for 2–5 options with no panel content (just a mode switch).
+**Use `Tree` not `List`** when data is genuinely hierarchical (file system, nested categories).
+
+---
+
+## Recipes
+
+### Select bound to a value
+
+```svelte
+<script>
+  import { Select } from '@rokkit/ui'
+
+  const roles = [
+    { label: 'Admin',  value: 'admin' },
+    { label: 'Editor', value: 'editor' },
+    { label: 'Viewer', value: 'viewer' }
+  ]
+  let role = $state('viewer')
+</script>
+
+<Select items={roles} bind:value={role} onchange={(v) => console.log('role:', v)} />
+<p>Current role: {role}</p>
+```
+
+### Tree with nested children
+
+```svelte
+<script>
+  import { Tree } from '@rokkit/ui'
+
+  const files = [
+    {
+      label: 'src',
+      icon: 'i-lucide:folder',
+      children: [
+        { label: 'index.ts',  icon: 'i-lucide:file-code' },
+        { label: 'utils.ts',  icon: 'i-lucide:file-code' }
+      ]
+    },
+    { label: 'README.md', icon: 'i-lucide:file-text' }
+  ]
+
+  let selected = $state(null)
+</script>
+
+<Tree items={files} bind:value={selected} onselect={(v) => console.log('file:', v)} />
+```
+
+### MultiSelect with chips
+
+```svelte
+<script>
+  import { MultiSelect } from '@rokkit/ui'
+
+  const tags = [
+    { label: 'Frontend', value: 'fe' },
+    { label: 'Backend',  value: 'be' },
+    { label: 'DevOps',   value: 'ops' }
+  ]
+  let selected = $state([])
+</script>
+
+<MultiSelect
+  items={tags}
+  bind:value={selected}
+  placeholder="Select tags…"
+  onchange={(vals) => console.log('selected:', vals)}
+/>
+<p>Tags: {selected.join(', ')}</p>
+```
+
+### Table with explicit columns and field mapping
+
+```svelte
+<script>
+  import { Table } from '@rokkit/ui'
+
+  // Row identifier is 'uid' — remap via fields
+  const users = [
+    { uid: 1, fullName: 'Alice Chen',  dept: 'Engineering' },
+    { uid: 2, fullName: 'Bob Tanaka',  dept: 'Design' }
+  ]
+
+  const columns = [
+    { name: 'fullName', label: 'Name',       sortable: true },
+    { name: 'dept',     label: 'Department', sortable: true }
+  ]
+
+  let selectedUser = $state(null)
+</script>
+
+<Table
+  data={users}
+  {columns}
+  fields={{ value: 'uid' }}
+  bind:value={selectedUser}
+  caption="User list"
+  onselect={(v, row) => console.log('selected row:', row)}
+/>
+```

package/skills/semantic-styles-rokkit/SKILL.md

@@ -0,0 +1,390 @@
+---
+name: semantic-styles-rokkit
+description: Use when building, styling, or auditing a Rokkit-powered app (Svelte 5 + UnoCSS presetRokkit) — covers the named-token vocabulary (paper / ink / primary / on-primary / *-soft), the rokkit.config.js palette→skin→tokens pipeline, dual-palette dark mode, migrating legacy z-scale utilities (bg-surface-z0, text-primary-z5) to named tokens, and the rokkit init / rokkit doctor CLI.
+---
+
+# Semantic Styles — Rokkit
+
+Rokkit's token pipeline turns a small config into a consistent, themeable, dark-mode-ready
+set of utility classes. Components use **named tokens** (`bg-paper`, `text-ink`,
+`text-on-primary`) — never raw hex/oklch values. That indirection is the consistency
+guarantee: change the config, the whole app reskins.
+
+```
+rokkit.config.js
+  palettes + skin + colorSpace + tokens
+       ↓
+  UnoCSS preset (presetRokkit)  →  CSS custom properties + utility classes
+       ↓
+  Components use named-token utilities:  bg-paper · text-ink · bg-primary · text-on-primary
+  (legacy z-scale utilities — bg-surface-z1 — still resolve via back-compat aliases)
+```
+
+The pipeline has three layers. Most authoring happens in **Layer 3 (named tokens)**.
+
+---
+
+## Layer 1 — Palettes
+
+**What:** A palette is a named 11-stop color scale from shade `50` (lightest) to `950`
+(darkest), declared in `rokkit.config.js` under `palettes:`.
+
+**Why:** Each role needs a range of shades so hover, active, tint-on-surface, and
+text-on-fill all come from one color family. 11 stops gives resolution without banding.
+
+**Two formats:**
+
+*RGB hex* — standard web colors; use when you have an existing brand palette:
+```js
+palettes: { shu: { 50: '#FEF3EE', 500: '#E8552B', 950: '#3C100A' } }
+// colorSpace: 'rgb' (default — may be omitted)
+```
+
+*OKLCH bare components* — perceptual, uniform lightness steps; best for palettes designed
+from scratch (increment L by equal steps for balanced results):
+```js
+palettes: { shu: { 50: '0.970 0.020 35', 500: '0.580 0.150 35', 950: '0.220 0.060 35' } },
+colorSpace: 'oklch'   // REQUIRED when palette values are bare "L C H" components
+```
+
+The preset wraps values into complete colors when it emits CSS vars (see Layer 3).
+
+---
+
+## Layer 2 — Skin and skins
+
+**What:** A skin maps semantic role names to palette names. The core roles that back the
+named-token vocabulary are: `surface`, `ink`, `primary`, `accent`, `success`, `warning`,
+`danger`, `error`, `info`. (`secondary`/`tertiary` are accepted but no named token reads
+them — they only matter if you also use `extended` z-scale utilities for those roles.)
+
+**Why:** Decoupling role from palette lets you swap the whole scheme in config, not code.
+`bg-paper` doesn't know whether `surface` is `kami`, `slate`, or `zinc`.
+
+### Single skin (`skin:`) — one fixed colormap
+```js
+skin: {
+  surface: 'slate',  ink: 'slate',   // ink backs the ink-* text tokens
+  primary: 'orange', accent: 'sky',
+  success: 'green', warning: 'yellow', danger: 'red', error: 'red', info: 'cyan',
+}
+```
+`colors:` is accepted as a back-compat alias but **prefer `skin:`**. Always include an
+`ink` role — without it the `ink-*` text tokens silently fall back to the surface palette.
+
+### Multi-skin (`skins:`) — named colormaps for runtime switching
+```js
+skins: {
+  default: { surface: { light: 'kami', dark: 'sumi' }, ink: { light: 'kami', dark: 'sumi' }, primary: 'shu' },
+  ocean:   { surface: 'slate', primary: 'sky', accent: 'teal' },
+}
+```
+`skins.default` is active on first load. **Use `skin:` OR `skins:`, not both** — providing
+`skins:` makes `skin:` ignored.
+
+### `tokens:` — which CSS the preset emits
+```js
+tokens: 'core'      // default — emit the 24 named tokens (palette values inlined) + z-aliases
+tokens: 'extended'  // also emit the full 11-shade ladder (--color-{role}-{shade}) per role
+```
+`'core'` is the default and what apps should use. Reach for `'extended'` only when you need
+the full ladder (charts / data-viz). Per-role is allowed: `tokens: { surface: 'extended' }`.
+
+---
+
+## Layer 2b — Dual-palette dark mode (how the flip actually works)
+
+**Named tokens flip in dark mode ONLY when the skin uses a dual-palette `{ light, dark }`
+mapping for a role (or an override carries a `dark` value).** The preset emits a
+`[data-mode="dark"]` block redefining the tokens **only then** — there is no automatic
+z-flip in the themes CSS anymore.
+
+```js
+skin: {
+  surface: { light: 'kami', dark: 'sumi' },   // ← emits the dark block
+  ink:     { light: 'kami', dark: 'sumi' },
+  primary: 'shu',                              // single palette — constant across modes (correct for an accent)
+}
+```
+
+The trick is that the **dark palette is authored inverted** relative to the light one, so
+the same shade index reads correctly per mode:
+
+| token (shade) | light (`kami`)        | dark (`sumi`)         |
+|---------------|-----------------------|-----------------------|
+| `--paper` (50)  | `0.985…` (light bg)  | `0.170…` (dark bg)    |
+| `--ink` (900)   | `0.220…` (dark text) | `0.940…` (light text) |
+
+> **Gotcha:** a **single-palette** surface (e.g. `surface: 'slate'`) emits **no dark
+> block → no flip** → effectively light-only. For dark mode, make `surface` and `ink`
+> dual-palette (the canonical `kami`/`sumi` OKLCH pair, where `sumi` is authored inverted).
+> The `rokkit init` "Zen-Sumi" starter ships this; the plain Tailwind starter does not.
+
+Dark mode flips when `data-mode="dark"` is on `<html>`/`<body>` — see the wiring section
+below for how to apply and persist that correctly.
+
+---
+
+## Applying & persisting the theme (don't hand-roll this)
+
+**Never** hand-roll `data-mode` writes, `localStorage` save/load, or your own theme store.
+The pattern is: the **`vibe` store** (`@rokkit/states`) holds reactive state; the
+**`themable` action** (`@rokkit/actions`) syncs it to the DOM + storage; **`ThemeSwitcherToggle`**
+(`@rokkit/app`) is the ready-made control.
+
+**1. Wire the root once** (e.g. `+layout.svelte`). `themable` loads from storage on mount,
+writes `data-style`/`data-mode`/`data-density` (mirrored to `<html>` to match the
+flash-prevention init script), **saves on every change**, and syncs across tabs via the
+`storage` event:
+
+```svelte
+<script>
+  import { vibe } from '@rokkit/states'
+  import { themable } from '@rokkit/actions'
+</script>
+<svelte:body use:themable={{ theme: vibe, storageKey: 'app-theme' }} />
+```
+
+**2. Add the mode control** anywhere — it drives `vibe.mode`, which `themable` then writes:
+
+```svelte
+<script>import { ThemeSwitcherToggle } from '@rokkit/app'</script>
+<ThemeSwitcherToggle variant="single" />                 <!-- one button, cycles light ↔ dark -->
+<ThemeSwitcherToggle variant="triad" />                  <!-- group: system | light | dark (default) -->
+<ThemeSwitcherToggle variant="triad" includeSystem={false} />  <!-- group: light | dark -->
+```
+
+**3. Switch the visual style** by setting state — no DOM writes:
+```svelte
+<button onclick={() => (vibe.style = 'minimal')}>Minimal</button>
+```
+
+**4. Prevent the flash on first paint.** Inject the pre-paint script so the persisted
+theme applies before first render. SvelteKit apps use the SSR `themeHook`; static apps use
+the script `rokkit init` writes into `app.html`:
+
+```js
+// src/hooks.server.ts
+import { themeHook } from '@rokkit/unocss/hooks'
+export const handle = themeHook({ storageKey: 'app-theme', defaultMode: 'system' })
+```
+
+`defaultMode: 'system'` (also the default when omitted) resolves `prefers-color-scheme`
+to a concrete `light`/`dark` pre-paint — never an invalid `data-mode="system"`. `'auto'`
+is accepted as a legacy alias. (Requires `@rokkit/unocss` ≥ 1.1.12.)
+
+`vibe` (singleton) exposes reactive `mode` (`light`|`dark`), `style`
+(`rokkit`|`minimal`|`material`), `density` (`compact`|`comfortable`|`cozy`), `direction`,
+plus `load(key)` / `save(key)` / `update(partial)`. `ThemeSwitcherToggle` lives in
+`@rokkit/app` (the store-wired shell package), built on `@rokkit/ui`'s `Toggle`; it adds
+`system` on top of `vibe.mode` via `ColorModeManager` (resolving `system` through
+`prefers-color-scheme`). The `storageKey` must be the same everywhere — `themable`,
+`ThemeSwitcherToggle`'s store, and the flash-prevention script (step 4).
+
+---
+
+## Layer 3 — Named tokens (what components use)
+
+The 24-token core vocabulary, all flipping automatically under `[data-mode="dark"]`:
+
+| Group   | Tokens                                                  | Use                                              |
+|---------|---------------------------------------------------------|--------------------------------------------------|
+| Surface | `paper` · `paper-soft` · `paper-mute` · `paper-edge`    | canvas · card · subdued panel · hairline border  |
+| Text    | `ink` · `ink-mute` · `ink-soft` · `ink-faint`           | body · secondary · placeholder · disabled        |
+| Primary | `primary` · `on-primary`                                | CTA fill · text/icon on a primary fill           |
+| Accent  | `accent` · `accent-soft`                                | accent fill · tinted accent background           |
+| Status  | `success`/`-soft`, `warning`/`-soft`, `danger`/`-soft`, `error`/`-soft`, `info`/`-soft` | solid status · tinted callout bg |
+| Misc    | `focus-ring` · `shadow-tint`                            | focus ring color · shadow color                  |
+
+**Prefixes:** `bg-`, `text-`, `border-` (+ `border-t/-b/-l/-r`), `fill-`, `stroke-`,
+`ring-`, `outline-`, `divide-`. Two constraints: `on-primary` emits **text only**
+(`text-on-primary`); `focus-ring` emits ring/outline/border/divide only; `shadow-tint`
+emits no utility (used inside `box-shadow` expressions).
+
+```html
+<!-- card -->
+<div class="bg-paper-soft border border-paper-edge rounded-md p-4">
+  <h3 class="text-ink text-sm font-medium">Title</h3>
+  <p class="text-ink-mute text-xs mt-1">Description</p>
+</div>
+
+<!-- primary button + status badge -->
+<button class="bg-primary text-on-primary rounded-md px-3 py-2">Save</button>
+<span class="bg-success-soft text-success text-xs px-2 py-0.5 rounded-full">Active</span>
+
+<!-- input -->
+<input class="bg-paper border border-paper-edge text-ink rounded-md px-3 py-2
+              focus:border-primary focus:outline-none text-[13px]" />
+```
+
+### CSS custom properties
+
+Named tokens emit `--{token}` vars holding **complete color values** —
+`--paper: oklch(0.985 0.005 85)` (oklch) or `--primary: rgb(232, 85, 43)` (rgb). Use them
+directly in CSS-only contexts; for alpha, use `color-mix` (the form the preset itself uses):
+```css
+.thing      { background: var(--paper); border-color: var(--paper-edge); }
+.thing-50pc { background: color-mix(in oklch, var(--primary) 50%, transparent); }
+```
+Prefer utility classes over raw vars where you can. (In `core` mode the legacy
+`--color-{role}-z{n}` vars are aliases pointing at named tokens, so they too resolve to
+complete colors — the old "wrap bare components in `rgb()`/`oklch()`" rule no longer
+applies in core mode.)
+
+### Legacy z-scale utilities (back-compat)
+
+The older z-scale utilities (`bg-surface-z0`, `text-surface-z9`, `text-primary-z5`, …)
+**still resolve** as a back-compat layer that collapses onto the named tokens above —
+existing code keeps working. New code should use named tokens. See the migration section.
+
+---
+
+## Migrating from z-scale to named tokens
+
+`rokkit doctor` scans `src/**` and prints the suggested replacement per occurrence
+(advisory — it never rewrites your code). The mapping it uses:
+
+**Surface role** (`{prefix}-surface-z{n}` → `{prefix}-{token}`):
+
+| z | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
+|---|---|---|---|---|---|---|---|---|---|---|----|
+| token | `paper` | `paper-soft` | `paper-mute` | `paper-mute` | `paper-edge` | `ink-soft` | `ink-soft` | `ink-mute` | `ink-mute` | `ink` | `ink` |
+
+**Ink role** (inverted scale):
+
+| z | 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 |
+|---|---|---|---|---|---|---|---|---|---|---|----|
+| token | `ink` | `ink-mute` | `ink-mute` | `ink-soft` | `ink-soft` | `paper-edge` | `paper-edge` | `paper-mute` | `paper-mute` | `paper-soft` | `paper` |
+
+**Accent / status roles** (`primary`, `accent`, `success`, `warning`, `danger`, `error`,
+`info`): `z0–z2 → {role}-soft` (tinted background), `z3+ → {role}` (solid). Exception:
+`primary` has **no** `-soft` companion — `primary-z*` all map to `primary`; for a tinted
+primary background use `accent-soft` or a custom token.
+
+Common rewrites:
+```
+bg-surface-z0   → bg-paper            text-surface-z9 → text-ink
+bg-surface-z1   → bg-paper-soft       text-surface-z7 → text-ink-mute
+border-surface-z3 → border-paper-edge text-surface-z5 → text-ink-soft
+text-primary-z5 → text-primary        bg-success-z1   → bg-success-soft
+```
+
+---
+
+## Rokkit CLI — `init` and `doctor`
+
+**`rokkit init`** scaffolds `rokkit.config.js` in the named-token shape (a header comment
+documents the vocabulary). Two starters via the palette prompt:
+- **Tailwind (rgb)** — `skin` of Tailwind palette names, `colorSpace: 'rgb'`, `tokens: 'core'`. Single-palette → light-leaning (see Layer 2b).
+- **Zen-Sumi (OKLCH)** — ships `palettes` (kami/sumi/shu/…), `colorSpace: 'oklch'`, dual-palette `surface`/`ink` → full dark mode out of the box.
+
+**`rokkit doctor`** validates an existing setup. Beyond file checks (config exists,
+`uno.config.js` uses `presetRokkit(config)`, `app.css` imports a theme, `app.html` has the
+mode init script), it runs **advisory** config-shape warnings and migration hints — none
+fail the command or block `--fix`:
+
+| Check | Warns when |
+|-------|-----------|
+| `skin-ink-role` | the active colormap has no `ink` role (text tokens fall back) |
+| `oklch-needs-palettes` | `colorSpace: 'oklch'` but no `palettes` block |
+| `colors-alias` | config uses the legacy `colors:` instead of `skin:` |
+| legacy z-utilities | `src/**` contains `bg-surface-z*` / `text-primary-z*` etc. (prints named-token suggestions) |
+
+The "active colormap" is resolved the same way the preset does: `skins.default ?? skin ??
+colors`. Run `rokkit doctor --fix` to auto-write a real starter config when one is missing.
+
+---
+
+## Typography configuration
+
+Set faces in config; the preset emits CSS vars and Tailwind `fontFamily` keys.
+```js
+typography: {
+  display: "'Fraunces', 'Iowan Old Style', Georgia, serif",  // heading/display face
+  sans:    "'Inter', system-ui, sans-serif",                 // UI/body face (alias: `ui`)
+  mono:    "'JetBrains Mono', 'SF Mono', Menlo, monospace",
+}
+```
+Canonical config keys are `display` / `ui` / `mono`; `heading` / `sans` are accepted
+aliases. Usage classes: `font-heading` (display face), `font-body` (UI face), `font-mono`.
+```html
+<h1 class="font-heading text-2xl text-ink">Page Title</h1>
+<p  class="font-body text-[13px] text-ink-mute">Description</p>
+<code class="font-mono text-xs text-ink-soft">path/to/file.ts</code>
+```
+
+---
+
+## Shape / radius configuration
+
+`shape: { radius: 'soft' }` selects a preset emitting `--radius-{sm,md,lg,xl,full}`.
+
+| Preset | sm | md | lg | xl | full | Personality |
+|--------|----|----|----|----|------|-------------|
+| `sharp` | 0 | 0 | 0 | 0 | 9999px | Minimal, editorial |
+| `soft` | 2px | 6px | 10px | 12px | 9999px | Professional, calm |
+| `rounded` | 4px | 8px | 12px | 16px | 9999px | Friendly, modern |
+| `pill` | 9999px | 9999px | 9999px | 9999px | 9999px | Playful, pill-native |
+
+Custom: `shape: { radius: { sm: '2px', md: '6px', lg: '10px', xl: '14px', full: '9999px' } }`.
+Use the Tailwind radius utilities that map to the vars (`rounded-md`, `rounded-lg`, …) —
+never `rounded-[6px]`, which bypasses the config.
+
+---
+
+## Spacing
+
+Rokkit inherits Tailwind's 4px-grid spacing. **Stay on the 4px grid, use Tailwind names.**
+
+| Tailwind | px | When |
+|----------|----|------|
+| `1` / `2` / `3` | 4 / 8 / 12 | tight gap · component gap · compact padding |
+| `4` / `6` | 16 / 24 | default padding · panel padding |
+| `8` / `12` / `16` | 32 / 48 / 64 | section separation · page padding · hero whitespace |
+
+Density: **compact** (tables/sidebars) `gap-1`/`gap-2`, `p-2`/`p-3`; **comfortable**
+(cards/forms) `gap-3`/`gap-4`, `p-4`/`p-6`; **relaxed** (marketing) `16–24px+`.
+
+---
+
+## Full config example
+
+```js
+// rokkit.config.js
+export default {
+  palettes: {
+    kami: { 50: '0.985 0.005 85', /* … */ 950: '0.170 0.010 50' },  // light surface (warm paper)
+    sumi: { 50: '0.170 0.010 50', /* … */ 950: '0.975 0.008 85' },  // dark surface (inverted ink)
+    shu:  { 50: '0.970 0.020 35', 500: '0.580 0.150 35', 950: '0.220 0.060 35' },  // accent
+  },
+  colorSpace: 'oklch',          // required for bare "L C H" palette values
+  tokens: 'core',               // emit the named-token vocabulary (default)
+  skin: {
+    surface: { light: 'kami', dark: 'sumi' },   // dual-palette → dark mode
+    ink:     { light: 'kami', dark: 'sumi' },
+    primary: 'shu', accent: 'shu',
+    success: 'hisui', warning: 'kohaku', danger: 'shu', error: 'shu', info: 'kohaku',
+  },
+  typography: { display: "'Fraunces', Georgia, serif", sans: "'Inter', sans-serif", mono: "'JetBrains Mono', monospace" },
+  shape: { radius: 'soft' },
+  switcher: 'full',             // 'system' | 'manual' | 'full'
+  storageKey: 'app-theme',
+}
+```
+
+---
+
+## Common mistakes
+
+| Mistake | Why it fails | Fix |
+|---|---|---|
+| `color: #3D3730` in a component | breaks on theme change | `text-ink` (or the right named token) |
+| Using `bg-surface-z5` / `text-primary-z5` in new code | legacy back-compat layer | named tokens — see migration table (or run `rokkit doctor`) |
+| Single-palette `surface` but expecting dark mode | no `[data-mode]` block is emitted | make `surface`/`ink` dual-palette `{ light, dark }` |
+| Skin with no `ink` role | `ink-*` text tokens fall back to surface | add `ink: '<palette>'` (reuse surface is fine) |
+| Using `skin:` and `skins:` together | `skins:` silently wins | pick one |
+| `oklch(0.58 0.15 35)` literal in a component | loses theming + composability | `bg-primary` / `var(--primary)` |
+| Double-wrapping in core mode: `oklch(var(--paper))` | `--paper` is already a complete color | use `var(--paper)` directly |
+| `colorSpace: 'oklch'` with hex palettes (or vice-versa) | wrap form won't match values | match `colorSpace` to the palette format |
+| `border-radius: 6px` / `font-family: 'Inter'` hardcoded | bypasses shape/typography config | `rounded-md` / `font-body` |
+| `@apply bg-paper` on `body {}` | descendant-combinator shortcut can't match `body` when `data-mode` is on it | `body { background: var(--paper); }` |

package/src/index.js

@@ -121,4 +121,22 @@ prog
 		await theme('create', opts)
 	})
 
+prog
+	.command('skills list')
+	.describe('List available Rokkit AI skills')
+	.action(async () => {
+		const { skillsCommand } = await import('./skills.js')
+		await skillsCommand('list')
+	})
+
+prog
+	.command('skills add')
+	.describe('Add Rokkit AI skills to .claude/skills/')
+	.option('--all', 'Install all available skills')
+	.option('--force', 'Overwrite an existing skill')
+	.action(async (opts) => {
+		const { skillsCommand } = await import('./skills.js')
+		await skillsCommand('add', opts)
+	})
+
 prog.parse(process.argv)

package/src/init.js

@@ -314,13 +314,30 @@ export function generateAppCssImports(themes) {
 
 /**
  * Generate the flash-prevention script for app.html.
- * Returns null when no script is needed (system switcher).
+ *
+ * Themes flip on `[data-mode="dark"]` only — there is no `@media
+ * (prefers-color-scheme)` fallback — so every switcher needs a script that
+ * resolves the mode pre-paint (mirrors `@rokkit/unocss`'s `themeHook`):
+ * - `system` tracks the OS preference directly (no persisted toggle).
+ * - `manual` / `full` read the persisted mode and resolve a stored-or-default
+ *   `'system'`/`'auto'` against the OS preference (default: follow the OS).
+ *
  * @param {string} switcher — 'system' | 'manual' | 'full'
  * @param {string} [storageKey='rokkit-theme']
- * @returns {string | null}
+ * @param {string} [defaultStyle='rokkit']
+ * @returns {string} the `<script>` tag to inject after `<body>`
  */
 export function generateInitScript(switcher, storageKey = 'rokkit-theme', defaultStyle = 'rokkit') {
-	if (switcher === 'system') return null
+	if (switcher === 'system') {
+		return `    <script>
+      (function () {
+        try {
+          document.body.dataset.mode =
+            matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+        } catch (e) {}
+      })()
+    </script>`
+	}
 
 	const setStyle =
 		switcher === 'full' ? `b.dataset.style = t.style || '${defaultStyle}'\n          ` : ''
@@ -330,7 +347,10 @@ export function generateInitScript(switcher, storageKey = 'rokkit-theme', defaul
         try {
           var t = JSON.parse(localStorage.getItem('${storageKey}') || '{}')
           var b = document.body
-          ${setStyle}b.dataset.mode = t.mode || 'dark'
+          ${setStyle}var m = t.mode || 'system'
+          if (m === 'system' || m === 'auto')
+            m = matchMedia('(prefers-color-scheme: dark)').matches ? 'dark' : 'light'
+          b.dataset.mode = m
         } catch (e) {}
       })()
     </script>`

package/src/skills.js

@@ -0,0 +1,141 @@
+/* eslint-disable no-console */
+import { readFileSync, readdirSync, existsSync, mkdirSync, cpSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import prompts from 'prompts'
+
+// The catalog ships inside the package: packages/cli/skills/ in dev/test,
+// node_modules/@rokkit/cli/skills/ once installed. One relative path, both worlds.
+// Guard against non-file: URLs (e.g. jsdom sets import.meta.url to http://localhost/...).
+const DEFAULT_SKILLS_DIR = (() => {
+	try {
+		return fileURLToPath(new URL('../skills/', import.meta.url))
+	} catch {
+		return resolve(process.cwd(), 'packages/cli/skills')
+	}
+})()
+
+/**
+ * Parse `name` and `description` from a SKILL.md YAML frontmatter block.
+ * @param {string} md
+ * @returns {{ name: string, description: string }}
+ */
+export function parseFrontmatter(md) {
+	// Keep these as literal regexes — do NOT collapse into a dynamic
+	// `new RegExp(`^${key}:...`)` helper: the keys are fixed, so the dynamic form
+	// adds nothing but trips the no-dynamic-regex lint, and the literals are
+	// plainly linear-time. The `?.[1]?.trim() ?? ''` chain returns '' for a
+	// missing block, a missing field, or a bare `key:` with no value.
+	const block = md.match(/^---\n([\s\S]*?)\n---/)?.[1] ?? ''
+	const name = block.match(/^name:\s*(.+)$/m)?.[1]?.trim() ?? ''
+	const description = block.match(/^description:\s*(.+)$/m)?.[1]?.trim() ?? ''
+	return { name, description }
+}
+
+/**
+ * Read the bundled skill catalog (derived from each SKILL.md's frontmatter).
+ * @param {{ skillsDir?: string }} [opts]
+ * @returns {Array<{ name: string, description: string }>}
+ */
+export function listSkills({ skillsDir = DEFAULT_SKILLS_DIR } = {}) {
+	if (!existsSync(skillsDir)) return []
+	return readdirSync(skillsDir)
+		.filter((entry) => existsSync(join(skillsDir, entry, 'SKILL.md')))
+		.map((entry) => parseFrontmatter(readFileSync(join(skillsDir, entry, 'SKILL.md'), 'utf-8')))
+		.filter((s) => s.name)
+		.sort((a, b) => a.name.localeCompare(b.name))
+}
+
+/**
+ * Copy named skills into <cwd>/.claude/skills/<name>/ (idempotent).
+ * @param {string[]} names
+ * @param {{ cwd?: string, force?: boolean, skillsDir?: string }} [opts]
+ * @returns {Array<{ name: string, status: 'added' | 'skipped' | 'unknown' }>}
+ */
+export function installSkills(
+	names,
+	{ cwd = process.cwd(), force = false, skillsDir = DEFAULT_SKILLS_DIR } = {}
+) {
+	const targetRoot = resolve(cwd, '.claude', 'skills')
+	return names.map((name) => {
+		const src = join(skillsDir, name)
+		if (!existsSync(join(src, 'SKILL.md'))) return { name, status: 'unknown' }
+		const dest = join(targetRoot, name)
+		if (existsSync(dest) && !force) return { name, status: 'skipped' }
+		mkdirSync(targetRoot, { recursive: true })
+		cpSync(src, dest, { recursive: true })
+		return { name, status: 'added' }
+	})
+}
+
+/**
+ * Print the catalog, marking already-installed skills.
+ * @param {{ skillsDir?: string, cwd?: string }} [opts]
+ */
+export async function runSkillsList({ skillsDir, cwd = process.cwd() } = {}) {
+	const catalog = listSkills({ skillsDir })
+	if (catalog.length === 0) {
+		console.info('No skills available.')
+		return
+	}
+	const installedRoot = resolve(cwd, '.claude', 'skills')
+	console.info('Available Rokkit skills:\n')
+	for (const s of catalog) {
+		const mark = existsSync(join(installedRoot, s.name, 'SKILL.md')) ? '✓ ' : '  '
+		console.info(`${mark}${s.name}`)
+		console.info(`     ${s.description}`)
+	}
+	console.info('\nInstall with: rokkit skills add <name> [...]   (or --all)')
+}
+
+/**
+ * Resolve which skills to install, then copy and report.
+ * @param {string[]} names
+ * @param {{ all?: boolean, force?: boolean, skillsDir?: string, cwd?: string }} [opts]
+ */
+export async function runSkillsAdd(
+	names,
+	{ all = false, force = false, skillsDir, cwd = process.cwd() } = {}
+) {
+	const catalog = listSkills({ skillsDir })
+	let selected = names
+	if (all) {
+		selected = catalog.map((s) => s.name)
+	} else if (selected.length === 0) {
+		const res = await prompts({
+			type: 'multiselect',
+			name: 'picked',
+			message: 'Select skills to add',
+			choices: catalog.map((s) => ({ title: s.name, value: s.name, description: s.description }))
+		})
+		selected = res.picked ?? []
+	}
+	if (selected.length === 0) {
+		console.info('No skills selected.')
+		return
+	}
+	const results = installSkills(selected, { cwd, force, skillsDir })
+	for (const r of results) {
+		if (r.status === 'added') console.info(`  added .claude/skills/${r.name}`)
+		else if (r.status === 'skipped')
+			console.info(`  skipped ${r.name} (exists — use --force to overwrite)`)
+		else console.error(`  unknown skill: ${r.name}`)
+	}
+	if (results.some((r) => r.status === 'unknown')) {
+		console.error(`\nValid skills: ${catalog.map((s) => s.name).join(', ')}`)
+		process.exitCode = 1
+	}
+}
+
+/**
+ * CLI entry for `rokkit skills` subcommands.
+ * @param {'list' | 'add'} sub
+ * @param {{ _?: string[], all?: boolean, force?: boolean }} [opts]
+ */
+export async function skillsCommand(sub, opts = {}) {
+	if (sub === 'add') {
+		await runSkillsAdd(opts._ ?? [], { all: opts.all, force: opts.force })
+	} else {
+		await runSkillsList()
+	}
+}