🛡️ DesignGuard-CLI

零依赖终端 AI 设计质量检测引擎
Zero-dependency terminal AI design quality detection engine

简体中文 · 繁體中文 · English

🇨🇳 简体中文

📑 目录

项目介绍
核心特性
快速开始
详细使用指南
设计思路与迭代规划
打包与部署指南
贡献指南
开源协议

🎉 项目介绍

DesignGuard-CLI 是一款轻量级终端 AI 设计质量检测引擎，帮助开发者检测和修复 AI 生成代码中的设计反模式。

🎯 项目定位

随着 AI 编程助手（如 Cursor、GitHub Copilot、ChatGPT 等）的普及，越来越多的前端代码由 AI 生成。然而，这些代码往往存在大量千篇一律的设计反模式——从千篇一律的紫蓝渐变到千篇一律的三列特性卡片，AI 生成的界面缺乏设计个性和专业水准。

DesignGuard-CLI 正是为了解决这一问题而生。它是一个纯 Python 实现、零外部依赖的命令行工具，通过 55 条精心设计的检测规则，覆盖排版、色彩、布局、动效、可访问性和 AI 反模式六大分类，帮助你在代码审查阶段快速发现并修复这些设计问题。

💡 灵感来源

在日常使用 AI 编程工具的过程中，我们观察到 AI 生成的前端代码存在大量重复的设计反模式：同样的 Inter 字体、同样的紫蓝渐变、同样的圆角图标瓦片、同样的三列特性卡片……这些"AI 味"十足的设计让项目看起来千篇一律、缺乏个性。DesignGuard-CLI 旨在成为开发者的设计质量守门人，在代码合入之前就捕获这些问题。

🔥 核心价值

🚫 识别 AI 设计反模式：精准检测 55 种常见的 AI 生成代码设计问题
⚡ 零依赖离线运行：无需安装任何第三方库，无需 AI API 密钥，完全离线工作
🔧 多格式输出：支持终端彩色输出、JSON 结构化数据、HTML 可视化报告
🔄 CI/CD 集成：通过退出码控制，轻松集成到自动化工作流
🌐 多格式文件支持：HTML、CSS、JSX、TSX、Vue SFC 一网打尽

✨ 核心特性

特性	描述
🐍 零依赖纯 Python	仅使用 Python 标准库，无需安装任何第三方依赖
📏 55 条检测规则	覆盖排版、色彩、布局、动效、可访问性、AI 反模式 6 大分类
📂 多格式文件支持	支持 HTML、CSS、JSX、TSX、Vue SFC 等前端文件格式
🎨 三种输出格式	终端彩色输出 / JSON 结构化数据 / HTML 可视化报告
⚙️ 灵活的规则配置	支持规则白名单（`--only`）和黑名单（`--ignore`）
🔄 CI/CD 集成	通过退出码控制，支持静默模式和严重等级过滤
🔌 完全离线运行	无需 AI API 密钥，无需网络连接，即装即用
💻 跨平台兼容	完美运行于 Windows、macOS、Linux

🚀 快速开始

📋 环境要求

Python 3.8+（已测试 3.8 / 3.9 / 3.10 / 3.11 / 3.12）
无需任何第三方依赖

📦 安装

# 克隆仓库
git clone https://github.com/gitstq/DesignGuard-CLI.git
cd DesignGuard-CLI

# 安装（开发模式）
pip install -e .

# 或直接运行（无需安装）
python -m designguard_cli --version

🎮 使用示例

# 扫描单个文件
designguard scan index.html

# 扫描整个项目目录
designguard scan ./src --format json --output report.json

# 只运行排版类规则
designguard scan ./src --only typography

# 忽略特定规则
designguard scan ./src --ignore TYP001,CLR003

# 生成 HTML 可视化报告
designguard scan ./src --format html --output report.html

# CI/CD 模式（静默输出，仅显示错误级别）
designguard scan ./src --quiet --severity error

# 列出所有可用规则
designguard list

# 生成默认配置文件
designguard init

📖 详细使用指南

📝 CLI 命令详解

DesignGuard-CLI 提供三个核心命令：

命令	说明
`scan`	扫描文件或目录，执行设计质量检测
`list`	列出所有可用的检测规则及其详情
`init`	在当前目录生成默认配置文件 `.designguard.json`

🔧 scan 命令参数

参数	简写	默认值	说明
`--format`	`-f`	`terminal`	输出格式：`terminal` / `json` / `html`
`--output`	`-o`	-	输出文件路径（不指定则输出到终端）
`--ignore`	`-i`	-	忽略的规则 ID（逗号分隔）
`--only`	`-n`	-	仅运行指定规则（逗号分隔）
`--severity`	`-s`	-	最低严重等级：`error` / `warning` / `info`
`--no-color`	-	`false`	禁用彩色输出
`--config`	`-c`	-	指定配置文件路径
`--verbose`	`-v`	`false`	详细输出模式
`--quiet`	`-q`	`false`	静默模式（仅输出错误）

⚙️ 配置文件

运行 designguard init 可生成默认配置文件 .designguard.json：

{
  "ignore_rules": [],
  "only_rules": [],
  "min_severity": "info",
  "exclude_dirs": ["node_modules", ".git", "dist", "build", ".next", "__pycache__"],
  "exclude_files": [],
  "include_extensions": [".html", ".htm", ".css", ".jsx", ".tsx", ".vue"],
  "severity_overrides": {},
  "no_color": false
}

配置文件支持自动向上查找（最多 5 级目录），CLI 参数优先级高于配置文件。

📏 规则分类一览

DesignGuard-CLI 内置 55 条检测规则，分为 6 大分类：

🔤 排版规则（Typography）— 10 条

