ui-modularization-workflow

name

ui-modularization-workflow

description

Reusable workflow for auditing, refactoring, or implementing UI style systems across apps. Use when the user asks to modularize UI, define or review design tokens, check typography or font-size hierarchy, enforce structured CSS, run UI lint/stylelint checks, choose UI quality metrics or mature tooling, control visual style, standardize interaction states, split frontend components/styles, create a UI checklist, or preserve cross-project UI rules.

UI Modularization Workflow

Use this skill to turn UI style and interaction details into a repeatable engineering workflow.

Operating Rules

1. Inspect the live project before prescribing structure. Find the app stack, style entry points, component conventions, token files, test commands, and existing UI abstractions.
2. Preserve local conventions where they are coherent. Introduce a new layer only when it removes real duplication, separates semantics, or gives the project a stable validation boundary.
3. Treat UI style as semantics first, token values second. Do not start by choosing colors; first name the state, role, and component responsibility.
4. Keep visual markers one-to-one with meaning. Do not reuse one marker for unrelated states such as selected, active, current, warning, merge, dirty, or focused.
5. Separate shared interaction shells from business content. Dialog dismissal, keyboard shortcuts, focus management, copy behavior, tooltips, menus, and scroll alignment should live in shared utilities or shell components when more than one surface needs them.
6. Treat lint as a design-system boundary. Discover and run the project's lint, typecheck, stylelint, formatting, and CSS-specific checks where available; do not add broad disables to pass them.
7. Keep typography hierarchical. Font sizes should map to common roles such as display, page title, section title, card title, body, label, caption, code, and control text; avoid arbitrary size jumps and hero-scale type inside dense tools.
8. Keep CSS structured by layer. Separate tokens/theme, base/reset, layout primitives, shared components, feature styles, responsive rules, and narrow overrides instead of accumulating unowned global selectors.
9. Validate the rendered behavior, not only the code shape. For geometry, overlay graphics, desktop windows, sticky headers, and scroll positioning, use browser or app-level checks when feasible.

Workflow

1. Inventory

Locate:

• Style system entry points: global CSS, CSS modules, Tailwind config, theme provider, design-token files, component library setup.
• UI module boundaries: component directories, pure view-model helpers, hooks, shared shells, feature modules.
• Existing state semantics: selected/current/active/focused/loading/empty/error/warning/danger/disabled/dirty.
• Interaction utilities: dismissable layers, keyboard shortcuts, focus traps, copy helpers, scroll helpers, menu/dialog primitives.
• Verification paths: lint, stylelint, formatting, typecheck, unit tests, UI smoke tests, visual checks, Storybook, Playwright, app packaging or desktop-window validation.
• Metrics already tracked: CSS size, unused CSS/JS, specificity, token usage, typography scale, accessibility violations, visual snapshots, bundle size, Lighthouse or Web Vitals.

2. Classify Tokens

Create or review three token layers:

• Foundation tokens: raw primitives such as color scale, spacing, radius, type, shadow, z-index, motion, opacity, hit area, row height, panel width.
• Semantic tokens: app-facing meanings such as surface, text, border, type roles, selected, current, focus, danger, warning, success, muted, disabled.
• Component tokens: stable component contracts such as dialog width, sidebar width, row height, graph rail width, toolbar height, node size.

Components should usually consume semantic or component tokens, not raw foundation values. Raw values belong in token/theme files and narrow one-off exceptions.

3. Modularize UI

Prefer this split when the project does not already have a stronger convention:

• lib/*View or equivalent: pure functions that derive labels, disabled states, classes, copy, and structural view models.
• components/*: rendering, DOM structure, accessibility wiring, and event handoff.
• hooks/* or interaction utilities: shared behavior such as dismissal, shortcuts, focus, copy, scroll, drag, resize.
• styles/*: structured CSS layers for tokens, themes, base controls, layout primitives, component styles, feature styles, responsive rules, and explicit overrides.

Do not move code just to match this shape. Use it when a component is mixing semantic decisions, rendering, and low-level interaction details in a way that blocks reuse or testing.

4. Audit Semantics

Check each important state:

• What business or product meaning does it represent?
• Is the meaning visible at the right scope?
• Is the same visual marker reused for another meaning?
• Does the label/copy describe observable state instead of vague readiness?
• Is the state owned by the right source of truth?

When two meanings differ, split the data fields and the visual treatment even if the old UI used one combined class.

5. Audit Interactions

For dialogs, popovers, menus, and floating panels, verify:

• Escape closes when expected.
• Outside click closes only from the backdrop or dismissable boundary.
• Inside click does not accidentally close.
• Focus behavior is predictable.
• First click works in desktop floating windows.
• Copy actions have success and failure states.
• Keyboard shortcuts focus the intended control.

For lists and visual overlays, verify:

• Fixed-format elements have stable dimensions through tokens.
• Selected items can be scrolled to the requested alignment, not merely made visible.
• Sticky controls stay reachable during long-list scrolling.
• Canvas/SVG/DOM overlays align using shared geometry constants.

6. Select Metrics

Use metrics to catch drift, not to replace judgment. Prefer existing project gates first. Add new tools only when they create a repeatable signal for CSS structure, token discipline, accessibility, visual regression, performance, or bundle size.

For mature tool options and candidate thresholds, read references/ui-metrics-tools.md when the task asks for quality gates, technical indicators, CI checks, or tool recommendations.

7. Plan and Implement

For implementation tasks:

1. State the current structure and the target structure.
2. Make the smallest coherent boundary change first.
3. Move duplicated interaction logic into shared utilities or shell components.
4. Replace naked values in components with semantic or component tokens.
5. Normalize font sizes into role-based typography tokens before adding one-off component sizes.
6. Put CSS in the correct layer before adding new selectors. Prefer local component or feature styles over broad global selectors unless the rule is truly foundational.
7. Add focused tests for pure view logic and shared interactions.
8. Run the repo's relevant lint/typecheck/stylelint/test command and any rendered checks needed for geometry or desktop behavior.

For review tasks, lead with bugs, semantic conflicts, missing token boundaries, interaction regressions, and test gaps. Use file and line references when possible.

Detailed Checklist

For a fuller checklist, read references/ui-system-checklist.md when performing a real audit, refactor, or implementation.