@canonical/terrazzo-lsp

语言服务器为设计令牌工作流程提供CSS自定义属性智能. 读取 tokens.json 构建文物并提供CSS和SCSS文件的编辑功能.

特征

编辑器设置

VS 代码 (建议):

npm install -D @canonical/design-tokens
npx @canonical/terrazzo-lsp-extension

扩展自动检测 bun 先掉头 node >= 22。 。 。 .

国 际

npx terrazzo-lsp --stdio                # Start LSP server on stdio
npx terrazzo-lsp --stdio --allow-degraded  # Start with reduced capabilities when config is missing
npx terrazzo-lsp check [globs]          # Run diagnostics on CSS files
npx terrazzo-lsp status                 # Show config and artifact status
npx terrazzo-lsp inspect <var>          # Inspect a CSS custom property
npx terrazzo-lsp resolve <spec>         # Resolve an import specifier
npx terrazzo-lsp graph <file>           # Show import graph from a file

参考文献

LSP发布14个诊断码. CSS诊断在工作空间的每个CSS/SCSS文件中运行. DTCG 诊断在装入时运行一次 tokens.json 文物和鉴定是否符合 DTCG 2025。 10 规格。 每个诊断可以配置到 "error", (中文(简体) ), "warning", (中文(简体) ), "info",或 "off" 内 terrazzo-lsp.config.json。 。 。 .

CSS 诊断实例

下面的例子触发一个文件中的每个 CSS 诊断:

/* Assume the following tokens exist in the artifact:
 *   --color-fg           : oklch(17.2% 0 0)        tier: semantic, type: color
 *   --spacing-sm         : 0.5rem                   tier: semantic, type: dimension
 *   --color-palette-blue : oklch(50% 0.15 250)      tier: primitive, type: color
 *   --button-pad         : 0.75rem                  tier: semantic, scoped to .button
 *   --unreachable-token  : 1rem                     (in a file not imported by this sheet)
 */

/* css/unknown-var — off by default, enable via config */
.unknown   { margin: var(--does-not-exist); }

/* css/missing-fallback — no fallback for a non-artifact property */
.missing   { padding: var(--local-pad); }

/* css/stale-fallback — resolved value is 0.5rem, not 16px */
.stale     { gap: var(--spacing-sm, 16px); }

/* css/type-mismatch — colour token in a length context */
.type-err  { width: var(--color-fg); }

/* css/type-uncertain — dimension in a shorthand accepting many types */
.type-warn { background: var(--spacing-sm); }

/* css/unreachable-token — output file not in @import graph */
.unreach   { margin: var(--unreachable-token); }

/* css/primitive-token — prefer semantic alias */
.primitive { color: var(--color-palette-blue); }

/* css/scoped-usage — --button-pad is scoped to .button */
.card      { padding: var(--button-pad); }

/* css/no-color-scheme — light-dark() without color-scheme */
.no-scheme { color: light-dark(black, white); }

DTCG 诊断例

DTCG诊断在符号定义本身的表面问题. 这些出现在 tokens.json 文物条目, 不在 CSS 文件中 :

{
  // dtcg/broken-alias — alias target does not exist
  "color.ghost":   { "aliasChain": ["color.nonexistent"], "type": "color" },

  // dtcg/schema-violation — "not-a-colour" is not a valid CSS colour
  "color.invalid": { "valueLight": "not-a-colour", "type": "color" },

  // dtcg/circular-alias — loop-a → loop-b → loop-a
  "color.loop-a":  { "aliasChain": ["color.loop-b", "color.loop-a"], "type": "color" },

  // dtcg/missing-type — no $type field, type is ambiguous
  "spacing.bare":  { "valueLight": "4px", "type": null },

  // dtcg/draft-syntax — uses pre-standard value/type without $ prefix
  "color.legacy":  { "type": "color", "extensions": { "com.terrazzo.draft-syntax": true } }
}

压制语法

诊断可用下列评论压制:

/* Disable all checks for a region: */
/* terrazzo-lsp-disable */
.suppressed { width: var(--color-fg); }
/* terrazzo-lsp-enable */

/* Disable a specific code for the next line: */
/* terrazzo-lsp-disable css/primitive-token */
.selective { color: var(--color-palette-blue); }
/* terrazzo-lsp-enable css/primitive-token */

配置

创建一个 terrazzo-lsp.config.json 在工作空间根中:

{
  "artifacts": ["@canonical/design-tokens/dist/tokens.json"],
  "globalStylesheets": [".storybook/styles.css"]
}

如果没有配置文件, 输出面板记录每个候选路径 尝试,打印一个可复制的启动配置,然后退出。 临时 降低启动、通过 --allow-degraded。 。 。 .

{ "artifacts": ["@canonical/design-tokens/dist/tokens.json"] }

完整配置参考

{
  "artifacts": [],
  "distDir": "dist",
  "scanGlobs": ["src/**/*.css", "src/**/*.scss"],
  "globalStylesheets": null,
  "diagnostics": {
    "unknownProperties": "off",
    "missingFallback": "warning",
    "staleFallback": "warning",
    "typeMismatch": "error",
    "typeUncertain": "info",
    "unreachableToken": "warning",
    "primitiveToken": "warning",
    "scopedDeclaration": "warning",
    "lightDarkNoScheme": "info",
    "brokenAlias": "error",
    "schemaViolation": "error",
    "circularAlias": "error",
    "inferredType": "info",
    "draftFormat": "info",
    "ignoreGlobs": []
  },
  "hover": {
    "showColourSwatches": true,
    "showSelectorContext": true,
    "showProvenanceBadge": true,
    "showAliasChain": true,
    "showSourceLocation": true,
    "showNavigationTier": true,
    "showSpecReferences": true
  },
  "inlayHints": {
    "enabled": false,
    "showColourSwatches": true
  },
  "logLevel": "info"
}

VS 代码扩展设置

发展

建筑

LSP 服务器主要分为四层:

诊断管道:

CSS diagnostics:  orchestrateDiagnostics → per-rule check modules → makeDiagnostic
DTCG diagnostics: produceArtifactDiagnostics → per-rule check modules → makeDiagnostic

每个诊断规则都生活在自己的档案中(diagnostics/checkMissingFallback.ts, (中文(简体) ), artifactDiagnostics/checkBrokenAlias.ts(例如) 与同一地点 .tests.ts 文档。 管弦乐团绕过用法(CSS)或道具(DTCG)并代表每个检查功能.

bun run build      # Compile LSP server (tsc)
bun run test       # Run tests
bun run check      # Lint + type check