home / skills / velcrafting / codex-skills / ui-refactor-extract

ui-refactor-extract skill

safe

This skill refactors UI code to improve maintainability by extracting subcomponents and reorganizing structure without changing public APIs, with evidence via

npx playbooks add skill velcrafting/codex-skills --skill ui-refactor-extract

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

2.4 KB

---
name: ui-refactor-extract
description: Refactor UI code without behavior change (extract/rename/reorganize) while preserving public APIs and adding evidence via tests or inspection.
metadata:
  short-description: UI refactor, no behavior change
  layer: frontend
  mode: write
  idempotent: false
---

# Skill: frontend/ui-refactor-extract

## Purpose
Improve UI maintainability without changing behavior by:
- extracting subcomponents
- renaming for clarity
- reorganizing file structure within existing conventions
- reducing component complexity (“god component” prevention)

Behavior must remain stable. This skill requires evidence.

---

## Inputs
- Target component(s)/route(s)
- Refactor intent (why, what pain)
- Public API constraints (props, exports, routes)
- Repo conventions (from `REPO_PROFILE.json` if present)

---

## Outputs
- Refactored UI modules with smaller components
- Updated imports/exports as needed
- Evidence of no behavior change:
  - tests updated/added OR
  - deterministic before/after inspection notes if tests are unavailable

---

## Non-goals
- Adding new features
- Visual redesign
- Changing data contracts
- Sweeping refactors outside the touched surface

---

## Workflow
1) Identify the smallest extraction that reduces complexity meaningfully.
2) Preserve public APIs:
   - keep existing props stable unless explicitly requested
   - keep exports stable or update all call sites
3) Extract subcomponents:
   - prefer pure, presentational components
   - pass minimal props
4) Keep behavior stable:
   - no logic changes unless required for extraction correctness
5) Add/adjust tests:
   - ensure at least one test asserts expected render/interaction
6) Run validations from profile.

---

## Checks
- No behavior change intended or introduced
- Public API compatibility preserved (props/exports/import paths)
- Typecheck/lint/tests pass if configured
- Component complexity reduced (clearer boundaries, fewer responsibilities)

---

## Failure modes
- Refactor drifts into feature work → stop and propose separate skill invocation.
- Extraction reveals hidden state coupling → recommend `frontend/state-modeling`.
- Tests unavailable → provide deterministic inspection steps and keep diff minimal.

---

## Telemetry
Log:
- skill: `frontend/ui-refactor-extract`
- refactor_type: `extract | rename | reorganize`
- evidence: `tests | inspection`
- files_touched
- outcome: `success | partial | blocked`

Overview

This skill extracts, renames, and reorganizes UI components to improve maintainability without changing runtime behavior or public APIs. I focus on small, safe refactors that reduce component complexity and create clearer module boundaries. All work is accompanied by evidence that behavior is unchanged via tests or deterministic inspection notes.

How this skill works

I inspect the target component and repo conventions to identify the smallest meaningful extraction that reduces cognitive load. I extract presentational subcomponents, update imports/exports as required, and preserve existing props and public routes unless an explicit API change is requested. After refactor, I provide evidence of no behavior change by updating or adding tests, or by producing deterministic before/after inspection steps when tests are not available.

When to use it

A large component has multiple responsibilities or is hard to reason about.
You want clearer file/module boundaries without changing public props or routes.
You need to rename or relocate files for clarity while preserving imports.
You want to reduce a ‘god component’ by extracting presentational pieces.
You require refactor evidence for code reviews or audits.

Best practices

Extract the smallest unit that meaningfully reduces complexity.
Favor pure, presentational components that accept minimal props.
Preserve public APIs; if you must change them, update all call sites and document the change.
Add or update at least one test that asserts render or interaction equivalence.
Run repo linters, typechecks, and test suite before and after the change.
If hidden state coupling appears, stop and recommend a dedicated state-modeling refactor.

Example use cases

Split a dashboard component into Header, Filters, and List subcomponents while keeping the same external props.
Rename a confusingly named component file and update import paths across the codebase without altering exports.
Move shared presentational pieces into a new subfolder structure to match repo conventions.
Extract a form subcomponent to simplify the parent and add a snapshot/unit test to prove unchanged rendering.
Reorganize route component files to align with a deterministic hierarchy defined in the repo profile.

FAQ

What counts as acceptable evidence if there are no tests?

I provide deterministic inspection notes: component prop/DOM snapshots, a list of rendered outputs for representative inputs, and a checklist showing no API changes; this keeps diffs minimal and reviewable.

Will you change public props during extraction?

No — I preserve public props by default. If a prop change is required, I update all call sites and document the change, but that should be requested explicitly.