07 — Claude Code Prompting Conventions

Dev Guide — Savoy Signature Hotels
Purpose: How to effectively prompt Claude Code for tasks on this project

---

1. Purpose

This guide defines how to structure prompts for Claude Code when working on the Savoy platform. Well-structured prompts produce consistent, PRD-aligned output. Poorly structured prompts produce code that doesn’t follow project conventions.

---

2. Context Loading

Before any implementation task, Claude Code should read the relevant context files. Here’s the recommended reading order based on task type:

Creating a New Module

1. docs/PRD/07_Modules_and_Templates.md — Module conventions, file structure
2. docs/dev-guides/03_MODULE_DEVELOPMENT_LIFECYCLE.md — Step-by-step checklist
3. docs/dev-guides/05_BEM_SASS_THEMING.md — CSS conventions
4. docs/dev-guides/06_RESPONSIVE_IMAGES_PATTERN.md — If module has images
5. The specific module spec from A04_Module_Catalog.md (if available)

Working on Design Tokens / Theming

1. docs/PRD/05_Design_System_and_Theming.md — Token architecture
2. docs/dev-guides/02_DESIGN_TOKENS_EXTRACTION.md — Extraction process
3. packages/themes/src/_base.css — Current shared tokens
4. packages/themes/src/{theme}.css — Current theme tokens

Setting Up Storybook

1. docs/dev-guides/04_STORYBOOK_FIRST_DEVELOPMENT.md — Full guide
2. apps/storybook/.storybook/ — Current config files

Working on Routing / Data Fetching

1. docs/PRD/04_Frontend_Architecture.md — App structure, routing, data fetching
2. docs/PRD/01_General_Architecture.md — System overview, ADRs
3. docs/PRD/08_API_Contracts.md — API contracts

---

3. Prompt Templates

3.1 Create a New Module

Create module M{XX} — {Module Name} following the Savoy conventions.

Specs:
- Server/Client: {Server | Client}
- Figma: {link or description}
- Props: {list key props}
- Responsive: {describe responsive behavior}
- Interactions: {if Client Component, describe interactions}

Follow the module lifecycle from docs/dev-guides/03_MODULE_DEVELOPMENT_LIFECYCLE.md.
Create all files: types, component, scss (BEM), mapper, stories, tests, index.
Use CSS variables from packages/themes for all visual values.
Use ResponsiveImage for all images (desktop + mobile variants).

3.2 Extract Design Tokens from Figma

Extract design tokens for the {Hotel Name} theme from the Figma design.

Colors identified:
- Primary: #{hex}
- Secondary: #{hex}
- Background: #{hex}
- Text: #{hex}
{... list all colors}

Fonts:
- Heading: {font name}
- Body: {font name}

Create the theme file at packages/themes/src/{theme-key}.css following
the token naming convention from docs/dev-guides/02_DESIGN_TOKENS_EXTRACTION.md.
Also register the fonts in apps/web/src/lib/fonts.ts.

3.3 Add a Storybook Story

Add Storybook stories for {Component Name} following the Savoy conventions.

Include variants: Default, WithOptionalProps, MinimalContent, EmptyState.
Use realistic hotel mock data (not placeholder text).
Link to Figma: {url}
Follow docs/dev-guides/04_STORYBOOK_FIRST_DEVELOPMENT.md for conventions.

3.4 Fix/Modify an Existing Module

Modify module M{XX} — {Module Name}.

Change: {describe what needs to change}
Reason: {why}

Ensure:
- BEM class naming still correct
- All CSS values use tokens (no hardcoded values)
- Stories updated to cover the change
- Tests updated if mapper logic changed
- Works in all 8 themes

---

4. Key Rules for Claude Code on This Project

Always Do:

• Read the relevant PRD document before implementing
• Use CSS custom properties (var(--token)) for ALL visual values
• Use BEM naming (.block__element--modifier) for CSS classes
• Use SASS .scss files with & nesting
• Create imageDesktop + imageMobile for all image props
• Use ResponsiveImage from @savoy/ui for images
• Default to Server Components; only use Client when interaction requires it
• Include siteKey and locale in all module props
• Write data-module + data-module-id attributes on the module’s root <section>
• Use semantic HTML elements (<section>, <article>, <nav>, <h2>)

Never Do:

• Hardcode colors, fonts, spacing, or shadows
• Use CSS Modules (.module.css) — use BEM + SASS
• Use @extend in SASS
• Nest CSS more than 3 levels deep
• Import one module inside another module
• Use @media (max-width) — always mobile-first with min-width
• Use !important
• Skip Storybook stories
• Use inline styles for theme values
• Use SASS variables ($var) for theme tokens

---

5. Project File Reference

Quick reference for where things live:

What	Where
PRD documents	docs/PRD/
Dev guides	docs/dev-guides/
Next.js app	apps/web/
Storybook app	apps/storybook/
UI components	packages/ui/src/
CMS modules	packages/modules/src/
Theme tokens	packages/themes/src/
CMS client	packages/cms-client/src/
Shared utils	packages/utils/src/
Module registry	packages/modules/src/registry.ts
Font config	apps/web/src/lib/fonts.ts
Site resolver	apps/web/src/helpers/site-resolver.ts
Proxy (routing)	apps/web/src/proxy.ts

---

6. Commit Convention

Use Conventional Commits:

feat: Add M08 Card Grid module
fix: Fix Hero Slider autoplay on mobile
style: Update Savoy Palace theme tokens
refactor: Extract shared image mapper utility
test: Add mapper tests for M05 Hero Slider
chore: Update Storybook to 8.6
docs: Add responsive images dev guide

---

7. PR Size Guideline

Maximum 400 lines changed per PR. If a module exceeds this:

1. PR 1: Types + Component + SCSS
2. PR 2: Mapper + Registry + Stories
3. PR 3: Tests + refinements

Each PR should be independently reviewable and not break the build.