@se-studio/contentful-cms 1.0.43 → 1.0.44

package/skills/cms-guidelines/generation-prompt.md

@@ -1,231 +0,0 @@
-# Generation Prompt — Code + Screenshots → Guideline Block
-
-**Step 5.1 — Multi-step prompts for generating one guideline fragment.**
-
-Run as a **Cursor agent task**. The agent reads the component source, screenshots, and field
-metadata, then writes a self-contained markdown guideline fragment in the target format.
-
----
-
-## Inputs
-
-| Input | Source |
-|---|---|
-| Component source file | `src/project/components/<TypeName>.tsx` |
-| Field metadata (used fields + types + enums) | `generated/cms-discovery/field-list.json` |
-| Project theme (palette + typography + grid) | `generated/cms-discovery/theme-context.md` |
-| Accepted screenshots | `generated/cms-discovery/accepted-variants/{components\|collections\|externals}/<type-slug>.json` + image files |
-| Target format example | `tmp/component-guidelines-target-format.md` (Hero example) |
-| Mapping reference | `generated/cms-discovery/mapping.md` |
-| SizingInformation source | `src/lib/SizingInformation.ts` |
-| Section wrapper source | `src/framework/Section.tsx` (for backgroundColour/textColour behaviour) |
-
----
-
-## Step 1 of 3 — Describe the screenshots
-
-**Prompt:**
-
-```
-You are documenting a CMS component for a marketing site.
-
-I will give you screenshots of the component in different states, and the component's
-accepted variant list. Describe what you see in each screenshot.
-
-Component: <COMPONENT_TYPE>
-
-Accepted variants (from accepted-variants/{components|collections|externals}/<type-slug>.json):
-<ACCEPTED_VARIANTS_JSON>
-
-Project theme (from generated/cms-discovery/theme-context.md):
-<THEME_CONTEXT>
-
-For each variant, describe:
-- The visual layout (columns, stack, full-width, etc.)
-- The elements visible (heading, eyebrow, body, links, visual/image, background colour)
-- The typography appearance (large heading, small body text, etc.)
-- The colour scheme (background colour, text colour, whether the visual is tinted)
-- Anything notable (animations not applicable in screenshots, spacing gaps, alignment)
-
-Be precise. Write one short paragraph per variant (3–5 sentences). No code references.
-Only use colour names from the site palette (listed in the theme context above) and
-typography class names (h1–h6, p2, p3 etc. from the typography scale above).
-
-Output format: one section per variant, headed by ## <label>.
-```
-
----
-
-## Step 2 of 3 — Extract behaviour and fields from code
-
-**Prompt:**
-
-```
-You are writing CMS component documentation.
-
-I will give you the source code of a Next.js component. Extract all behaviour
-rules for the documentation. Do NOT quote or reference the code — translate
-the code behaviour into plain English rules that a non-developer can follow.
-
-Component source:
-<COMPONENT_SOURCE>
-
-SizingInformation.ts source (shows how index affects heading level and section spacing):
-<SIZING_INFORMATION_SOURCE>
-
-Section.tsx source (shows how backgroundColour and textColour are applied):
-<SECTION_SOURCE>
-
-Field mapping reference (mapping.md — shows how CMS fields map to app props):
-<MAPPING_SOURCE>
-
-Project theme (palette, typography, grid from generated/cms-discovery/theme-context.md):
-<THEME_CONTEXT>
-
-Extract and write:
-1. FIELDS: For each field in USED_FIELDS, write one row: field name, type, what it does when
-   set, what happens when it is empty. Use only typography class names and colour names as
-   code snippets. No file paths.
-2. BEHAVIOUR: Any behaviour that depends on position (index), variant (flipped), or other
-   logic. E.g. "When this is the first block on the page, the heading renders as <h1>".
-3. IMPACT: What visually changes when content changes (longer text, add/remove visual, etc.).
-4. TYPOGRAPHY: Which typography classes (h1–h6, p2, p3, h4, etc.) are applied to each element.
-5. COLOUR APPLICATION: How backgroundColour and textColour are applied. Section-wide? Per-card?
-
-Output each section clearly labelled (## Fields, ## Behaviour, ## Impact, ## Typography,
-## Colour Application). No code blocks. No file references. Plain English only (except
-typography class names and colour names).
-```
-
----
-
-## Step 3 of 3 — Merge into guideline block
-
-**Prompt:**
-
-```
-You are writing a self-contained CMS component guideline fragment.
-
-Below are two inputs:
-A) Screenshot descriptions for each variant of <COMPONENT_TYPE>.
-B) Extracted behaviour rules from the source code.
-
-Also provided:
-- The target format example (Hero guideline from tmp/component-guidelines-target-format.md).
-- The field list from generated/cms-discovery/field-list.json.
-- The project theme from generated/cms-discovery/theme-context.md (palette names + typography scale).
-- The screenshot index from docs/cms-guidelines/screenshots/index.json (lists captured screenshots).
-- The app's devBaseUrl from .contentful-cms.json (e.g. "http://localhost:3010").
-
-Produce a single markdown fragment for <COMPONENT_TYPE> following EXACTLY this structure:
-
-# <ComponentType>
-(one-line summary of what it is and when to use it)
-
-## Screenshots
-
-(For each accepted variant that has a captured screenshot in index.json, include an image link.
-Use the devBaseUrl from .contentful-cms.json for the host.
-Use the `file` field from index.json VERBATIM as the ?file= value — it may include a subdirectory
-prefix such as `components/` or `collections/`. Do NOT reconstruct the path from the type slug. Format:)
-
-| Variant | Preview |
-|---------|---------|
-| Default | ![Default](<devBaseUrl>/cms/screenshot?file=<file-field-from-index-json>) |
-| Navy    | ![Navy](<devBaseUrl>/cms/screenshot?file=<file-field-from-index-json>) |
-
-(Only include variants present in index.json. If no screenshots exist, write: "No screenshots captured yet. Run cms-capture-screenshots to generate them.")
-
-## What it looks like
-(describe layout, columns, stacking, visible elements — based on screenshot descriptions)
-
-## Typography
-(typography classes for heading, body, subtitle — bullets only)
-
-## Colours
-(how backgroundColour/textColour apply — section-wide? per-card? valid palette values)
-
-## Used fields
-(table: Field | Type | Effect when set | Effect when empty/removed)
-
-## Behaviour
-(position/index rules, variant differences, anything that depends on content logic)
-
-## Impact of content changes
-(table or bullets: what changes when you add/remove/change specific fields)
-
-Rules:
-- SELF-CONTAINED. A reader with no code access must fully understand the component.
-- No source code references, no file paths, no "see Hero.tsx".
-- Only use typography class names (from theme-context.md, e.g. h1–h6, p2, p3) and colour
-  names (from theme-context.md palette) as code-like snippets. Everything else is plain English.
-- For the ## Colours section, list the valid palette colour names from theme-context.md — do
-  NOT invent colour names or describe them generically.
-- If a field is listed in USED_FIELDS but has no visual effect when empty, say
-  "No visible effect when empty" in the table.
-- Collections: add a section for card-level fields and describe how the number of cards
-  affects layout.
-- External components: omit screenshots and the Screenshots section; describe parameters instead.
-- Screenshot links use the devBaseUrl from .contentful-cms.json — they resolve when the dev
-  server is running and are useful for both human reviewers and AI assistants.
-
-Output raw markdown only. Start with "# <ComponentType>". No preamble.
-```
-
----
-
-## External component variant
-
-For external components (no showcase), replace Step 1 with:
-
-```
-The component has no screenshots (not yet in the showcase). Instead, describe what
-the component likely looks like based on its name and parameters alone. Mark this
-section with a note: "(Visual description estimated from code; no screenshots available.)"
-```
-
-All other steps are the same.
-
----
-
-## After generation
-
-After the LLM produces the fragment:
-
-1. Save to `docs/cms-guidelines/components/<type-slug>.md`
-   (or `collections/` or `externals/` as appropriate).
-2. Run validation (Step 5.3 prompt).
-3. If validation passes, run merge: `pnpm run cms-guidelines:merge`
-4. Commit both files.
-
----
-
-## Cursor agent task prompt
-
-```
-Generate the CMS guideline fragment for <COMPONENT_TYPE>.
-
-Files to read:
-- src/project/components/<TypeName>.tsx (or collections/<TypeName>.tsx)
-- generated/cms-discovery/field-list.json
-- generated/cms-discovery/theme-context.md (palette + typography + grid — use for all colour and font references)
-- generated/cms-discovery/mapping.md
-- generated/cms-discovery/accepted-variants/{components|collections|externals}/<type-slug>.json
-- docs/cms-guidelines/screenshots/index.json (to know which screenshots exist)
-- .contentful-cms.json (to get devBaseUrl for screenshot links)
-- src/lib/SizingInformation.ts
-- src/framework/Section.tsx
-- tmp/component-guidelines-target-format.md (example format)
-
-Images to analyse:
-- docs/cms-guidelines/screenshots/<type-slug>-*.png (all accepted variant screenshots)
-
-Follow the three-step generation process in generation-prompt.md:
-1. Describe screenshots.
-2. Extract behaviour from code.
-3. Merge into guideline fragment (include ## Screenshots section with image links using devBaseUrl).
-
-Save the output to docs/cms-guidelines/components/<type-slug>.md.
-Then run: pnpm run cms-guidelines:merge
-Then commit: git add docs/cms-guidelines/ && git commit -m "chore(bl): generate guideline for <TypeName>"
-```

