Figma sang Claude Code — Ngữ cảnh thiết kế có cấu trúc cho CLI của Anthropic

Chỉ dẫn "không triển khai lại các component đã tồn tại" quan trọng khi danh mục component được chia sẻ. Claude Code có thể đọc design/components/inventory.json để xác định component nào đã được triển khai và import chúng thay vì tạo lại.

Kết nối design tokens

tokens.json được xuất bởi figmascope sử dụng cấu trúc lồng nhau theo phong cách W3C với các trường $value và $type:

{
  "color": {
    "surface":    { "$value": "#f6f2ea", "$type": "color" },
    "ink":        { "$value": "#1f1d1a", "$type": "color" },
    "accent":     { "$value": "#d96a3a", "$type": "color" }
  },
  "spacing": {
    "1": { "$value": "4px",  "$type": "dimension" },
    "2": { "$value": "8px",  "$type": "dimension" },
    "4": { "$value": "16px", "$type": "dimension" },
    "8": { "$value": "32px", "$type": "dimension" }
  },
  "typography": {
    "body": {
      "fontFamily": { "$value": "Inter",  "$type": "fontFamily" },
      "fontSize":   { "$value": "14px",   "$type": "dimension" },
      "lineHeight": { "$value": 1.45,     "$type": "number" }
    }
  }
}

Yêu cầu Claude Code tạo khối mở rộng theme tailwind.config.ts từ tệp này như bước đầu tiên, trước khi triển khai bất kỳ màn hình nào. Điều đó đảm bảo tất cả các triển khai màn hình tiếp theo có thể sử dụng các alias token Tailwind một cách nhất quán:

claude --print "Read design/tokens.json and generate a tailwind.config.ts
theme.extend block. Map color tokens to theme.extend.colors,
spacing tokens to theme.extend.spacing, and typography to
theme.extend.fontFamily / fontSize. Output only the config object."

Xem Xuất Design Token cho AI Agents để tìm hiểu sâu hơn về định dạng token và cơ chế suy luận tần suất mà figmascope sử dụng khi Figma Variables không được thiết lập.

Xử lý lớp chuỗi

Mỗi node văn bản trong tệp Figma được ghi vào một slot trong strings.json. Các khóa sử dụng ký pháp dấu chấm được suy ra từ hệ thống phân cấp frame:

{
  "home.hero.title":        "Everything you need",
  "home.hero.subtitle":    "Ship faster with structured context",
  "home.cta.primary":      "Get started",
  "settings.account.heading": "Account settings"
}

Hướng dẫn Claude Code sử dụng các khóa này làm định danh i18n. Thay vì hardcode chuỗi "Everything you need" trong JSX, component được tạo ra gọi t('home.hero.title') (hoặc tương đương trong thư viện i18n của bạn). Tệp tài nguyên đã có trong strings.json — bạn chỉ cần import nó hoặc kết nối với cài đặt i18n của mình.

Nếu figmascope phát hiện va chạm — hai node hash thành cùng một khóa — nó phát ra cảnh báo strings-collision trong _meta.json và thêm hậu tố số để giải quyết mơ hồ. Kiểm tra _meta.json trước khi bắt đầu phiên để bạn biết điều gì cần mong đợi.

Tích hợp CLAUDE.md

Nếu bạn sử dụng tệp ngữ cảnh dự án CLAUDE.md, hãy thêm một phần ngắn trỏ tác nhân đến thư mục thiết kế. Điều này kết hợp tốt với cách tiếp cận được mô tả trong AI Design Handoff và bổ sung cho lý do figmascope khác với các plugin Figma inspector.

Thêm phần thiết kế như thế này:

## Design context

Design tokens, layout IR, reference renders, and strings live in `design/`.
Always read `design/CONTEXT.md` before implementing any screen.
Token values are in `design/tokens.json` — never hardcode color or spacing.
Component canonical names are in `design/components/inventory.json`.

Điều này có nghĩa là mỗi phiên Claude Code trong dự án sẽ tự động có ngữ cảnh thiết kế như một phần kiến thức làm việc của nó, mà không cần bạn phải lặp lại trong mỗi prompt.

Những gì tác nhân thực sự làm đúng

Với ngữ cảnh có cấu trúc, Claude Code đáng tin cậy trong:

• Giá trị spacing — vì chúng có trong tokens.json dưới dạng spacing.4 → 16px, không ước tính từ ảnh chụp màn hình
• Màu sắc — giá trị hex chính xác, không phải "trông như một màu cam ấm"
• Typography — font family, size, weight, line-height, tất cả được đánh máy
• Hướng bố cục — các node stack có trường direction và gap rõ ràng
• Đặt tên component — inventory.json là nguồn chuẩn, vì vậy không có tên được tạo ra
• Copy — strings.json ngăn tác nhân diễn giải lại hoặc bịa ra văn bản giữ chỗ

