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

## 1. Brand Identity & Business Model

- **Brand**: WJS Home (`wjshomestore.com`)
- **Category & Public Price Band**: Family Comfort Sofa & Home Living DTC | Public storefront pricing (Sereno 26 modular layouts $359-$2,789; core L-shape $1,359)
- **Business Model (EN)**: Family Comfort Sofa & Multi-Category Home Living DTC
- **Business Model (ZH)**: 美国家庭舒适沙发与多品类客厅家具直营 DTC 独立站
- **Core Positioning**: Home Is Where Joy Settles (`Where Joy Settles` / `喜悦安居之处`): approachable US family home living prioritizing sink-in comfort first, removable washable covers on select series second (follow care label), and modular layout rearrangement or hidden storage third (`Deluxe Cloud`, `Matrix`, non-modular `Essential`, sintered-stone dining tables, coffee tables, media consoles, and slipcovers).
- **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 | `#F5F2ED` |
| Card / Elevated Surface | `#FFFFFF` |
| Elevated Surface / Footer | `#FCFBFA` / `#53443C` (`#EBE2D8` small chips only) |
| Primary / Secondary Ink | `#53443C` / `#666564` |
| Primary Action Fill / Text | `#53443C` / `#FFFFFF` |
| Button / Card Corner Radius | `999px` / `20px` |
| Display / Body / CJK Fonts | `Mulish` / `Archivo` / `Noto Sans SC` |
| Elevation & Shadow Rule | Soft warm-walnut elevation (`0 2px 10px rgba(83,68,60,0.06)`) on #FFFFFF 20px cards and #FCFBFA overlays over #F5F2ED warm-linen ground and #FCFBFA clean elevated surfaces (#EBE2D8 restricted to small-area chips/callouts, never alternating section bands). |

## 4. Commercial & Legal Guardrails

- **primaryCta**: PDP primary button is `Add to Cart` or `Add to Cart · $1,299` / `加入购物车` or `加入购物车 · $1,299` (`999px` pill, `#53443C` walnut fill, matching `wjshomestore.com` and `tokens.json`; `02-language-en.md` also permits sentence-case `Add to cart`). Homepage hero CTA is `Shop sofas` / `选购沙发`; cart CTA is `Check out` / `去结算`. Never write `Add to Bag`, all-caps `ADD TO CART`, or `加入购物袋`.
- **shipping**: Free standard shipping to the continental US and US territories (excludes APO/FPO/DPO; no white-glove service). Ships within 2 business days; sofas arrive in 7-15 business days by LTL freight (smaller parcel items in 5-8 business days).
- **returns**: 30-day returns from delivery on unused, unassembled items in original packaging; buyer pays return shipping (~$60-$80/seat) for non-quality returns. Report transit damage within 7 days. Never promise 30-day home trial or free returns.
- **warranty**: 2-year limited warranty (never promise 5-year or lifetime warranty).
- **careAndCertifications**: Removable washable covers apply to select series only; state `machine-washable` only when specified on the care label. Never state `OEKO-TEX` or free swatch programs without verified documentation.
- **valueOrder**: Always present benefits in locked sequence: 1. Family deep comfort -> 2. Removable washable covers on select series (follow care label) -> 3. Modular layout rearrangement & storage (never promise buying single add-on seats later).

## 5. Non-Negotiable Redlines

