DocusプロジェクトでのTailwind CSS v4完全移行ガイド — スタイルカスタマイズとベストプラクティス

DocusプロジェクトでのTailwind CSS v4完全移行ガイド — スタイルカスタマイズとベストプラクティス

Docus 5.2.0でのTailwind CSS v4統合、カスタムスタイリング、@applyディレクティブ活用、レスポンシブデザイン、ダークモード実装の完全ガイド。

はじめに

この記事は、Docus実践ガイドを読んだ方に向けて、Tailwind CSS v4を使ったスタイルカスタマイズの詳細を提供します。

この記事の対象読者:

  • Docusプロジェクトでスタイルをカスタマイズしたい方
  • Tailwind CSS v3からv4への移行を検討している方
  • 既存CSSをTailwindユーティリティに変換したい方
  • レスポンシブデザインとダークモード対応を実装したい方

この記事で扱うこと:

  • Tailwind CSS v4の新機能と変更点
  • Docusプロジェクトでの統合手順
  • カスタムカラーとデザイントークンの定義
  • @applyディレクティブを使った既存CSSの移行
  • コンポーネントスタイリングパターン
  • レスポンシブデザインの実装戦略
  • ダークモード対応のベストプラクティス
  • パフォーマンス最適化とビルド設定
  • よくあるトラブルシューティング

1. Tailwind CSS v4の新機能と変更点

v4の主な変更点

Tailwind CSS v4は、パフォーマンスと開発者体験を大幅に改善しました。

主要な変更点:

  • 新しいエンジン: Rust製の高速パーサーでビルド時間が50%削減
  • CSS-first設定: tailwind.config.js から @theme ディレクティブへ移行
  • ネイティブカスケードレイヤー: @layer の改善とカスタマイズ性向上
  • 改善された型サポート: TypeScript完全対応とIDE補完の強化
  • 最適化されたバンドルサイズ: 未使用CSSの自動削除がより効率的に

破壊的変更:

  • tailwind.config.js の一部オプションが非推奨
  • カスタムカラーの定義方法が変更
  • プラグインAPIの一部が更新

Docus 5.2.0での統合状況

Docus 5.2.0以降、Tailwind CSS v4が標準統合されています:

  • 依存関係の自動インストール: @nuxt/uitailwindcssが含まれる
  • ビルド最適化: 本番ビルド時の自動最適化
  • 設定の注意点: Nuxtのバージョンにより追加設定が必要な場合がある

2. プロジェクトセットアップと統合

Docusの依存関係の理解

Docus 5.2.0以降をインストールすると、以下が依存関係として含まれます

docus 5.2.0+
  └── @nuxt/ui 4.x
        ├── @tailwindcss/vite 4.x
        └── tailwindcss 4.x

依存関係の確認:

# Docusをインストール後、依存関係を確認
pnpm list @nuxt/ui
# → docus経由で自動インストール済み

pnpm list tailwindcss
# → @nuxt/ui経由で自動インストール済み

新規プロジェクトの場合

Docusプロジェクトを作成すると、Tailwind CSS v4が依存関係として含まれます:

# Docusプロジェクト作成
npx nuxi init docs -t docus
cd docs
pnpm install

# 依存関係を確認
pnpm why tailwindcss
# → @nuxt/ui経由で自動インストール済み

nuxt.config.ts の基本設定(Nuxt 3の場合):

export default defineNuxtConfig({
  // Docusを拡張(@nuxt/ui、Tailwindも自動有効化)
  extends: ['docus'],
})

既存プロジェクトへのDocus追加

ステップ1: Docusのインストール

# Docusのみをインストール(依存関係が自動的についてくる)
pnpm add docus

ステップ2: nuxt.config.ts の設定

Nuxt 3の場合(推奨):

export default defineNuxtConfig({
  // extendsだけでOK
  extends: ['docus'],
})

Nuxt 4の場合(compatibilityVersion: 4):

