@fluid-app/fluid-cli-theme-dev 0.1.41 → 0.1.43

package/dist/skills/themes-settings-schema/SKILL.md

@@ -0,0 +1,283 @@
+---
+name: themes-settings-schema
+description: |
+  Authors and audits `config/settings_schema.json` in a Fluid theme so the Visual Builder
+  actually resolves it — text presets group into cards, fonts and weights link to the
+  presets that use them, and rich-text blocks pick up theme typography. Use when writing a
+  theme's global settings from scratch, when the Themes panel renders a group as a flat
+  list of unrelated controls instead of preset cards, when a font or weight dropdown is
+  empty or shows the wrong names, when changing a theme setting does not move the preview,
+  or when the rich-text preset picker shows no presets. Covers the exact rules the builder
+  classifies settings by (what becomes a text preset, what counts as a font or a weight),
+  the `role` / `font_family_ref` / `font_weight_ref` linkage, the CSS-variable contract in
+  `layouts/theme.liquid` that makes any of it reach the page, `option_group` tokens that
+  feed section dropdowns, and the keys the builder writes back into your schema. Companion
+  to `themes-review` — that one reviews a whole theme, this one gets the settings schema
+  right.
+---
+
+# Settings Schema Authoring
+
+`config/settings_schema.json` has two readers, and they are stricter than the file format suggests:
+
+1. **The Visual Builder's Themes panel** — turns the schema into editing UI, and groups typography into per-preset cards.
+2. **The rich-text preset picker** — resolves each text preset into a concrete font size, weight and family so a merchant can apply "H1" to a paragraph.
+
+Both infer structure from **ids, types, labels and a few reserved keys**. A schema that lints fine can still render as a flat wall of controls, or produce presets that do nothing. This skill is the contract.
+
+> Prerequisite: [`themes-review/references/setting-types.md`](../themes-review/references/setting-types.md) lists every valid `type`, and [`themes-review/references/global-settings.md`](../themes-review/references/global-settings.md) covers the globals pipeline generally. This skill covers what the *builder* additionally requires.
+
+## Work in this order
+
+1. **Groups** — get the group names right; a few carry behaviour.
+2. **Fonts and weights** — declare the theme's typefaces and weight vocabulary once.
+3. **Text presets** — declare sizes and link each to a font and a weight.
+4. **CSS variables** — wire every setting into `layouts/theme.liquid`, or none of it reaches the page.
+5. **Audit** — run the checks at the bottom.
+
+Read [`references/typography-presets.md`](references/typography-presets.md) before step 3 and [`references/css-variables.md`](references/css-variables.md) before step 4. They hold the exact resolution rules; the summaries here are not sufficient to author against.
+
+## Step 1 — Groups
+
+The outer array is **grouped, not flat**. Each object with a `name` becomes one accordion in the panel.
+
+| Group `name` | Behaviour |
+| --- | --- |
+| `typography` | **The only group rendered as text-preset cards.** Any other name renders a flat list, however the settings are shaped. |
+| `custom_font_sizes`, `custom_colors` | Hidden from the panel. Builder-managed — presets a merchant creates from the rich-text toolbar land here. Do not hand-author them. |
+| `theme_info` | Metadata only, no `settings` array. |
+| anything else | Flat list of controls, in schema order. |
+
+Two things the panel silently drops, which surprise most authors:
+
+- **A setting without a string `id`, `type` *and* `label` is discarded.** That includes every `{"type": "header", "content": "…"}` — headers render in section schemas but **not** in the Themes panel. Do not rely on them to separate groups of settings; use a real group instead.
+- **A group whose settings all get discarded is dropped entirely.**
+
+## Step 2 — Fonts and weights
+
+Declare each typeface the theme offers as one `font_picker`, and each weight in the theme's vocabulary as its own setting.
+
+```json
+{
+  "name": "fonts",
+  "settings": [
+    {
+      "type": "font_picker",
+      "id": "font_family_heading",
+      "label": "Heading font",
+      "default": "Reckless Neue",
+      "options": [
+        { "value": "Reckless Neue", "label": "Reckless Neue" },
+        { "value": "Basis Grotesque", "label": "Basis Grotesque" }
+      ]
+    },
+    {
+      "type": "font_picker",
+      "id": "font_family_body",
+      "label": "Body font",
+      "default": "Basis Grotesque",
+      "options": [
+        { "value": "Reckless Neue", "label": "Reckless Neue" },
+        { "value": "Basis Grotesque", "label": "Basis Grotesque" }
+      ]
+    }
+  ]
+}
+```
+
+**Name fonts by role in the id, not in the label.** The panel labels a font in a preset's picker from its **id** with the `font_family_` prefix stripped — `font_family_heading` shows as "Heading". This exists because themes habitually label both of their font settings "Font family", which tells a merchant nothing about which is which. Give ids meaning:
+
+| Id | Shows in the preset picker as |
+| --- | --- |
+| `font_family_heading` | Heading |
+| `font_family_body` | Body |
+| `font_family_display` | Display |
+| `brand_typeface` | falls back to the label — no recognisable prefix |
+
+`font_family_heading` and `font_family_body` are additionally **reserved**: they are what a preset falls back to when it declares no explicit font. Define at least one of them.
+
+Weights are a vocabulary, one setting per step:
+
+```json
+{
+  "name": "font_weights",
+  "settings": [
+    { "type": "range", "id": "font_weight_light",  "label": "Light",  "min": 100, "max": 900, "step": 100, "default": 300 },
+    { "type": "range", "id": "font_weight_normal", "label": "Normal", "min": 100, "max": 900, "step": 100, "default": 400 },
+    { "type": "range", "id": "font_weight_bold",   "label": "Bold",   "min": 100, "max": 900, "step": 100, "default": 700 }
+  ]
+}
+```
+
+Weights are labelled from their **label**, not their id — "Light", "Bold" are already the names a merchant wants.
+
+## Step 3 — Text presets
+
+A text preset is a **font-size setting** that links to a font and a weight. Put them in the `typography` group.
+
+```json
+{
+  "name": "typography",
+  "settings": [
+    {
+      "type": "range",
+      "id": "font_size_h1",
+      "label": "H1",
+      "min": 32, "max": 120, "step": 1,
+      "unit": "px",
+      "default": 64,
+      "role": "heading",
+      "font_family_ref": "font_family_heading",
+      "font_weight_ref": "font_weight_bold"
+    },
+    {
+      "type": "range",
+      "id": "font_size_base",
+      "label": "Base",
+      "min": 14, "max": 20, "step": 0.5,
+      "unit": "px",
+      "default": 16,
+      "role": "body",
+      "font_family_ref": "font_family_body",
+      "font_weight_ref": "font_weight_normal"
+    }
+  ]
+}
+```
+
+| Key | Why |
+| --- | --- |
+| `unit` | Appended to the size. Omitted means `px`. |
+| `role` | `heading` or `body`. Picks the default weight (bold / normal) and the fallback font. Without it, an id starting `font_size_h` is read as a heading and everything else as body. **Always set it explicitly** — the id convention is a legacy fallback. |
+| `font_family_ref` | Id of the font setting this preset uses. Resolves **anywhere in the schema**, so the font may live in another group. |
+| `font_weight_ref` | Id of the weight setting this preset uses. Same resolution. |
+
+**Refs are authoritative.** A `font_family_ref` pointing at an id that does not exist gives the preset **no font at all** — it does not fall back to the role font. Typos fail loudly rather than silently doing something plausible. A dangling `font_weight_ref` does fall back to the role weight.
+
+Both refs are optional. Omit them and the preset derives its font from `role` (`heading` → `font_family_heading`, `body` → `font_family_body`, each falling back to the other when only one exists) and its weight from `role` (`bold` / `normal`). Explicit refs are better: they survive an id rename showing up as a visible break rather than a silent change in meaning.
+
+Full rules, including exactly what does and does not become a preset: [`references/typography-presets.md`](references/typography-presets.md).
+
+## Step 4 — CSS variables
+
+**A schema on its own changes nothing.** `layouts/theme.liquid` must publish each setting as a CSS custom property, and the theme's CSS must consume it:
+
+```liquid
+{% style %}
+  :root {
+    --font_family_heading: {{ settings.font_family_heading }};
+    --font_family_body:    {{ settings.font_family_body }};
+    --font_weight_bold:    {{ settings.font_weight_bold }};
+    --font_size_h1:        {{ settings.font_size_h1 }}px;
+  }
+{% endstyle %}
+```
+
+Two rules that are easy to miss:
+
+- **The builder matches the exact form `--anything: {{ settings.<id> }}`** inside a `{% style %}` or `<style>` block. A setting with no such declaration still edits fine, but presets referencing it cannot link to a variable, so rich-text content gets a baked literal instead of something that follows later edits.
+- **Name the variable after the setting id.** Any name works for *reading*, but the builder writes and removes `--<id>` when it manages a variable for you. Matching keeps hand-authored and builder-authored declarations from diverging.
+
+Details, including the per-preset alias variables the builder maintains and why repointing a preset needs them: [`references/css-variables.md`](references/css-variables.md).
+
+## Step 5 — Section dropdowns from theme settings
+
+A theme setting can publish itself into a named token list that **section** settings then reference by id, instead of every section hardcoding the same options. See [`references/option-groups.md`](references/option-groups.md).
+
+## What the builder writes back
+
+The Themes panel edits `config/settings_schema.json` in place. Expect these and leave them alone:
+
+| What | Written when |
+| --- | --- |
+| `generated_for: "<group or preset>"` on a setting | The builder created that setting — a font added via **Add font**. Only settings carrying this key can be removed through the panel; one you authored is never deleted, because the theme's own Liquid may read it. |
+| New entries in every `font_picker`'s `options` | A merchant added a Google font or uploaded a font file. It becomes selectable on every font in the theme. |
+| `font_family_ref` / `font_weight_ref` on a preset | A merchant repointed that preset. |
+| `--<preset_id>_font_family` / `_font_weight` in `layouts/theme.liquid` | A preset was applied to rich-text content. See [`references/css-variables.md`](references/css-variables.md). |
+
+Do not strip `generated_for` by hand: it is the only thing separating a setting the builder may remove from one it must not.
+
+## Authoring checklist
+
+- [ ] Groups are named objects; the preset group is named exactly `typography`
+- [ ] No reliance on `header` settings for structure in the Themes panel
+- [ ] Every setting has a unique, meaningful `id`, plus `type` and `label`
+- [ ] Font ids carry the role (`font_family_heading`, not `brand_typeface`)
+- [ ] At least one of `font_family_heading` / `font_family_body` exists
+- [ ] Every preset sets `role` explicitly
+- [ ] Every preset sets `unit`
+- [ ] Every `*_ref` points at an id that exists
+- [ ] No size preset's id or label contains "font weight" (it would stop being a preset — see the pitfalls reference)
+- [ ] `layouts/theme.liquid` declares `--<id>: {{ settings.<id> }}` for every font, weight and size
+- [ ] The theme's CSS consumes those variables rather than hardcoding fonts
+
+## Audit
+
+```bash
+# Groups, in order — is there one named exactly "typography"?
+jq -r '.[].name' config/settings_schema.json
+
+# Every setting id, with its type — duplicates here are a bug
+jq -r '.[].settings[]? | "\(.id // "-")\t\(.type)"' config/settings_schema.json | sort | uniq -d
+
+# Presets and what they link to
+jq -r '.[] | select(.name=="typography") | .settings[]?
+       | select(.font_family_ref or .font_weight_ref or (.id // "" | startswith("font_size")))
+       | "\(.id)\trole=\(.role // "-")\tfamily=\(.font_family_ref // "-")\tweight=\(.font_weight_ref // "-")\tunit=\(.unit // "px")"' \
+  config/settings_schema.json
+
+# Refs that point at nothing — must print nothing
+jq -r '[.[].settings[]?.id] as $ids
+       | .[].settings[]? | select(.font_family_ref and (.font_family_ref | IN($ids[]) | not))
+       | "DANGLING family_ref: \(.id) -> \(.font_family_ref)"' config/settings_schema.json
+jq -r '[.[].settings[]?.id] as $ids
+       | .[].settings[]? | select(.font_weight_ref and (.font_weight_ref | IN($ids[]) | not))
+       | "DANGLING weight_ref: \(.id) -> \(.font_weight_ref)"' config/settings_schema.json
+
+# Fonts, weights and presets the layout does not publish as a CSS variable.
+# Anything listed here cannot be linked, so content applying it gets a baked
+# literal instead of something that follows later edits.
+#
+# Two halves, and both matter:
+#
+#   LINKED   what the builder can actually see — a `--x: {{ settings.<id> }}`
+#            custom property *inside* a {% style %} or <style> block. A
+#            {{ settings.<id> }} in a meta tag, an inline style= attribute, or
+#            `font-family: {{ settings.x }}` is output, not a variable, and
+#            grepping the whole file for it reports a theme as wired when it
+#            is not.
+#
+#   the jq   selects by the classification rules rather than a list of types:
+#            a font may be typed font_picker/font_family/font, a weight is
+#            usually a plain `range` named for one, and a size may be typed
+#            anything at all.
+LINKED=$(awk '
+  /<style|\{%[ \t]*style[ \t]*%\}/        { inblock = 1 }
+  inblock                                 { print }
+  /<\/style>|\{%[ \t]*endstyle[ \t]*%\}/  { inblock = 0 }
+' layouts/theme.liquid \
+  | grep -oE -- '--[A-Za-z0-9_-]+[ \t]*:[ \t]*\{\{[ \t]*settings\.[A-Za-z0-9_]+' \
+  | sed -E 's/.*settings\.//' | sort -u)
+
+jq -r '
+  .[] | .name as $group | .settings[]?
+  | select(.id)
+  | select(
+      ((.type // "") | test("^(font_picker|font_family|font|font_weight)$"))
+      or ((.role // "") | test("^(font_family|font_weight)$"))
+      or (.id | test("(^|[_-])font[_-]?weight($|[_-])"; "i"))
+      or ((.label // "") | test("font\\s*weight"; "i"))
+      or ($group == "typography")
+    )
+  | .id' config/settings_schema.json | while read -r id; do
+  printf '%s\n' "$LINKED" | grep -qx "$id" || echo "NO CSS VAR: $id"
+done
+```
+
+Then run the repo's own validator:
+
+```bash
+fluid theme lint --json
+```
+
+`settings_schema.json` is not Liquid, so the linter does not read it — these checks are the only ones that cover it.

