Skip to content
Skills Library
Programming · Review & audit

headlessui-optimizer

/headlessui-optimizer

Audit and optimize Headless UI (headless React/Vue primitives, @headlessui/react 2.x / @headlessui/vue 1.x) usage in a codebase for Headless UI, @headlessui/react, @headlessui/vue, Dialog/Menu/Listbox/Combobox, Tailwind transitions, bundle/import cost, runtime and re-render cost, theming/SSR, accessibility/forms, copy-in or version drift, with real before/after measurement. Always produces a written findings report and a fix plan for approval before touching code. Use this whenever the user mentions Headless UI, @headlessui/react, @headlessui/vue, Dialog/Menu/Listbox/Combobox, Tailwind transit

Licence
MIT
Last repository change
04.11.2026

Assessment and security

85/ 100Class: good
Format20 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content25 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
8
Scripts
1
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 04.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 1 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: scripts/audit.py

What it does and when to use it

Audit and optimize Headless UI (headless React/Vue primitives, @headlessui/react 2.x / @headlessui/vue 1.x) usage in a codebase for Headless UI, @headlessui/react, @headlessui/vue, Dialog/Menu/Listbox/Combobox, Tailwind transitions, bundle/import cost, runtime and re-render cost, theming/SSR, accessibility/forms, copy-in or version drift, with real before/after measurement. Always produces a written findings report and a fix plan for approval before touching code. Use this whenever the user mentions Headless UI, @headlessui/react, @headlessui/vue, Dialog/Menu/Listbox/Combobox, Tailwind transit

Original author description

Audit and optimize Headless UI (headless React/Vue primitives, @headlessui/react 2.x / @headlessui/vue 1.x) usage in a codebase for Headless UI, @headlessui/react, @headlessui/vue, Dialog/Menu/Listbox/Combobox, Tailwind transitions, bundle/import cost, runtime and re-render cost, theming/SSR, accessibility/forms, copy-in or version drift, with real before/after measurement. Always produces a written findings report and a fix plan for approval before touching code. Use this whenever the user mentions Headless UI, @headlessui/react, @headlessui/vue, Dialog/Menu/Listbox/Combobox, Tailwind transit

How it works

  1. Workflow
  2. Principles
  3. Docs
Original SKILL.md headings · 61 lines, 587 words
SKILL.md preview
---
name: headlessui-optimizer
description: Audit and optimize Headless UI (headless React/Vue primitives, @headlessui/react 2.x / @headlessui/vue 1.x) usage in a codebase for Headless UI, @headlessui/react, @headlessui/vue, Dialog/Menu/Listbox/Combobox, Tailwind transitions, bundle/import cost, runtime and re-render cost, theming/SSR, accessibility/forms, copy-in or version drift, with real before/after measurement. Always produces a written findings report and a fix plan for approval before touching code. Use this whenever the user mentions Headless UI, @headlessui/react, @headlessui/vue, Dialog/Menu/Listbox/Combobox, Tailwind transitions or "optimize my UI" -- even if they never say "audit" or "optimize".
---

# Headless UI Optimizer

Headless UI is a small set of unstyled, accessible React/Vue primitives. Cost is mostly wrong composition (Transition/Dialog parts), missing labels, and using it alongside another primitive base for the same widget. The bundle is small; correctness and a11y are the work.

## Workflow

### 1. Scope (quick)

- Find the app root and detect Headless UI usage: `@headlessui/react 2.x / @headlessui/vue 1.x`. Record the version, framework (React/Next/Vue/Svelte/Solid/Angular or HTML), styling system, and whether the library is a package, a CSS-only kit, or copied source.
- Run `python <skill-dir>/scripts/audit.py <project-root>` -- static scan of `package.json`, config/CSS files and source for version drift, provider/config drift, import and theme issues, a11y gaps, heavy components and upgrade risk, with file:line evidence. Use `--json` to post-process.
- Classify the pain: bundle/import cost, runtime/re-render cost, theming/SSR style flash, accessibility/forms, large tables/lists, or migration/upgrade. Ask which hurts if unclear.
- Read `references/tooling.md` once: what can be measured here.

- Check the React vs Vue package and major, then read the Dialog/Menu/Listbox/Combobox usage. Confirm no Radix/Base UI duplicate.