export default defineNuxtConfig({
  extends: ['docus'],

  future: {
    compatibilityVersion: 4,
  },

  // Nuxt 4では明示的な追加が必要な場合がある
  modules: [
    '@nuxt/ui',  // Docusの依存関係を明示的に追加
    // ...他のモジュール
  ],
})

重要な注意点:

  • Nuxt 4(compatibilityVersion: 4)では、extendsの動作が変更され、一部のモジュールを明示的に追加する必要がある場合があります
  • プロジェクトで動作しない場合は、modules@nuxt/uiを追加してください

ステップ3: CSSファイルの設定

app/assets/css/main.cssを作成し、Tailwind CSSと@nuxt/uiをインポートします:

app/assets/css/main.css
/*
 * Docus + Nuxt UI v4 統合スタイル
 * Tailwind CSS v4 を PostCSS プラグインとして使用
 */

@import "tailwindcss";
@import "@nuxt/ui";

/* カスタムスタイル(オプション) */
/* @import "./tailwind.css"; */  /* カスタムカラー・テーマ定義 */
/* @import "./prose.css"; */     /* Markdownコンテンツスタイル */

次に、nuxt.config.tsでCSSファイルを読み込みます:

nuxt.config.ts
export default defineNuxtConfig({
  extends: ['docus'],

  css: [
    '~/app/assets/css/main.css',  // メインCSSファイル
  ],
})

package.jsonへの明示的な追加が必要:

pnpmのストリクトなnode_modules構造により、CSSから直接@importで参照するパッケージは、package.jsonに明示的に記載する必要があります

{
  "dependencies": {
    "docus": "5.3.1",
    "@nuxt/ui": "^4.2.1"  // CSS から @import するため必要
  },
  "devDependencies": {
    "tailwindcss": "^4.1.17"  // CSS から @import するため必要
  }
}
# 明示的にインストール
pnpm add @nuxt/ui
pnpm add -D tailwindcss

# node_modulesに直接リンクされることを確認
ls node_modules/@nuxt/ui
ls node_modules/tailwindcss

重要:

  • Nuxt moduleとしての有効化: extends: ['docus']で自動(modules配列への追加は不要)
  • CSSからの直接参照: package.jsonへの明示的な記載が必要(pnpmの制約)

これは2つの異なるレイヤーの要件です。

ファイル構成

Tailwind CSSのカスタマイズファイル構成:

docs/
├── app/
│   └── assets/
│       └── css/
│           ├── tailwind.css      # カスタムカラー・テーマ定義
│           └── prose.css          # Markdownコンテンツスタイル
├── components/
│   └── content/                   # スタイル付きコンポーネント
│       ├── CustomCard.vue
│       └── LinkCard.vue
└── nuxt.config.ts                 # Tailwind設定(必要に応じて)

3. カスタムカラーとデザイントークンの定義

カスタムカラーの定義

app/assets/css/tailwind.css でカスタムカラーを定義:

app/assets/css/tailwind.css
@reference "tailwindcss";

/* カスタムカラーパレット */
:root {
  /* プライマリカラー */
  --color-primary-50: #f0fdf4;
  --color-primary-100: #dcfce7;
  --color-primary-500: #22c55e;
  --color-primary-600: #16a34a;
  --color-primary-700: #15803d;

  /* ブランドカラー */
  --color-brand-head: #380964;
  --color-brand-accent: #4f46e5;

  /* セマンティックカラー */
  --color-success: #10b981;
  --color-warning: #f59e0b;
  --color-error: #ef4444;
  --color-info: #3b82f6;

  /* ニュートラル */
  --color-gray-50: #f9fafb;
  --color-gray-100: #f3f4f6;
  --color-gray-500: #6b7280;
  --color-gray-900: #111827;
}

/* ダークモード用カラー */
.dark {
  --color-primary-500: #34d399;
  --color-primary-600: #10b981;
  --color-brand-head: #9333ea;
  --color-brand-accent: #8b5cf6;
}

デザイントークンの活用

定義したカスタムカラーをTailwindユーティリティとして使用:

