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

## 1. Brand Identity & Business Model

- **Brand**: Aesthea (`aesthea.com`)
- **Category & Public Price Band**: Trade-Primary & Direct Retail Made-to-Order Furniture | Public retail catalog pricing + verified Trade 20% off (`Retail x 0.8`, no min order; COM & custom dimensions priced on request)
- **Business Model (EN)**: Trade-Primary + Direct Retail Made-to-Order Furniture Brand (Four Hands Benchmark: Public Retail Checkout + Verified Trade 20% Off)
- **Business Model (ZH)**: 对标 Four Hands 的设计师优先（Trade-Primary）与公开零售直购双轨按单定制家具品牌（Trade 登录无起订量享 8 折）
- **Core Positioning**: Formed by Aesthetics, Defined by You (Bespoke Furniture, Made to Order): architectural walnut-and-linen residential and contract-grade furniture (CAL TB 117-2013, >=30,000 double rubs) with public retail checkout (`Add to cart`), 20% Trade pricing (`Retail x 0.8`, no minimum order), and independent brand identity.
- **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 | `#FAF7F2` |
| Alternating Band / Footer | `#F3EEE6` / `#30211C` |
| Primary / Secondary Ink | `#201D1A` / `#66615E` |
| Primary Action Fill / Text | `#6D4F40` / `#FFFFFF` |
| Button / Card Corner Radius | `0px` / `0px` |
| Display / Body / CJK Fonts | `Marcellus` / `Archivo` / `Noto Sans SC` |
| Elevation & Shadow Rule | Zero heavy shadows; rely on #FFFFFF / #FAF7F2 / #F3EEE6 tonal separation and 1px #E4DDD3 hairlines. |

## 4. Commercial & Legal Guardrails

- **primaryCta**: Default PDP and configurator CTA is `Add to cart` (sentence case in DOM, displayed uppercase via CSS `text-transform: uppercase; letter-spacing: 0.08em`) / `加入购物车` (no uppercase or extra tracking in Chinese). COM fabrics and custom dimensions show `Priced on request` + inquiry CTA. Trade page CTA is `Apply now` / `申请加入 Trade 计划`; design service CTA is `Book a free design session` / `预约免费设计服务`.
- **leadTimes**: Three-tier fulfillment: In stock 5-7 business days; Quick ship 2-3 weeks; Made to order 8-10 weeks (10-12 weeks for C/D grade fabrics, sectionals, and stone).
- **shipping**: $249 flat-rate white-glove delivery per order across the 48 contiguous US states (room placement, assembly, packaging removal; AK/HI quoted separately). Swatches ship free separately.
- **returns**: Made-to-order pieces allow free edit or cancellation within 48 hours of ordering and are non-returnable once in production; In-stock & Quick-ship items support 30-day returns ($249 return pickup fee). Report delivery damage with photos within 7 days of delivery (pending final pre-launch sign-off).
- **warranty**: 10-year structural frame warranty; 1-year fabric, finish, and hardware warranty (never claim Lifetime Heirloom Warranty; pending final pre-launch sign-off).
- **swatches**: Up to 10 complimentary material swatches delivered free in 5-7 business days.
- **tradeProgram**: Verified interior designers, architects, and hospitality buyers (2-business-day review) receive 20% off (`Retail x 0.8`) with no minimum order, tax-exempt checkout, project volume quotes, tear sheets, and large memo samples.

## 5. Non-Negotiable Redlines

- Zero fabricated consumer star ratings (`★★★★★` / `★★★★☆`) anywhere on PDP, PLP, BuyBox, or cards, and never append `by Domula` to Aesthea.
- Keep `0px` square geometry on buttons, inputs, and product cards; primary CTA fill is locked to `#6D4F40` walnut (`#57453B` hover, `#44332C` active) and footer fill to `#30211C`.
- Default PDP and configurator items display retail pricing with `Add to cart` / `加入购物车` for direct consumer purchase; reserve `Priced on request` strictly for COM fabrics and custom dimensions.
- Separate the 48-hour post-order MTO edit/cancel window from the 7-day delivery damage reporting window; state In-stock (5-7 business days) & Quick-ship (2-3 weeks) 30-day returns ($249 return pickup fee) while MTO items are non-returnable once in production.
- Distinguish Overall Depth (`38"`) from Inside Seat Depth (`23"`); always use `"` for inches and `'` for feet.
- Maintain Retail vs Verified Trade (`Retail x 0.8`, no minimum order) dual-state clarity without fake strikethrough MSRP; use polite `您` in `zh-Hans-US` service/checkout copy.

## 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 gallery homepage leading with `Shop the living room` + `For the trade` and calm generous whitespace. |
| `PageCategoryHub` | `components/PagePLP/preview.html` | `components/PagePLPZh/preview.html` | Living, Dining, and Bedroom architectural category hub with 3-column 0px card rhythm. |
| `PagePLPWithFacetDrawer` | `components/PagePLP/preview.html` | `components/PagePLPZh/preview.html` | Interactive material, readiness (In stock / Quick ship / MTO), and width facet filtering with zero star-rating clutter. |
| `PagePDPFullLongScroll` | `components/PagePDP/preview.html` | `components/PagePDPZh/preview.html` | Flagship long-scroll PDP with public Retail `Add to cart` (`PagePDP`), signed-in Trade `Retail x 0.8` (`PagePDPTrade`), and COM `Priced on request`. |
| `CartDrawer` | `components/AddedToCart/preview.html` | `components/PageCart/preview.html` | Slide-over bag and full cart page stating $249 flat-rate white-glove delivery, 48h MTO edit window, and 7-day damage report. |
| `PageTradeOrConsultation` | `components/PageTrade/preview.html` | `components/PageTradeZh/preview.html` | Trade & Contract portal (`Apply now` / `Trade sign in`) plus `PageDesignServices` (`Book a free design session`). |
| `PageEditorialLookbook` | `components/PageConfigurator/preview.html` | `components/PageHomeZh/preview.html` | Gallery room studies and interactive finish configurator (`PageConfigurator`) with `#6D4F40` `Add to cart`. |
| `PageCraftsmanshipStory` | `components/PageAbout/preview.html` | `components/PageHowToBuy/preview.html` | Brand story (`PageAbout`) and transparent 3-tier ordering & warranty guide (`PageHowToBuy` / `PagePolicy`). |
| `PageFreeSwatchesStudio` | `components/PageSwatches/preview.html` | `components/PageSwatches/preview.html` | Interactive fabric, leather, wood, and stone library supporting up to 10 free swatches. |

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

- **Preferred `en-US` Terms**: `Formed by Aesthetics, Defined by You.`, `Bespoke Furniture, Made to Order`, `Add to cart`, `Apply now`, `Book a free design session`, `Report delivery damage within 7 days`
- **Prohibited `en-US` Terms**: `Verified US Buyers`, `by Domula`, `Commission Made-to-Order Piece`, `Request Trade Quote`, `48-Hour Freight Damage`, `Lifetime Heirloom Warranty`
- **Preferred `zh-Hans-US` Terms**: `美学成形，由你定义`, `按订单定制的家具`, `加入购物车`, `申请加入 Trade 计划`, `预约免费设计服务`, `到货损坏 7 天内反馈`
- **Prohibited `zh-Hans-US` Terms**: `美元`, `美刀`, `包邮`, `亲`, `全网最低`, `终身传世框架质保`, `48 小时货运破损保障`, `定制款 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"`).