@se-studio/project-build 1.0.130 → 1.0.132

package/skills/contentful-cms/cms-guidelines/generate-component-guidelines.md

@@ -1,126 +0,0 @@
-# Generate Component Guidelines — Full Pipeline (Step 5.4)
-
-**End-to-end pipeline for one component:** variant loop → generate → colour hint → validate → merge → commit.
-
----
-
-## What this produces
-
-For one CMS type (e.g. Hero):
-
-| Output | Location |
-|---|---|
-| Variant screenshots | `docs/cms-guidelines/screenshots/components/hero-*.png` |
-| Accepted variant list | `generated/cms-discovery/accepted-variants/components/hero.json` |
-| Guideline fragment | `docs/cms-guidelines/components/hero.md` |
-| Colour hint entry | `generated/cms-discovery/colour-hints.json` |
-| Merged full doc (updated) | `docs/cms-guidelines/COMPONENT_GUIDELINES_FOR_LLM.md` |
-
----
-
-## Cursor agent task prompt
-
-**Assign to a Cursor subagent. Provide:**
-- This file
-- `variant-loop.md` (in the same skills/cms-guidelines/ directory)
-- `generation-prompt.md`
-- `colour-hint-prompt.md`
-- `validation-prompt.md`
-- `docs/cms-guidelines/LAYOUT.md`
-- `tmp/component-guidelines-target-format.md`
-
-**Task prompt:**
-
-```
-Run the full guideline generation pipeline for <COMPONENT_TYPE>.
-Target app: <APP_DIR> (all paths relative to that directory).
-
-=== Phase A: Variant loop ===
-Follow variant-loop.md.
-1. Read src/project/components/<TypeName>.tsx (or collections/<TypeName>.tsx).
-2. Read generated/cms-discovery/field-list.json for field metadata.
-3. Propose N=5 variants using the prompt in variant-proposal-prompt.md.
-4. Capture screenshots:
-   cms-capture-screenshots --variants /tmp/<type-slug>-variants.json --app-dir <APP_DIR>
-5. Evaluate screenshots using evaluation-prompt.md.
-   - If not suitably different and attempts < 2×N: capture new suggestions, re-evaluate.
-   - When done: save accepted list to generated/cms-discovery/accepted-variants/{components|collections|externals}/<type-slug>.json
-
-=== Phase B: Generate guideline ===
-Follow generation-prompt.md.
-1. Describe screenshots (Step 1 prompt).
-2. Extract behaviour from code (Step 2 prompt).
-3. Merge into guideline block (Step 3 prompt).
-4. Save output to docs/cms-guidelines/components/<type-slug>.md.
-   (Collections → collections/<type-slug>.md, externals → externals/<type-slug>.md)
-
-=== Phase C: Colour hint ===
-Follow colour-hint-prompt.md.
-Derive the colour application hint (section/card/section+card/none) from the source.
-Run:
-  cms-update-colour-hints --app-dir <APP_DIR> \
-    --type "<COMPONENT_TYPE>" --hint "<hint>" --notes "<brief reason>"
-
-=== Phase D: Validate ===
-Follow validation-prompt.md.
-1. Read the generated fragment and the component source.
-2. Run the 9-check validation.
-3. If NEEDS REVISION: apply fixes to the fragment and re-run validation.
-4. Repeat until APPROVED.
-
-=== Phase E: Merge ===
-  cms-merge-guidelines --app-dir <APP_DIR>
-This updates docs/cms-guidelines/COMPONENT_GUIDELINES_FOR_LLM.md.
-
-=== Phase F: Commit ===
-  git add docs/cms-guidelines/ generated/cms-discovery/
-  git commit -m "chore: generate guidelines for <COMPONENT_TYPE>"
-```
-
----
-
-## Manual pipeline (for Hero — already partially done)
-
-Hero has a hand-written guideline fragment (Step 3.1), accepted variant screenshots
-(Step 4.2), and colour hints (Step 5.2). To complete the pipeline manually:
-
-```bash
-# Phase D: Validate hero.md (hand-written)
-# Use: validation-prompt.md + src/project/components/Hero.tsx
-# Apply any fixes to docs/cms-guidelines/components/hero.md
-
-# Phase E: Merge
-cms-merge-guidelines
-
-# Phase F: Commit
-git add docs/cms-guidelines/ generated/cms-discovery/
-git commit -m "chore: complete Hero guideline pipeline"
-```
-
----
-
-## For all components (full site run)
-
-To generate guidelines for all components and collections:
-
-1. Get the list of all types from the discovery API:
-   ```
-   GET /api/cms/discovery
-   ```
-2. For each type in components[], collections[], externals[], run this pipeline.
-3. After all types: run merge and commit the final COMPONENT_GUIDELINES_FOR_LLM.md.
-
-A full run typically takes 5–10 minutes per component (mostly LLM time) and
-30–60 minutes total for a typical site.
-
----
-
-## npm scripts summary
-
-| Script | What it does |
-|---|---|
-| `pnpm run cms-discovery:field-list` | Generate `generated/cms-discovery/field-list.json` from TypeScript types |
-| `pnpm run cms-guidelines:screenshots` | Capture screenshots for a type (interactive) |
-| `pnpm run cms-guidelines:merge` | Merge per-type files into COMPONENT_GUIDELINES_FOR_LLM.md |
-| `cms-update-colour-hints` | Upsert a colour hint in colour-hints.json |
-| `cms-capture-screenshots` | Capture screenshots for a type |

package/skills/contentful-cms/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>"
-```