@se-studio/project-build 1.0.131 → 1.0.133

package/skills/contentful-cms/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).

package/skills/contentful-cms/cms-guidelines/validation-prompt.md

@@ -1,170 +0,0 @@
-# Validation Prompt — Guideline vs Code
-
-**Step 5.3 — LLM validation of a guideline fragment against the component source.**
-
-Run as part of the generation pipeline (not CI). Heavy validation that checks completeness
-and consistency before committing. It is acceptable for this to take time — correctness is
-the priority.
-
----
-
-## When to run
-
-After Step 5.1 (generation) produces a guideline fragment, before committing. Feed the
-fragment and the component source to this prompt.
-
----
-
-## Prompt
-
-```
-You are validating a CMS component guideline fragment for accuracy and completeness.
-
-You will be given:
-1. The guideline fragment (markdown).
-2. The component source file (TypeScript/React).
-3. Supporting files: SizingInformation.ts, Section.tsx, mapping.md.
-
-Your task: systematically check whether the guideline is COMPLETE and CONSISTENT with
-the code. Produce a detailed report.
-
-Guideline fragment:
-<GUIDELINE_MARKDOWN>
-
-Component source:
-<COMPONENT_SOURCE>
-
-SizingInformation.ts:
-<SIZING_SOURCE>
-
-Section.tsx:
-<SECTION_SOURCE>
-
-mapping.md (CMS field → app prop mapping):
-<MAPPING_SOURCE>
-
----
-
-Check the following and report each as PASS, FAIL, or N/A:
-
-1. FIELDS COVERAGE
-   - Are all fields in USED_FIELDS mentioned in the "Used fields" table?
-   - Are any fields mentioned in the table that are NOT in USED_FIELDS?
-
-2. FIELD DESCRIPTIONS
-   - For each field in the table: is the "Effect when set" accurate?
-   - For each field in the table: is the "Effect when empty/removed" accurate?
-   - Are any effects described that do not match the code?
-
-3. TYPOGRAPHY
-   - Does the guideline state the correct typography class for each element?
-     (e.g. heading = h4, body = p3)
-   - Does it correctly describe which HTML element the heading renders as
-     based on index (h1 for first, h2 for later)?
-
-4. COLOUR BEHAVIOUR
-   - Does the guideline correctly describe how backgroundColour and textColour are applied
-     (section-wide, card-level, or neither)?
-   - Are the valid enum values for backgroundColour and textColour correct?
-
-5. POSITION/INDEX BEHAVIOUR
-   - If the component uses getSizingInformation(index), does the guideline describe:
-     (a) the heading level change (h1 vs h2)?
-     (b) the spacing/padding change?
-
-6. VARIANT DIFFERENCES
-   - If there are multiple registered variants (e.g. Hero and Hero Flipped), are they
-     all described, and are the differences accurately stated?
-
-7. IMPACT SECTION
-   - Does the "Impact of content changes" section describe what happens when:
-     (a) important optional fields are added?
-     (b) important optional fields are removed?
-   - Are there missing impact scenarios that would be confusing to a user?
-
-8. NO CODE REFERENCES
-   - Does the guideline contain any file path references (e.g. "Hero.tsx", "Section.tsx")?
-   - Does it contain any code beyond typography class names and colour names?
-
-9. COMPLETENESS
-   - Is there anything important in the code that the guideline does NOT mention and SHOULD?
-   - List any missing items.
-
----
-
-Output format:
-
-## Validation Report — <ComponentType>
-
-### Summary
-PASS / FAIL / PARTIAL — one sentence overall verdict.
-
-### Checks
-
-| Check | Result | Detail |
-|---|---|---|
-| Fields coverage | PASS | All 10 used fields are in the table. |
-| Field descriptions | FAIL | `visual` empty description says "copy-only" but should say "copy spans full width". |
-| Typography | PASS | Heading h4, body p3 — correct. |
-| Colour behaviour | PASS | Section-wide application described correctly. |
-| Position/index | PASS | h1/h2 and padding described. |
-| Variant differences | PASS | Hero Flipped column order described. |
-| Impact section | PARTIAL | Removing preHeading described; removing body not described. |
-| No code references | PASS | No file paths or raw code. |
-| Completeness | PARTIAL | Animation behaviour (animate-when-seen) not mentioned. |
-
-### Issues to fix
-
-List each FAIL and PARTIAL item with a specific fix instruction:
-- **Field: visual empty description** — change to: "Copy spans full section width on all breakpoints."
-- **Impact: removing body** — add row: "Remove body → body block disappears; links follow directly after heading/subtitle."
-- **Completeness: animation** — add to Behaviour section: "All text elements animate in when they scroll into view."
-
-### Verdict
-
-APPROVED — The guideline is complete and consistent. Minor fixes applied.
-OR
-NEEDS REVISION — Fix issues above before committing.
-```
-
----
-
-## Acceptance criteria
-
-**Approved if:**
-- Fields coverage = PASS
-- Typography = PASS
-- Colour behaviour = PASS
-- No code references = PASS
-- No more than 2 PARTIAL items (and they are minor)
-
-**Needs revision if:**
-- Any FAIL item
-- More than 2 PARTIAL items
-
-When revision is needed: apply the specific fixes from the "Issues to fix" list and re-run
-validation. Repeat until approved.
-
----
-
-## Cursor agent task prompt
-
-```
-Validate the CMS guideline fragment for <COMPONENT_TYPE>.
-
-Files to read:
-- docs/cms-guidelines/components/<type-slug>.md (the guideline to validate)
-- src/project/components/<TypeName>.tsx (source of truth)
-- src/lib/SizingInformation.ts
-- src/framework/Section.tsx
-- generated/cms-discovery/mapping.md
-
-Follow the validation prompt in validation-prompt.md.
-Produce a validation report.
-
-If APPROVED: proceed to merge.
-If NEEDS REVISION: apply the specific fixes to docs/cms-guidelines/components/<type-slug>.md,
-then re-validate (run this task again with the updated fragment).
-When approved, run: pnpm run cms-guidelines:merge
-Then commit both files.
-```