---
title: "Theme Studio"
description: "拨动几个控件，看真实的组件随之变化，然后导出一个有效的设计系统层，可以为每个平台构建。"
url: "https://tanrei.chnotchy.com/zh-cn/foundations/theme-studio/"
last_updated: 2026-10-26T22:31:37.000Z
---

# Theme Studio

> 拨动几个控件，看真实的组件随之变化，然后导出一个有效的设计系统层，可以为每个平台构建。

设计系统应当默认就让人觉得恰当，并在你改动一处时跟着你变化。Studio 把这个想法做成了可以上手摆弄的东西：选一个基础系统、转一个调节量、挑一种颜色、改一个令牌、添加一个你自己的令牌——然后导出那个小小的[层文件](https://tanrei.chnotchy.com/zh-cn/foundations/design-systems/#%E8%AE%BE%E8%AE%A1%E7%B3%BB%E7%BB%9F%E6%98%AF%E4%B8%80%E4%B8%AA%E5%B1%82)，里面写的正是你改了什么，除此之外什么都没有。

- [打开 Theme Studio](https://tanrei.chnotchy.com/zh-cn/studio/): 在单独的页面中打开 Studio，整个窗口都用来预览。

这里没有任何东西是效果图。预览是真实的系统作用域和真实的组件，应用的正是 `tanrei build` 会为你的层写出的那份样式表——由同一个引擎、同一个生成器和同样的无障碍检查在你的浏览器里算出。仓库的测试用 CLI 的流水线构建 Studio 的层，要求整份样式表、六种配色方案下的每个令牌值以及每条警告都完全一致。

你的主题会呈现在用这些组件搭成的五个界面上：汇集各类组件的概览、仪表盘、设置表单、列表与详情，以及一个文档页面。可以切换浅色、深色或两者并排显示，也可以在三档对比度下分别查看。看哪个界面、怎么看，都不属于主题本身，因此都不会保存到文件中。

你正在制作的层保存在这个浏览器里，也保存在页面的地址中：Studio 的链接打开后就是同一个层。打开链接不会覆盖浏览器里保存的层：Studio 上方会出现一条横幅，说明链接带来的是哪个层、它基于哪个系统；在你编辑它或选择保留它之前，你原来的层一直保留着，你也可以回到原来的层。

Studio 顶栏最前面是**层的起点**：默认系统 Tanrei，或主题库的示例——m3-like、cupertino 和 m3-expressive-like。这些示例展示一个层能模仿到什么程度，并不是原系统的官方设计。Tanrei 的根层 Core 也列在其中，但暂时不能选：它仍带有默认系统的值，等这些值变为中性后，它就会成为空白起点。在同一个菜单里，还可以导入一个层文件来替换正在编辑的层：schema 不接受的文件不会载入，面板会说明原因；接受的文件会载入，令牌引擎发现的问题会列在面板里。层里有更改时，Studio 会在替换前先询问，**撤销**可以把更改找回来。

Studio 顶栏中的**导出**会打开一个侧边面板，里面是文件以及接下来怎么用。第一行说明 schema、令牌引擎和构建检查是否接受这个文件。从主题库的示例开始的层，默认依赖这个示例：文件很小，并随示例的改进而更新。你也可以写出所有值，这样示例改变时文件也不会变；不过属于示例的组件仍从示例引入。下面依次是：可以复制或下载的文件本身；`tanrei build` 为 Web 写出的样式表中与基础系统不同的声明，以及可下载的完整样式表；还有接下来的步骤，其中每条命令 CLI 都能照原样接受，另有一个分享这个层的链接。

左侧栏列出外观的九个部分——品牌色、灰色、字体、尺寸、圆角、圆角平滑、图标、按下时的反馈和焦点样式——每一项都显示当前的值和一个小样本，下面是层所包含的其他内容。点一行，右侧面板就会显示它的控件。锁定你喜欢的行，再点**随机搭配**，其他每一行都会换成另一个值，撤销一次即可恢复。**检查**会在面板上方打开全部令牌和层文件本身。每一处改动都可以撤销和重做，用 Studio 顶栏里的按钮，或者用 ⌘Z 和 ⇧⌘Z（Ctrl+Z 和 Ctrl+Shift+Z）。

## 各个控件写入什么

| 你做的事 | 层得到的内容 |
| --- | --- |
| 选择基础系统 | `"extends"` |
| 拨动一个调节量 | `dial.*` 上的 `"$value"`，附带 `reason` |
| 选择种子色或色相 + 色度，声明或去掉一个调色板 | `"palettes"` 中的一个条目——`null` 表示去掉继承来的调色板 |
| 把调色板的某个色调固定为精确的颜色 | 该调色板的 `source.tones`——`{ "40": "#e60012" }`；新的一行以生成的颜色为初始值 |
| 排列 **Brand**、**Plain** 或 **Mono** 的字体族顺序，选择通用回退字体，把平台的字体放在第一位 | `ref.typeface.*` 上的 `{ "$value": ["IBM Plex Sans", "system-ui", "sans-serif"], "reason": "…" }` |
| 选择图标集——一个可变字体族，或每种选中状态一个字体族——以及它的字重和填充 | `ref.typeface.icon` 或 `sys.icon.family.*`、`sys.icon.weight`、`sys.icon.fill.*` 上固定的 `$value` |
| 拖动圆角平滑滑块 | `sys.shape.corner-smoothing` 上的 `{ "$value": 0.6, "reason": "…" }`——一个 0–1 的量，含义与 Figma 相同（[形状](https://tanrei.chnotchy.com/zh-cn/foundations/shape/#%E5%9C%86%E8%A7%92%E5%B9%B3%E6%BB%91)） |
| 选择按下如何得到反馈、焦点长什么样 | `sys.behavior.*` 上的 `{ "$value": 1, "reason": "…" }`——你选的是**名称**（`ripple`、`glow`）；文件里存的是它的位置 |
| 缩放一个令牌 | `{ "scale": n }`——相对于它所继承的值的比例，仍然由它的调节量驱动 |
| 重新指向一个令牌 | `{ "$value": "{another.token}" }` |
| 固定一个令牌 | `{ "$value": …, "reason": "…" }`——不受任何调节量影响；有了理由才会写入 |
| 替换一条规则 | `{ "derive": … }`——调节量上的系数、颜色角色的色调表、状态用的 `mix` 或 `alpha` |
| 编辑模式规则 | `"rules"`——悬停、聚焦、按下和禁用的样子，一次作用于所有组件 |
| Add…：添加一种尺寸或变体、序列中的一个级别、一个你自己的令牌 | `"vocabulary"` 下的一条声明，必须带 `rationale` |

Typefaces、Icons、Shape 和 Behaviour 写入的是固定值，而固定值需要理由：这四组各问一次，并预先填好（“Brand typeface.”），它写入的每个固定值都带着你的措辞。在**检查**的令牌树中，种类选择按名称挑选，从不以数字输入；字体栈则是与**字体**一行中相同的有序列表。预览里的按钮是真的，所以 `ripple`、`dim`、缓和过渡的圆角和焦点光晕，就是 `<tanrei-button>` 在这个浏览器里用这些令牌实际画出的结果。字阶预览会画出每种字体的一个标题、一段连续文本、一个标签和一段代码——以及你的层添加的每种文本样式——预览栏上的 **Emphasized** 开关会按各自角色的字重加上该字体族的 `sys.typescale.emphasis.*` 级差重新绘制它们，直接取自样式表。当某个选择什么也画不出来时——例如所有按下不透明度都是 1 的情况下选择 `dim`，默认系统就是如此——构建自己的警告会一字不差地显示在控件下方，警告提到的令牌则是通往其编辑器的链接。

保持基础取值不动的控件什么也不写，所以一个没碰过的 Studio 导出的是 `{ "id", "extends" }`，构建结果与基础系统完全相同。有效的层所能包含的任何内容，在这里都可以编辑——导入一个层时，不会有任何东西被搁在一边。

## 用在你自己的文件上

`tanrei studio` 在本地提供这个 Studio，并让它指向你产品的层文件：你一边编辑，改动一边保存到文件；**Build** 运行 `tanrei build`；文件在背后发生变化时——被编辑器修改，或执行了 `git checkout`——Studio 会让你选择重新加载，还是保留当前打开的内容。它绝不会悄悄覆盖。只有当 schema、层链的规则和令牌引擎都接受这个层时，保存才会写入——服务器询问的是引擎本身，并用引擎的消息作答——所以无论发送它的是哪个程序，磁盘上的文件始终是 `tanrei build` 能构建的文件。这个应用还会从它自己的地址提供 Tanrei 内置系统所指定的文本字体和图标字体（Inter、Noto Sans JP、Roboto Mono、Roboto、Material Symbols Rounded 和 Outlined），所以预设是用它自己的字体绘制的。

产品可以把自己的层叠起来——`acme-app.system.json` 扩展它旁边的 `acme.system.json`。`tanrei studio` 会把你的文件旁边的那些层以只读方式交给 Studio，Studio 在浏览器里解析整条层链，与处理内置系统时完全一样；父层在磁盘上发生变化时，一切都会重新计算。

## 它做不到的事

在本站上，Studio 背后没有文件，所以扩展了你自己某个层的层无法在这里导入——请用 `tanrei studio` 打开它，它知道旁边有哪些文件。除了提供它的站点之外，Studio 绝不从别处获取字体：该站点不提供、你的浏览器也没有的字体族会被指出名字，预览则如实显示回退字体。它的“预览等于构建”测试比较的是 Web 样式表、令牌包和警告；原生平台的输出由 `tanrei build` 从同一个模型生成。

命令行工具不接受在命令中传入层：先用 `tanrei init` 创建一个层，再用从“导出”下载的文件替换它。