让开源，少一点语言距离。
npm包中文文档

@canonical/token-types

中文文档
0.44.0发布于 2026/10/23LGPL-3.0TypeScriptES Module零依赖构建来源已验证近 30 天下载 5916

Shared types for Canonical design token tooling.

原始使用文档
中文原文
文档目录6 节
  1. Installation
  2. Usage
  3. Exports
  4. Types
  5. Runtime
  6. Development

@canonical/token-types

Shared TypeScript types for Canonical design token tooling. This package defines the JSON contract between the Terrazzo CSS plugin (producer) and the LSP (consumer) — the tokens.json artifact format.

Installation

bun add -d @canonical/token-types

Usage

Import types for working with the tokens.json artifact:

import type { Artifact, ArtifactToken, ArtifactEnvelope } from "@canonical/token-types";

function loadTokens(json: ArtifactEnvelope): Artifact {
  if ("tokens" in json) return json.tokens; // wrapped envelope
  return json;                               // flat artifact
}

Use the runtime guard to narrow DTCG type strings:

import { isKnownDtcgTokenType } from "@canonical/token-types";

if (isKnownDtcgTokenType(token.type)) {
  // token.type is narrowed to KnownDtcgTokenType
}

Exports

Types

TypeDescription
ArtifactThe complete artifact: CSS variable name to token metadata.
ArtifactTokenA single token entry combining metadata, resolved values, source location, derivation, and registration fields.
ArtifactTokenInitInput contract for constructing a DTCG-sourced artifact token.
DerivedArtifactTokenInitInput contract for constructing a derived or plugin-generated token.
ArtifactEnvelopeUnion of flat Artifact and WrappedArtifactEnvelope — the plugin may emit either.
WrappedArtifactEnvelopeArtifact payload with version, generator, and tokens fields.
ArtifactDeclarationA declaration site (selector, file, line, enclosing at-rules).
ArtifactAtRuleAn at-rule context (name + prelude).
DtcgTokenTypeDTCG $type values — known literals with a string escape hatch for forward compatibility.
KnownDtcgTokenTypeThe known DTCG type literals (color, dimension, number, etc.).
TokenTierTier classification: "primitive", "semantic", or "derived".
ArtifactTierTier strings carried by artifacts — known tiers plus a string escape hatch.
DerivationKindDerivation formula kinds ("hover", "active", "disabled", "delta", etc.).

Runtime

ExportDescription
KNOWN_DTCG_TOKEN_TYPESconst array of all recognised DTCG type literals.
isKnownDtcgTokenType(value)Type guard narrowing a string to KnownDtcgTokenType.

Development

bun run build     # Compile (tsc)
bun run test      # Run type-level tests
bun run check     # Type check

版本与发布记录

@canonical/token-types 共发布 21 个版本，首次发布于 2026/03/11；过去 12 个月发布了 21 个版本。最新版本附带 npm provenance 构建来源证明，可追溯到公开的 CI 构建记录。

版本发布日期距今
0.44.0latest2026/10/2317 天前
0.43.02026/10/011 个月前
0.43.0-experimental.0experimental2026/09/291 个月前
0.10.02026/09/092 个月前
0.9.02026/09/072 个月前
0.8.12026/07/203 个月前

关于 @canonical/token-types 的常见问题

@canonical/token-types 是什么？

Shared types for Canonical design token tooling.

如何安装 @canonical/token-types？

在项目目录运行 npm install @canonical/token-types，或使用 pnpm add / yarn add / bun add。

@canonical/token-types 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@canonical/token-types 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node.js 20.19+ / 22.12+ 可以直接 require() 不含顶层 await 的 ES Module，更早的版本需要改用动态 import()。

@canonical/token-types 需要什么版本的 Node.js？

package.json 的 engines 字段要求 Node.js >=22。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

@canonical/token-types 可以商用吗？

@canonical/token-types 使用 LGPL-3.0 许可。弱 Copyleft：作为库被调用时通常不要求开源你自己的代码，但修改库本身需以 LGPL 开源；前端打包合并后的适用边界存在不同理解。以上为概括，不构成法律意见，请以许可原文为准。

@canonical/token-types 的下载量有多少？

根据 npm 官方下载统计，@canonical/token-types 在 2026/10/09 – 2026/11/07 这 30 天内被下载 5,916 次，日均约 197 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@canonical/token-types 还在维护吗？

最新版本 0.44.0 发布于 2026/10/23（17 天前）；至今共发布 21 个版本，其中过去 12 个月发布了 21 个；首次发布于 2026/03/11。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。