---
title: "UnoCSSとは？アトミックCSSエンジンの設定と採用判断を実装目線で解説"
url: "https://www.issoh.co.jp/tech/details/16477/"
published: 2026-08-12
updated: 2026-08-12
categories: ["開発"]
publisher: "株式会社一創"
---

# UnoCSSとは？アトミックCSSエンジンの設定と採用判断を実装目線で解説

UnoCSSは、使っているクラスだけをその場でCSSへ変換する、オンデマンド方式のアトミックCSSエンジンです。特徴的なのは、本体そのものはユーティリティを一切持たず、どんなクラス名が使えるかを**プリセットが決める**という構造。npm registryで2026年8月12日に確認した`unocss`のlatestは66.7.5（公開日は2026年7月7日）でした。この記事では、UnoCSSの立ち位置、Viteでの導入と`uno.config.ts`の各項目、preset-wind3とpreset-wind4の分岐、Tailwind CSSやPanda CSSとの使い分け、そして受託開発で採用してよい条件までを実装目線で扱います。

## まとめ：UnoCSSを採用してよい条件と見送る線引き

先に結論を置きます。Tailwind CSSのクラス名をそのまま使いたい、かつビルドがViteで、さらに「このプロジェクト固有のユーティリティを自分で生やしたい」という要求があるなら、UnoCSSはよく噛み合います。プリセットを差し替えるだけでTailwind互換の書き味を保ったまま、正規表現ルールで独自のクラスを足せるからです。アイコンをCSSだけで扱えるpreset-iconsのように、Tailwind側では別ライブラリが要る領域を公式プリセット1つで賄える点も効いてきます。

見送る判断が要るのは3つの場合。第一に、社外の制作会社や後任へ引き継ぐ前提で、参照できる日本語情報の量を優先したい案件。UnoCSSは設定の自由度が高いぶん、プロジェクトごとに書き味が変わり、引き継ぎ時の説明コストが乗ります。第二に、Tailwind CSSのエコシステム（プラグインやUIキット）に依存した構成。互換プリセットは大半のユーティリティを吸収しますが、プラグイン資産までは持ち込めません。第三に、CSSを書く人がフロントエンドの専任ではない体制。設定ファイルを読み解く前提のツールなので、恩恵より学習コストが上回ります。

## UnoCSSの定義｜プリセットで役割が決まるアトミックCSSエンジン

まず、UnoCSSが何であって何でないのかを整理します。ここを取り違えると「Tailwindの速い版」という理解で導入し、設定の空っぽさに戸惑うことになります。

### フレームワークではなくアトミックCSSエンジンだと説明される理由

公式ドキュメントはUnoCSSを「柔軟性と拡張性を狙って設計された、即時のアトミックCSSエンジン」と定義しています。同じ箇所で、コアは意見を持たず、すべてのユーティリティはプリセット経由で提供されると明記されている点が肝。つまり、素の状態でインストールして`p-4`と書いても何も生成されません。

この設計は、CSSフレームワークというより「クラス名からCSSを作る変換器」に近い立て付けになります。Tailwind互換のユーティリティが欲しければ互換プリセットを読み込み、自社のデザイントークンだけを配るならプリセットを自作する。ルール・バリアント・ショートカットをまとめて1つのnpmパッケージにし、チーム内で配布する運用も想定されています。

### 使ったぶんだけCSSを生成するオンデマンド方式の仕組みと抽出範囲

UnoCSSは、ソースコードに実際に現れたユーティリティだけをCSSへ変換します。生成してから未使用分を削るのではなく、そもそも使われたものしか作らないという順序。この検出を担うのがExtractorで、対象の拡張子や検出ロジックを設定で差し替えられます。

裏を返すと、静的解析で見つけられない書き方は生成対象から漏れます。テンプレート文字列でクラス名を組み立てる、APIレスポンスの値をそのままクラスにする、といったコードは検出されません。この漏れを埋めるのが`safelist`で、検出結果に関係なく常に出力したいユーティリティを列挙します。ビルドは通るのに本番だけスタイルが当たらない、という事故の大半はここが原因です。

### 66.7系という版番号とリリース間隔をnpmで実測した結果（2026年8月）

