eslint-plugin-ui-consistency

用于 shadcn/ui + Radix UI + Tailwind CSS 项目的 UI 一致性 ESLint 插件。

概述

此插件通过强制执行组件使用、样式模式和设计令牌遵循规则，帮助维护设计系统的一致性。专为使用 shadcn/ui、Radix UI 原语和 Tailwind CSS 的项目设计。

安装

npm install --save-dev eslint-plugin-ui-consistency

或使用 pnpm:

pnpm add -D eslint-plugin-ui-consistency

快速开始

使用预设配置

最简单的入门方式是使用预设配置之一：

推荐预设（平衡方案）：

// eslint.config.js
import { recommended } from "eslint-plugin-ui-consistency/presets";

export default [
  recommended,
  // ... 你的其他配置
];

严格预设（启用所有规则）：

// eslint.config.js
import { strict } from "eslint-plugin-ui-consistency/presets";

export default [
  strict,
  // ... 你的其他配置
];

手动配置

自定义规则配置：

// eslint.config.js
import { uiConsistencyPlugin } from "eslint-plugin-ui-consistency";

export default [
  {
    plugins: {
      "ui-consistency": uiConsistencyPlugin,
    },
    rules: {
      "ui-consistency/no-raw-interactive-elements": "error",
      "ui-consistency/no-raw-palette-utility": "error",
      // ... 根据需要配置其他规则
    },
  },
];

规则

此插件提供 11 条规则来强制执行 UI 一致性：

1. no-raw-interactive-elements

禁止使用原始 HTML 交互元素（button、input、textarea、select、a、label、form、fieldset），应使用 UI 库原语。

原因： 确保所有交互元素的样式、可访问性和行为一致。

// ❌ 错误
<button onClick={handleClick}>点击我</button>

// ✅ 正确
<Button onClick={handleClick}>点击我</Button>

2. no-primitive-classname

禁止在受管理的 UI 组件上覆盖 className，以维护设计系统完整性。

原因： 通过确保组件使用其内置样式模式来防止样式偏移。

3. no-shell-only-component-usage

限制仅在布局和模式中使用 shell 专用组件（如 SidebarFooter、SidebarGroup）。

原因： 防止在业务逻辑页面中误用布局特定组件。

4. no-raw-palette-utility

禁止使用原始 Tailwind 调色板工具类（如 bg-blue-500、text-red-600），应使用设计令牌。

原因： 强制使用语义化颜色并确保主题一致。

// ❌ 错误
<div className="bg-blue-500 text-white">内容</div>

// ✅ 正确
<div className="bg-primary text-primary-foreground">内容</div>

5. no-forbidden-ui-import-path

防止从绕过官方导出的旧版或内部 UI 路径导入。

原因： 确保稳定的导入并防止内部重构导致的破坏性更改。

6. no-button-icon-classname

禁止在 Button 组件内的图标上使用不必要的 className。

原因： Button 组件已通过 [&_svg] 样式处理图标大小和间距。

// ❌ 错误
<Button>
  <Icon className="h-4 w-4 mr-2" />
  点击我
</Button>

// ✅ 正确
<Button>
  <Icon />
  点击我
</Button>

7. no-arbitrary-utility

禁止使用绕过设计令牌的任意 Tailwind 工具类（如 bg-[#ff0000]、text-[14px]）。

原因： 维护设计系统一致性并防止一次性值。

// ❌ 错误
<div className="bg-[#3b82f6] text-[14px]">内容</div>

// ✅ 正确
<div className="bg-primary text-sm">内容</div>

8. no-hardcoded-z-index

禁止使用任意 z-index 值，应使用预定义层级。

原因： 防止 z-index 冲突并维护清晰的堆叠上下文层次结构。

// ❌ 错误
<div className="z-[9999]">模态框</div>

// ✅ 正确
<div className="z-50">模态框</div>

9. no-dark-mode-hardcode

禁止使用原始调色板工具类实现暗黑模式。

原因： 设计令牌通过 CSS 变量自动处理暗黑模式。

// ❌ 错误
<div className="bg-white dark:bg-gray-900">内容</div>

// ✅ 正确
<div className="bg-background">内容</div>

10. no-inconsistent-spacing

禁止使用绕过设计系统间距比例的任意间距值。

原因： 在整个应用程序中保持一致的间距。

// ❌ 错误
<div className="p-[13px] m-[7px]">内容</div>

// ✅ 正确
<div className="p-3 m-2">内容</div>

11. prefer-composition-import

强制从正确的路径导入组合组件。

原因： 在原语组件和组合组件之间保持清晰的分离。

// ❌ 错误
import { DataTable } from "@your-org/ui/components/data-table";

// ✅ 正确
import { DataTable } from "@your-org/ui/compositions/";

预设配置

Recommended（推荐）

适合大多数项目的平衡配置：

• ✅ no-raw-interactive-elements (error)
• ✅ no-raw-palette-utility (error)
• ⚠️ no-arbitrary-utility (warn)
• ✅ no-button-icon-classname (error)
• ⚠️ no-hardcoded-z-index (warn)

Strict（严格）

启用所有规则以实现最大一致性：

• 推荐配置中的所有规则
• ✅ no-primitive-classname (error)
• ✅ no-shell-only-component-usage (error)
• ✅ no-forbidden-ui-import-path (error)
• ✅ no-arbitrary-utility (error - 从 warn 升级)
• ✅ no-hardcoded-z-index (error - 从 warn 升级)
• ⚠️ no-dark-mode-hardcode (warn)
• ⚠️ no-inconsistent-spacing (warn)
• ✅ prefer-composition-import (error)

配置示例

渐进式采用

从警告开始，逐步提高严格程度：

import { uiConsistencyPlugin } from "eslint-plugin-ui-consistency";

export default [
  {
    plugins: {
      "ui-consistency": uiConsistencyPlugin,
    },
    rules: {
      "ui-consistency/no-raw-interactive-elements": "warn",
      "ui-consistency/no-raw-palette-utility": "warn",
      "ui-consistency/no-arbitrary-utility": "warn",
    },
  },
];

按目录配置

对新代码应用更严格的规则：

import { recommended, strict } from "eslint-plugin-ui-consistency/presets";

export default [
  recommended, // 所有文件的默认配置
  {
    files: ["src/features/new-dashboard/**/*.tsx"],
    ...strict, // 新功能使用更严格的规则
  },
];

贡献

欢迎贡献！请随时提交问题或拉取请求。

许可证

MIT

相关项目

• shadcn/ui - 使用 Radix UI 和 Tailwind CSS 构建的可重用组件
• Radix UI - 无样式、可访问的组件
• Tailwind CSS - 实用优先的 CSS 框架