|
| 1 | +--- |
| 2 | +description: Get theming guidelines, guided questions, and WCAG color contrast validation for Storefront Next. |
| 3 | +--- |
| 4 | + |
| 5 | +# storefront_next_site_theming |
| 6 | + |
| 7 | +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. |
| 8 | + |
| 9 | +## Overview |
| 10 | + |
| 11 | +The `storefront_next_site_theming` tool provides a structured workflow for applying theming to Storefront Next sites: |
| 12 | + |
| 13 | +1. **Guidelines** - Layout preservation rules, specification compliance, and accessibility requirements |
| 14 | +2. **Guided Questions** - Collects user preferences (colors, fonts, mappings) one at a time |
| 15 | +3. **WCAG Validation** - Automatically validates color contrast when `colorMapping` is provided |
| 16 | + |
| 17 | +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. |
| 18 | + |
| 19 | +## Authentication |
| 20 | + |
| 21 | +No authentication required. This tool operates on local content and returns guidance text. |
| 22 | + |
| 23 | +**Requirements:** |
| 24 | +- `--allow-non-ga-tools` flag (preview release) |
| 25 | +- Storefront Next project (for implementation; tool itself works without project) |
| 26 | + |
| 27 | +## Parameters |
| 28 | + |
| 29 | +| Parameter | Type | Required | Description | |
| 30 | +|-----------|------|----------|-------------| |
| 31 | +| `fileKeys` | string[] | No | File keys to add to the default set. Custom keys are merged with defaults: `theming-questions`, `theming-validation`, `theming-accessibility`. | |
| 32 | +| `conversationContext` | object | No | Context from previous rounds. Omit to list available files. See [Conversation Context](#conversation-context) for details. | |
| 33 | + |
| 34 | +### Conversation Context |
| 35 | + |
| 36 | +When using the tool across multiple turns, provide `conversationContext` with the following structure: |
| 37 | + |
| 38 | +| Field | Type | Description | |
| 39 | +|-------|------|-------------| |
| 40 | +| `currentStep` | `"updating-information"` \| `"validation"` | Current step in the workflow | |
| 41 | +| `collectedAnswers` | object | Previously collected answers. Include `colorMapping` to trigger automatic WCAG validation. | |
| 42 | +| `questionsAsked` | string[] | List of question IDs already asked | |
| 43 | + |
| 44 | +**collectedAnswers** can include: |
| 45 | + |
| 46 | +| Field | Type | Description | |
| 47 | +|-------|------|-------------| |
| 48 | +| `colors` | object[] | Extracted colors with `hex` and optional `type` | |
| 49 | +| `fonts` | object[] | Extracted fonts with `name` and optional `type` | |
| 50 | +| `colorMapping` | object | Maps color keys to hex values (for example, `lightText`, `lightBackground`, `buttonText`, `buttonBackground`). **Providing this triggers automatic WCAG contrast validation.** | |
| 51 | + |
| 52 | +## Operation Modes |
| 53 | + |
| 54 | +### List Available Files |
| 55 | + |
| 56 | +Call the tool without `conversationContext` (and without `fileKeys`) to list loaded theming file keys: |
| 57 | + |
| 58 | +```json |
| 59 | +{} |
| 60 | +``` |
| 61 | + |
| 62 | +Returns the list of available keys. Default files are always used when `conversationContext` is provided. |
| 63 | + |
| 64 | +### Theming Workflow |
| 65 | + |
| 66 | +When `conversationContext` is provided, the tool returns guidelines and questions, or validation results when `colorMapping` is included. |
| 67 | + |
| 68 | +## Workflow |
| 69 | + |
| 70 | +### Phase 1: Information Gathering |
| 71 | + |
| 72 | +1. **First call** - Call the tool with `conversationContext.collectedAnswers` (can be empty `{colors: [], fonts: []}`) |
| 73 | +2. **Extract** - If the user provided colors/fonts in their message, extract and include in `collectedAnswers` |
| 74 | +3. **Ask questions** - Tool returns questions; ask the user one at a time and collect answers |
| 75 | +4. **Update** - Call the tool again with updated `collectedAnswers` after each user response |
| 76 | + |
| 77 | +### Phase 2: Validation (Mandatory) |
| 78 | + |
| 79 | +1. **Construct colorMapping** - Map each color to its usage (text, buttons, links, accents) based on user answers |
| 80 | +2. **Validation call** - Call the tool with `collectedAnswers.colorMapping` to trigger automatic WCAG validation |
| 81 | +3. **Present findings** - Show contrast ratios, WCAG status (AA/AAA/FAIL), and recommendations to the user |
| 82 | +4. **Wait for confirmation** - Do not implement until the user explicitly confirms |
| 83 | + |
| 84 | +### Phase 3: Implementation |
| 85 | + |
| 86 | +Only after completing Phases 1 and 2 may you apply theme changes to `app.css` (or project theme files). |
| 87 | + |
| 88 | +## Usage Examples |
| 89 | + |
| 90 | +### Example Prompts (Natural Language) |
| 91 | + |
| 92 | +Try these prompts to get started: |
| 93 | + |
| 94 | +| Goal | Example prompt | |
| 95 | +|------|----------------| |
| 96 | +| Start theming from scratch | "I want to apply my brand colors to my Storefront Next site. Use the MCP tool to help me." | |
| 97 | +| Validate before implementing | "I have a color scheme ready. Use the MCP tool to validate my colors for accessibility before I implement." | |
| 98 | +| Colors + fonts upfront | "Use these colors: #635BFF (accent), #0A2540 (dark). Font: Inter. Use the MCP tool to guide me through theming." | |
| 99 | +| Check accessibility only | "Use the MCP tool to validate these color combinations for WCAG: light text #333 on background #FFF, button #0A2540 with white text." | |
| 100 | +| Change existing theme | "I want to change my site theme. Use the MCP tool to walk me through the process." | |
| 101 | +| List available content | "What theming files does the MCP tool have? Use the tool to list them." | |
| 102 | + |
| 103 | +### First Call - Get Guidelines and Questions |
| 104 | + |
| 105 | +``` |
| 106 | +I want to apply my brand colors to my Storefront Next site. Use the MCP tool to help me. |
| 107 | +``` |
| 108 | + |
| 109 | +**Example arguments:** |
| 110 | + |
| 111 | +```json |
| 112 | +{ |
| 113 | + "conversationContext": { |
| 114 | + "collectedAnswers": {"colors": [], "fonts": []} |
| 115 | + } |
| 116 | +} |
| 117 | +``` |
| 118 | + |
| 119 | +### Validation Call - After Constructing colorMapping |
| 120 | + |
| 121 | +After collecting user answers, construct the color mapping and call the tool to validate. |
| 122 | + |
| 123 | +**Minimal colorMapping (light theme only):** |
| 124 | + |
| 125 | +```json |
| 126 | +{ |
| 127 | + "conversationContext": { |
| 128 | + "collectedAnswers": { |
| 129 | + "colorMapping": { |
| 130 | + "lightText": "#000000", |
| 131 | + "lightBackground": "#FFFFFF", |
| 132 | + "buttonText": "#FFFFFF", |
| 133 | + "buttonBackground": "#0A2540" |
| 134 | + } |
| 135 | + } |
| 136 | + } |
| 137 | +} |
| 138 | +``` |
| 139 | + |
| 140 | +**Full colorMapping (light + dark theme):** |
| 141 | + |
| 142 | +```json |
| 143 | +{ |
| 144 | + "conversationContext": { |
| 145 | + "collectedAnswers": { |
| 146 | + "colorMapping": { |
| 147 | + "lightText": "#171717", |
| 148 | + "lightBackground": "#FFFFFF", |
| 149 | + "darkText": "#FAFAFA", |
| 150 | + "darkBackground": "#0A0A0A", |
| 151 | + "buttonText": "#FFFFFF", |
| 152 | + "buttonBackground": "#0A2540", |
| 153 | + "linkColor": "#2563EB", |
| 154 | + "accent": "#635BFF" |
| 155 | + } |
| 156 | + } |
| 157 | + } |
| 158 | +} |
| 159 | +``` |
| 160 | + |
| 161 | +### With Pre-Provided Colors |
| 162 | + |
| 163 | +When the user provides colors upfront, extract and include them: |
| 164 | + |
| 165 | +``` |
| 166 | +Use these colors: #635BFF (accent), #0A2540 (dark), #F6F9FC (brand), #FFFFFF (light). Use the MCP tool to guide me through theming. |
| 167 | +``` |
| 168 | + |
| 169 | +**Example arguments:** |
| 170 | + |
| 171 | +```json |
| 172 | +{ |
| 173 | + "conversationContext": { |
| 174 | + "collectedAnswers": { |
| 175 | + "colors": [ |
| 176 | + {"hex": "#635BFF", "type": "accent"}, |
| 177 | + {"hex": "#0A2540", "type": "dark"}, |
| 178 | + {"hex": "#F6F9FC", "type": "brand"}, |
| 179 | + {"hex": "#FFFFFF", "type": "light"} |
| 180 | + ] |
| 181 | + } |
| 182 | + } |
| 183 | +} |
| 184 | +``` |
| 185 | + |
| 186 | +### With Pre-Provided Fonts |
| 187 | + |
| 188 | +When the user specifies fonts: |
| 189 | + |
| 190 | +``` |
| 191 | +I want to use Inter for body text and Playfair Display for headings. Use the MCP tool to help me theme my site. |
| 192 | +``` |
| 193 | + |
| 194 | +**Example arguments:** |
| 195 | + |
| 196 | +```json |
| 197 | +{ |
| 198 | + "conversationContext": { |
| 199 | + "collectedAnswers": { |
| 200 | + "colors": [], |
| 201 | + "fonts": [ |
| 202 | + {"name": "Inter", "type": "body"}, |
| 203 | + {"name": "Playfair Display", "type": "heading"} |
| 204 | + ] |
| 205 | + } |
| 206 | + } |
| 207 | +} |
| 208 | +``` |
| 209 | + |
| 210 | +### Mid-Conversation Update |
| 211 | + |
| 212 | +When the user answers a question and provides new information, merge it into `collectedAnswers` and call again: |
| 213 | + |
| 214 | +```json |
| 215 | +{ |
| 216 | + "conversationContext": { |
| 217 | + "collectedAnswers": { |
| 218 | + "colors": [{"hex": "#635BFF", "type": "accent"}], |
| 219 | + "fonts": [], |
| 220 | + "color-1": "primary action buttons", |
| 221 | + "color-2": "links and hover states" |
| 222 | + }, |
| 223 | + "questionsAsked": ["color-1", "color-2"] |
| 224 | + } |
| 225 | +} |
| 226 | +``` |
| 227 | + |
| 228 | +### List Available Files (No Context) |
| 229 | + |
| 230 | +Call with empty arguments to list loaded theming file keys: |
| 231 | + |
| 232 | +```json |
| 233 | +{} |
| 234 | +``` |
| 235 | + |
| 236 | +Returns available keys such as `theming-questions`, `theming-validation`, `theming-accessibility`. |
| 237 | + |
| 238 | +## Custom Theming Files |
| 239 | + |
| 240 | +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. |
| 241 | + |
| 242 | +**Required heading patterns** (use these exact patterns for content to be parsed): |
| 243 | + |
| 244 | +- `## 🔄 WORKFLOW` - Workflow steps (numbered `1. Step text`) |
| 245 | +- `### 📝 EXTRACTION` - Extraction instructions |
| 246 | +- `### ✅ PRE-IMPLEMENTATION` - Pre-implementation checklist |
| 247 | +- `## ✅ VALIDATION` - Validation rules (with `### A. Color`, `### B. Font`, `### C. General`, `### IMPORTANT`) |
| 248 | +- `## ⚠️ CRITICAL: Title` - Critical guidelines |
| 249 | +- `## 📋 Title` - Specification rules |
| 250 | +- `### What TO Change:` / `### What NOT to Change:` - DO/DON'T rules (list items with `-`) |
| 251 | + |
| 252 | +**Questions**: Lines ending with `?` (length > 10) from bullet or numbered lists are extracted. Reference the built-in files in `content/site-theming/` for examples. |
| 253 | + |
| 254 | +## Rules and Constraints |
| 255 | + |
| 256 | +- `colorMapping` triggers automatic WCAG validation; `colors` and `fonts` arrays are optional when `colorMapping` is provided |
| 257 | +- `fileKeys` add to the default files; they do not replace them |
| 258 | +- Call the tool first before implementing any theming changes; never skip the question-answer or validation workflow |
| 259 | +- Theme changes apply to `app.css` (standalone: `src/app.css`; monorepo: `packages/template-retail-rsc-app/src/app.css`) |
| 260 | + |
| 261 | +## Output |
| 262 | + |
| 263 | +The tool returns text content that includes: |
| 264 | + |
| 265 | +- **Internal instructions** - Workflow steps, critical rules, validation requirements |
| 266 | +- **User-facing response** - What to say to the user, questions to ask |
| 267 | +- **Validation results** (when `colorMapping` provided) - Contrast ratios, WCAG compliance status, recommendations for failing combinations |
| 268 | + |
| 269 | +## Requirements |
| 270 | + |
| 271 | +- `--allow-non-ga-tools` flag (preview release) |
| 272 | +- Storefront Next project (for applying theme changes to `app.css`) |
| 273 | + |
| 274 | +## Features |
| 275 | + |
| 276 | +- **Mandatory workflow** - Ensures questions are asked and validation is performed before implementation |
| 277 | +- **Automatic WCAG validation** - Validates color contrast when `colorMapping` is provided |
| 278 | +- **Content-driven** - Loads guidance from markdown files (`theming-questions`, `theming-validation`, `theming-accessibility`) |
| 279 | +- **Layout preservation** - Guidelines enforce that only colors, typography, and visual styling change—never layout or positioning |
| 280 | + |
| 281 | +## Related Tools |
| 282 | + |
| 283 | +- Part of the [STOREFRONTNEXT](../toolsets#storefrontnext) toolset |
| 284 | +- Auto-enabled for Storefront Next projects (with `--allow-non-ga-tools`) |
| 285 | +- Related: [`storefront_next_development_guidelines`](../toolsets#storefrontnext) - Architecture and coding guidelines |
| 286 | + |
| 287 | +## See Also |
| 288 | + |
| 289 | +- [STOREFRONTNEXT Toolset](../toolsets#storefrontnext) - Overview of Storefront Next development tools |
| 290 | +- [Storefront Next Guide](../../guide/storefront-next) - Storefront Next development guide |
| 291 | +- [Configuration](../configuration) - Configure project directory |
0 commit comments