<template>
  <!-- カスタムカラーの使用例 -->
  <div class="bg-primary-500 text-white">
    プライマリカラー背景
  </div>

  <h1 class="text-brand-head dark:text-brand-head">
    ブランドカラーの見出し
  </h1>

  <button class="bg-success hover:bg-success/90">
    成功ボタン
  </button>
</template>

フォントとスペーシングのカスタマイズ

@reference "tailwindcss";

:root {
  /* カスタムフォント */
  --font-sans: "Inter", -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
  --font-mono: "Fira Code", "SF Mono", Consolas, monospace;
  --font-ja: "Hiragino Sans", "Yu Gothic", "Meiryo", sans-serif;

  /* カスタムスペーシング */
  --spacing-xs: 0.25rem;
  --spacing-sm: 0.5rem;
  --spacing-md: 1rem;
  --spacing-lg: 1.5rem;
  --spacing-xl: 2rem;

  /* カスタムブレークポイント(参考値) */
  --screen-sm: 640px;
  --screen-md: 768px;
  --screen-lg: 1024px;
  --screen-xl: 1280px;
  --screen-2xl: 1536px;
}

4. @applyディレクティブを使った既存CSSの移行

基本的な移行パターン

従来のCSSをTailwindユーティリティに変換:

<style scoped>
@reference "tailwindcss";

/* Before: 従来のCSS */
.card {
  position: relative;
  display: flex;
  flex-direction: column;
  width: 100%;
  padding: 1.5rem;
  margin-bottom: 1rem;
  background-color: #ffffff;
  border: 1px solid #e5e7eb;
  border-radius: 0.5rem;
  box-shadow: 0 1px 3px rgba(0, 0, 0, 0.1);
  transition: all 0.2s ease;
}

.card:hover {
  box-shadow: 0 4px 6px rgba(0, 0, 0, 0.1);
  transform: translateY(-2px);
}

/* After: Tailwind CSS */
.card {
  @apply relative flex flex-col w-full p-6 mb-4;
  @apply bg-white border border-gray-200 rounded-lg;
  @apply shadow-sm transition-all duration-200;
  @apply hover:shadow-md hover:-translate-y-0.5;
}
</style>

レスポンシブデザインの移行

メディアクエリをTailwindブレークポイントに変換:

<style scoped>
@reference "tailwindcss";

/* Before: メディアクエリ */
.hero {
  width: 100%;
  height: 400px;
  padding: 2rem;
}

@media (min-width: 768px) {
  .hero {
    height: 500px;
    padding: 3rem;
  }
}

@media (min-width: 1024px) {
  .hero {
    height: 600px;
    padding: 4rem;
  }
}

/* After: Tailwindレスポンシブユーティリティ */
.hero {
  @apply w-full h-[400px] p-8;
  @apply md:h-[500px] md:p-12;
  @apply lg:h-[600px] lg:p-16;
}
</style>

グラデーションと複雑な背景

<style scoped>
@reference "tailwindcss";

