# Magic Home Design System V2 · AI Agent Replication Guide (`CLAUDE.md`)

## 1. Brand Identity & Business Model

- **Brand**: Magic Home (`magichome.com`)
- **Category & Public Price Band**: Smart Modular & Power-Comfort Sofa DTC | Public storefront modular & power-reclining configurations ($1,500-$3,500)
- **Business Model (EN)**: Smart Modular & Power-Comfort Sofa DTC + 5 US Showrooms
- **Business Model (ZH)**: 智能模块化与电动舒适沙发直营 DTC 独立站（配全美 5 家线下展厅）
- **Core Positioning**: Smart Comfort for Flexible Living (`智享舒适，随心而居`): smart modular comfort furniture built on three pillars (`Built to change` true modular add/remove/rearrange pieces, `Comfort you choose` seat-by-seat power recline, zero gravity, heated seats, and wireless + USB-C charging on select series, and `Fits your life` transparent box/doorway dimensions and select washable covers), backed by 5 US showrooms.
- **Self-Contained Package**: Every token file, offline webfont, bilingual runtime helper, Brand Book chapter, component preview, asset, and specimen referenced below lives inside this folder using portable relative paths.

## 2. Canonical Entrypoints (Read Order)

1. **Machine Contract**: `ai-replication-contract.json` (`schemaVersion: "4.0.0"`)
2. **Design Tokens & Offline Runtime**:
   - Canonical JSON: `tokens/tokens.json`
   - W3C DTCG 10-Group JSON: `tokens/tokens.dtcg.json`
   - Brand CSS Variables: `tokens/tokens.css`
   - 48-Variable Cross-Brand Semantic Bridge: `tokens/semantic-bridge.css`
   - Shopify OS 2.0 Theme Settings Bridge: `tokens/shopify-theme-tokens.css`
   - Multi-Platform Token Exports: `tokens/tailwind.preset.json`, `tokens/tokens.tailwind.config.js`, `tokens/tokens.style-dictionary.json`, `tokens/shopify-settings_schema.json`, `tokens/figma-variables.json`
   - Offline Brand Webfonts & CJK Mono Stack: `tokens/brand-fonts.css` (`assets/Fonts/*.woff2`)
   - Bilingual Switcher Helper: `tokens/ds-i18n.js`
3. **Bilingual Brand Book**:
   - Chinese (`zh-Hans-US` governance): `docs/`
   - English (`en-US` governance): `docs/en/`
4. **Brand Evidence & Dossier**:
   - Manifest: `brand-archive/manifest.json`
   - Official Materials: `brand-archive/official-materials.md` and `brand-archive/en/official-materials.md`
   - Strategic Dossier: `brand-archive/third-party-dossier.md` and `brand-archive/en/third-party-dossier.md`
5. **Interactive Viewers & Candidates**:
   - Standalone Bilingual System Viewer: `index.html` (`?lang=en` / `?lang=zh`)
   - Baseline V1 Structural Specimen: `candidates/baseline_v1/specimen.html`
   - Flagship V2 Interactive Specimen: `candidates/optimized_v2/specimen.html`

## 3. Locked Visual DNA

| Property | Locked Value |
| --- | --- |
| Primary Page Ground | `#FFFFFF` |
| Card / Elevated Surface | `#FFFFFF` |
| Alternating Band / Footer | `#EFEFEB` / `#FFFFFF` |
| Primary / Secondary Ink | `#171616` / `#525050` |
| Primary Action Fill / Text | `#3F1A03` / `#FFFFFF` |
| Button / Card Corner Radius | `0px` / `0px` |
| Display / Body / CJK Fonts | `Montserrat` / `Archivo` / `Noto Sans SC` |
| Elevation & Shadow Rule | Strict zero drop-shadow policy (`box-shadow: none`); pure `#FFFFFF` page canvas and `#FFFFFF` footer, `#EFEFEB` small neutral control fill only (never `#F6F1EA` section bands), `#171616` primary ink, `#525050` secondary ink, and `#353534` control borders. |

## 4. Commercial & Legal Guardrails

- **primaryCta**: PDP and configurator summary primary CTA is locked to `Add to cart` or `Add to cart · $2,080` / `加入购物车` or `加入购物车 · $2,080` (`MGH-CORE-10`, sentence case, `0px` square, `#3F1A03` espresso fill). Configurator entry CTA is locked to `Build yours` / `开始搭配` (`Shop Modular Sectionals` on hero; `Finish checkout` on English checkout). Never write `Configure Yours`, `Add to Bag`, or all-caps CTAs.
- **shipping**: Free standard shipping to the U.S. and U.S. territories. Processed in 2 business days; arrives in 7-15 business days via FedEx multi-box parcel or LTL freight for oversized/power pieces (custom & pre-order: 28-70 business days). Multi-box orders may arrive on different days.
- **returns**: 30-day returns from delivery on unused, uninstalled items in original packaging (email first for RA authorization; buyer pays return shipping for non-quality returns; custom and clearance items final sale). One-time 7-day price match.
- **warranty**: 2-year limited warranty covering structural and manufacturing defects (zero steel-latch warranty claims).
- **swatchesAndShowrooms**: Up to 5 free fabric swatches mailed to U.S. addresses; 5 U.S. showrooms in Los Angeles, Houston, New Jersey, Atlanta, and Miami.