package/skills/cms-guidelines/html-component-authoring.md

@@ -1,401 +0,0 @@
----
-name: html-component-authoring
-description: Guidelines for authoring HTML content in HtmlComponent CMS entries. Covers how to use the project style guide, what classes to use, field semantics, and common layout patterns.
-license: Private
-metadata:
-  author: se-core-product
-  version: "1.1.0"
----
-
-# HtmlComponent Authoring Guide
-
-`HtmlComponent` is a CMS content type that renders developer-authored HTML directly into the page. It bypasses the standard component registration system and is intended for one-off or highly custom layouts that the structured component library cannot produce.
-
----
-
-## Before You Start
-
-**Read the project style guide.** Every app has an auto-generated HTML Component Style Guide at:
-
-```
-docs/cms-guidelines/html-component-style-guide.md
-```
-
-This file contains the exact colour names, typography class names, grid configuration, confirmed-safe Tailwind utilities, and custom utilities available for that specific project. It is derived from `tailwind.config.json`, `globals.css`, and the compiled source files — always consult it before writing any HTML.
-
-If the file does not exist, generate it first:
-
-```bash
-# From the app directory:
-pnpm cms-generate-html-style-guide
-```
-
-**Ensure the rawHtml safelist is active.** The style guide generator also writes `src/generated/cms-rawhtml-safelist.css` containing `@source inline(...)` directives that force common spacing utilities into the compiled CSS bundle. This file must be imported once in `src/app/globals.css`:
-
-```css
-/* Add this line near the top of globals.css */
-@import "../generated/cms-rawhtml-safelist.css";
-```
-
-Without this import the safelist has no effect and the spacing classes in the Confirmed Safe list may not be compiled.
-
-**Keep your working files in the project directory.** Write your `component.html`, `component.css`, and `component.js` files to a persistent location such as `/home/nick/test/cmsedit/<page-name>/` — not to `/tmp`. Files in `/tmp` are lost between sessions and cannot be reviewed or version-controlled.
-
----
-
-## HtmlComponent Fields
-
-| Field | Required | Type | Purpose |
-|-------|----------|------|---------|
-| `cmsLabel` | ✓ | Text | Internal label. **Set this immediately after creating the entry** — use a descriptive value like `"meridian-pricing-grid"` or `"demo-hero"`. The Contentful UI shows only this name; defaults like "New Hero" are useless at scale. |
-| `rawHtml` | ✓ | Text | The HTML markup. Use Tailwind classes; never inline `style=` for colours/typography/layout. |
-| `customCss` | — | Text | Scoped CSS. Rules are automatically prefixed with `[data-hc-id="<id>"]` — they cannot pollute other components. Use for responsive layout (`@media` queries), `:hover`, `::before`/`::after`, and any utility class not in the confirmed-safe list. |
-| `customJs` | — | Text | JavaScript loaded via Next.js `<Script>`. A `hcRoot` variable pointing to this component's root element is automatically injected — use it to scope all queries. Use sparingly. |
-| `markdownContent` | — | Text | Plain text for search indexing. **Always fill this** so the component appears in site search. |
-| `isHero` | — | Boolean | `true` if the HTML contains an `<h1>`. Moves this block to the top of the page content flow. |
-| `fullWidth` | — | Boolean | `true` for edge-to-edge (full-bleed) layouts that break out of the column grid. |
-| `excludeFromSearch` | — | Boolean | `true` to exclude from search even if `markdownContent` is set. |
-| `loadScriptOnce` | — | Boolean | `true` (default) to deduplicate the script tag when the same entry appears multiple times. |
-| `scriptStrategy` | — | Enum | `afterInteractive` (default), `lazyOnload`, `beforeInteractive`. |
-
----
-
-## The Four Non-Negotiable Rules
-
-1. **Use Tailwind classes, not inline styles.**
-   - ❌ `style="color: #FF5C00; font-size: 48px;"`
-   - ✓ `class="text-orange h2"`
-
-2. **Use named colour classes from the palette.**
-   - ❌ `class="bg-[#1F2E32]"` or `style="background: #1F2E32"`
-   - ✓ `class="bg-dark text-light"`
-
-3. **Use typography classes, not raw font sizes.**
-   - ❌ `class="text-[48px] font-semibold"`
-   - ✓ `class="h2"`
-
-4. **Use the two-layer grid structure.** Every section needs an outer `container-cols-grid` wrapper (for page margins) and an inner `content-cols-grid` wrapper (for the 12-column content grid). See [Grid & Layout](#grid--layout).
-
----
-
-## Colour Usage
-
-All colour names are defined in the style guide. Use lowercase in Tailwind:
-
-```
-Dark    → bg-dark / text-dark / border-dark
-Light   → bg-light / text-light / border-light
-Orange  → bg-orange / text-orange
-Blue    → bg-blue / text-blue
-```
-
-For dark backgrounds, pair with the contrast colour (`bg-dark text-light`). Check the "Contrast pair" column in the style guide to know which pairings are approved.
-
----
-
-## Typography Usage
-
-Pick from the named type styles in the style guide. Apply directly to the element:
-
-```html
-<h1 class="h1">Large display heading (uppercase, 96–200px)</h1>
-<h2 class="h2">Section heading (45–48px)</h2>
-<h3 class="h3">Sub-heading (21–44px, uppercase)</h3>
-<p class="p1">Large body (20–24px)</p>
-<p class="p2">Standard body (16px)</p>
-<p class="p3">Small body (13px)</p>
-```
-
-**For rich text blocks** (content rendered from Markdown or the CMS), wrap in an RTF class:
-
-```html
-<div class="rtf-standard">
-  <h2>Auto-styled heading</h2>
-  <p>Auto-styled paragraph with list and link support.</p>
-</div>
-```
-
-Available RTF classes: `rtf-standard`, `rtf-article`, `rtf-article-right`, `rtf-legal`, `rtf-embedded-entry`.
-
----
-
-## Grid & Layout
-
-Every `HtmlComponent` section uses a **two-layer grid structure**. Without the outer layer, content has no page margins and elements stretch edge-to-edge.
-
-```html
-<!-- Required boilerplate for every section -->
-<div class="w-full container-cols-grid container-rows-grid container-row-6-12 bg-dark text-light">
-  <div class="col-start-2 col-span-1 row-start-2 row-span-4 content-cols-grid">
-    <!-- col-span-* / laptop:col-start-* content here -->
-  </div>
-</div>
-```
-
-**How the layers work:**
-
-| Layer | Classes | Role |
-|-------|---------|------|
-| Outer | `container-cols-grid` | 3-column grid: `[margin \| content \| margin]`. Background colour and edge-to-edge visuals go here. |
-| Outer | `container-rows-grid container-row-6-12` | Adds vertical spacing rows. Replace `container-row-6-12` with the spacing value you need (see table below). |
-| Inner | `col-start-2 col-span-1` | Places the inner div in the centre content column (skips the margin columns). |
-| Inner | `row-start-2 row-span-4` | Places the inner div in the content rows (skips the spacing rows). |
-| Inner | `content-cols-grid` | Creates the 12-column content grid. `col-span-*` / `laptop:col-start-*` work inside here. |
-
-### Vertical spacing values
-
-Use `container-row-6-*` classes for bottom spacing. The values below all appear in the project's compiled source files and are guaranteed to be in the CSS bundle (confirmed via Tailwind JIT source scan).
-
-| Class | Bottom space | Use for |
-|-------|-------------|---------|
-| `container-row-6-6` | 24px | Tight spacing |
-| `container-row-6-8` | 32px | |
-| `container-row-6-10` | 40px | |
-| `container-row-6-12` | 48px | **Standard default** |
-| `container-row-6-20` | 80px | Generous spacing |
-| `container-row-6-24` | 96px | Hero / large sections |
-
-For top spacing, source-confirmed values are `container-row-1-10` (40px), `container-row-1-24` (96px), `container-row-1-40` (160px).
-
-> All values in the tables above appear in the project's source files and are compiled by Tailwind JIT. If you need a value not listed, use `padding-top` / `padding-bottom` in `customCss` instead — do not guess at unlisted `container-row-*` values as they may not be compiled.
-
-### Column spans (inside the inner div)
-
-| Use | Classes |
-|-----|---------|
-| Full width | `col-span-full` |
-| Centered (one column margin each side) | `laptop:col-start-2 laptop:col-span-10` |
-| Left half (text) | `laptop:col-start-2 laptop:col-span-4` |
-| Right half (visual) | `laptop:col-start-7 laptop:col-span-5` |
-
-For **full-bleed** content (background extends edge to edge), set `fullWidth: true` on the entry instead of using the two-layer structure. The outer grid is removed and you control the full viewport width.
-
----
-
-## Breakpoints
-
-All breakpoints are mobile-first. Use prefixes to override at larger sizes:
-
-| Prefix | Min-width |
-|--------|-----------|
-| *(none)* | 0px (mobile default) |
-| `tablet:` | 768px |
-| `laptop:` | 1024px |
-| `desktop:` | 1440px |
-
----
-
-## Tailwind JIT Constraint
-
-> **Critical — read before writing any classes.**
-
-Tailwind only includes CSS for classes it finds in compiled source files (`.tsx`, `.ts`, `.css`). Classes written inside `rawHtml` CMS strings are **never scanned** — if a class isn't already used somewhere in the codebase, it silently has no effect.
-
-**Rule: only use `tablet:` / `laptop:` prefixes that appear in the project style guide's Confirmed Safe Tailwind Utilities section** — they are proven to be in the compiled bundle. For any responsive behaviour not listed there, use `customCss` with `@media` queries instead.
-
-For non-responsive utility classes, check the **Confirmed Safe Tailwind Utilities** section in the project style guide (`docs/cms-guidelines/html-component-style-guide.md`). These are extracted from the compiled source and are guaranteed to work. If a class isn't listed, use `customCss`.
-
----
-
-## Scoped CSS (`customCss`)
-
-Use `customCss` for:
-- **Responsive layout** — `@media` queries for flex direction, grid column counts, show/hide (see Tailwind JIT constraint above)
-- Complex `:hover`, `::before`/`::after` interactions impossible with Tailwind
-- Any utility class not in the project's confirmed-safe list
-
-Rules are automatically scoped to this entry's `data-hc-id` attribute — write selectors relative to the component root:
-
-```css
-/* Responsive layout — use @media instead of tablet:/laptop: in rawHtml */
-@media (min-width: 768px) {
-  .my-grid { display: grid; grid-template-columns: repeat(3, 1fr); gap: 24px; }
-}
-@media (min-width: 1024px) {
-  .my-card { flex-direction: row; }
-}
-
-/* Hover and pseudo-elements */
-.my-card:hover {
-  transform: translateY(-4px);
-  transition: transform 0.2s ease;
-}
-```
-
-Never redeclare colours or typography in `customCss` — those already exist as Tailwind classes.
-
----
-
-## Custom JavaScript (`customJs`)
-
-The renderer automatically injects a `hcRoot` variable pointing to this component's own `[data-hc-id]` element before your script runs. **Always use `hcRoot` as the root for DOM queries** — never `document.querySelector('[data-hc-id]')`, which matches the first component on the page, not this one.
-
-```js
-// ✓ Correct — hcRoot is scoped to this component automatically
-var btns = hcRoot.querySelectorAll('.my-btn');
-btns.forEach(function (btn) {
-  btn.addEventListener('click', function () {
-    // toggle state…
-  });
-});
-
-// ✗ Wrong — querySelector matches the FIRST [data-hc-id] on the page
-var section = document.querySelector('[data-hc-id]');
-```
-
-**Rules:**
-- Use `hcRoot.querySelector` / `hcRoot.querySelectorAll` for all DOM lookups.
-- Keep scripts small and self-contained — no module imports, no global state.
-- Avoid `document.getElementById` unless the ID is guaranteed unique across the whole page.
-- Default `scriptStrategy` is `afterInteractive` — runs after page hydration. Use `lazyOnload` for non-critical third-party widgets.
-
----
-
-## Common Patterns
-
-All patterns use the mandatory two-layer grid structure.
-
-### Centered text block
-
-```html
-<div class="w-full container-cols-grid container-rows-grid container-row-6-12">
-  <div class="col-start-2 col-span-1 row-start-2 row-span-4 content-cols-grid">
-    <div class="col-span-full laptop:col-start-2 laptop:col-span-10 flex flex-col gap-6">
-      <h2 class="h2">Section Heading</h2>
-      <div class="rtf-standard">
-        <p>Body copy goes here.</p>
-      </div>
-    </div>
-  </div>
-</div>
-```
-
-### Two-column (text + image)
-
-```html
-<div class="w-full container-cols-grid container-rows-grid container-row-6-12">
-  <div class="col-start-2 col-span-1 row-start-2 row-span-4 content-cols-grid">
-    <div class="col-span-full laptop:col-start-2 laptop:col-span-4 flex flex-col gap-6">
-      <h2 class="h2">Heading</h2>
-      <p class="p1">Supporting description.</p>
-    </div>
-    <div class="col-span-full laptop:col-start-7 laptop:col-span-5">
-      <img src="..." alt="..." class="w-full rounded-lg" />
-    </div>
-  </div>
-</div>
-```
-
-Note: the two columns stack on mobile by default. To flip to side-by-side on tablet, use `customCss`:
-```css
-@media (min-width: 768px) {
-  /* If you need column layout earlier than laptop, use customCss @media */
-}
-```
-
-### Coloured card
-
-```html
-<div class="w-full container-cols-grid container-rows-grid container-row-6-12">
-  <div class="col-start-2 col-span-1 row-start-2 row-span-4 content-cols-grid">
-    <div class="col-span-full laptop:col-start-2 laptop:col-span-10">
-      <div class="bg-orange text-dark p-8 rounded-lg flex flex-col gap-4">
-        <h3 class="h3">Card Title</h3>
-        <p class="p2">Supporting text.</p>
-      </div>
-    </div>
-  </div>
-</div>
-```
-
-### Hero (set `isHero: true`, `fullWidth: true`)
-
-With `fullWidth: true` the outer grid is removed — you control the full viewport width directly:
-
-```html
-<!-- fullWidth: true → no outer grid, you own the full width -->
-<div class="bg-dark text-light w-full">
-  <div class="content-cols-grid py-16">
-    <div class="col-span-full laptop:col-start-2 laptop:col-span-10 flex flex-col gap-8">
-      <h1 class="h1">Hero Heading</h1>
-      <p class="p1">Subtitle or intro text.</p>
-    </div>
-  </div>
-</div>
-```
-
----
-
-## Images
-
-**Do not hardcode Contentful CDN URLs in `rawHtml`.** If the asset is deleted or re-uploaded, the image silently breaks and the CMS has no record of the dependency.
-
-For images in `rawHtml`, use a plain `<img>` tag with Contentful's image transformation API for basic optimisation:
-
-```html
-<img
-  src="https://images.ctfassets.net/…/image.jpg?w=800&fm=webp&fit=fill"
-  srcset="
-    https://images.ctfassets.net/…/image.jpg?w=400&fm=webp&fit=fill 400w,
-    https://images.ctfassets.net/…/image.jpg?w=800&fm=webp&fit=fill 800w,
-    https://images.ctfassets.net/…/image.jpg?w=1200&fm=webp&fit=fill 1200w
-  "
-  sizes="(max-width: 768px) 100vw, 50vw"
-  alt="Descriptive alt text"
-  class="w-full rounded-lg"
-  loading="lazy"
-/>
-```
-
-**Trade-off:** A plain `<img>` does not use Next.js `<Image>` optimisation (no automatic WebP conversion, no LQIP placeholder, no automatic `srcset`). The Contentful image API partially compensates — append `?fm=webp` to serve WebP, `?w=N` to resize, and `?fit=fill` to crop. Always add `loading="lazy"` manually.
-
-**Rules:**
-- Always include a descriptive `alt` attribute. Decorative images use `alt=""`.
-- Prefer managing images via a CMS asset field where possible — that creates a tracked dependency. Use `rawHtml` images only for layout-specific embedding that can't be achieved via component fields.
-
----
-
-## Iteration Expectation
-
-**Authoring `rawHtml` without live preview requires iteration.** Expect 4–8 rounds of save → screenshot → fix for a multi-section page. This is normal, not a sign of failure. Approach each round with a focus:
-
-1. **Structure** — does the two-layer grid produce correct page margins?
-2. **Spacing** — are sections spaced correctly vertically?
-3. **Responsive** — do cards/columns lay out correctly at tablet and laptop widths?
-4. **Interactions** — if there's JavaScript, does it work correctly?
-
----
-
-## Checklist Before Saving
-
-> **Visual verification is mandatory**, not optional. Tailwind JIT failures and grid structure issues are invisible without a rendered view. Take a screenshot and check before marking done.
-
-- [ ] `cmsLabel` is set to a descriptive, unique value (not the default "New Hero" etc.)
-- [ ] `rawHtml` uses only confirmed-safe Tailwind classes — no inline `style=` for colours/typography/layout
-- [ ] All colour references use named classes (`text-dark`, `bg-orange`), not hex values
-- [ ] Typography uses named classes (`h2`, `p1`), not raw `text-[Npx]`
-- [ ] Content uses the two-layer grid structure (`container-cols-grid` outer + `content-cols-grid` inner)
-- [ ] Responsive layout not covered by the Confirmed Safe list uses `customCss` with `@media` queries (not raw `tablet:` / `laptop:` prefixes in `rawHtml`)
-- [ ] Any Tailwind utility class not in the confirmed-safe list uses `customCss` instead
-- [ ] `markdownContent` is filled with the plain-text equivalent for search indexing
-- [ ] `isHero: true` if the HTML contains an `<h1>`
-- [ ] `fullWidth: true` if the design needs an edge-to-edge background
-- [ ] **Took a screenshot and reviewed the render — no layout bugs visible**
-- [ ] **If interactive: tested the interaction in browser (toggles, tabs, JS)**
-- [ ] Source files (`component.html`, `component.css`, `component.js`) saved to project directory, not `/tmp`
-
----
-
-## Generating and Updating the Style Guide
-
-The style guide is auto-generated and should be regenerated whenever the design system changes:
-
-```bash
-# From the app directory:
-pnpm cms-generate-html-style-guide
-
-# Then re-merge to include it in COMPONENT_GUIDELINES_FOR_LLM.md:
-pnpm cms-guidelines:merge
-```
-
-The style guide is also regenerated automatically as part of the `update-cms-guidelines` workflow (Step 3 in `fresh` mode, or any time you run a merge step).