/* Before: 複雑なCSS */
.gradient-card {
  background: linear-gradient(135deg, #667eea 0%, #764ba2 100%);
  position: relative;
}

.gradient-card::before {
  content: '';
  position: absolute;
  inset: 0;
  background: linear-gradient(to bottom, rgba(0, 0, 0, 0.1), rgba(0, 0, 0, 0.3));
  border-radius: inherit;
}

/* After: Tailwind CSS */
.gradient-card {
  @apply relative bg-gradient-to-br from-indigo-500 to-purple-600;
}

.gradient-card::before {
  @apply absolute inset-0 bg-gradient-to-b from-black/10 to-black/30 rounded-inherit;
  content: '';
}
</style>

アニメーションとトランジション

<style scoped>
@reference "tailwindcss";

/* Before: キーフレームアニメーション */
@keyframes fadeIn {
  from {
    opacity: 0;
    transform: translateY(20px);
  }
  to {
    opacity: 1;
    transform: translateY(0);
  }
}

.fade-in-element {
  animation: fadeIn 0.5s ease-out;
}

/* After: Tailwindユーティリティ + カスタムアニメーション */
.fade-in-element {
  @apply animate-fade-in;
}

/* カスタムアニメーション定義(tailwind.css) */
@keyframes fade-in {
  from {
    @apply opacity-0 translate-y-5;
  }
  to {
    @apply opacity-100 translate-y-0;
  }
}
</style>

5. コンポーネントスタイリングパターン

Nuxt UI v4のuiプロップ活用

Nuxt UIコンポーネントをTailwindで完全カスタマイズ:

<template>
  <UCard
    :ui="{
      root: 'overflow-hidden rounded-xl ring-1 ring-gray-200 dark:ring-gray-800',
      body: 'p-0',
      header: 'p-6 pb-4 border-b border-gray-100 dark:border-gray-800',
      footer: 'p-6 pt-4 border-t border-gray-100 dark:border-gray-800'
    }"
    class="hover:ring-primary-500 transition-all duration-200"
  >
    <template #header>
      <h3 class="text-lg font-semibold text-gray-900 dark:text-white">
        カードタイトル
      </h3>
    </template>

    <div class="p-6">
      <p class="text-gray-600 dark:text-gray-400">
        カードコンテンツ
      </p>
    </div>

    <template #footer>
      <UButton
        :ui="{
          root: 'bg-primary-500 hover:bg-primary-600',
          label: 'font-medium'
        }"
      >
        アクション
      </UButton>
    </template>
  </UCard>
</template>

カスタムコンポーネントの構築

Tailwindベースのカスタムコンポーネント例:

<!-- components/content/CustomAlert.vue -->
<template>
  <div
    :class="[
      'alert',
      `alert--${variant}`,
      { 'alert--dismissible': dismissible }
    ]"
    role="alert"
  >
    <div class="alert-icon">
      <Icon :name="iconName" />
    </div>
    <div class="alert-content">
      <h4 v-if="title" class="alert-title">
        {{ title }}
      </h4>
      <div class="alert-message">
        <slot />
      </div>
    </div>
    <button
      v-if="dismissible"
      class="alert-dismiss"
      @click="$emit('dismiss')"
    >
      <Icon name="carbon:close" />
    </button>
  </div>
</template>

<script setup lang="ts">
const props = defineProps({
  variant: {
    type: String as () => 'info' | 'success' | 'warning' | 'error',
    default: 'info'
  },
  title: String,
  dismissible: Boolean
})

const iconName = computed(() => {
  const icons = {
    info: 'carbon:information',
    success: 'carbon:checkmark-filled',
    warning: 'carbon:warning',
    error: 'carbon:error-filled'
  }
  return icons[props.variant]
})
</script>

<style scoped>
@reference "tailwindcss";

.alert {
  @apply flex gap-3 p-4 rounded-lg border;
  @apply transition-all duration-200;
}

.alert--info {
  @apply bg-blue-50 border-blue-200 text-blue-900;
  @apply dark:bg-blue-950/50 dark:border-blue-800 dark:text-blue-100;
}

.alert--success {
  @apply bg-green-50 border-green-200 text-green-900;
  @apply dark:bg-green-950/50 dark:border-green-800 dark:text-green-100;
}

.alert--warning {
  @apply bg-yellow-50 border-yellow-200 text-yellow-900;
  @apply dark:bg-yellow-950/50 dark:border-yellow-800 dark:text-yellow-100;
}

.alert--error {
  @apply bg-red-50 border-red-200 text-red-900;
  @apply dark:bg-red-950/50 dark:border-red-800 dark:text-red-100;
}

.alert-icon {
  @apply flex-shrink-0 text-xl;
}

.alert-content {
  @apply flex-1 min-w-0;
}

.alert-title {
  @apply font-semibold mb-1 text-sm;
}

.alert-message {
  @apply text-sm leading-relaxed;
}

.alert-dismiss {
  @apply flex-shrink-0 p-1 rounded hover:bg-black/5;
  @apply dark:hover:bg-white/5 transition-colors;
}
</style>

proseスタイルの上書き