规则 ID	名称	描述	严重等级
TYP001	过度使用常见 AI 字体	检测 Inter/Arial/system-ui 等 AI 生成内容常见字体	⚠️ warning
TYP002	纯黑/纯灰文字颜色	检测使用纯黑(#000)或纯灰色文字，应使用 tinted neutrals	⚠️ warning
TYP003	行高不足	检测行高低于 1.4，影响可读性	❌ error
TYP004	字号过小	检测小于 12px 的字号，可能影响可读性	⚠️ warning
TYP005	缺少字体回退栈	检测 font-family 只指定单一字体，缺少回退字体	⚠️ warning
TYP006	标题层级跳跃	检测标题层级跳跃（如 h1 直接到 h3），破坏文档结构	❌ error
TYP007	过多不同字号	检测使用超过 6 种不同字号，设计不够统一	⚠️ warning
TYP008	letter-spacing 异常值	检测异常的 letter-spacing 值（过大或负值）	ℹ️ info
TYP009	font-weight 滥用	检测过多不同的 font-weight 值（超过 4 种）	ℹ️ info
TYP010	text-transform 全大写滥用	检测过度使用 text-transform:uppercase，降低可读性	ℹ️ info

🎨 色彩规则（Color）— 10 条

规则 ID	名称	描述	严重等级
CLR001	紫色到蓝色渐变	检测紫色到蓝色的渐变，AI 生成内容的典型配色	⚠️ warning
CLR002	灰色文字在彩色背景上	检测灰色文字(#666/#999)在彩色背景上使用，对比度不足	❌ error
CLR003	纯黑/纯白背景	检测使用纯黑(#000)或纯白(#fff/#FFF)背景	⚠️ warning
CLR004	过多颜色使用	检测使用超过 5 种主色，设计色彩不够统一	⚠️ warning
CLR005	缺少交互状态颜色	检测链接/按钮缺少 hover/focus 状态颜色定义	⚠️ warning
CLR006	硬编码颜色值	检测直接使用硬编码颜色值而非 CSS 变量	ℹ️ info
CLR007	低对比度文本	检测文本与背景对比度低于 WCAG 标准（4.5:1）	❌ error
CLR008	默认蓝色链接色未自定义	检测使用浏览器默认蓝色链接色而未自定义	ℹ️ info
CLR009	彩虹渐变滥用	检测使用彩虹色或多色渐变，通常是 AI 生成的标志	⚠️ warning
CLR010	相同颜色重复定义	检测同一颜色值被多次硬编码定义，应使用 CSS 变量	ℹ️ info

📐 布局规则（Layout）— 10 条

规则 ID	名称	描述	严重等级
LAY001	卡片嵌套卡片	检测卡片内嵌套卡片的布局模式，增加视觉复杂度	⚠️ warning
LAY002	固定像素宽度	检测使用固定像素宽度而非响应式单位	⚠️ warning
LAY003	过大 padding/margin	检测超过 100px 的 padding 或 margin 值	⚠️ warning
LAY004	text-align:center 滥用	检测过度使用 text-align:center 进行居中	ℹ️ info
LAY005	缺少 container/wrapper	检测缺少容器/包装器限制内容宽度	⚠️ warning
LAY006	绝对定位滥用	检测过多使用 position:absolute	⚠️ warning
LAY007	z-index 值过大	检测 z-index 值超过 999，可能导致层叠上下文问题	❌ error
LAY008	缺少 viewport meta 标签	检测 HTML 缺少 viewport meta 标签，影响移动端显示	❌ error
LAY009	display:inline-block 滥用	检测过度使用 display:inline-block 而非 flexbox/grid	ℹ️ info
LAY010	overflow:hidden 滥用	检测过多使用 overflow:hidden，可能隐藏内容	ℹ️ info

🎬 动效规则（Motion）— 7 条

规则 ID	名称	描述	严重等级
MOT001	bounce/elastic 缓动函数	检测使用 bounce/elastic 缓动函数，可能导致不自然的动画效果	⚠️ warning
MOT002	过长动画时间	检测动画时间超过 1 秒，影响用户体验	⚠️ warning
MOT003	缺少 prefers-reduced-motion	检测使用动画但缺少 prefers-reduced-motion 媒体查询	❌ error
MOT004	infinite 动画滥用	检测 animation-iteration-count: infinite 的滥用	⚠️ warning
MOT005	同时过多动画元素	检测同时有过多元素使用动画，影响性能	⚠️ warning
MOT006	transition 属性过多	检测单个元素上同时过渡过多属性	ℹ️ info
MOT007	动画使用 !important	检测动画属性使用 !important，可能导致难以覆盖	ℹ️ info

♿ 可访问性规则（Accessibility）— 8 条

规则 ID	名称	描述	严重等级
A11Y001	img 缺少 alt 属性	检测 img 标签缺少 alt 属性，影响屏幕阅读器访问	❌ error
A11Y002	缺少 lang 属性	检测 HTML 缺少 lang 属性，影响屏幕阅读器语言识别	❌ error
A11Y003	缺少 main/landmark 元素	检测缺少 main 或 landmark 元素，影响页面导航	⚠️ warning
A11Y004	按钮缺少 aria-label	检测按钮缺少文本内容或 aria-label 属性	⚠️ warning
A11Y005	颜色作为唯一区分手段	检测仅使用颜色区分信息（如"点击红色按钮"）	⚠️ warning
A11Y006	过小的触摸目标	检测触摸目标小于 44px，影响移动端操作	❌ error
A11Y007	空链接	检测没有文本内容和 aria-label 的空链接	❌ error
A11Y008	缺少标题结构	检测页面缺少 h1 标签	⚠️ warning

🤖 AI 反模式规则（AI Slop）— 10 条

规则 ID	名称	描述	严重等级
AIS001	圆角方形图标瓦片	检测标题上方的圆角方形图标瓦片，AI 生成内容的典型特征	⚠️ warning
AIS002	侧边标签边框	检测侧边标签的装饰性边框，AI 生成内容的常见模式	ℹ️ info
AIS003	暗色发光效果	检测暗色背景上的发光效果（box-shadow glow），AI 生成内容的标志	⚠️ warning
AIS004	过度使用渐变背景	检测过多使用渐变背景，AI 生成内容的典型特征	⚠️ warning
AIS005	千篇一律的三列特性卡片	检测千篇一律的三列特性卡片布局，AI 生成内容的典型模式	⚠️ warning
AIS006	过度使用 emoji 装饰	检测过度使用 emoji 作为装饰元素	ℹ️ info
AIS007	千篇一律的 hero section	检测千篇一律的 hero section 布局模式	⚠️ warning
AIS008	过度使用阴影堆叠	检测多层 box-shadow 堆叠，AI 生成内容的常见模式	⚠️ warning
AIS009	统一圆角滥用	检测所有元素使用相同的圆角值，缺乏设计变化	ℹ️ info
AIS010	装饰性分隔线	检测过多的装饰性分隔线或水平线元素	ℹ️ info

🎯 典型使用场景

场景一：CI/CD 集成

在持续集成流水线中自动检测设计质量问题，阻止低质量代码合入：

# GitHub Actions 示例
designguard scan ./src --quiet --severity error
# 退出码：0 = 通过，1 = 存在错误级别问题

场景二：代码审查辅助

在 Pull Request 审查过程中，快速扫描变更文件的设计质量：

designguard scan ./src/components --format json --output review-report.json

场景三：设计系统审计

对整个项目进行全面的设计质量审计，生成 HTML 可视化报告：

designguard scan ./src --format html --output audit-report.html

📸 运行效果

终端彩色输出效果：

$ designguard scan ./src

🛡️ DesignGuard-CLI v1.0.0 — 设计质量检测报告

📁 扫描路径: ./src
📄 扫描文件: 23 个
🔍 检测规则: 55 条

❌ 发现 12 个问题（3 错误 · 6 警告 · 3 提示）

  ❌ CLR002 [error]    灰色文字在彩色背景上
     📄 src/components/Card.tsx:42
     💡 使用更深或更浅的文字颜色以确保对比度

  ⚠️ TYP001 [warning]  过度使用常见AI字体
     📄 src/styles/global.css:15
     💡 考虑使用更具特色的字体组合

  ⚠️ AIS005 [warning]  千篇一律的三列特性卡片
     📄 src/pages/Home.vue:88
     💡 尝试不同的布局方式，如不对称网格或交错布局

✅ 扫描完成！耗时 0.12s

💡 设计思路与迭代规划

🧠 设计理念

为什么需要 AI 设计质量检测？

AI 编程助手正在改变软件开发的方式，但它们生成的前端代码往往存在一个被忽视的问题——设计同质化。当大量项目使用 AI 生成界面时，它们开始看起来越来越相似：同样的字体选择、同样的配色方案、同样的布局模式。DesignGuard-CLI 的核心理念是：AI 可以辅助编码，但设计质量仍需人工把关。

我们不反对使用 AI 编程工具，而是希望帮助开发者在使用 AI 的同时，保持项目的设计个性和专业水准。

🔧 技术选型原因

为什么选择 Python 零依赖？

通用性：Python 是开发者最常用的语言之一，几乎所有开发环境都已预装
零摩擦：无需 npm install、无需 pip install 第三方包，克隆即可运行
离线友好：无需网络连接，无需 AI API 密钥，适合内网开发环境
轻量高效：纯标准库实现，启动速度快，内存占用低
易于集成：可轻松嵌入到任何 Python 项目或 CI/CD 流水线中

🗺️ 迭代规划

版本	计划功能	状态
v1.1	自定义规则插件系统，支持用户编写自己的检测规则	📋 规划中
v1.2	VS Code 扩展，实时编辑器内检测	📋 规划中
v1.3	Webpack/Vite 插件集成，构建时自动检测	📋 规划中
v2.0	Web UI 管理面板，可视化规则配置和历史趋势分析	📋 规划中

🤝 社区贡献方向

我们欢迎以下方向的贡献：

🆕 新检测规则：发现新的 AI 设计反模式？欢迎提交规则 PR
🌍 多语言支持：帮助完善规则描述的多语言翻译
📚 文档改进：补充使用案例、最佳实践文档
🐛 Bug 修复：发现误报或漏报？欢迎提交 Issue
🧪 测试覆盖：帮助增加测试用例，提高检测准确性

📦 打包与部署指南

📥 pip 安装

# 从 PyPI 安装（即将发布）
pip install designguard-cli

# 从源码安装
pip install git+https://github.com/gitstq/DesignGuard-CLI.git

🔨 从源码安装

git clone https://github.com/gitstq/DesignGuard-CLI.git
cd DesignGuard-CLI
pip install -e .

🐳 Docker 部署

FROM python:3.11-slim

WORKDIR /app
COPY . .

RUN pip install -e .

ENTRYPOINT ["designguard"]

# 构建镜像
docker build -t designguard-cli .

# 运行扫描
docker run --rm -v $(pwd)/src:/src designguard-cli scan /src

🔄 CI/CD 集成示例（GitHub Actions）

name: Design Quality Check

on: [pull_request]

jobs:
  designguard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install DesignGuard-CLI
        run: pip install -e .

      - name: Run design quality check
        run: designguard scan ./src --quiet --severity error

🤝 贡献指南

我们非常欢迎社区贡献！以下是贡献流程：

📋 提交 PR 规范

本项目遵循 Angular Commit Convention：

<type>(<scope>): <subject>

<body>

type 类型：

类型	说明
`feat`	新功能
`fix`	Bug 修复
`docs`	文档更新
`style`	代码格式调整（不影响逻辑）
`refactor`	代码重构
`test`	测试相关
`chore`	构建/工具链相关

示例：

feat(rules): 新增检测规则 - 圆角方形图标瓦片

- 新增 AIS001 规则用于检测标题上方的圆角方形图标瓦片
- 支持多种图标容器 class 模式匹配
- 添加对应的单元测试用例

🐛 Issue 反馈规则

提交 Issue 时，请包含以下信息：

问题描述：清晰描述遇到的问题或建议
复现步骤：提供最小可复现示例
期望行为：描述你期望的正确行为
实际行为：描述实际观察到的行为
环境信息：Python 版本、操作系统、DesignGuard-CLI 版本

🛠️ 开发环境搭建

# 克隆仓库
git clone https://github.com/gitstq/DesignGuard-CLI.git
cd DesignGuard-CLI

# 安装（开发模式）
pip install -e .

# 运行测试
python -m pytest tests/

# 验证安装
designguard --version

📏 代码规范要求

遵循 PEP 8 代码风格
所有公共函数和类必须包含中英双语文档字符串
新增规则必须包含对应的单元测试
规则 ID 命名规范：分类前缀 + 三位数字（如 TYP001、CLR003）
提交前确保所有测试通过：python -m pytest tests/

📄 开源协议

本项目基于 MIT 协议开源。

MIT 协议是一款简洁且宽松的开源协议，允许你自由使用、复制、修改、合并、发布、分发、再授权和/或销售本软件，唯一的要求是在所有副本或重要部分中包含版权声明和许可声明。

简而言之：你可以用这个软件做任何事情，但请保留原作者的版权信息。

详见 LICENSE 文件。

_{Built with ❤️ by DesignGuard Team}

🇹🇼 繁體中文

🎉 專案介紹

DesignGuard-CLI 是一款輕量級終端 AI 設計品質檢測引擎，幫助開發者檢測和修復 AI 生成程式碼中的設計反模式。

🎯 專案定位

隨著 AI 程式設計助手（如 Cursor、GitHub Copilot、ChatGPT 等）的普及，越來越多的前端程式碼由 AI 生成。然而，這些程式碼往往存在大量千篇一律的設計反模式——從千篇一律的紫藍漸層到千篇一律的三列特性卡片，AI 生成的介面缺乏設計個性和專業水準。

DesignGuard-CLI 正是為了解決這一問題而生。它是一個純 Python 實作、零外部依賴的命令列工具，透過 55 條精心設計的檢測規則，涵蓋排版、色彩、佈局、動效、可訪問性和 AI 反模式六大分類，幫助你在程式碼審查階段快速發現並修復這些設計問題。

💡 靈感來源

在日常使用 AI 程式設計工具的過程中，我們觀察到 AI 生成的前端程式碼存在大量重複的設計反模式：同樣的 Inter 字型、同樣的紫藍漸層、同樣的圓角圖示瓦片、同樣的三列特性卡片……這些「AI 味」十足的設計讓專案看起來千篇一律、缺乏個性。DesignGuard-CLI 旨在成為開發者的設計品質守門人，在程式碼合入之前就捕獲這些問題。

🔥 核心價值

🚫 識別 AI 設計反模式：精準檢測 55 種常見的 AI 生成程式碼設計問題
⚡ 零依賴離線運行：無需安裝任何第三方函式庫，無需 AI API 金鑰，完全離線工作
🔧 多格式輸出：支援終端彩色輸出、JSON 結構化資料、HTML 視覺化報告
🔄 CI/CD 整合：透過退出碼控制，輕鬆整合到自動化工作流
🌐 多格式檔案支援：HTML、CSS、JSX、TSX、Vue SFC 一網打盡

✨ 核心特性

特性	描述
🐍 零依賴純 Python	僅使用 Python 標準函式庫，無需安裝任何第三方依賴
📏 55 條檢測規則	涵蓋排版、色彩、佈局、動效、可訪問性、AI 反模式 6 大分類
📂 多格式檔案支援	支援 HTML、CSS、JSX、TSX、Vue SFC 等前端檔案格式
🎨 三種輸出格式	終端彩色輸出 / JSON 結構化資料 / HTML 視覺化報告
⚙️ 靈活的規則配置	支援規則白名單（`--only`）和黑名單（`--ignore`）
🔄 CI/CD 整合	透過退出碼控制，支援靜音模式和嚴重等級過濾
🔌 完全離線運行	無需 AI API 金鑰，無需網路連接，即裝即用
💻 跨平台相容	完美運行於 Windows、macOS、Linux

🚀 快速開始

📋 環境要求

Python 3.8+（已測試 3.8 / 3.9 / 3.10 / 3.11 / 3.12）
無需任何第三方依賴

📦 安裝

# 克隆倉庫
git clone https://github.com/gitstq/DesignGuard-CLI.git
cd DesignGuard-CLI

# 安裝（開發模式）
pip install -e .

# 或直接運行（無需安裝）
python -m designguard_cli --version

🎮 使用範例

# 掃描單一檔案
designguard scan index.html

# 掃描整個專案目錄
designguard scan ./src --format json --output report.json

# 只運行排版類規則
designguard scan ./src --only typography

# 忽略特定規則
designguard scan ./src --ignore TYP001,CLR003

# 生成 HTML 視覺化報告
designguard scan ./src --format html --output report.html

# CI/CD 模式（靜音輸出，僅顯示錯誤級別）
designguard scan ./src --quiet --severity error

# 列出所有可用規則
designguard list

# 生成預設配置檔案
designguard init

📖 詳細使用指南

📝 CLI 命令詳解

DesignGuard-CLI 提供三個核心命令：

命令	說明
`scan`	掃描檔案或目錄，執行設計品質檢測
`list`	列出所有可用的檢測規則及其詳情
`init`	在目前目錄生成預設配置檔案 `.designguard.json`

🔧 scan 命令參數

參數	簡寫	預設值	說明
`--format`	`-f`	`terminal`	輸出格式：`terminal` / `json` / `html`
`--output`	`-o`	-	輸出檔案路徑（不指定則輸出到終端）
`--ignore`	`-i`	-	忽略的規則 ID（逗號分隔）
`--only`	`-n`	-	僅運行指定規則（逗號分隔）
`--severity`	`-s`	-	最低嚴重等級：`error` / `warning` / `info`
`--no-color`	-	`false`	停用彩色輸出
`--config`	`-c`	-	指定配置檔案路徑
`--verbose`	`-v`	`false`	詳細輸出模式
`--quiet`	`-q`	`false`	靜音模式（僅輸出錯誤）

⚙️ 配置檔案

運行 designguard init 可生成預設配置檔案 .designguard.json：

{
  "ignore_rules": [],
  "only_rules": [],
  "min_severity": "info",
  "exclude_dirs": ["node_modules", ".git", "dist", "build", ".next", "__pycache__"],
  "exclude_files": [],
  "include_extensions": [".html", ".htm", ".css", ".jsx", ".tsx", ".vue"],
  "severity_overrides": {},
  "no_color": false
}

配置檔案支援自動向上查找（最多 5 級目錄），CLI 參數優先級高於配置檔案。

📏 規則分類一覽

DesignGuard-CLI 內建 55 條檢測規則，分為 6 大分類：

🔤 排版規則（Typography）— 10 條

規則 ID	名稱	描述	嚴重等級
TYP001	過度使用常見 AI 字型	檢測 Inter/Arial/system-ui 等 AI 生成內容常見字型	⚠️ warning
TYP002	純黑/純灰文字顏色	檢測使用純黑(#000)或純灰色文字，應使用 tinted neutrals	⚠️ warning
TYP003	行高不足	檢測行高低於 1.4，影響可讀性	❌ error
TYP004	字號過小	檢測小於 12px 的字號，可能影響可讀性	⚠️ warning
TYP005	缺少字型回退棧	檢測 font-family 只指定單一字型，缺少回退字型	⚠️ warning
TYP006	標題層級跳躍	檢測標題層級跳躍（如 h1 直接到 h3），破壞文件結構	❌ error
TYP007	過多不同字號	檢測使用超過 6 種不同字號，設計不夠統一	⚠️ warning
TYP008	letter-spacing 異常值	檢測異常的 letter-spacing 值（過大或負值）	ℹ️ info
TYP009	font-weight 濫用	檢測過多不同的 font-weight 值（超過 4 種）	ℹ️ info
TYP010	text-transform 全大寫濫用	檢測過度使用 text-transform:uppercase，降低可讀性	ℹ️ info

🎨 色彩規則（Color）— 10 條

規則 ID	名稱	描述	嚴重等級
CLR001	紫色到藍色漸層	檢測紫色到藍色的漸層，AI 生成內容的典型配色	⚠️ warning
CLR002	灰色文字在彩色背景上	檢測灰色文字(#666/#999)在彩色背景上使用，對比度不足	❌ error
CLR003	純黑/純白背景	檢測使用純黑(#000)或純白(#fff/#FFF)背景	⚠️ warning
CLR004	過多顏色使用	檢測使用超過 5 種主色，設計色彩不夠統一	⚠️ warning
CLR005	缺少互動狀態顏色	檢測連結/按鈕缺少 hover/focus 狀態顏色定義	⚠️ warning
CLR006	硬編碼顏色值	檢測直接使用硬編碼顏色值而非 CSS 變數	ℹ️ info
CLR007	低對比度文字	檢測文字與背景對比度低於 WCAG 標準（4.5:1）	❌ error
CLR008	預設藍色連結色未自訂	檢測使用瀏覽器預設藍色連結色而未自訂	ℹ️ info
CLR009	彩虹漸層濫用	檢測使用彩虹色或多色漸層，通常是 AI 生成的標誌	⚠️ warning
CLR010	相同顏色重複定義	檢測同一顏色值被多次硬編碼定義，應使用 CSS 變數	ℹ️ info

📐 佈局規則（Layout）— 10 條

規則 ID	名稱	描述	嚴重等級
LAY001	卡片巢狀卡片	檢測卡片內巢狀卡片的佈局模式，增加視覺複雜度	⚠️ warning
LAY002	固定像素寬度	檢測使用固定像素寬度而非響應式單位	⚠️ warning
LAY003	過大 padding/margin	檢測超過 100px 的 padding 或 margin 值	⚠️ warning
LAY004	text-align:center 濫用	檢測過度使用 text-align:center 進行置中	ℹ️ info
LAY005	缺少 container/wrapper	檢測缺少容器/包裝器限制內容寬度	⚠️ warning
LAY006	絕對定位濫用	檢測過多使用 position:absolute	⚠️ warning
LAY007	z-index 值過大	檢測 z-index 值超過 999，可能導致層疊上下文問題	❌ error
LAY008	缺少 viewport meta 標籤	檢測 HTML 缺少 viewport meta 標籤，影響行動端顯示	❌ error
LAY009	display:inline-block 濫用	檢測過度使用 display:inline-block 而非 flexbox/grid	ℹ️ info
LAY010	overflow:hidden 濫用	檢測過多使用 overflow:hidden，可能隱藏內容	ℹ️ info

🎬 動效規則（Motion）— 7 條

規則 ID	名稱	描述	嚴重等級
MOT001	bounce/elastic 緩動函數	檢測使用 bounce/elastic 緩動函數，可能導致不自然的動畫效果	⚠️ warning
MOT002	過長動畫時間	檢測動畫時間超過 1 秒，影響使用者體驗	⚠️ warning
MOT003	缺少 prefers-reduced-motion	檢測使用動畫但缺少 prefers-reduced-motion 媒體查詢	❌ error
MOT004	infinite 動畫濫用	檢測 animation-iteration-count: infinite 的濫用	⚠️ warning
MOT005	同時過多動畫元素	檢測同時有過多元素使用動畫，影響效能	⚠️ warning
MOT006	transition 屬性過多	檢測單一元素上同時過渡過多屬性	ℹ️ info
MOT007	動畫使用 !important	檢測動畫屬性使用 !important，可能導致難以覆蓋	ℹ️ info

♿ 可訪問性規則（Accessibility）— 8 條

規則 ID	名稱	描述	嚴重等級
A11Y001	img 缺少 alt 屬性	檢測 img 標籤缺少 alt 屬性，影響螢幕閱讀器訪問	❌ error
A11Y002	缺少 lang 屬性	檢測 HTML 缺少 lang 屬性，影響螢幕閱讀器語言識別	❌ error
A11Y003	缺少 main/landmark 元素	檢測缺少 main 或 landmark 元素，影響頁面導航	⚠️ warning
A11Y004	按鈕缺少 aria-label	檢測按鈕缺少文字內容或 aria-label 屬性	⚠️ warning
A11Y005	顏色作為唯一區分手段	檢測僅使用顏色區分資訊（如「點擊紅色按鈕」）	⚠️ warning
A11Y006	過小的觸控目標	檢測觸控目標小於 44px，影響行動端操作	❌ error
A11Y007	空連結	檢測沒有文字內容和 aria-label 的空連結	❌ error
A11Y008	缺少標題結構	檢測頁面缺少 h1 標籤	⚠️ warning

🤖 AI 反模式規則（AI Slop）— 10 條

規則 ID	名稱	描述	嚴重等級
AIS001	圓角方形圖示瓦片	檢測標題上方的圓角方形圖示瓦片，AI 生成內容的典型特徵	⚠️ warning
AIS002	側邊標籤邊框	檢測側邊標籤的裝飾性邊框，AI 生成內容的常見模式	ℹ️ info
AIS003	暗色發光效果	檢測暗色背景上的發光效果（box-shadow glow），AI 生成內容的標誌	⚠️ warning
AIS004	過度使用漸層背景	檢測過多使用漸層背景，AI 生成內容的典型特徵	⚠️ warning
AIS005	千篇一律的三列特性卡片	檢測千篇一律的三列特性卡片佈局，AI 生成內容的典型模式	⚠️ warning
AIS006	過度使用 emoji 裝飾	檢測過度使用 emoji 作為裝飾元素	ℹ️ info
AIS007	千篇一律的 hero section	檢測千篇一律的 hero section 佈局模式	⚠️ warning
AIS008	過度使用陰影堆疊	檢測多層 box-shadow 堆疊，AI 生成內容的常見模式	⚠️ warning
AIS009	統一圓角濫用	檢測所有元素使用相同的圓角值，缺乏設計變化	ℹ️ info
AIS010	裝飾性分隔線	檢測過多的裝飾性分隔線或水平線元素	ℹ️ info

🎯 典型使用場景

場景一：CI/CD 整合

在持續整合流水線中自動檢測設計品質問題，阻止低品質程式碼合入：

# GitHub Actions 範例
designguard scan ./src --quiet --severity error
# 退出碼：0 = 通過，1 = 存在錯誤級別問題

場景二：程式碼審查輔助

在 Pull Request 審查過程中，快速掃描變更檔案的設計品質：

designguard scan ./src/components --format json --output review-report.json

場景三：設計系統審計

對整個專案進行全面的設計品質審計，生成 HTML 視覺化報告：

designguard scan ./src --format html --output audit-report.html

📸 運行效果

終端彩色輸出效果：

$ designguard scan ./src

🛡️ DesignGuard-CLI v1.0.0 — 設計品質檢測報告

📁 掃描路徑: ./src
📄 掃描檔案: 23 個
🔍 檢測規則: 55 條

❌ 發現 12 個問題（3 錯誤 · 6 警告 · 3 提示）

  ❌ CLR002 [error]    灰色文字在彩色背景上
     📄 src/components/Card.tsx:42
     💡 使用更深或更淺的文字顏色以確保對比度

  ⚠️ TYP001 [warning]  過度使用常見AI字型
     📄 src/styles/global.css:15
     💡 考慮使用更具特色的字型組合

  ⚠️ AIS005 [warning]  千篇一律的三列特性卡片
     📄 src/pages/Home.vue:88
     💡 嘗試不同的佈局方式，如不對稱網格或交錯佈局

✅ 掃描完成！耗時 0.12s

💡 設計思路與迭代規劃

🧠 設計理念

為什麼需要 AI 設計品質檢測？

AI 程式設計助手正在改變軟體開發的方式，但它們生成的前端程式碼往往存在一個被忽視的問題——設計同質化。當大量專案使用 AI 生成介面時，它們開始看起來越來越相似：同樣的字型選擇、同樣的配色方案、同樣的佈局模式。DesignGuard-CLI 的核心理念是：AI 可以輔助編碼，但設計品質仍需人工把關。

我們不反對使用 AI 程式設計工具，而是希望幫助開發者在使用 AI 的同時，保持專案的設計個性和專業水準。

🔧 技術選型原因

為什麼選擇 Python 零依賴？

通用性：Python 是開發者最常用的語言之一，幾乎所有開發環境都已預裝
零摩擦：無需 npm install、無需 pip install 第三方套件，克隆即可運行
離線友善：無需網路連接，無需 AI API 金鑰，適合內網開發環境
輕量高效：純標準函式庫實作，啟動速度快，記憶體佔用低
易於整合：可輕鬆嵌入到任何 Python 專案或 CI/CD 流水線中

🗺️ 迭代規劃

版本	計畫功能	狀態
v1.1	自訂規則外掛系統，支援使用者撰寫自己的檢測規則	📋 規劃中
v1.2	VS Code 擴充功能，即時編輯器內檢測	📋 規劃中
v1.3	Webpack/Vite 外掛整合，建構時自動檢測	📋 規劃中
v2.0	Web UI 管理面板，視覺化規則配置和歷史趨勢分析	📋 規劃中

🤝 社群貢獻方向

我們歡迎以下方向的貢獻：

🆕 新檢測規則：發現新的 AI 設計反模式？歡迎提交規則 PR
🌍 多語言支援：幫助完善規則描述的多語言翻譯
📚 文件改進：補充使用案例、最佳實踐文件
🐛 Bug 修復：發現誤報或漏報？歡迎提交 Issue
🧪 測試覆蓋：幫助增加測試案例，提高檢測準確性

📦 打包與部署指南

📥 pip 安裝

# 從 PyPI 安裝（即將發布）
pip install designguard-cli

# 從原始碼安裝
pip install git+https://github.com/gitstq/DesignGuard-CLI.git

🔨 從原始碼安裝

git clone https://github.com/gitstq/DesignGuard-CLI.git
cd DesignGuard-CLI
pip install -e .

🐳 Docker 部署

FROM python:3.11-slim

WORKDIR /app
COPY . .

RUN pip install -e .

ENTRYPOINT ["designguard"]

# 建置映像檔
docker build -t designguard-cli .

# 運行掃描
docker run --rm -v $(pwd)/src:/src designguard-cli scan /src

🔄 CI/CD 整合範例（GitHub Actions）

name: Design Quality Check

on: [pull_request]

jobs:
  designguard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install DesignGuard-CLI
        run: pip install -e .

      - name: Run design quality check
        run: designguard scan ./src --quiet --severity error

🤝 貢獻指南

我們非常歡迎社群貢獻！以下是貢獻流程：

📋 提交 PR 規範

本專案遵循 Angular Commit Convention：

<type>(<scope>): <subject>

<body>

type 類型：

類型	說明
`feat`	新功能
`fix`	Bug 修復
`docs`	文件更新
`style`	程式碼格式調整（不影響邏輯）
`refactor`	程式碼重構
`test`	測試相關
`chore`	建置/工具鏈相關

範例：

feat(rules): 新增檢測規則 - 圓角方形圖示瓦片

- 新增 AIS001 規則用於檢測標題上方的圓角方形圖示瓦片
- 支援多種圖示容器 class 模式匹配
- 新增對應的單元測試案例

🐛 Issue 回饋規則

提交 Issue 時，請包含以下資訊：

問題描述：清晰描述遇到的問題或建議
重現步驟：提供最小可重現範例
期望行為：描述你期望的正確行為
實際行為：描述實際觀察到的行為
環境資訊：Python 版本、作業系統、DesignGuard-CLI 版本

🛠️ 開發環境搭建

# 克隆倉庫
git clone https://github.com/gitstq/DesignGuard-CLI.git
cd DesignGuard-CLI

# 安裝（開發模式）
pip install -e .

# 運行測試
python -m pytest tests/

# 驗證安裝
designguard --version

📏 程式碼規範要求

遵循 PEP 8 程式碼風格
所有公共函數和類別必須包含中英雙語文件字串
新增規則必須包含對應的單元測試
規則 ID 命名規範：分類前綴 + 三位數字（如 TYP001、CLR003）
提交前確保所有測試通過：python -m pytest tests/

📄 開源協議

本專案基於 MIT 協議開源。

MIT 協議是一款簡潔且寬鬆的開源協議，允許你自由使用、複製、修改、合併、發布、分發、再授權和/或銷售本軟體，唯一的要求是在所有副本或重要部分中包含版權聲明和許可聲明。

簡而言之：你可以用這個軟體做任何事情，但請保留原作者的版權資訊。

詳見 LICENSE 檔案。

_{Built with ❤️ by DesignGuard Team}

🇺🇸 English

📑 Table of Contents

Project Introduction
Core Features
Quick Start
Detailed Usage Guide
Design Philosophy & Roadmap
Packaging & Deployment Guide
Contributing Guide
License

🎉 Project Introduction

DesignGuard-CLI is a lightweight terminal-based AI design quality detection engine that helps developers detect and fix design anti-patterns in AI-generated code.

🎯 Project Positioning

With the growing adoption of AI coding assistants (such as Cursor, GitHub Copilot, ChatGPT, etc.), an increasing amount of frontend code is being generated by AI. However, this code often suffers from cookie-cutter design anti-patterns -- from the ubiquitous purple-blue gradients to the generic three-column feature cards, AI-generated interfaces lack design personality and professional polish.

DesignGuard-CLI was built to address this very problem. It is a pure Python, zero external dependency command-line tool that leverages 55 carefully crafted detection rules across six categories -- typography, color, layout, motion, accessibility, and AI anti-patterns -- to help you quickly identify and fix these design issues during code review.

💡 Inspiration

While using AI coding tools in our daily workflow, we noticed that AI-generated frontend code exhibits numerous repetitive design anti-patterns: the same Inter font, the same purple-blue gradients, the same rounded icon tiles, the same three-column feature cards... These distinctly "AI-flavored" designs make projects look generic and devoid of character. DesignGuard-CLI aims to serve as a design quality gatekeeper for developers, catching these issues before code gets merged.

🔥 Core Value

🚫 Identify AI Design Anti-patterns: Accurately detect 55 common design issues in AI-generated code
⚡ Zero-Dependency Offline Operation: No third-party libraries, no AI API keys, fully offline
🔧 Multi-Format Output: Terminal color output / JSON structured data / HTML visual reports
🔄 CI/CD Integration: Exit code control for seamless integration into automation workflows
🌐 Multi-Format File Support: Covers HTML, CSS, JSX, TSX, and Vue SFC

✨ Core Features

Feature	Description
🐍 Zero-Dependency Pure Python	Uses only Python standard library, no third-party dependencies required
📏 55 Detection Rules	Covers typography, color, layout, motion, accessibility, and AI anti-patterns across 6 categories
📂 Multi-Format File Support	Supports HTML, CSS, JSX, TSX, Vue SFC and other frontend file formats
🎨 Three Output Formats	Terminal color output / JSON structured data / HTML visual reports
⚙️ Flexible Rule Configuration	Supports rule whitelist (`--only`) and blacklist (`--ignore`)
🔄 CI/CD Integration	Exit code control with quiet mode and severity level filtering
🔌 Fully Offline Operation	No AI API keys, no network connection required, install and run
💻 Cross-Platform Compatible	Works seamlessly on Windows, macOS, and Linux

🚀 Quick Start

📋 Requirements

Python 3.8+ (tested on 3.8 / 3.9 / 3.10 / 3.11 / 3.12)
No third-party dependencies required

📦 Installation

# Clone the repository
git clone https://github.com/gitstq/DesignGuard-CLI.git
cd DesignGuard-CLI

# Install (development mode)
pip install -e .

# Or run directly (no installation needed)
python -m designguard_cli --version

🎮 Usage Examples

# Scan a single file
designguard scan index.html

# Scan an entire project directory
designguard scan ./src --format json --output report.json

# Run only typography rules
designguard scan ./src --only typography

# Ignore specific rules
designguard scan ./src --ignore TYP001,CLR003

# Generate an HTML visual report
designguard scan ./src --format html --output report.html

# CI/CD mode (silent output, errors only)
designguard scan ./src --quiet --severity error

# List all available rules
designguard list

# Generate default configuration file
designguard init

📖 Detailed Usage Guide

📝 CLI Commands

DesignGuard-CLI provides three core commands:

Command	Description
`scan`	Scan files or directories for design quality issues
`list`	List all available detection rules with details
`init`	Generate a default configuration file `.designguard.json` in the current directory

🔧 scan Command Parameters

Parameter	Short	Default	Description
`--format`	`-f`	`terminal`	Output format: `terminal` / `json` / `html`
`--output`	`-o`	-	Output file path (prints to terminal if not specified)
`--ignore`	`-i`	-	Rule IDs to ignore (comma-separated)
`--only`	`-n`	-	Only run specified rules (comma-separated)
`--severity`	`-s`	-	Minimum severity level: `error` / `warning` / `info`
`--no-color`	-	`false`	Disable color output
`--config`	`-c`	-	Specify configuration file path
`--verbose`	`-v`	`false`	Verbose output mode
`--quiet`	`-q`	`false`	Quiet mode (errors only)

⚙️ Configuration File

Run designguard init to generate a default configuration file .designguard.json:

{
  "ignore_rules": [],
  "only_rules": [],
  "min_severity": "info",
  "exclude_dirs": ["node_modules", ".git", "dist", "build", ".next", "__pycache__"],
  "exclude_files": [],
  "include_extensions": [".html", ".htm", ".css", ".jsx", ".tsx", ".vue"],
  "severity_overrides": {},
  "no_color": false
}

The configuration file supports automatic upward lookup (up to 5 directory levels). CLI parameters take precedence over configuration file settings.

📏 Rule Categories

DesignGuard-CLI includes 55 detection rules organized into 6 categories:

🔤 Typography Rules — 10 Rules

Rule ID	Name	Description	Severity
TYP001	Overused AI Fonts	Detects overuse of Inter/Arial/system-ui fonts common in AI-generated content	⚠️ warning
TYP002	Pure Black/Gray Text	Detects pure black (#000) or pure gray text, should use tinted neutrals	⚠️ warning
TYP003	Insufficient Line Height	Detects line-height below 1.4 which affects readability	❌ error
TYP004	Font Size Too Small	Detects font sizes smaller than 12px which may affect readability	⚠️ warning
TYP005	Missing Font Fallback Stack	Detects font-family with only a single font, missing fallback fonts	⚠️ warning
TYP006	Heading Level Skipping	Detects heading level skipping (e.g., h1 directly to h3), breaking document structure	❌ error
TYP007	Too Many Font Sizes	Detects more than 6 different font sizes, indicating inconsistent design	⚠️ warning
TYP008	Abnormal Letter Spacing	Detects abnormal letter-spacing values (too large or negative)	ℹ️ info
TYP009	Font Weight Abuse	Detects too many different font-weight values (more than 4)	ℹ️ info
TYP010	Uppercase Text Transform Abuse	Detects excessive use of text-transform:uppercase, reducing readability	ℹ️ info

🎨 Color Rules — 10 Rules

Rule ID	Name	Description	Severity
CLR001	Purple to Blue Gradient	Detects purple-to-blue gradients, a typical AI-generated color scheme	⚠️ warning
CLR002	Gray Text on Colored Background	Detects gray text (#666/#999) on colored backgrounds with insufficient contrast	❌ error
CLR003	Pure Black/White Background	Detects pure black (#000) or pure white (#fff) backgrounds	⚠️ warning
CLR004	Too Many Colors	Detects more than 5 primary colors, indicating inconsistent color design	⚠️ warning
CLR005	Missing Interactive State Colors	Detects links/buttons missing hover/focus state color definitions	⚠️ warning
CLR006	Hardcoded Color Values	Detects hardcoded color values instead of CSS variables	ℹ️ info
CLR007	Low Contrast Text	Detects text-to-background contrast ratio below WCAG standard (4.5:1)	❌ error
CLR008	Unstyled Default Blue Links	Detects unstyled default blue link colors without customization	ℹ️ info
CLR009	Rainbow Gradient Abuse	Detects rainbow or multi-color gradients, often a sign of AI generation	⚠️ warning
CLR010	Duplicate Color Definitions	Detects same color value hardcoded multiple times, should use CSS variables	ℹ️ info

📐 Layout Rules — 10 Rules

Rule ID	Name	Description	Severity
LAY001	Card-in-Card Nesting	Detects card-in-card nesting pattern, increasing visual complexity	⚠️ warning
LAY002	Fixed Pixel Width	Detects fixed pixel widths instead of responsive units	⚠️ warning
LAY003	Excessive Padding/Margin	Detects padding or margin values exceeding 100px	⚠️ warning
LAY004	text-align:center Overuse	Detects excessive use of text-align:center for centering	ℹ️ info
LAY005	Missing Container/Wrapper	Detects missing container/wrapper to limit content width	⚠️ warning
LAY006	Absolute Positioning Abuse	Detects excessive use of position:absolute	⚠️ warning
LAY007	Excessive z-index Values	Detects z-index values exceeding 999, potentially causing stacking context issues	❌ error
LAY008	Missing Viewport Meta Tag	Detects missing viewport meta tag, affecting mobile display	❌ error
LAY009	display:inline-block Overuse	Detects excessive use of display:inline-block instead of flexbox/grid	ℹ️ info
LAY010	overflow:hidden Overuse	Detects excessive use of overflow:hidden, potentially hiding content	ℹ️ info

🎬 Motion Rules — 7 Rules

Rule ID	Name	Description	Severity
MOT001	Bounce/Elastic Easing Functions	Detects bounce/elastic easing functions which may cause unnatural animation effects	⚠️ warning
MOT002	Excessive Animation Duration	Detects animation durations exceeding 1 second, affecting user experience	⚠️ warning
MOT003	Missing prefers-reduced-motion	Detects animations without prefers-reduced-motion media query	❌ error
MOT004	Infinite Animation Abuse	Detects abuse of animation-iteration-count: infinite	⚠️ warning
MOT005	Too Many Simultaneous Animations	Detects too many elements with animations simultaneously, affecting performance	⚠️ warning
MOT006	Too Many Transition Properties	Detects too many transition properties on a single element	ℹ️ info
MOT007	Animation with !important	Detects animation properties using !important, making them hard to override	ℹ️ info

♿ Accessibility Rules — 8 Rules

Rule ID	Name	Description	Severity
A11Y001	Missing img alt Attribute	Detects img tags missing alt attribute, affecting screen reader accessibility	❌ error
A11Y002	Missing lang Attribute	Detects HTML missing lang attribute, affecting screen reader language detection	❌ error
A11Y003	Missing main/landmark Element	Detects missing main or landmark elements, affecting page navigation	⚠️ warning
A11Y004	Button Missing aria-label	Detects buttons missing text content or aria-label attribute	⚠️ warning
A11Y005	Color as Only Differentiator	Detects color as the only means of differentiation (e.g., "click the red button")	⚠️ warning
A11Y006	Touch Target Too Small	Detects touch targets smaller than 44px, affecting mobile interaction	❌ error
A11Y007	Empty Links	Detects empty links without text content or aria-label	❌ error
A11Y008	Missing Heading Structure	Detects pages missing h1 tag	⚠️ warning

🤖 AI Anti-pattern Rules (AI Slop) — 10 Rules

Rule ID	Name	Description	Severity
AIS001	Rounded Square Icon Tiles	Detects rounded square icon tiles above headings, typical AI-generated content pattern	⚠️ warning
AIS002	Side Tab Borders	Detects decorative borders on side tabs, common AI-generated content pattern	ℹ️ info
AIS003	Dark Glow Effects	Detects glow effects on dark backgrounds (box-shadow glow), AI-generated content marker	⚠️ warning
AIS004	Excessive Gradient Backgrounds	Detects excessive use of gradient backgrounds, typical AI-generated content pattern	⚠️ warning
AIS005	Generic Three-Column Feature Cards	Detects generic three-column feature card layout, typical AI-generated content pattern	⚠️ warning
AIS006	Excessive Emoji Decoration	Detects excessive use of emoji as decorative elements	ℹ️ info
AIS007	Generic Hero Section	Detects generic hero section layout pattern	⚠️ warning
AIS008	Excessive Box-Shadow Stacking	Detects multiple box-shadow stacking, common AI-generated content pattern	⚠️ warning
AIS009	Uniform Border-Radius Abuse	Detects all elements using the same border-radius, lacking design variation	ℹ️ info
AIS010	Decorative Dividers	Detects excessive decorative dividers or horizontal rule elements	ℹ️ info

🎯 Typical Use Cases

Use Case 1: CI/CD Integration

Automatically detect design quality issues in continuous integration pipelines, blocking low-quality code from being merged:

# GitHub Actions example
designguard scan ./src --quiet --severity error
# Exit code: 0 = pass, 1 = error-level issues found

Use Case 2: Code Review Assistance

Quickly scan changed files for design quality during Pull Request reviews:

designguard scan ./src/components --format json --output review-report.json

Use Case 3: Design System Audit

Perform a comprehensive design quality audit on your entire project with an HTML visual report:

designguard scan ./src --format html --output audit-report.html

📸 Output Preview

Terminal color output example:

$ designguard scan ./src

🛡️ DesignGuard-CLI v1.0.0 — Design Quality Report

📁 Scan path: ./src
📄 Files scanned: 23
🔍 Rules applied: 55

❌ Found 12 issues (3 errors · 6 warnings · 3 info)

  ❌ CLR002 [error]    Gray text on colored background
     📄 src/components/Card.tsx:42
     💡 Use darker or lighter text color to ensure contrast

  ⚠️ TYP001 [warning]  Overused AI fonts
     📄 src/styles/global.css:15
     💡 Consider using more distinctive font combinations

  ⚠️ AIS005 [warning]  Generic three-column feature cards
     📄 src/pages/Home.vue:88
     💡 Try different layouts like asymmetric grids

✅ Scan complete! Took 0.12s

💡 Design Philosophy & Roadmap

🧠 Design Philosophy

Why do we need AI design quality detection?

AI coding assistants are transforming the way software is developed, but the frontend code they generate often suffers from an overlooked problem -- design homogenization. When numerous projects use AI to generate interfaces, they start looking increasingly similar: the same font choices, the same color schemes, the same layout patterns. The core philosophy of DesignGuard-CLI is: AI can assist with coding, but design quality still requires human oversight.

We are not against using AI coding tools. Rather, we want to help developers maintain their project's design personality and professional standards while leveraging AI assistance.

🔧 Technical Choices

Why Python with zero dependencies?

Universality: Python is one of the most commonly used languages among developers, pre-installed in nearly all development environments
Zero Friction: No npm install, no pip install of third-party packages -- clone and run
Offline-Friendly: No network connection required, no AI API keys needed, suitable for air-gapped development environments
Lightweight & Efficient: Pure standard library implementation, fast startup, low memory footprint
Easy Integration: Can be easily embedded into any Python project or CI/CD pipeline

🗺️ Roadmap

Version	Planned Features	Status
v1.1	Custom rule plugin system, allowing users to write their own detection rules	📋 Planned
v1.2	VS Code extension for real-time in-editor detection	📋 Planned
v1.3	Webpack/Vite plugin integration for build-time automatic detection	📋 Planned
v2.0	Web UI management dashboard with visual rule configuration and historical trend analysis	📋 Planned

🤝 Community Contribution Directions

We welcome contributions in the following areas:

🆕 New Detection Rules: Discovered a new AI design anti-pattern? Submit a rule PR
🌍 Multilingual Support: Help improve multilingual translations of rule descriptions
📚 Documentation: Add use cases and best practice guides
🐛 Bug Fixes: Found false positives or false negatives? Submit an Issue
🧪 Test Coverage: Help add test cases to improve detection accuracy

📦 Packaging & Deployment Guide

📥 pip Installation

# Install from PyPI (coming soon)
pip install designguard-cli

# Install from source
pip install git+https://github.com/gitstq/DesignGuard-CLI.git

🔨 Install from Source

git clone https://github.com/gitstq/DesignGuard-CLI.git
cd DesignGuard-CLI
pip install -e .

🐳 Docker Deployment

FROM python:3.11-slim

WORKDIR /app
COPY . .

RUN pip install -e .

ENTRYPOINT ["designguard"]

# Build the image
docker build -t designguard-cli .

# Run a scan
docker run --rm -v $(pwd)/src:/src designguard-cli scan /src

🔄 CI/CD Integration Example (GitHub Actions)

name: Design Quality Check

on: [pull_request]

jobs:
  designguard:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4

      - name: Set up Python
        uses: actions/setup-python@v5
        with:
          python-version: '3.11'

      - name: Install DesignGuard-CLI
        run: pip install -e .

      - name: Run design quality check
        run: designguard scan ./src --quiet --severity error

🤝 Contributing Guide

We warmly welcome community contributions! Here is the contribution workflow:

📋 PR Submission Guidelines

This project follows the Angular Commit Convention:

<type>(<scope>): <subject>

<body>

Commit types:

Type	Description
`feat`	New feature
`fix`	Bug fix
`docs`	Documentation update
`style`	Code formatting (no logic changes)
`refactor`	Code refactoring
`test`	Test-related
`chore`	Build/tooling related

Example:

feat(rules): add detection rule - rounded square icon tiles

- Add AIS001 rule to detect rounded square icon tiles above headings
- Support multiple icon container class pattern matching
- Add corresponding unit test cases

🐛 Issue Reporting Guidelines

When submitting an Issue, please include the following information:

Problem Description: Clearly describe the issue or suggestion
Steps to Reproduce: Provide a minimal reproducible example
Expected Behavior: Describe what you expect the correct behavior to be
Actual Behavior: Describe what you actually observed
Environment: Python version, operating system, DesignGuard-CLI version

🛠️ Development Environment Setup

# Clone the repository
git clone https://github.com/gitstq/DesignGuard-CLI.git
cd DesignGuard-CLI

# Install (development mode)
pip install -e .

# Run tests
python -m pytest tests/

# Verify installation
designguard --version

📏 Code Standards

Follow PEP 8 code style
All public functions and classes must include bilingual (Chinese/English) docstrings
New rules must include corresponding unit tests
Rule ID naming convention: category prefix + three-digit number (e.g., TYP001, CLR003)
Ensure all tests pass before submitting: python -m pytest tests/

📄 License

This project is licensed under the MIT License.

The MIT License is a concise and permissive open-source license that allows you to freely use, copy, modify, merge, publish, distribute, sublicense, and/or sell this software, with the only requirement being that copyright and license notices are included in all copies or substantial portions.

In short: You can do anything with this software, but please retain the original author's copyright information.

See the LICENSE file for details.

_{Built with ❤️ by DesignGuard Team}

Name		Name	Last commit message	Last commit date
Latest commit History 1 Commit
.github/workflows		.github/workflows
designguard_cli		designguard_cli
tests		tests
.gitignore		.gitignore
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
README.md		README.md
pyproject.toml		pyproject.toml
setup.py		setup.py

Folders and files

Latest commit

History

Repository files navigation

🛡️ DesignGuard-CLI

🇨🇳 简体中文

📑 目录

🎉 项目介绍

🎯 项目定位

💡 灵感来源

🔥 核心价值

✨ 核心特性

🚀 快速开始

📋 环境要求

📦 安装

🎮 使用示例

📖 详细使用指南

📝 CLI 命令详解

🔧 scan 命令参数

⚙️ 配置文件

📏 规则分类一览

🔤 排版规则（Typography）— 10 条

🎨 色彩规则（Color）— 10 条

📐 布局规则（Layout）— 10 条

🎬 动效规则（Motion）— 7 条

♿ 可访问性规则（Accessibility）— 8 条

🤖 AI 反模式规则（AI Slop）— 10 条

🎯 典型使用场景

📸 运行效果

💡 设计思路与迭代规划

🧠 设计理念

🔧 技术选型原因

🗺️ 迭代规划

🤝 社区贡献方向

📦 打包与部署指南

📥 pip 安装

🔨 从源码安装

🐳 Docker 部署

🔄 CI/CD 集成示例（GitHub Actions）

🤝 贡献指南

📋 提交 PR 规范

🐛 Issue 反馈规则

🛠️ 开发环境搭建

📏 代码规范要求

📄 开源协议

🇹🇼 繁體中文

📑 目錄

🎉 專案介紹

🎯 專案定位

💡 靈感來源

🔥 核心價值

✨ 核心特性

🚀 快速開始

📋 環境要求

📦 安裝

🎮 使用範例

📖 詳細使用指南

📝 CLI 命令詳解

🔧 scan 命令參數

⚙️ 配置檔案

📏 規則分類一覽

🔤 排版規則（Typography）— 10 條

🎨 色彩規則（Color）— 10 條

📐 佈局規則（Layout）— 10 條

🎬 動效規則（Motion）— 7 條

♿ 可訪問性規則（Accessibility）— 8 條

🤖 AI 反模式規則（AI Slop）— 10 條

🎯 典型使用場景

📸 運行效果

💡 設計思路與迭代規劃

🧠 設計理念

🔧 技術選型原因

🗺️ 迭代規劃

🤝 社群貢獻方向

📦 打包與部署指南

📥 pip 安裝

🔨 從原始碼安裝

🐳 Docker 部署

🔄 CI/CD 整合範例（GitHub Actions）

🤝 貢獻指南

Packages