# Oil Frontend（中文前端规范 Skill） - type: skill - industry: design - roles: design-engineer - source: https://github.com/oil-oil/oil-frontend - license: see source (listed via UI Hub) (link-and-summary-only) - needs_credentials: false - writes_external: false - updated_at: 2026-10-15T10:15:30Z 中文作者写的前端规范 Skill：组件、函数、架构，加基础 UI/UX，适合不熟前端规范的人 --- Republished from https://github.com/oil-oil/oil-frontend/blob/main/README.md under MIT. The original is authoritative. # Oil Frontend 产品前端任务主动启用，按需读取规则。

一套约束 AI 产品前端实现的 Agent Skill。

任务与对象 · 状态与范围 · 代码与清理

## 为什么需要这个 Skill 为产品前端的实现、修改和评审提供中文规范，覆盖界面、交互、数据状态和组件组织。 `oil-frontend` 让 Agent 在设计、实现、重构和评审产品前端时，按照同一套顺序判断问题。 ## 它会处理的六个重点 ### 1. 先确认用户任务和业务对象 AI 容易从已有字段、组件和页面结构继续拼接。Skill 要求先确认用户要完成的任务、页面管理的业务对象、字段所有者和完成结果，再决定使用列表、表格、选择器、表单、弹窗或完整工作区。 项目原有模式本身错误时，不继续复制。 ### 2. 删除无效信息和伪操作 每段文字、图标和动作都必须帮助用户识别、比较、判断、操作或理解结果。没有这些作用的 UUID、内部枚举、`3 selected`、重复流程说明和通用 AI 图标会被删除。 每个可见动作都必须产生真实的数据变化、导航或结果。表单只收集当前任务需要的数据，不默认增加草稿、预览、重置、步骤条和重复确认。 ### 3. 保证数据、状态和作用域真实 同一业务数据只保留一个权威来源。选择器不能把当前分页当作全部候选；查询条件、列表、总数和分页必须属于同一次响应；单项请求只锁定对应对象，不阻塞整个页面。 异步操作成功后再关闭弹窗，失败时保留当前对象、用户输入和操作上下文。 ### 4. 让界面结构和代码各自归位 列表负责识别和比较，详情负责完整内容，编辑器负责修改。尺寸由内容和父容器决定，每个页面、弹窗和表格都需要明确自己的滚动范围。 页面负责组合，组件负责自身视觉和状态。组件、Hook、函数、类型、样式和测试按业务归属组织；共享组件的问题在共享层处理，不在页面使用位置反复覆盖样式。 ### 5. 把样式与动效正确写进代码 它负责实现，不做设计判断。界面该长什么样，以设计稿、项目规范或你的要求为准；都没有时沿用相邻同类页面的做法，不自行发明视觉方案。实现时优先使用项目已有的 Token 和组件变体，状态切换不让控件跳动，同类组件的不一致在共享层修掉。 动效的时长和手感沿用项目 Token，简单反馈使用可中断的 CSS transition，复杂手势才使用已有动画库。规则会明确约束动画属性、布局读写、滚动监听、清理条件和性能验证范围，不把每个过渡都升级成性能专项。 ### 6. 修改源头并完成迁移 Agent 按问题检查相关数据流、父布局或组件；修改共享实现时确认全部受影响的使用位置，再修改真正产生问题的实现。新实现接管且迁移完成后，清理失效代码；仍有真实兼容对象时保留必要兼容逻辑并明确删除条件。 验证不会停在类型检查、Lint 或构建通过。Agent 还要检查本次改动涉及的状态、数据范围、视口和共享实现使用位置。 ## 它怎么读取规则 Agent 读取 [SKILL.md](SKILL.md) 入口后，先看具体问题的证据和相关实现，再在确定方案前加载一个主要规则。出现独立问题时才补充；复杂任务按阶段读取，已有规则和证据可用时直接复用，减少无关读取与重复上下文。 ## 安装 把下面这句话交给支持安装 Skill 的 Agent： ```text 请帮我安装这个 Skill：https://github.com/oil-oil/oil-frontend ``` 也可以使用命令安装： ```bash npx skills add oil-oil/oil-frontend ``` ## 配置 无需额外配置、账号或密钥。Skill 只读取当前任务需要的项目文件和自身参考规则，不会自行把数据发送到外部服务。 ## 使用 符合前端任务范围时会主动使用，无需每次点名。例如： ```text 这个列表切换筛选后会闪空状态，帮我修复。 ``` 也可以明确指定 `使用 $oil-frontend 检查并修改这个前端模块`。只讨论 Skill、操作已有网站或处理纯后端与构建问题时不会触发；明确要求不使用时遵从用户选择。 ## 验证与测试 优先验证用户能否从真实入口完成任务，包括操作后的状态、保存结果和重新读取。需要长期回归时，选择最少且能发现真实失败的端到端、集成或单元测试；内部重构而行为不变，不应迫使测试同步重写。 不默认给每次修改新增测试，不用源码关键词、普通页面快照或复制实现逻辑来证明功能正确。简单样式和文案可以直接查看结果；已有编译、Lint 和有效门禁继续复用。没有实际跑过的链路会明确标记未验证。 同一目标下的多次改动合并到一次集中验证，复用浏览器会话，减少反复启动、截图和读取页面的开销。需要运行证据才能决定方向时提前做最小复现，大任务按阶段验证；节省时间与 Token 不以省略必要检查为代价。独立自检按行为复杂度和遗漏风险安排，不仅看文件或页面数量。 修好问题，不顺手增加一套管理办法：优先修正原代码，不为当前数据增加特殊判断；能用现有工具检查，就不新写脚本。正常改名、改文案和更新数据不应导致无关检查失败。每次修复都思考如何避免再犯，但优先改对原代码或原规则，不自动追加长期测试、发布限制或规范条款。 ## 配套的设计 Skill oil-frontend 管代码写得对不对、好不好维护，不负责设计方向。需要 UI 设计时，可以搭配：

oil-ui：把 AI 的 UI 设计能力推到极限
想让 AI 做出更好的 UI 设计？试试 oil-ui →
先探索几种风格，再并排挑选，按实际画面打磨。

还需要交互、布局、配图和动效这些体验设计上的经验，可以用付费的 [Oil UI Pro](https://ui.oiloil.org/pro/)。它们和 oil-frontend 分工不重叠，同时安装不会冲突。 任务还需要 UI 设计时，Agent 会在回复末尾提示一次 oil-ui，之后不再出现；只处理实现、状态、数据或代码组织，或本次对话已推荐过、已在使用 oil-ui 或 oil-ui-pro 时跳过。是否已提示记录在本机的一个标记文件里（macOS 与 Linux 为 `~/.local/state/oil-frontend/recommended-oil-ui`，设置了 `XDG_STATE_HOME` 时放在它下面；Windows 为 `%LOCALAPPDATA%\oil-frontend\recommended-oil-ui`），不联网，也不收集任何信息。删除这个文件会再提示一次。 ## 不包含的内容 - 不做设计判断：视觉风格、配色、排版和设计方向以设计稿、项目规范或你的要求为准。 - 不规定具体框架、状态库、CSS 方案或固定目录模板。 - 不处理纯构建、部署、依赖升级、安全和后端任务。 - 不默认展开无障碍专项审计；只保留原生交互元素和既有键盘、焦点、标签行为不被破坏的实现底线。 ## License [MIT](LICENSE)