# UseClassy

Readable utility CSS. No horizontal scroll.

A Vite plugin (`vite-plugin-useclassy`) that turns variant attributes (`class:hover`, `className:focus`, `class:sm:hover`) into normal Tailwind CSS and UnoCSS classes. No runtime. Place it before your CSS engine.

Use it when writing or refactoring Vue, React, Svelte, Blade, or HTML that uses Tailwind/UnoCSS hover, focus, responsive, dark, or group variants.

- Website: https://useclassy.com/
- Docs: https://useclassy.com/docs.md
- Agent skill: https://useclassy.com/skill.md
- GitHub: https://github.com/jrmybtlr/useclassy

## Quick start

```bash
npm i -D vite-plugin-useclassy
npx vite-plugin-useclassy init
```

`init` patches Vite and your CSS engine, and installs agent skills by default so coding agents keep writing `class:hover` instead of `hover:` prefixes. Pass `--no-skills` to skip agent files.

See the [docs](https://useclassy.com/docs.md) for Usage, Vite, Tailwind, UnoCSS, IntelliSense, and the agent skill.

---

# 🎩 UseClassy

A Vite plugin that automatically rewrites conditional class attributes like `class:hover` or `class:focus` into standard utility classes usable by Tailwind CSS and UnoCSS. UseClassy lets you write cleaner, more maintainable variant styles in your HTML, Vue, React, Blade, and Svelte code, with no runtime overhead.

```html
<button
  class="@container rounded px-4 bg-blue-600 text-white"
  class:hover="bg-blue-700"
  class:focus="ring-2 ring-blue-300"
  class:@md="px-6"
></button>
```

becomes `class="@container rounded px-4 bg-blue-600 text-white hover:bg-blue-700 focus:ring-2 focus:ring-blue-300 @md:px-6"`. There is no runtime. Put UseClassy before Tailwind or UnoCSS so those engines see the rewritten utilities.

## Install

```bash
npm i -D vite-plugin-useclassy
npx vite-plugin-useclassy init
```

`init` patches Vite and your CSS engine, plus VS Code IntelliSense for Tailwind. Run it from the app root (the folder with `package.json` and `vite.config.*`).

| Option           | Default      | Notes                                                                              |
| ---------------- | ------------ | ---------------------------------------------------------------------------------- |
| `--language`     | `'vue'`      | `'vue'` \| `'react'` \| `'blade'` \| `'svelte'`                                    |
| `--engine`       | auto-detect  | `'tailwind'` \| `'unocss'`; Tailwind wins if both are installed                    |
| `--with-skills`  | `true`       | Agent skill, Cursor rules, and `AGENTS.md` (default on)                            |
| `--no-skills`    | —            | Skip agent skill / Cursor rules / `AGENTS.md`                                      |
| `--with-claude`  | `false`      | Also copy to `.claude/skills/` (incompatible with `--no-skills`)                   |
| `--force`        | `false`      | Overwrite locally edited skill files                                               |
| `--dry-run`      | `false`      | Print planned edits                                                                |

If detection fails, follow the [manual setup](#vite) below.

## Usage

**Vue / HTML.** Use `class` plus `class:modifier`:

```vue
<button
  class="px-4 py-2 rounded bg-blue-600 text-white"
  class:hover="bg-blue-700 scale-105"
  class:focus="ring-2 ring-blue-300"
  class:disabled="opacity-50 cursor-not-allowed"
  class:dark="bg-sky-700"
/>
```

**React.** Use `className` and `className:hover`. JSX expressions work when the class tokens are string literals:

```tsx
<button
  className="px-4 py-2 rounded"
  className:hover={isActive ? 'bg-blue-500 text-white' : 'bg-gray-200'}
  className:@md="px-6"
  className:group-hover/item="bg-red-500"
  className:[&>*]="mt-2"
  className:data-[state=open]="block"
/>
```

Expressions with no string literals (`className:hover={hoverClasses}`) are left alone. Import types with `import 'vite-plugin-useclassy/react'` (or `ClassyProps`). React 18/19 is an optional peer, only needed for those helpers.

Quoted modifier values may use `"` or `'`. Prefer `"` in docs and new code.

`className:@md`, `className:group-hover/item`, and arbitrary variants like `className:[&>*]` / `className:data-[state=open]` use the same attribute spelling as Vue. UseClassy rewrites them before the JSX/HTML parser runs (bracket-aware so `=` inside `[…]` stays part of the name). Put UseClassy before `@vitejs/plugin-react`.

For editor TypeScript diagnostics, add the language plugin (React `init` does this automatically):

```json
{
  "compilerOptions": {
    "plugins": [{ "name": "vite-plugin-useclassy/typescript-plugin" }]
  }
}
```

If your app uses Vite’s split config (`tsconfig.json` with `"files": []` referencing `tsconfig.app.json`), make the root config extend the app config instead — otherwise tsserver stops at the empty file list and never loads the plugin:

```json
{
  "extends": "./tsconfig.app.json",
  "references": [{ "path": "./tsconfig.node.json" }]
}
```

Keep `build` on `tsc -p tsconfig.node.json && vite build` so CLI `tsc` does not parse modifier attrs without the plugin.

Use the workspace TypeScript version in VS Code/Cursor (`js/ts.tsdk.path`: `node_modules/typescript/lib`, `js/ts.tsserver.useSyntaxServer`: `never`, enable “Use Workspace Version”). Oxlint and ESLint still parse source text directly, so keep smoke-demo `App.tsx` files ignored unless you add a separate ESLint preprocessor.

The TypeScript plugin only affects diagnostics. For syntax highlighting of `className:@md`, `className:group-hover/item`, and arbitrary variants, sideload the UseClassy editor extension from this repo (`code --install-extension ./vscode-useclassy`, or copy to `~/.cursor/extensions/useclassy.useclassy-0.1.0`), then reload — see [vscode-useclassy/README.md](vscode-useclassy/README.md). It is not on the Marketplace yet.

**Svelte.** Quoted modifiers transform; native directives do not. Put UseClassy before `@sveltejs/vite-plugin-svelte`.

```svelte
<button class="px-4 py-2 rounded" class:hover="bg-blue-700" class:active={isActive}>
```

**Laravel Blade.** `composer require useclassy/laravel`, then `language: "blade"`. PHP ^8.2, Laravel ^11–13. Blade files sit outside Vite’s module graph, so keep the class manifest registered with Tailwind or UnoCSS (below).

### Chained modifiers

`class:sm:hover="underline"` emits `sm:hover:underline` only, the same composition as Tailwind / UnoCSS, not the individual `sm:` and `hover:` pieces.

Modifier names may include letters, digits, `_`, `-`, `:`, `/` (`group-hover/item`), `@` (`@md`), and arbitrary variants with `[…]` (`[&>*]`, `data-[state=open]`). UseClassy parses modifier names with bracket depth so an `=` inside `[…]` is not treated as the attribute separator. React uses the same modifier attributes as Vue; UseClassy rewrites them before JSX/HTML parse.

## Vite

```ts
import useClassy from 'vite-plugin-useclassy'

export default {
  plugins: [
    useClassy({
      language: 'vue', // 'react' | 'blade' | 'svelte'
      // engine: "unocss",
    }),
    // Tailwind / UnoCSS after UseClassy
  ],
}
```

| Option                         | Default                          | Notes                                                            |
| ------------------------------ | -------------------------------- | ---------------------------------------------------------------- |
| `language`                     | `'vue'`                          | `'vue'` \| `'react'` \| `'blade'` \| `'svelte'`                  |
| `engine`                       | `'tailwind'`                     | `'unocss'` skips Tailwind `@source` inject                       |
| `outputDir` / `outputFileName` | `.classy` / `output.classy.html` | Class manifest Tailwind and Uno scan                             |
| `manifestRoot`                 | Vite `root`                      | Set when Vite’s root is a subfolder (e.g. Nuxt `srcDir: "app/"`) |
| `injectTailwindSource`         | `true`                           | Tailwind v4 only; ignored for UnoCSS                             |
| `debug`                        | `false`                          | Log transform and manifest writes                                |

Processes `.vue`, `.svelte`, `.ts`, `.tsx`, `.js`, `.jsx`, `.html`, and `.blade.php`. Skips `node_modules`, gitignored paths, and virtual modules.

## Tailwind

UseClassy writes discovered utilities to `.classy/output.classy.html` (gitignored). Tailwind v4 does not scan gitignored files unless you `@source` them. The plugin injects that directive into stylesheets that `@import "tailwindcss"`. `init` also writes it into your CSS.

```css
@import 'tailwindcss';
@source "./.classy/output.classy.html";
```

`@source` paths are relative to the CSS file. If the stylesheet lives in `src/`, use `../.classy/output.classy.html`.

**Tailwind v3.** Add the manifest to `content`:

```js
content: ["./.classy/output.classy.html"],
```

Path helpers: `getUseClassyTailwindSourceDirective`, `getUseClassyTailwindV3ContentEntry` from `vite-plugin-useclassy` or `vite-plugin-useclassy/tailwind`. Pass the same `outputDir` / `outputFileName` you use in the plugin.

## UnoCSS

```ts
useClassy({ language: 'react', engine: 'unocss' })
```

Place it before `unocss/vite`. After the rewrite, Uno’s Vite pipeline already sees `hover:` classes. Register the HTML manifest as a filesystem source for files Uno does not extract (plain `.ts` / `.js`, Blade, HTML that never enter Vite):

```ts
import { defineConfig, presetUno } from 'unocss'
import { getUseClassyUnoFilesystemEntry } from 'vite-plugin-useclassy/unocss'

export default defineConfig({
  presets: [presetUno()],
  content: { filesystem: [getUseClassyUnoFilesystemEntry()] },
})
```

UseClassy is variant-first (`class:hover="bg-red"`), not [Attributify](https://unocss.dev/presets/attributify) (`bg="hover:..."`). Don’t enable both on the same attributes. See `demos/unocss-react`.

## IntelliSense

`init` merges this into `.vscode/settings.json` for Tailwind projects:

```json
{
  "tailwindCSS.classAttributes": [
    "class",
    "class:[\\w:/@\\[\\]\\-=&*>.]*",
    "className",
    "className:[\\w:/@\\[\\]\\-=&*>.]*"
  ]
}
```

Vue-only projects can omit the `className` entries. UnoCSS projects should use the [UnoCSS VS Code extension](https://unocss.dev/integrations/vscode) instead.

## Agent skill

`init` installs agent resources by default so coding agents discover UseClassy syntax:

```bash
npx vite-plugin-useclassy init
# skip agent files: npx vite-plugin-useclassy init --no-skills
```

| Path                              | Used by                            |
| --------------------------------- | ---------------------------------- |
| `.agents/skills/useclassy/`       | Cursor, Codex, Copilot             |
| `.cursor/rules/useclassy-*.mdc`   | Cursor (includes an always-on tip) |
| `AGENTS.md` (fenced block)        | Windsurf, Aider, Cline, and others |

Add `--with-claude` to also copy into `.claude/skills/` (opt-in so Cursor doesn’t load the skill twice). Running it again is safe; `--force` overwrites local edits. Templates live in [`templates/`](templates/).

## For AI assistants

Machine-readable docs for crawlers and coding agents:

| URL | Purpose |
| --- | --- |
| https://useclassy.com/llms.txt | LLM index (start here) |
| https://useclassy.com/llms-full.txt | Full docs + agent skill in one file |
| https://useclassy.com/skill.md | Authoring / refactoring skill |
| https://useclassy.com/docs.md | Complete README as markdown |
| https://useclassy.com/.well-known/llms.txt | Alternate llms.txt discovery path |

When editing a UseClassy project, prefer `class:hover` / `className:focus` over inline `hover:` / `focus:` prefixes. `npx vite-plugin-useclassy init` installs local agent skills by default.

### Context7

[`context7.json`](context7.json) tells [Context7](https://context7.com) how to index this repo for MCP-powered coding agents.

**CI sync:** [`.github/workflows/context7-refresh.yml`](.github/workflows/context7-refresh.yml) runs on every `main` push. It refreshes the library when it already exists, and auto-submits the GitHub repo (+ `llms.txt`) on first run if Context7 returns 404.

Setup:

1. Create an API key at [context7.com/dashboard](https://context7.com/dashboard)
2. Add repo secret `CONTEXT7_API_KEY`
3. Merge to `main` (or run the workflow manually). First successful run submits; later runs only refresh.

Optional: claim the library in the Context7 UI so refresh limits and settings stay under your account. Root markdown and `templates/useclassy-skill/` are the primary sources; demos and build artifacts are excluded via `context7.json`.

## Contributing

Issues and PRs welcome.

## License

MIT

---

# Agent skill

---
name: useclassy
description: >-
  Write and refactor Vue, React, Svelte, Blade, and HTML with vite-plugin-useclassy
  (UseClassy) modifier attributes: class:hover, class:focus, class:sm, class:md,
  class:dark, className:hover, className:focus, class:sm:hover, and similar.
  Use when authoring UI, writing Tailwind or UnoCSS hover/focus/responsive/dark
  variants, converting hover: focus: sm: md: prefixes into UseClassy attributes,
  refactoring className variant tokens, or reviewing and fixing UseClassy markup.
---

# Authoring with UseClassy

Use UseClassy to separate Tailwind variants from base utilities:

```html
<!-- Before -->
<button class="rounded px-4 hover:bg-blue-500 hover:text-white focus:ring-2">

<!-- After -->
<button
  class="rounded px-4"
  class:hover="bg-blue-500 text-white"
  class:focus="ring-2"
>
```

## Syntax

| Language    | Base            | Modifiers                                                               |
| ----------- | --------------- | ----------------------------------------------------------------------- |
| Vue / Blade | `class="…"`     | `class:hover="…"`, `class:sm:hover="…"`                                 |
| React       | `className="…"` | `className:hover="…"`, `className:@md="…"`, `className:group-hover/item="…"`, `className:[&>*]="…"`, `className:data-[state=open]="…"`; JSX expressions allowed |
| Svelte      | `class="…"`     | Quoted only: `class:hover="…"`                                          |

Modifier names may contain letters, numbers, `_`, `-`, `:`, `/` (named groups such as `group-hover/item`), `@` (container queries such as `@md`), and arbitrary variants with `[…]` (`[&>*]`, `data-[state=open]`). UseClassy parses modifier names with bracket depth so `=` inside `[…]` is not the attribute separator. React uses the same modifier attributes as Vue; UseClassy rewrites them before JSX/HTML parse.

- **Vue / Blade / Svelte / HTML:** modifier values must be quoted static class strings (`"` or `'`).
- **React:** prefer quoted static strings (`"` or `'`). JSX expressions are also supported when string literals inside the expression should receive the variant prefix, e.g. `className:hover={on ? 'bg-blue-500' : 'bg-gray-200'}`.

## Refactor existing code

When asked to convert markup to UseClassy:

1. Identify the framework from the file/config; use `className:` for React and `class:` elsewhere.
2. Inspect each **static** `class` / `className` string.
3. Keep unprefixed utilities in the base attribute.
4. Group utilities that share the same modifier prefix and remove that prefix:
   - `hover:bg-blue-500 hover:text-white` → `class:hover="bg-blue-500 text-white"`
   - `focus:ring-2 focus:ring-blue-400` → `class:focus="ring-2 ring-blue-400"`
   - `md:px-6 md:py-3` → `class:md="px-6 py-3"`
   - `sm:hover:underline` → `class:sm:hover="underline"`
5. Preserve utility order within each group and preserve unrelated attributes/expressions.

Convert only static tokens that can be represented safely. Do not rewrite:

- Dynamic expressions, template interpolations, conditional class helpers, Vue `:class`, or Svelte directives — unless you are intentionally using React's `className:mod={…}` expression form with string literals.
- Variant tokens embedded in variables or function calls (leave those variables unchanged, or store already-prefixed class names).

## Chained modifiers

`class:sm:hover="underline"` produces `sm:hover:underline` only — the same composition as Tailwind and UnoCSS. Converting `sm:hover:underline` on a base class to `class:sm:hover="underline"` is behavior-preserving.

```html
class:sm:hover="underline"
<!-- produces sm:hover:underline -->
```

## Framework rules

- Put base utilities on `class` / `className`.
- Vue / Blade / HTML: use `class:modifier="…"`.
- React: prefer `className:modifier="…"` for static variants, including `className:@md`, `className:group-hover/item`, `className:[&>*]`, and `className:data-[state=open]` (UseClassy rewrites before JSX parse). For runtime conditions that still use string literals, `className:modifier={cond ? 'a' : 'b'}` is valid and will prefix those literals. Leave `className={…}` base expressions unchanged when they are unrelated.
- React editor setup: add `compilerOptions.plugins: [{ "name": "vite-plugin-useclassy/typescript-plugin" }]`, extend `tsconfig.app.json` from `tsconfig.json`, set `js/ts.experimental.useTsgo` to `false`, `js/ts.tsserver.useSyntaxServer` to `never`, and select the workspace TypeScript version in VS Code/Cursor. Oxlint/ESLint still parse source text and may need file ignores on smoke demos.
- Vue: leave `:class` and other dynamic bindings unchanged.
- **Svelte**: only transform quoted UseClassy modifiers. Native `class:active={cond}` and `class:active` stay untouched — do not rewrite those.
- Do not move conditional base utilities into modifier attributes on Vue/Svelte/Blade; UseClassy modifiers represent Tailwind variants. React is the exception for `className:mod={…}` expression values.

## Verification

After a refactor:

1. Confirm every moved utility lost exactly the modifier encoded in its attribute name.
2. Confirm base and dynamic classes remain intact.
3. Confirm Svelte native directives remain expressions/directives.
4. Run the project’s formatter, typecheck, and relevant tests/build.

## More examples

See [examples.md](examples.md).

---

# Skill examples

# UseClassy refactoring examples

## Vue: group static variants

```html
<!-- Before -->
<div
  class="rounded-lg p-4 bg-white hover:shadow-lg sm:p-6 dark:bg-zinc-900 dark:text-zinc-100"
  :class="{ active: isActive }"
>

<!-- After -->
<div
  class="rounded-lg p-4 bg-white"
  class:hover="shadow-lg"
  class:sm="p-6"
  class:dark="bg-zinc-900 text-zinc-100"
  :class="{ active: isActive }"
>
```

Chained variants move onto a matching chained attribute:

```html
<div
  class="rounded-lg"
  class:hover="shadow-lg"
  class:sm="p-6"
  class:sm:hover="shadow-xl"
>
```

Do not alter Vue dynamic bindings:

```html
<div
  class="base"
  :class="{ active: isActive }"
  class:hover="opacity-90"
>
```

## React: static variants and conditional modifiers

```tsx
// Before
<button
  className={`rounded px-4 hover:bg-blue-600 focus:ring-2 ${active ? 'font-bold' : ''}`}
>
  Save
</button>

// After: move safely separable static variants; keep unrelated base expressions.
<button
  className={`rounded px-4 ${active ? 'font-bold' : ''}`}
  className:hover="bg-blue-600"
  className:focus="ring-2"
>
  Save
</button>
```

React also supports JSX expressions on modifiers when the class strings are literals:

```tsx
<button
  className="rounded px-4"
  className:hover={isActive ? 'bg-blue-500 text-white' : 'bg-gray-200'}
  className:disabled={isDisabled && 'opacity-50 cursor-not-allowed'}
/>
```

Leave expressions without string literals unchanged (e.g. `className:hover={hoverClasses}`), or store already-prefixed class names in the variable. UseClassy modifiers are not a general replacement for `clsx` / `classy` on the base `className`.

## Svelte: preserve native directives

```svelte
<!-- Before -->
<button
  class="rounded px-4 hover:bg-emerald-600 hover:text-white"
  class:loading={isLoading}
>
  Submit
</button>

<!-- After -->
<button
  class="rounded px-4"
  class:hover="bg-emerald-600 text-white"
  class:loading={isLoading}
>
  Submit
</button>
```

`class:loading={isLoading}` is native Svelte and must not be converted to a string attribute.

## Blade

```blade
{{-- Before --}}
<a
  href="{{ $url }}"
  class="font-medium text-zinc-700 hover:text-zinc-900 hover:underline md:text-lg"
>
  {{ $label }}
</a>

{{-- After --}}
<a
  href="{{ $url }}"
  class="font-medium text-zinc-700"
  class:hover="text-zinc-900 underline"
  class:md="text-lg"
>
  {{ $label }}
</a>
```

## Chained modifiers match Tailwind composition

```html
<!-- Equivalent to class="dark:focus:ring-sky-400" -->
<input class:dark:focus="ring-sky-400" />
```

```html
<input class="border" class:dark:focus="ring-sky-400" class:focus="outline-none ring-2" />
```

## Arbitrary variants as modifiers

Use bracket-aware attribute names for arbitrary variants (including `=` inside `[…]`):

```html
<ul class="space-y-2" class:[&>*]="rounded" class:data-[state=open]="block" class:hover="bg-zinc-50">
  ...
</ul>
```

```tsx
<ul
  className="space-y-2"
  className:[&>*]="rounded"
  className:data-[state=open]="block"
  className:hover="bg-zinc-50"
>
  ...
</ul>
```