Cursor Composer có thể viết rất nhiều code UI. Điều nó không thể làm là đọc file Figma của bạn. Dán ảnh chụp màn hình vào và nó đoán — spacing sai, giá trị màu được bịa ra, tên component không khớp với bất cứ thứ gì trong codebase của bạn. Vấn đề không phải là model. Đó là thiếu context có cấu trúc.
figmascope giải quyết điều đó. Nó xuất file Figma của bạn dưới dạng zip bundle: design tokens, cây layout từng màn hình, render tham chiếu 2×, component inventory, và UI strings — tất cả những gì agent của Cursor cần để tạo ra code chính xác thay vì code trông có vẻ hợp lý.
Hướng dẫn này bao gồm toàn bộ pipeline: URL Figma → context bundle → Cursor prompt → output được xem xét.
Có gì trong bundle
Khi figmascope xuất file của bạn, zip chứa:
CONTEXT.md— thông số mà agent đọc đầu tiên. Liệt kê framework mục tiêu, nguồn token, các ràng buộc, và các khoảng trống đã biết.tokens.json— design tokens có kiểu: spacing, border-radius, color, typography.screens/<name>.json— intermediate representation từng màn hình: các node stack/overlay/absolute/leaf với fill, spacing, và string ref.screens/<name>.png— render tham chiếu 2× để xác nhận trực quan.components/inventory.json— id, name, và type của component.strings.json— UI strings với khóa resource dot-notation._meta.json— build manifest: tên file nguồn, timestamp xuất, cảnh báo.
Bundle nằm trên máy của bạn. Nó không bao giờ được tải lên lại ở đâu.
Bước 1: Tạo bundle
Truy cập figmascope và dán URL file Figma của bạn vào trường nhập. Trình xuất chạy trong trình duyệt của bạn theo Figma REST API — bạn sẽ cần personal access token lần đầu tiên (được lưu trong localStorage, không bao giờ gửi đến máy chủ figmascope).
Nhấn Export Agent Context. Trang xử lý từng frame, giải quyết token, xây dựng IR, sau đó tải xuống context-bundle.zip về máy của bạn.
Nếu file của bạn có nhiều frame, chỉ các frame cấp cao nhất không phải component hay thumbnail mới được bao gồm. _meta.json hiển thị chính xác những frame nào được xuất và bất kỳ cảnh báo nào (gradient fill, các hiệu ứng không được hỗ trợ).
Bước 2: Giải nén vào project
Đặt bundle ở nơi Cursor có thể thấy nó — một thư mục design/ ở root repo của bạn là mẫu sạch nhất.
# từ root project của bạn
unzip ~/Downloads/context-bundle.zip -d ./design/
# xác minh cấu trúc
ls design/
# CONTEXT.md _meta.json components/ screens/ strings.json tokens.jsonThêm design/ vào .gitignore nếu bạn không muốn commit bundle. Hoặc commit nó — nó có tính xác định; cùng file Figma ở cùng trạng thái luôn tạo ra cùng bundle, vì vậy các diff có ý nghĩa.
Bước 3: Thêm đoạn .cursorrules
Cursor đọc .cursorrules ở root repo và thêm nó vào đầu mỗi chat context. Đây là nơi bạn kết nối agent với bundle.
# .cursorrules
When building UI screens:
1. Read ./design/CONTEXT.md first. It specifies the target framework and constraints.
2. Use tokens from ./design/tokens.json for all spacing, color, radius, and typography values.
3. Reference ./design/screens/<name>.json for layout structure and node hierarchy.
4. Match ./design/screens/<name>.png for visual confirmation — use it as a sanity check, not the source of truth.
5. Use string keys from ./design/strings.json rather than hardcoding UI copy.
6. Do not invent token values. If a value isn't in tokens.json, flag it.Khối đơn này ngăn chặn ba nguồn drift phổ biến nhất: màu được bịa ra, chuỗi hardcoded, và đoán layout từ screenshot.
Bước 4: Mở Cursor Composer và triển khai một màn hình
Mở Composer (Cmd+I trên macOS). Ghim các file trước khi prompt: nhấp vào biểu tượng ghim và thêm design/CONTEXT.md, design/tokens.json, và design/screens/home.json. Sau đó prompt:
Implement the home screen from ./design/screens/home.json.
Constraints:
- Target framework and component conventions are in ./design/CONTEXT.md
- All spacing, color, and radius values must come from ./design/tokens.json
- UI strings must use keys from ./design/strings.json
- The root node is a stack (vertical). Children are declared in order in the JSON.
- Do not invent any values not present in the token or IR files.Cursor sẽ đọc các file được ghim, ánh xạ các node IR đến các primitive của framework, và tạo ra triển khai. Output được tham chiếu token — nếu bạn kiểm tra code được tạo ra, mỗi giá trị spacing phải truy ngược đến một khóa trong tokens.json.
Bước 5: Xem xét và lặp lại
Mở design/screens/home.png cùng với output được render. PNG là bản xuất 2× từ Figma — nó hiển thị chính xác thiết kế trông như thế nào. Sự khác biệt có ý nghĩa: chúng chỉ ra các khoảng trống mapping IR hoặc các giá trị token chưa được áp dụng.
Các vấn đề phổ biến và prompt tiếp theo:
Token drift — agent sử dụng hex hardcoded thay vì token:
Compare every color value in the generated component against ./design/tokens.json.
List any colors that don't match a token key. Replace them with the correct token reference.Thiếu component — IR tham chiếu đến một component ID mà agent không giải quyết được:
The IR references componentId "btn-primary-01". Check ./design/components/inventory.json
for its name and type, then implement a placeholder with that name and the correct token values.Layout lệch — spacing hoặc alignment không khớp với PNG:
The vertical gap between the header and the card list should be spacing.24 from tokens.json (24dp).
Your output uses 16px. Fix it.Cái gì hoạt động, cái gì không
Hoạt động tốt: màn hình phẳng với layout stack, spacing và color được điều khiển bởi token, văn bản với string ref, các mẫu card và list đơn giản. Cursor xử lý tốt những điều này khi IR đã trong context — nó ngừng đoán và bắt đầu ánh xạ.
Hoạt động kém hơn: các overlay được định vị tuyệt đối phức tạp (Cursor đôi khi đọc sai tọa độ offset), gradient fill (được đánh dấu là cảnh báo trong _meta.json — Cursor sẽ xấp xỉ), và icon vector (IR chỉ lưu trữ ID tham chiếu, không phải dữ liệu path).
Chỉ dùng screenshot vs. bundle: chỉ dùng screenshot nhanh hơn để bắt đầu nhưng không xác định. Mỗi phiên bắt đầu lại từ đầu. Model có thể làm đúng spacing một lần và bỏ lỡ nó ở lượt tiếp theo. Bundle có thể tham chiếu trên toàn bộ phiên — Cursor có thể kiểm tra output của chính mình theo file token tại bất kỳ điểm nào mà không cần tải lên lại bất cứ thứ gì.
Mẹo: kiểm tra cảnh báo _meta.json trước khi prompt
Trước prompt triển khai đầu tiên, đọc design/_meta.json. Mảng warnings liệt kê bất cứ thứ gì trình xuất không thể giải quyết hoàn toàn: gradient fill, thiếu token mapping, các frame với ảnh nhúng. Thêm ghi chú về những điều này vào prompt của bạn để agent không cố triển khai chúng và âm thầm rơi lại vào giá trị hardcoded.
cat design/_meta.json | python3 -m json.tool | grep -A 20 '"warnings"'Nếu output hiển thị "gradientFill: not fully supported" trên một node cụ thể, hãy nói với Cursor bỏ qua background của node đó và để lại comment // TODO: gradient thay thế.
Tóm tắt
Quy trình làm việc là: xuất một lần, tham chiếu mọi nơi. Bundle là thông số ổn định, có thể đọc được bởi máy tính mà Cursor có thể tham khảo qua nhiều lượt mà không cần xử lý lại thiết kế. Bạn nhận được code chính xác token, được tham chiếu chuỗi, đúng layout thay vì xấp xỉ screenshot — và khi có gì đó trôi dạt, bạn có thể chỉ agent trở lại nguồn sự thật chỉ trong một dòng.
Tự chạy trên figmascope.dev — dán URL Figma của bạn, nhấn Export Agent Context, và giải nén bundle vào workspace Cursor của bạn trong dưới hai phút.