@fluid-app/fluid-cli-theme-dev 0.1.19 → 0.1.21

package/skills/themes-review/references/editor-attributes.md

@@ -0,0 +1,160 @@
+# Editor selector attributes — fluid_attributes
+
+> Part of the `themes-review` skill. See [`../SKILL.md`](../SKILL.md) for the review workflow, severity ladder, and validator rules.
+
+## Contents
+
+- What `fluid_attributes` emits
+- The two drops
+- Correct usage
+- Findings to surface
+- Examples from the reference theme
+- Quick audit
+
+
+Sections and blocks have a Liquid drop called `fluid_attributes` that emits the `data-fluid-section-*` attributes the visual editor uses to find, select, click-to-edit, and drag-to-reorder the element. **Without these attributes on the right element, the editor cannot interact with the content** — click handlers don't bind, inspector panels don't open, drag-and-drop is dead.
+
+> **Note:** Despite the `data-fluid-*` prefix, these are _editor_ attributes — not the same as the runtime [FairShare behavioral attributes](#fairshare-behavioral-attributes--data-fluid-) below (which wire up cart, checkout, enrollment behavior). Keep them straight: `section.fluid_attributes` / `block.fluid_attributes` are Liquid drops the _theme engine_ emits in editor mode; FairShare attributes are _hand-written_ HTML attributes that the FairShare runtime SDK reads.
+
+These attributes are only populated in editor preview mode; in production rendering, the drops emit an empty string. So a missing call has zero visible effect at runtime — the bug only surfaces in the editor. That's why reviewers must catch it.
+
+### What `fluid_attributes` emits
+
+In editor mode, `{{ block.fluid_attributes }}` expands to the full set of `data-fluid-*` attributes the editor needs to find and edit the block — block id, parent section type, section id, block type, and a serialized settings payload — rendered as one attribute string on the element:
+
+```html
+<div
+  data-fluid-section-block-id="abc123"
+  data-fluid-parent-section-type="hero"
+  data-fluid-section-id="45678"
+  data-fluid-section-block-type="heading"
+  data-fluid-block-attribute='{"color":"#000000",...}'
+></div>
+```
+
+### The two drops
+
+| Drop                             | Where it's available                                                                             | Where to emit it                                |
+| -------------------------------- | ------------------------------------------------------------------------------------------------ | ----------------------------------------------- |
+| `{{ section.fluid_attributes }}` | Inside a section file (`sections/{name}/index.liquid`)                                           | On the **root** wrapper element of the section  |
+| `{{ block.fluid_attributes }}`   | Inside a `{% for block in section.blocks %}` loop, or when a block context is passed to a render | On the **root** wrapper element of _each_ block |
+
+**These are the only two.** There is no `component.fluid_attributes`, no dropzone drop, no slot drop, no inline-editing helper. Components are pure partials — they don't have editor presence on their own; the section/block that _renders_ them carries the attributes.
+
+### Correct usage
+
+```liquid
+{%- comment -%} Section root: section's attributes on the outer wrapper {%- endcomment -%}
+<section class="featured-products" {{ section.fluid_attributes }}>
+  {%- for block in section.blocks -%}
+    {%- case block.type -%}
+      {%- when 'heading' -%}
+        <h2 class="featured-products__heading" {{ block.fluid_attributes }}>
+          {{ block.settings.text | escape }}
+        </h2>
+
+      {%- when 'product_card' -%}
+        <article class="featured-products__card" {{ block.fluid_attributes }}>
+          {% render 'product_card', product: block.settings.product %}
+        </article>
+
+      {%- when 'cta' -%}
+        {%- comment -%} Passing into a component? Forward the attrs through a named arg. {%- endcomment -%}
+        {% render 'button',
+          text:    block.settings.label,
+          href:    block.settings.link,
+          variant: block.settings.variant,
+          attr:    block.fluid_attributes %}
+    {%- endcase -%}
+  {%- endfor -%}
+</section>
+```
+
+When a block's content is fully delegated to a component, the standard pattern is to forward the attributes as a named argument (`attr: block.fluid_attributes`) and have the component apply them on its root element. See `sections/hero_section/index.liquid` in the reference theme and the `button` component for examples.
+
+### Findings to surface
+
+| You see                                                                                                                      | Severity                    | Fix                                                                                                                                                                                                                   |
+| ---------------------------------------------------------------------------------------------------------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| Section file has no `{{ section.fluid_attributes }}` anywhere                                                                | `blocker`                   | Add it to the outer wrapper element of the section. Editor cannot select the section without it.                                                                                                                      |
+| Section uses `{% for block in section.blocks %}` and the block's root element has no `{{ block.fluid_attributes }}`          | `blocker`                   | Each block's outer element must carry its own `block.fluid_attributes`. Without it the editor can't click-to-edit individual blocks.                                                                                  |
+| Typo: `{{ section.fluid_attribute }}` (singular)                                                                             | `blocker`                   | The drop name is `fluid_attributes` (plural). The singular form renders empty.                                                                                                                                        |
+| Typo: `{{ block.fluid_attr }}` / `{{ section.fluidAttributes }}` / `{{ section.fluid_attribute_set }}`                       | `blocker`                   | Only `fluid_attributes` exists.                                                                                                                                                                                       |
+| Attributes applied on a child element instead of the root                                                                    | `blocker`                   | Move to the outermost element of the section/block. The editor walks ancestors looking for the closest match; placing it on a child means the editor picks up _that_ element as the section bounds, not the real one. |
+| Same `{{ section.fluid_attributes }}` applied to multiple elements                                                           | `should`                    | Apply it once — to the root. Duplicates render the same `data-*` attributes twice in the DOM.                                                                                                                         |
+| Hardcoded `data-fluid-*` attributes (`data-section-id="{{ section.id }}"`) instead of the helper                             | `blocker`                   | Replace with `{{ section.fluid_attributes }}` / `{{ block.fluid_attributes }}`. The helper emits a full attribute set; hand-rolling drops most of them.                                                               |
+| Block-aware component (renders inside `{% for block %}`) has no `attr` parameter to receive `block.fluid_attributes`         | `should`                    | Add an `attr` argument to the component's signature and apply it on the component's root element.                                                                                                                     |
+| Conditional render without protecting against `nil`: `<div {{ section.fluid_attributes }}>` where `section` may be undefined | `should` (rarely `blocker`) | Wrap: `{% if section %}{{ section.fluid_attributes }}{% endif %}`. Same for `block`. Only relevant where the value can legitimately be nil.                                                                           |
+
+### Examples from the reference theme
+
+Section root with attributes — `sections/main_product/index.liquid:49-51` in the reference fluid theme:
+
+```liquid
+<div
+  class="MainProductBlock MainProductBlock--breadcrumb MainProductBlock--{{ block.id }}"
+  {{ block.fluid_attributes }}
+>
+```
+
+Block forwarding through to a component as `attr:` — `sections/hero_section/index.liquid:140-149` in the reference fluid theme:
+
+```liquid
+{%- if block.type == 'button' -%}
+  {%- render 'button',
+    text:    block.settings.text,
+    href:    block.settings.link,
+    variant: block.settings.variant | default: 'primary',
+    size:    block.settings.size    | default: 'md',
+    attr:    block.fluid_attributes
+  -%}
+```
+
+Multiple blocks each carrying their own attrs — `sections/main_category/index.liquid:109,123,158` in the reference fluid theme:
+
+```liquid
+<div class="categories-page-header-copy" {% if header_block %}{{ header_block.fluid_attributes }}{% endif %}>
+  <h2>{{ page_title }}</h2>
+</div>
+
+<div class="categories-page-view-all" {% if view_all_block %}{{ view_all_block.fluid_attributes }}{% endif %}>
+  {% render 'button', ... %}
+</div>
+
+<div
+  class="splide carousel"
+  data-fluid-resource-slider
+  {% if grid_block %}{{ grid_block.fluid_attributes }}{% endif %}
+>
+```
+
+### Quick audit
+
+From the theme repo root:
+
+```bash
+# Sections missing section.fluid_attributes entirely
+for f in sections/*/index.liquid; do
+  grep -q 'section\.fluid_attributes' "$f" || echo "MISSING section.fluid_attributes  $f"
+done
+
+# Sections that iterate blocks but never emit block.fluid_attributes
+for f in sections/*/index.liquid; do
+  iterates=$(grep -q 'for\s\+block\s\+in\s\+section\.blocks' "$f" && echo yes)
+  emits=$(grep -q 'block\.fluid_attributes' "$f" && echo yes)
+  if [ "$iterates" = "yes" ] && [ "$emits" != "yes" ]; then
+    echo "MISSING block.fluid_attributes  $f"
+  fi
+done
+
+# Common typos
+grep -rE 'fluid_attribute[^s]|fluidAttributes|fluid_attribute_set' sections/ components/
+
+# Hardcoded data-fluid-* attributes (likely should use the helper)
+grep -rE 'data-fluid-section-id|data-fluid-section-block-id|data-fluid-parent-section-type' sections/ components/ \
+  | grep -v 'fluid_attributes'
+```
+
+The last grep is the one to actually open a PR comment on — any hit is a hand-rolled subset of what the helper would emit.
+
+---

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

@@ -0,0 +1,111 @@
+# Worked examples — full section reviews
+
+> Part of the `themes-review` skill. See [`../SKILL.md`](../SKILL.md) for the review workflow, severity ladder, and validator rules.
+
+## Contents
+
+- Summary review output
+- Inline comment (line 9)
+- Inline comment (lines 5-8)
+
+
+**File:** `sections/featured_products/index.liquid`
+
+```liquid
+{% schema %}
+{
+  "name": "Featured Products",
+  "settings": [
+    { "type": "text",        "id": "heading", "label": "Heading" },
+    { "type": "product",     "id": "p1",      "label": "Product 1" },
+    { "type": "product",     "id": "p2",      "label": "Product 2" },
+    { "type": "product",     "id": "p3",      "label": "Product 3" },
+    { "type": "product",     "id": "p4",      "label": "Product 4" },
+    { "type": "text_area",   "id": "desc",    "label": "Description" },
+    { "type": "image",       "id": "bg",      "label": "Background" }
+  ]
+}
+{% endschema %}
+
+<section>
+  <h2>{{ section.settings.heading }}</h2>
+
+  {% for product in products %}
+    <img src="{{ 'placeholder.png' | asset_url }}" />
+    <a href="{{ product.url }}">{{ product.title }}</a>
+  {% endfor %}
+
+  {% if section.settings.p1 != blank %}{% render 'product_card', product: section.settings.p1 %}{% endif %}
+  {% if section.settings.p2 != blank %}{% render 'product_card', product: section.settings.p2 %}{% endif %}
+  {% if section.settings.p3 != blank %}{% render 'product_card', product: section.settings.p3 %}{% endif %}
+  {% if section.settings.p4 != blank %}{% render 'product_card', product: section.settings.p4 %}{% endif %}
+</section>
+````
+
+### Summary review output
+
+```
+## Theme review — featured_products.liquid
+
+**8 findings** — 3 blocker, 4 should, 1 nit
+
+Reproduce locally with `fluid theme lint --json`.
+
+| Severity | Line | Finding |
+|---|---|---|
+| blocker | 9  | Invalid type `text_area` — use `textarea`. Validator rejects. |
+| blocker | 16 | Missing `{{ section.fluid_attributes }}` on the section root — editor cannot select or click-to-edit this section. Replace `<section>` with `<section {{ section.fluid_attributes }}>`. |
+| blocker | 18 | `{% for product in products %}` — `products` is undefined in this scope. It is not a global drop, and the schema declares no `products` setting. Loop silently iterates `nil`. Collapse to the `product_list` fix below (`section.settings.products`) or remove. |
+| should  | 10 | Type `image` is valid but `image_picker` is clearer for new code |
+| should  | 5-8 | Four `product` settings, same role — collapse to one `product_list` with `limit: 4` |
+| should  | 19 | `asset_url` resolved inside loop — hoist above |
+| should  | 16-21 | Missing whitespace control on `{% for %}` / `{% endfor %}` |
+| nit     | 17 | `<h2>{{ section.settings.heading }}</h2>` — add `| default: 'Featured'` |
+```
+
+### Inline comment (line 9)
+
+````
+[blocker] Invalid setting type `text_area`
+
+The schema validator only accepts the canonical type list. `fluid theme lint --json`
+fails on this. The correct type is `textarea`:
+
+```json
+{ "type": "textarea", "id": "desc", "label": "Description" }
+```
+````
+
+### Inline comment (lines 5-8)
+
+````
+
+[should] Four `product` settings — collapse to `product_list`
+
+Four singular product pickers playing the same role. Replace with one list:
+
+```json
+{
+  "type": "product_list",
+  "id": "products",
+  "label": "Products",
+  "limit": 4
+}
+```
+
+Render block becomes a single loop:
+
+```liquid
+{%- for product in section.settings.products -%}
+  {% render 'product_card', product: product %}
+{%- endfor -%}
+```
+
+This drops 4 conditionals + 4 settings into 1 + 1 and removes the per-slot upper
+bound the manual setup encoded by accident. A `product_list` does **not** give
+drag-and-drop reorder — that's a blocks feature; model items as blocks if the
+merchant needs to reorder them.
+
+````
+
+---

package/skills/themes-review/references/fairshare-attributes.md

@@ -0,0 +1,185 @@
+# FairShare behavioral attributes — data-fluid-*
+
+> Part of the `themes-review` skill. See [`../SKILL.md`](../SKILL.md) for the review workflow, severity ladder, and validator rules.
+
+## Contents
+
+- Naming convention
+- Loading the runtime
+- The attributes
+- Correct usage examples
+- Findings to surface
+- Quick audit
+- Checklist for FairShare-attributed elements
+
+
+These are the **runtime behavioral attributes** consumed by the FairShare web-widget SDK (loaded from `https://assets.fluid.app/scripts/fluid-sdk/latest/web-widgets/index.js`). Theme authors hand-write them on buttons, links, and elements to wire up commerce behavior — add to cart, open cart drawer, add enrollment packs, etc.
+
+**This is different from `section.fluid_attributes` above.** The editor attributes are emitted by Liquid drops in editor mode. These are static HTML attributes you write into the template that the runtime SDK scans for on `DOMContentLoaded`.
+
+### Naming convention
+
+All FairShare runtime attributes are `data-fluid-*` (kebab-case, `data-` prefix). The SDK is case-sensitive — `data-fluid-add-to-cart` works, `data-fluid-addToCart` and `data-fluid_add_to_cart` do not. The runtime auto-scans the DOM; no init call is required.
+
+### Loading the runtime
+
+```html
+<script
+  id="fluid-cdn-script"
+  src="https://assets.fluid.app/scripts/fluid-sdk/latest/web-widgets/index.js"
+  data-fluid-shop="{{ shop.handle }}"
+  defer
+></script>
+```
+
+`data-fluid-shop` is required. Optional script-level attributes: `data-fluid-api-base-url`, `data-fluid-country` (2-letter ISO), `data-fluid-language` (2–3 letter), `data-fluid-rep-id`, `data-share-guid`, `data-debug`.
+
+### The attributes
+
+| Attribute                         | Value shape                                                 | Goes on                                                                           | Notes                                                                                                                                                         |
+| --------------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `data-fluid-cart`                 | `"open"` / `"close"` / `"toggle"`                           | button/link                                                                       | Lowercase only. Strict equality check in the SDK.                                                                                                             |
+| `data-fluid-add-to-cart`          | comma-separated variant IDs (integers)                      | button/link                                                                       | Companion for `data-fluid-quantity`, `data-fluid-subscribe`, `data-fluid-subscription-plan-id`, `data-fluid-bundled-items`, `data-fluid-open-cart-after-add`. |
+| `data-fluid-quantity`             | positive integer                                            | button/link **with** `data-fluid-add-to-cart` or `data-fluid-add-enrollment-pack` | Defaults to 1.                                                                                                                                                |
+| `data-fluid-subscribe`            | `"true"` / `"false"` or comma-separated per item            | button/link **with** `data-fluid-add-to-cart`                                     | Per-item shape mirrors the variant ID list.                                                                                                                   |
+| `data-fluid-subscription-plan-id` | **single** integer                                          | button/link **with** `data-fluid-add-to-cart`                                     | **Only one** — comma-separated values are not supported.                                                                                                      |
+| `data-fluid-bundled-items`        | JSON string `[{"variant_id": int, "quantity": int}, ...]`   | button/link **with** `data-fluid-add-to-cart`                                     | Invalid JSON is logged and silently dropped.                                                                                                                  |
+| `data-fluid-open-cart-after-add`  | `"true"` / `"false"`                                        | button/link **with** add-to-cart or enrollment-pack                               | Defaults to `"true"`. Set `"false"` to keep shopping.                                                                                                         |
+| `data-fluid-add-enrollment-pack`  | enrollment pack ID (integer)                                | button/link                                                                       | Can combine with `data-fluid-add-to-cart` for pack + items in one click.                                                                                      |
+| `data-fluid-bundle-selections`    | JSON string `[{"variant_id": int, "bundled_items": [...]}]` | button/link **with** `data-fluid-add-enrollment-pack`                             | For packs whose products take variant/bundle config.                                                                                                          |
+| `data-fluid-add-combined`         | `"{enrollmentPackId}+{variantId1},{variantId2},..."`        | button/link                                                                       | Alternative to setting both `data-fluid-add-to-cart` and `data-fluid-add-enrollment-pack`.                                                                    |
+
+### Correct usage examples
+
+```html
+{%- comment -%} Open cart drawer {%- endcomment -%}
+<button data-fluid-cart="open">Cart ({{ cart.item_count }})</button>
+
+{%- comment -%} Add one item {%- endcomment -%}
+<button data-fluid-add-to-cart="{{ product.first_variant.id }}">
+  Add to cart
+</button>
+
+{%- comment -%} Add with quantity + subscription {%- endcomment -%}
+<button
+  data-fluid-add-to-cart="{{ variant.id }}"
+  data-fluid-quantity="2"
+  data-fluid-subscribe="true"
+  data-fluid-subscription-plan-id="{{ section.settings.default_plan_id }}"
+>
+  Subscribe &amp; save
+</button>
+
+{%- comment -%} Add a bundle product with its bundled items {%- endcomment -%}
+<button
+  data-fluid-add-to-cart="{{ bundle_variant.id }}"
+  data-fluid-bundled-items='[
+    {%- for item in selected_items -%}
+      { "variant_id": {{ item.variant_id }}, "quantity": {{ item.qty }} }{%- unless forloop.last -%},{%- endunless -%}
+    {%- endfor -%}
+  ]'
+  data-fluid-open-cart-after-add="false"
+>
+  Add bundle
+</button>
+
+{%- comment -%} Add an enrollment pack {%- endcomment -%}
+<button data-fluid-add-enrollment-pack="{{ section.settings.starter_pack.id }}">
+  Join with starter pack
+</button>
+```
+
+### Findings to surface
+
+The reviewer should flag these on any element that uses `data-fluid-*`:
+
+#### Wrong attribute names (typos / wrong casing)
+
+**`blocker`** — the SDK only recognizes the exact kebab-case forms listed above.
+
+| You see                                                     | Severity  | Fix                                              |
+| ----------------------------------------------------------- | --------- | ------------------------------------------------ |
+| `data-fluid-addToCart="..."`                                | `blocker` | `data-fluid-add-to-cart="..."`                   |
+| `data-fluid_add_to_cart="..."` (underscores)                | `blocker` | Kebab-case only.                                 |
+| `datafluid-add-to-cart="..."` (missing hyphen after `data`) | `blocker` | Must be `data-fluid-*`.                          |
+| `fluid-add-to-cart="..."` (missing `data-` prefix)          | `blocker` | Add `data-`.                                     |
+| `data-fluid-cart="Open"` / `"OPEN"`                         | `blocker` | Lowercase: `"open"` / `"close"` / `"toggle"`.    |
+| `data-fluid-cart="show"` / `"display"`                      | `blocker` | Only `open` / `close` / `toggle` are recognized. |
+
+#### Missing required companions / dangling modifiers
+
+**`blocker`** — modifier attributes are inert without their owner.
+
+| You see                                                                                                        | Severity  | Fix                                                     |
+| -------------------------------------------------------------------------------------------------------------- | --------- | ------------------------------------------------------- |
+| `data-fluid-quantity` on an element with neither `data-fluid-add-to-cart` nor `data-fluid-add-enrollment-pack` | `blocker` | Either pair it with one of the add-actions or remove.   |
+| `data-fluid-subscribe` without `data-fluid-add-to-cart`                                                        | `blocker` | Subscribe is meaningful only in an add-to-cart context. |
+| `data-fluid-subscription-plan-id` without `data-fluid-add-to-cart`                                             | `blocker` | Same.                                                   |
+| `data-fluid-bundled-items` without `data-fluid-add-to-cart`                                                    | `blocker` | Bundled items modify the add-to-cart action.            |
+| `data-fluid-bundle-selections` without `data-fluid-add-enrollment-pack`                                        | `blocker` | Only meaningful when adding a pack.                     |
+| `data-fluid-open-cart-after-add` on an element with no add-action                                              | `should`  | Inert — remove or pair with an add-action.              |
+
+#### Wrong value shapes
+
+| You see                                                                                    | Severity  | Fix                                                                                                           |
+| ------------------------------------------------------------------------------------------ | --------- | ------------------------------------------------------------------------------------------------------------- |
+| `data-fluid-subscription-plan-id="4,5"` (comma-separated)                                  | `blocker` | Single integer only. If the items need different plans, that's not supported — drop down to single-item rows. |
+| `data-fluid-quantity="2.5"` / `"0"` / `"-1"`                                               | `blocker` | Positive integer.                                                                                             |
+| `data-fluid-subscribe="yes"` / `"1"` / `"on"`                                              | `blocker` | String `"true"` or `"false"` only.                                                                            |
+| `data-fluid-bundled-items='[{"variant_id":"39325", "quantity":1}]'` (variant_id as string) | `blocker` | `variant_id` and `quantity` must be JSON numbers.                                                             |
+| `data-fluid-bundled-items='{...}'` (object, not array)                                     | `blocker` | Must be a JSON array.                                                                                         |
+| Single-quote-wrapped JSON without escaping inner double quotes                             | `blocker` | Use `'[...]'` outer + `"..."` inner per the examples. Mismatched quoting breaks parsing silently.             |
+| `data-fluid-country="USA"` (3-letter) on the script tag                                    | `blocker` | 2-letter ISO. `"US"`, not `"USA"`.                                                                            |
+| `data-fluid-language="english"` on the script tag                                          | `blocker` | 2–3 letter code: `"en"`, `"es"`, `"fil"`.                                                                     |
+
+#### Wrong element type / placement
+
+| You see                                                                 | Severity                                              | Fix                                                                                                                   |
+| ----------------------------------------------------------------------- | ----------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| `data-fluid-add-to-cart` on a `<div>` with no click semantics           | `should` (`blocker` for accessibility-critical pages) | Use `<button type="button">` or `<a href="...">`.                                                                     |
+| `data-fluid-add-to-cart` on a parent that wraps multiple buttons        | `blocker`                                             | Move to the specific clickable child — the SDK click handler fires once per click, on the element with the attribute. |
+| `data-fluid-shop` missing from the `<script id="fluid-cdn-script">` tag | `blocker`                                             | Required for SDK init. Without it, none of the `data-fluid-*` attributes do anything.                                 |
+| Multiple `<script>` tags with `id="fluid-cdn-script"`                   | `blocker`                                             | The SDK uses this ID for self-discovery; duplicates pick a random one.                                                |
+
+#### Liquid-side mistakes
+
+| You see                                                                                        | Severity                           | Fix                 |
+| ---------------------------------------------------------------------------------------------- | ---------------------------------- | ------------------- | -------------------------------------------------------------------------------------------------------------------- |
+| `data-fluid-add-to-cart="{{ variant }}"` (drop, not `.id`)                                     | `blocker`                          | `{{ variant.id }}`. |
+| `data-fluid-quantity="{{ section.settings.default_qty                                          | default: 1 }}"` rendering to empty | `should`            | Always provide a `default:` filter for settings that are required by the SDK to be integers.                         |
+| `data-fluid-bundled-items` JSON built with un-escaped Liquid (commas/quotes from user content) | `blocker`                          | Render through `    | json` or hand-craft only with sanitized numeric IDs. User-controlled strings inside JSON attributes are an XSS path. |
+
+### Quick audit
+
+From the theme repo root:
+
+```bash
+# Wrong attribute prefixes
+grep -rE 'datafluid-|data-fluid_|[^a-z-]fluid-add-to-cart|[^a-z-]fluid-cart=' --include='*.liquid' . 2>/dev/null
+
+# Common camelCase typos
+grep -rE 'data-fluid-(addToCart|openCartAfterAdd|subscriptionPlanId|bundledItems)' --include='*.liquid' . 2>/dev/null
+
+# Modifier attributes without an owner action in the same element
+# (heuristic — manual review still needed)
+grep -rln 'data-fluid-quantity' --include='*.liquid' . 2>/dev/null | while read -r f; do
+  if ! grep -q 'data-fluid-add-to-cart\|data-fluid-add-enrollment-pack' "$f"; then
+    echo "POSSIBLE_ORPHAN  $f"
+  fi
+done
+
+# Wrong cart action values
+grep -rE 'data-fluid-cart="(?!(open|close|toggle)")' --include='*.liquid' . 2>/dev/null
+```
+
+### Checklist for FairShare-attributed elements
+
+- [ ] Attribute name is exact kebab-case with `data-fluid-` prefix
+- [ ] `data-fluid-cart` value is `open` / `close` / `toggle` (lowercase)
+- [ ] Modifier attributes (`quantity`, `subscribe`, `subscription-plan-id`, `bundled-items`, `open-cart-after-add`) are paired with an add-action attribute
+- [ ] `data-fluid-subscription-plan-id` carries a single integer
+- [ ] `data-fluid-bundled-items` / `data-fluid-bundle-selections` are valid JSON arrays with numeric IDs and quantities
+- [ ] Attributes live on a `<button>` or `<a>` (or have appropriate ARIA + click semantics)
+- [ ] Script tag has `id="fluid-cdn-script"` and `data-fluid-shop` set, and there is exactly one
+
+---