@se-studio/contentful-cms 1.0.3 → 1.0.5

package/skills/cms-guidelines/variant-proposal-prompt.md

@@ -0,0 +1,127 @@
+# Variant Proposal Prompt
+
+**Step 4.1 — Input/output contract and prompt for proposing component variants.**
+
+The variant loop produces screenshots that cover the visual diversity of a component. A good
+set captures: default state, important absent-field states, colour variants, and any layout
+variants (like flipped). The screenshots are then used to write the "What it looks like" and
+"Colours" sections of the guideline.
+
+---
+
+## Input
+
+- **Component source file:** full contents of `src/project/components/<Type>.tsx` (or
+  `src/project/collections/<Type>.tsx`).
+- **Used fields:** the `USED_FIELDS` or `FIELD_KEYS` from the source file.
+- **Palette:** `backgroundColour` and `textColour` enum values from `generated/cms-discovery/field-list.json`
+  (or from `generated/colors.ts`).
+- **N:** number of variants to propose (typically 4–6 for a component, up to 8 for complex ones).
+
+The LLM should output **N variants** in JSON format (see below).
+
+---
+
+## Prompt
+
+```
+You are preparing screenshots for CMS component guidelines.
+
+I will give you the source code of a Next.js component that renders a CMS entry.
+Your task: propose N variants that, together, best document how the component looks
+under different conditions. Choose variants that are VISUALLY DISTINCT — a reader
+should be able to tell them apart at a glance.
+
+Component source:
+<COMPONENT_SOURCE>
+
+Palette (backgroundColour options):
+<BACKGROUND_COLOURS>
+
+Text colour options (textColour):
+<TEXT_COLOURS>
+
+Rules:
+1. Always include a "default" variant with all optional fields populated and no colour override.
+2. Include at least one variant per important "missing field" state (e.g. no visual, no links).
+3. Include at least one colour variant if the component has backgroundColour (use a dark colour
+   like Navy or Deep Periwinkle).
+4. If the component has a flipped/alternate variant (e.g. Hero Flipped), include it.
+5. Avoid variants that will look identical or near-identical to another variant in the list.
+6. N = <N>; produce exactly N variants (or fewer if the component is simple).
+
+Output JSON only, no explanation. Format:
+{
+  "typeName": "<CMS componentType or collectionType>",
+  "variants": [
+    {
+      "label": "default",
+      "description": "All fields populated, no colour override.",
+      "showcaseParams": {}
+    },
+    {
+      "label": "no-visual",
+      "description": "visual field removed; copy spans full width.",
+      "showcaseParams": { "showVisual": "false" }
+    },
+    {
+      "label": "navy-background",
+      "description": "Navy background with Off White text.",
+      "showcaseParams": { "backgroundColour": "Navy", "textColour": "Off White" }
+    }
+  ]
+}
+
+showcaseParams keys must match the cms-edit screenshot --param format:
+  backgroundColour, textColour, showVisual, showLinks, showHeading, etc.
+For a flipped variant, use a separate typeName entry for "Hero Flipped".
+```
+
+---
+
+## Output contract
+
+```json
+{
+  "typeName": "Hero",
+  "variants": [
+    {
+      "label": "default",
+      "description": "All optional fields populated, no colour override.",
+      "showcaseParams": {}
+    },
+    {
+      "label": "no-visual",
+      "description": "Visual removed; copy spans full width.",
+      "showcaseParams": { "showVisual": "false" }
+    },
+    {
+      "label": "navy",
+      "description": "Navy background + Off White text.",
+      "showcaseParams": { "backgroundColour": "Navy", "textColour": "Off White" }
+    },
+    {
+      "label": "minimal",
+      "description": "Heading only, no eyebrow/subtitle/body/links/visual.",
+      "showcaseParams": { "showVisual": "false", "showLinks": "false" }
+    }
+  ]
+}
+```
+
+- `label` — used to name the screenshot file: `<typeName-kebab>-<label>.png`
+- `description` — included in the screenshot log and used by the evaluation step
+- `showcaseParams` — key-value pairs passed as `--param key=value` to `cms-edit screenshot`
+
+---
+
+## Notes on N and the cap
+
+The orchestrator (Step 4.4) uses N (the number of proposed variants) as a cap:
+
+- It will attempt up to **2×N** screenshots in total.
+- If the evaluation step (Step 4.3) concludes the variants are "suitably different" before
+  reaching 2×N attempts, it stops early.
+- If not, it requests a new proposal from the LLM for the remaining slots (up to 2×N total).
+
+For most components, N = 4–6 produces a good coverage set.