Migrate the site theming MCP tool

[sf-cboscenco]

Summary

Adds the storefront_next_site_theming MCP tool for Storefront Next. The tool guides theming changes (colors, fonts, visual styling) and validates color combinations for WCAG 2.1 accessibility.

Testing

Tests are included in the PR, also manual test instructions are available in the Readme.md on the test path.

Dependencies

• No net-new third-party dependencies were added
• If net-new third-party dependencies were added, rationale/discussion is included and 3pl-approved is set by a maintainer

---

• Tests pass (pnpm test)
• Code is formatted (pnpm run format)

[sf-cboscenco]

Site Theming MCP Tool – Staged Changes Summary

Branch: feature-W-20796653-site-theming-mcp-tool
Date: 2025-02-25

Overview

Adds the storefront_next_site_theming MCP tool for Storefront Next. The tool guides theming changes (colors, fonts, visual styling) and validates color combinations for WCAG 2.1 accessibility.

---

Staged Files (15 files, +3,299 / -1 lines)

Changeset

File	Purpose
.changeset/site-theming-mcp-tool.md	Minor bump for @salesforce/b2c-dx-mcp; release notes

Documentation

File	Purpose
packages/b2c-dx-mcp/README.md	Site Theming section, prompt examples, tool table entry
packages/b2c-dx-mcp/src/tools/storefrontnext/README.md	Tool docs: parameters, returns, example usage, architecture

Content (3 files)

File	Purpose
content/site-theming/theming-accessibility.md	WCAG guidelines, contrast ratios, font accessibility, color blindness, focus/keyboard, screen readers
content/site-theming/theming-questions.md	Layout preservation, specification compliance, workflow (extraction, updating), DO/DON'T
content/site-theming/theming-validation.md	Validation gate workflow, pre-implementation checklist, color/font validation, how to trigger validation

Implementation (5 files)

File	Purpose
src/tools/storefrontnext/index.ts	Register createSiteThemingTool in STOREFRONTNEXT tools
src/tools/storefrontnext/site-theming/index.ts	Main tool: createSiteThemingTool, question flow, color validation, response generation
src/tools/storefrontnext/site-theming/theming-store.ts	Content loading, markdown parsing, THEMING_FILES env, init guard
src/tools/storefrontnext/site-theming/color-contrast.ts	WCAG 2.1 luminance, contrast ratio, validateContrast, validateColorCombinations
src/tools/storefrontnext/site-theming/README.md	Tool docs: overview, workflow, usage, architecture

Tests (4 files)

File	Purpose
test/tools/storefrontnext/site-theming/index.test.ts	Tool metadata, behavior, question filtering, color validation, file merging, edge cases
test/tools/storefrontnext/site-theming/color-contrast.test.ts	getLuminance, isValidHex, getContrastRatio, getWCAGLevel, validateContrast, formatValidationResult
test/tools/storefrontnext/site-theming/theming-store.test.ts	initialize, get/getKeys, loadFile, THEMING_FILES env, workflow/validation parsing
test/tools/storefrontnext/site-theming/README.md	Test instructions, manual scenarios

---

Key Features

• Mandatory workflow: Questions → validation → confirmation → implement
• WCAG validation: Automatic contrast checks when colorMapping is provided (colorMapping alone is sufficient)
• Content-driven: Markdown in content/site-theming/ drives questions and rules
• Merge support: fileKey / fileKeys for custom content; THEMING_FILES env
• Init guard: Skips re-loading when workspace root is unchanged
• Logger: Warnings use project logger instead of stderr

[yhsieh1]

@sf-cboscenco Could you pull changes from main and there is TF in this PR? Please attach a demo recording or screen shoot so we have better understanding how the tool interact with user.

[sf-cboscenco]

@sf-cboscenco Could you pull changes from main and there is TF in this PR? Please attach a demo recording or screen shoot so we have better understanding how the tool interact with user.

Done.

[yhsieh1]

It looks good to me.

[sf-cboscenco]

Demo videos provided by Madhuri Uppu, thank you:
https://drive.google.com/file/d/1-LpDeVDw6aKNYzcF_04UaqyjCWIdO0Y5/view?usp=sharing - cursor rules
https://drive.google.com/file/d/1VlEIklAbqw6moDOorLOed86RpzdjuWUG/view?usp=sharing - This is for the mcp tool (