ss-lint

用途

ss-lint 是一个快速的设计系统代码检查（lint）工作流，用于在数秒内检测常见的设计系统违规。它面向已有的 UI 文件，在请求或构建工作流要求时运行，不检查无关的编辑。

在开始前，需遵循每会话一次的更新预检（preflight）。

主要能力

注册表优先的产物边界

当 .styleseed/project.json 与 .styleseed/artifacts/index.json 存在时，先解析所请求的产物 ID，然后只读取 .styleseed/bundles/<artifact-id>.md 与 .styleseed/manifests/<artifact-id>.json。对于注册表项目，绝不回退到全局的 legacy bundle。仅当不存在注册表时，legacy 项目才可使用 .styleseed/effective-rules.md。

规范化的可执行检查

要进行可复现、与产物绑定的扫描并获得机器可读输出，使用：

node <installed-ss-score>/scripts/styleseed-check.mjs scan \
  --project-root . --artifact <artifact-id> --format json
node <installed-ss-score>/scripts/styleseed-check.mjs scan \
  --project-root . --all --format sarif

检查器仅将 contract、containment、manifest/hash、malformed-report 以及必需覆盖率（required coverage）失败视为硬错误。检测器发现项（SS001–SS006）保持为警告，并包含稳定的文件、行号、证据片段、严重级别与修复建议。使用 styleseed-check ... verify 重新计算绑定的证据运行；不要将字符串或过时报告当作通过。

若任一注册表文件存在，则要求一个完整有效的注册表，并只检查所选产物的 bundle 与 manifest。仅当两个注册表文件都不存在时，才读取 .styleseed/effective-rules.md 与 .styleseed/manifest.json。在仅 lint 的请求中，报告缺失或过时的证据，而不重新生成 bundles。Lint 检测确定性的漂移；不得将精确的 grammar/recipe/profile/adapter 契约标记为违规，也不得让任意的 lock 值创建例外。

检查项

以下是手动审查提示，用于适用的项目约定，而非附加的硬错误检测器。

硬编码颜色：在 className 字符串中搜索应为语义 token 的十六进制颜色。例如 text-[#3C3C3C]、bg-[#3182F6]，应改为 text-text-primary、bg-brand。
Tailwind 中的原始像素值：例如 p-[24px]、gap-[12px]，应改为 p-6、gap-3。
旧的宽高语法：例如 w-4 h-4，应改为 size-4。
物理方向属性（仅 LTR）：例如 ml-2、mr-4，应改为 ms-2、me-4。
未契约的纯黑：在没有精确结构角色的情况下使用纯黑，应使用语义 ink token，或引用要求纯黑的维护契约。
缺失 data-slot：组件缺少 data-slot，应添加 data-slot="component-name"。
字号 CSS 变量（关键 — Tailwind v4 冲突）：例如 text-[var(--text-sm)] 或 theme.css 中的 --text-sm: 13px，应使用显式的 text-[13px]。CSS 变量字号会与 Tailwind v4 的 --text-* 命名空间冲突——Tailwind 会将其读取为颜色而非字号。
未使用 cn() 的 className：例如模板字符串 className，所有 className 组合都应使用 cn()。
通用软卡片漂移：在 pattern 文件中搜索重复的 rounded-2xl、shadow-[var(--shadow-card)] 与 mx-6。当所选 recipe 不是 calm-consumer 时，标记该组合，改用 ss-pattern-surface、ss-page-gutter 等 recipe 感知的辅助类。

使用方式

使用上述规范化检查器进行可执行诊断。在请求或构建工作流要求时对受影响的 UI 文件运行；不要 lint 无关的编辑。在仅 lint 模式下不要编辑代码。一旦必需的检查通过，仅在相关变更或出现新的问题证据后重复运行。仅当所有产物明确在范围内时才使用 --all。

输出格式

🔴 FAIL  [file:line] Hardcoded hex: text-[#3C3C3C] → use text-text-primary
🔴 FAIL  [file:line] Raw px: p-[24px] → use p-6
🟡 WARN  [file:line] Physical prop: ml-2 → use ms-2
🟡 WARN  [file:line] Missing data-slot on MyComponent
🟢 PASS  No violations found

Total: X errors, Y warnings

如果错误数大于 0，为每个违规列出具体修复。

适用场景

快速检查 UI 文件是否存在常见的设计系统违规。
在构建工作流中作为可执行诊断运行。
需要机器可读输出（JSON/SARIF）时进行可复现的产物绑定扫描。

限制

不适用场景：对设计判断（构图、层级、节奏）的更深层审查使用 /ss-review；无障碍专项使用 /ss-a11y；Nielsen UX 启发式使用 /ss-audit；应用重构不在此列——本工具仅标记发现项，由授权的实现步骤负责修复。
仅 lint 模式下不得编辑代码。
不得将精确的 grammar/recipe/profile/adapter 契约标记为违规，也不得让任意 lock 值创建例外。
在仅 lint 请求中不得重新生成 bundles。
目标参数：$ARGUMENTS。