package/dist/skills/themes-settings-schema/references/css-variables.md

@@ -0,0 +1,99 @@
+# CSS variables — the contract between the schema and the page
+
+> Part of the `themes-settings-schema` skill. See [`../SKILL.md`](../SKILL.md) for the authoring workflow.
+
+## Contents
+
+- Why the layout is not optional
+- Declaring a setting's variable
+- Preset variables, and why they exist
+- Consuming variables in theme CSS
+- Custom fonts
+- Pitfalls
+
+## Why the layout is not optional
+
+`config/settings_schema.json` describes *what a merchant may change*. `layouts/theme.liquid` is what makes a change reach the page. A theme with a perfect schema and no `:root` block gives a merchant a panel full of controls that do nothing.
+
+```liquid
+{% style %}
+  :root {
+    --font_family_heading: {{ settings.font_family_heading }};
+    --font_family_body:    {{ settings.font_family_body }};
+    --font_weight_bold:    {{ settings.font_weight_bold }};
+    --font_size_h1:        {{ settings.font_size_h1 }}px;
+  }
+{% endstyle %}
+```
+
+Either `{% style %}…{% endstyle %}` or `<style>…</style>` works.
+
+## Declaring a setting's variable
+
+The builder scans the layout for exactly this shape:
+
+```
+--<any-name>: {{ settings.<setting_id> }}
+```
+
+and builds a table of *setting id → variable name*. Consequences:
+
+- **A setting with no such declaration cannot be linked.** It still edits, and the preview still re-renders, but a text preset that references it resolves to a literal value baked into content at the moment it was applied, rather than to something that follows later edits.
+- **The variable name does not have to match the id** for reading. `--heading-font: {{ settings.font_family_heading }}` is found.
+- **But match it anyway.** When the builder writes a variable for a setting it created, it writes `--<id>`, and when it removes one it removes only that exact form. A theme that names variables differently ends up with both conventions in one file.
+- **Add the unit in the layout, not the schema.** `unit` in the schema is a display hint for the panel and the preset resolver; the variable is what the browser reads, so `{{ settings.font_size_h1 }}px` is what makes it a length.
+
+## Preset variables, and why they exist
+
+Beyond one variable per setting, the builder maintains **one variable per preset property**:
+
+```css
+--font_size_h1_font_family: var(--font_family_heading);
+--font_size_h1_font_weight: var(--font_weight_bold);
+```
+
+These are written automatically the first time a merchant applies that preset to rich-text content. You do not author them, but you need to know why they exist.
+
+When a merchant applies "H1" to a paragraph, the content records the preset's variables — `font-family: var(--font_size_h1_font_family)` — **named after the preset, not after the font it currently uses**. Later, when the merchant repoints H1 from the heading font to the body font, the builder rewrites that one declaration and every paragraph ever styled as H1 follows.
+
+Recording `var(--font_family_heading)` in the content directly would freeze the decision at the moment it was applied: repointing the preset would update the schema and change nothing already on the page.
+
+A theme never needs to write these, and should not delete them — they are the only link between styled content and the preset definition.
+
+## Consuming variables in theme CSS
+
+```css
+h1 {
+  font-family: var(--font_size_h1_font_family, var(--font_family_heading));
+  font-weight: var(--font_size_h1_font_weight, var(--font_weight_bold));
+  font-size: var(--font_size_h1);
+}
+```
+
+Reading the **preset's** variable first, with the target's as a fallback, is the shape that keeps a theme's own elements in step with the preset. A theme that reads only `var(--font_family_heading)` will style its `<h1>` elements from the heading font no matter what the H1 preset has been repointed to — the panel will look correct and the page will disagree.
+
+This is the single most common reason a merchant reports "I changed it and nothing happened".
+
+## Custom fonts
+
+When a merchant picks a Google font or uploads a font file, the builder:
+
+1. appends the font to the `options` of **every** `font_picker` in the schema, so it is selectable everywhere;
+2. injects the loader into the layout `<head>` — a `<link rel="stylesheet">` for Google, or a `<link rel="preload">` plus an `@font-face` block for an upload;
+3. stores the **display name** as the setting's value.
+
+So a custom font resolves **by name**: the display name a merchant types becomes the CSS `font-family` identifier, and the `@font-face` in the layout is what makes that name mean something. Two consequences worth knowing when debugging:
+
+- Two fonts given the same display name collide — one `@font-face` wins.
+- The name flows through every variable unchanged, so preset linkage works for uploaded fonts exactly as for built-in ones.
+
+## Pitfalls
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| Panel edits change nothing anywhere | No `:root` block, or the layout reads `settings.*` without emitting variables | Add the `{% style %}` block. |
+| Panel edits change the preview but not real elements | Theme CSS hardcodes fonts and sizes | Rewire the CSS to `var(…)`. |
+| Repointing a preset moves rich-text content but not the theme's own headings | Theme CSS reads the target variable directly | Read the preset variable first, with the target as fallback. |
+| Sizes render unstyled | `unit` set in the schema but no unit in the layout | Append the unit in the Liquid: `{{ settings.font_size_h1 }}px`. |
+| A preset applies a literal instead of a variable | The target setting has no declaration in the layout | Declare `--<id>: {{ settings.<id> }}`. |
+| Uploaded `.ttf` / `.otf` fonts do not render | The generated `@font-face` declares `format('woff2')` regardless of the file | Convert to `.woff2` before uploading. |

