version: "1.0.0" name: frontend-ui-refinement description: Refine existing web interfaces and simplify their behavioral tests. Use for layout, theme, floating layers, scrolling, loading or feedback inconsistencies, editor state or draft loss across view switches, and pruning redundant UI tests. Follow the approved reference or established design system. Not for greenfield design, full redesigns, backend-only logic, or directory restructuring.

Frontend UI Refinement

Improve the requested interface within its existing visual language. Prefer removing conflicting styles, duplicate state, and unnecessary UI over adding another layer of customization.

For test-only cleanup, inspect existing scenarios and the behavior they protect; use the verification guidance below without redesigning the interface.

Ground the Change

For interface work, inspect the user's reference, affected components, neighboring examples, and shared tokens. Confirm the visible problem in the relevant state when a browser is available. Separate an observed mismatch from an inferred cause.

Identify the styles or state that own the behavior before editing. A local hover issue rarely needs a global redesign; a shared token error may need a shared fix. Ask only when missing intent would materially change the result.

Use the existing primitives, icons, and styling approach. Do not introduce a design system, animation dependency, cache framework, or directory migration for a small refinement.

Keep the Visual Contract Coherent

Resolve the owning rule and remove superseded overrides within the affected scope. Avoid accumulating higher-specificity selectors or copying shared token values into individual pages. Keep dimensions and colors derived from the project rather than importing a universal recipe.

Follow State Through the Interaction

Inspect only the states relevant to the change: first paint, loading, ready, empty, error, reconnect, or unsaved content. Preserve the requested experience while keeping data semantics accurate.

• Keep loading feedback in the region being loaded. Background refresh should usually retain useful content rather than reset the whole layout.
• When tab switching loses content or repeats requests, trace component lifetime and state ownership first. Reuse existing successful data or in-flight work with appropriate invalidation and failure recovery; do not add caching solely to hide a loading indicator.
• Related editor views should operate on the same draft. Preserve incomplete input and failed-save content, and distinguish navigation within an editor from leaving it.
• Keep presentation fallbacks separate from actual data. A missing metric may have an approved display fallback without becoming a real measurement.
• When behavior crosses an API or persistence boundary, verify the result at that boundary. A cleared local view alone does not establish that saved data was removed.

Verify with Minimal Maintenance

For spacing, colors, borders, icon placement, or removal of decorative motion, default to browser inspection and the relevant existing checks. Do not add a test file, snapshot, or fixture framework for a purely visual edit.

Inspect existing coverage for behavior the change could affect, including behavior that must remain unchanged during a refactor. Extend the smallest useful scenario, and add a test only when it protects an important gap. Prefer user actions and outcomes over component internals; one owner should normally carry a given assertion rather than repeating it in helper, component, page, and end-to-end suites.

When simplifying tests:

• Remove redundant default-value checks, decorative class or pixel assertions, incidental wording, and checks that reproduce implementation logic or retest an unmodified library.
• Keep meaningful contracts such as draft preservation, valid save payloads, numeric precision, authorization, and persistence. A class such as the theme's dark marker may itself be a contract; judge its purpose rather than the matcher name.
• Preserve waits for actual readiness, event synchronization, isolation, and cleanup. Do not fix a slow test merely by increasing timeouts or remove synchronization to make it shorter.
• Reuse existing fixtures and public entry points. Avoid production abstractions or exposed private APIs added solely to make tests convenient.
• Keep distinct failure modes independently diagnosable; reducing files must not produce one large test that mixes unrelated scenarios.

For visual or interaction changes, inspect the affected UI in representative themes, viewport sizes, and interaction states. Observe first paint, scrolling, or transient feedback as a sequence when those are the issue. DOM assertions cannot establish visual quality.

Run focused existing checks, expanding for shared changes, failures, or repository requirements. Once the relevant checks pass, repeat only for a new change or unresolved concern. Report the observed result and checks performed; if the browser or real backend was unavailable, state that limit without claiming visual or persistence verification.