令牌

使用标记管理应用中的设计决策。

概述

¥Overview

设计令牌是一种与平台无关的管理应用或网站设计决策的方法。它是描述任何基本/原子视觉样式的属性集合。每个属性都是一个键值对。

¥Design tokens are the platform-agnostic way to manage design decisions in your application or website. It is a collection of attributes that describe any fundamental/atomic visual style. Each attribute is a key-value pair.

Chakra 中的设计 token 很大程度上受到 W3C 令牌格式的影响。

设计令牌包含以下属性：

¥A design token consists of the following properties:

value：token 的值。这可以是任何有效的 CSS 值。
description：可选的令牌用途描述。

定义标记

¥Defining Tokens

Token 在系统配置的 theme 键下定义。

¥Tokens are defined in the under the theme key in your system config.

theme.ts

import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"

const config = defineConfig({
  theme: {
    tokens: {
      colors: {
        primary: { value: "#0FEE0F" },
        secondary: { value: "#EE0F0F" },
      },
      fonts: {
        body: { value: "system-ui, sans-serif" },
      },
    },
  },
})

export const system = createSystem(defaultConfig, config)

warning

Token 值需要嵌套在具有 value 键的对象中。这是为了让将来能够使用像 description 这样的其他属性。

使用标记

¥Using Tokens

定义令牌后，我们建议使用 Chakra CLI 为你的令牌生成主题类型。

¥After defining tokens, we recommend using the Chakra CLI to generate theme typings for your tokens.

npx @chakra-ui/cli typegen ./src/theme.ts

这将为你的编辑器中的令牌提供自动补齐功能。

¥This will provide autocompletion for your tokens in your editor.

<Box color="primary" fontFamily="body">
  Hello World
</Box>

令牌参考语法

¥Token reference syntax

Chakra UI 允许你在 CSS 属性（例如 border、padding 和 box-shadow）的复合值中引用设计令牌。这是通过 token 引用语法实现的：{path.to.token}。

¥Chakra UI enables you to reference design tokens within composite values for CSS properties like border, padding, and box-shadow.\ This is achieved through the token reference syntax: {path.to.token}.

note

使用完整的令牌路径非常重要；例如，你不能使用 red.300，而必须将其引用为 colors.red.300。

¥It is important to use the complete token path; for example, instead of using red.300, you must reference it as colors.red.300.

以下是将 token 引用语法应用于 border 和 p（padding）属性的示例：

¥Here’s an example where token reference syntax is applied to both the border and p (padding) props:

<Box
  border="1px solid {colors.red.300}"
  p="{spacing.4} {spacing.6} {spacing.8} {spacing.10}"
  boxShadow="{spacing.4} {spacing.2} {spacing.2} {colors.red.300}"
/>

令牌嵌套

¥Token Nesting

Token 可以嵌套，以创建 token 的层次结构。当你想将相关的 token 分组在一起时，这很有用。

¥Tokens can be nested to create a hierarchy of tokens. This is useful when you want to group related tokens together.

info

使用 DEFAULT 键定义嵌套 token 的默认值。

¥Use the DEFAULT key to define the default value of a nested token.

theme.ts

import { createSystem, defaultConfig, defineConfig } from "@chakra-ui/react"

const config = defineConfig({
  theme: {
    tokens: {
      colors: {
        red: {
          DEFAULT: { value: "#EE0F0F" },
          100: { value: "#EE0F0F" },
        },
      },
    },
  },
})

export default createSystem(defaultConfig, config)

<Box
  // 👇🏻 This will use the `DEFAULT` value
  bg="red"
  color="red.100"
>
  Hello World
</Box>

令牌类型

¥Token Types

颜色

¥Colors

颜色具有含义，并支持内容的目的，例如传达信息层次结构和状态。它通常定义为字符串值或对其他标记的引用。

¥Colors have meaning and support the purpose of the content, communicating things like hierarchy of information, and states. It is mostly defined as a string value or reference to other tokens.

theme.ts

import { defineTokens } from "@chakra-ui/react"

const tokens = defineTokens({
  colors: {
    red: {
      100: { value: "#fff1f0" },
    },
  },
})

export default createSystem({
  theme: { tokens },
})

渐变

¥Gradients

渐变令牌表示两种或多种颜色之间的平滑过渡。它的值可以定义为字符串或复合值。

¥Gradient tokens represent a smooth transition between two or more colors. Its value can be defined as a string or a composite value.

theme.ts

import { defineTokens } from "@chakra-ui/react"

const tokens = defineTokens({
  gradients: {
    // string value
    simple: { value: "linear-gradient(to right, red, blue)" },

    // composite value
    primary: {
      value: { type: "linear", placement: "to right", stops: ["red", "blue"] },
    },
  },
})

