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

## 1. Brand Identity & Business Model

- **Brand**: Atunus Home (`atunushome.com`)
- **Category & Public Price Band**: Whole-Room Coordinated Furniture Sets & Bilingual Spatial Planning DTC | Public storefront single pieces & coordinated room sets (single sofa anchor $1,598; $199/room Room Plan credited within 60 days)
- **Business Model (EN)**: Single-Piece to Whole-Space Furniture DTC + Coordinated Sets + Bilingual Spatial Planning
- **Business Model (ZH)**: Atunus Home（家具与空间方案）：中高端单品到整屋空间方案与中英双语设计咨询 DTC
- **Core Positioning**: From concept to home, all in Atunus. (`从构想到家，尽在 Atunus。` · `From single pieces to complete spaces.`): first Chinese mention locked to `Atunus Home（家具与空间方案）`, spanning single pieces, coordinated sets (`Set saves you $X`), room concepts, free 30-45 min bilingual consultations, `$199/room` Room Plans (100% credited within 60 days), custom pieces (3-business-day quote, 50% deposit), and commercial spaces.
- **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 | `#FAFAF9` |
| Card / Elevated Surface | `#FFFFFF` |
| Alternating Band / Footer | `#F3F3F0` / `#292D23` |
| Primary / Secondary Ink | `#2A2926` / `#56534F` |
| Primary Action Fill / Text | `#707461` / `#FFFFFF` |
| Button / Card Corner Radius | `8px` / `12px` |
| Display / Body / CJK Fonts | `Archivo` / `Archivo` / `Noto Sans SC` |
| Elevation & Shadow Rule | Calm warm-minimal border (`1px solid #E8E6E1`) and subtle `0 2px 12px rgba(42,41,38,0.05)` lift; `#2A2926` primary body ink, `#56534F` secondary ink, `#292D23` reserved for deep forest footer/inverse band, single Latin font family `Archivo`. |

## 4. Commercial & Legal Guardrails

- **primaryCta**: PDP primary CTA is `Add to cart · $1,598` (or `Add to cart`) / `加入购物车 · $1,598` (`8px` radius, `#707461` sage fill, sentence case). Homepage hero primary CTA is `Shop furniture sets` / `看整套家具` + secondary `Book a consultation` / `预约设计咨询`. Room concept CTA is `Shop the look` / `看整间搭配` + `Plan a room like this` / `照这个房间规划`. Custom/commercial CTA is `Request a custom quote` / `Plan a project space`.
- **eightNonPromises**: ATH-CORE-06 Eight Non-Promises: never promise white-glove delivery, free shipping, free full design, free swatches, third-party sourcing, dedicated concierge, installment financing, or Trade/member discounts.
- **designConsultation**: Free 30-45 min bilingual (`en-US` / `zh-Hans-US`) initial design consultation; `$199/room` Room Plan package credited 100% toward furniture orders placed within 60 days.
- **shippingAndSwatches**: Per-piece transparent lead times (in-stock 3-7 days; made-to-order 8-9 weeks; multi-item orders with mixed lead times ship separately by item schedule). Shipping is calculated by region and shipment batch at checkout (rate table [NEED ALLEN REVIEW]). Paid fabric swatches only (non-returnable; never promise free swatches).
- **returns**: 30-day returns on unused in-stock items in original packaging (no restocking fee; regional return pickup fee [NEED ALLEN REVIEW]; original shipping non-refundable; MTO/custom/clearance/display/swatches final sale; report transit damage within 7 days).
- **warranty**: Limited warranty: 5-year frame, 2-year other components, 1-year upholstery/leather/lighting/mirrors/accessories (pending written manufacturer sign-off [NEED ALLEN REVIEW]).
- **photographyNotice**: Images under `assets/Photos/` are Editorial Reference Photography (mood and material reference only, non-SKU) until studio SKU photography is supplied.

## 5. Non-Negotiable Redlines

