Oil Frontend

What does Oil Frontend do?

First, identify the user's task, business objects, and data sources. Then, remove invalid content and establish correct information, state, code ownership, and shared implementations.

Always Follow

• Start from the real user task, business object, and completion result; only keep visible content that helps identify, compare, judge, operate, or understand the result.
• Execute a user intent only once; actions must produce real results; keep data, operations, busy state, and submission boundaries consistent; on failure, preserve the current object, position, and entered content.
• For common tasks, follow the user's existing mental model; resource browsing shows by default, editing must be explicitly triggered, forms only collect data necessary for the current task and owned by the current object.
• Icons, emphasis methods, and fixed sizes must express stable meaning; do not use generic AI decorations, meaningless emphasis borders, or sizes that only fit the current instance to create hierarchy.
• For visual adjustments, first use the project's existing design tokens, components, and density; then handle hierarchy, spacing, typography, surface, and feedback; only when no project standard exists, use fallback values from the reference rules—do not expand fallback values into a new design system.
• Keep only one authoritative source for the same business data and meaning; prioritize fixing data flow, parent layout, and shared implementations; do not repeatedly patch at usage locations.
• Organize components, Hooks, functions, types, styles, and tests by business ownership; place single-module code nearby; only move to a shared layer when stable cross-module reuse is needed.
• For complex logic, first check existing project capabilities and mature libraries; if the existing dependency is unsuitable, you may introduce a well-maintained, project-compatible new library; do not manually implement core capabilities already covered by mature solutions. For simple logic, implement directly; do not introduce new dependencies for a small amount of code.
• Project history is not proof of correctness; error patterns should be replaced, and after migrating all related usage locations, delete old code, fallbacks, legacy logic, and dead states.

Reference File Reading Order

1. After triggering, first read only this file to clarify the task, object, and scope of changes; do not pre-read reference files.
2. If the task does not involve user-visible UI, frontend state and data flow, component implementation, or frontend code organization, stop using this Skill.
3. First, based on the result the user wants to change, select one primary rule; do not select rules based on file type or CSS/animation keywords appearing in the code.
4. For simple local changes, read only one primary rule; supplement a second rule only if the task simultaneously involves a second independent problem. Only for cross-page comprehensive reviews can you read three rules; never more.
5. Do not continue reading rules due to keyword appearances, links within files, or "just to be safe." When a visual symptom is caused by data, state, or parent layout, read the rule truly responsible for the root cause; do not additionally load a visual rule.

Current Task	Primary Rule	Supplement Only in These Cases
"Looks wrong," visual polish, hierarchy, spacing, typography, colors, border radius, borders, shadows, or icons	Visual Engineering	Read Components & Code Organization when modifying shared tokens, component default styles, or variants; when changing column layout, scrolling, or responsive structure, switch to Viewport & Dialog as the primary rule
Animation, transitions, micro-interactions, expand/collapse, drag feedback, scroll effects, or jank	Motion & Performance	Read Visual Engineering when motion carries action feedback or visual hierarchy; when the root cause is asynchronous state, switch to State & Loading as the primary rule
Module boundaries, components, Hooks, functions, types, style ownership, shared styles, CSS organization, or shared implementations	Components & Code Organization	Read Automation when a new check is needed
Adding or changing copy, action meaning, icons, click feedback, or visual emphasis	Information & Action	Read Resource Recognition when object identity, images, or selectors are involved

Continue selecting based on data, state, and layout by result:

Current Task	Primary Rule	Supplement Only in These Cases
Lists, cards, details, tables, or batch operations	Collection & Detail	Read Resource Recognition when resource identity is involved; read Interaction & Editing when editing is involved
Forms, selection, editing, or multi-step workflows	Interaction & Editing	Read Data & Operation Scope when save scope and flow continuity are involved
Query results, pagination, candidate sets, save scope, batch scope, or request result ownership	Data & Operation Scope	Read State & Loading when simultaneously changing the display of loading, refreshing, empty, error, or processing
Loading, refreshing, empty, filtered-empty, error, queued, processing, or skeleton	State & Loading	Read Data & Operation Scope when simultaneously involving query snapshots, operation scopes, or save result ownership
Changing page size, column layout, scrolling, dialog structure, or responsive behavior	Viewport & Dialog	Read Overlay when overlays triggered by an element (dropdown, menu, tooltip) are involved