## 5. Non-Negotiable Redlines

- Brand tagline is locked verbatim to `Smart Comfort for Flexible Living` (Chinese subtitle `智享舒适，随心而居`); never revert to V1 slogan `Furniture That Moves With Your Life`.
- Page canvas AND site footer must stay pure `#FFFFFF`; `#EFEFEB` is restricted to small neutral control fills (never `#F6F1EA` section bands); primary ink is `#171616`, secondary ink `#525050`, control border `#353534`, and all corners `0px` with zero shadows.
- Primary purchase CTA is `Add to cart` / `加入购物车` (`#3F1A03` espresso) and configurator entry CTA is `Build yours` / `开始搭配` (sentence case); `#E1441D` red is reserved for the 2x3 modular mark and active indicator.
- Never fabricate `concealed steel latches`, `Steel-Latch Warranty`, `CubeGrid`, `OEKO-TEX`, or `2-5 business days` shipping; distinguish `Modular Sectionals` from fixed `Reclining Sectionals` (never call fixed power recliners modular).
- State `2` business days processing + `7-15` business days delivery (`28-70` business days custom/pre-order), up to `5` free swatches, `30-day` unused original-packaging returns (RA required, buyer pays return shipping), `2-year` limited warranty, and `5` US showrooms.
- Distinguish Overall Depth (`38"`) from Inside Seat Depth (`25"`); keep cart and checkout in English per `03-copy-zh.md`.

## 6. Nine Canonical Page Blueprints

| Blueprint ID | Primary Specimen (`en-US`) | Localized Specimen (`zh-Hans-US`) | Implementation Notes |
| --- | --- | --- | --- |
| `PageHome` | `snapshot/cards/Page01Home.html` | `snapshot/cards/ChineseKeyPages.html` | Pure `#FFFFFF` homepage (`Page01Home`, `Page01HomeBlackFriday`, and `ChineseKeyPages` `zh-Hans-US` edition) leading with `Smart Comfort for Flexible Living`. |
| `PageCategoryHub` | `snapshot/cards/Page02Collection.html` | `snapshot/cards/ChineseKeyPages.html` | Collection hub spanning `Modular Sectionals`, `Reclining Sectionals`, and `Customization`. |
| `PagePLPWithFacetDrawer` | `snapshot/cards/Page02Collection.html` | `snapshot/cards/ChineseKeyPages.html` | 0px `#353534`-bordered product grid displaying piece count, box count, power options, swatches, and USD price. |
| `PagePDPFullLongScroll` | `snapshot/cards/Page03Product.html` | `snapshot/cards/ChineseKeyPages.html` | Flagship `Cero Modular Sectional, 6-Piece` PDP (`Page03Product` and localized `ChineseKeyPages`) with `Add to cart` and `Build yours`. |
| `CartDrawer` | `snapshot/cards/Page12Cart.html` | `snapshot/cards/AddedToCart.html` | English cart and checkout flow displaying box counts and split-day multi-box delivery notice. |
| `PageTradeOrConsultation` | `snapshot/cards/Page04Customization.html` | `snapshot/cards/Page09Showrooms.html` | `Build yours` 2D modular & custom planner (`28-70` business days) plus 5 US showroom booking (`LA / Houston / NJ / Atlanta / Miami`). |
| `PageEditorialLookbook` | `snapshot/cards/Page11HomeIdeas.html` | `snapshot/cards/Page05Sale.html` | Home Ideas editorial hub (`Page11HomeIdeas`) demonstrating real room layouts and doorway clearance. |
| `PageCraftsmanshipStory` | `snapshot/cards/Page10About.html` | `snapshot/cards/ChocolateGrid.html` | Explains `Built to change`, `Comfort you choose`, and `Fits your life` (`Page10About` & `ChocolateGrid`). |
| `PageFreeSwatchesStudio` | `snapshot/cards/SwatchPicker.html` | `snapshot/cards/Page06Support.html` | Up to 5 free fabric swatches across Chenille, Corduroy, and Boucle (`SwatchPicker`, `SwatchCard`, `Page06Support`). |

## 7. Bilingual Copy & Typography Checklist (`en-US` & `zh-Hans-US`)

- **Preferred `en-US` Terms**: `Smart Comfort for Flexible Living`, `Add to cart`, `Build yours`, `Built to change`, `Comfort you choose`, `Fits your life`, `Cero Modular Sectional, 6-Piece`
- **Prohibited `en-US` Terms**: `Verified US Buyers`, `Configure Yours`, `Add to Bag`, `Furniture That Moves With Your Life`, `concealed steel latches`, `Steel-Latch Warranty`, `OEKO-TEX certified`, `30-Day Trial`
- **Preferred `zh-Hans-US` Terms**: `智享舒适，随心而居`, `加入购物车`, `开始搭配`, `随你变`, `舒适按需选`, `放得下，住得开`, `全美 5 家线下展厅`
- **Prohibited `zh-Hans-US` Terms**: `美元`, `美刀`, `包邮`, `亲`, `定制模块组合`, `隐藏钢扣`, `钢扣质保`, `圆角胶囊按钮`, `30 天试用`, `10 年质保`
- **Imperial Furniture Units**: Always format inches with `"` and feet with `'` (for example `96"W x 38"D x 30"H` and `12' x 14'` room size). Always state Overall Depth separately from Inside Seat Depth (`22"` to `28"`).