{"_id":"@aicode-nexus/eslint-plugin-ui-consistency","name":"@aicode-nexus/eslint-plugin-ui-consistency","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@aicode-nexus/eslint-plugin-ui-consistency","version":"0.1.0","description":"ESLint plugin for enforcing UI consistency in shadcn/ui + Radix UI + Tailwind CSS projects","keywords":["eslint","eslint-plugin","shadcn-ui","radix-ui","tailwindcss","design-system","ui-consistency","design-tokens"],"author":{"name":"AICode-Nexus"},"license":"MIT","type":"module","main":"./eslint-plugin.mjs","exports":{".":{"import":"./eslint-plugin.mjs","types":"./eslint-plugin.mjs.d.ts"},"./presets":{"import":"./presets.mjs"}},"peerDependencies":{"eslint":">=9.0.0"},"repository":{"type":"git","url":"git+https://github.com/AICode-Nexus/ui-consistency.git"},"publishConfig":{"access":"public"},"_id":"@aicode-nexus/eslint-plugin-ui-consistency@0.1.0","gitHead":"3b003fd4bf81d8fbdc8ca2dfb840a1db8c8b800c","bugs":{"url":"https://github.com/AICode-Nexus/ui-consistency/issues"},"homepage":"https://github.com/AICode-Nexus/ui-consistency#readme","_nodeVersion":"22.22.2","_npmVersion":"10.9.7","dist":{"integrity":"sha512-zIiV3stXBU3UEk1f6O3fwXv8EC5//uvz1zXKY3pzxvohQGau77NA6h20DhIPUzGTs1J2rsv9+dzUwqM1B+66Ig==","shasum":"49260bf6f5f7d96386e908185dfbf02bc60300eb","tarball":"https://registry.npmjs.org/@aicode-nexus/eslint-plugin-ui-consistency/-/eslint-plugin-ui-consistency-0.1.0.tgz","fileCount":13,"unpackedSize":63716,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIEUFpwXNoftlz5dLhiWMHq/ZLi5UkyBpPK8I9D8gl7MfAiEAsiqvGNG3o86kQFkARku66pd/eyXXBw2xH32b5oLm04I="}]},"_npmUser":{"name":"trsoliu","email":"trsoliu@gmail.com"},"directories":{},"maintainers":[{"name":"trsoliu","email":"trsoliu@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/eslint-plugin-ui-consistency_0.1.0_1777545946745_0.8173210870490948"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-30T10:45:46.585Z","0.1.0":"2026-04-30T10:45:46.904Z","modified":"2026-04-30T10:45:47.233Z"},"maintainers":[{"name":"trsoliu","email":"trsoliu@gmail.com"}],"description":"ESLint plugin for enforcing UI consistency in shadcn/ui + Radix UI + Tailwind CSS projects","homepage":"https://github.com/AICode-Nexus/ui-consistency#readme","keywords":["eslint","eslint-plugin","shadcn-ui","radix-ui","tailwindcss","design-system","ui-consistency","design-tokens"],"repository":{"type":"git","url":"git+https://github.com/AICode-Nexus/ui-consistency.git"},"author":{"name":"AICode-Nexus"},"bugs":{"url":"https://github.com/AICode-Nexus/ui-consistency/issues"},"license":"MIT","readme":"# eslint-plugin-ui-consistency\n\n用于 shadcn/ui + Radix UI + Tailwind CSS 项目的 UI 一致性 ESLint 插件。\n\n## 概述\n\n此插件通过强制执行组件使用、样式模式和设计令牌遵循规则，帮助维护设计系统的一致性。专为使用 shadcn/ui、Radix UI 原语和 Tailwind CSS 的项目设计。\n\n## 安装\n\n```bash\nnpm install --save-dev eslint-plugin-ui-consistency\n```\n\n或使用 pnpm:\n\n```bash\npnpm add -D eslint-plugin-ui-consistency\n```\n\n## 快速开始\n\n### 使用预设配置\n\n最简单的入门方式是使用预设配置之一：\n\n**推荐预设**（平衡方案）：\n\n```javascript\n// eslint.config.js\nimport { recommended } from \"eslint-plugin-ui-consistency/presets\";\n\nexport default [\n  recommended,\n  // ... 你的其他配置\n];\n```\n\n**严格预设**（启用所有规则）：\n\n```javascript\n// eslint.config.js\nimport { strict } from \"eslint-plugin-ui-consistency/presets\";\n\nexport default [\n  strict,\n  // ... 你的其他配置\n];\n```\n\n### 手动配置\n\n自定义规则配置：\n\n```javascript\n// eslint.config.js\nimport { uiConsistencyPlugin } from \"eslint-plugin-ui-consistency\";\n\nexport default [\n  {\n    plugins: {\n      \"ui-consistency\": uiConsistencyPlugin,\n    },\n    rules: {\n      \"ui-consistency/no-raw-interactive-elements\": \"error\",\n      \"ui-consistency/no-raw-palette-utility\": \"error\",\n      // ... 根据需要配置其他规则\n    },\n  },\n];\n```\n\n## 规则\n\n此插件提供 11 条规则来强制执行 UI 一致性：\n\n### 1. `no-raw-interactive-elements`\n\n禁止使用原始 HTML 交互元素（`button`、`input`、`textarea`、`select`、`a`、`label`、`form`、`fieldset`），应使用 UI 库原语。\n\n**原因：** 确保所有交互元素的样式、可访问性和行为一致。\n\n```jsx\n// ❌ 错误\n<button onClick={handleClick}>点击我</button>\n\n// ✅ 正确\n<Button onClick={handleClick}>点击我</Button>\n```\n\n### 2. `no-primitive-classname`\n\n禁止在受管理的 UI 组件上覆盖 className，以维护设计系统完整性。\n\n**原因：** 通过确保组件使用其内置样式模式来防止样式偏移。\n\n### 3. `no-shell-only-component-usage`\n\n限制仅在布局和模式中使用 shell 专用组件（如 `SidebarFooter`、`SidebarGroup`）。\n\n**原因：** 防止在业务逻辑页面中误用布局特定组件。\n\n### 4. `no-raw-palette-utility`\n\n禁止使用原始 Tailwind 调色板工具类（如 `bg-blue-500`、`text-red-600`），应使用设计令牌。\n\n**原因：** 强制使用语义化颜色并确保主题一致。\n\n```jsx\n// ❌ 错误\n<div className=\"bg-blue-500 text-white\">内容</div>\n\n// ✅ 正确\n<div className=\"bg-primary text-primary-foreground\">内容</div>\n```\n\n### 5. `no-forbidden-ui-import-path`\n\n防止从绕过官方导出的旧版或内部 UI 路径导入。\n\n**原因：** 确保稳定的导入并防止内部重构导致的破坏性更改。\n\n### 6. `no-button-icon-classname`\n\n禁止在 Button 组件内的图标上使用不必要的 className。\n\n**原因：** Button 组件已通过 `[&_svg]` 样式处理图标大小和间距。\n\n```jsx\n// ❌ 错误\n<Button>\n  <Icon className=\"h-4 w-4 mr-2\" />\n  点击我\n</Button>\n\n// ✅ 正确\n<Button>\n  <Icon />\n  点击我\n</Button>\n```\n\n### 7. `no-arbitrary-utility`\n\n禁止使用绕过设计令牌的任意 Tailwind 工具类（如 `bg-[#ff0000]`、`text-[14px]`）。\n\n**原因：** 维护设计系统一致性并防止一次性值。\n\n```jsx\n// ❌ 错误\n<div className=\"bg-[#3b82f6] text-[14px]\">内容</div>\n\n// ✅ 正确\n<div className=\"bg-primary text-sm\">内容</div>\n```\n\n### 8. `no-hardcoded-z-index`\n\n禁止使用任意 z-index 值，应使用预定义层级。\n\n**原因：** 防止 z-index 冲突并维护清晰的堆叠上下文层次结构。\n\n```jsx\n// ❌ 错误\n<div className=\"z-[9999]\">模态框</div>\n\n// ✅ 正确\n<div className=\"z-50\">模态框</div>\n```\n\n### 9. `no-dark-mode-hardcode`\n\n禁止使用原始调色板工具类实现暗黑模式。\n\n**原因：** 设计令牌通过 CSS 变量自动处理暗黑模式。\n\n```jsx\n// ❌ 错误\n<div className=\"bg-white dark:bg-gray-900\">内容</div>\n\n// ✅ 正确\n<div className=\"bg-background\">内容</div>\n```\n\n### 10. `no-inconsistent-spacing`\n\n禁止使用绕过设计系统间距比例的任意间距值。\n\n**原因：** 在整个应用程序中保持一致的间距。\n\n```jsx\n// ❌ 错误\n<div className=\"p-[13px] m-[7px]\">内容</div>\n\n// ✅ 正确\n<div className=\"p-3 m-2\">内容</div>\n```\n\n### 11. `prefer-composition-import`\n\n强制从正确的路径导入组合组件。\n\n**原因：** 在原语组件和组合组件之间保持清晰的分离。\n\n```jsx\n// ❌ 错误\nimport { DataTable } from \"@your-org/ui/components/data-table\";\n\n// ✅ 正确\nimport { DataTable } from \"@your-org/ui/compositions/\";\n```\n\n## 预设配置\n\n### Recommended（推荐）\n\n适合大多数项目的平衡配置：\n\n- ✅ `no-raw-interactive-elements` (error)\n- ✅ `no-raw-palette-utility` (error)\n- ⚠️ `no-arbitrary-utility` (warn)\n- ✅ `no-button-icon-classname` (error)\n- ⚠️ `no-hardcoded-z-index` (warn)\n\n### Strict（严格）\n\n启用所有规则以实现最大一致性：\n\n- **推荐**配置中的所有规则\n- ✅ `no-primitive-classname` (error)\n- ✅ `no-shell-only-component-usage` (error)\n- ✅ `no-forbidden-ui-import-path` (error)\n- ✅ `no-arbitrary-utility` (error - 从 warn 升级)\n- ✅ `no-hardcoded-z-index` (error - 从 warn 升级)\n- ⚠️ `no-dark-mode-hardcode` (warn)\n- ⚠️ `no-inconsistent-spacing` (warn)\n- ✅ `prefer-composition-import` (error)\n\n## 配置示例\n\n### 渐进式采用\n\n从警告开始，逐步提高严格程度：\n\n```javascript\nimport { uiConsistencyPlugin } from \"eslint-plugin-ui-consistency\";\n\nexport default [\n  {\n    plugins: {\n      \"ui-consistency\": uiConsistencyPlugin,\n    },\n    rules: {\n      \"ui-consistency/no-raw-interactive-elements\": \"warn\",\n      \"ui-consistency/no-raw-palette-utility\": \"warn\",\n      \"ui-consistency/no-arbitrary-utility\": \"warn\",\n    },\n  },\n];\n```\n\n### 按目录配置\n\n对新代码应用更严格的规则：\n\n```javascript\nimport { recommended, strict } from \"eslint-plugin-ui-consistency/presets\";\n\nexport default [\n  recommended, // 所有文件的默认配置\n  {\n    files: [\"src/features/new-dashboard/**/*.tsx\"],\n    ...strict, // 新功能使用更严格的规则\n  },\n];\n```\n\n## 贡献\n\n欢迎贡献！请随时提交问题或拉取请求。\n\n## 许可证\n\nMIT\n\n## 相关项目\n\n- [shadcn/ui](https://ui.shadcn.com/) - 使用 Radix UI 和 Tailwind CSS 构建的可重用组件\n- [Radix UI](https://www.radix-ui.com/) - 无样式、可访问的组件\n- [Tailwind CSS](https://tailwindcss.com/) - 实用优先的 CSS 框架\n","readmeFilename":"README.zh-CN.md","_rev":"1-dda080c4aa7dc16f9c79f23a86edb578"}