Markdownコンテンツのスタイルカスタマイズ:

<style scoped>
@reference "tailwindcss";

/* proseクラスの影響を除外 */
.custom-content {
  @apply not-prose;
}

/* または個別要素を上書き */
.article-content :deep(.prose) {
  /* 見出しのカスタマイズ */
  & h2 {
    @apply text-3xl font-bold mb-4 mt-8;
    @apply text-gray-900 dark:text-white;
    @apply border-b-2 border-primary-500 pb-2;
  }

  /* リンクのカスタマイズ */
  & a {
    @apply text-primary-600 dark:text-primary-400;
    @apply underline decoration-primary-300 hover:decoration-primary-500;
    @apply transition-colors duration-200;
  }

  /* コードブロックのカスタマイズ */
  & pre {
    @apply bg-gray-900 dark:bg-gray-950;
    @apply rounded-lg p-4 overflow-x-auto;
  }

  & code {
    @apply text-sm font-mono;
    @apply bg-gray-100 dark:bg-gray-800;
    @apply px-1.5 py-0.5 rounded;
  }
}
</style>

6. レスポンシブデザインの実装戦略

モバイルファーストアプローチ

Tailwindのモバイルファースト設計を活用:

<template>
  <!-- 基本はモバイル、sm以上でタブレット、lg以上でデスクトップ -->
  <div class="
    grid grid-cols-1 gap-4 p-4
    sm:grid-cols-2 sm:gap-6 sm:p-6
    lg:grid-cols-3 lg:gap-8 lg:p-8
    xl:grid-cols-4
  ">
    <div v-for="item in items" :key="item.id" class="card">
      {{ item.title }}
    </div>
  </div>
</template>

コンテナクエリの活用

親要素のサイズに応じたスタイル調整:

<style scoped>
@reference "tailwindcss";

.card-container {
  @apply container-type-inline;
}

.card {
  @apply p-4 text-sm;
  /* 親コンテナが広い場合 */
  @container (min-width: 400px) {
    @apply p-6 text-base;
  }
  @container (min-width: 600px) {
    @apply p-8 text-lg;
  }
}
</style>

レスポンシブタイポグラフィ

clamp()関数とTailwindの組み合わせ:

<style scoped>
@reference "tailwindcss";

.responsive-heading {
  /* font-size: clamp(最小値, 推奨値, 最大値) */
  font-size: clamp(1.5rem, 4vw, 3rem);
  @apply font-bold leading-tight;
}

/* または個別にブレークポイント指定 */
.heading {
  @apply text-2xl md:text-3xl lg:text-4xl xl:text-5xl;
  @apply font-bold leading-tight;
}
</style>

レスポンシブスペーシング

画面サイズに応じた余白調整:

<template>
  <section class="
    py-8 px-4
    sm:py-12 sm:px-6
    md:py-16 md:px-8
    lg:py-20 lg:px-12
    xl:py-24 xl:px-16
  ">
    <div class="max-w-7xl mx-auto">
      <h2 class="mb-4 sm:mb-6 md:mb-8 lg:mb-10">
        セクションタイトル
      </h2>
    </div>
  </section>
</template>

7. ダークモード対応のベストプラクティス

カラースキーム設計

ライト・ダークモード両対応のカラー戦略:

@reference "tailwindcss";

:root {
  /* ライトモード: 読みやすさ重視 */
  --color-bg-primary: #ffffff;
  --color-bg-secondary: #f9fafb;
  --color-text-primary: #111827;
  --color-text-secondary: #6b7280;
  --color-border: #e5e7eb;
}

.dark {
  /* ダークモード: 目に優しい配色 */
  --color-bg-primary: #1f2937;
  --color-bg-secondary: #111827;
  --color-text-primary: #f9fafb;
  --color-text-secondary: #9ca3af;
  --color-border: #374151;
}

コンポーネントのダークモード対応

