@fluid-app/fluid-cli-theme-dev 0.1.20 → 0.1.22

package/skills/themes-review/references/blocks-vs-sections.md

@@ -0,0 +1,131 @@
+# Blocks vs. sections
+
+> Part of the `themes-review` skill. See [`../SKILL.md`](../SKILL.md) for the review workflow, severity ladder, and validator rules.
+
+## Contents
+
+- The rule — blocks first
+- Standalone blocks over inline blocks
+- Threshold
+- Bad — settings-panel wall of fields
+- Good — block per feature
+- Benefits the reviewer should cite when suggesting the fix
+- When sections-with-many-fields _is_ the right answer
+
+
+Fluid themes are **blocks-first**: a section is a layout shell, and its *content* lives in blocks. A section that bundles every piece of content into one giant `settings: [...]` array becomes a wall of fields the merchant can't navigate, can't reorder, and can't extend without a developer.
+
+### The rule — blocks first
+
+- **Block settings** hold **content** — anything a merchant might add, remove, reorder, or repeat: headings, paragraphs, images, buttons/CTAs, cards, FAQs, features, logos. Model content as blocks **even when there is only one today.** "There's just one heading" is not a reason to make it a section setting — a merchant who later wants a second heading, wants to drop the image, or wants the CTA above the text should do it in the editor, not in a PR.
+- **Section settings** hold only **true whole-section configuration**: width, background, padding, column count, vertical alignment — values that are singular for the whole section by nature and that a merchant would never duplicate or reorder.
+
+That split is the whole point: the **section** carries only a handful of settings (its whole-section config), while every **element-specific** setting lives on the block it belongs to. The section panel stays short and scannable, and each setting sits next to the element it controls.
+
+**Litmus test:** _"Could a merchant reasonably want two of these, none of these, or these in a different order?"_ If yes → block. If it is genuinely one-per-section plumbing → section setting.
+
+`setting_a_1` / `setting_a_2` / `setting_a_3` (or `show_card_1` / `show_card_2`) is the obvious failure mode — but the blocks-first bar is higher: reach for blocks _before_ the duplication ever appears.
+
+### Standalone blocks over inline blocks
+
+Once content is a block, prefer a **standalone block** — `blocks/{name}/index.liquid`, referenced from the section's `"blocks"` array via `@theme` or a named-block reference (`{ "type": "<name>" }`) — over an **inline block** defined inside the section's `{% schema %}`.
+
+- **Default to standalone.** It is reusable across sections, testable on its own, keeps the section schema small, and is how Fluid themes are meant to be composed.
+- **Inline blocks only when the block is very small** (a couple of settings, a few lines of markup) **and** clearly specific to one section. If there's any chance of reuse, go standalone.
+- Extracting an inline block into `blocks/` is always a valid, encouraged fix; never flag the reverse.
+
+| You see                                                                                                          | Severity | Fix                                                          |
+| ---------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------------ |
+| Section content (a heading / text / image / CTA a merchant would add, remove, or reorder) modeled as fixed section settings | `should` | Model it as a block.                                         |
+| A non-trivial inline block (many settings or substantial markup) defined inside a section schema                 | `should` | Extract to a standalone `blocks/{name}/index.liquid` and reference it. |
+| The same inline block duplicated across 2+ sections                                                              | `should` | Extract to one standalone `blocks/{name}/`.                  |
+| A tiny, genuinely one-off inline block                                                                           | `nit`    | Acceptable; suggest standalone only if reuse is likely.      |
+
+### Threshold
+
+**`should`** when:
+
+- A section has **more than ~15 top-level settings**, _and_ any of them look like variations of the same thing
+- A section has 2+ pairs of settings of the form `X_1` / `X_2`
+- A section has a fixed N copies of "card", "feature", "tile", "testimonial", "FAQ", "logo" — anything that semantically wants to be a list
+
+### Bad — settings-panel wall of fields
+
+```json
+{% schema %}
+{
+  "name": "Three Features",
+  "settings": [
+    { "type": "image_picker", "id": "feat_1_icon",  "label": "Feature 1 icon" },
+    { "type": "text",         "id": "feat_1_title", "label": "Feature 1 title" },
+    { "type": "textarea",     "id": "feat_1_body",  "label": "Feature 1 body" },
+    { "type": "image_picker", "id": "feat_2_icon",  "label": "Feature 2 icon" },
+    { "type": "text",         "id": "feat_2_title", "label": "Feature 2 title" },
+    { "type": "textarea",     "id": "feat_2_body",  "label": "Feature 2 body" },
+    { "type": "image_picker", "id": "feat_3_icon",  "label": "Feature 3 icon" },
+    { "type": "text",         "id": "feat_3_title", "label": "Feature 3 title" },
+    { "type": "textarea",     "id": "feat_3_body",  "label": "Feature 3 body" }
+  ]
+}
+{% endschema %}
+```
+
+### Good — block per feature
+
+```json
+{% schema %}
+{
+  "name": "Features",
+  "settings": [
+    { "type": "text",    "id": "heading", "label": "Section heading", "default": "Why us" },
+    { "type": "select",  "id": "columns", "label": "Columns",
+      "options": [{ "value": "2", "label": "2" }, { "value": "3", "label": "3" }, { "value": "4", "label": "4" }],
+      "default": "3" }
+  ],
+  "blocks": [
+    {
+      "type": "feature",
+      "name": "Feature",
+      "settings": [
+        { "type": "image_picker", "id": "icon",  "label": "Icon" },
+        { "type": "text",         "id": "title", "label": "Title" },
+        { "type": "textarea",     "id": "body",  "label": "Description" }
+      ]
+    }
+  ]
+}
+{% endschema %}
+```
+
+Rendering:
+
+```liquid
+<div class="features features--cols-{{ section.settings.columns }}">
+  {%- for block in section.blocks -%}
+    <article class="feature" {{ block.fluid_attributes }}>
+      {%- if block.settings.icon != blank -%}
+        <img src="{{ block.settings.icon }}" alt="{{ block.settings.title | escape }}" />
+      {%- endif -%}
+      <h3>{{ block.settings.title }}</h3>
+      <p>{{ block.settings.body }}</p>
+    </article>
+  {%- endfor -%}
+</div>
+```
+
+**Prefer this as a standalone block.** Define `feature` at `blocks/feature/index.liquid` and reference it from the section's `"blocks"` array (`{ "type": "feature" }`) instead of inlining it — see [Standalone blocks over inline blocks](#standalone-blocks-over-inline-blocks). (A stricter blocks-first read would make `heading` a block too; it's kept as a section setting here only for brevity.)
+
+### Benefits the reviewer should cite when suggesting the fix
+
+- **Editor UX:** Each block shows up as a collapsible item with its own fields — far easier to scan than a 27-field wall.
+- **Drag-and-drop reorder for free.**
+- **Add/remove without code changes:** users can add a 4th feature without a developer.
+- **Per-block dropzone hooks:** `{{ block.fluid_attributes }}` gives the editor click-to-edit on each one.
+- **`limit:` on the block** (optional) enforces a max count without baking it into Liquid.
+- **Reusable across sections** when defined standalone (`blocks/{name}/index.liquid`) instead of inline.
+
+### When sections-with-many-fields _is_ the right answer
+
+Some sections genuinely have many settings that _all_ apply to the whole section — e.g. a configuration-heavy hero with background, overlay, video poster, mobile alt, autoplay, mute, etc. That's fine: those are whole-section **config**, not content. The test isn't field count — it's whether each field is one-per-section plumbing (section setting) or a piece of content a merchant would add / remove / reorder (block).
+
+---

