Atlas

HouseSigma 新市场项目。三端原生（Web + iOS + Android），以 designs/design.pen 作为设计 SoT，通过 Pencil MCP 抽取 DTCG tokens 并手工实现组件。数据目前全 mock，Phase 4 接入真实后端。

Quick Start

pnpm install
bash scripts/gen-models.sh           # JSON Schema → TS/Swift/Kotlin types
bash scripts/sync-pen-tokens.sh      # pen → DTCG tokens.json → CSS/Tailwind/Swift/Kotlin
pnpm --filter web dev                # Next.js dev server（包名是 "web"）

sync-pen-tokens.sh 依赖本地安装的 Pencil CLI（brew install pencil 或 npm i -g @pencil.dev/cli）+ 一次性 pencil login。CI 用 PENCIL_CLI_KEY 环境变量。如果只想从已有 tokens.json 重建产物（不抓 pen），跑 bash scripts/gen-tokens.sh。

iOS：cd apps/ios && xcodebuild -scheme Atlas -destination 'platform=iOS Simulator,OS=18.6' Android：cd apps/android && ./gradlew assembleDebug

Clean clone 额外一次性：

make hooks                           # 激活 pre-commit hook（符号链接 .githooks → .git/hooks）

Directory Structure

目录	作用
designs/design.pen	设计 SoT。Pencil MCP 读写，不手动解析
packages/design-tokens/tokens.json	DTCG tokens，从 pen 抽取的产物，不手工编辑
packages/design-tokens/gen/	CSS / Swift / Kotlin / Tailwind theme 产物
packages/json-schema/	JSON Schema 数据模型源头 → TS/Swift/Kotlin types
packages/shared/	纯 TS 工具 + 生成的 model 类型
packages/ui/	React 组件库，手工实现，视觉对齐 pen
apps/web/	Next.js 15 App Router，MSW mock
apps/ios/	SwiftUI，iOS 17+，独立 Xcode 项目
apps/android/	Compose，API 31+，独立 Gradle 项目
specs/mock-data/	三端共享 mock 数据
scripts/	gen-tokens.sh / gen-models.sh / validate-native.sh
docs/pen-workarounds.md	DTCG 无法平直映射的 pen 问题台账
.claude/	Claude 操作入口：skills/d2c.md、rules/pen-sot.md

Design → Code 两阶段

Phase A — Tokens（pen → DTCG → code）

designs/design.pen ──Pencil MCP `get_variables` ──► DTCG tokens.json
                                                       │
                                                       └─► build.ts
                                                            ├─► gen/css/tokens.css  (:root + .dark)
                                                            ├─► gen/css/tailwind-theme.css (@theme)
                                                            ├─► gen/swift/** + HSColors.xcassets
                                                            └─► gen/kotlin/**

无 validator。tokens.json 作为 DTCG 产物，由 Claude 在会话里通过 Pencil MCP 抽取并写入，然后 pnpm --filter @atlas/design-tokens build 生成各端代码。

Phase B — Components（pen → tsx 手工实现）

packages/ui/atoms/ 和 packages/ui/composites/ 以 pen 的可复用节点（batch_get({reusable:true})）为视觉 ground-truth 手工实现，使用 Tailwind v4 utility + var(--color-*)。无 codegen，以 get_screenshot 对照校验。

Phase C — Screens（暂未启用）

待 A/B 稳定后再基于 pen 屏幕 frame 单独实现。

核心约束

• designs/design.pen 是 SoT — 任何冲突只能 code → pen 对齐；做不到的走 docs/pen-workarounds.md 回流给设计方
• packages/design-tokens/tokens.json 不手工编辑 — 它是 DTCG 产物，来源是 pen get_variables
• 颜色/间距/字号用 token — 禁止硬编码 hex（例外 #fff / #000 / 透明阴影）
• DTCG 合规 — tokens.json 遵循 DTCG 1.0 基础结构；多 mode 走 $extensions 命名空间（见 .claude/rules/pen-sot.md）
• 分支：feature/DEL-{id}-{slug} ／ 提交：Conventional Commits（type(scope): description）

深入文档

主题	文档
Design → Code 入口（两阶段管线 + Pencil MCP 工作流）	.claude/skills/d2c.md
Pen SOT 规则 + DTCG 合规 + workaround 流程	.claude/rules/pen-sot.md
Pen 工作台账（反向提交给设计侧）	docs/pen-workarounds.md
Token 使用规则 / 通用禁止项	.claude/rules/never.md
Claude 操作上下文入口	CLAUDE.md

Tooling

• Node 20、pnpm 9.15+、Bun（TS 脚本运行时）
• Turbo（monorepo 编排）、Vitest（单测）、Playwright（视觉回归）
• Pencil MCP（designs/*.pen 交互读写，提供 get_variables / batch_get / get_screenshot 等工具）