Page Builder Skill

Step-by-Step Workflow

Follow these steps in order. Do not skip steps.

Step 0: Query Storybook MCP (MANDATORY — do this FIRST)

Before writing any component code, you MUST consult Storybook MCP to understand each component's API, variants, best practices, and gotchas:

1. Call getComponentList to see all available composed components and templates.
2. Identify which Storybook components match the page you're building (PageHeader, CommandBar, FilterBar, DataGrid, SideNavigation, Azure Container, Resource List Page template, etc.).
3. Call getComponentsProps for every component you plan to use — read the full Storybook documentation for each one. This tells you the correct props, available variants, do's and don'ts, and usage patterns. This is critical for greenfield builds and when modifying existing designs.
4. Import components and themes from @azure-fluent-storybook/components — this is a real npm package in the project dependencies. Both components and themes are exported from this single package.
5. Only drop to raw @fluentui/react-components for elements that have no equivalent in @azure-fluent-storybook/components.
6. The Storybook docs often contain helpful information about composition patterns, accessibility, and edge cases — always read them before writing code.

If Storybook MCP is not running, STOP and tell the user:

"The Storybook MCP server isn't running. Open the Command Palette (Cmd+Shift+P), type MCP: List Servers, and click Start next to storybook."

Step 1: Analyze the Input

Determine what the user wants to build. Input can be:

• A screenshot of an Azure Portal page (most common)
• A text description of what the page should look like
• A reference to an existing page they want to replicate or modify

Extract these details from the input:

• Page name and resource type
• Whether it has a side navigation panel (resource pages do, browse/create pages don't)
• What's in the command bar (action buttons)
• Whether there's an Essentials accordion (resource overview pages)
• What the main content area shows (table, form, cards, detail sections, or custom)
• Breadcrumb trail
• Container type (azure or sre)

Step 2: Determine the Layout

Read references/layout-decision.md for the layout decision guide.

Apply this rule:

• Side Panel layout → The user is viewing a specific deployed resource or service (overview, sub-page, detail)
• Full Width layout → Home page, create wizard, marketplace browse, all-resources list

Step 3: Choose the Content Template

The PageSchema supports 5 content template types. Pick the right one:

If the page doesn't fit any standard template (e.g., it has tabs, cards, illustrations, and mixed content like a resource overview "Get started" tab), use custom as the template kind in the schema but build the TSX by hand — the codegen only handles structured templates.

Step 4: Build the Schema JSON

Create src/pages/<PageName>.schema.json conforming to the PageSchema Pydantic model.

Read references/schema-reference.md for the full schema structure and field descriptions.

The schema answers 6 questions:

1. Container — "azure" or "sre"
2. Side nav — SideNavConfig with entries (NavItem/NavGroup), defaultSelected, width
3. Title — TitleConfig with resourceName, pageName, icon, breadcrumbs
4. Command bar — CommandBar with items (StoryRef-backed buttons)
5. Template — One of: list-table, form, cards-grid, detail, custom
6. Essentials — EssentialsConfig with key-value fields (or null)

For command bar items, use these StoryRef patterns:

{
  "story": {
    "storyId": "components-button--subtle",
    "instanceId": "<unique-id>",
    "argOverrides": { "label": "Button Text", "icon": "IconName" }
  },
  "isSeparator": false
}

Step 5: Generate or Hand-Build the TSX

For standard templates (list-table, form, cards-grid, detail): Run the pipeline to generate the TSX:

python pipeline.py src/pages/<PageName>.schema.json

For custom/complex pages (resource overviews with tabs, mixed content): Build the TSX by hand, following the established patterns. Read existing pages in src/pages/ as references.

Read references/component-catalog.md for the full list of available shared components and their props.

When building by hand:

• Import shared components from @azure-fluent-storybook/components — NEVER recreate what already exists
• Use @fluentui/react-components for standard UI primitives
• Use makeStyles + tokens for styling (never hardcode colors/fonts)
• Follow the page layout structure from existing pages

Step 6: Register in App.tsx

Add the new page to src/App.tsx:

1. Add an import: import <PageName> from './pages/<PageName>';
2. Add to the pages record: '<Display Name>': <PageName>,

Step 7: Verify

1. Check for TypeScript errors in the new file
2. Run npx tsc --noEmit and confirm no new errors from your page

Step 8: Build Report

After completing the page, produce a structured build report. This is mandatory — it gives the user visibility into exactly what happened.

Report format:

## Build Report: <Page Name>

### Files Created
- `src/pages/<Name>.schema.json` — Page schema definition
- `src/pages/<Name>.tsx` — React page component

### Files Modified
- `src/App.tsx` — Registered page as "<Display Name>"

### Shared Components Used
List every component imported from `@azure-fluent-storybook/components`:
- `AzureGlobalHeader` — Top application bar
- `PageHeader` — Title with icon, pin, more-actions
- (etc.)

### Fluent UI Components Used
List every component from `@fluentui/react-components`:
- `DataGrid` — Data table
- `Text` — Typography
- (etc.)

### Fluent Icons Used
- `Delete20Regular`
- (etc.)

### Custom Components Created
List any UI elements you built from scratch that don't exist in the shared library:
- `ProductionCard` — Checklist card with icon, title, description, status dot
- (etc.)
If none, state: "None — all UI composed from shared components."

### Layout Decisions
- Layout type: Side Panel / Full Width
- Template type: list-table / form / cards-grid / detail / custom
- Rationale: (why this layout and template were chosen)

### Schema Summary (6 Questions)
1. Container: azure / sre
2. Side nav: Yes/No (N items, M groups)
3. Title: "<title string>"
4. Breadcrumbs: Home > ...
5. Template: <kind>
6. Essentials: Yes/No

Step 9: Post-Build Review (MANDATORY)

After the build report is complete, run the page-review skill to validate quality.

1. Read the page-review skill at .github/skills/page-review/SKILL.md.
2. Execute all three passes against the page you just built:
   • Pass 1 — Token Audit: Scan for hardcoded colors, fonts, spacing, shadows, and border radii.
   • Pass 2 — Component Audit: Verify Storybook components were used where applicable; justify any Fluent fallbacks.
   • Pass 3 — Visual Analysis: Use Playwright to screenshot the rendered page and check layout, icons, alignment, and overall appearance.
3. Present the prioritized action list (High → Medium → Low) to the user.
4. Fix all High-priority items before considering the page complete.
5. Medium and Low items should be presented to the user for decision.

Do NOT skip this step. The page is not considered finished until the review passes.

Important Rules

• NEVER recreate shared components. Before building any custom UI element, check if @azure-fluent-storybook/components already provides it. Call getComponentList from Storybook MCP to verify. Read references/component-catalog.md.
• NEVER hardcode colors or fonts. Always use Fluent tokens.* values.
• NEVER skip the build report. The report is the final deliverable alongside the code.
• Use makeStyles for all styling. No inline CSS objects except for truly dynamic values.
• Match the exact portal look. If the user provides a screenshot, replicate it faithfully — icons, text, layout, spacing.
• Page background is always white (tokens.colorNeutralBackground1). Do not use grey or tinted backgrounds for the page body unless the user explicitly requests dark mode.
• ALWAYS use the iconcloud-browser skill for icons. When you need to find, search for, or download an icon (Azure service icon, Fluent icon, or any Microsoft icon), invoke the iconcloud-browser skill. Do NOT guess icon names, suggest icons from memory, or provide a text-based list of icon suggestions. The skill browses IconCloud.design to find the correct icon with its exact name, collection, and SVG. This applies to page icons, nav icons, command bar icons, and any other icon needed during page building.