- Always use official domain `atunushome.com` (never `atunus.com`) and first Chinese mention `Atunus Home（家具与空间方案）`.
- Enforce `ATH-CORE-06` Eight Non-Promises: strictly zero promises of white-glove delivery, free shipping, free swatches, free full design, third-party sourcing, dedicated concierge, installments, or Trade/member dual-track pricing.
- Use single Latin font family `Archivo` (600/500/400) + `Noto Sans SC`, `#2A2926` primary body ink, `#56534F` secondary ink, `#292D23` forest footer, and `#707461` `8px` sentence-case CTAs (`Add to cart`, `Shop furniture sets`, `Shop the look`, `Book a consultation`).
- State split-shipment transparency (`in-stock 3-7 days; MTO 8-9 weeks; multi-item orders ship by item lead time`) and preserve `[NEED ALLEN REVIEW]` on regional shipping rates, regional return pickup fees, and manufacturer sign-off for the `5/2/1-year` warranty.
- Label `assets/Photos/` clearly as `Editorial Reference Photography` (non-SKU mood reference), and maintain `zh-Hans-US` parity (polite `您`, `$1,598` USD format, CJK-Latin half-width spacing).

## 6. Nine Canonical Page Blueprints

| Blueprint ID | Primary Specimen (`en-US`) | Localized Specimen (`zh-Hans-US`) | Implementation Notes |
| --- | --- | --- | --- |
| `PageHome` | `components/PageHome/preview.html` | `components/PageHomeZh/preview.html` | 1440px homepage (`PageHome`, `PageHomeMobile`, `PageHomeZh`) leading with `Shop furniture sets` + `Book a consultation`. |
| `PageCategoryHub` | `components/PageRoomConcept/preview.html` | `components/PageRoomConceptZh/preview.html` | Spatial room hub (`PageRoomConcept` / `PageRoomConceptZh`) with `Shop the look` + `Plan a room like this`. |
| `PagePLPWithFacetDrawer` | `components/PagePLP/preview.html` | `components/PagePLPZh/preview.html` | Interactive collection grid (`PagePLP`, `PagePLPMobile`, `PagePLPZh`) showing in-stock `3-7d` vs MTO `8-9w` lead times. |
| `PagePDPFullLongScroll` | `components/PagePDP/preview.html` | `components/PagePDPZh/preview.html` | Supports Single Piece (`Add to cart · $1,598`) and Coordinated Set (`Set saves you $X`) modes with split-delivery transparency. |
| `CartDrawer` | `components/PageCart/preview.html` | `components/PageCartZh/preview.html` | Slide-over `AddedToCart` drawer plus `PageCart` / `PageCartZh` calculating shipping by region and shipment batch at checkout. |
| `PageTradeOrConsultation` | `components/PageConsultation/preview.html` | `components/PageConsultationZh/preview.html` | Bilingual consultation flow (`PageConsultation`, `PageConsultationZh`) for residential Room Plans and commercial space inquiries. |
| `PageEditorialLookbook` | `components/ShopTheLook/preview.html` | `components/PageRoomConceptZh/preview.html` | Editorial room scenes (`ShopTheLook` + `PageRoomConcept`) using labeled Editorial Reference Photography. |
| `PageCraftsmanshipStory` | `components/PageAbout/preview.html` | `components/PageAboutZh/preview.html` | Canonical brand story from `01-brand-core.md` in English (`PageAbout`) and `zh-Hans-US` (`PageAboutZh`). |
| `PageFreeSwatchesStudio` | `components/SwatchPicker/preview.html` | `components/SwatchCard/preview.html` | Paid material swatch selector (non-returnable per `ATH-CORE-06`) paired with 30-45 min design consultations. |

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

- **Preferred `en-US` Terms**: `From concept to home, all in Atunus.`, `From single pieces to complete spaces.`, `Add to cart`, `Shop furniture sets`, `Shop the look`, `Book a consultation`, `Set saves you`
- **Prohibited `en-US` Terms**: `atunus.com`, `Verified US Buyers`, `Shop the Room`, `ADD ROOM SET`, `White-glove delivery`, `Complimentary swatch kit`, `Trade discount`, `30-Day In-Home Trial`
- **Preferred `zh-Hans-US` Terms**: `从构想到家，尽在 Atunus。`, `Atunus Home（家具与空间方案）`, `加入购物车`, `看整套家具`, `看整间搭配`, `预约设计咨询`, `每个房间 $199（60 天内下单全额抵扣）`
- **Prohibited `zh-Hans-US` Terms**: `美元`, `美刀`, `包邮`, `亲`, `atunus.com`, `白手套送装`, `免费小样`, `选购整屋搭配`, `30 天试用`
- **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"`).