Back to Details

design-system

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Design System

设计系统

Mục tiêu: dịch các mô tả cảm tính của user ("đẹp như Grab", "tối giản hơn") thành giá trị cụ thể, cố định, để code sinh ra nhất quán qua nhiều lần chạy.
目标：将用户的感性描述（如“像Grab一样美观”、“更简约”）转化为具体、固定的参数值，确保多次运行生成的代码保持一致。

Giá trị mặc định (đọc/ghi vào 
openspec/config.yaml
mục 
context
, phần "Design tokens" - nếu project chưa có thì thêm mới)

默认参数值（读取/写入至
openspec/config.yaml
的
context
项中“Design tokens”部分——若项目未包含则新增）

yaml
colors:
  primary: "#..."      # brand color - lấy từ config.yaml nếu user đã cung cấp, nếu chưa dùng Material 3 seed mặc định
  surface: "#FFFFFF"
  error: "#B3261E"
spacing:
  xs: 4
  sm: 8
  md: 16
  lg: 24
  xl: 32
radius:
  sm: 8
  md: 12
  lg: 16
typography:
  base: Material 3 default (Roboto) trừ khi user chỉ định font khác
elevation:
  card: 1
  dialog: 3
yaml
colors:
  primary: "#..."      # 品牌色 - 若用户已提供则从config.yaml获取，未提供则使用Material 3默认种子色
  surface: "#FFFFFF"
  error: "#B3261E"
spacing:
  xs: 4
  sm: 8
  md: 16
  lg: 24
  xl: 32
radius:
  sm: 8
  md: 12
  lg: 16
typography:
  base: Material 3 default (Roboto) 除非用户指定其他字体
elevation:
  card: 1
  dialog: 3

Quy tắc áp dụng

应用规则

  • Không dùng số magic (
    padding: 13
    , màu hex rời rạc trong widget) — luôn tham chiếu token ở trên qua 
    Theme.of(context)
    hoặc file 
    app/theme/
    .
  • Khi user nói cảm tính, dịch sang thay đổi token cụ thể rồi ghi lại vào 
    openspec/config.yaml
    (mục 
    context
    ), ví dụ:
    • "Đẹp như Grab" → tăng contrast, bo góc 
      radius.md
      cho card, dùng màu primary đậm, spacing rộng rãi hơn (
      md
      /
      lg
      ).
    • "Tối giản hơn" → giảm elevation, giảm số màu dùng trên 1 màn hình, tăng khoảng trắng.
  • Mỗi lần đổi token, cập nhật vào 
    config.yaml
    để lần sau agent tự đọc, không hỏi lại / không đoán lại từ đầu (config được inject tự động vào mọi artifact OpenSpec).
  • 禁止使用魔法数值（如
    padding: 13
    、widget中零散的十六进制颜色值）——始终通过
    Theme.of(context)
    或
    app/theme/
    文件引用上述参数。
  • 当用户提出感性需求时，将其转化为具体参数值的修改并写入
    openspec/config.yaml
    的
    context
    项中，例如：
    • “像Grab一样美观” → 提高对比度，为卡片设置
      radius.md
      圆角，使用深色调主色，采用更宽松的间距（
      md
      /
      lg
      ）。
    • “更简约” → 降低阴影层级，减少单屏使用的颜色数量，增加留白。
  • 每次修改参数后，更新至
    config.yaml
    ，以便后续Agent自动读取，无需再次询问/重新推断（配置会自动注入所有OpenSpec工件）。

Khi UI-checkpoint bị từ chối ("chưa đúng ý")

当UI检查点被拒绝（“不符合需求”）时

  • Hỏi lại đúng 1 câu để xác định thay đổi cụ thể (ví dụ: "to chữ hơn hay đổi màu?"), KHÔNG hỏi nhiều câu cùng lúc.
  • Map câu trả lời của user sang token cụ thể ở trên, sửa, rồi quay lại 
    mcp-loop
    để build lại.
  • 仅用一个问题确认具体修改方向（例如：“是要放大字体还是更改颜色？”），禁止同时提出多个问题。
  • 将用户的回答映射为上述具体参数，修改后返回
    mcp-loop
    重新构建。

Widget Library ưu tiên tái sử dụng

优先复用组件库

Trước khi tạo widget mới, kiểm tra 
shared/widgets/
đã có chưa (Card, BottomSheet, OTP input, AddressPicker, ChatBubble, Timeline, Dashboard...). Ưu tiên tái sử dụng, chỉ tạo mới khi thực sự chưa có.
在创建新组件前，先检查
shared/widgets/
中是否已有对应组件（如Card、BottomSheet、OTP输入框、地址选择器、聊天气泡、时间线、仪表盘等）。优先复用组件，仅在确实不存在时才创建新组件。