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

## 1. Brand Identity & Business Model

- **Brand**: Domula (`domula.com`)
- **Category & Public Price Band**: Los Angeles Phase 1 Designer-First B2B2C Custom Production & Project Delivery Platform | Zero public retail pricing (Designer Portal project BOM quote only)
- **Business Model (EN)**: Los Angeles Phase 1 Designer-First B2B2C Design-to-Delivery Platform (Custom Manufacturing + Third-Party Receiving & Single-Visit Setup)
- **Business Model (ZH)**: 第一阶段聚焦洛杉矶的设计师优先 B2B2C 设计到交付平台（自有按图定制生产 + 第三方货物代收验货合单 + 一次上门送装）
- **Core Positioning**: Good Design Finds Its Home. (`好设计，自有归处。` · `Designers draw it. We make it, ship it and set it up.`): Los Angeles Phase 1 designer-first platform providing same-day quotes and bills of materials once drawings are ready, two settlement paths, 12-month client protection, custom manufacturing (8-10 weeks; COM 12-16 weeks), 48h LA warehouse receiving inspection for third-party items, shipped and set up in one visit, and 72h aftercare.
- **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 | `#FAFAFA` |
| Alternating Band / Footer | `#F4F4F4` / `#161616` |
| Primary / Secondary Ink | `#161616` / `#545454` |
| Primary Action Fill / Text | `#A6192E` / `#FFFFFF` |
| Button / Card Corner Radius | `999px` / `20px` |
| Display / Body / CJK Fonts | `Albert Sans` / `Albert Sans` / `Noto Sans SC` |
| Elevation & Shadow Rule | Pure neutral achromatic planes (#FFFFFF primary canvas, #FAFAFA workspace surface, #F4F4F4 neutral light gray bands, 20px cards, 28px hero media, 12px inputs, and 1px solid #EAEAEA hairlines; default card shadow none); reserve shadows strictly for floating overlays. |

## 4. Commercial & Legal Guardrails

- **primaryCta**: Public website CTAs: hero `See the homes` / `查看作品`, designer & process pages `Apply to join` / `申请加入`, form `Send application` / `提交申请`, showroom `Book a visit` / `预约参观`, portfolio `Contact {Designer}` / `联系 {设计师}`. Designer Portal CTAs: `New project` / `新建项目`, `Add to the project` / `加入项目`, `Send to client` / `发送给客户`, client proposal `Approve and pay the deposit` / `确认并支付定金` (`999px` pill, `#A6192E` crimson fill, sentence case).
- **accessAndSettlement**: Phase 1 serves Los Angeles interior designers (`Los Angeles, for now` / `先在洛杉矶`) (walk-in homeowners without a designer are served by Domula's paid project design team, credited toward furniture). Two settlement paths: Path A designer net purchase with a valid California Resale Certificate (CDTFA-230 per CDTFA Pub 35); Path B client retail payment with post-delivery designer commission (never expose commission split ratios publicly). Includes 12-month client protection.
- **pricingVisibility**: Zero public consumer retail dollar figures on the public website; itemized quotes are generated per whole-project BOM inside the Designer Portal.
- **fulfillmentAndAftercare**: Same-day quotes and bills of materials; custom manufacturing in 8-10 weeks (12-16 weeks for COM or special craft); third-party items received at the LA hub with open-box photo inspection within 48 hours (billed per piece/project); once complete, shipped and set up in one LA visit (unpacking, placement, packaging removal); 72-hour post-delivery aftercare response.
- **designerAttribution**: Completed home portfolios always credit the interior designer and studio first; never imply consumer shoppable room bundles, nationwide shipping, free design, or third-party brand marketplace onboarding.

## 5. Non-Negotiable Redlines

- Zero public consumer retail prices, zero `Add to cart` / `Shop now` / all-caps buttons, and zero promotional discount banners anywhere on public pages.
- Zero fabricated star ratings (`★★★★★` / `★★★★☆`) anywhere in website or portal components.
- Zero confidential business-plan financial projections, internal margin or commission split ratios, or single-project forecast numbers in any public or design-system file.
- Maintain locked Pure Neutral Gray-White visual system (`#FFFFFF` primary canvas, `#FAFAFA` workspace surface, `#F4F4F4` neutral light gray bands, `#161616` neutral near-black ink, `#545454` secondary ink, `20px` card radius, `28px` hero radius, `12px` input radius, `1px solid #EAEAEA` border, `Albert Sans` + `Noto Sans SC`); never introduce warm beige grounds, serif display fonts, or `12px` card radius descriptions.
- Use `shipped and set up in one visit` / `一次上门送装` (never luxury glove-delivery cliches), state `same-day quotes and bills of materials` (never 5-day drawing turnaround), and restrict Phase 1 geographic claims to Los Angeles (`Los Angeles, for now` / `先在洛杉矶`, never cities beyond Los Angeles).
- Primary CTA buttons use `#A6192E` Domula red (`999px` pill); checkboxes, radio buttons, and active tabs use `#161616` neutral ink (`selection-mark`), never red.

## 6. Nine Canonical Platform & Designer Portal Blueprints

| Blueprint ID | Primary Specimen (`en-US`) | Localized Specimen (`zh-Hans-US`) | Implementation Notes |
| --- | --- | --- | --- |
| `SiteHome` | `components/SiteHome/preview.html` | `components/SiteHomeZh/preview.html` | Public LA B2B2C platform homepage (`SiteHome`, `SiteHomeMobile`, `SiteHomeZh`) leading with `See the homes` and `Apply to join`. |
| `SitePortfolioHomes` | `components/SiteHomes/preview.html` | `components/SiteProjectsZh/preview.html` | Completed LA residences portfolio (`SiteHomes` / `SiteProjectsZh`) crediting the lead interior designer on every home. |
| `PortalMaterialLibrary` | `components/PortalLibrary/preview.html` | `components/SiteProjectsZh/preview.html` | Designer Portal customizable piece & material library (`PortalLibrary`, trade-authenticated, `Add to the project`). |
| `PortalPieceConfigurator` | `components/PortalConfigure/preview.html` | `components/PortalQuoteZh/preview.html` | Designer Portal custom piece & COM specification configurator (`PortalConfigure` + `SiteProject`) with `Add to the project` (zero retail PDP/cart chrome). |
| `PortalSampleTrayAndQuote` | `components/SampleTray/preview.html` | `components/PortalQuoteZh/preview.html` | Designer Sample Tray & Project BOM Quote (`SampleTray` / `PortalQuote` with Path A CDTFA-230 vs Path B client settlement, `Send to client`, and `Approve and pay the deposit`). |
| `SiteDesignerApplication` | `components/SiteApply/preview.html` | `components/SiteProcessZh/preview.html` | Designer partnership page (`SiteForDesigners` -> `Apply to join`) and application form (`SiteApply` -> `Send application`). |
| `SiteEditorialJournal` | `components/SiteJournal/preview.html` | `components/SiteHomeZh/preview.html` | Editorial journal (`SiteJournal`, `SiteArticle`) documenting LA residential architecture and designer collaborations. |
| `SiteHowItWorks` | `components/SiteHowItWorks/preview.html` | `components/SiteProcessZh/preview.html` | End-to-end LA design-to-delivery workflow (`SiteHowItWorks` / `SiteProcessZh` / `SiteAbout`). |
| `SiteAndPortalShowroom` | `components/PortalShowroom/preview.html` | `components/SiteShowroom/preview.html` | Los Angeles showroom (`Book a visit`) and physical material sample tray (`SiteShowroom` / `PortalShowroom`). |

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

- **Preferred `en-US` Terms**: `Good Design Finds Its Home.`, `Designers draw it. We make it, ship it and set it up.`, `See the homes`, `Apply to join`, `Add to the project`, `Send to client`, `shipped and set up in one visit`
- **Prohibited `en-US` Terms**: `Add to Cart`, `Add to Bag`, `Shop now`, `SUBMIT PROJECT BOM`, `Submit Project Drawings`, `Request Designer Trade Access`, `shoppable whole-room sets`, `Verified US Buyers`
- **Preferred `zh-Hans-US` Terms**: `好设计，自有归处。`, `设计师来画，我们负责做出来、送到、装好。`, `查看作品`, `申请加入`, `加入项目`, `发送给客户`, `一次上门送装`
- **Prohibited `zh-Hans-US` Terms**: `加入购物车`, `立即抢购`, `品牌入驻`, `全国配送`, `免费设计`, `美元`, `美刀`, `包邮`, `亲`
- **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"`).