The following cases do not trigger additional reading:

• The presence of Tailwind, CSS, transition, or animation libraries in the code does not mean the task is a visual or motion task.
• When changing visible attributes like colors, spacing, borders, shadows, or typography, use Visual Engineering as the primary rule; only supplement the Components & Code Organization rule when the task also requires adjusting style ownership, sharing method, or module boundaries.
• When only fixing color variable names, class names, types, or import errors without changing the visual result, do not read the Visual Engineering rule.
• When only modifying business state, event bindings, or data sources for existing animations without changing motion style or performance, do not read the Motion rule.
• When only moving existing controls without changing copy, action meaning, or feedback, do not read the Information & Action rule.
• When only adjusting ownership of regular parent-child containers without changing size, scrolling, dialog, or responsive behavior, do not read the Viewport & Dialog rule.
• Links in reference files only indicate the location of related rules; they do not mean that reading must continue.

Terminology Quick Reference

Core terms in this file and reference rules should be understood according to these definitions:

• Resource Identity: The minimum combination of information that lets the user recognize "which object this is"—image + name + one distinguishing field. Example: member list shows "avatar + name + department," not "uuid + type label."
• Pseudo-Operation: A control that appears usable but does not produce a real result. Example: clicking "Save" only changes local state, lost on refresh; a permanently disabled Delete button acting as a placeholder.
• Single-Component Visual Patch: Applying styles to only one component at a usage location of a shared component. Example: <Dialog className="h-[640px]">, !important overrides, page-specific selectors modifying component internals. The correct approach is to fix the shared component itself, or add a purpose-named component variant.
• Purpose-Named Component Variant: Named after "why it's different." Example: variant="destructive", size="compact" are acceptable; variant="blue", variant="userListPage" are not.
• Primary Action: The one action that completes the main task on the current page, dialog, or operation area. At most one high-emphasis button in the same area.
• Submission Boundary: When a modification actually takes effect—instant, auto-save, explicit batch submission, or temporary preview only.
• Busy Scope: The smallest area that needs to prevent duplicate operations while a request is in progress. Single-item requests should lock only that item, not use a full-page overlay.
• Submitted Query Snapshot: The query conditions, list, total result count, and pagination information jointly determined by the same response. Before the new query is completed, the old snapshot still belongs to the old conditions.
• Homogeneous Batch Task: A task that repeats filling the same fields for a batch of similar objects, e.g., batch scheduling, batch price changes.
• Editable Worksheet: A table that keeps multiple rows in a continuous editing state for homogeneous batch tasks. Contrast with resource list: shows by default, editing must be explicitly triggered.

Decision Order

Answer sequentially before making changes.

Task and Object:

1. What task is the user currently trying to complete, and what result indicates completion?
2. What core object does the page manage, and to whom do the fields belong?
3. Is the current context browsing, comparing, selecting, or editing? Does it follow the user's familiar structure and terminology?

Data and Scope:

4. Does the data come from a complete collection, the current visible collection, or a search result?
5. What scope do operations, busy state, and submission boundary affect respectively? Do remote query conditions and the current list already belong to the same submitted result?
6. What information does the user rely on to distinguish adjacent objects?
7. Can text, steps, confirmations, duplicate inputs, or fields already known by the system be removed?
8. Which information belongs to the collection, and which belongs only to the detail?

Structure and State:

9. What is the primary action of the current page, dialog, or operation area?
10. Who is responsible for the first screen, scroll container, and overlay boundaries respectively?
11. How do loading, empty, filtered-empty, queued, processing, error, and ready mutually exclude each other?

Visual and Motion – only answer when the task requires changing them:

12. Which tokens, components, and adjacent pages define the current project's hierarchy, density, and motion language? What visible attribute is truly inconsistent?
13. Is the motion for feedback, explaining spatial relationships, or decoration? Can it be accomplished using only transform, opacity, or existing component capabilities?

Placement:

14. Do correctly owned modules, components, Hooks, functions, types, unified design tokens, or styles already exist? Ultimately, which data source, parent layout, or shared implementation should be modified?

When a clear answer cannot be given, stop adding UI elements: ask the user the 1–2 most critical questions; if unable to ask, implement at the minimum verifiable scope and declare the assumptions made in the output.

Execution Flow

1. Reconstruct Facts