export default createSystem({
  theme: { tokens },
})

尺寸

¥Sizes

大小标记表示元素的宽度和高度。其值定义为字符串。

¥Size tokens represent the width and height of an element. Its value is defined as a string.

theme.ts

import { defineTokens } from "@chakra-ui/react"

const tokens = defineTokens({
  sizes: {
    sm: { value: "12px" },
  },
})

export default createSystem({
  theme: { tokens },
})

大小标记通常用于 width、height、minWidth、maxWidth、minHeight、maxHeight 属性。

间距

¥Spacing

间距标记表示元素的边距和填充。其值定义为字符串。

¥Spacing tokens represent the margin and padding of an element. Its value is defined as a string.

theme.ts

import { defineTokens } from "@chakra-ui/react"

const tokens = defineTokens({
  spacing: {
    gutter: { value: "12px" },
  },
})

export default createSystem({
  theme: { tokens },
})

间距标记通常用于 margin、padding、gap 和 {top,right,bottom,left} 属性。

字体

¥Fonts

字体标记表示文本元素的字体系列。它的值可以定义为字符串或字符串数组。

¥Font tokens represent the font family of a text element. Its value is defined as a string or an array of strings.

theme.ts

import { defineTokens } from "@chakra-ui/react"

const tokens = defineTokens({
  fonts: {
    body: { value: "Inter, sans-serif" },
    heading: { value: ["Roboto Mono", "sans-serif"] },
  },
})

export default createSystem({
  theme: { tokens },
})

字体标记通常用于 font-family 属性。

字体粗细

¥Font Weights

字体粗细标记表示文本元素的粗细。其值定义为字符串。

¥Font weight tokens represent the weight of a text element. Its value is defined as a string.

theme.ts

import { defineTokens } from "@chakra-ui/react"

const tokens = defineTokens({
  fontWeights: {
    bold: { value: "700" },
  },
})

export default createSystem({
  theme: { tokens },
})

字体粗细标记通常用于 font-weight 属性。

字母间距

¥Letter Spacings

字母间距标记表示文本元素中字母之间的间距。其值定义为字符串。

¥Letter spacing tokens represent the spacing between letters in a text element. Its value is defined as a string.

const tokens = defineTokens({
  letterSpacings: {
    wide: { value: "0.1em" },
  },
})

export default createSystem({
  theme: { tokens },
})

字母间距标记通常用于 letter-spacing 属性。

线条高度

¥Line Heights

行高标记表示文本行的高度。其值定义为字符串。

¥Line height tokens represent the height of a line of text. Its value is defined as a string.

theme.ts

import { defineTokens } from "@chakra-ui/react"

const tokens = defineTokens({
  lineHeights: {
    normal: { value: "1.5" },
  },
})

export default createSystem({
  theme: { tokens },
})

行高标记通常用于 line-height 属性。

半径

¥Radii

Radii 令牌表示边框的半径。其值定义为字符串。

¥Radii tokens represent the radius of a border. Its value is defined as a string.

theme.ts

import { defineTokens } from "@chakra-ui/react"

const tokens = defineTokens({
  radii: {
    sm: { value: "4px" },
  },
})

export default createSystem({
  theme: { tokens },
})

Radii 令牌通常用于 border-radius 属性。

边框

¥Borders

边框是围绕 UI 元素的线。你可以将它们定义为字符串值或复合值。

¥A border is a line surrounding a UI element. You can define them as string values or as a composite value

theme.ts

import { defineTokens } from "@chakra-ui/react"

const tokens = defineTokens({
  borders: {
    // string value
    subtle: { value: "1px solid red" },
    // string value with reference to color token
    danger: { value: "1px solid {colors.red.400}" },
    // composite value
    accent: { value: { width: "1px", color: "red", style: "solid" } },
  },
})

export default createSystem({
  theme: { tokens },
})

边框标记通常用于 border、border-top、border-right、border-bottom、border-left、outline 属性。

边框宽度

¥Border Widths

边框宽度标记表示边框的宽度。其值定义为字符串。

¥Border width tokens represent the width of a border. Its value is defined as a string.

theme.ts

import { defineTokens } from "@chakra-ui/react"

const tokens = defineTokens({
  borderWidths: {
    thin: { value: "1px" },
    thick: { value: "2px" },
    medium: { value: "1.5px" },
  },
})

export default createSystem({
  theme: { tokens },
})

阴影

¥Shadows

阴影标记表示元素的阴影。其值定义为单个值或包含字符串或复合值的多个值。

¥Shadow tokens represent the shadow of an element. Its value is defined as single or multiple values containing a string or a composite value.

theme.ts

import { defineTokens } from "@chakra-ui/react"

