@ch-ui/tokens
符號套件使CSS自定义属性集,a.k.a. CSS变量,可以放入Tailwind等公用系统或网页组件库的上游(或自动使用).
这个软件包使用原则性方法生成符号,目的是让平台开发者、应用程序开发者和终端用户都更容易维护和应用对应用程序设计系统符号的调整.
开始
pnpm add -D @ch-ui/tokens
那么,使用任意的渲染功能 如果你在使用Vite, 已经存在 @ch-ui/vite-plugin-tokens 如果你喜欢.
使用 PostCSS
要添加到您的 PostCSS 设置中 :
import chTokens from '@ch-ui/tokens/postcss';
import myTokenSet from './config';
//...
plugins: [
// ...
chTokens((params: string) => myTokenSet),
// ...
]
//...
在您的 PostCSS 中:
@layer tokens {
@tokens myTokens
}
别紧张.
如果你喜欢,可以使用 params 之后提供 @tokens。 。 。 .
如果出现空白画布综合症,则提供“默认符号集”:
import chTokens from '@ch-ui/tokens/postcss';
import { defaultTokenSet } from '@ch-ui/tokens';
import myTokenSet from './config';
//...
plugins: [
// ...
chTokens(
(params: string) => params === 'myProductionApp'
? myTokenSet
: defaultTokenSet
),
// ...
]
//...
背景情况
设计系统经常保持一套有意有限的设计标志,例如:
- 在“平板”中排列的具体颜色,
- 字体大小按“平面”或“平面坡道”排列.
这些 物理状态 符是最根本的地层,命名要使用的特定分级(数字)值. 同样的同义词可以在有条件的规则中重新定义,例如支持更广泛的游戏,例如: rec2020。 。 。 .
然后,物理符号的基层可以加一层 语义 符号,将有条件规则保护的物理值映射到一个连贯有意义的名称,例如 --fg-description (对于“前景颜色:描述”)可以默认地映射到一种物理颜色,也可以在下列情况下映射到另一种颜色: prefers-color-palette: dark。 。 。 .
物理序列
所有设计标志最终都符合物理价值,在 @ch-ui/tokens 由 a 生成 系列 沿连续线输入.
@ch-ui/tokens 执行三种系列:
- 线性, (中文(简体) ),
- 指数,以及
- 螺旋弧 彩色调色板
例如,软件包在一个指数序列中带有默认字体大小:
const defaultSizes = {
initial: 1,
unit: 'rem',
base: 1.2,
naming: {
'2xs': -3,
xs: -2,
s: -1,
base: 0,
lg: 1,
xl: 2,
'2xl': 3,
'3xl': 4,
'4xl': 5,
},
} satisfies ExponentialSeries;
这将输出物理符号于 rem 输入值 [-3, -2, -1, 0, 1, 2, 3, 4, 5] 使用等式 initial * Math.pow(base, input)。 。 。 .
层
编剧:
renderPhysicalLayer(physicalLayer: PhysicalLayer, semanticValues?: SemanticValues)renderSemanticLayer(semanticLayer: SemanticLayer)
物理和语义配置定义于 层 让你根据 条件,这些只是嵌入式 CSS 语句(按规则或选择者)。 此外,层是设置命名空间的地方.
例如,当浏览器支持更广泛的游戏时,包会带有默认的颜色,使用条件来重新定义符:
export const defaultPhysicalColors = {
conditions: {
srgb: [':root'],
p3: ['@media (color-gamut: p3)', ':root'],
rec2020: ['@media (color-gamut: rec2020)', ':root'],
},
series: {
neutral: {
srgb: neutralArc,
p3: neutralArc,
rec2020: neutralArc,
},
accent: {
srgb: accentArc,
p3: accentArc,
rec2020: accentArc,
},
},
namespace: 'ch-',
} satisfies ColorsPhysicalLayer;
请注意: neutralArc 财务报告和审定财务报表 accentArc 是重复的螺旋弧系列;重复是偶然的,因为您可能想要在不同条件下使用不同的系列。 如何具体适用于颜色,详见 @ch-ui/colors。 。 。 .
语义层
使用语义分层,可以定义在不同的条件下将哪些名称映射到不同的物理符号上. 如果物理层将其值描述为 系列,语义层将其值描述为 语句 (/ˈsɛmiːms/),将有意义的名称映射到层中每个条件的物理值.
例如,软件包带有默认的语义层,用于在光和暗模式之间应用颜色:
export const defaultSemanticColors = {
conditions: {
light: [':root'],
dark: ['@media (prefers-color-scheme: dark)', ':root'],
},
sememes: {
'bg-base': {
light: ['neutral', 975],
dark: ['neutral', 150],
},
'fg-base': {
light: ['neutral', 0],
dark: ['neutral', 900],
},
// etc
},
namespace: 'ch-',
} satisfies SemanticLayer;
语义表达式
语义层支持表达式,在表达式中,您可以在字面值上指定一些操作,或者引用另一个语义符号,例如:
export const defaultSemanticColors = {
// ...
sememes: {
'bg-base': {
// ...
},
'fg-base': {
light: ['neutral', '88f:bg-base'],
dark: ['neutral', '-88f:bg-base'],
},
// ...
},
// ...
} satisfies SemanticLayer;
有了这个配置, fg-base光和暗的值将被计算成一个值,如果每个值都导致 APCA 内值 ±88 当 fg-base 用作反对 bg-base。 。 。 .
在提到其他符号时注意,它们不能循环,最终必须达到字面价值.
有效操作取决于语义层配置的系列类型. 目前仅 f 财务报告和审定财务报表 b 行动得到支持,以及 f 财务报告和审定财务报表 b 仅适用于颜色序列 a.k.a. HelicalArcSeries。 。 。 .
面额
编剧: renderFacet(facet: Facet)。 。 。 .
为了更好的人文工程,物理和语义层可以合并成一个 侧像这样在一起的时候, @ch-ui/tokens 将自动推断语义层中提及的任何值应被添加到物理层的输入中。 如果您只使用语义值, 这意味着您不需要定义物理层中的任何值 .
打开所有符牌
所有符号都可以使用 renderTokenSet(tokenSet: TokenSet)。 。 。 .
A 类 TokenSet 这只是一个 Record<string, Facet> 包含您想要表达的方方面面.
审计
如果你想要更多关于系统为何会渲染物理标志的信息, 您可以对符号( 一次一个面) 进行审计 .
import { auditFacet } from '@ch-ui/tokens';
const colorsAudit = auditFacet(tokenSet.colors, { condition: 'p3' });