@fluid-app/fluid-cli-theme-dev 0.1.63 → 0.1.65

package/dist/skills/themes-review/references/global-settings.md

@@ -18,79 +18,60 @@ The most-overlooked layer of a theme is **`config/settings_schema.json` + `layou
 
 ### The pattern
 
-1. **`config/settings_schema.json`** declares theme-wide settings, grouped by `name` (typography, spacing, color_schema, shadows, border_radius, cards, etc.).
-2. **`layouts/theme.liquid`** reads `{{ settings.* }}` and emits **CSS custom properties on `:root`** inside a `<style>` block.
-3. **Sections and components** consume those custom properties via `var(--font-body)`, `var(--color-primary)`, etc. — never re-reading the underlying `settings.*` value.
+1. **`config/settings_schema.json`** declares theme-wide settings, grouped by `name`. The editor gives four group names special meaning — `typography` (text-preset cards), `color_schema`, `padding`, and `corner_radius` (the presets offered by section and block controls). Other groups (`shadows`, `cards`, `appearance`, …) render as plain lists.
+2. **`layouts/theme.liquid`** reads `{{ settings.* }}` and emits **CSS custom properties on `:root`** inside a `{% style %}` or `<style>` block, one `--<setting_id>` per setting. The editor only offers a setting as a preset when such a declaration exists, and it writes `--<setting_id>` itself when it manages a variable.
+3. **Sections and components** consume those custom properties via `var(--font_family_body)`, `var(--color_primary)`, etc. — never re-reading the underlying `settings.*` value.
+
+The `themes-settings-schema` skill (installed as a sibling: [`../../themes-settings-schema/SKILL.md`](../../themes-settings-schema/SKILL.md)) has the full typography-preset contract.
 
 ### What `config/settings_schema.json` looks like
 
 ```json
 [
-  {
-    "name": "theme_info",
-    "theme_name": "My Theme",
-    "theme_version": "1.0.0",
-    "theme_author": "..."
-  },
   {
     "name": "typography",
     "settings": [
-      { "type": "header", "content": "Body" },
       {
         "type": "font_picker",
         "id": "font_family_body",
-        "label": "Font family",
+        "label": "Body font",
+        "default": "Inter"
+      },
+      {
+        "type": "font_picker",
+        "id": "font_family_heading",
+        "label": "Heading font",
         "default": "Inter"
       },
       {
         "type": "range",
         "id": "font_weight_body",
-        "label": "Weight",
+        "label": "Body weight",
         "min": 100,
         "max": 900,
         "step": 100,
         "default": 400
       },
-      { "type": "header", "content": "Headings" },
-      {
-        "type": "font_picker",
-        "id": "font_family_heading",
-        "label": "Font family",
-        "default": "Inter"
-      },
       {
         "type": "range",
         "id": "font_size_h1",
-        "label": "H1 size",
+        "label": "H1",
         "min": 24,
         "max": 96,
         "step": 1,
         "default": 48,
-        "unit": "px"
+        "unit": "px",
+        "role": "heading",
+        "font_family_ref": "font_family_heading"
       }
     ]
   },
   {
     "name": "color_schema",
     "settings": [
-      {
-        "type": "color",
-        "id": "color_primary",
-        "label": "Primary",
-        "default": "#0a0a0a"
-      },
-      {
-        "type": "color",
-        "id": "color_secondary",
-        "label": "Secondary",
-        "default": "#ffffff"
-      },
-      {
-        "type": "color",
-        "id": "color_text",
-        "label": "Body text",
-        "default": "#111111"
-      }
+      { "type": "color", "id": "color_primary",   "label": "Primary",   "default": "#0a0a0a" },
+      { "type": "color", "id": "color_secondary", "label": "Secondary", "default": "#ffffff" },
+      { "type": "color", "id": "color_text",      "label": "Body text", "default": "#111111" }
     ]
   },
   {
@@ -99,7 +80,7 @@ The most-overlooked layer of a theme is **`config/settings_schema.json` + `layou
       {
         "type": "checkbox",
         "id": "enable_dark_mode",
-        "label": "Enable dark mode toggle",
+        "label": "Enable dark mode",
         "default": false
       }
     ]
@@ -107,53 +88,59 @@ The most-overlooked layer of a theme is **`config/settings_schema.json` + `layou
 ]
 ```
 
-Note: the **outer array is grouped**, not flat. Each object with a `name:` becomes a settings group in the editor UI. The `theme_info` group is metadata and contains no `settings:` array.
+Note: the **outer array is grouped**, not flat. Each object with a `name:` becomes a settings group in the theme panel. The theme panel drops any setting without an `id`, `type`, and `label` — so `{"type": "header"}` entries render nothing there; use separate groups instead. Fluid does not read a Shopify-style `theme_info` group.
 
 ### What `layouts/theme.liquid` does with them
 
 ```liquid
 <head>
   ...
-  {{ settings.font_family_body    | font_face: font_display: 'swap' }}
-  {{ settings.font_family_heading | font_face: font_display: 'swap' }}
+  {%- comment -%} Load the default fonts yourself; fonts a merchant adds in the Theme panel are linked into this <head> by the editor {%- endcomment -%}
+  <link rel="preconnect" href="https://fonts.googleapis.com">
+  <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+  <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;700&display=swap" rel="stylesheet">
 
-  <style>
+  {% style %}
     :root {
       /* Typography */
-      --font-body:        {{ settings.font_family_body    | font_family | default: "Inter, system-ui, sans-serif" }};
-      --font-heading:     {{ settings.font_family_heading | font_family | default: "Inter, system-ui, sans-serif" }};
-      --font-weight-body: {{ settings.font_weight_body | default: 400 }};
-      --font-size-h1:     {{ settings.font_size_h1     | default: 48 | append: 'px' }};
+      --font_family_body:    {{ settings.font_family_body    | default: "Inter" }}, system-ui, sans-serif;
+      --font_family_heading: {{ settings.font_family_heading | default: "Inter" }}, system-ui, sans-serif;
+      --font_weight_body:    {{ settings.font_weight_body | default: 400 }};
+      --font_size_h1:        {{ settings.font_size_h1     | default: 48 }}px;
 
       /* Color */
-      --color-primary:    {{ settings.color_primary   | default: '#0a0a0a' }};
-      --color-secondary:  {{ settings.color_secondary | default: '#ffffff' }};
-      --color-text:       {{ settings.color_text      | default: '#111111' }};
+      --color_primary:   {{ settings.color_primary }};
+      --color_secondary: {{ settings.color_secondary }};
+      --color_text:      {{ settings.color_text }};
     }
 
     {%- if settings.enable_dark_mode -%}
       @media (prefers-color-scheme: dark) {
         :root {
-          --color-primary:   {{ settings.color_primary_dark   | default: '#ffffff' }};
-          --color-secondary: {{ settings.color_secondary_dark | default: '#0a0a0a' }};
-          --color-text:      {{ settings.color_text_dark      | default: '#fafafa' }};
+          --color_primary:   #ffffff;
+          --color_secondary: #0a0a0a;
+          --color_text:      #fafafa;
         }
       }
     {%- endif -%}
-  </style>
+  {% endstyle %}
 </head>
 ```
 
+A `font_picker` value is a plain family-name string. Do not use Shopify's font filters: `font_family` does not exist in Fluid (unknown filters are silently ignored), and Fluid's `font_face` expects a font object with `family` and `src`, so `{{ settings.font_family_body | font_face }}` emits an empty `@font-face`. A global `color` setting is a color value: it renders as the saved color and also exposes `.rgb`, `.rgba`, `.hue`, `.saturation`, `.lightness`.
+
 And sections then look like:
 
 ```css
 .featured-products h2 {
-  font-family: var(--font-heading);
-  font-size: var(--font-size-h1);
-  color: var(--color-text);
+  font-family: var(--font_size_h1_font_family, var(--font_family_heading));
+  font-size: var(--font_size_h1);
+  color: var(--color_text);
 }
 ```
 
+Read a text preset's own variable (`--<preset_id>_font_family`, written by the editor once a merchant applies the preset) before the font variable, so repointing the preset in the editor moves the theme's own headings too.
+
 ### What belongs at the global level
 
 Anything that should stay consistent across the whole theme:
@@ -162,13 +149,12 @@ Anything that should stay consistent across the whole theme:
 | --------------- | ------------------------------------------------------------------------------------------------------------ |
 | `typography`    | Body + heading font families, font weights, font size scale (`xs`–`9xl`), heading sizes (h1–h6), line height |
 | `color_schema`  | Brand palette (primary, secondary, accent, text, surface, border), plus dark-mode variants                   |
-| `spacing`       | Spacing scale, section padding scale                                                                         |
+| `padding`       | Spacing scale used by section/block `padding` controls (preset group)                                        |
 | `layout`        | Max container width, gutter, grid breakpoints                                                                |
-| `border_radius` | Radius scale (sm, md, lg, full)                                                                              |
+| `corner_radius` | Radius scale used by `corner_radius` controls (preset group)                                                 |
 | `shadows`       | Shadow scale (sm, md, lg)                                                                                    |
 | `cards`         | Card-wide defaults (radius, shadow, padding) that per-card-type groups inherit                               |
 | `appearance`    | Dark mode toggle, motion-reduce, animation preferences                                                       |
-| `theme_info`    | Theme name, version, author, docs URL — **metadata only, no `settings:`**                                    |
 
 ### What does NOT belong at the global level
 
@@ -183,13 +169,13 @@ The test: _would changing this break the visual coherence of the rest of the the
 
 | You see                                                                                                                        | Severity  | Fix                                                                                                                                                                             |
 | ------------------------------------------------------------------------------------------------------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| Section adds its own `font_family` / `font_size` / `color_*` setting when the global already exists                            | `should`  | Use `var(--font-body)`, `var(--color-primary)`, etc. Per-section overrides should be the _exception_, configured via section setting `color_override` that defaults to `unset`. |
+| Section adds its own `font_family` / `font_size` / `color_*` setting when the global already exists                            | `should`  | Use `var(--font_family_body)`, `var(--color_primary)`, etc. Per-section overrides should be the _exception_, configured via section setting `color_override` that defaults to `unset`. |
 | Theme has 0 global typography settings but every section hardcodes fonts in inline styles                                      | `blocker` | Add a `typography` group to `config/settings_schema.json` and a `:root` `<style>` block in `layouts/theme.liquid`.                                                              |
 | Theme has 0 global color settings but uses hardcoded hex everywhere                                                            | `blocker` | Add a `color_schema` group.                                                                                                                                                     |
-| `layouts/theme.liquid` reads `settings.*` but emits no `<style>` / CSS variables                                               | `should`  | Wire the settings into `--var` declarations on `:root`. Without this layer, sections have no way to consume globals.                                                            |
-| `config/settings_schema.json` is a **flat array of settings** (no `name:` groups)                                              | `should`  | The engine accepts it, but the editor UI flattens to one giant panel. Group by `name:` (typography, color, spacing, …) for usability.                                           |
-| `theme_info` group missing                                                                                                     | `nit`     | Adds version + author metadata visible to admins.                                                                                                                               |
-| Two `font_family_body` and `font_family_heading` settings exist but every section uses a hardcoded `font-family: 'Inter'`      | `blocker` | Rewire sections to `var(--font-heading)` / `var(--font-body)`. Globals that nothing consumes are dead weight.                                                                   |
+| `layouts/theme.liquid` reads `settings.*` but emits no `{% style %}` / `<style>` CSS variables                                              | `should`  | Wire the settings into `--var` declarations on `:root`. Without this layer, sections have no way to consume globals.                                                            |
+| `config/settings_schema.json` is a **flat array of settings** (no `name:` groups)                                              | `blocker` | The theme panel drops every entry without a group `name`, so a flat array renders an empty Theme panel. Group the settings by `name:` (typography, color_schema, …). |
+| Theme panel groups named `spacing`, `border_radius`, `Typography`, or `colors` | `should` | The editor builds presets only from `typography`, `color_schema`, `padding`, and `corner_radius` (exact, case-sensitive). Rename so section controls offer the presets. |
+| `font_family_body` and `font_family_heading` settings exist but every section uses a hardcoded `font-family: 'Inter'`         | `blocker` | Rewire sections to `var(--font_family_heading)` / `var(--font_family_body)`. Globals that nothing consumes are dead weight. |
 | Dark-mode toggle exists in schema but no `@media (prefers-color-scheme: dark)` / `[data-theme="dark"]` block in `theme.liquid` | `blocker` | Setting is a lie — wire it.                                                                                                                                                     |
 
 ### Dark-mode patterns — two acceptable shapes
@@ -209,7 +195,10 @@ jq -r '.[].name' config/settings_schema.json
 grep -E 'settings\.' layouts/theme.liquid | head
 
 # 3. Does the layout emit CSS variables?
-grep -E '^\s*--[a-z-]+:' layouts/theme.liquid | head
+grep -E '^\s*--[a-z_-]+:' layouts/theme.liquid | head
+
+# 3b. Shopify font filters that don't work in Fluid
+grep -nE '\| *(font_face|font_family)\b' layouts/theme.liquid
 
 # 4. Do sections actually USE the variables (vs. hardcoded)?
 grep -rE 'font-family:\s*[A-Za-z]' --include='*.liquid' --include='*.css' . 2>/dev/null  # hardcoded fonts

package/dist/skills/themes-review/references/liquid-correctness.md

@@ -23,7 +23,7 @@ The variables a template can read fall into three buckets:
 
 | Bucket                       | Available in…                                           | Examples                                                                                                                   |
 | ---------------------------- | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
-| **Always available globals** | every template                                          | `request`, `cart`, `customer`, `shop`, `settings` (global), `linklists`                                                    |
+| **Always available globals** | every storefront template                                | `company`, `request`, `params`, `localization`, `country`, `affiliate`, `username`, `routes`, `settings` (global), and the on-demand collections `products`, `collections`, `categories`, `posts`, `enrollment_packs`. No `cart` (only in `cart_page`), and no Shopify `shop`, `customer`, or `linklists` |
 | **Resource context**         | the matching page template, plus any section it renders | `product` (only on `product/{variant}/index.liquid` and sections rendered from it); `collection`, `category`, `post`, etc. |
 | **Section / block scope**    | inside that section only                                | `section`, `section.settings`, `section.blocks`, `block`, `block.settings`                                                 |
 | **Component args**           | inside a component only when explicitly passed          | only the keys passed to `{% render 'name', key: value %}`                                                                  |
@@ -34,7 +34,7 @@ Things that go wrong:
 | -------------------------------------------------------------------------------------------------------------------------------------------- | --------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------- |
 | `{{ product.title }}` inside a section that's rendered on the homepage (`home_page/default/index.liquid`) without an explicit `product:` arg | `blocker` | `product` is only in scope on product page templates. On `home_page` it's `nil`, silently rendering empty.                                                            |
 | `{{ collection.products }}` inside `sections/main_navbar/index.liquid`                                                                       | `blocker` | `collection` is not in scope in a navbar section. Pass the resource explicitly via a block setting (`collection` type) and read `block.settings.collection.products`. |
-| `{{ cart.item_count }}` in a component without `cart` passed as a `render` arg                                                               | `should`  | `cart` is global, so this often works, but if the component is intended to be self-contained, accept `cart:` explicitly.                                              |
+| `{{ cart.item_count }}` (or any `cart.*`) outside a `cart_page` template                                                                          | `blocker` | `cart` exists only in `cart_page` templates; elsewhere it renders empty. Use the SDK's `<span id="fluid-cart-count">` for a live count. |
 | `{{ section.settings.thing }}` where the schema does not declare `thing`                                                                     | `blocker` | Typo or stale reference. Validator does not catch this — it only checks the schema, not the template. Grep the schema for the `id` and fix.                           |
 | `{{ block.settings.thing }}` where the block's `settings:` array does not declare `thing`                                                    | `blocker` | Same as above for blocks.                                                                                                                                             |
 | `{{ block.settings.x }}` inside a section that has `blocks` declared but NOT inside a `{% for block in section.blocks %}` loop               | `blocker` | `block` is only in scope inside the iteration; outside it's `nil`.                                                                                                    |
@@ -81,19 +81,21 @@ Liquid is forgiving. `nil.foo` does not raise — it renders empty. That's worse
 <h2>{{ section.settings.heading | default: 'Featured products' }}</h2>
 ```
 
-**`blocker`** when a method-chain on a resource picker is unguarded and the page can render with a blank picker:
+**`blocker`** when markup around a resource picker is unguarded and the page can render with a blank picker. An unset resolved setting is an empty object — the chain renders empty rather than raising, leaving an empty `<span>` or a broken link behind. Guard with `!= blank` (a bare `{% if p %}` is always true for an empty object):
 
 ```liquid
-{%- comment -%} Bad: `.first_variant.price` chain blows up if product is blank {%- endcomment -%}
-<span>{{ section.settings.product.first_variant.price | money }}</span>
+{%- comment -%} Bad: renders an empty <span> when no product is picked {%- endcomment -%}
+<span>{{ section.settings.product.selected_or_first_available_variant.price }}</span>
 
 {%- comment -%} Good {%- endcomment -%}
 {%- assign p = section.settings.product -%}
-{%- if p != blank and p.first_variant != blank -%}
-  <span>{{ p.first_variant.price | money }}</span>
+{%- if p != blank -%}
+  <span>{{ p.selected_or_first_available_variant.price }}</span>
 {%- endif -%}
 ```
 
+Prices on products and variants are already formatted for the visitor's currency. Fluid has no `money` filter — an unknown filter is silently ignored.
+
 ### 2. Whitespace control
 
 Liquid keeps every whitespace character outside tags. In tight loops, this inflates HTML by KBs. **`should`** when a `for`/`if` block in markup context lacks `-`:
@@ -116,14 +118,7 @@ Rule of thumb: control tags (`{%- ... -%}`) get dashes; output tags (`{{ ... }}`
 
 ### 3. Unclosed tags / mismatched conditionals
 
-**`blocker`.** Liquid's parser is permissive — an unclosed `{% if %}` will consume the rest of the template silently. Quick count check:
-
-```bash
-grep -cE '{%-?\s*(if|for|case|capture|comment|unless)\b' file.liquid
-grep -cE '{%-?\s*end(if|for|case|capture|comment|unless)\b' file.liquid
-```
-
-The two counts must match.
+**`blocker`.** An unclosed `{% if %}` (or `for`, `case`, `capture`, `unless`, …) is a Liquid syntax error. The upload still succeeds, but the storefront can no longer render that file correctly. `fluid theme lint --json` reports each unbalanced block tag with its line — run it rather than counting tags by hand.
 
 ### 4. Filter ordering
 

package/dist/skills/themes-review/references/media-tag.md

@@ -2,9 +2,9 @@
 
 > Part of the `themes-review` skill. See [`../SKILL.md`](../SKILL.md) for the review workflow, severity ladder, and validator rules.
 
-Render every setting- or resource-backed image and video with the `media_tag` filter. It turns an image or video into a complete, responsive HTML element — `srcset`, WebP/AVIF negotiation, `loading`, `decoding="async"`, and `alt` — so a hand-rolled `<img>` / `<video>` in a section is almost always the wrong call.
+Render every setting- or resource-backed image and video with the `media_tag` filter — except a Fluid media item from a `media_picker`, which renders as `<fluid-media-widget>` (see the rule below). It turns an image or video into a complete, responsive HTML element — `srcset`, WebP/AVIF negotiation, `loading`, `decoding="async"`, and `alt` — so a hand-rolled `<img>` / `<video>` in a section is almost always the wrong call.
 
-Docs: <https://docs.fluid.app/docs/themes/media-tag>
+Docs: <https://docs.fluid.app/themes/media-tag>
 
 ## Contents
 
@@ -15,14 +15,14 @@ Docs: <https://docs.fluid.app/docs/themes/media-tag>
 
 ### 1. The rule
 
-**`should`.** A raw `<img src="{{ ... }}">` or `<video>` that renders an `image` / `image_picker` / `video_picker` / `media_picker` setting, or a resource image (`product.image`, `collection.image`, …), should be `| media_tag`. Hand-rolled markup ships one fixed-size original — no responsive `srcset`, no format negotiation — which bloats the download and hurts LCP, and forces you to remember `loading` / `decoding` / `alt` every time.
+**`should`.** A raw `<img src="{{ ... }}">` or `<video>` that renders an `image` / `image_picker` / `video_picker` setting, a plain-file `media_picker` value, or a resource image (`product.image`, `collection.image`, …), should be `| media_tag`. Hand-rolled markup ships one fixed-size original — no responsive `srcset`, no format negotiation — which bloats the download and hurts LCP, and forces you to remember `loading` / `decoding` / `alt` every time.
 
 ```liquid
 {%- comment -%} Bad: fixed original, manual (easy-to-forget) attributes {%- endcomment -%}
 <img src="{{ section.settings.banner_image }}" alt="{{ section.settings.heading | escape }}" loading="lazy" decoding="async" />
 
 {%- comment -%} Good: responsive, format-negotiated, accessible — one filter {%- endcomment -%}
-{{ section.settings.banner_image | media_tag: sizes: '(max-width: 768px) 100vw, 1200px', alt: section.settings.heading }}
+{{ section.settings.banner_image | media_tag: sizes: '(max-width: 768px) 100vw, 1200px', alt: section.settings.banner_image_alt }}
 ```
 
 `media_tag` escapes its own output, so do **not** wrap the setting in `| escape` yourself. It renders nothing on blank input, so the `{%- if image != blank -%}` guard is optional — keep it only when surrounding markup must be suppressed too.
@@ -41,14 +41,14 @@ Pass options as filter arguments. Anything not in this table becomes a plain HTM
 | `format`  | `auto`              | WebP/AVIF negotiation.                                                     |
 | `crop`    | —                   | Focus point.                                                               |
 | `loading` | `lazy`              | Use `eager` for the hero / above-the-fold image — `lazy` there delays LCP. |
-| `alt`     | image's alt text    | Set it for `*_picker` settings; `alt: ''` for decorative.                  |
+| `alt`     | image's alt text    | For `*_picker` settings pass the `<id>_alt` companion; `alt: ''` for decorative. |
 
 ```liquid
 {%- comment -%} Fixed-width logo, retina srcset {%- endcomment -%}
 {{ section.settings.logo | media_tag: width: 240, alt: 'Logo' }}
 
 {%- comment -%} Hero — eager so it doesn't delay LCP {%- endcomment -%}
-{{ section.settings.hero | media_tag: sizes: '100vw', loading: 'eager', alt: section.settings.heading }}
+{{ section.settings.hero | media_tag: sizes: '100vw', loading: 'eager', alt: section.settings.hero_alt }}
 ```
 
 ### 3. Video
@@ -61,7 +61,8 @@ A video URL (`.mp4` / `.mov` / `.webm` / `.m4v`) or video object renders a `<vid
 
 ### 4. What it does *not* replace
 
+- **Fluid media items.** A `media_picker` value with a positive `fluid_media_id` is a Fluid media item. Render it as `<fluid-media-widget media-id="{{ media.fluid_media_id }}" embed-type="{{ media.embed_type | default: 'default' }}">`, passing the saved `embed_settings` through as widget attributes (`autoOpen` → `auto-open`, `width`/`height` → `px` lengths when not responsive, `hideCta` → a disabled `cta-options-manual-override`; see [Setting types](setting-types.md#visual--media)) — `media_tag` would emit a bare `<img>`/`<video>` from its `url` and drop the embed (popover, inline shopping, CTAs). Only a plain file (`fluid_media_id` `0` or absent) goes through `media_tag`. Compare with `> 0`: Liquid treats `0` as true. Flag a `media_picker` rendered only through `media_tag` as a `blocker`.
 - **Static theme assets** (`'logo.svg' | asset_url`) are not ImageKit media — `media_tag` passes non-ImageKit URLs through as a plain tag, so `asset_url` + a plain `<img>` stays correct for files shipped in `assets/`.
-- **`alt` judgement** is still yours — `media_tag` defaults `alt` from the image, but `*_picker` settings carry none, so pass one (or `alt: ''` for decorative). The alt rule in [security & accessibility](security-accessibility.md) still applies.
+- **`alt` judgement** is still yours — `media_tag` defaults `alt` from the image, but `*_picker` values carry none. Pass the editor-managed `<id>_alt` setting (for `banner_image`, `section.settings.banner_image_alt`), or `alt: ''` for decorative. The alt rule in [security & accessibility](security-accessibility.md) still applies.
 
 ---

package/dist/skills/themes-review/references/navigation.md

@@ -14,7 +14,13 @@ Prefer a `link_list` setting — **the engine's menu selector** — for navigati
 
 The findings below are maintainability recommendations. Explain the benefit of managed menus, respect the user's chosen implementation, and verify destinations, dropdowns, accessibility, and desktop/mobile rendering. Hardcoded navigation is supported; it is not a validation blocker.
 
-`link_list` is one of the canonical setting types (a single-resource picker). It points at a _menu_ the company configures in admin; the theme reads it as an iterable of menu items.
+`link_list` is one of the canonical setting types (a single-resource picker). It saves a menu's slug, and Fluid resolves it before the template reads it:
+
+```text
+{ title, handle, menu_items: [ { title, url, sub_menu_items: [ { title, url, sub_menu_items }, … ] }, … ] }
+```
+
+This is **not** Shopify's shape: there is no `menu.links`, `link.links`, `link.active`, or `linklists` global. Those render empty.
 
 ### Bad — hardcoded nav
 
@@ -57,33 +63,32 @@ Or this — better, but still wrong: company-level text/URL settings paired into
 
 ```liquid
 {%- assign menu = section.settings.menu -%}
-<nav class="main-nav" aria-label="Main navigation">
-  {%- for link in menu.links -%}
-    <a href="{{ link.url }}"
-       class="main-nav__link {% if link.active %}is-active{% endif %}">
-      {{ link.title | escape }}
-    </a>
-  {%- endfor -%}
-</nav>
+{%- if menu != blank -%}
+  <nav class="main-nav" aria-label="{{ menu.title | escape }}">
+    {%- for item in menu.menu_items -%}
+      <a href="{{ item.url }}" class="main-nav__link">{{ item.title | escape }}</a>
+    {%- endfor -%}
+  </nav>
+{%- endif -%}
 ```
 
-The company now picks an existing menu in admin (the editor surfaces all menus the store has configured), and adds/reorders/renames items without ever touching code. Multi-level dropdowns work via `link.links` (children).
+The company now picks an existing menu in admin (the editor surfaces all menus the store has configured), and adds/reorders/renames items without ever touching code. Multi-level dropdowns work via `item.sub_menu_items`. There is no `active` flag on menu items. An unset `link_list` is an empty object, so guard with `!= blank`.
 
 ### Findings to surface
 
 | You see                                                                                                                       | Severity | Fix                                                                                                                                                |
 | ----------------------------------------------------------------------------------------------------------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
-| 2+ hardcoded `<a href="/...">` tags that visually form a navigation (header, footer columns, mobile drawer, social row)       | `should` | Replace with a `link_list` setting and a `{% for link in menu.links %}` loop.                                                                      |
+| 2+ hardcoded `<a href="/...">` tags that visually form a navigation (header, footer columns, mobile drawer, social row)       | `should` | Replace with a `link_list` setting and a `{% for item in menu.menu_items %}` loop.                                                                 |
+| `menu.links`, `link.links`, `link.active`, or `linklists` (Shopify names)                                                     | `blocker` | Renders nothing in Fluid. Use `menu.menu_items` and `item.sub_menu_items`; menu items have no `active` flag.                                       |
 | Multiple parallel `text` + `url` settings used to fake a menu (`nav_label_1` / `nav_url_1`, `nav_label_2` / `nav_url_2`, ...) | `should` | Collapse to one `link_list`. Each menu item gains drag-reorder, depth, and active-state tracking.                                                  |
 | Section that lists footer columns by hardcoding the same column twice                                                         | `should` | One block per column with a `link_list` inside the block. Users add/remove/rename columns.                                                         |
-| Iterating `linklists` (the global) without exposing a `link_list` picker                                                      | `nit`    | Acceptable for "site-wide menu" cases, but giving the user a `link_list` setting is more flexible — the section can be reused for different menus. |
 | Breadcrumbs, social-link rows, related-links rails — anything that's a list of `{ label, url }` pairs                         | `should` | All belong in a `link_list`. Don't reinvent.                                                                                                       |
 
 ### When to keep nav items singular
 
 The `link_list` heuristic does not apply to:
 
-- **Single CTAs** in marketing sections — these are real "hero button" / "secondary button" roles. A standalone `text` + `url` (or one `link_list` with `limit: 1` if you want consistency) is fine.
+- **Single CTAs** in marketing sections — these are real "hero button" / "secondary button" roles. A standalone `plaintext` + `url` pair is fine.
 - **Brand logo links** — the logo's `href` is almost always "go home"; a fixed `/` is acceptable, or expose a single `url` setting.
 - **Legal/footer links that are _required by policy_** (Terms, Privacy) and not the company's call to omit — but even these are usually better as a `link_list` so they can be reordered or extended.
 

package/dist/skills/themes-review/references/security-accessibility.md

@@ -15,12 +15,17 @@
 
 ### 1. Unescaped user content
 
-**`blocker`.** Any string that originated from a user (product title, comment, custom heading) outside of a `richtext`/`html`/`html_textarea` field must be escaped. Default to `| escape` for any string field. The only exception is the HTML-shaped types — those are HTML by design.
+**`blocker`.** Escape plain strings: resource fields such as `product.title`, comments, `plaintext` settings, and global `settings.<id>` values of type `text` (the Theme panel renders `text` as a plain input).
 
 ```liquid
 <h2>{{ product.title | escape }}</h2>
+<input placeholder="{{ section.settings.email_placeholder | escape }}">  {%- comment -%} plaintext setting {%- endcomment -%}
 ```
 
+Do **not** escape the HTML-shaped **section and block** setting types: `text`, `textarea`, `richtext` / `rich_text`, and `html` / `html_textarea`. In section and block schemas, `text` and `textarea` are rich-text editors — they save HTML such as `Free delivery on <strong>every</strong> order` — so `| escape` shows merchants `&lt;strong&gt;`. Render them raw, in element content only. A section or block value that must go into an attribute, a CSS value, a URL, or a script needs a `plaintext` setting instead; flag `text`/`textarea` in those positions as a `blocker`.
+
+Global settings from `config/settings_schema.json` are different: the Theme panel renders `text` as a plain input and `textarea` as rich text, and offers no `plaintext`. Escape a global `text` value (`{{ settings.announcement | escape }}`); render a global `textarea` raw.
+
 ### 2. Raw output of URLs in `href` / `src`
 
 **`should`.** Escape:
@@ -44,14 +49,14 @@
 Render the image with `| media_tag` (see [Media rendering](media-tag.md)) and pass `alt`:
 
 ```liquid
-{%- comment -%} Bad: image_picker carries no stored alt, so this ships alt-less {%- endcomment -%}
+{%- comment -%} Bad: the picker value is a bare URL, so this ships alt-less {%- endcomment -%}
 {{ section.settings.image | media_tag }}
 
-{%- comment -%} Good {%- endcomment -%}
-{{ section.settings.image | media_tag: alt: section.settings.heading }}
+{%- comment -%} Good: the editor stores alt text in the `<id>_alt` companion setting {%- endcomment -%}
+{{ section.settings.image | media_tag: alt: section.settings.image_alt }}
 ```
 
-`media_tag` defaults `alt` from a resource image (`product.featured_image`), but `*_picker` settings carry none — pass one explicitly. Decorative images: `alt: ''`.
+Every `image_picker`, `video_picker`, and `media_picker` gets an editor-managed `<id>_alt` setting that merchants fill in next to the picker; don't declare it, read it. Don't reuse a heading as alt text — a `text` heading is HTML. `media_tag` takes `alt` from an image value that carries one (an entry in `product.images`, for example); picker values carry none. Decorative images: `alt: ''`.
 
 ### 2. Heading hierarchy
 
@@ -66,7 +71,7 @@ A clickable `<div>` is `blocker`. Use `<button>` for actions, `<a href>` for nav
 `| media_tag` applies `decoding="async"` and `loading="lazy"` for you — don't hand-roll them. For hero/above-the-fold images pass `loading: 'eager'`, since lazy loading there delays LCP:
 
 ```liquid
-{{ section.settings.hero | media_tag: loading: 'eager', alt: section.settings.heading }}
+{{ section.settings.hero | media_tag: loading: 'eager', alt: section.settings.hero_alt }}
 ```
 
 ---