npm registryを2026年8月12日に叩いて確認したところ、`unocss`のlatestは66.7.5で、公開日は2026年7月7日でした。同じレスポンスに含まれる履歴を遡ると、66.7.0が2026年5月21日、66.7.2が6月12日、66.7.3が6月26日、66.7.4が6月29日と、おおむね数週間おきにパッチが出ています。

版番号が66という大きな数字なのは、リリースのたびにメジャーを進める運用に由来するもので、成熟度を表す数字ではありません。実務上の意味は、パッチ更新であっても変更履歴に目を通す前提を置いたほうがよい、という点に尽きます。UnoCSSはモノレポ構成で各パッケージの版が揃うため、`unocss`本体と個別のプリセットパッケージを混在させるときは版を合わせてください。

## Viteへの導入手順とuno.config.tsに書く設定項目

次に、実際に動かすところまでを追います。Vite以外にNuxt・Astro・Webpack・PostCSS・CLI・CDNランタイムの経路が用意されていますが、ここでは公式が中心に据えるVite統合を扱います。

### npm導入からvirtual:uno.cssを読み込むまでの手順

導入は開発依存へ1パッケージ入れるだけ。プラグインを登録し、エントリで仮想モジュールをimportすれば動きます。

```
npm install -D unocss
```

```
import UnoCSS from 'unocss/vite'
import { defineConfig } from 'vite'

export default defineConfig({
  plugins: [UnoCSS()],
})
```

エントリ側では、生成物の受け口になる仮想モジュールを読み込みます。この1行を忘れるとCSSが一切出力されないため、動かないときは真っ先に確認したい箇所です。

```
import 'virtual:uno.css'
```

設定の配置先はプロジェクト直下の`uno.config.ts`です。公式は、この独立したファイルに寄せるとエディタ拡張やCLIなど他の統合と設定を共有できるため推奨だとしています。開発中は設定ファイルの変更がHMRの対象になり、書き換えると即座に反映されます。

```
import { defineConfig, presetWind4, presetIcons } from 'unocss'

export default defineConfig({
  presets: [
    presetWind4(),
    presetIcons({ scale: 1.2 }),
  ],
  shortcuts: {
    'btn-primary': 'px-4 py-2 rounded bg-blue-600 text-white',
  },
})
```

### uno.config.tsで押さえておきたい主要な設定項目の一覧と役割

設定ファイルの項目は多く見えますが、役割で分けると3群に整理できます。ユーティリティを供給する群、検出と出力を制御する群、素のCSSを差し込む群です。

| 設定項目         | 役割           |
| ------------ | ------------ |
| presets      | ユーティリティの供給元  |
| rules        | 独自ユーティリティの定義 |
| shortcuts    | 既存クラスの束に別名   |
| theme        | ルール横断で使う変数   |
| variants     | セレクタの前処理     |
| transformers | ソースコードの書き換え  |
| extractors   | クラス検出の対象と方法  |
| content      | 走査するファイルの指定  |
| preflights   | 素のCSSを直接注入   |
| safelist     | 検出に頼らず常時出力   |
| blocklist    | 生成させない指定を除外  |

実務で最初に触るのは`presets`と`shortcuts`、次に`safelist`という順序になるはずです。`content`はViteのビルドパイプラインに乗らないファイル、たとえばバックエンドのテンプレートやMarkdownを走査対象へ足すときに使います。`blocklist`は逆向きの道具で、デザインシステムから外したいユーティリティを封じる用途。自由度を絞りたいチームでは効きます。

### 生成モードの選び分けとVueやWeb Componentsでの扱い

Viteプラグインには生成モードがあり、CSSをどこへ吐くかを切り替えられます。既定のglobalで困る場面は限られますが、Web Componentsやマルチページ構成では選び直しが要ります。

| モード        | 出力のされ方            | 向く構成           |
| ---------- | ----------------- | -------------- |
| global     | 単一のCSSを注入         | 既定・SPA全般       |
| vue-scoped | SFCのstyle scopedへ | Vueで影響範囲を絞る    |
| shadow-dom | 生成CSSを内側へ差し込む     | Web Components |
| per-module | モジュール単位で分割        | 実験的な位置づけ       |
| dist-chunk | チャンク単位で分割         | MPAのビルド        |