package/dist/skills/themes-settings-schema/references/option-groups.md

@@ -0,0 +1,66 @@
+# `option_group` — feeding section dropdowns from theme settings
+
+> Part of the `themes-settings-schema` skill. See [`../SKILL.md`](../SKILL.md) for the authoring workflow.
+
+A section setting usually declares its own `options` array. When the choices are really *the theme's* — its palette, its size scale — that duplicates the same list into every section, and the lists drift.
+
+`option_group` inverts it: a **theme** setting publishes itself into a named token list, and a **section** setting names that list instead of enumerating options.
+
+## Theme side
+
+```json
+{
+  "type": "color_background",
+  "id": "color_primary",
+  "label": "Primary",
+  "default": "#49473e",
+  "option_group": {
+    "id": "background_colors",
+    "label": "Primary",
+    "value": "var(--clr-primary)"
+  }
+}
+```
+
+| Key | Meaning |
+| --- | --- |
+| `id` | The token list this setting joins. Any number of settings may share one. Must match `^[a-zA-Z0-9_-]+$`. |
+| `label` | What a merchant sees in the section dropdown. |
+| `value` | What the section setting stores when chosen — almost always a `var(…)`, so the choice follows later theme edits. |
+
+`label` and `value` must both be non-empty strings, or the entry is skipped and a warning is logged once.
+
+## Section side
+
+```json
+{
+  "type": "select",
+  "id": "background",
+  "label": "Background",
+  "options": "background_colors"
+}
+```
+
+`options` as a **string** is a token reference; as an **array** it is a literal list.
+
+## Conventions
+
+Keep one token list per visual axis, and let every setting on that axis join it:
+
+| Token list | Joined by |
+| --- | --- |
+| `background_colors` | every palette colour usable as a surface |
+| `font_sizes` | every text preset |
+| `font_weights` | every weight in the vocabulary |
+| `spacing_sizes` | every step in the spacing scale |
+| `border_radii` | every radius step |
+
+Point `value` at the CSS variable, not the raw value. `"value": "var(--clr-primary)"` keeps a section following the theme; `"value": "#49473e"` freezes the colour at the moment it was chosen, and re-themeing leaves it behind.
+
+## Pitfalls
+
+| Symptom | Cause |
+| --- | --- |
+| Section dropdown is empty | No theme setting registers that `option_group.id`, or the id is misspelled on one side |
+| One choice missing from a populated dropdown | That setting's `option_group` lacks `label` or `value` |
+| Re-theming leaves stale colours in sections | `value` holds a literal instead of a `var(…)` |