• Search for existing modules, components, Hooks, functions, types, unified design tokens, and styles in the project to confirm whether the same meaning already has a correct implementation.
• Identify all pages and components that use the shared component, as well as other entry points for the same data.
• Review requests should only provide evidence and suggestions; implement only when the user requests modifications.

2. Clarify Scope

• Identify the core object, field owners, data collections, operation scope, busy scope, and submission boundary.
• Distinguish between page structure issues, component default behavior, incorrect page usage patterns, and data flow errors.
• For visual problems, only record differences that can point to a specific element, attribute, existing evidence, and code placement; when the correct value cannot be determined, first use existing project tokens or adjacent similar components; do not invent precise values based on aesthetic preference.

3. Delete First

• Delete content that does not affect judgment, duplicate states, duplicate entry points, duplicate confirmations, and visual patches targeting only a single component.
• Delete pseudo-operations that have no real state changes or cannot actually save data.
• Delete old components, old functions, old types, old states, fallbacks, legacy logic, old styles, and dead references that have already been replaced by newer implementations.

4. Choose Structure

• First, check the established usage of similar task pages and shared container components in the project; only follow the existing pattern if it conforms to this specification; otherwise, re-select the structure based on the real task.
• Based on browsing, comparing, selecting, batch configuration, or deep editing tasks, choose a list, table, worksheet, selector, dialog, or full workspace.
• Let the list handle identification and comparison, the detail handle complete content, and the editor handle modifications.
• Handle visual adjustments in the order: "information hierarchy → space and alignment → typography → surface → control state → motion"; stop when the previous layer has solved the problem; do not continue to add decoration.

5. Fix the Truly Incorrect Location

• Prioritize fixing data scope, operation scope, parent layout, shared component default behavior, and semantically stable component variants.
• Use shared components for recurring resource identities, menus, overlays, loading, dialogs, and action bars.
• Abstract only when responsibilities, inputs/outputs, and behavior are stably repeated; do not copy components just because local structures are similar, and do not create universal components with many page-level toggles.
• When existing shared components, functions, styles, or data flows themselves are incorrect, directly fix or replace the truly erroneous shared implementation within the authorized scope, and address all affected usage locations; do not continue adding erroneous implementations to maintain backward compatibility.
• When not all changes can be completed within the current scope, stop expanding the old pattern, clearly report how many old usage locations remain and which ones have been changed this time; do not claim unification.
• When fixing a problem that can be detected repeatedly, judge whether the project actually needs a new lint, test, or check rule; if needed, supplement reading Automation according to the routing table, and count it towards the supplementary rule limit. Do not set up automation for small changes.
• Do not modify unrelated areas.

6. Verify

• Run existing project type checks, Lint, tests, or builds relevant to the changes.
• For simple local changes, only check the modified location, direct behavior, and nearest usage locations; do not expand into a complete state matrix.
• When changes involve shared components, data scope, asynchronous state, form flow, scrolling, responsive behavior, or multiple pages, also check the affected states, data scopes, representative viewports, and all usage locations.
• For visual changes, check real content, main states, and affected viewports; for motion changes, only check applicable interruption, re-trigger, exit, unmount, or scroll behavior by type. Only use performance recording for complex motion or real jank; do not upgrade every transition into a performance exercise.
• Only report verified items, unverified items, and blocking reasons.

Independent Self-Check

Only dispatch an independent self-check without historical context when the frontend review involves multiple pages, all usage locations of shared components, multiple viewports or states, or large-scale rule adjustments. Single page, single component, single screenshot, and local differences should be directly checked by the main Agent.

The independent self-check only receives the check object, scope, and oil-frontend; it does not receive conversation history, existing conclusions, problem guesses, expected answers, or fix proposals.

Output Requirements

Give the conclusion first, then the evidence. Only output:

1. Specific problem;
2. What should be deleted;
3. Correct information, action, and spatial structure;
4. Modules, shared components, or data flows that should be modified;
5. Verified and unverified items.

Prohibit descriptions like "improve experience," "more modern," or "more intuitive" that cannot guide implementation.

Do not proactively expand into an accessibility-specific audit. Continue using native interactive elements when implementing UI; do not break the project's existing focus, keyboard, label, and ARIA behavior; only perform checks when the user explicitly requests it or when the current change directly makes the task impossible to complete.