UI 视觉设计 / 系统课时

表示字体和阴影等复合类型

表示字体和阴影等复合类型

字体样式同时包含字号、字重与行高,阴影也需要颜色、偏移和模糊参数。把它们压成字符串会让引用与校验失效。本课按 DTCG 2025.10 编写一份可复用的 Token JSON,并验证复合字段的类型与引用位置。

学习目标

  • 区分简单 Token、复合 Token 与字段级引用。
  • 正确填写 typography 和 shadow 的必需子字段。
  • 使用整项引用与 JSON Pointer 复用值,并检查常见错误。

判定简单值与复合值

一个字体族名称是 fontFamily 简单 Token,颜色是 color 简单 Token;一套文字样式使用 typography,一个阴影样式使用 shadow。在 DTCG 2025.10 中,Token 用 $type 声明类型,用 $value 存放值。复合值的子字段不是独立 Token,不应在其中随意嵌套 $type、$value。

复合类型 $value 必需字段 值的格式
typography fontFamily、fontSize、fontWeight、letterSpacing、lineHeight 字体族字符串/数组;字号与字距为维度对象;字重为数值或规范别名;行高为无单位数字
shadow color、offsetX、offsetY、blur、spread 颜色对象或颜色 Token 引用;其余四项为维度对象;可选 inset 布尔值

维度必须写成 {"value": 16, "unit": "px"} 这类对象;2025.10 允许 px 或 rem,即使是零也不能省略单位。lineHeight: 1.5 表示建议按字号的 1.5 倍计算,不能把它写成 "24px"。

编写字体与阴影数据文件

将以下内容保存为 tokens.json。示例同时包含基础字体和颜色 Token、两套文字样式及单层/双层阴影。颜色用 DTCG 的 sRGB 结构表示,不能直接用 "#00000026" 冒充 2025.10 的 color 值。

json
{
  "$schema": "https://www.designtokens.org/schemas/2025.10/format.json",
  "font": {
    "familyBody": {
      "$type": "fontFamily",
      "$value": [
        "Inter",
        "Arial",
        "sans-serif"
      ]
    }
  },
  "color": {
    "shadow": {
      "$type": "color",
      "$value": {
        "colorSpace": "srgb",
        "components": [
          0,
          0,
          0
        ],
        "alpha": 0.16
      }
    }
  },
  "typography": {
    "body": {
      "$type": "typography",
      "$value": {
        "fontFamily": "{font.familyBody}",
        "fontSize": {
          "value": 16,
          "unit": "px"
        },
        "fontWeight": 400,
        "letterSpacing": {
          "value": 0,
          "unit": "px"
        },
        "lineHeight": 1.5
      }
    },
    "heading": {
      "$type": "typography",
      "$value": {
        "fontFamily": "{font.familyBody}",
        "fontSize": {
          "value": 24,
          "unit": "px"
        },
        "fontWeight": 700,
        "letterSpacing": {
          "value": 0,
          "unit": "px"
        },
        "lineHeight": {
          "$ref": "#/typography/body/$value/lineHeight"
        }
      }
    }
  },
  "shadow": {
    "card": {
      "$type": "shadow",
      "$value": {
        "color": "{color.shadow}",
        "offsetX": {
          "value": 0,
          "unit": "px"
        },
        "offsetY": {
          "value": 4,
          "unit": "px"
        },
        "blur": {
          "value": 12,
          "unit": "px"
        },
        "spread": {
          "value": 0,
          "unit": "px"
        }
      }
    },
    "popover": {
      "$type": "shadow",
      "$value": [
        "{shadow.card}",
        {
          "color": "{color.shadow}",
          "offsetX": {
            "value": 0,
            "unit": "px"
          },
          "offsetY": {
            "value": 12,
            "unit": "px"
          },
          "blur": {
            "value": 24,
            "unit": "px"
          },
          "spread": {
            "value": 0,
            "unit": "px"
          }
        }
      ]
    }
  }
}

typography.body 对应 16px、400 字重和 1.5 倍行高,按 16 × 1.5 得到约 24px 行盒高度;typography.heading 是 24px、700 字重,引用相同行高倍率后约为 36px。shadow.card 的垂直偏移是 4px、模糊半径是 12px;shadow.popover 用数组表示两层阴影,第一层引用 shadow.card,第二层向下偏移 12px。

区分整项引用与字段引用

花括号引用如 {font.familyBody}、{color.shadow} 取目标 Token 的完整 $value,适合在复合值中复用已有字体或颜色。{shadow.card} 在阴影数组里复用完整的单层阴影对象。

如果只想复用行高,应使用 { "$ref": "#/typography/body/$value/lineHeight" }。这里 #/ 从当前 JSON 文档根部开始,$value/lineHeight 精确定位子字段;写成 {typography.body.lineHeight} 不合法,因为花括号不能直接指向复合值的内部属性。字段引用必须解析为目标字段所需的类型,且不能形成循环。

简单 Token、复合 Token 与字段引用关系

验证文件与修正常见错误

安装 Node.js 后,在 tokens.json 所在目录运行以下命令,先只检查 JSON 语法:

bash
node -e "JSON.parse(require('node:fs').readFileSync('tokens.json','utf8')); console.log('JSON syntax OK')"

预期输出:

text
JSON syntax OK

这一步不会检查 DTCG 结构和引用。还需使用支持 DTCG 2025.10 的校验工具或导入器,对照文件的 $schema 校验,并确认:typography 的五个必需字段齐全;shadow 每层包含五项;所有维度都具备 value、unit;$ref 指向存在的字段且无循环。

常见错误是把阴影写成 "0 4px 12px #0003"、把整套字体写成 "700 24px/1.5 Inter",或把 fontSize 简写成 "16px"。这些是 CSS 风格的字符串,不是这里要求的 DTCG 复合值。需要生成 CSS 时,应先解析 Token 和引用,再由转换器输出对应属性。规范依据:DTCG Format Module 2025.10。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

表示字体和阴影等复合类型

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通