package/dist/skills/themes-settings-schema/references/typography-presets.md

@@ -0,0 +1,138 @@
+# Text presets — what the builder counts, and how it resolves
+
+> Part of the `themes-settings-schema` skill. See [`../SKILL.md`](../SKILL.md) for the authoring workflow.
+
+## Contents
+
+- What becomes a text preset
+- Roles
+- Resolving a preset's font
+- Resolving a preset's weight
+- Worked examples
+- Pitfalls
+
+## What becomes a text preset
+
+Every setting in the `typography` group is tested against three questions. A setting becomes a **preset card** only if all three say "not a font, not a weight".
+
+A setting is a **font** if either holds:
+
+- `role` is `"font_family"`
+- `type` is `font_picker`, `font_family`, or `font`
+
+A setting is a **weight** if any holds:
+
+- `role` is `"font_weight"`
+- `type` is `font_weight`
+- its **id** matches `/(^|[_-])font[_-]?weight($|[_-])/i` — `font_weight_bold`, `heading-font-weight`, `fontweight_x`
+- its **label** matches `/font\s*weight/i` — "Font weight", "Body font-weight"
+
+Everything else in `typography` with a string `id`, `type` and `label` is a **preset**. The check is exclusion, not an allow-list, so a size may be typed `range`, `number`, `font_size`, or anything else — legacy themes that typed sizes inconsistently keep working.
+
+The id and label checks exist because themes overwhelmingly author weights as `range`, not as a dedicated `font_weight` type. Without them, `font_weight_body` would become a preset card called "Weight" sitting between H1 and H2.
+
+## Roles
+
+```
+role: "heading" | "body"
+```
+
+Explicit `role` wins. Without it, an id starting `font_size_h` reads as `heading`; everything else reads as `body`.
+
+Role decides two things: the fallback font (`font_family_heading` vs `font_family_body`) and the fallback weight (`bold` vs `normal`). It does nothing when both refs are set — but set it anyway, so the preset still resolves sensibly if a ref is later removed.
+
+## Resolving a preset's font
+
+In order:
+
+1. **`font_family_ref`** — the id of a font setting, resolved across the whole schema. **Authoritative:** if it resolves to nothing, the preset has no font. It does *not* fall through to the role.
+2. **A literal `font_family`** on the preset — a value, not a reference. Used by builder-created custom presets; avoid hand-authoring it, since nothing in the panel can edit it.
+3. **The role fallback** — `heading` → `font_family_heading`, `body` → `font_family_body`. If only one of the pair exists, both roles use it. Only settings that are actually fonts qualify.
+
+## Resolving a preset's weight
+
+In order:
+
+1. **`font_weight_ref`** — id of a weight setting, resolved across the whole schema. Unlike the family, a ref that resolves to nothing **falls back to the role weight**.
+2. **A literal `font_weight`** on the preset.
+3. **The role weight** — `heading` → `bold`, `body` → `normal`.
+
+The asymmetry is deliberate: a missing weight has a sane universal default, a missing typeface does not.
+
+## Worked examples
+
+### The shape to copy
+
+Fonts in their own group, weights in theirs, presets referencing both by id.
+
+```json
+[
+  { "name": "theme_info", "theme_name": "My Theme", "theme_version": "1.0.0" },
+  {
+    "name": "fonts",
+    "settings": [
+      { "type": "font_picker", "id": "font_family_heading", "label": "Heading font", "default": "Reckless Neue" },
+      { "type": "font_picker", "id": "font_family_body", "label": "Body font", "default": "Basis Grotesque" }
+    ]
+  },
+  {
+    "name": "font_weights",
+    "settings": [
+      { "type": "range", "id": "font_weight_normal", "label": "Normal", "min": 100, "max": 900, "step": 100, "default": 400 },
+      { "type": "range", "id": "font_weight_bold", "label": "Bold", "min": 100, "max": 900, "step": 100, "default": 700 }
+    ]
+  },
+  {
+    "name": "typography",
+    "settings": [
+      {
+        "type": "range", "id": "font_size_h1", "label": "H1",
+        "min": 32, "max": 120, "step": 1, "unit": "px", "default": 64,
+        "role": "heading",
+        "font_family_ref": "font_family_heading",
+        "font_weight_ref": "font_weight_bold"
+      },
+      {
+        "type": "range", "id": "font_size_base", "label": "Base",
+        "min": 14, "max": 20, "step": 0.5, "unit": "px", "default": 16,
+        "role": "body",
+        "font_family_ref": "font_family_body",
+        "font_weight_ref": "font_weight_normal"
+      }
+    ]
+  }
+]
+```
+
+Renders as: a **fonts** accordion with two pickers, a **font weights** accordion with two sliders, and a **typography** accordion with one card per preset — each card showing its size, a font dropdown reading "Heading" / "Body", and a weight dropdown reading "Normal" / "Bold".
+
+### The minimum that still works
+
+No refs at all. Presets resolve by role. Valid, and what most older themes look like.
+
+```json
+{
+  "name": "typography",
+  "settings": [
+    { "type": "font_picker", "id": "font_family_heading", "label": "Heading font", "default": "Inter" },
+    { "type": "font_picker", "id": "font_family_body", "label": "Body font", "default": "Inter" },
+    { "type": "range", "id": "font_size_h1", "label": "H1", "unit": "px", "default": 48, "role": "heading" },
+    { "type": "range", "id": "font_size_base", "label": "Base", "unit": "px", "default": 16, "role": "body" }
+  ]
+}
+```
+
+H1 resolves to the heading font at `bold`; Base to the body font at `normal`. Fonts and presets may share one group — the panel gathers every font into whichever group declares the first one.
+
+## Pitfalls
+
+| Symptom | Cause | Fix |
+| --- | --- | --- |
+| A size setting never appears as a card | Its id or label matches the weight patterns — e.g. a size labelled "Heading font weight scale" | Rename it. Nothing in the schema can override the classification. |
+| Typography renders as a flat list | The group is not named exactly `typography` | Rename the group. `type`, `text`, `Typography` all miss. |
+| A card shows a size slider and nothing else | Its `font_family_ref` / `font_weight_ref` point at ids that do not exist | Fix the ids, or drop the refs and let `role` resolve them. |
+| Two font settings are indistinguishable in a preset's dropdown | Both labelled "Font family", ids not role-named | Rename ids to `font_family_<role>`. The dropdown reads the id, not the label. |
+| Headers vanish | The Themes panel discards settings without `id`/`label` | Use separate groups instead. |
+| A font appears in a group the theme did not declare it in | The panel gathers every font into the first group that declares one, so a merchant finds them all in one place | Expected. Declare fonts in one group to keep schema and panel aligned. |
+| Changing a preset's font moves nothing on the page | The theme's CSS reads `--font-heading` directly rather than the preset's own variable | See [`css-variables.md`](css-variables.md). |
+| An id like `font_size_body` behaves oddly | Its derived names collide with the shared `font_family_body` | Avoid `font_size_<role>` ids; use `font_size_base`, `font_size_lg`. |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fluid-app/fluid-cli-theme-dev",
-  "version": "0.1.41",
+  "version": "0.1.43",
   "description": "Fluid CLI plugin for theme developer workflows — dev server, push, pull, init",
   "files": [
     "dist",
@@ -27,7 +27,7 @@
     "open": "^10.0.0",
     "ora": "^8.0.0",
     "prompts": "^2.4.2",
-    "@fluid-app/fluid-cli": "0.1.18"
+    "@fluid-app/fluid-cli": "0.1.17"
   },
   "devDependencies": {
     "@swc/core": "^1.15.18",