AI Code Generation — From prompt to XM Cloud component matrix

Created:
Updated:

When I talk about “from prompt to component matrix” on real XM Cloud projects, I am rarely starting from a crawler alone. By the time I bring coding agents into the loop, there is usually a manually created component matrix put together by a BA, architect, or tech lead:

In greenfield builds the starting point is usually Figma or similar, not an existing site. Either way, the pattern is the same: provide enough context for an AI coding agent to infer:

This post describes how I structure that work and how I prompt agents to:

The output is deliberately narrow: no Storybook yet, no code, just the markdown requirement files and/or a enriched component matrix that will feed the next post on Storybook component generation.

If you want to see how these specs feed into the rest of the pipeline, the follow-up posts in this series show what I do next:

At a high level, the flow looks like this:

High-level requirements prompt

Manual component matrix or Figma list

AI coding agent

Component requirement .md files

Storybook + XM Cloud build

In my own workflow I start with a prompt and a human‑curated matrix, let an agent transform each row into a structured requirements document, and then hand those documents to the next stage of the XM Cloud build.

The starting point: a manual component matrix or Figma list

For lift‑and‑shift projects, the starting artifact is usually a spreadsheet or markdown table created by the team:

On greenfield builds, the same matrix can be built off Figma rather than a live site. The BA or designer lists components straight from the design system:

The key is that, by the time I bring in an AI coding agent, humans have already agreed which components matter. The agent’s job is to turn each line item into a Sitecore-ready requirements document, not to decide the entire IA on its own.

The agents I tend to use

For this phase I usually lean on:

Sometimes I will run two agents in parallel:

To keep them aligned, I usually give them both:

The rest of this post shows the kinds of prompts and context files that have worked well for me.

Conceptually, I think about two “agents” in the loop:

Component matrix / Figma list

Agent A: orchestrator

Agent B: requirements writer

Markdown requirement files

Target output: component requirement markdown files

The end result of this step is a folder full of markdown requirement files (one per component) and/or a richer component matrix. These files are the contract that future steps will use to generate Storybook components and XM Cloud artifacts.

I keep the format simple and consistent:

Here is an example of a requirement file I would be happy to hand to a coding agent for implementation:

# Requirements

## Name
Accordion

## Description
Expandable FAQ container used to present grouped questions and answers. Authors can supply an optional intro with subtitle, then curate individual accordion items that reveal detailed answers on click. Component supports lazy loading and can reveal additional items with a “Load more” control.

## Fields

### Title
- **Field Type**: Single-Line Text
- **Required**: Yes
- **Repeating**: No
- **Notes**: Headline displayed above the accordion; keep concise (e.g., “Frequently asked questions”).
- **Example Value**: `Frequently asked questions`

### Subtitle
- **Field Type**: Single-Line Text
- **Required**: No
- **Repeating**: No
- **Notes**: Optional sub-heading shown under the main title to frame the content.
- **Example Value**: `Answers about our rental and laundry service`

### Introduction Text
- **Field Type**: Rich Text
- **Required**: No
- **Repeating**: No
- **Notes**: Brief descriptive paragraph preceding the accordion list; supports bold text and inline links.
- **Example Value**: `<p>Find quick answers about delivery intervals, textile care, and service options.</p>`

### Accordion Items
- **Field Type**: Treelist (Accordion Item)
- **Required**: Yes
- **Repeating**: Yes
- **Notes**: Ordered list of FAQ entries rendered in the accordion; first item loads expanded by default.
- **Example Value**: Service Process, Delivery Cycle, Textile Care

#### Accordion Item Fields:
- **Question**: Single-Line Text - Title displayed on the accordion trigger.
- **Answer**: Rich Text - Content revealed when the panel expands; supports lists and inline links.
- **Anchor ID**: Single-Line Text - Optional anchor for deep-linking directly to the FAQ entry.

### Load More Button Text
- **Field Type**: Single-Line Text
- **Required**: No
- **Repeating**: No
- **Notes**: Overrides the default “Load more” label used when the component hides items beyond the initial set.
- **Example Value**: `Show more questions`

### Load More Enabled
- **Field Type**: Checkbox
- **Required**: No
- **Repeating**: No
- **Notes**: When checked, only the first three items render initially; remaining items appear after clicking the button.
- **Example Value**: Checked

### Background Theme
- **Field Type**: Droplist
- **Required**: No
- **Repeating**: No
- **Notes**: Selects alternate background shading (e.g., `white`, `light-grey`, `yellow`) to match adjacent sections.
- **Example Value**: `Light-grey`

## Example Reference
* **URL**: https://www.cws.com/en/workwear/products
* **Element**: `<div class="paragraph paragraph--type--faq lazy-load workwear lazy-inst-1">`

## Notes
- Component lazy-loads content to improve performance; ensure important FAQs appear in the first three slots.
- Only one accordion panel opens at a time; expanding a new item automatically collapses the previous one.
- Provide concise questions and direct answers to maintain scannability, especially on mobile devices.