### 2. Audit

The script finds cheap leads; you find the rest by reading. Read the install/config, the global CSS/theme file, the provider or plugin setup, and the 3-5 most-used components. Load only what applies:

| Area | Reference |
|------|-----------|
| Install, config, provider/plugin, theming, SSR | `references/setup.md` |
| Bundle/imports, runtime, a11y/forms, tables, upgrades | `references/optimizations.md` |
| Measurement and honest reporting | `references/tooling.md` |

**Measure, never guess.** Build for production and measure the real route/bundle. Inspect SSR HTML for style tags and dark-mode flash; run axe/Playwright on dialogs, menus, forms and tables. Component count, bundle bytes and a11y violations are evidence; "feels heavy" is not.

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

### 3. Report

Fill `assets/report-template.md`, save it as `HEADLESS_UI_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 near-duplicates.

### 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** -- trim imports, use path imports, add provider/plugin correctly, add missing labels/titles, move heavy components off the initial route, remove per-row overlays, align theme tokens, add SSR style/cache setup. Low risk.
2. **Structural** -- split component boundaries, virtualize tables, lazy-load heavy widgets, consolidate theming, migrate variants/tokens, fix form composition, deduplicate copied components. Name each behavior change.
3. **Heavy** -- major upgrade, primitive-base change, CSS-only to styled kit (or reverse), Tailwind 3 to 4, copy-in registry extraction, SSR architecture. 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 affected components. A break must trace to one change. Do not mix a major migration with optimization edits. If a change alters a public component API, theme tokens or SSR behavior, stop and ask.

### 6. Verify and wrap up

Re-measure the same routes/components: route JS/CSS, SSR styles/theme, axe violations, dialog/form keyboard flow, table interaction. State plainly what could not be measured. End with deferred items and one suggested next step.

## Principles

- **Compose all parts.** Headless UI behavior depends on the tree.
- **Labels are not optional.** Primitives can't invent content.
- **One primitive base.** Don't mix for one widget.

## Docs

- https://headlessui.com/
Files in this package (8)
  • LICENSE 1 KB
  • README.md 1 KB
  • SKILL.md 5 KB
  • assets/report-template.md 1 KB
  • references/optimizations.md 1 KB
  • references/setup.md 1 KB
  • references/tooling.md 1 KB
  • scripts/audit.py 9 KB

Versions

The database has no other skills named headlessui-optimizer.

Database snapshot: 13.11.2026 · package version 6277728eb0e1 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 85floatui-optimizer
    Audit and optimize Float UI (copy-in Tailwind components, copied Tailwind/React/Vue components) usage in a codebase for Float UI, floatui.com components, copied Tailwind landing sections, Headless UI + Tailwind snippets, bundle/import cost, runtime and re-render cost,…
  • 85flowbite-optimizer
    Audit and optimize Flowbite (Tailwind components + JS / React wrapper, flowbite 4.x / flowbite-react 0.12.x) usage in a codebase for Flowbite, flowbite-react, data-modal-target, Flowbite Tailwind plugin, Flowbite datepicker/dropdown, bundle/import cost, runtime and re-render…
  • 86mobile-headlessui-accessible-overlay
    Use when building accessible mobile menus, dialogs, popovers, disclosure panels, focus management, keyboard behavior, and ARIA state inspired by Headless UI.
  • 90vue-ui
    Build Vue interfaces with component libraries. Reka UI headless primitives (dialog, select, combobox, menu, tabs, popover, the asChild pattern, controlled and uncontrolled state) and Nuxt UI 4 styled components, theming, forms, overlays, data tables and app layouts. Use when…
  • 100guide
    Write, review and debug code that uses x4js, the TypeScript object-component UI framework (`import { ... } from 'x4js'`), and run its `x4js` command line. Use this skill whenever a project depends on x4js, or the user mentions x4js, x4, an x4 component (Component, VBox, HBox,…
  • 100vue-review
    Review Vue and Nuxt code changes. A prioritized checklist for pull requests and diffs touching .vue files, composables, Pinia stores, routes and Nuxt server code, covering correctness, reactivity, SSR safety, security, accessibility, performance and maintainability, with…

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.