Shadow DOMを使うWeb Componentsでは、グローバルなスタイルシートが内側へ届きません。shadow-domモードは生成CSSをコンポーネント内へ差し込むことでこれを解きます。Svelteのスコープ付き生成は別パッケージへ切り出されている点も、移行時に引っかかりやすいところ。per-moduleとdist-chunkは公式が実験的と明示しているので、長期保守の案件では避けるのが無難でしょう。

## プリセットの選び方｜preset-wind3とwind4の分岐点

UnoCSSで最初に決めるのはプリセットです。ここが書き味と移行コストを丸ごと左右します。

### preset-unoがpreset-wind3へ改名された経緯

かつて既定として案内されていた`@unocss/preset-uno`は、公式ドキュメント上で非推奨となり、`@unocss/preset-wind3`へ改名されています。中身はTailwind CSSとWindi CSSの互換プリセットで、名前が変わっただけという理解でおおむね足ります。

古い記事やテンプレートを参考にすると`presetUno()`を書いたままになりがちなので、新規に組むなら改名後の名前を使ってください。既存プロジェクトの更新では、まず`presetWind3()`へ差し替えて既存の見た目が崩れないことを確認し、そのうえで次項のwind4へ進む二段階が安全です。

### preset-wind4で変わったテーマキーとレイヤー設計の要点