Everything else in this post is about giving agents the context and prompts they need to output documents in this shape for every component in the matrix, not one at a time by hand.

AGENTS.md for the component requirements workspace

Before I hand anything to an AI coding agent, I like to drop an AGENTS.md file into the repo. This keeps the workspace predictable and makes it easy to swap models later.

Here is a minimal AGENTS.md that fits the way I like to run this workspace:

# AGENTS.md — Component requirements generation for XM Cloud

## Project scope
- Generate Sitecore-friendly component requirement markdown files from a manually curated component matrix or Figma-based list.
- Do NOT generate implementation code, Storybook stories, or XM Cloud templates in this repo.
- Output is used as input for a separate Storybook + XM Cloud generation step.

## Preferred tools
- Primary: OpenAI ChatGPT-5 Codex (coding-focused model).
- Secondary: Claude Sonnet 4 for analysis and long-form reasoning.
- Budget option: Google CLI with Gemini 2.5 (expect lower quality and more manual review).

## Input artifacts
- Component matrix: Excel, CSV, or Markdown with:
  - Component name
  - Sample URL(s)
  - Selector hints (ID/class)
  - Field hints
  - Figma links (if available)
- Reference requirement files, e.g. `Accordion.md`.

## Output artifacts
- One markdown requirement file per component (unless instructed otherwise).
- File naming: `<ComponentName>.md` (PascalCase, no spaces).
- Structure must follow the Accordion example (Name, Description, Fields, Example Reference, Notes).

## Conventions
- Use Sitecore field types (Single-Line Text, Rich Text, Image, General Link, Checkbox, Droplink, Multilist, Treelist, etc.).
- Prefer concise, editor-friendly language in descriptions and notes.
- Do not invent completely new components; stay within the provided matrix.

## What you should do
- Iterate through all components in the matrix.
- For each, browse sample URLs and/or Figma references.
- Propose a complete, consistent requirements document.
- Ask clarifying questions when information is missing or ambiguous.

I reference this file directly in my prompts so agents internalize the scope and avoid jumping ahead to Storybook or code.

Batch prompt: generate requirements from the component matrix

The main prompt I use for this step is a batch‑oriented task: the agent should iterate through the component matrix and produce one requirement file per row, rather than treating each component as a separate manual conversation.

Here is a version of that prompt, adapted to this blog’s narrative.

# Component Requirements Generation Task

## Overview

You are an AI coding agent helping on a Sitecore XM Cloud project.

Your goal is to read a manually curated component matrix and generate Sitecore-ready component requirement markdown files for every component listed.

Prefer to run with:
- OpenAI ChatGPT-5 Codex as the primary coding model where available.
- Claude Sonnet 4 as a strong fallback for analysis-heavy steps.
- Google CLI with Gemini 2.5 as a cheaper, lower-capability alternative if required.

## Input Files

- **Component Matrix**: `ai/prompts/component_specs/input/Component_Matrix.xlsx`
  - Use the first sheet only.
- **Reference Requirements**:
  - `ai/prompts/component_specs/Accordion.md` (example requirements document)
  - `ai/prompts/component_specs/IndustryCard.md` (another example)
- **Workspace Instructions**:
  - `AGENTS.md` at the repo root (defines scope, conventions, and output format)

## Excel Column Mapping

Interpret the matrix columns as:

- **Component Name**: use the `Component` column.
- **Sample URLs**: use `Sample URLs of Component` (comma- or newline-separated).
- **HTML Selector Hint**: use `Component ID` (preferred) or `Component Class` (fallback).
- **Field Suggestions**: use any `Fields`-related columns as a starting point only.
- **Design Reference** (if present): use `Figma Link` or similar columns when available.

## Requirements

### Component Analysis

For each row in the matrix (each component):

1. **Fetch live HTML (when URLs exist)**  
   - Visit each sample URL and extract the component’s markup.  
   - Use `Component ID` first to locate the component; fall back to `Component Class` or structural hints if needed.

2. **Validate and enrich fields**  
   - Cross-check suggested fields from the matrix against the actual HTML structure and visible behavior.  
   - Add any missing fields that are implied by the markup (e.g., image alt text, badge labels, tracking attributes).  
   - Map all fields to appropriate Sitecore field types.

3. **Clarify behavior and variants**  
   - Infer key behaviors (hover states, lazy loading, “load more”, responsive changes) from the page or Figma.  
   - Capture these as notes rather than implementation details.

### Sitecore Field Types

When defining fields, use appropriate Sitecore field types, such as:

- Single-Line Text  
- Multi-Line Text  
- Rich Text  
- Image  
- General Link  
- Checkbox  
- Number  
- Date  
- Droplink / Droplist  
- Multilist / Treelist  

### Output Specifications

For each component in the matrix:

- **Location**: save the requirements file under `ai/prompts/component_specs/`.  
- **File name**: use the `Component` name, sanitized to `PascalCase.md` (e.g., `HeroBanner.md`).  
- **Format**: follow the structure and tone of `Accordion.md`.  
  - Sections: Name, Description, Fields, Example Reference, Notes.  
  - Include nested field groups for repeating items (e.g., “Accordion Item Fields”).  
