@se-studio/project-build 1.0.118 → 1.0.120

package/dist/cms-generate-html-style-guide.js

@@ -0,0 +1,1006 @@
+#!/usr/bin/env node
+/** biome-ignore-all lint/suspicious/noConsole: Console output is intentional in CLI */
+/**
+ * cms-generate-html-style-guide
+ *
+ * Generates a comprehensive HTML authoring style guide for HtmlComponent entries.
+ * Reads the project's design tokens from tailwind.config.json and globals.css and
+ * produces a self-contained markdown reference document.
+ *
+ * Usage:
+ *   cms-generate-html-style-guide [--app-dir <path>]
+ *
+ * Output:
+ *   <app-dir>/docs/cms-guidelines/html-component-style-guide.md
+ *
+ * The output file is picked up automatically by cms-merge-guidelines and included
+ * as the "Design System Reference" preamble in COMPONENT_GUIDELINES_FOR_LLM.md.
+ *
+ * Run this whenever tailwind.config.json or globals.css changes, or as part of
+ * the update-cms-guidelines workflow.
+ */
+import { existsSync, mkdirSync, readdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
+import { basename, join } from 'node:path';
+import { loadTailwindConfig } from './loadTailwindConfig.js';
+// ---------------------------------------------------------------------------
+// CLI parsing
+// ---------------------------------------------------------------------------
+function parseAppDir() {
+    const args = process.argv.slice(2);
+    const idx = args.indexOf('--app-dir');
+    return idx !== -1 && args[idx + 1] ? args[idx + 1] : process.cwd();
+}
+// ---------------------------------------------------------------------------
+// CSS parsing helpers
+// ---------------------------------------------------------------------------
+/**
+ * Extracts all @utility names from a globals.css string.
+ * Returns a list of { name, body } where body is the raw CSS inside the braces.
+ */
+function extractUtilities(css) {
+    const results = [];
+    // Match @utility <name> { ... } — handle nested braces via depth counting
+    const utilityRe = /@utility\s+([\w-]+)\s*\{/g;
+    let match = utilityRe.exec(css);
+    while (match !== null) {
+        const name = match[1];
+        const start = utilityRe.lastIndex;
+        let depth = 1;
+        let i = start;
+        while (i < css.length && depth > 0) {
+            if (css[i] === '{')
+                depth++;
+            else if (css[i] === '}')
+                depth--;
+            i++;
+        }
+        const body = css.slice(start, i - 1).trim();
+        results.push({ name, body });
+        match = utilityRe.exec(css);
+    }
+    return results;
+}
+/**
+ * Extracts .rtf-* class names present in the CSS.
+ */
+function extractRtfClasses(css) {
+    const names = new Set();
+    const rtfRe = /\.(rtf-[\w-]+)/g;
+    let m = rtfRe.exec(css);
+    while (m !== null) {
+        names.add(m[1]);
+        m = rtfRe.exec(css);
+    }
+    return [...names].sort();
+}
+/**
+ * Extracts CSS custom property declarations from :root blocks.
+ */
+function extractRootVars(css) {
+    const results = [];
+    // Find :root { ... } blocks
+    const rootRe = /:root\s*\{([^}]+)\}/g;
+    let m = rootRe.exec(css);
+    while (m !== null) {
+        const block = m[1];
+        const varRe = /--([\w-]+)\s*:\s*([^;]+);/g;
+        let v = varRe.exec(block);
+        while (v !== null) {
+            results.push({ name: `--${v[1]}`, value: v[2].trim() });
+            v = varRe.exec(block);
+        }
+        m = rootRe.exec(css);
+    }
+    return results;
+}
+function resolveSizePx(value) {
+    if (typeof value === 'number')
+        return value;
+    if (value !== null && typeof value === 'object') {
+        const v = value;
+        if (typeof v['sizePixels'] === 'number')
+            return v['sizePixels'];
+    }
+    return null;
+}
+function buildBreakpointsSection(config) {
+    const sizes = config.sizes ?? {};
+    const lines = ['## Breakpoints', ''];
+    lines.push('All breakpoints are **mobile-first**. Default styles apply to all sizes; use prefixes to override at larger breakpoints.');
+    lines.push('');
+    lines.push('| Prefix | Min-width | Columns |');
+    lines.push('|--------|-----------|---------|');
+    lines.push(`| *(none)* | 0px (mobile) | ${sizes['mobile']?.cols ?? '—'} |`);
+    for (const [name, s] of Object.entries(sizes)) {
+        if (name === 'mobile' || s.breakpoint === undefined)
+            continue;
+        lines.push(`| \`${name}:\` | ${s.breakpoint}px | ${s.cols ?? '—'} |`);
+    }
+    lines.push('');
+    lines.push('```html');
+    lines.push('<!-- Example: stacked on mobile, side-by-side on laptop -->');
+    lines.push('<div class="flex flex-col laptop:flex-row gap-6">...</div>');
+    lines.push('```');
+    return lines.join('\n');
+}
+function buildColourSection(config) {
+    const colorOptions = config.colorOptions ?? {};
+    const gradients = config.gradients ?? {};
+    const foregroundColors = new Set(config.foregroundColors ?? []);
+    const colorOpposites = config.colorOpposites ?? {};
+    const lines = ['## Colour Palette', ''];
+    lines.push('Use **lowercase** colour names in Tailwind classes (e.g. colour `Dark` → class `text-dark`).');
+    lines.push('');
+    if (Object.keys(colorOptions).length > 0) {
+        lines.push('| Name | Hex | `bg-*` class | `text-*` class | `border-*` class | Contrast pair |');
+        lines.push('|------|-----|-------------|----------------|-----------------|---------------|');
+        for (const [name, hex] of Object.entries(colorOptions)) {
+            const lc = name.toLowerCase();
+            const opposite = colorOpposites[name] ?? '—';
+            const foreground = foregroundColors.has(name) ? '*(text colour)*' : '';
+            lines.push(`| **${name}** ${foreground} | \`${hex}\` | \`bg-${lc}\` | \`text-${lc}\` | \`border-${lc}\` | ${opposite} |`);
+        }
+    }
+    if (Object.keys(gradients).length > 0) {
+        lines.push('');
+        lines.push('**Gradients:**');
+        lines.push('');
+        lines.push('| Name | Value | `bg-*` class |');
+        lines.push('|------|-------|-------------|');
+        for (const [name, value] of Object.entries(gradients)) {
+            const lc = name.toLowerCase();
+            lines.push(`| ${name} | \`${value}\` | \`bg-${lc}\` |`);
+        }
+    }
+    lines.push('');
+    lines.push('**Rules:**');
+    lines.push('- Never use hardcoded hex values. Always use the named classes above.');
+    lines.push('- For body copy on a dark background use the contrast pair (e.g. `bg-dark text-light`).');
+    lines.push('- Accent colours (Orange, Blue, Yellow) work as backgrounds and highlights.');
+    return lines.join('\n');
+}
+function buildTypographySection(config) {
+    const fontTable = config.fontTable;
+    const styles = fontTable?.styles;
+    if (!styles || Object.keys(styles).length === 0) {
+        return '## Typography\n\nNo typography styles defined in tailwind.config.json.';
+    }
+    // After the guard above, styles is guaranteed defined. Alias for closure access.
+    const definedStyles = styles;
+    const baseFont = fontTable?.font ?? 'sans-serif';
+    const baseWeight = fontTable?.weight ?? 400;
+    const lines = ['## Typography', ''];
+    lines.push(`Base font: **${baseFont}** | Base weight: **${baseWeight}**`);
+    lines.push('');
+    lines.push('Use the class name directly on any HTML element — the class controls font-size, weight, line-height, and letter-spacing across breakpoints.');
+    lines.push('');
+    // Categorise by approximate usage
+    const displayClasses = [];
+    const headingClasses = [];
+    const bodyClasses = [];
+    const specialClasses = [];
+    for (const name of Object.keys(styles)) {
+        if (name.startsWith('h1'))
+            displayClasses.push(name);
+        else if (name.startsWith('h2') || name.startsWith('h3') || name.startsWith('h4'))
+            headingClasses.push(name);
+        else if (name.startsWith('p'))
+            bodyClasses.push(name);
+        else
+            specialClasses.push(name);
+    }
+    function buildTypographyTable(names) {
+        const rows = [
+            '| Class | Mobile | Tablet | Laptop | Desktop | Weight | Notes |',
+            '|-------|--------|--------|--------|---------|--------|-------|',
+        ];
+        for (const name of names) {
+            const e = definedStyles[name];
+            const defaultPx = resolveSizePx(e['default']);
+            const tabletPx = resolveSizePx(e['tablet']);
+            const laptopVal = e['laptop'];
+            const laptopPx = laptopVal !== undefined ? resolveSizePx(laptopVal) : null;
+            const desktopVal = e['desktop'];
+            const desktopPx = desktopVal !== undefined ? resolveSizePx(desktopVal) : null;
+            const weight = typeof e['weight'] === 'number' ? e['weight'] : (baseWeight ?? '—');
+            const additional = e['additional'];
+            const notes = [];
+            if (additional?.['text-transform'] === 'uppercase')
+                notes.push('UPPERCASE');
+            if (typeof e['letterSpacing'] === 'number' && e['letterSpacing'] !== 0)
+                notes.push(`tracking ${e['letterSpacing']}px`);
+            rows.push(`| \`${name}\` | ${defaultPx !== null ? `${defaultPx}px` : '—'} | ${tabletPx !== null ? `${tabletPx}px` : '—'} | ${laptopPx !== null ? `${laptopPx}px` : '—'} | ${desktopPx !== null ? `${desktopPx}px` : '—'} | ${weight} | ${notes.join(', ')} |`);
+        }
+        return rows.join('\n');
+    }
+    if (displayClasses.length > 0) {
+        lines.push('### Display Headings');
+        lines.push('');
+        lines.push(buildTypographyTable(displayClasses));
+        lines.push('');
+    }
+    if (headingClasses.length > 0) {
+        lines.push('### Section & Sub-Headings');
+        lines.push('');
+        lines.push(buildTypographyTable(headingClasses));
+        lines.push('');
+    }
+    if (bodyClasses.length > 0) {
+        lines.push('### Body Text');
+        lines.push('');
+        lines.push(buildTypographyTable(bodyClasses));
+        lines.push('');
+    }
+    if (specialClasses.length > 0) {
+        lines.push('### Special Styles');
+        lines.push('');
+        lines.push(buildTypographyTable(specialClasses));
+        lines.push('');
+    }
+    lines.push('**Rules:**');
+    lines.push('- Apply the class directly: `<h2 class="h2">Heading</h2>`');
+    lines.push('- Never use `text-[Npx]`, `font-size`, or `font-weight` inline styles.');
+    lines.push('- For body copy, use `p1` (large) or `p2` (standard). Reserve `h*` classes for actual headings.');
+    return lines.join('\n');
+}
+function buildGridSection(config) {
+    const sizes = config.sizes ?? {};
+    const lines = ['## Grid & Layout', ''];
+    lines.push('Content is placed on a CSS grid. The grid column count changes per breakpoint; gaps and margins are fixed.');
+    lines.push('');
+    lines.push('| Breakpoint | Columns | Gap | Margin |');
+    lines.push('|------------|---------|-----|--------|');
+    for (const [name, s] of Object.entries(sizes)) {
+        const bp = s.breakpoint !== undefined ? `${s.breakpoint}px` : 'default';
+        const cols = s.cols !== undefined ? String(s.cols) : '—';
+        const gap = s.gap !== undefined ? `${s.gap}px` : '—';
+        const margin = s.margin !== undefined ? `${s.margin}px` : '—';
+        lines.push(`| ${name} (${bp}) | ${cols} | ${gap} | ${margin} |`);
+    }
+    lines.push('');
+    lines.push('### Grid Container Classes');
+    lines.push('');
+    lines.push('The author is responsible for adding both grid layers. Without them, content has no page margins');
+    lines.push('and stretches edge-to-edge. **Outer layer** classes go on the section wrapper; **inner layer** classes');
+    lines.push('go on the div that receives `content-cols-grid`. Content spans go inside the inner layer.');
+    lines.push('');
+    lines.push('| Class | Layer | Description |');
+    lines.push('|-------|-------|-------------|');
+    lines.push('| `container-cols-grid` | Outer | 3-column grid: `[margin \\| content \\| margin]`. Background colour goes here. |');
+    lines.push('| `container-rows-grid` | Outer | Adds vertical spacing rows. Required when using `container-row-*`. |');
+    lines.push('| `container-row-6-12` | Outer | Vertical spacing (48px bottom — standard default). Replace with desired value. |');
+    lines.push('| `col-start-2 col-span-1` | Inner | Places inner div in the content column (skips margin columns). |');
+    lines.push('| `row-start-2 row-span-4` | Inner | Places inner div in the content rows (skips spacing rows). |');
+    lines.push('| `content-cols-grid` | Inner | Creates the 12-column content grid inside the inner div. |');
+    lines.push('| `col-span-full` | Content | Full width (all 12 columns) |');
+    lines.push('| `laptop:col-start-2 laptop:col-span-10` | Content | Centered with one-column margin each side (laptop+) |');
+    lines.push('| `laptop:col-start-2 laptop:col-span-4` | Content | Left column (text side in two-column layout) |');
+    lines.push('| `laptop:col-start-7 laptop:col-span-5` | Content | Right column (visual side in two-column layout) |');
+    lines.push('| `laptop:col-start-2 laptop:col-span-5` | Content | Narrow left half |');
+    lines.push('| `laptop:col-start-7 laptop:col-span-6` | Content | Wide right half |');
+    lines.push('');
+    lines.push('### Layout Notes');
+    lines.push('');
+    lines.push('- On mobile, all content columns are `col-span-full` by default.');
+    lines.push('- For edge-to-edge (full-bleed) content, set `fullWidth: true` on the HtmlComponent entry — the outer grid is removed and you control the full viewport width.');
+    return lines.join('\n');
+}
+function buildSpacingSection() {
+    const lines = ['## Spacing Conventions', ''];
+    lines.push('Use Tailwind spacing utilities. Multiples of 4 (the Tailwind scale) are preferred.');
+    lines.push('');
+    lines.push('| Purpose | Classes |');
+    lines.push('|---------|---------|');
+    lines.push('| Section vertical padding (large) | `py-16 laptop:py-24` |');
+    lines.push('| Section vertical padding (medium) | `py-12 laptop:py-16` |');
+    lines.push('| Section vertical padding (small) | `py-8 laptop:py-12` |');
+    lines.push('| Between stacked elements | `space-y-4 laptop:space-y-8` |');
+    lines.push('| Flex/grid gap | `gap-4 laptop:gap-8` |');
+    lines.push('| Card padding | `p-6 laptop:p-10` |');
+    lines.push('');
+    lines.push('> **Note:** HtmlComponent renders inside the Section component which already provides top/bottom padding. Avoid adding extra outer padding that doubles the section gap.');
+    lines.push('');
+    lines.push('> All classes in the table above are included in the generated `src/generated/cms-rawhtml-safelist.css`', '> and are guaranteed to be compiled once that file is imported into `globals.css`.', '> See the Confirmed Safe Tailwind Utilities section for details.');
+    return lines.join('\n');
+}
+function buildUtilitiesSection(utilities) {
+    // Filter out internal/layout utilities unlikely to be useful in raw HTML
+    const skipList = new Set([
+        'unknown-component',
+        'button',
+        'outlined-button',
+        'visual-cols',
+        'visual-width',
+        'image-item-h',
+        'row-1-pageHalf',
+        'row-6-pageHalf',
+    ]);
+    const useful = utilities.filter((u) => !skipList.has(u.name));
+    if (useful.length === 0) {
+        return '## Custom Tailwind Utilities\n\n*None defined in globals.css.*';
+    }
+    const lines = ['## Custom Tailwind Utilities', ''];
+    lines.push('These utilities are available in addition to the standard Tailwind library:');
+    lines.push('');
+    lines.push('| Class | Description |');
+    lines.push('|-------|-------------|');
+    const descriptions = {
+        'animate-ticker': 'Horizontal ticker/marquee scroll animation (20s loop)',
+        'animate-fade-in-grow': 'Fade in + scale up entrance animation (0.5s)',
+        'animate-shape-shift': 'Animated shape morphing (clip-path + rotation, 9s loop)',
+        'animate-card-rotate': 'Subtle 3D rotation on hover (0.4s)',
+        'animate-clip-reveal': 'Left-to-right clip-path reveal animation (0.6s)',
+        'film-grain': 'Adds a subtle animated film grain overlay (fixed, z-index 9998)',
+        'section-spacing': 'Standard section top/bottom padding',
+    };
+    for (const { name } of useful) {
+        const desc = descriptions[name] ?? 'Custom utility — see globals.css for details';
+        lines.push(`| \`${name}\` | ${desc} |`);
+    }
+    return lines.join('\n');
+}
+function buildRtfSection(rtfClasses) {
+    const lines = ['## Rich Text Classes', ''];
+    lines.push('Apply these classes to an element that contains HTML produced from rich text or Markdown:');
+    lines.push('');
+    const rtfDescriptions = {
+        'rtf-standard': 'Default rich text styling. Handles headings, paragraphs, lists, blockquotes, and links with standard spacing. Use for most body content.',
+        'rtf-article': 'Editorial / blog styling with wider paragraph spacing and emphasis on readability. Use for long-form articles.',
+        'rtf-article-right': 'Article styling with paragraphs pinned to the right column (laptop+). Use for editorial layouts with a wide left margin.',
+        'rtf-legal': 'Legal document styling with compact spacing. Headings map to smaller sizes (h1→h3, h2→h4, etc.). Use for terms, privacy, and compliance content.',
+    };
+    if (rtfClasses.length === 0) {
+        lines.push('*No `.rtf-*` classes found in globals.css.*');
+    }
+    else {
+        lines.push('| Class | Use when… |');
+        lines.push('|-------|-----------|');
+        for (const cls of rtfClasses) {
+            const desc = rtfDescriptions[cls] ?? 'Custom rich text variant — see globals.css for details.';
+            lines.push(`| \`${cls}\` | ${desc} |`);
+        }
+        lines.push('');
+        lines.push('```html');
+        lines.push('<div class="rtf-standard">');
+        lines.push('  <h2>Heading</h2>');
+        lines.push('  <p>Paragraph with <strong>bold</strong> and <em>italic</em>.</p>');
+        lines.push('  <ul><li>List item</li></ul>');
+        lines.push('</div>');
+        lines.push('```');
+    }
+    return lines.join('\n');
+}
+function buildFontsSection(config) {
+    const fontTable = config.fontTable;
+    const baseFont = fontTable?.font;
+    const lines = ['## Fonts', ''];
+    if (baseFont) {
+        lines.push(`The primary font is **${baseFont}**, loaded via Next.js font optimisation.`);
+        lines.push('');
+        lines.push('| Tailwind property | CSS variable |');
+        lines.push('|-------------------|--------------|');
+        lines.push('| `font-sans` | `var(--font-sans)` — use for all body and heading text |');
+        lines.push('| `font-mono` | `var(--font-mono)` — use for code snippets |');
+        lines.push('');
+        lines.push('> **Do not** reference the font family by name in CSS. Use `font-sans` or rely on the typography classes which already apply the correct font.');
+    }
+    else {
+        lines.push('Font information not available in tailwind.config.json.');
+    }
+    return lines.join('\n');
+}
+function buildPatternsSection(config) {
+    const colors = Object.keys(config.colorOptions ?? {});
+    const darkColor = colors.find((c) => c.toLowerCase() === 'dark') ?? colors[0] ?? 'dark';
+    const lightColor = colors.find((c) => c.toLowerCase() === 'light') ?? colors[1] ?? 'light';
+    const accentColor = colors.find((c) => !['dark', 'light', 'gray', 'grey'].includes(c.toLowerCase())) ??
+        colors[2] ??
+        'orange';
+    const dc = darkColor.toLowerCase();
+    const lc = lightColor.toLowerCase();
+    const ac = accentColor.toLowerCase();
+    const lines = ['## Common Layout Patterns', ''];
+    lines.push('Copy-paste these patterns into `rawHtml`. Replace placeholder text with real content.');
+    lines.push('');
+    lines.push('> **All patterns use the mandatory two-layer grid structure.** The outer `container-cols-grid` provides');
+    lines.push('> page margin columns; the inner `content-cols-grid` provides the 12-column content grid.');
+    lines.push('> Never use `content-cols-grid` as the outermost element — content will have no page margins.');
+    lines.push('');
+    lines.push('### Centered Text Block');
+    lines.push('');
+    lines.push('```html');
+    lines.push('<div class="w-full container-cols-grid container-rows-grid container-row-6-12">');
+    lines.push('  <div class="col-start-2 col-span-1 row-start-2 row-span-4 content-cols-grid">');
+    lines.push('    <div class="col-span-full laptop:col-start-2 laptop:col-span-10 flex flex-col gap-6">');
+    lines.push('      <h2 class="h2">Section Heading</h2>');
+    lines.push('      <div class="rtf-standard">');
+    lines.push('        <p>Body copy goes here.</p>');
+    lines.push('      </div>');
+    lines.push('    </div>');
+    lines.push('  </div>');
+    lines.push('</div>');
+    lines.push('```');
+    lines.push('');
+    lines.push('### Two-Column Layout (Text + Visual)');
+    lines.push('');
+    lines.push('```html');
+    lines.push('<div class="w-full container-cols-grid container-rows-grid container-row-6-12">');
+    lines.push('  <div class="col-start-2 col-span-1 row-start-2 row-span-4 content-cols-grid">');
+    lines.push('    <div class="col-span-full laptop:col-start-2 laptop:col-span-4 flex flex-col gap-6">');
+    lines.push('      <h2 class="h2">Heading</h2>');
+    lines.push('      <p class="p1">Descriptive text alongside the visual.</p>');
+    lines.push('    </div>');
+    lines.push('    <div class="col-span-full laptop:col-start-7 laptop:col-span-5">');
+    lines.push('      <img src="..." alt="..." class="w-full rounded-lg" />');
+    lines.push('    </div>');
+    lines.push('  </div>');
+    lines.push('</div>');
+    lines.push('<!-- For tablet column layout, use customCss @media instead of tablet: prefix -->');
+    lines.push('```');
+    lines.push('');
+    lines.push('### Coloured Card');
+    lines.push('');
+    lines.push('```html');
+    lines.push('<div class="w-full container-cols-grid container-rows-grid container-row-6-12">');
+    lines.push('  <div class="col-start-2 col-span-1 row-start-2 row-span-4 content-cols-grid">');
+    lines.push('    <div class="col-span-full laptop:col-start-2 laptop:col-span-10">');
+    lines.push(`      <div class="bg-${ac} text-${dc} p-8 rounded-lg flex flex-col gap-4">`);
+    lines.push('        <h3 class="h3">Card Title</h3>');
+    lines.push('        <p class="p2">Supporting description text.</p>');
+    lines.push('      </div>');
+    lines.push('    </div>');
+    lines.push('  </div>');
+    lines.push('</div>');
+    lines.push('```');
+    lines.push('');
+    lines.push('### Card Grid');
+    lines.push('');
+    lines.push('```html');
+    lines.push('<div class="w-full container-cols-grid container-rows-grid container-row-6-12">');
+    lines.push('  <div class="col-start-2 col-span-1 row-start-2 row-span-4 content-cols-grid gap-y-8">');
+    lines.push('    <div class="col-span-full laptop:col-start-2 laptop:col-span-10">');
+    lines.push('      <h2 class="h2">Grid Title</h2>');
+    lines.push('    </div>');
+    lines.push('    <div class="col-span-full laptop:col-start-2 laptop:col-span-10">');
+    lines.push('      <!-- Use customCss for responsive grid columns (tablet:/laptop: not reliable in rawHtml) -->');
+    lines.push('      <div class="my-card-grid">');
+    lines.push('        <div class="flex flex-col gap-4 p-6 border rounded-lg">');
+    lines.push('          <h3 class="h3">Card 1</h3>');
+    lines.push('          <p class="p2">Description.</p>');
+    lines.push('        </div>');
+    lines.push('      </div>');
+    lines.push('    </div>');
+    lines.push('  </div>');
+    lines.push('</div>');
+    lines.push('<!-- In customCss: -->');
+    lines.push('<!-- @media (min-width: 768px) { .my-card-grid { display: grid; grid-template-columns: repeat(2, 1fr); gap: 24px; } } -->');
+    lines.push('<!-- @media (min-width: 1024px) { .my-card-grid { grid-template-columns: repeat(3, 1fr); } } -->');
+    lines.push('```');
+    lines.push('');
+    lines.push('### Hero with Dark Background');
+    lines.push('');
+    lines.push('```html');
+    lines.push('<!-- Set isHero: true and fullWidth: true on this HtmlComponent entry -->');
+    lines.push('<!-- fullWidth: true removes the outer grid — you own the full width -->');
+    lines.push('<!-- py-16 is used here because fullWidth: true removes the outer grid/row spacing. -->');
+    lines.push('<!-- In a standard (non-fullWidth) section, use container-row-6-* for vertical spacing. -->');
+    lines.push(`<div class="bg-${dc} text-${lc} w-full">`);
+    lines.push('  <div class="content-cols-grid py-16">');
+    lines.push('    <div class="col-span-full laptop:col-start-2 laptop:col-span-10 flex flex-col gap-8">');
+    lines.push('      <h1 class="h1">Hero Heading</h1>');
+    lines.push('      <p class="p1">Subtitle or intro text.</p>');
+    lines.push('    </div>');
+    lines.push('  </div>');
+    lines.push('</div>');
+    lines.push('```');
+    return lines.join('\n');
+}
+function buildHtmlComponentRules() {
+    return `## HtmlComponent Field Reference
+
+When authoring HTML for a \`HtmlComponent\` entry in Contentful, fill these fields:
+
+| Field | Required | Notes |
+|-------|----------|-------|
+| \`rawHtml\` | ✓ | The HTML markup. Use Tailwind classes; avoid inline \`style=\` attributes for layout/colour/typography. |
+| \`customCss\` | — | Scoped CSS. Rules are automatically prefixed with \`[data-hc-id="<id>"]\` so they cannot leak. **Use for all responsive layout** (\`@media\` queries) and any utility class not in the Confirmed Safe list. |
+| \`customJs\` | — | 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 (see below). |
+| \`markdownContent\` | — | Plain text summary for site search indexing. **Strongly recommended** — leaving it empty makes the component invisible to search. |
+| \`isHero\` | — | Set \`true\` if the HTML contains an \`<h1>\`. Ensures this block appears first in the page content flow. |
+| \`fullWidth\` | — | Set \`true\` for edge-to-edge (full-bleed) layouts that break out of the column grid. |
+| \`excludeFromSearch\` | — | Set \`true\` to exclude from search indexing even if \`markdownContent\` is filled. |
+| \`scriptStrategy\` | — | \`afterInteractive\` (default, safe), \`lazyOnload\` (deferred), \`beforeInteractive\` (constrained). |
+
+### Authoring Rules
+
+1. **Classes, not inline styles.** Use Tailwind utility classes. Never write \`style="color: #FF5C00"\` — use \`class="text-orange"\` instead.
+2. **Use the two-layer grid.** Every section needs an outer \`container-cols-grid\` wrapper (page margins) and an inner \`col-start-2 col-span-1 content-cols-grid\` wrapper (12-column content grid). See the Layout Patterns section.
+3. **Only use responsive prefixes from the Confirmed Safe list.** Tailwind only compiles classes found in source files — classes in \`rawHtml\` are invisible to the scanner. Only use \`tablet:\` / \`laptop:\` prefixes that appear in the **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.
+4. **Semantic HTML.** Use correct heading levels (\`<h1>\` only once per page, \`<h2>\` for section heads, \`<h3>\` for cards).
+5. **Accessible images.** Always include \`alt\` attributes. Decorative images use \`alt=""\`.
+6. **No custom font stacks.** Use \`font-sans\` or rely on typography classes. The project font is loaded by Next.js automatically.
+7. **Fill \`markdownContent\`.** This is strongly recommended — it is the only way site search can index the component's content. Leave it empty and the component is invisible to search.
+8. **Set \`cmsLabel\` immediately.** Use a descriptive value — the Contentful UI shows only this name.
+
+### Custom JavaScript (\`customJs\`)
+
+The renderer automatically injects \`hcRoot\` — a reference to this component's root \`[data-hc-id]\` element — before your script runs. **Always use \`hcRoot\` instead of \`document.querySelector('[data-hc-id]')\`**, which would match the first component on the page, not this one.
+
+\`\`\`js
+// ✓ Correct — hcRoot is automatically scoped to this component
+var btns = hcRoot.querySelectorAll('.my-btn');
+btns.forEach(function (btn) {
+  btn.addEventListener('click', function () { /* ... */ });
+});
+
+// ✗ Wrong — matches the first [data-hc-id] on the page, not necessarily this component
+var section = document.querySelector('[data-hc-id]');
+\`\`\`
+
+**Rules:**
+- Use \`hcRoot\` as the root for all \`querySelector\` / \`querySelectorAll\` calls.
+- Keep scripts small and self-contained — no module imports, no global state.
+- Avoid \`document.getElementById\` unless the ID is unique across the entire page.
+- Use \`afterInteractive\` (default) for toggle/tab interactions. Use \`lazyOnload\` for non-critical analytics or third-party widgets.`;
+}
+// ---------------------------------------------------------------------------
+// Safe Tailwind utilities scanner
+// ---------------------------------------------------------------------------
+/** Responsive / state prefixes to strip before category matching. */
+const VARIANT_PREFIXES = [
+    'tablet:',
+    'laptop:',
+    'desktop:',
+    'wide:',
+    'hover:',
+    'focus:',
+    'active:',
+    'group-hover:',
+    'dark:',
+    'motion-safe:',
+    'motion-reduce:',
+];
+/**
+ * Per-category patterns matched against the BASE class (after stripping variants).
+ * Order matters — first match wins.
+ */
+const SAFE_UTILITY_CATEGORIES = [
+    {
+        label: 'Display & Visibility',
+        pattern: /^(block|inline-block|inline|flex|inline-flex|grid|inline-grid|hidden|contents|flow-root|visible|invisible|sr-only|not-sr-only)$/,
+    },
+    {
+        label: 'Position',
+        pattern: /^(relative|absolute|fixed|sticky|static)$|^(inset(-[xy])?|top|right|bottom|left|z)-/,
+    },
+    {
+        label: 'Flexbox',
+        pattern: /^(flex(-col|-row|-wrap|-nowrap|-1|-auto|-initial|-none|-shrink|-shrink-0|-grow|-grow-0)?|items|justify|self|content|place-items|place-content|place-self|order|grow|shrink|basis)(-|$)/,
+    },
+    {
+        label: 'Grid',
+        pattern: /^(grid(-cols|-rows|-flow)?|col(-span|-start|-end)?|row(-span|-start|-end)?|auto-cols|auto-rows)(-|\d|$)/,
+    },
+    {
+        label: 'Gap',
+        pattern: /^gap(-[xy])?-/,
+    },
+    {
+        label: 'Padding',
+        pattern: /^(p|px|py|pt|pr|pb|pl|ps|pe)-/,
+    },
+    {
+        label: 'Margin',
+        pattern: /^-?(m|mx|my|mt|mr|mb|ml|ms|me)-/,
+    },
+    {
+        label: 'Space Between',
+        pattern: /^-?space-(x|y)-/,
+    },
+    {
+        label: 'Sizing',
+        pattern: /^(w|h|min-w|min-h|max-w|max-h|size)-/,
+    },
+    {
+        label: 'Typography Utilities',
+        pattern: /^(text-(center|left|right|justify|wrap|nowrap|balance|pretty)|font-(bold|semibold|medium|normal|light|thin|black|extrabold)|leading|tracking|uppercase|lowercase|capitalize|normal-case|truncate|break|whitespace|underline|no-underline|line-through|decoration|align|indent)(-|$)/,
+    },
+    {
+        label: 'Borders & Radius',
+        pattern: /^(border(-[0-9]|-(t|b|l|r|x|y|s|e|dashed|solid|dotted|none))?$|rounded)(-|$)/,
+    },
+    {
+        label: 'Opacity',
+        pattern: /^opacity-/,
+    },
+    {
+        label: 'Shadow & Ring',
+        pattern: /^(shadow|ring)(-|$)/,
+    },
+    {
+        label: 'Overflow',
+        pattern: /^overflow(-[xy])?-/,
+    },
+    {
+        label: 'Object Fit',
+        pattern: /^object-/,
+    },
+    {
+        label: 'Aspect Ratio',
+        pattern: /^aspect-/,
+    },
+    {
+        label: 'Transition & Animation',
+        pattern: /^(transition|duration|ease|delay|animate)(-|$)/,
+    },
+    {
+        label: 'Transform',
+        pattern: /^-?(translate|rotate|scale|skew|transform)(-|$)/,
+    },
+    {
+        label: 'Interactivity',
+        pattern: /^(cursor|pointer-events|select|resize|scroll|touch)(-|$)/,
+    },
+];
+/** Characters that are valid in a Tailwind class token. */
+const VALID_CLASS_RE = /^[a-z0-9_-]+([:/[\].!a-z0-9_-])*$/i;
+/**
+ * For spacing/sizing categories the value portion (after the last prefix hyphen)
+ * must look like a Tailwind scale — a number, fraction, keyword, or arbitrary value.
+ * This prevents descriptive classnames like `my-warning` from being included.
+ */
+const SPACING_CATEGORY_LABELS = new Set(['Padding', 'Margin', 'Gap', 'Space Between', 'Sizing']);
+const VALID_SPACING_VALUE_RE = /^(\[.*\]|-?\d[\d.]*(?:\/\d+)?|px|auto|full|screen|fit|min|max|svh|dvh|unset|inherit|cols-\S+|gap-\S+)$/;
+/** Patterns for strings we always exclude even if they match a category. */
+const EXCLUDE_RE = /^(bg-|text-|border-|ring-|from-|to-|via-|fill-|stroke-|shadow-|outline-|accent-|caret-|divide-color|placeholder-)(?!opacity|none|current|inherit|transparent|clip|left|right|center|justify|auto|full|screen|fit|max|min|px|0|[0-9]|\.)/;
+/** Custom design-system class names that should never appear in utility output. */
+const CUSTOM_CLASS_RE = /^(content-cols-grid|container-cols-grid|container-rows-grid|container-row|section-spacing|col-start-2|rtf-|animate-ticker|animate-fade|animate-shape|animate-card|animate-clip|film-grain|h[1-4](Med|plus|l|lbold|MedYellow)?|p[1-3](Med)?|hHome|large-button|nav)(-|$)/;
+function collectSourceFiles(dir) {
+    const results = [];
+    if (!existsSync(dir))
+        return results;
+    for (const entry of readdirSync(dir)) {
+        const full = join(dir, entry);
+        const st = statSync(full);
+        if (st.isDirectory()) {
+            if (entry === 'node_modules' || entry === '.next' || entry === 'dist')
+                continue;
+            results.push(...collectSourceFiles(full));
+        }
+        else if (/\.(tsx?|css)$/.test(entry)) {
+            results.push(full);
+        }
+    }
+    return results;
+}
+function extractClassTokens(files) {
+    // Match quoted strings that are plausibly class lists (contain spaces or look like single classes)
+    const QUOTED_RE = /(?:className|class)=(?:"([^"]+)"|'([^']+)'|`([^`]+)`)/g;
+    const CN_RE = /\bcn\(([^)]{1,500})\)/g;
+    const tokens = new Set();
+    for (const file of files) {
+        const src = readFileSync(file, 'utf-8');
+        for (const match of src.matchAll(QUOTED_RE)) {
+            const val = match[1] ?? match[2] ?? match[3] ?? '';
+            for (const tok of val.split(/\s+/)) {
+                if (tok)
+                    tokens.add(tok);
+            }
+        }
+        for (const match of src.matchAll(CN_RE)) {
+            for (const quoted of (match[1] ?? '').matchAll(/"([^"]+)"|'([^']+)'/g)) {
+                const val = quoted[1] ?? quoted[2] ?? '';
+                for (const tok of val.split(/\s+/)) {
+                    if (tok)
+                        tokens.add(tok);
+                }
+            }
+        }
+    }
+    return tokens;
+}
+function stripVariantPrefix(cls) {
+    for (const prefix of VARIANT_PREFIXES) {
+        if (cls.startsWith(prefix))
+            return cls.slice(prefix.length);
+    }
+    return cls;
+}
+function categorizeSafeClasses(tokens) {
+    const result = new Map();
+    for (const { label } of SAFE_UTILITY_CATEGORIES) {
+        result.set(label, new Set());
+    }
+    for (const cls of tokens) {
+        // Must look like a valid class token
+        if (!VALID_CLASS_RE.test(cls))
+            continue;
+        // Exclude design-system colour classes (already in Colours section)
+        if (EXCLUDE_RE.test(stripVariantPrefix(cls)))
+            continue;
+        if (CUSTOM_CLASS_RE.test(stripVariantPrefix(cls)))
+            continue;
+        const base = stripVariantPrefix(cls);
+        for (const { label, pattern } of SAFE_UTILITY_CATEGORIES) {
+            if (pattern.test(base)) {
+                // For spacing/sizing categories validate the value portion looks like a
+                // Tailwind scale value, not a descriptive word (e.g. reject `my-warning`)
+                if (SPACING_CATEGORY_LABELS.has(label)) {
+                    const valuePart = base.split('-').at(-1) ?? '';
+                    if (!VALID_SPACING_VALUE_RE.test(valuePart))
+                        break;
+                }
+                result.get(label)?.add(cls);
+                break;
+            }
+        }
+    }
+    return result;
+}
+/**
+ * Expands a single brace-expansion pattern into all concrete strings.
+ * E.g. "{,laptop:}py-{4,8}" → ["py-4", "py-8", "laptop:py-4", "laptop:py-8"]
+ */
+function braceExpand(pattern) {
+    const start = pattern.indexOf('{');
+    if (start === -1)
+        return [pattern];
+    const end = pattern.indexOf('}', start);
+    if (end === -1)
+        return [pattern];
+    const pre = pattern.slice(0, start);
+    const suf = pattern.slice(end + 1);
+    return pattern
+        .slice(start + 1, end)
+        .split(',')
+        .flatMap((alt) => braceExpand(pre + alt + suf));
+}
+/** Parse @source inline("...") entries from a CSS string and expand to class tokens. */
+function expandInlineSources(css) {
+    const tokens = new Set();
+    const re = /@source\s+inline\("([^"]+)"\)/g;
+    let m = re.exec(css);
+    while (m !== null) {
+        for (const cls of braceExpand(m[1])) {
+            const t = cls.trim();
+            if (t)
+                tokens.add(t);
+        }
+        m = re.exec(css);
+    }
+    return tokens;
+}
+/**
+ * Build the cms-rawhtml-safelist.css content for this project.
+ * Uses project breakpoints from tailwind.config.json to generate the correct
+ * variant prefixes, and unions the baseline values with scanner-found values
+ * to cover project-specific spacing usage.
+ */
+function buildSafelistCss(config, scannerTokens) {
+    const sizes = config.sizes ?? {};
+    // Breakpoint names in config order, skipping 'mobile' (no prefix)
+    const bpNames = Object.entries(sizes)
+        .filter(([name, s]) => name !== 'mobile' && s.breakpoint !== undefined)
+        .map(([name]) => name);
+    // e.g. "{,tablet:,laptop:}" or "{,laptop:}" — empty string = base class (no prefix)
+    const vp = bpNames.length > 0 ? `{,${bpNames.map((n) => `${n}:`).join(',')}}` : '';
+    // Extract numeric values the scanner found for a given property prefix
+    function scannerValuesFor(propPrefix) {
+        const vals = new Set();
+        for (const tok of scannerTokens) {
+            const base = stripVariantPrefix(tok);
+            if (base.startsWith(`${propPrefix}-`)) {
+                const val = base.slice(propPrefix.length + 1);
+                if (/^\d+(\.\d+)?$/.test(val))
+                    vals.add(val);
+            }
+        }
+        return [...vals];
+    }
+    // Curated baseline values per property (Tailwind default spacing scale subset)
+    const BASELINE = {
+        py: ['2', '4', '6', '8', '10', '12', '16', '20', '24'],
+        px: ['2', '4', '6', '8', '10', '12', '16', '20'],
+        pt: ['2', '4', '6', '8', '10', '12', '16', '20', '24'],
+        pb: ['2', '4', '6', '8', '10', '12', '16', '20', '24'],
+        p: ['2', '4', '6', '8', '10', '12'],
+        gap: ['1', '2', '3', '4', '5', '6', '8', '10', '12', '16'],
+        'gap-y': ['2', '4', '6', '8', '10', '12', '16'],
+        'gap-x': ['2', '4', '6', '8', '10', '12'],
+        'space-y': ['2', '4', '6', '8', '10', '12', '16'],
+        'space-x': ['2', '4', '6', '8', '10', '12'],
+    };
+    // Properties where responsive variants are meaningful for layout
+    const RESPONSIVE = new Set(['py', 'px', 'gap', 'gap-y', 'gap-x', 'space-y', 'space-x']);
+    const lines = [
+        '/* Auto-generated by cms-generate-html-style-guide — do not edit by hand */',
+        '/* Regenerate: pnpm cms-generate-html-style-guide */',
+        '',
+        '/*',
+        ' * Forces common spacing/gap utilities into the CSS bundle so they can be',
+        ' * safely used in HtmlComponent rawHtml fields (which Tailwind JIT never scans).',
+        ' *',
+        ' * Setup (one time per app):',
+        ` * Add to src/app/globals.css: @import "../generated/cms-rawhtml-safelist.css"`,
+        ' */',
+        '',
+    ];
+    for (const [prop, baseline] of Object.entries(BASELINE)) {
+        // Union baseline with scanner-found values, sort numerically
+        const all = new Set([...baseline, ...scannerValuesFor(prop)]);
+        const values = [...all].sort((a, b) => Number(a) - Number(b));
+        const valBrace = `{${values.join(',')}}`;
+        const prefix = RESPONSIVE.has(prop) && vp ? vp : '';
+        lines.push(`@source inline("${prefix}${prop}-${valBrace}");`);
+    }
+    return `${lines.join('\n')}\n`;
+}
+function buildSafeUtilitiesSection(allTokens) {
+    const grouped = categorizeSafeClasses(allTokens);
+    const lines = [
+        '## Confirmed Safe Tailwind Utilities',
+        '',
+        'These classes are **guaranteed to be in the CSS bundle** — either found in compiled source',
+        'files or explicitly included in the generated `src/generated/cms-rawhtml-safelist.css`.',
+        'Use them freely in `rawHtml`.',
+        '',
+        '> **Setup required (one time):** Add `@import "../generated/cms-rawhtml-safelist.css"` to',
+        '> `src/app/globals.css`. Without this import the safelist classes are not compiled.',
+        '',
+        '> **Any class NOT listed here may not be compiled.** For responsive layout not in this list,',
+        '> use `customCss` with `@media` queries instead.',
+        '',
+    ];
+    let totalCount = 0;
+    for (const { label } of SAFE_UTILITY_CATEGORIES) {
+        const classes = grouped.get(label);
+        if (!classes || classes.size === 0)
+            continue;
+        const sorted = [...classes].sort();
+        totalCount += sorted.length;
+        lines.push(`### ${label}`);
+        lines.push('');
+        lines.push(sorted.map((c) => `\`${c}\``).join(' '));
+        lines.push('');
+    }
+    if (totalCount === 0) {
+        lines.push('_No confirmed utility classes found — ensure source files are accessible._');
+    }
+    return lines.join('\n');
+}
+// ---------------------------------------------------------------------------
+// Main
+// ---------------------------------------------------------------------------
+function main() {
+    const appRoot = parseAppDir();
+    const appName = basename(appRoot);
+    console.log(`Generating HTML style guide for: ${appRoot}`);
+    // Load tailwind config
+    const config = loadTailwindConfig(appRoot);
+    if (!config) {
+        console.error(`ERROR: Could not load tailwind.config.json from ${appRoot}`);
+        console.error('  Run from or pass --app-dir pointing to an app directory.');
+        process.exit(1);
+    }
+    // Load globals.css
+    const globalsCssPath = join(appRoot, 'src/app/globals.css');
+    let globalsCss = '';
+    if (existsSync(globalsCssPath)) {
+        globalsCss = readFileSync(globalsCssPath, 'utf8');
+    }
+    else {
+        console.warn(`  WARNING: globals.css not found at ${globalsCssPath} — skipping CSS parsing`);
+    }
+    const utilities = extractUtilities(globalsCss);
+    const rtfClasses = extractRtfClasses(globalsCss);
+    const rootVars = extractRootVars(globalsCss);
+    // Scan source files for confirmed-safe class tokens
+    const monorepoRoot = join(appRoot, '../..');
+    const scanDirs = [join(appRoot, 'src'), join(monorepoRoot, 'packages/core-ui/src')];
+    const sourceFiles = scanDirs.flatMap(collectSourceFiles);
+    const scannerTokens = extractClassTokens(sourceFiles);
+    // Generate the per-project safelist CSS (uses project breakpoints + scanner values)
+    const safelistCss = buildSafelistCss(config, scannerTokens);
+    const safelistDir = join(appRoot, 'src/generated');
+    const safelistPath = join(safelistDir, 'cms-rawhtml-safelist.css');
+    mkdirSync(safelistDir, { recursive: true });
+    writeFileSync(safelistPath, safelistCss);
+    // Expand safelist tokens and merge with scanner tokens
+    const safelistTokens = expandInlineSources(safelistCss);
+    const allTokens = new Set([...scannerTokens, ...safelistTokens]);
+    console.log(`  Colours: ${Object.keys(config.colorOptions ?? {}).length}`);
+    console.log(`  Typography styles: ${Object.keys(config.fontTable?.styles ?? {}).length}`);
+    console.log(`  Utilities: ${utilities.length}`);
+    console.log(`  RTF classes: ${rtfClasses.length}`);
+    console.log(`  CSS variables: ${rootVars.length}`);
+    console.log(`  Safelist classes: ${safelistTokens.size} (wrote ${safelistPath})`);
+    console.log(`  ℹ  One-time setup: add  @import "../generated/cms-rawhtml-safelist.css"  to src/app/globals.css`);
+    // Build sections
+    const now = new Date().toISOString().split('T')[0];
+    const sections = [
+        `# HTML Component Style Guide — ${appName}`,
+        '',
+        `> Auto-generated on ${now} from \`tailwind.config.json\` and \`src/app/globals.css\`.`,
+        '> Regenerate with: `pnpm cms-generate-html-style-guide`',
+        '',
+        'This guide defines every design token available for use in `HtmlComponent` `rawHtml` fields.',
+        'Read this before authoring any custom HTML for the site — it ensures visual consistency.',
+        '',
+        '---',
+        '',
+        buildHtmlComponentRules(),
+        '',
+        '---',
+        '',
+        buildBreakpointsSection(config),
+        '',
+        '---',
+        '',
+        buildColourSection(config),
+        '',
+        '---',
+        '',
+        buildTypographySection(config),
+        '',
+        '---',
+        '',
+        buildGridSection(config),
+        '',
+        '---',
+        '',
+        buildSpacingSection(),
+        '',
+        '---',
+        '',
+        buildFontsSection(config),
+        '',
+        '---',
+        '',
+        buildUtilitiesSection(utilities),
+        '',
+        '---',
+        '',
+        buildRtfSection(rtfClasses),
+        '',
+        '---',
+        '',
+        buildSafeUtilitiesSection(allTokens),
+        '',
+        '---',
+        '',
+        buildPatternsSection(config),
+    ];
+    // Include CSS variables if any interesting ones found
+    const interestingVars = rootVars.filter((v) => !v.name.startsWith('--color-') && !v.name.startsWith('--animate-'));
+    if (interestingVars.length > 0) {
+        sections.push('', '---', '', '## CSS Custom Properties', '');
+        sections.push('These tokens are available via `var(--name)` in `customCss` fields:');
+        sections.push('');
+        sections.push('| Variable | Default value |');
+        sections.push('|----------|---------------|');
+        // De-duplicate by name — keep the first (default/mobile) value; note responsive overrides
+        const seenVars = new Map();
+        const multipleVars = new Set();
+        for (const { name, value } of interestingVars) {
+            if (seenVars.has(name)) {
+                multipleVars.add(name);
+            }
+            else {
+                seenVars.set(name, value);
+            }
+        }
+        for (const [name, value] of seenVars) {
+            const note = multipleVars.has(name) ? ' *(has responsive override)*' : '';
+            sections.push(`| \`${name}\` | \`${value}\`${note} |`);
+        }
+    }
+    const output = `${sections.join('\n')}\n`;
+    // Write output
+    const outputDir = join(appRoot, 'docs/cms-guidelines');
+    mkdirSync(outputDir, { recursive: true });
+    const outputPath = join(outputDir, 'html-component-style-guide.md');
+    writeFileSync(outputPath, output);
+    console.log(`\nWrote ${outputPath}`);
+}
+main();
+//# sourceMappingURL=cms-generate-html-style-guide.js.map