`@unocss/preset-wind4`は、Tailwind CSS 4に合わせた互換プリセットです。公式はwind3の全機能と互換だとしたうえで、テーマの持ち方を作り直したと説明しています。[Tailwind CSS v4の主な変更点と新機能の概要](https://www.issoh.co.jp/tech/details/5060/)で扱ったCSS変数中心の設計が、そのままUnoCSS側にも反映された形です。

変更のうち実装に効くのはテーマキーの改称で、`fontFamily`が`font`、`borderRadius`が`radius`、`boxShadow`が`shadow`、`easing`が`ease`へ移り、サイズ系は`spacing`に寄せられました。加えて`properties`・`theme`・`base`という3つのレイヤーが増え、`@property`を使う形に変わっています。テーマ変数の出力は既定がオンデマンドで、全量出力にも切り替えられる設定です。

移行時の注意も公式が明示しています。`presetRemToPx`は組み込みのプロセッサへ置き換わったため設定から外すこと、そして`presetLegacyCompat`との併用はoklchの色表現と噛み合わないため避けること。古いブラウザを相手にする案件では、この2点目が採用可否を分ける判断材料になります。

### アイコンや属性記法を足す公式プリセットのそれぞれの使いどころ

互換プリセット以外にも公式プリセットが揃っています。`preset-icons`はIconify由来のアイコンを純粋なCSSとして扱うもので、SVGコンポーネントを都度作る手間が消えます。`preset-web-fonts`はGoogle Fontsなどの読み込みを設定へ寄せる道具。`preset-typography`は本文組みの既定スタイル、`preset-attributify`と`preset-tagify`は記法そのものを拡張するプリセットです。

UIコンポーネントまで揃えたい場合は、プリセットではなくTailwind側の資産を借りる選択肢もあります。[daisyUIとは？Tailwind CSSコンポーネントの使い方とv5の設定変更](https://www.issoh.co.jp/tech/details/2987/)のようなコンポーネント集は、互換プリセットの下でも動く場合と動かない場合があるため、採用前に小さく試すのが確実です。

## ルールとショートカットとAttributifyで変わる書き味

ここからはUnoCSS固有の書き味を見ます。Tailwind互換で始めても、結局この3つを使うかどうかで採用の意味が変わります。

### 正規表現ルールで任意の数値や単位をそのまま通せる書き方と注意点

ルールは静的にも動的にも書けます。動的ルールは正規表現でクラス名を受け、キャプチャした値からCSSオブジェクトを組み立てる方式。これにより、あらかじめ定義していない数値をそのまま通せます。

```
rules: [
  ['card-flat', { 'box-shadow': 'none' }],
  [/^pad-(\d+(?:\.\d+)?)$/, function (match) {
    return { padding: match[1] + 'px' }
  }],
]
```

この仕組みのおかげで、小数を含む指定や独自の単位もブラケット記法に頼らず書けます。ルールは後に書いたものが優先される順序なので、プリセット由来のクラス名と衝突させると意図しない上書きが起きます。命名にプロジェクト固有の接頭辞を付けておくと、この事故を避けられるでしょう。

### shortcutsでクラスの束に名前を付ける運用の勘所と落とし穴

`shortcuts`は、複数のユーティリティをまとめて1つの名前にする機能です。ボタンやカードのように繰り返し現れる組み合わせを1箇所へ寄せられます。ただし、ここへ寄せすぎるとアトミックCSSの利点である「クラス名を読めばスタイルが分かる」性質が薄れます。

実務では、バリエーション（サイズ違い・状態違い）が絡む単位はshortcutsではなく専用のライブラリへ渡すほうが破綻しません。同じ課題をTailwind側で解く道具としては[Tailwind Variants(tv)の使い方｜slotsとcompoundVariants](https://www.issoh.co.jp/tech/details/3773/)が参考になります。shortcutsは「常に同じ組み合わせ」だけに絞り、条件分岐が入る瞬間に別の層へ逃がす、という線引きが運用しやすい形です。

### Attributifyモードが向く場面と避けたほうがよい場面

Attributifyモードは、クラス属性に長い文字列を並べる代わりに、`text`や`bg`といった属性へ値を分けて書ける記法を足します。クラス名が数十文字に膨らんだテンプレートを整理する手段として有効。属性ごとに関心が分かれるため、差分レビューも読みやすくなります。

一方で、この記法はUnoCSS固有です。将来Tailwind CSSへ戻す可能性が残る案件で全面採用すると、移行時にテンプレートを総書き換えする羽目になります。導入するなら、新規で閉じた画面から部分的に始め、戻せる範囲を保っておくのが安全側の判断でしょう。

## Tailwind CSSやPanda CSSとの違いと受託での使い分け

最後に、近い立ち位置の道具と並べて整理します。速さだけで比べると選び分けを誤るため、生成のされ方と拡張の方式という軸で見ます。

### UnoCSSとTailwindとPanda CSSの守備範囲を比較する

| ツール          | 立ち位置      | 生成のされ方     | 拡張の方式          |
| ------------ | --------- | ---------- | -------------- |
| UnoCSS       | エンジン      | 使用箇所を走査    | プリセットとルール      |
| Tailwind CSS | フレームワーク   | 使用箇所を走査    | プラグインとCSS変数    |
| Panda CSS    | ビルド時生成    | 型付きAPIから抽出 | レシピとパターン       |
| CSS Modules  | スコープ機構    | 手書きCSSを変換  | 素のCSSのまま       |
| StyleX       | CSS-in-JS | 静的解析で抽出    | JavaScriptのAPI |

UnoCSSとTailwind CSSは、クラス名を走査してCSSを作るという点で同じ系統です。違いは既定値の有無で、Tailwindはデザインシステムを丸ごと持ち込むのに対し、UnoCSSは何を持ち込むかを選ばせます。スコープの与え方で解く[CSS Modulesとは？Next.js・TypeScriptでの導入と型安全化](https://www.issoh.co.jp/tech/details/2917/)や、JavaScript側のAPIで書く[StyleXとは？Meta製CSS-in-JSの導入手順と使い方](https://www.issoh.co.jp/tech/details/2267/)とは、そもそも解いている課題が違います。ビルド時生成のまま型をトークン名まで効かせたい要求があるなら、[Panda CSSとは？型付きスタイル生成の設定と採用判断](https://www.issoh.co.jp/tech/details/16479/)で扱った関数呼び出し起点の方式が候補に入ります。

### Tailwind v4がCSS-firstになった後の選び分け

Tailwind CSS v4が設定をCSS側へ寄せたことで、「設定ファイルの書きやすさ」でUnoCSSを選ぶ理由は薄まりました。それでも残る差は2つ。1つは独自ルールを正規表現で書ける拡張性、もう1つはアイコンや属性記法まで公式プリセットで賄える範囲の広さです。

逆に言えば、この2つを使わないならTailwind CSSで足ります。既存のTailwind構成で困っていない案件をUnoCSSへ寄せる動機は薄いはずです。CSS-in-JSとの併存を検討している段階なら、[Tailwind CSSとEmotionの違い｜v4での使い分けと共存](https://www.issoh.co.jp/tech/details/4494/)で整理した論点がそのまま当てはまります。

### 受託開発でUnoCSSを採用してよい3条件と見送るべき場面の切り分け

受託の現場で判断するなら、次の3条件が揃うときに選んで差し支えありません。第一に、ビルドがViteで、フロントエンドの専任が保守を担当し続ける。第二に、デザイントークンや独自ユーティリティを自前で定義する必要が実際にある。第三に、パッチ更新のたびに変更履歴を追える運用が組める。

見送るのは、納品後の保守を顧客側の非専任メンバーが担う案件と、Tailwindのプラグイン資産に深く依存した既存構成の移行です。前者は設定ファイルの読解が属人化し、後者は互換プリセットでは吸収しきれない差分の洗い出しに工数が乗ります。[業務用・Webアプリ開発](https://www.issoh.co.jp/service/apps/business/)では、こうしたフロントエンド基盤の選定から移行手順の設計、引き継ぎドキュメントの整備までを含めて相談を受けています。既存プロジェクトで判断に迷うなら、まず1画面だけUnoCSSに載せ替えて差分を測るところから始めてください。

## よくある質問

### UnoCSSとTailwind CSSはどちらを選ぶべきですか？

独自ユーティリティを正規表現で足したい要求がなければ、Tailwind CSSで足ります。UnoCSSが効くのは、プロジェクト固有のルールやプリセットを自前で持ちたい場面です。クラス名の互換性は互換プリセットで確保されるため、書き味そのものは大きく変わりません。

### UnoCSSはTailwindのクラス名がそのまま使えますか？

preset-wind3またはpreset-wind4を読み込めば、大半のユーティリティはそのまま通ります。ただしプラグインが提供していたクラスは対象外です。移行前に、使っているTailwindプラグインを洗い出し、代替がプリセットやルールで書けるかを確認してください。

### クラス名を動的に組み立てるとスタイルが当たらないのはなぜですか？

Extractorがソースコードを走査して検出したものだけを生成する仕組みだからです。文字列連結で作ったクラス名は静的解析で見つかりません。対策は`safelist`への列挙か、条件分岐で完全なクラス名を書き分ける形へ直すかの二択になります。

### preset-unoは今でも使えますか？

公式ドキュメント上で非推奨となり、preset-wind3へ改名されています。動作自体は当面残るとしても、新規に書くなら改名後の名前を使ってください。既存プロジェクトでは、まず名前を差し替えて見た目が変わらないことを確認する手順が安全です。

### UnoCSSはVite以外のビルド環境でも動きますか？

Nuxt・Astro・Next.js・Webpack向けの統合に加え、PostCSSプラグイン、CLI、CDN経由のランタイムが公式から提供されています。ただし公式ドキュメントの中心はVite統合で、生成モードのような細かい制御もVite前提の記述が厚めです。新規に組むならViteが素直でしょう。

## 関連記事

- [Tailwind CSS v4の主な変更点と新機能の概要](https://www.issoh.co.jp/tech/details/5060/)
- [daisyUIとは？Tailwind CSSコンポーネントの使い方とv5の設定変更【2026年版】](https://www.issoh.co.jp/tech/details/2987/)
- [Tailwind Variants(tv)の使い方｜slots・compoundVariants・レスポンシブとTailwind CSS v4対応](https://www.issoh.co.jp/tech/details/3773/)
- [Tailwind CSSとEmotionの違い｜v4での使い分けと共存](https://www.issoh.co.jp/tech/details/4494/)
- [CSS Modulesとは？Next.js・TypeScriptでの導入と型安全化の設定を解説](https://www.issoh.co.jp/tech/details/2917/)

---

出典: [UnoCSSとは？アトミックCSSエンジンの設定と採用判断を実装目線で解説](<https://www.issoh.co.jp/tech/details/16477/>)（株式会社一創）