<template>
  <div class="
    bg-white dark:bg-gray-900
    text-gray-900 dark:text-gray-100
    border border-gray-200 dark:border-gray-700
    shadow-sm dark:shadow-gray-900/50
  ">
    <h3 class="text-gray-900 dark:text-white">
      タイトル
    </h3>
    <p class="text-gray-600 dark:text-gray-400">
      説明文
    </p>
    <button class="
      bg-primary-500 hover:bg-primary-600
      dark:bg-primary-600 dark:hover:bg-primary-700
      text-white
    ">
      ボタン
    </button>
  </div>
</template>

画像とグラフィックスのダークモード対応

<template>
  <!-- 画像の明度調整 -->
  <img
    src="/image.png"
    alt="説明"
    class="dark:brightness-90 dark:contrast-90"
  />

  <!-- ライト/ダーク別画像 */
  <picture>
    <source
      srcset="/image-dark.png"
      media="(prefers-color-scheme: dark)"
    />
    <img src="/image-light.png" alt="説明" />
  </picture>

  <!-- CSSで背景画像を切り替え -->
  <div class="
    bg-[url('/bg-light.png')] dark:bg-[url('/bg-dark.png')]
    bg-cover bg-center
  " />
</template>

ダークモードトグルの実装

<!-- components/ColorModeToggle.vue -->
<template>
  <button
    @click="toggleColorMode"
    class="
      p-2 rounded-lg
      bg-gray-100 hover:bg-gray-200
      dark:bg-gray-800 dark:hover:bg-gray-700
      transition-colors duration-200
    "
    aria-label="カラーモード切り替え"
  >
    <Icon
      :name="colorMode === 'dark' ? 'carbon:moon' : 'carbon:sun'"
      class="text-xl"
    />
  </button>
</template>

<script setup lang="ts">
const colorMode = useColorMode()

function toggleColorMode() {
  colorMode.preference = colorMode.value === 'dark' ? 'light' : 'dark'
}
</script>

8. パフォーマンス最適化とビルド設定

未使用CSSの削除

Tailwindは自動で未使用CSSを削除しますが、確実に動作させるために:

// nuxt.config.ts
export default defineNuxtConfig({
  css: ['~/assets/css/tailwind.css'],

  postcss: {
    plugins: {
      tailwindcss: {},
      autoprefixer: {},
    },
  },

  // 本番ビルドでの最適化
  experimental: {
    inlineStyles: true, // インラインCSSの最適化
  },
})

CSS変数の最適化

頻繁に使用するスタイルはCSS変数化:

@reference "tailwindcss";

:root {
  /* よく使う組み合わせを変数化 */
  --card-padding: theme('spacing.6');
  --card-radius: theme('borderRadius.xl');
  --card-shadow: theme('boxShadow.md');
}

.card {
  padding: var(--card-padding);
  border-radius: var(--card-radius);
  box-shadow: var(--card-shadow);
}

JIT(Just-In-Time)モードの活用

任意の値を動的に生成:

<template>
  <!-- 任意の値を直接指定 -->
  <div class="w-[347px] h-[231px] text-[17px]">
    カスタムサイズ
  </div>

  <!-- 任意のカラーコード -->
  <div class="bg-[#1da1f2] text-[#abc123]">
    カスタムカラー
  </div>

  <!-- 計算値 -->
  <div class="top-[calc(100vh-4rem)]">
    計算された位置
  </div>
</template>

バンドルサイズの確認

ビルド後のCSSサイズを確認:

# ビルド
pnpm build

# CSSファイルサイズを確認
du -h .output/public/_nuxt/*.css

# 詳細な分析
npx vite-bundle-visualizer

9. トラブルシューティング

スタイルが適用されない場合

問題: Tailwindユーティリティが反映されない

原因と解決策:

  1. @reference の記載忘れ:
<style scoped>
@reference "tailwindcss";  /* これが必要 */

.my-class {
  @apply flex items-center;
}
</style>
  1. 動的クラス名の問題:
<!-- ❌ 誤り: 動的な文字列結合はPurgeの対象外 -->
<div :class="`text-${color}-500`">

