Migrate the site theming MCP tool

.changeset/site-theming-mcp-tool.md

@@ -0,0 +1,9 @@
+---
+'@salesforce/b2c-dx-mcp': minor
+---
+
+Add `storefront_next_site_theming` MCP tool for Storefront Next theming
+
+- Provides theming guidelines, questions, and WCAG color contrast validation
+- Call this tool first when users request brand colors or theme changes
+- Validates color combinations for accessibility before implementation

docs/mcp/index.md

@@ -120,6 +120,7 @@ AI assistants automatically decide which MCP tools to use based on your prompts.
 **Storefront Next Development:**
 - ✅ "I'm new to Storefront Next. Use the MCP tool to show me the critical rules I need to know."
 - ✅ "I need to build a product detail page. Use the MCP tool to show me best practices for data fetching and component patterns."
+- ✅ "I want to apply my brand colors to my Storefront Next site. Use the MCP tool to help me."
 
 **SCAPI Discovery:**
 - ✅ "Use the MCP tool to list all available SCAPI schemas."

docs/mcp/tools/storefront-next-site-theming.md

@@ -0,0 +1,205 @@
+---
+description: Get theming guidelines, guided questions, and WCAG color contrast validation for Storefront Next.
+---
+
+# storefront_next_site_theming
+
+Guides theming changes (colors, fonts, visual styling) for Storefront Next and validates color combinations for WCAG accessibility. **Call this tool first** when the user wants to apply brand colors or change the site theme.
+
+## Overview
+
+The `storefront_next_site_theming` tool provides a structured workflow for applying theming to Storefront Next sites:
+
+1. **Guidelines** - Layout preservation rules, specification compliance, and accessibility requirements
+2. **Guided Questions** - Collects user preferences (colors, fonts, mappings) one at a time
+3. **WCAG Validation** - Automatically validates color contrast when `colorMapping` is provided
+
+The tool enforces a mandatory workflow: ask questions → validate colors → present findings → wait for confirmation → implement. Never implement theming changes without calling this tool first.
+
+## Authentication
+
+No authentication required. This tool operates on local content and returns guidance text.
+
+**Requirements:**
+- `--allow-non-ga-tools` flag (preview release)
+- Storefront Next project (for implementation; tool itself works without project)
+
+## Parameters
+
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `fileKeys` | string[] | No | File keys to add to the default set. Custom keys are merged with defaults: `theming-questions`, `theming-validation`, `theming-accessibility`. |
+| `conversationContext` | object | No | Context from previous rounds. Omit to list available files. See [Conversation Context](#conversation-context) for details. |
+
+### Conversation Context
+
+When using the tool across multiple turns, provide `conversationContext` with the following structure:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `currentStep` | `"updating-information"` \| `"validation"` | Current step in the workflow |
+| `collectedAnswers` | object | Previously collected answers. Include `colorMapping` to trigger automatic WCAG validation. |
+| `questionsAsked` | string[] | List of question IDs already asked |
+
+**collectedAnswers** can include:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `colors` | object[] | Extracted colors with `hex` and optional `type` |
+| `fonts` | object[] | Extracted fonts with `name` and optional `type` |
+| `colorMapping` | object | Maps color keys to hex values (for example, `lightText`, `lightBackground`, `buttonText`, `buttonBackground`). **Providing this triggers automatic WCAG contrast validation.** |
+
+## Operation Modes
+
+### List Available Files
+
+Call the tool without `conversationContext` (and without `fileKeys`) to list loaded theming file keys:
+
+```json
+{}
+```
+
+Returns the list of available keys. Default files are always used when `conversationContext` is provided.
+
+### Theming Workflow
+
+When `conversationContext` is provided, the tool returns guidelines and questions, or validation results when `colorMapping` is included.
+
+## Workflow
+
+### Phase 1: Information Gathering
+
+1. **First call** - Call the tool with `conversationContext.collectedAnswers` (can be empty `{colors: [], fonts: []}`)
+2. **Extract** - If the user provided colors/fonts in their message, extract and include in `collectedAnswers`
+3. **Ask questions** - Tool returns questions; ask the user one at a time and collect answers
+4. **Update** - Call the tool again with updated `collectedAnswers` after each user response
+
+### Phase 2: Validation (Mandatory)
+
+1. **Construct colorMapping** - Map each color to its usage (text, buttons, links, accents) based on user answers
+2. **Validation call** - Call the tool with `collectedAnswers.colorMapping` to trigger automatic WCAG validation
+3. **Present findings** - Show contrast ratios, WCAG status (AA/AAA/FAIL), and recommendations to the user
+4. **Wait for confirmation** - Do not implement until the user explicitly confirms
+
+### Phase 3: Implementation
+
+Only after completing Phases 1 and 2 may you apply theme changes to `app.css` (or project theme files).
+
+## Usage Examples
+
+### First Call - Get Guidelines and Questions
+
+```
+I want to apply my brand colors to my Storefront Next site. Use the MCP tool to help me.
+```
+
+**Example arguments:**
+
+```json
+{
+  "conversationContext": {
+    "collectedAnswers": {"colors": [], "fonts": []}
+  }
+}
+```
+
+### Validation Call - After Constructing colorMapping
+
+After collecting user answers, construct the color mapping and call the tool to validate.
+
+**Example arguments:**
+
+```json
+{
+  "conversationContext": {
+    "collectedAnswers": {
+      "colorMapping": {
+        "lightText": "#000000",
+        "lightBackground": "#FFFFFF",
+        "buttonText": "#FFFFFF",
+        "buttonBackground": "#0A2540"
+      }
+    }
+  }
+}
+```
+
+### With Pre-Provided Colors
+
+When the user provides colors upfront, extract and include them:
+
+```
+Use these colors: #635BFF (accent), #0A2540 (dark), #F6F9FC (brand), #FFFFFF (light). Use the MCP tool to guide me through theming.
+```
+
+**Example arguments:**
+
+```json
+{
+  "conversationContext": {
+    "collectedAnswers": {
+      "colors": [
+        {"hex": "#635BFF", "type": "accent"},
+        {"hex": "#0A2540", "type": "dark"},
+        {"hex": "#F6F9FC", "type": "brand"},
+        {"hex": "#FFFFFF", "type": "light"}
+      ]
+    }
+  }
+}
+```
+
+## Custom Theming Files
+
+You can add custom theming files via `fileKeys` or the `THEMING_FILES` environment variable. Custom files must follow a specific Markdown format so the parser can extract guidelines, questions, and validation rules.
+
+**Required heading patterns** (use these exact patterns for content to be parsed):
+
+- `## 🔄 WORKFLOW` - Workflow steps (numbered `1. Step text`)
+- `### 📝 EXTRACTION` - Extraction instructions
+- `### ✅ PRE-IMPLEMENTATION` - Pre-implementation checklist
+- `## ✅ VALIDATION` - Validation rules (with `### A. Color`, `### B. Font`, `### C. General`, `### IMPORTANT`)
+- `## ⚠️ CRITICAL: Title` - Critical guidelines
+- `## 📋 Title` - Specification rules
+- `### What TO Change:` / `### What NOT to Change:` - DO/DON'T rules (list items with `-`)
+
+**Questions**: Lines ending with `?` (length > 10) from bullet or numbered lists are extracted. Reference the built-in files in `content/site-theming/` for examples.
+
+## Rules and Constraints
+
+- `colorMapping` triggers automatic WCAG validation; `colors` and `fonts` arrays are optional when `colorMapping` is provided
+- `fileKeys` add to the default files; they do not replace them
+- Call the tool first before implementing any theming changes; never skip the question-answer or validation workflow
+- Theme changes apply to `app.css` (standalone: `src/app.css`; monorepo: `packages/template-retail-rsc-app/src/app.css`)
+
+## Output
+
+The tool returns text content that includes:
+
+- **Internal instructions** - Workflow steps, critical rules, validation requirements
+- **User-facing response** - What to say to the user, questions to ask
+- **Validation results** (when `colorMapping` provided) - Contrast ratios, WCAG compliance status, recommendations for failing combinations
+
+## Requirements
+
+- `--allow-non-ga-tools` flag (preview release)
+- Storefront Next project (for applying theme changes to `app.css`)
+
+## Features
+
+- **Mandatory workflow** - Ensures questions are asked and validation is performed before implementation
+- **Automatic WCAG validation** - Validates color contrast when `colorMapping` is provided
+- **Content-driven** - Loads guidance from markdown files (`theming-questions`, `theming-validation`, `theming-accessibility`)
+- **Layout preservation** - Guidelines enforce that only colors, typography, and visual styling change—never layout or positioning
+
+## Related Tools
+
+- Part of the [STOREFRONTNEXT](../toolsets#storefrontnext) toolset
+- Auto-enabled for Storefront Next projects (with `--allow-non-ga-tools`)
+- Related: [`storefront_next_development_guidelines`](../toolsets#storefrontnext) - Architecture and coding guidelines
+
+## See Also
+
+- [STOREFRONTNEXT Toolset](../toolsets#storefrontnext) - Overview of Storefront Next development tools
+- [Storefront Next Guide](../../guide/storefront-next) - Storefront Next development guide
+- [Configuration](../configuration) - Configure project directory

docs/mcp/toolsets.md

@@ -96,6 +96,7 @@ Storefront Next development tools for building modern storefronts.
 |------|-------------|---------------|
 | `storefront_next_development_guidelines` | Get Storefront Next development guidelines and best practices | — |
 | [`storefront_next_page_designer_decorator`](./tools/storefront-next-page-designer-decorator) | Add Page Designer decorators to Storefront Next components | [View details](./tools/storefront-next-page-designer-decorator) |
+| [`storefront_next_site_theming`](./tools/storefront-next-site-theming) | Get theming guidelines, questions, and WCAG color validation for Storefront Next | [View details](./tools/storefront-next-site-theming) |
 | [`scapi_schemas_list`](./tools/scapi-schemas-list) | List or fetch SCAPI schemas (standard and custom). Use apiFamily: "custom" for custom APIs. | [View details](./tools/scapi-schemas-list) |
 | [`scapi_custom_api_scaffold`](./tools/scapi-custom-api-scaffold) | Generate a new custom SCAPI endpoint (schema, api.json, script.js) in an existing cartridge. | [View details](./tools/scapi-custom-api-scaffold) |
 | [`scapi_custom_apis_status`](./tools/scapi-custom-apis-status) | Get registration status of custom API endpoints (active/not_registered). Remote only, requires OAuth. | [View details](./tools/scapi-custom-apis-status) |

packages/b2c-dx-mcp/.c8rc.json

@@ -1,7 +1,7 @@
 {
   "all": true,
   "src": ["src"],
-  "exclude": ["test/**", "**/*.d.ts", "**/index.ts"],
+  "exclude": ["test/**", "**/*.d.ts", "**/index.ts", "**/site-theming/types.ts"],
   "reporter": ["text", "text-summary", "html", "lcov"],
   "report-dir": "coverage",
   "check-coverage": true,

packages/b2c-dx-mcp/README.md

@@ -112,6 +112,15 @@ The `storefront_next_development_guidelines` tool provides critical architecture
 - `extensions` - Extension development
 - `pitfalls` - Common pitfalls
 
+##### Site Theming
+
+The `storefront_next_site_theming` tool guides theming changes (colors, fonts, visual styling) and validates color combinations for WCAG accessibility. **Use this tool first** when the user wants to apply brand colors or change the site theme.
+
+**Prompt examples:**
+- "I want to apply my brand colors to my Storefront Next site. Use the MCP tool to help me."
+- "Change the theme colors and fonts. Use the MCP tool to guide me through the process."
+- "Use the MCP tool to validate my color combinations for accessibility before I implement."
+
 ##### PWA Kit Development
 
 **Prompt examples:**
@@ -311,6 +320,7 @@ Storefront Next development tools for building modern storefronts.
 |------|-------------|
 | `storefront_next_development_guidelines` | Get Storefront Next development guidelines and best practices |
 | `storefront_next_page_designer_decorator` | Add Page Designer decorators to Storefront Next components |
+| `storefront_next_site_theming` | Get theming guidelines, questions, and WCAG color validation for Storefront Next |
 | `scapi_schemas_list` | List or fetch SCAPI schemas (standard and custom). Use apiFamily: "custom" for custom APIs. |
 | `scapi_custom_apis_status` | Get registration status of custom API endpoints (active/not_registered). Remote only, requires OAuth. |
 | `scapi_customapi_scaffold` | Generate a new custom SCAPI endpoint (OAS 3.0 schema, api.json, script.js) in an existing cartridge. Required: apiName. Optional: cartridgeName (defaults to first cartridge), apiType, apiDescription, projectRoot, outputDir. |

packages/b2c-dx-mcp/content/site-theming/theming-accessibility.md

@@ -0,0 +1,126 @@
+---
+description: Accessibility guidelines and WCAG compliance rules for theming
+alwaysApply: false
+---
+# Accessibility Guidelines for Theming
+
+## 🎯 Accessibility Requirements
+
+**All theming implementations MUST comply with WCAG 2.1 Level AA standards at minimum.**
+
+### Color Contrast Requirements
+
+**WCAG 2.1 Contrast Ratios:**
+- **Normal text (16px and below)**: Minimum 4.5:1 contrast ratio
+- **Large text (18pt+ or 14pt+ bold)**: Minimum 3:1 contrast ratio
+- **AAA compliance (recommended)**: 7:1 for normal text, 4.5:1 for large text
+
+**Critical Color Combinations to Validate:**
+1. Primary text on primary background
+2. Secondary text on secondary background
+3. Button text on button background
+4. Link text on page background
+5. Accent colors on all background variations
+6. Muted text on muted backgrounds
+7. Border colors against adjacent backgrounds
+
+### Visual Hierarchy and Readability
+
+**Text Readability:**
+- Ensure sufficient contrast for all text sizes
+- Avoid using similar brightness levels for text and background
+- Test color combinations in both light and dark themes
+- Consider users with color vision deficiencies
+
+**Interactive Elements:**
+- Buttons must have clear visual distinction from backgrounds
+- Hover states must maintain or improve contrast
+- Focus indicators must be clearly visible (minimum 3:1 contrast)
+- Disabled states should still be readable (minimum 3:1 contrast)
+
+### Font Accessibility
+
+**Font Readability Requirements:**
+- Body text should use fonts optimized for screen reading
+- Minimum font size: 16px for body text (recommended)
+- Line height: Minimum 1.5 for body text
+- Letter spacing: Ensure adequate spacing for readability
+- Font weights: Ensure sufficient contrast between weights
+
+**Font Loading Performance:**
+- Web fonts should not block rendering
+- Provide appropriate fallback fonts
+- Consider font-display: swap for better performance
+- Test font loading on slow connections
+
+### Color Vision Deficiency Considerations
+
+**Design for Color Blindness:**
+- Don't rely solely on color to convey information
+- Use patterns, icons, or text labels in addition to color
+- Test color combinations with color blindness simulators
+- Ensure sufficient contrast even when colors are desaturated
+
+**Common Color Blindness Types:**
+- Protanopia (red-blind)
+- Deuteranopia (green-blind)
+- Tritanopia (blue-blind)
+- Monochromacy (total color blindness)
+
+### Focus and Keyboard Navigation
+
+**Focus Indicators:**
+- All interactive elements must have visible focus indicators
+- Focus indicators must have minimum 3:1 contrast ratio
+- Focus indicators should be at least 2px thick
+- Use outline or border to indicate focus state
+
+**Keyboard Accessibility:**
+- All interactive elements must be keyboard accessible
+- Tab order should be logical and intuitive
+- Skip links should be provided for long pages
+- Focus trap should be implemented in modals
+
+### Screen Reader Considerations
+
+**Semantic HTML:**
+- Use proper heading hierarchy (h1-h6)
+- Use semantic HTML elements (nav, main, article, etc.)
+- Provide alt text for images
+- Use ARIA labels when necessary
+
+**Color and Screen Readers:**
+- Screen readers don't convey color information
+- Ensure information is accessible without color
+- Use text labels, icons, or patterns in addition to color
+
+### Testing and Validation
+
+**Required Testing:**
+1. Automated contrast checking (WCAG AA/AAA)
+2. Manual visual inspection
+3. Color blindness simulator testing
+4. Screen reader testing
+5. Keyboard navigation testing
+
+**Tools for Validation:**
+- Color contrast analyzers (WebAIM, WAVE)
+- Color blindness simulators
+- Screen reader testing (NVDA, JAWS, VoiceOver)
+- Browser accessibility inspectors
+
+### Implementation Guidelines
+
+**When Implementing Themes:**
+1. Always validate color contrast ratios before implementation
+2. Test with multiple color combinations
+3. Provide alternative color suggestions if contrast fails
+4. Document accessibility decisions
+5. Test with assistive technologies
+
+**If Accessibility Issues Are Found:**
+- Present findings clearly to the user
+- Provide specific contrast ratios and WCAG compliance status
+- Suggest concrete alternatives with improved contrast
+- Explain the accessibility impact
+- Wait for user confirmation before proceeding