UI Components Optimizer

Audit the component-library layer of a web app, report what is slow, inaccessible or fragile and why, agree a plan, then fix it. Order: evidence, approval, edits. UI kits decide a large share of bundle size, SSR styling, accessibility and upgrade risk, but changing providers, imports or component APIs can alter behavior and appearance, so nothing is edited before approval.

Workflow

1. Scope (quick)

• Find the app root (package.json). Record: framework (React/Next, Vue/Nuxt, Svelte/SvelteKit, Solid/SolidStart, Angular, Lit/Web Components), UI library (or libraries) and version, styling approach (runtime CSS-in-JS, CSS modules, Tailwind, plain CSS, web components), SSR/RSC mode, and whether components are dependency-based, headless, copy-in (shadcn-style) or CSS-only.
• Run python <skill-dir>/scripts/audit.py <project-root> -- static scan of package.json, config, components/pages and styles for library/version issues, whole-library imports, runtime styling, SSR provider gaps, accessibility mistakes and large-list patterns, with file:line evidence. Use --json to post-process.
• Classify the pain: bundle/load, runtime style/SSR flash, accessibility/forms, large tables/lists, visual inconsistency, or upgrade risk. Ask which hurts if unclear.
• Read references/tooling.md once: what can be measured here (bundle analyzer, framework profiler, SSR HTML, axe, Storybook).

2. Audit

The script finds cheap leads; you find the rest by reading. Read package.json, the root provider/layout, the 3-5 screens with the most UI, and the component wrappers/design-system layer. Load only what applies:

For a single library, use the matching focused optimizer in skills/: Aceternity UI, Base UI, Bulma, coss ui, Create UI, DaisyUI, Float UI, Flowbite, Franken UI, Headless UI, HeroUI, Mantine, MUI, Park UI, Preline UI, Radix UI, ReUI, shadcn, TailGrids, tweakcn or Untitled UI. Use this generic guide when comparing libraries or when no per-library skill matches.

Measure, never guess. Build for production and measure the real bundle/route; inspect SSR HTML for style tags and dark-mode flash; run axe/Playwright on the UI states that matter. Component count, bundle bytes and a11y violations are evidence; "feels heavy" is not.

Per-stack guides live in stacks/: react, vue, svelte, solid, angular, web-components, css-only. Read the one matching the project before applying generic advice.

Mark each finding Confirmed (build/analyzer/axe/code evidence) or Suspected (needs measuring).

3. Report

Fill assets/report-template.md, save it as UI_COMPONENTS_OPTIMIZATION_REPORT.md in the project root, and show the user. Five-line summary, findings table by impact/effort, then per-finding detail (evidence, why it hurts, fix, risk, visual/behavior impact). Group related findings.

4. Plan -- then stop for approval

Use plan mode: EnterPlanMode (load with ToolSearch if deferred), write the plan, present with ExitPlanMode; if unavailable show it in chat and wait for an explicit "go". Structure:

1. Quick wins -- per-component imports, drop duplicate icon/UI libs, lazy-load heavy widgets, fix missing alt/labels/keys, replace index keys, add SSR provider/cache, preload the theme script, remove unused kit CSS. Low risk.
2. Structural -- one styled kit, headless primitive layer, virtualize large tables/lists, split provider boundaries, replace runtime CSS-in-JS with CSS modules/Tailwind where measured, consolidate design tokens/wrappers. Name each visual/behavior change.
3. Heavy -- major-version upgrades (MUI 9, Chakra 3, Mantine 9, AntD 6, HeroUI 3, Vuetify 4, PrimeVue 5, Nuxt UI 4, Angular Material 22), library swap, headless/rebuild design system. Separately approved. Each step: files touched, expected effect, how to verify, how to roll back.

5. Fix

Only approved items, in small groups. After each: typecheck, lint, tests, production build, and a visual/axe check on the affected screens. A break must trace to one change. Do not mix a library major upgrade with optimization edits. If a change alters public component APIs, theme tokens or SSR output, stop and ask.

6. Verify and wrap up

Re-measure the same routes and states: route JS (raw/gzip), CSS bytes, SSR style/flash behavior, axe violations, table/list interaction cost, LCP/INP/CLS. State plainly what could not be measured. End with deferred items and one suggested next step.

Principles

• One styled kit, one primitive layer. Mixing MUI + Chakra + Ant Design (or two headless layers) multiplies bundle, theming and a11y surface.
• Imports decide the bundle. Namespace imports, barrel files and every-icon imports can ship the whole library; use per-component paths and package-import optimization.
• Runtime CSS-in-JS is a tax. Emotion/styled-components need SSR caches and client style work; measure before choosing, and prefer CSS modules/Tailwind for new work when it fits.
• SSR needs a provider and a cache. MUI/Chakra/AntD/Mantine/HeroUI each have a server story; missing it means style flash, hydration mismatches or client-only pages.
• Accessibility is part of the component contract. Prefer the kit's accessible primitives; don't rebuild dialogs/menus with divs and click handlers.
• Large lists need virtualization. Tooltips, menus and dialogs per row are the usual performance cliff.
• Tokens before overrides. Theme tokens/CSS variables beat per-screen overrides and survive upgrades better.
• Migrations are their own plan item. A UI major changes APIs, tokens and styling; never bundle it with performance edits.
• Hand off framework internals. React re-renders, Next caching, Vue/Nuxt reactivity, Svelte runes, Solid signals: use the matching optimizer; this skill owns the kit layer.