Dev Guides — Claude Code Development Reference

Savoy Signature Hotels — Multi-Site Headless Platform
Purpose: Actionable development guides for AI-assisted (Claude Code) and human FE development
Phase Focus: Phase 1 — Design System + Figma-to-FE Integration

---

Guide Index

Guide	Filename	Focus
00	00_INDEX.md	This index
01	01_FIGMA_TO_CODE_WORKFLOW.md	End-to-end workflow from Figma design to production component
02	02_DESIGN_TOKENS_EXTRACTION.md	How to extract, name, and implement design tokens from Figma
03	03_MODULE_DEVELOPMENT_LIFECYCLE.md	Step-by-step guide for creating a new module (M01-Mxx)
04	04_STORYBOOK_FIRST_DEVELOPMENT.md	Developing and validating components in Storybook before integration
05	05_BEM_SASS_THEMING.md	BEM + SASS conventions, CSS variables, and multi-theme support
06	06_RESPONSIVE_IMAGES_PATTERN.md	Desktop + Mobile image handling with ResponsiveImage component
07	07_CLAUDE_PROMPTING_CONVENTIONS.md	How to prompt Claude Code for this project: context, patterns, and examples
09	09_GIT_WORKFLOW.md	Branch naming, git worktree isolation, and PR-to-develop workflow

---

How to Use These Guides

For Claude Code (AI Agent)

These guides serve as the operational manual when implementing FE tasks. Before starting any module or component:

1. Read the relevant PRD document (e.g., docs/PRD/07_Modules_and_Templates.md)
2. Read the corresponding dev guide for the workflow you’re executing
3. Follow the file conventions, naming patterns, and acceptance criteria exactly

For Human Developers

These guides document the team’s conventions for the Savoy project. They complement the PRD (which defines what to build) by explaining how to build it consistently.

---

Relationship to PRD

PRD Document	Related Dev Guide(s)
04_Frontend_Architecture.md	01, 03, 05
05_Design_System_and_Theming.md	02, 04, 05
07_Modules_and_Templates.md	01, 03, 04, 06
13_Media_and_Image_Pipeline.md	06
14_Accessibility_and_Compliance.md	03, 04
18_QA_Pipeline_and_Testing.md	03, 04 (+ Pixel Perfect visual testing)

---

Phase 1 Priority Order

For Phase 1 (Design System + Core Modules), follow these guides in order:

1. 02 Design Tokens — Extract tokens from Figma, create _base.css + 8 theme files
2. 05 BEM + SASS + Theming — Understand the CSS architecture before writing any component
3. 04 Storybook-First — Set up Storybook with theme decorator, validate tokens visually
4. 01 Figma-to-Code — Full workflow for converting a Figma screen to a module
5. 03 Module Lifecycle — Detailed module creation checklist (M01-M06 first)
6. 06 Responsive Images — Implement desktop/mobile image pattern
7. 07 Claude Conventions — Reference for AI-assisted implementation sessions
8. 09 Git Workflow — Branch-per-feature, worktree isolation, PR to develop

Mandatory Visual Testing

Every module MUST pass Pixel Perfect visual tests before merging. This is an absolute rule enforced across all development:

• Initial development: Rendered stories are compared against Figma baselines (screenshot comparison)
• Ongoing development: Code changes are validated against regression baselines
• Tool: Pixel Perfect addon in Storybook (custom panel with KPIs, diff viewer, baseline management)
• Command: pnpm --filter storybook visual:test
• Guides: See 03_MODULE_DEVELOPMENT_LIFECYCLE.md Step 8 and 04_STORYBOOK_FIRST_DEVELOPMENT.md Section 11