Kalka
文档

组件与变量

带有变体和属性的可复用组件,包含集合与模式的变量页面,以及变量如何变成 CSS 自定义属性和设计令牌。

docs / components-variables

组件

组件是可以重复使用的设计:按钮、卡片、导航栏。它的副本叫作实例,会跟随组件变化。修改组件,所有实例都会随之改变,实例中覆盖过的部分除外。

  • 创建组件: 选中图层,按 Cmd Alt K(Ctrl Alt K)。
  • 创建实例: 从 资源 面板把组件拖到画布上,或使用其中的 插入实例。
  • 转到主组件 从实例跳转到它的组件。
  • 分离实例(Cmd Alt B,Ctrl Alt B)把实例还原为普通图层。

资源 面板以网格或列表列出文档中的组件,并支持搜索。

变体

变体是同一个组件的不同版本,比如一个按钮有主要和次要、小号和大号之分。选中多个组件,使用 创建组件集(Shift Cmd K,Ctrl Shift K),然后添加变体属性及其取值。每个变体的取值组合必须唯一。在实例上,可以从设计面板切换变体。

组件属性

除了变体,组件还可以公开:

  • 文本 属性,用于在每个实例上修改标签文字;
  • 布尔值 属性,用于显示或隐藏某个部分;
  • 实例切换 属性,用于替换嵌套的组件,比如图标;
  • 插槽,每个实例都可以在其中放入自己的图层,并可限制数量。

在设计面板中使用 创建属性… 创建,或者在某个字段上使用 将组件属性应用到 该字段。实例会在设计面板顶部显示这些属性。

行为

组件可以像真实控件一样工作:开关、复选框、滑块、标签页、文本框、手风琴、带有悬停、按下、聚焦和禁用状态的按钮等。在组件的 行为 部分中选择。随后,视图 › 预览(Cmd Alt Enter)会让这些控件真正运行:你可以在文本框里输入、拖动滑块、展开手风琴,也可以用键盘操作。试用期间文档不会有任何改动;按 Esc 返回编辑。

库

要在文档之间共享组件,先用 发布库 把一个文档发布为库,再在另一个文档中通过 管理库 启用它。库有变化时,查看库更新 会在你更新之前展示改动,可以并排对比,也可以叠加对比。

变量

变量是可复用的命名值:品牌色、间距、字号、标签文字。修改变量,所有用到它的图层都会随之改变。

打开变量页面

点击左侧栏中的 变量。在桌面编辑器中,变量页面会覆盖在面板和画布之上。再次点击 变量、选择其他面板或按 Esc,画布就会恢复原样。也可以通过 视图 › 变量…,或在未选中任何内容时点击设计面板中的 打开变量 来打开。在手机屏幕上,它以对话框形式打开。

打开 Tokens 集合的变量页面:颜色、间距和圆角变量,带有浅色和深色取值及 CSS 名称,下方是生成的样式表
变量页面:每个变量的 CSS 名称和每个模式下的取值,以及 Kalka 生成的样式表。

类型

类型 用于
颜色 填充、描边、阴影颜色
数字 尺寸、间距、圆角、不透明度、字号
文本 标签、文案、字体系列
布尔值 真或假,比如是否显示某个图层

变量可以通过 范围 限定在某些字段中使用,这样间距变量就不会出现在颜色列表里。它的 CSS 表达式 可以让它在代码中保存类似 clamp(1rem, 4vw, 1.5rem) 的值。

集合与模式

变量存放在 集合 中,比如 Colors 或 Spacing,并可以分组整理。集合可以有多个 模式:浅色和深色、紧凑和宽松、每个品牌一个。每个变量在每个模式下都有一个取值。

每个模式都规定了它在导出的 CSS 中何时生效:

  • 手动切换,使用 data-theme 之类的属性;
  • 系统处于深色或浅色模式时;
  • 开启高对比度或减弱动态效果时;
  • 屏幕宽度或容器宽度低于或高于某个值时;
  • 或者在你编写的任意 CSS 选择器或 @media、@supports、@container 查询下。

使用变量

点击字段旁的 使用变量,从小列表中选择一个;悬停在颜色或数字变量上,会在画布上预览效果。解除变量绑定 会把它改回普通值。对于已经设置好的值,从该值创建颜色变量 或 从该值创建数字变量 可以一步把它变成变量。

代码中的变量

变量就是 CSS 自定义属性。每个集合的默认模式写在 :root 中,其他模式只在各自的条件下覆盖不同的值。名为 Gray/50 的变量会变成 --color-gray-50,Space/small 会变成 --spacing-small;你也可以自己设置 CSS 名称。

在变量页面中,你可以:

  • 将所有变量复制为 CSS,或 将所有变量复制为 Tailwind 主题(@theme);
  • 导出为设计令牌: W3C 设计令牌的 .zip,每个集合模式一个文件;
  • 导入设计令牌:从 .json、.tokens 或 .zip 文件导入。同名变量会被更新,不会删除任何内容。

在 Kalka 文件夹中,变量以 W3C 设计令牌的形式保存在 design-system/tokens.json,并以 CSS 形式保存在 design-system/tokens.css。参见文件与版本。