# Oil Frontend > 仅在用户明确要求使用 oil-frontend 时触发，或在用户主动通过 Skill 选择器选择时触发。典型表达包括 $oil-frontend 和“用 oil-frontend”。普通前端、UI/UX、组件、CSS、交互、视觉、动效或重构请求不得自动触发；只讨论、引用或评价本 Skill 也不触发。触发后用于实现、修改、重构或评审产品前端，并按主要决策加载最小规则集。 - Skill: `oil-oil/oil-frontend` (Agent Skill, multi-file: 4 files) - Install (CLI): `npx skillmds@latest add oil-oil/oil-frontend` - Raw SKILL.md: https://api.skillmd.com/api/skills/oil-oil/oil-frontend/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Web & Frontend - Author: oil-oil (https://skillmd.com/u/oil-oil) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/oil-oil/oil-frontend --- # Oil Frontend 先识别用户任务、业务对象和数据来源，再删除无效内容，建立正确的信息、状态、代码归属和共享实现。 ## 始终遵守 - 从真实用户任务、业务对象和完成结果出发；可见内容只保留能够帮助识别、比较、判断、操作或理解结果的信息。 - 一个用户意图只执行一次，动作必须产生真实结果；数据、操作、忙碌和提交边界保持一致，失败时保留当前对象、位置和已输入内容。 - 常见任务沿用用户已有认知；资源浏览默认展示，编辑必须明确触发，表单只收集当前任务必需且归当前对象所有的数据。 - 图标、强调方式和固定尺寸都必须表达稳定含义；不使用通用 AI 装饰、无意义强调边或只适配当前实例的尺寸制造层级。 - 视觉调整先沿用项目已有的设计变量、组件和密度，再处理层级、间距、排版、表面与反馈；没有项目标准时才使用参考规则中的兜底值，不把兜底值扩张成新的设计系统。 - 同一业务数据和同一含义只保留一个权威来源；优先修复数据流、父布局和共享实现，不在页面使用位置反复打补丁。 - 按业务归属组织组件、Hook、函数、类型、样式和测试；单模块代码就近放置，只有稳定跨模块复用时才进入共享层。 - 遇到复杂逻辑，先检查项目已有能力和成熟库；已有依赖不合适时，可以引入维护良好、与项目兼容的新库，不手写已有成熟方案覆盖的核心能力。简单逻辑直接实现，不为少量代码引入新依赖。 - 项目历史不是正确性的证明；错误模式应被替换，相关使用位置完成迁移后删除旧代码、fallback、legacy 逻辑和失效状态。 ## 参考文件读取顺序 1. 触发后先只阅读本文件，明确任务、对象和改动范围，不预先读取参考文件。 2. 如果任务不涉及用户可见界面、前端状态与数据流、组件实现或前端代码组织，停止使用本 Skill。 3. 先按用户要改变的结果选择一个主要规则，不按文件类型或代码中出现的 CSS、动画关键词选规则。 4. 简单局部改动只读取一个主要规则；任务确实同时包含第二个独立问题时才补充一个。只有跨页面综合评审可以读取三个，不得更多。 5. 不因关键词出现、文件内链接或“保险起见”继续读取规则。视觉症状由数据、状态或父布局造成时，读取真正负责根因的规则，不额外加载视觉规则。 | 当前任务 | 主要规则 | 仅在这些情况补充 | | --- | --- | --- | | “看起来不对”、视觉精修、层级、间距、排版、颜色、圆角、边框、阴影或图标 | [视觉工程](references/visual-engineering-contract.md) | 需要修改共享 Token、组件默认样式或变体时读 [组件与代码组织](references/component-contract.md)；改变分栏、滚动或响应式结构时改读 [视口与弹窗](references/viewport-and-dialog-contract.md) 为主要规则 | | 动画、过渡、微交互、展开收起、拖拽反馈、滚动动效或卡顿 | [动效与性能](references/motion-performance-contract.md) | 动效承担动作反馈或视觉层级时读 [视觉工程](references/visual-engineering-contract.md)；根因是异步状态时改读 [状态与加载](references/state-and-loading-contract.md) 为主要规则 | | 模块边界、组件、Hook、函数、类型、样式归属、共享样式、CSS 组织或共享实现 | [组件与代码组织](references/component-contract.md) | 需要新增检查时读 [自动化](references/automation-contract.md) | | 新增或改变文案、动作含义、图标、点击反馈或视觉强调 | [信息与动作](references/information-and-action-contract.md) | 涉及对象身份、图片或选择器时读 [资源识别](references/resource-recognition-contract.md) | 数据、状态和布局继续按结果选择： | 当前任务 | 主要规则 | 仅在这些情况补充 | | --- | --- | --- | | 列表、卡片、详情、表格或批量操作 | [集合与详情](references/collection-and-detail-contract.md) | 涉及资源身份时读 [资源识别](references/resource-recognition-contract.md)；涉及编辑时读 [交互与编辑](references/interaction-and-editing-contract.md) | | 表单、选择、编辑或多步工作流 | [交互与编辑](references/interaction-and-editing-contract.md) | 涉及保存范围和流程连续性时读 [数据与操作范围](references/scope-and-state-integrity-contract.md) | | 查询结果、分页、候选集合、保存范围、批量范围或请求结果归属 | [数据与操作范围](references/scope-and-state-integrity-contract.md) | 同时改变 loading、refreshing、empty、error 或 processing 呈现时读 [状态与加载](references/state-and-loading-contract.md) | | loading、refreshing、empty、filtered-empty、error、queued、processing 或骨架 | [状态与加载](references/state-and-loading-contract.md) | 同时涉及查询快照、操作范围或保存结果归属时读 [数据与操作范围](references/scope-and-state-integrity-contract.md) | | 改变页面尺寸、分栏、滚动、弹窗结构或响应式行为 | [视口与弹窗](references/viewport-and-dialog-contract.md) | 涉及下拉、菜单、提示等依附触发器的浮层时读 [弹层](references/overlay-contract.md) | 以下情况不触发额外读取： - 代码中存在 Tailwind、CSS、`transition` 或动画库，不代表任务是视觉或动效任务。 - 改变颜色、间距、边框、阴影、排版等可见属性时，以视觉工程为主要规则；只有任务同时要求调整样式归属、共享方式或模块边界时才补充组件与代码组织规则。 - 只修复颜色变量名、类名、类型或导入错误，且不改变视觉结果时，不读取视觉工程规则。 - 只为既有动效改业务状态、事件绑定或数据来源，且不改变运动方式和性能时，不读取动效规则。 - 只移动现有控件，且不改变文案、动作含义或反馈时，不读取信息与动作规则。 - 只调整普通父子容器归属，且不改变尺寸、滚动、弹窗或响应式行为时，不读取视口与弹窗规则。 - 参考文件中的链接只说明相关规则的位置，不表示必须继续读取。 ## 术语速查 本文件和参考规则中的核心词汇，按这里的定义理解： - **资源身份**：让用户认出"这是哪个对象"的最小信息组合——图片 + 名称 + 一个区分字段。例：成员列表显示"头像 + 姓名 + 部门"，而不是"uuid + 类型标签"。 - **伪操作**：看似可用、实际不产生真实结果的控件。例：点"保存"只改了本地 state、刷新即丢失；删除按钮永久 disabled 占位。 - **单个组件的视觉补丁**：在页面使用共享组件的位置，只给这一个组件补样式。例：``、`!important` 覆盖、页面专属选择器改组件内部。正确做法是修共享组件本身，或新增按用途命名的组件变体。 - **按用途命名的组件变体（variant）**：用“为什么不同”命名。例：`variant="destructive"`、`size="compact"` 合格；`variant="blue"`、`variant="userListPage"` 不合格。 - **主导动作**：当前页面、弹窗或操作区域中完成主要任务的那一个操作。同一区域最多一个高强调按钮。 - **提交边界**：一次修改何时真正生效——即时生效、自动保存、显式统一提交，或仅临时预览。 - **忙碌范围**：请求进行中需要防止重复操作的最小区域。单项请求只锁定该项，不用全页遮罩。 - **已提交查询快照**：由同一次响应共同确定的查询条件、列表、结果总数和分页信息。新查询完成前，旧快照仍属于旧条件。 - **同类批量任务**：对一批同类对象重复填写相同字段的任务，如批量排期、批量改价。 - **可编辑工作表**：为同类批量任务让多行持续处于编辑态的表格。与之相对的是资源列表：默认展示，编辑必须明确触发。 ## 决策顺序 改动前依次回答。 任务与对象： 1. 用户当前要完成什么任务，什么结果表示完成？ 2. 页面管理哪个核心对象，字段分别归谁所有？ 3. 当前是浏览、比较、选择还是编辑，是否沿用用户熟悉的结构和术语？ 数据与范围： 4. 数据来自完整集合、当前可见集合还是搜索结果？ 5. 操作、忙碌状态和提交边界分别影响什么范围；远程查询条件与当前列表是否已经属于同一次已提交结果？ 6. 用户靠哪些信息区分相邻对象？ 7. 能否删除文字、步骤、确认、重复输入或系统已经知道的字段？ 8. 哪些信息属于集合，哪些只属于详情？ 结构与状态： 9. 当前页面、弹窗或操作区域的主导动作是什么？ 10. 首屏、滚动容器和弹层边界分别由谁负责？ 11. loading、empty、filtered-empty、queued、processing、error、ready 如何互斥？ 视觉与动效，仅在任务要求改变时回答： 12. 当前项目用哪些 Token、组件和相邻页面定义层级、密度与动效语言？真正不一致的是哪个可见属性？ 13. 动效是在反馈状态、解释空间关系还是装饰；能否只使用 `transform`、`opacity` 或已有组件能力完成？ 落点： 14. 是否已有正确归属的模块、组件、Hook、函数、类型、统一设计变量或样式，最终应修改哪个数据源、父布局或共享实现？ 无法明确回答时，先停止添加界面元素：向用户提出最关键的 1–2 个问题；无法提问时按最小可验证范围实施，并在输出中声明所做的假设。 ## 执行流程 ### 1. 还原事实 - 搜索项目已有的模块、组件、Hook、函数、类型、统一设计变量和样式，确认相同含义是否已经存在正确实现。 - 找出所有使用共享组件的页面和组件，以及相同数据的其他入口。 - 评审请求只给证据与建议；用户要求修改时才实施。 ### 2. 明确范围 - 明确核心对象、字段所有者、数据集合、操作范围、忙碌范围和提交边界。 - 区分页面结构问题、组件默认行为、页面使用方式错误和数据流错误。 - 视觉问题只记录能够指出具体元素、属性、现有依据和代码落点的差异；不能确定正确值时先使用项目既有 Token 或相邻同类组件，不凭审美发明精确数值。 ### 3. 先删除 - 删除不影响判断的内容、重复状态、重复入口、重复确认和只针对单个组件的视觉补丁。 - 删除没有真实状态变化或不能真正保存数据的伪操作。 - 删除已经被新实现替代的旧组件、旧函数、旧类型、旧状态、fallback、legacy 逻辑、旧样式和失效引用。 ### 4. 选择结构 - 先检查项目中同类任务页面和共享容器组件的既定用法；只有既有模式符合本规范时才沿用，否则按真实任务重新选择结构。 - 根据浏览、比较、选择、批量配置或深度编辑任务，选择列表、表格、工作表、选择器、弹窗或完整工作区。 - 让列表负责识别和比较，让详情负责完整内容，让编辑器负责修改。 - 视觉调整按“信息层级 → 空间与对齐 → 排版 → 表面 → 控件状态 → 动效”的顺序处理；前一层已经解决问题时停止，不继续叠加装饰。 ### 5. 修复真正出错的位置 - 优先修复数据范围、操作范围、父布局、共享组件默认行为和含义稳定的组件变体。 - 重复出现的资源身份、菜单、弹层、加载、弹窗和操作栏使用共享组件。 - 只有职责、输入输出和行为稳定重复时才抽象；不要因为局部结构相似就复制组件，也不要用大量页面开关制造万能组件。 - 既有共享组件、函数、样式或数据流本身错误时，在授权范围内直接修复或替换真正出错的共享实现，并处理所有受影响的使用位置；不要为了兼容历史继续新增错误实现。 - 无法在当前范围内全部改完时，停止扩大旧模式，明确报告还剩哪些旧使用位置以及这次改到哪里，不得声称已经统一。 - 修复可重复检测的问题时，判断项目是否确实需要新增 lint、测试或检查规则；需要时按路由表补充读取 [自动化](references/automation-contract.md)，并计入补充规则数量。小改动不为此前置搭建自动化。 - 不修改无关区域。 ### 6. 验证 - 运行项目现有且与改动相关的类型检查、Lint、测试或构建。 - 简单局部改动只检查修改位置、直接行为和最近的使用位置，不展开完整状态矩阵。 - 改动涉及共享组件、数据范围、异步状态、表单流程、滚动、响应式或多个页面时，再检查受影响的状态、数据范围、代表性视口和全部使用位置。 - 视觉改动检查真实内容、主要状态和受影响视口；动效改动只按类型检查适用的中断、重复触发、退出、卸载或滚动行为。只有复杂动效或真实卡顿才使用性能录制，不把每个过渡升级成性能专项。 - 只报告已验证项、未验证项和阻断原因。 ## 独立自检 仅当前端评审涉及多个页面、所有使用共享组件的位置、多种视口或状态，或大范围规则调整时，才派发无历史上下文的独立自检。单页面、单组件、单截图和局部差异由主 Agent 直接检查。 独立自检只接收检查对象、范围和 `oil-frontend`，不接收对话历史、既有结论、问题猜测、预期答案或修复方案。 ## 输出要求 先给结论，再给证据。只输出： 1. 具体问题； 2. 应删除的内容； 3. 正确的信息、动作和空间结构； 4. 应修改的模块、共享组件或数据流； 5. 已验证和未验证项。 禁止使用"提升体验""更现代""更直观"等不能指导实现的描述。 不主动扩展成无障碍专项审计。实现 UI 时继续使用原生交互元素，不破坏项目已有的焦点、键盘、标签和 ARIA 行为；只有用户明确要求或当前改动直接造成任务不可完成时才展开检查。