<!-- ✅ 正しい: 完全なクラス名を使用 -->
<div :class="color === 'red' ? 'text-red-500' : 'text-blue-500'">
  1. グローバルスタイルの上書き(! 修飾子):

Tailwind CSS v4では、グローバルスタイル(prose.cssなど)を上書きするために!修飾子を使用します:

<template>
  <!-- ✅ 正しい: ! 修飾子をクラス名の前につける -->
  <div class="!text-gray-900 !font-bold">
    グローバルスタイルより優先される
  </div>

  <!-- 複数のプロパティに適用 -->
  <p class="!text-base !leading-relaxed !text-gray-800">
    prose.cssのスタイルを上書き
  </p>
</template>

構文: !{utility-class} (クラス名の前に!をつける)

注意: !修飾子は!importantを追加するため、必要最小限の使用に留めてください。

ダークモードが正常に動作しない

問題: dark: バリアントが反映されない

解決策:

// nuxt.config.ts でカラーモード設定を確認
export default defineNuxtConfig({
  colorMode: {
    preference: 'system', // 'system', 'light', 'dark'
    fallback: 'light',
    classSuffix: '', // 'dark' クラスを使用
  },
})

レスポンシブブレークポイントが効かない

問題: メディアクエリが正しく動作しない

チェックポイント:

<!-- ブレークポイントの順序を確認 -->
<div class="
  text-sm
  md:text-base  <!-- 768px以上 -->
  lg:text-lg    <!-- 1024px以上 -->
">
  レスポンシブテキスト
</div>

<!-- モバイルファーストなので小→大の順 -->
<!-- ❌ 誤り -->
<div class="lg:text-lg md:text-base text-sm">

<!-- ✅ 正しい -->
<div class="text-sm md:text-base lg:text-lg">

ビルド時のエラー

問題: @apply でエラーが発生

解決策:

<style scoped>
/* ❌ 誤り: 存在しないユーティリティ */
.my-class {
  @apply custom-utility;  /* エラー */
}

/* ✅ 正しい: 定義されたユーティリティのみ使用 */
.my-class {
  @apply flex items-center justify-center;
}

/* または通常のCSSで記述 */
.my-class {
  display: flex;
  align-items: center;
  justify-content: center;
}
</style>

10. まとめと次のステップ

核心的な学び

  1. Tailwind CSS v4のメリット: 高速ビルド、改善された型サポート、最適化されたバンドルサイズ
  2. @applyの適切な使用: 繰り返しパターンのみ抽象化、過度な使用は避ける
  3. レスポンシブデザイン: モバイルファーストアプローチで段階的に拡張
  4. ダークモード: カラースキームを戦略的に設計し、一貫性を保つ
  5. パフォーマンス: 未使用CSS削除、CSS変数活用、JITモードで最適化

避けた落とし穴

  • ❌ すべてのCSSを@applyに変換(可読性低下)
  • ❌ 動的クラス名の生成(Purgeの対象外)
  • ❌ 過度なカスタマイズ(Tailwindの利点を損なう)
  • ❌ グローバルスタイルとの競合を放置

短期的な次のステップ(1-2週間)

  • プロジェクトのコアコンポーネントをTailwind化
  • カスタムカラーパレットの定義と適用
  • レスポンシブデザインの一貫性確認
  • ダークモードの動作検証

中期的な次のステップ(1-2ヶ月)

  • 残りのレガシーCSSをTailwindに移行
  • デザインシステムの構築(コンポーネントライブラリ化)
  • パフォーマンス最適化とビルドサイズ削減
  • アクセシビリティ対応の強化

長期的な次のステップ(3ヶ月以降)

  • Tailwind CSSベースのUIコンポーネントライブラリ構築
  • デザイントークンの体系化とドキュメント化
  • チーム向けのスタイルガイド作成
  • CI/CDでのスタイル自動検証

参考リソース

公式ドキュメント:

関連記事(本サイト内):


この記事が、Tailwind CSS v4を使ったスタイルカスタマイズの参考になれば幸いです。質問やフィードバックがあれば、ぜひコメントやSNSでお寄せください。