- **Scope**: do NOT generate Storybook stories, React code, XM Cloud templates, or any implementation artifacts in this task.

### Iteration Strategy

- Treat the component matrix as the source of truth for **which** components to cover.  
- Iterate through all rows; do not stop after a single component unless explicitly instructed.  
- Process components in batches (e.g., 5–10 at a time) to avoid context overflow, but ensure that the final output includes a requirements file for every row in the matrix.

## Quality Checks

Before you consider the task complete, verify that:

- [ ] Every component in the `Component` column has a corresponding `.md` file.  
- [ ] Each requirements file follows the agreed format and includes Name, Description, Fields, Example Reference, and Notes.  
- [ ] Field types are consistent and appropriate for Sitecore.  
- [ ] Sample URLs and selector hints are captured in the Example Reference.  
- [ ] No implementation code or Storybook details have leaked into the requirements.

## Questions to Confirm (if needed)

1. How should you handle components whose sample URLs are inaccessible or whose markup cannot be located by the given selectors?  
2. Are there any client-specific naming conventions (prefixes, casing, folder paths) for component names or templates?  
3. Should you generate a summary report (e.g., a table) that lists all components and links to their requirement files?  
4. Are there any components that should be treated as layout containers rather than content components?

In practice I paste this prompt (or a variant) into the chosen agent, attach the matrix and the reference files, and then let it run in batches while I review early outputs.

Single-component prompt: from page (or Figma) to requirements

When I want to refine or regenerate a single component’s requirements, I use a smaller prompt that mirrors the batch task but focuses on one component. Here is a version that matches the narrative in this post:

Create a Sitecore component requirements document in markdown format by analyzing the provided component.

Your output will be a high-level specification that another coding agent can use to locate and analyze the component independently.

## Inputs

- One or more **webpage URLs** where the component appears, OR a **Figma link** and textual description.  
- Optional: a selector hint (ID or class) to narrow down the DOM element.  
- Optional: field hints or existing matrix row for this component.

## Instructions

1. **Examine the component**  
   - If URLs are provided, browse the referenced webpage(s) and locate the component using the selector hint when available.  
   - If a Figma link is provided, study the component’s structure, states, and variants.

2. **Identify the component pattern**  
   - Classify the component (accordion, carousel, card grid, hero banner, teaser, etc.).  
   - Note any repeating items (e.g., FAQ entries, slides, cards).

3. **Document high-level requirements only**  
   - Provide enough detail for another agent to locate the component and understand its purpose, behavior, and fields.  
   - Focus on fields needed for Sitecore templates and datasource items.  
   - Do NOT include implementation code, Storybook details, or exhaustive content samples.

4. **Focus on structure over content**  
   - Use example values sparingly, just to illustrate field usage.  
   - Emphasize field types, required vs optional, repeating vs non-repeating, and any nested item templates.

## Required Document Format

Follow this structure and tone (similar to `Accordion.md`):

```md
# Requirements

## Name
[ComponentName]

## Description
[2–3 sentences describing:
- What the component does
- Key visual/interactive features
- Primary user interactions]

## Fields

### [Field Name]
- **Field Type**: [Single-Line Text | Multi-Line Text | Rich Text | Image | General Link | Checkbox | Droplink | Multilist | Treelist | etc.]
- **Required**: [Yes | No]
- **Repeating**: [Yes | No] (if part of a repeating item)
- **Notes**: [Any validation, defaults, or special considerations]
- **Example Value**: [Brief example to illustrate expected format]

### [Collection Field Name]
- **Field Type**: [Multilist | Treelist]
- **Required**: Yes
- **Repeating**: Yes
- **Notes**: [How the collection is used in the component]

#### [Item Template Name] Fields:
- **[Field Name]**: [Field Type] - [Short description]
- **[Field Name]**: [Field Type] - [Short description]

## Example Reference
* **URL**: [example URL where this component appears]
* **Element**: `[selector or brief DOM description]`

## Scope

- Do NOT discuss or generate Storybook stories, React/Next.js components, or XM Cloud templates in this task.  
- Only produce the markdown requirements document as described above.

## Notes
- [Any additional context about variants, responsive behavior, or dependencies]

This pattern has been enough for me to regenerate or refine individual components when the batch run misinterprets something or when designers change the spec.

Where this fits in the broader flow

In the broader AI Code Generation theme, this step sits between:

At this stage, the deliverables are intentionally simple:

Those documents then become the single source of truth for the next post, where I focus on taking requirement files like Accordion.md and turning them into Storybook components and XM Cloud BYOC registrations—with agents doing most of the mechanical work and humans staying firmly in charge of what gets shipped.

Additional resources

Previous Post
Integrations — Vercel routing and microfrontends for Sitecore XM Cloud
Next Post
AI‑Powered Stack — From Signed SOW to Sprint One