NiceUI

面向网页与应用界面的设计、实现和审查工作流。NiceUI 让 AI 先理解产品、用户任务和现有项目，再决定页面结构、视觉语言、真实内容、交互状态与验证方式，产出可用而不是只有外观的界面。

它不是组件库，也不把所有产品套成同一套主题；它是一套可被多个 AI 编程工具加载的 Agent Skill，附带 CLI 安装器和按需读取的设计参考文档。

核心能力

• 产品先行 — 先识别产品载体、页面职责、子类型和领域内容模型，再决定布局与组件。
• 非模板化设计 — 建立产品指纹，检查相邻页面和连续交付之间的风格距离，避免通用 Hero、后台侧栏和登录卡片模板。
• 完整实现流程 — 覆盖理解任务、检查项目、确定方向、实现、验证、迭代六个阶段。
• 真实内容与状态 — 要求真实标题、字段、数据、媒体、操作结果，以及正常、悬停、聚焦、加载、空数据、错误和成功等相关状态。
• 平台适配 — 为 Web、React/Vue/Tailwind 和 Flutter 提供独立的实现规则，并根据项目技术栈路由参考文档。
• 交互与可访问性 — 关注键盘操作、焦点、表单语义、图标一致性、内容溢出、响应式和 prefers-reduced-motion。
• 动效有目的 — 官网、品牌、营销和创意展示页可使用 Canvas、滚动、鼠标或入场动效；后台和工具页面只保留有助于理解状态的反馈。
• 验证门禁 — 交付前执行静态视觉检查、首屏识别检查、真实尺寸渲染、交互与内容溢出验证，并输出 5 秒自检结果。

案例展示

下面案例来自仓库中的实际演示素材，覆盖后台、商城、音乐平台和 SaaS 官网，展示同一套工作流如何根据产品语境切换信息密度、内容模型和视觉方向，而不是复用固定模板。

更多案例见 完整案例目录。

快速开始

安装到项目

适合让项目保留一份可追踪的 NiceUI 依赖：

npm install ui-nice-skill

# 查看 CLI 帮助；--no-install 确保使用项目内已安装的版本
npx --no-install niceui --help

# 输出主技能内容
npx --no-install niceui

全局安装

适合在终端中直接调用 CLI，或把 NiceUI 安装到多个项目/AI 工具：

npm install -g ui-nice-skill

niceui --help
niceui ls                 # 列出支持的 AI 工具
niceui -r                 # 列出参考文档
niceui -d                 # 输出 NiceUI 安装路径

安装到 AI 工具

NiceUI 使用 SKILL.md + frontmatter 的 Agent Skills 结构。进入目标项目后，可以按工具安装，或一次安装到所有支持的目标：

cd /path/to/your/project

niceui i all              # 安装到所有支持的工具
niceui i claude           # 只安装 Claude Code
niceui i cursor            # 只安装 Cursor

| 工具 | 命令 | 生成位置 | |---|---|---| | Claude Code | niceui i claude | ~/.claude/skills/niceui/ | | OpenCode | niceui i opencode | ~/.config/opencode/skill/niceui/ | | Cursor | niceui i cursor | .cursor/skills/niceui/ + .cursor/rules/niceui.mdc | | Windsurf | niceui i windsurf | .windsurf/rules/niceui.md | | Codex CLI | niceui i codex | AGENTS.md | | Gemini CLI | niceui i gemini | AGENTS.md | | GitHub Copilot CLI | niceui i copilot | AGENTS.md | | Aider | niceui i aider | CONVENTIONS.md |

niceui i <工具> 会根据目标工具选择复制 skill 目录或写入规则文件。codex、gemini 和 copilot 共用项目根目录的 AGENTS.md，请在目标项目目录中运行命令。

输出规则文件而不立即写入

规则型工具可以使用单个内联文档。CLI 会把 SKILL.md 和 references/ 中的参考文档拼接成完整规则内容：

niceui r codex                  # 打印 AGENTS.md 内容
niceui r codex --write          # 写入 ./AGENTS.md
niceui r codex --write --force  # 覆盖已安装的 NiceUI 规则

使用方式

自动激活

安装到 Claude Code、OpenCode、Cursor 或其他支持规则/skill 的工具后，直接提出 UI/UX 任务即可：

为一个医疗预约产品设计患者端首页，保留项目现有的品牌色，先检查现有组件和响应式规则，再实现可操作的页面。

审查这个后台页面的首屏密度、键盘操作、状态反馈和移动端溢出问题，只输出按严重程度排序的问题与修改建议。

对话模型

在 ChatGPT、Claude 或其他对话模型中，直接提供 SKILL.md 的内容；复杂任务再按需提供 references/ 中对应的参考文档。

典型任务

从零创建一个 SaaS 产品落地页，要求首屏能看出真实产品对象，并提供有目的的入场动效。

修改现有电商商品详情页，只解决移动端规格选择和购买操作的溢出问题，不改变现有视觉语言。

审查一个 Flutter 仪表盘，重点检查信息密度、空数据状态、可访问性和交互反馈。

工作原理

NiceUI 将界面任务分成六个阶段：

