@evilmartians/设计-林特

使用 Tailwind v4 工程设计脚本规则 氧化剂。 。 。 .

规则将彩色,打字,角光度 保存在你的设计系统。 它们捕捉出硬编码的颜色,Tailwind调色板的颜色,本地的暗模分枝,无效的符号名称,以及组件颜色的覆盖. 它们也捕取了任意的打字和radi.

npm install --save-dev @evilmartians/design-lint oxlint

设置

创建 oxlint.config.ts数字 :

import { defineConfig } from "oxlint";
import { designLint } from "@evilmartians/design-lint/preset";

export default defineConfig(
  await designLint({
    tokenFiles: ["src/styles.css"],
    componentSources: ["@/components/ui/*"],
  }),
);

tokenFiles 是定义您的样式表 --color-* 标志.

componentSources 是您设计系统组件的导入路径。 写得跟你的密码一样 例如,如果您的应用程序导入 #/components/ui/button,使用时 #/components/ui/*没有 @/components/ui/*。 。 。 .

如果工程没有组件库, 请通过 componentSources: []关机 no-component-color-override。 。 。 .

预设

选择带有预设 preset 选项 :

• "strict" (default) 启用所有规则,包括检查符名、主题和组件变体。 这需要 componentSources; 通过 [] 如果您没有组件库.
• "basic" 启用仅需要符号样式表的检查。 奥米 componentSources; 此预设拒绝 .

见 规则 每个预设的规则及其要求.

await designLint({
  preset: "basic",
  tokenFiles: ["src/styles.css"],
});

您可以使用 basic; 见 配置。 。 。 .

保持现有 .oxlintrc.json

奥克林特拒绝在 oxlint.config.ts 财务报告和审定财务报表 .oxlintrc.json 坐在同一个目录中,上面的设置需要TypeScript配置. 为了保持JSON的配置不变,重新命名它(至 oxlint.base.json,并合并为:

import { defineConfig, type OxlintConfig } from "oxlint";
import { designLint } from "@evilmartians/design-lint/preset";
import json from "./oxlint.base.json" with { type: "json" };

const base = json as OxlintConfig;
const design = await designLint({
  tokenFiles: ["src/styles.css"],
  componentSources: ["@/components/ui/*"],
});

export default defineConfig({
  ...base,
  jsPlugins: [...(base.jsPlugins ?? []), ...design.jsPlugins],
  rules: { ...base.rules, ...design.rules },
});

把它合并起来,而不是通过它 extends: Oxlint 拒绝相对 jsPlugins 到达的配置路径 extends。 。 。 .

示例输出 :

src/App.tsx:5:46: error design(no-spectral-color): bg-red-500 — spectral color class; use bg-danger instead
src/App.tsx:8:21: error design(no-undefined-token): text-nonesuch generates no CSS — nonesuch is not defined; check the spelling, or add --color-nonesuch to your token stylesheet

规则

基础

在两个预设中启用 。 这些规则只要求符号样式表.

严格

仅启用于 strict,与所有基本规则。 这些检查取决于下列公约.

每个规则都有一条简短的指南 docs/rules:它报告什么,它允许什么,以及如何修复.

配置

覆盖规则选项或在您的 Oxlint 配置中启用附加规则 。 保留 ...design.rules 保留预设规则:

const design = await designLint({
  preset: "basic",
  tokenFiles: ["src/styles.css"],
});

export default defineConfig({
  ...design,
  rules: {
    ...design.rules,
    "design/no-dark-variant": ["error", { flagNonColorUtilities: false }],
  },
});

当您重述一条规则时, 您将替换预设给出的选项 。 如果您只想改变严重程度, 请保留所需的选项 。 这对 no-component-color-override,因为 componentSources 没有安全的默认.

综合报告

要看一个工程的设计系统 有多少没有限制,运行这个 从你运行的地方 oxlint数字 :

npx @evilmartians/design-lint report

design-lint report — oxlint.config.ts

Disabled rules (1 of 12)
  no-opacity-modifier  off

Silenced (49)
  no-raw-color             34
  no-dark-variant          12
  no-spectral-color        2
  (all rules, none named)  1

Ignored paths (2)
  src/legacy/**      ignorePatterns
  src/brand/art.tsx  no-raw-color

• 已禁用规则 规则设定为 off 或从配置中删除。 这包括使用时的严格规则 basic,以及 no-component-color-override 何时 componentSources: []。 。 。 .
• 安静 在文件"Oxlint lints"中,添加了可分行规则提及记录的批量压制计数,按规则细分. 每个 oxlint-disable-line, (中文(简体) ), oxlint-disable-next-line,或相当 eslint- 注释为每个命名的设计规则贡献一个. 一个不命名规则的评论 贡献了自己一行。 数头来自 oxlint-suppressions.json,从目录中读取 Oxlint 运行英寸 总数是压制使用的一个指标:一行评论可以隐藏多起违规或无违规,所记录的批量计数会变得呆滞.
• 已忽略路径 列出配置 ignorePatterns 包含块的文件 /* oxlint-disable */ 或者说 /* eslint-disable */ 评论。 注释条目显示命名的设计规则,或者在没有命名时显示"所有规则". 块禁用只能覆盖一个文件的一部分,例如,当后面有一个启用注释时;其条目并不意味着整个文件不受控制.

写着 oxlint.config.ts 奥克林特找到它的方式 过 --config <file> 和运行路径匹配 oxlint。 。 。 .

限制

这些规则是故意静止的。 他们不会运行您的应用程序, 也不会在文件之间跟踪值 .

已知限制 :

• CSS 文件尚未被内嵌 。 类别 @apply 而目前CSS申报的颜色已超出范围.
• 未检查动态组装的类 。 譬如说, `bg-${tone}` 过于含糊不清,无法证实.
• 大多数规则检查字符串的写出地,而不是一个值最终流动地.
• no-undefined-token 只检查明确的类列表位置, 如 className班上帮手的电话, cva() 财务报告和审定财务报表 tv()。 。 。 .

所需资源

• 节点22.18+或23.6+
• 氧化剂 1.82+
• 尾风 4.1.8+

软件包使用 @tailwindcss/node 以读取您 Tailwind 构建时所用的相同的设计系统。 它需要复制您的项目解析度, 因此在旧的 Tailwind 旁边安装一个更新的系统没有帮助: 升级项目的 Tailwind 。 如果您的工程已经通过 Vite, PostCSS 或 Tailwind CLI 使用 Tailwind, 通常已经安装了 。 否则,增加:

npm install --save-dev @tailwindcss/node

ESLint 语录

规则还可以在ESLint v9平面配置中运行. 将三件事添加到您已有的 eslint.config.mjs数字 :

// eslint.config.mjs
import { designLint } from "@evilmartians/design-lint/preset";

// 1. Resolve the design system.
const design = await designLint({
  tokenFiles: ["src/styles.css"],
  componentSources: ["@/components/ui/*"],
});

// 2. Then load the plugin.
const designPlugin = (await import("@evilmartians/design-lint/oxlint")).default;

export default [
  // ...your existing config

  // 3. Turn the rules on for your component files.
  {
    files: ["**/*.{js,jsx,ts,tsx}"],
    plugins: { design: designPlugin },
    rules: design.rules,
  },
];

使用动态 import() 用于插件。 这个 designLint() 调用规则所需的符号数据,插件在加载时读取.

规则使用您配置中已经为这些文件设置的解析器,所以它必须读取JSX,如果使用它,则必须读取TypeScript.

捐款

见 CONTRIBUTING.md。 。 。 .

许可证

麻省理工学院