package/skills/themes-review/references/css-js-hygiene.md

@@ -0,0 +1,153 @@
+# CSS / JS asset hygiene
+
+> Part of the `themes-review` skill. See [`../SKILL.md`](../SKILL.md) for the review workflow, severity ladder, and validator rules.
+
+## Contents
+
+- 1. Naming and scoping — everything lives under `assets/`
+- 1a. Deprecated — co-located `styles.css` / `style.css`
+- 2. Tailwind class duplication
+- 3. Dead code
+- 4. Inline `<style>` blocks — extract to assets
+- 5. Inline `<script>` blocks — extract to assets
+- 6. Hardcoded URLs — use `asset_url`
+- 7. Hardcoded copy in markup
+
+
+### 1. Naming and scoping — everything lives under `assets/`
+
+**All stylesheets live under `assets/`.** Co-located `styles.css` / `style.css` files inside `sections/{name}/`, `components/{name}/`, etc. **are deprecated** and should be migrated.
+
+- Section CSS: `assets/{section_name}.css`
+- Component CSS: `assets/{component_name}.css`
+- Global / theme-wide CSS: `assets/theme.css` (or named after intent — `assets/typography.css`, `assets/utilities.css`)
+- Custom stylesheets: `assets/{name}.css`
+- Scope class names by section: `.cart-page__line-item`, not `.line-item`
+
+Referenced via `asset_url`:
+
+```liquid
+{{ 'featured_products.css' | asset_url | stylesheet_tag }}
+````
+
+### 1a. Deprecated — co-located `styles.css` / `style.css`
+
+The earlier theme convention placed a `styles.css` next to each template, section, or component (e.g. `sections/featured/styles.css`). **This is being phased out** in favor of `assets/`-only. The reference `base-theme` still contains `styles.css` files inside section / page-variant directories — these are being migrated.
+
+**`should`** when a PR adds or modifies a co-located stylesheet. **`blocker`** for any new file added under this pattern (new code must follow the assets-only convention).
+
+| You see                                                                                                            | Severity  | Fix                                                                                                               |
+| ------------------------------------------------------------------------------------------------------------------ | --------- | ----------------------------------------------------------------------------------------------------------------- |
+| New file `sections/{name}/styles.css`                                                                              | `blocker` | Place it under `assets/{name}.css` instead and reference via `{{ '{name}.css' \| asset_url \| stylesheet_tag }}`. |
+| New file `components/{name}/style.css`                                                                             | `blocker` | Same — `assets/{name}.css` and `asset_url`.                                                                       |
+| New file under a page-variant directory like `{type}/{variant}/styles.css`                                         | `blocker` | Move to `assets/{name}.css`.                                                                                      |
+| Existing co-located stylesheet edited in the PR                                                                    | `should`  | Suggest migrating to `assets/` as part of the same PR if the diff is small, or a follow-up if not.                |
+| Global / custom stylesheets anywhere outside `assets/` (other than the engine-recognized root `global_styles.css`) | `blocker` | Move to `assets/`.                                                                                                |
+| Hardcoded path like `<link rel="stylesheet" href="/sections/{name}/styles.css">` (bypassing `asset_url`)           | `blocker` | Move the file and switch to `asset_url`.                                                                          |
+
+Migration recipe (suggest in the comment when applicable):
+
+```bash
+# 1. Move the file
+git mv sections/featured/styles.css assets/featured.css
+
+# 2. Update the reference in the section template
+# Find:   {{ 'sections/featured/styles.css' | asset_url | stylesheet_tag }}
+# Replace:{{ 'featured.css' | asset_url | stylesheet_tag }}
+
+# 3. Validate
+fluid theme lint --json
+```
+
+### 2. Tailwind class duplication
+
+Long, identical `class="…"` strings repeated across cards → extract via `{% capture %}` or a component. **`should`** when 4+ identical class strings appear.
+
+### 3. Dead code
+
+See [Dead code — unused blocks, components, sections, assets](#dead-code--unused-blocks-components-sections-assets) for the unified audit. Assets are one category among four.
+
+### 4. Inline `<style>` blocks — extract to assets
+
+**`should`** when any inline `<style>` block exceeds **10 lines**, or when the same inline rules repeat across multiple sections. The engine deduplicates external stylesheets across the page, so external is almost always better.
+
+```liquid
+{%- comment -%} Bad: 40 lines of CSS shipped per section render {%- endcomment -%}
+<style>
+  .featured-products { padding: 64px 0; }
+  .featured-products__heading { font-size: 48px; }
+  .featured-products__grid { display: grid; gap: 24px; ... }
+  /* ... 30 more lines ... */
+</style>
+
+{%- comment -%} Good {%- endcomment -%}
+{{ 'featured_products.css' | asset_url | stylesheet_tag }}
+```
+
+**Exception:** A small block of _dynamic_ CSS that depends on schema settings is fine inline — the dynamism is the whole point. Even then, extract the static base to a stylesheet and leave only the per-section overrides inline:
+
+```liquid
+{{ 'featured_products.css' | asset_url | stylesheet_tag }}
+<style>
+  .featured-products[data-section-id="{{ section.id }}"] {
+    --section-bg: {{ section.settings.bg_color }};
+    --section-pad: {{ section.settings.section_pad }};
+  }
+</style>
+```
+
+### 5. Inline `<script>` blocks — extract to assets
+
+Same rule, lower threshold. **`should`** when any inline `<script>` block exceeds **5 lines**. Inline JS bypasses caching, defeats `defer`, and runs render-blocking unless explicitly deferred via `setTimeout`.
+
+```liquid
+{%- comment -%} Bad {%- endcomment -%}
+<script>
+  document.addEventListener('DOMContentLoaded', function() {
+    const slider = document.querySelector('.featured-slider');
+    new Splide(slider, { type: 'loop', perPage: 3 }).mount();
+    // ...
+  });
+</script>
+
+{%- comment -%} Good {%- endcomment -%}
+<script src="{{ 'featured_slider.js' | asset_url }}" defer></script>
+```
+
+**Exception:** Tiny dynamic config bridges — passing schema settings into a global config object — are acceptable inline if under 5 lines. Keep the runtime in an asset:
+
+```liquid
+<script>
+  window.fluidFeaturedConfig = {{ section.settings | json }};
+</script>
+<script src="{{ 'featured_slider.js' | asset_url }}" defer></script>
+```
+
+### 6. Hardcoded URLs — use `asset_url`
+
+Any reference to an external CDN URL, hardcoded path, or `https://cdn.example.com/...` for assets the theme owns is a finding. The asset belongs in `assets/` and the URL should resolve through `| asset_url`.
+
+| You see                                                                          | Severity  | Fix                                                                                                                                          |
+| -------------------------------------------------------------------------------- | --------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
+| `src="https://cdn.example.com/img/banner.jpg"` (external CDN, theme-owned asset) | `blocker` | Download the file into `assets/banner.jpg` and use `{{ 'banner.jpg' \| asset_url }}`. External CDNs can disappear or change CORS.            |
+| `src="/assets/banner.jpg"` (hardcoded path)                                      | `blocker` | Use `{{ 'banner.jpg' \| asset_url }}`. The engine versions/CDN-fronts the URL.                                                               |
+| `href="https://fonts.googleapis.com/css?family=..."`                             | `should`  | Either upload the font files to `assets/` and `@font-face` them via stylesheet, or use `font_picker`.                                        |
+| `<link rel="stylesheet" href="/some-static.css">`                                | `blocker` | `{{ 'some-static.css' \| asset_url \| stylesheet_tag }}`.                                                                                    |
+| `<script src="https://unpkg.com/some-lib"></script>` (third-party library)       | `should`  | Vendor it into `assets/` and reference via `asset_url`. unpkg/jsDelivr can go down and you have no control over what loads.                  |
+| Image URL hardcoded in CSS (`background-image: url(/assets/x.png)`)              | `should`  | Move the rule into Liquid where `asset_url` is available, or pre-process the CSS, or use a CSS variable injected via inline `<style>` block. |
+| Hardcoded route paths (`href="/products"`, `href="/cart"`)                       | `nit`     | Acceptable when they're well-known engine routes. Surface only if the route ever changes per company.                                        |
+
+**Why these matter:**
+
+- `asset_url` returns a fingerprinted CDN URL — cache-busted on deploy, CDN-fronted globally.
+- External CDNs introduce a dependency on a server you don't control.
+- Hardcoded paths break when the theme is renamed or moved.
+
+### 7. Hardcoded copy in markup
+
+Already covered as **`should`** under [Dynamism](#dynamism--settings-over-hardcoded-values), but it's worth restating here because reviewers often miss it during a CSS/JS pass: literal English (or any language) hardcoded in markup is the same shape of problem as a hardcoded URL — it locks the theme to one company / one locale / one campaign.
+
+- User-visible string → `text` / `textarea` / `richtext` setting
+- Repeated brand-agnostic UI string (Add to cart, Read more) → `locales/en.json` and `{{ 'add_to_cart' | t }}`
+
+---

package/skills/themes-review/references/dead-code.md

@@ -0,0 +1,161 @@
+# Dead code — unused blocks, components, sections, assets
+
+> Part of the `themes-review` skill. See [`../SKILL.md`](../SKILL.md) for the review workflow, severity ladder, and validator rules.
+
+## Contents
+
+- What to check
+- Sections — unused
+- Components — unused
+- Block types — declared but never rendered
+- Assets — unused
+- Output format for removal recommendations
+- When dead-code findings turn into fixes
+
+
+A theme accumulates dead code faster than almost any other codebase: schemas evolve, blocks get renamed, components get inlined, CSS files outlive their consumers. Every dead artifact is **download weight, cognitive load, and a maintenance trap** (someone will eventually edit the dead one wondering why their changes don't show up).
+
+The reviewer's posture: **suggest removal, default to `should`, never delete from a PR without explicit approval.** Most "unused" detections have a small false-positive rate (dynamic strings, future-use), so the recommendation is always "consider removing" with the audit command attached.
+
+### What to check
+
+There are four categories. Each has the same recipe: enumerate what's defined, enumerate what's referenced, take the set difference.
+
+| Category        | Defined                                                | Referenced via                                                                  | Severity                          |
+| --------------- | ------------------------------------------------------ | ------------------------------------------------------------------------------- | --------------------------------- |
+| **Sections**    | `sections/{name}/index.liquid`                         | `{% section 'name' %}` in any `.liquid`                                         | `should`                          |
+| **Components**  | `components/{name}/index.liquid`                       | `{% render 'name' %}` / `{% include 'name' %}`                                  | `should`                          |
+| **Block types** | `{% schema %}` `blocks: [{ "type": "X", ... }]` arrays | `{% case block.type %}` / `{% if block.type == 'X' %}` in the same section file | `should`                          |
+| **Assets**      | files in `assets/` (flat)                              | `{{ 'name' \| asset_url }}` in any `.liquid`                                    | `nit` to flag, `should` to remove |
+
+### Sections — unused
+
+A section file with no `{% section 'name' %}` consumer is dormant. Either it's been deprecated and forgotten, or it was never wired into any page template.
+
+```bash
+# From the theme repo root
+for d in sections/*/; do
+  name=$(basename "$d")
+  count=$(grep -rE "\\{%\\s*section\\s+['\"]${name}['\"]" sections/ components/ layouts/ */default/ 2>/dev/null | wc -l)
+  [ "$count" -eq 0 ] && echo "UNUSED  $d"
+done
+```
+
+**False-positive guard:** some sections are added dynamically by users through the editor — these don't appear in any `{% section %}` literal but are still live. Before recommending removal, check `config/sections/*.json` (per-section metadata) — if metadata exists, the section is registered with the editor and probably in use. Drop the severity to `nit` and frame it as "appears unused in templates — confirm before removing".
+
+### Components — unused
+
+A component partial that nothing renders is dead weight. Lower false-positive rate than sections (no editor-driven instantiation).
+
+```bash
+for d in components/*/; do
+  name=$(basename "$d")
+  count=$(grep -rE "\\{%\\s*(render|include)\\s+['\"]${name}['\"]" sections/ components/ layouts/ */default/ 2>/dev/null | wc -l)
+  [ "$count" -eq 0 ] && echo "UNUSED  $d"
+done
+```
+
+**Watch for dynamic render:** `{% render snippet_name %}` where `snippet_name` is a variable. Grep for the literal first; if zero hits, also grep for the bare name as a string anywhere:
+
+```bash
+grep -rE "['\"]${name}['\"]" sections/ components/ layouts/ */default/ 2>/dev/null | grep -v "components/${name}/"
+```
+
+If that's also zero, it's safe to recommend removal.
+
+### Block types — declared but never rendered
+
+The most insidious form of dead code: a section's `{% schema %}` declares a block type, the editor exposes it to users, users add it, and the template renders **nothing** because the `{% case block.type %}` switch has no matching `when`.
+
+Inside each section file:
+
+```liquid
+{% schema %}
+{
+  "blocks": [
+    { "type": "page_header",  "name": "Page Header" },
+    { "type": "product_grid", "name": "Product Grid" },
+    { "type": "cta_banner",   "name": "CTA Banner" }   ← declared
+  ]
+}
+{% endschema %}
+
+{% for block in section.blocks %}
+  {% case block.type %}
+    {% when 'page_header' %}  ...
+    {% when 'product_grid' %} ...
+    {%- comment -%} cta_banner has no `when` branch — silently rendered as nothing {%- endcomment -%}
+  {% endcase %}
+{% endfor %}
+```
+
+**`should`** when the schema declares a block type that the template never handles. **`blocker`** if users have already populated this block in production (visible as orphan data in `settings_data.json` / per-section metadata) — they're staring at an empty section right now.
+
+Quick audit per section:
+
+```bash
+for f in sections/*/index.liquid; do
+  # block types declared in schema (very rough — schema is JSON inside Liquid)
+  declared=$(awk '/{% schema %}/,/{% endschema %}/' "$f" | grep -oE '"type":\s*"[^"]+"' | grep -v '"type": *"[a-z_]+"$' | sed 's/.*"type":\s*"\([^"]*\)".*/\1/' | sort -u)
+  # block types referenced in template
+  referenced=$(grep -oE "block\.type\s*==\s*['\"][^'\"]+['\"]|when\s+['\"][^'\"]+['\"]" "$f" | grep -oE "['\"][^'\"]+['\"]" | tr -d '"'"'" | sort -u)
+  for d in $declared; do
+    echo "$referenced" | grep -qx "$d" || echo "UNHANDLED  $f  block type: $d"
+  done
+done
+```
+
+(The above is a heuristic — verify each hit manually before recommending. Block schema lives inside JSON-in-Liquid, which is hard to parse with shell tools.)
+
+### Assets — unused
+
+Files in `assets/` that no Liquid reference. Lowest severity because removal is cheapest and risk lowest.
+
+```bash
+for f in assets/*; do
+  name=$(basename "$f")
+  count=$(grep -rE "['\"]${name}['\"]" --include='*.liquid' --include='*.css' . 2>/dev/null | wc -l)
+  echo "$count $name"
+done | sort -n | awk '$1 == 0 { print "UNUSED  " $2 }'
+```
+
+**False positives to filter:**
+
+- Asset referenced via concatenation: `{% assign css = section.id | append: '.css' %}` — rare, but real.
+- Asset referenced from another asset: a CSS file `@import`'ing another CSS file in `assets/`. Re-grep `assets/` itself before recommending removal:
+  ```bash
+  grep -rl "$name" assets/
+  ```
+
+### Output format for removal recommendations
+
+Always frame as "consider removing" with the audit command. Never propose deletion without leaving the human a way to verify:
+
+````
+[should] `components/old_card/index.liquid` appears unused
+
+Audit:
+
+```bash
+grep -rE "\{%\s*(render|include)\s+['\"]old_card['\"]" sections/ components/ layouts/ */default/ 2>/dev/null
+# 0 results
+```
+
+If the grep stays at 0 after this PR, consider removing the file. If it's
+referenced dynamically (variable name into `render`), keep it and add a
+comment at the top noting that.
+
+````
+
+### When dead-code findings turn into fixes
+
+If the user says `open the fix PR`:
+
+1. **Remove sections, components, and assets** in separate commits, one per artifact, so reverting any one is a one-commit revert.
+2. **For block types**, the fix is to either:
+   - Add the missing `when` branch in the template (preferred — the block was meant to render something), or
+   - Remove the declaration from the `{% schema %}` `blocks:` array (only if confirmed no users have populated it).
+3. **Run `fluid theme lint --json` after each removal** — the validator catches `{% section 'name' %}` references that became dangling.
+4. **Never bulk-delete** across categories in one commit. Each removal is its own decision.
+
+---

package/skills/themes-review/references/dynamism.md

@@ -0,0 +1,88 @@
+# Dynamism — settings over hardcoded values
+
+> Part of the `themes-review` skill. See [`../SKILL.md`](../SKILL.md) for the review workflow, severity ladder, and validator rules.
+
+## Contents
+
+- What "hardcoded" looks like
+- What dynamic looks like
+- Findings to surface
+- When _not_ to make something a setting
+
+
+The point of a theme is that the _company_ can edit it without touching code. Anything user-visible that's hardcoded into Liquid is a missed setting. The reviewer should be relentless here: every literal string, color, image URL, link, count, or toggle in markup is a candidate.
+
+**The principle:** if a company employee, designer, or marketer might ever want to change it, it belongs in `{% schema %}`.
+
+### What "hardcoded" looks like
+
+```liquid
+{%- comment -%} Bad: every value here is locked in code {%- endcomment -%}
+<section style="background:#0a0a0a;padding:64px 0;">
+  <h2 style="font-size:48px;color:white;">Our Bestsellers</h2>
+  <p>Browse this season's most popular picks.</p>
+  <img src="https://cdn.example.com/static/banner.jpg" alt="Banner" />
+  <a href="/shop?sort=popular" class="btn">Shop now</a>
+</section>
+```
+
+Every one of those values — background, padding, heading text, body text, image, button text, button link — is a hardcoded decision the company can never override without a code change.
+
+### What dynamic looks like
+
+```json
+{% schema %}
+{
+  "name": "Bestsellers Banner",
+  "settings": [
+    { "type": "text",             "id": "heading",       "label": "Heading",         "default": "Our Bestsellers" },
+    { "type": "textarea",         "id": "body",          "label": "Body text",       "default": "Browse this season's most popular picks." },
+    { "type": "image_picker",     "id": "banner_image",  "label": "Banner image" },
+    { "type": "color_background", "id": "bg_color",      "label": "Background",      "default": "#0a0a0a" },
+    { "type": "color",            "id": "text_color",    "label": "Text color",      "default": "#ffffff" },
+    { "type": "padding",          "id": "section_pad",   "label": "Section padding" },
+    { "type": "text",             "id": "cta_label",     "label": "Button label",    "default": "Shop now" },
+    { "type": "url",              "id": "cta_url",       "label": "Button link",     "default": "/shop?sort=popular" },
+    { "type": "checkbox",         "id": "show_cta",      "label": "Show button",     "default": true }
+  ]
+}
+{% endschema %}
+```
+
+```liquid
+{%- assign s = section.settings -%}
+<section style="background:{{ s.bg_color }};padding:{{ s.section_pad }};">
+  <h2 style="color:{{ s.text_color }};">{{ s.heading | default: 'Our Bestsellers' }}</h2>
+  <p>{{ s.body }}</p>
+  {%- if s.banner_image != blank -%}
+    <img src="{{ s.banner_image }}" alt="{{ s.heading | escape }}" />
+  {%- endif -%}
+  {%- if s.show_cta -%}
+    <a href="{{ s.cta_url }}" class="btn">{{ s.cta_label }}</a>
+  {%- endif -%}
+</section>
+```
+
+### Findings to surface
+
+| You see                                                                | Severity                                        | Why                                                                                               |
+| ---------------------------------------------------------------------- | ----------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| User-visible literal text in markup (heading, paragraph, button label) | `should`                                        | Should be a `text` / `textarea` / `richtext` setting.                                             |
+| Hardcoded colors (`#0a0a0a`, `rgb(...)`, `red`) in style/attribute     | `should`                                        | Should be a `color` or `color_background` setting.                                                |
+| Hardcoded image URL (external CDN, hardcoded path)                     | `blocker` if external CDN, `should` if internal | External CDNs can break, get blocked, or change. Upload to `assets/` or expose as `image_picker`. |
+| Hardcoded `href` to a fixed page or `?sort=popular`-style URL          | `should`                                        | Use a `url` setting.                                                                              |
+| Hardcoded counts (`limit: 6`, `limit: 12`) in `for` loops              | `nit` → `should`                                | Expose as a `range` setting if the company might want to change density.                          |
+| Boolean branches with no user toggle (`{% if true %}`)                 | `should`                                        | Either delete or expose as a `checkbox`.                                                          |
+| Tailwind class strings that bake in color (`bg-black text-white`)      | `should`                                        | Use CSS variables driven by `color` settings.                                                     |
+
+### When _not_ to make something a setting
+
+Adding settings has a real cost — they clutter the editor and shift the burden to non-technical users. Skip settings for:
+
+- Internal layout primitives (grid gaps, micro-margins) the design system already controls
+- Engineering plumbing (data attributes, schema markup hooks)
+- Values that _must_ stay in lockstep with code (icon class names, route slugs the theme relies on)
+
+The test: _would I expect a non-developer to want to change this?_ No → leave it hardcoded. Yes → make it a setting.
+
+---