Những gì vẫn cần đánh giá của con người: trạng thái tương tác (hover, focus, active) không hiển thị trong các frame Figma tĩnh, thời gian animation và các breakpoint responsive không được thiết kế rõ ràng trong tệp. IR nắm bắt bố cục tĩnh; hành vi động nằm ngoài phạm vi.

Sử dụng --dangerously-skip-permissions trong môi trường được kiểm soát

Đối với các pipeline tự động mà bạn muốn Claude Code hoạt động mà không cần lời nhắc phê duyệt tương tác — ví dụ trong bước CI tạo stub component sau khi cập nhật thiết kế — bạn có thể sử dụng --dangerously-skip-permissions. Chỉ phù hợp trong môi trường sandbox không có thông tin xác thực sản xuất.

claude --dangerously-skip-permissions --print "$(cat <<'EOF'
Read design/CONTEXT.md. Generate component stub files for any components
in design/components/inventory.json that don't already exist in src/components/.
Use TypeScript + React functional component format. Include a TODO comment
for each component referencing the relevant screen JSON.
EOF
)"

Trong các quy trình làm việc phát triển sản xuất, hãy để permissions tương tác. Các lời nhắc tồn tại vì lý do chính đáng — Claude Code có thể và sẽ ghi tệp, và bạn muốn biết tệp nào trước khi nó làm.

Kiểm tra cảnh báo xuất trước khi bạn nhắc

figmascope phát ra cảnh báo vào _meta.json cho các điều kiện có thể ảnh hưởng đến chất lượng đầu ra. Kiểm tra chúng trước khi bắt đầu phiên Claude Code:

python3 -c "
import json
meta = json.load(open('design/_meta.json'))
for w in meta.get('warnings', []):
    print(f\"{w['code']}: {w['message']}\")
print(f\"Frames exported: {meta['frameCount']}\")
print(f\"Tokens source: {meta.get('tokensSource', 'variables')}\")
"

Hai cảnh báo cần chú ý:

• layout-mode-none-inferred — một frame không có auto-layout được đặt. figmascope suy luận bố cục từ vị trí tuyệt đối của con, ít đáng tin cậy hơn. Đánh dấu màn hình liên quan trong prompt của bạn: "Màn hình này sử dụng vị trí tuyệt đối; tạo code tương ứng."
• strings-collision — hai node văn bản tạo ra cùng khóa tài nguyên. figmascope giải quyết mơ hồ bằng hậu tố số, nhưng bạn nên xác minh chuỗi trong strings.json là đúng trước khi tác nhân tạo các lệnh gọi i18n.

Quy trình Android và iOS

Claude Code không bị giới hạn ở các framework web. Gói ngữ cảnh là framework-agnostic — layout IR và tokens là dữ liệu, không phải CSS. Đối với Jetpack Compose:

claude --print "$(cat <<'EOF'
Read design/CONTEXT.md and design/tokens.json.

Implement design/screens/Home.json as a Jetpack Compose screen.
- Map color tokens to a MaterialTheme ColorScheme
- Map spacing tokens to Dp values (strip 'px' suffix, use .dp)
- Map typography tokens to MaterialTheme.typography
- Use the component names from design/components/inventory.json as Composable names
- Reference design/screens/Home.png for visual accuracy
EOF
)"

Các node stack của IR ánh xạ tự nhiên thành Column (hướng dọc) và Row (hướng ngang) trong Compose. Các node leaf với type: "text" trở thành composable Text; type: "image" trở thành Image hoặc placeholder. Xem Jetpack Compose từ Figma để biết pattern đầy đủ.

Phiên bản gói thiết kế

Xử lý thư mục design/ như bất kỳ dependency dự án nào khác. Khi thiết kế thay đổi đáng kể, xuất lại từ figmascope.dev, commit và ghi chú thay đổi trong PR:

# Check when the bundle was last exported vs when Figma file was last modified
python3 -c "
import json
from datetime import datetime
meta = json.load(open('design/_meta.json'))
exported = datetime.fromisoformat(meta['exportedAt'].replace('Z', '+00:00'))
modified = datetime.fromisoformat(meta['figmaLastModified'].replace('Z', '+00:00'))
delta = modified - exported
if delta.total_seconds() > 0:
    print(f'WARNING: Figma file was modified {delta} after last export')
else:
    print('Bundle is current')
"

Gói lỗi thời có nghĩa là tác nhân đang làm việc từ một thiết kế lỗi thời. Việc kiểm tra dấu thời gian bắt điều này trước khi bạn dành thời gian cho phiên codegen dựa trên thông số đã lỗi thời.