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

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:**
@@ -301,6 +310,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. |
 | `mrt_bundle_push` | Build, push bundle (optionally deploy) |

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

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

@@ -0,0 +1,208 @@
+---
+description: Theming questions and information gathering guidelines
+alwaysApply: false
+---
+# Theming Questions and Information Gathering
+
+## ⚠️ CRITICAL: Layout Preservation Rules
+
+**NEVER modify positioning, layout, or structural CSS properties when applying theming changes. Only change colors, typography, and visual styling.**
+
+### What NOT to Change:
+- `position` properties (fixed, absolute, relative)
+- `top`, `left`, `right`, `bottom` positioning
+- `margin` and `padding` values
+- `width`, `height`, `min-height`, `max-height`
+- `display` properties (flex, grid, block)
+- `z-index` values (unless specifically requested)
+- `transform` properties
+- Grid/flexbox layout properties
+
+### What TO Change:
+- `color`, `background-color`, `border-color`
+- `text-decoration`, `font-weight`, `font-size`
+- `opacity`, `box-shadow`, `border-radius`
+- CSS custom properties (CSS variables)
+- Hover states and transitions
+- Theme-specific styling
+
+### Example of CORRECT theming:
+```css
+/* ✅ CORRECT - Only changing colors and visual styling */
+.navigation-item {
+  color: var(--foreground);
+  background-color: var(--background);
+  border-color: var(--border);
+  transition: color 0.2s ease;
+}
+
+.navigation-item:hover {
+  color: var(--accent);
+  background-color: var(--accent/10);
+}
+```
+
+### Example of INCORRECT theming:
+```css
+/* ❌ INCORRECT - Changing layout/positioning */
+.navigation-item {
+  margin-left: 20px; /* DON'T change margins */
+  position: relative; /* DON'T change positioning */
+  z-index: 100; /* DON'T change z-index */
+  width: 200px; /* DON'T change dimensions */
+}
+```
+
+### When Layout Changes Are Needed:
+If layout modifications are required, they should be:
+1. Explicitly requested by the user
+2. Clearly separated from theming changes
+3. Documented as layout fixes, not theming
+4. Tested thoroughly for responsive behavior
+
+## 📋 Specification Compliance Rules
+
+**ALWAYS follow user specifications exactly. Never make assumptions or interpretations.**
+
+### ⚠️ **CRITICAL: WAIT FOR USER RESPONSE RULE**
+
+**NEVER implement changes after asking clarifying questions without waiting for the user's response.**
+
+**Required Process:**
+1. Ask clarifying questions
+2. **WAIT for user response** ⚠️ **CRITICAL STEP**
+3. Only implement after receiving explicit guidance
+4. Never proceed with assumptions
+
+**Violations:**
+- ❌ Ask questions then immediately implement
+- ❌ Make assumptions about color/font mapping
+- ❌ Proceed without explicit user guidance
+- ❌ Implement "best guess" solutions
+
+### ✅ **Color Specification Rules:**
+1. **Use exact hex values** provided by the user
+2. **Ask for clarification** on color type mapping (e.g., "brand" vs "accent")
+3. **Propose color combinations** before implementing:
+   - Which color should be primary vs secondary?
+   - How should "brand" colors be used vs "accent" colors?
+   - Should "dark" colors be used for text or backgrounds?
+   - What should be the hover state colors?
+4. **Never assume** color usage without explicit user guidance
+
+### ✅ **Font Specification Rules:**
+1. **Use exact font names** as provided by the user
+2. **Ask for clarification** if font names are unclear or unfamiliar
+3. **Verify font availability** before implementing
+4. **Never substitute** similar fonts without user permission
+
+### ✅ **General Specification Rules:**
+1. **Follow exact specifications** without interpretation
+2. **Ask clarifying questions** when specifications are ambiguous
+3. **Propose implementation approaches** before making changes
+4. **Confirm understanding** of requirements before proceeding
+
+### Example of CORRECT specification handling:
+```
+User: "Use these colors: #635BFF (accent), #0A2540 (dark), #F6F9FC (brand), #FFFFFF (light)"
+
+AI Response: "I see you've provided 4 colors. Before implementing, I'd like to clarify:
+- Should #635BFF be used for primary actions and hover states?
+- Should #0A2540 be used for text color or background?
+- Should #F6F9FC be used for secondary elements or primary branding?
+- What should be the light theme vs dark theme color mapping?"
+
+[WAITS for user response before implementing]
+```
+
+### Example of INCORRECT specification handling:
+```
+❌ DON'T: Assume "sohne-var" means "Sohne" font
+❌ DON'T: Guess color usage without asking
+❌ DON'T: Make assumptions about font weights or styles
+❌ DON'T: Implement without confirming understanding
+❌ DON'T: Ask clarifying questions then immediately implement
+```
+
+## 🔄 WORKFLOW - PHASE 1: INFORMATION GATHERING
+
+**YOU MUST FOLLOW THIS WORKFLOW - NO EXCEPTIONS:**
+
+1. **DO NOT implement any changes yet**
+2. **Ask the questions below ONE AT A TIME**
+3. **WAIT for the user's response** before asking the next question
+4. **Only proceed after ALL required questions are answered**
+5. **Even if the user provided colors/fonts upfront, you MUST still ask ALL these clarifying questions**
+   - Colors provided? Still ask about color mapping, usage, hover states, etc.
+   - Fonts provided? Still ask about font usage, availability, headings vs body, etc.
+6. **You MUST ask questions from ALL categories (colors, fonts, general) - do not skip any**
+
+**VIOLATION OF THIS WORKFLOW IS A CRITICAL ERROR.**
+
+### 📝 EXTRACTION
+
+**BEFORE generating questions, you MUST extract and provide the theming information from the user's input.**
+
+1. **Review the user's input** carefully for any theming information:
+   - Colors (hex values like "#635BFF", color types like "accent", "primary", "dark", "light")
+   - Fonts (font names like "Sohne Var", font types like "title", "body", "heading")
+   - Any other theming preferences (spacing, sizes, etc.)
+
+2. **Extract and structure the information** in the following format:
+   - Colors: Array of objects with `hex` (string) and `type` (string, optional) properties
+   - Fonts: Array of objects with `name` (string) and `type` (string, optional) properties
+   - Other info: Key-value pairs as needed
+
+3. **Call this tool again** with the extracted information in `conversationContext.collectedAnswers`:
+   ```
+   {
+     conversationContext: {
+       collectedAnswers: {
+         colors: [{ hex: "#635BFF", type: "accent" }, { hex: "#0A2540", type: "dark" }, ...],
+         fonts: [{ name: "Sohne Var", type: "title" }, ...],
+         // ... other info
+       }
+     }
+   }
+   ```
+
+4. **Only after providing this information** will the tool generate the appropriate questions.
+
+**IMPORTANT:**
+- If the user did NOT mention colors or fonts, you can still call the tool with empty arrays or skip this step
+- But if the user DID mention colors/fonts, you MUST extract them before proceeding
+- **DO NOT proceed with questions until you have extracted and provided the theming information.**
+
+### 🔄 UPDATING INFORMATION (MANDATORY)
+
+**⚠️ CRITICAL: Whenever the user provides NEW or UPDATED theming information, you MUST call the tool again with the updated information.**
+
+**This applies to:** New/updated colors, fonts, color mappings, or any theming preferences.
+
+**Required Process:**
+1. Extract the new/updated information from the user's message
+2. Merge with ALL previously collected information (include everything, not just new data)
+3. Call the `site_theming` tool IMMEDIATELY with complete updated information
+4. If `colorMapping` is provided, validation will trigger automatically (see validation phase)
+
+**Tool call structure:**
+```
+{
+  conversationContext: {
+    currentStep: "updating-information" | "validation",
+    collectedAnswers: {
+      colors: [...all colors, including previous and new...],
+      fonts: [...all fonts, including previous and new...],
+      colorMapping: {...all mappings, including previous and updated...},
+      // ... all other collected information
+    },
+    questionsAsked: [...previous questions...]
+  }
+}
+```
+
+**⚠️ CRITICAL RULES:**
+- Every update requires a new tool call (not optional)
+- Include ALL previously collected information in each call
+- If user provides `colorMapping`, it triggers automatic validation
+- DO NOT implement without calling the tool with updated information first