const tokens = defineTokens({
  shadows: {
    // string value
    subtle: { value: "0 1px 2px 0 rgba(0, 0, 0, 0.05)" },
    // composite value
    accent: {
      value: {
        offsetX: 0,
        offsetY: 4,
        blur: 4,
        spread: 0,
        color: "rgba(0, 0, 0, 0.1)",
      },
    },
    // multiple string values
    realistic: {
      value: [
        "0 1px 2px 0 rgba(0, 0, 0, 0.05)",
        "0 1px 4px 0 rgba(0, 0, 0, 0.1)",
      ],
    },
  },
})

export default createSystem({
  theme: { tokens },
})

阴影标记通常用于 box-shadow 属性。

缓动

¥Easings

缓动标记表示动画或过渡的缓动功能。它的值可以定义为表示三次贝塞尔曲线的字符串或值数组。

¥Easing tokens represent the easing function of an animation or transition. Its value is defined as a string or an array of values representing the cubic bezier.

theme.ts

import { defineTokens } from "@chakra-ui/react"

const tokens = defineTokens({
  easings: {
    // string value
    easeIn: { value: "cubic-bezier(0.4, 0, 0.2, 1)" },
    // array value
    easeOut: { value: [0.4, 0, 0.2, 1] },
  },
})

export default createSystem({
  theme: { tokens },
})

缓动标记通常用于 transition-timing-function 属性。

不透明度

¥Opacity

不透明度标记可帮助你设置元素的不透明度。

¥Opacity tokens help you set the opacity of an element.

theme.ts

import { defineTokens } from "@chakra-ui/react"

const tokens = defineTokens({
  opacity: {
    50: { value: 0.5 },
  },
})

export default createSystem({
  theme: { tokens },
})

不透明度标记通常用于 opacity 属性。

Z 轴索引

¥Z-Index

此 token 类型表示元素在 z 轴上位置的深度。

¥This token type represents the depth of an element's position on the z-axis.

theme.ts

import { defineTokens } from "@chakra-ui/react"

const tokens = defineTokens({
  zIndex: {
    modal: { value: 1000 },
  },
})

export default createSystem({
  theme: { tokens },
})

Z-index 标记通常用于 z-index 属性。

资源

¥Assets

资源标记表示 URL 或 svg 字符串。它的值可以定义为字符串或复合值。

¥Asset tokens represent a url or svg string. Its value is defined as a string or a composite value.

type CompositeAsset = { type: "url" | "svg"; value: string }
type Asset = string | CompositeAsset

theme.ts

import { defineTokens } from "@chakra-ui/react"

const tokens = defineTokens({
  tokens: {
    assets: {
      logo: {
        value: { type: "url", value: "/static/logo.png" },
      },
      checkmark: {
        value: { type: "svg", value: "<svg>...</svg>" },
      },
    },
  },
})

export default createSystem({
  theme: { tokens },
})

资源标记通常用于 background-image 属性。

持续时间

¥Durations

持续时间标记表示动画或动画周期完成所需的时间长度（以毫秒为单位）。其值定义为字符串。

¥Duration tokens represent the length of time in milliseconds an animation or animation cycle takes to complete. Its value is defined as a string.

theme.ts

import { defineTokens } from "@chakra-ui/react"

const tokens = defineTokens({
  durations: {
    fast: { value: "100ms" },
  },
})

export default createSystem({
  theme: { tokens },
})

持续时间标记通常用于 transition-duration 和 animation-duration 属性。

动画

¥Animations

动画令牌代表一个关键帧动画。其值定义为字符串值。

¥Animation tokens represent a keyframe animation. Its value is defined as a string value.

theme.ts

import { defineTokens } from "@chakra-ui/react"

const tokens = defineTokens({
  animations: {
    spin: {
      value: "spin 1s linear infinite",
    },
  },
})

export default createSystem({
  theme: { tokens },
})

动画令牌通常用于 animation 属性。

宽高比

¥Aspect Ratios

宽高比标记表示元素的宽高比。其值定义为字符串。

¥Aspect ratio tokens represent the aspect ratio of an element. Its value is defined as a string.

theme.ts

import { defineTokens } from "@chakra-ui/react"

const tokens = defineTokens({
  aspectRatios: {
    "1:1": { value: "1 / 1" },
    "16:9": { value: "16 / 9" },
  },
})

export default createSystem({
  theme: { tokens },
})

概述

语义令牌

令牌

.css-vfo6uh{color:var(--chakra-colors-fg);-webkit-text-decoration:underline;text-decoration:underline;text-underline-offset:3px;text-decoration-thickness:2px;text-decoration-color:var(--chakra-colors-border-emphasized);font-weight:500;}概述

概述