1. 理解任务 — 区分从零创建、修改/重构和仅审查，明确用户、核心任务、设备和页面职责。
2. 检查项目 — 识别框架、入口、组件库、设计变量、字体、图标、资源和已有视觉语言。
3. 确定方向 — 推导领域内容模型和产品指纹，选择构图模式、信息密度、视觉方向和交互强度。
4. 完整实现 — 遵循项目约定，使用真实内容，覆盖主要工作流与相关状态，并加载对应平台规则。
5. 验证结果 — 运行已有检查，在桌面与移动尺寸中验证渲染、交互、溢出、键盘、焦点、对比度和动效偏好。
6. 迭代 NiceUI — 当任务是改进技能本身时，从验证样本的失败中提炼可复用规则，不把测试页面变成默认模板。

支持的平台与技术栈

| 类型 | 支持范围 | 对应参考 | |---|---|---| | Web | 原生 HTML / CSS / JavaScript | impl-web.md | | React 生态 | React、Next.js、Tailwind、styled-components | impl-react.md | | Vue 生态 | Vue、Nuxt（复用组件化实现规则） | impl-react.md | | Flutter | Flutter / Dart / Widget | impl-flutter.md |

未识别到已知技术栈时，默认按 Web 实现规则处理。用户指定的框架、组件库、图标库和现有设计系统优先于 NiceUI 的通用建议。

质量底线

• 全页面文字计算字号不超过 22px；通过字重、行高、留白、位置和颜色建立层级。
• 不用 Emoji 代替功能图标；图标来自统一的 SVG 或图标组件。
• 不用 CSS 渐变或纯色块冒充产品图片、人物、封面、截图或 Logo；没有素材时使用真实可加载的演示图片。
• 表单控件保持可访问语义与键盘行为；下拉、复选、日期等控件使用合适的自定义组件。
• Hover、focus、active、disabled、弹出和收起等状态不应瞬间跳变，并尊重减少动效偏好。
• 页面内容必须对应产品领域，不能用空泛标题、占位文案、假图表和均质卡片代替真实对象。
• 首屏必须能识别产品类型、主要对象和主要动作；后台、工具和编辑器应优先显示可操作对象。
• 修改已有页面时默认保留当前视觉语言，只在任务范围内改动；新页面则需要检查与近期页面的风格距离。

目录结构

ui-nice-skill/
├── SKILL.md                 # 主技能定义：原则、流程、门禁和输出要求
├── README.md                # 安装、使用和开发说明
├── package.json              # npm 包与 niceui CLI 配置
├── bin/
│   └── niceui.js             # 安装器、规则生成器和 CLI 入口
├── agents/
│   └── openai.yaml           # OpenAI skill 展示信息与默认提示
└── references/               # 按任务路由的设计与实现参考

参考文档路由

仓库目前包含 18 份参考文档。SKILL.md 会在任务需要时指向它们，CLI 也可以把它们内联到规则文件中。

| 主题 | 文档 | |---|---| | 设计方向与决策 | design-decision.md、design-methodology.md、design-direction.md | | 产品识别与参考学习 | product-specificity.md、reference-learning.md、reference-discovery.md | | 视觉与构图 | visual-system.md、theme-references.md、composition-detail.md | | 跨平台基线 | design-baseline.md、interaction-baseline.md | | 平台实现 | impl-web.md、impl-react.md、impl-flutter.md | | 修改与动效 | modify-existing.md、motion-canvas.md | | 验证与技能迭代 | verification.md、skill-evaluation.md |

更新 NiceUI

NiceUI 被复制到 AI 工具目录或项目规则文件后，是一份独立快照。更新 npm 包不会自动刷新已经安装的副本：

# 全局安装方式
npm install -g ui-nice-skill@latest
niceui i <工具>              # 或 niceui i all

# 项目安装方式
npm install ui-nice-skill@latest
npx --no-install niceui i <工具>

如果工具提示找不到 niceui 命令，先确认是否进行了全局安装，并检查 npm 全局 bin 目录是否在 PATH 中：

npm prefix -g
echo "$(npm prefix -g)/bin"

使用 fnm/nvm 管理 Node.js 时，可把下面这行加入 ~/.zshrc 后重新打开终端：

export PATH="$(npm prefix -g)/bin:$PATH"

本地开发与贡献

修改技能规则时，优先编辑 SKILL.md 或对应的 references/；README.md 只描述实际可用的能力和命令：

git clone https://github.com/lxhcool/niceui.git
cd niceui

# 检查 CLI 帮助、工具列表和参考文档列表
node bin/niceui.js --help
node bin/niceui.js ls
node bin/niceui.js -r

# 检查 npm 打包内容，不生成发布包
npm pack --dry-run

提交前至少确认：

• README 中的命令与 bin/niceui.js 的实际参数一致。
• 目录、参考文档数量和文件链接没有过期。
• SKILL.md 的 frontmatter、agents/openai.yaml 和 package.json 未被文档改动意外破坏。
• 修改规则后，用独立验证页面执行 skill-evaluation.md 中的验证协议。

常见问题

npm 更新后 AI 仍使用旧规则

复制到 AI 工具目录的文件不会自动同步。重新执行对应的安装命令：

niceui i claude
niceui i opencode
niceui i all

niceui 找不到

项目内安装请使用 npx --no-install niceui；全局使用请执行：

npm install -g ui-nice-skill
niceui --help

若仍找不到，检查 $(npm prefix -g)/bin 是否在 PATH 中。

不确定支持哪些工具或参考文档

niceui ls
niceui -r

规则文件没有覆盖

niceui r <工具> --write 默认会跳过已经包含 NiceUI 的规则文件；确认内容后，如确实需要刷新可使用：

niceui r codex --write --force

License

MIT