- Never invert the selling-point hierarchy: 1. Comfort -> 2. Removable washable covers on select series (follow care label) -> 3. Modular layout rearrangement & storage.
- Primary CTA is locked to `Add to Cart` / `加入购物车` (`#53443C` walnut `999px` pill); never write `Add to Bag` / `加入购物袋` or all-caps button labels.
- Use locked 18-color tokens: `#53443C` primary ink and CTA, `#666564` secondary ink, `#F5F2ED` canvas, `#EBE2D8` small-area chip/callout only (never alternating section bands), `#FCFBFA` elevated surface, `#FFFFFF` `20px` cards (`14px` inputs); reserve `#D35C1A` strictly for verified sale badges and prices.
- State accurate LTL freight fulfillment (`2` business days dispatch + `7-15` business days by freight for sofas, `5-8` business days for parcels) and never promise `30-Day Home Trial`, `Free swatches`, `OEKO-TEX`, steel latches, or single-seat expansion.
- Use polite `您` across storefront, checkout, support, and policy pages (`你` only on RedNote/WeChat social posts); distinguish Overall Depth (`39.3"`) from Seat Depth (`25.59"`).

## 6. Nine Canonical Page Blueprints

| Blueprint ID | Primary Specimen (`en-US`) | Localized Specimen (`zh-Hans-US`) | Implementation Notes |
| --- | --- | --- | --- |
| `PageHome` | `preview/PageHome.html` | `preview/PageHomeZh.html` | Everyday (`PageHome`), Black Friday (`PageHomeBF`), mobile (`PageHomeMobile`), and `zh-Hans-US` (`PageHomeZh`) editions. |
| `PageCategoryHub` | `preview/PagePLP.html` | `preview/PagePLPZh.html` | Sectional, Sofa (`Deluxe Cloud`, `Matrix`, `Essential`), Dining Table, Coffee Table, Console, and Slipcover category hub. |
| `PagePLPWithFacetDrawer` | `preview/PagePLP.html` | `preview/PagePLPZh.html` | Desktop (`PagePLP`), mobile (`PagePLPMobile`), and localized (`PagePLPZh`) collection filtering. |
| `PagePDPFullLongScroll` | `preview/PagePDP.html` | `preview/PagePDPZh.html` | Full long-scroll `Deluxe Cloud` / `Matrix` PDP with `Add to Cart` primary CTA in desktop, mobile, and `zh-Hans-US`. |
| `CartDrawer` | `preview/AddedToCart.html` | `preview/PageCartZh.html` | Slide-over `AddedToCart` drawer plus full `PageCart` / `PageCartMobile` / `PageCartZh` using `Check out` / `去结算`. |
| `PageTradeOrConsultation` | `preview/BrandOnePage.html` | `preview/PageHomeZh.html` | Family room layout and fabric care guidance routed through WJS customer care. |
| `PageEditorialLookbook` | `preview/ShopTheLook.html` | `preview/PageHomeZh.html` | Living-room layout rearrangements (Movie Night, Family Gathering, Chaise Lounge) using existing modular pieces. |
| `PageCraftsmanshipStory` | `preview/KeyFacts.html` | `preview/Steps.html` | Cushion comfort cross-section paired with zip-off cover care instructions per care label. |
| `PageFreeSwatchesStudio` | `preview/SwatchPicker.html` | `preview/SwatchPicker.html` | Tactile fabric comparison across Chenille, Corduroy, Boucle, and Velvet upholstery options. |

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

- **Preferred `en-US` Terms**: `Home Is Where Joy Settles`, `Add to Cart`, `Cloud-soft deep comfort`, `Removable washable covers on select series (follow care label)`, `Modular sections rearrange to fit your room layout`
- **Prohibited `en-US` Terms**: `Verified US Buyers`, `Add to Bag`, `30-Day Home Trial`, `Free Return Pickup`, `5-Year Frame Warranty`, `add armless seats`, `Hidden steel latches`
- **Preferred `zh-Hans-US` Terms**: `喜悦安居之处`, `加入购物车`, `云感深坐舒适`, `主力系列配可拆洗沙发套（洗护方式以洗标为准）`, `模块可按客厅动线重新组合摆法`
- **Prohibited `zh-Hans-US` Terms**: `美元`, `美刀`, `包邮`, `亲`, `加入购物袋`, `无理由免费退运`, `30 天居家试用`, `30 天试坐`, `增配单人模块`, `5 年质保`
- **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"`).