# 通知設計書 23-@import/@reference不足エラー

## 概要

本ドキュメントは、Tailwind CSSの`@apply`ディレクティブにおいて、テーマが空（サイズ0）であるためにユーティリティクラスが解決できない場合に、`@import`または`@reference`ディレクティブの不足を示唆するエラー通知の設計を定義する。

### 本通知の処理概要

`@apply`ディレクティブで指定されたユーティリティクラスが見つからず、かつDesignSystemのテーマサイズが0である場合（テーマが一切ロードされていない状態）に、`@import "tailwindcss"`や`@reference`の追加を促すエラーメッセージを出力する通知処理である。

**業務上の目的・背景**：Tailwind CSS v4では、CSSモジュールや分割CSSファイルにおいて`@apply`を使用する場合、テーマ情報を読み込むために`@import "tailwindcss"`または`@reference "app.css"`のようなディレクティブが必要になる。これらのディレクティブが欠落している場合、テーマが空の状態となりユーティリティクラスが一切解決できない。本通知はこの特定の状況を検出し、開発者に具体的な解決策（`@reference`ディレクティブの追加）を公式ドキュメントへのリンク付きで提案する。

**通知の送信タイミング**：CSS生成処理における`@apply`展開フェーズで、`onInvalidCandidate`コールバック内でprefixチェック、ブロックリストチェック、variantチェックをすべて通過した後、`designSystem.theme.size === 0`の判定が行われた時点でエラーがthrowされる。

**通知の受信者**：CLIビルドコマンドまたはPostCSSプラグイン経由でビルドを実行した開発者。特にCSSモジュール（`.module.css`）を使用している開発者に多く発生する。

**通知内容の概要**：`Cannot apply unknown utility class \`{candidate}\`. Are you using CSS modules or similar and missing \`@reference\`?`というメッセージに加え、公式ドキュメントへのリンク（`https://tailwindcss.com/docs/functions-and-directives#reference-directive`）が含まれる。

**期待されるアクション**：開発者は、CSSファイルの先頭に`@reference "tailwindcss"`や`@reference "./app.css"`等のディレクティブを追加して、テーマ情報を読み込む。または`@import "tailwindcss"`を追加する。公式ドキュメントの`@reference`ディレクティブのセクションを参照する。

## 通知種別

ランタイムエラー（`throw new Error`）。ビルド時にCLIのstderrまたはビルドツールのエラー出力としてコンソールに表示される。

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（throwによるエラー伝播） |
| 優先度 | 高（ビルド処理を中断する致命的エラー） |
| リトライ | 無（設定修正が必要） |

### 送信先決定ロジック

ビルドプロセスの呼び出し元に対してエラーが伝播する。CLIの場合はプロセスのstderrに出力され、PostCSSプラグインの場合は`console.error`経由で出力された後、PostCSSのエラーとして再throwされる。

## 通知テンプレート

### メール通知の場合

本通知はメール送信ではなく、コンソールエラー出力である。

| 項目 | 内容 |
|-----|------|
| 送信元アドレス | N/A |
| 送信元名称 | N/A |
| 件名 | N/A |
| 形式 | テキスト（stderr出力） |

### 本文テンプレート

```
Cannot apply unknown utility class `{candidate}`. Are you using CSS modules or similar and missing `@reference`? https://tailwindcss.com/docs/functions-and-directives#reference-directive
```

### 添付ファイル

| ファイル名 | 形式 | 条件 | 説明 |
|----------|------|------|------|
| N/A | N/A | N/A | 添付ファイルなし |

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| candidate | @applyで指定されたユーティリティクラス名 | `@apply`ディレクティブのパラメータ解析結果 | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| ビルド処理 | `@apply`ディレクティブの展開処理 | candidateが未知であり、かつ`designSystem.theme.size === 0`の場合 | テーマ未ロード状態での@apply使用を検出 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| テーマが読み込まれている | `designSystem.theme.size > 0`の場合はこのエラーではなく、汎用の未知ユーティリティエラー（No.24）が出力される |
| 先行するエラーチェックに該当 | prefix/blocklist/variantの各チェックで先にエラーが発生した場合はそちらが優先される |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A["@applyディレクティブ検出"] --> B["compileCandidates実行"]
    B --> C["onInvalidCandidate呼び出し"]
    C --> D["prefixチェック（No.20）"]
    D --> E["blocklistチェック（No.21）"]
    E --> F["variantチェック（No.22）"]
    F --> G{"designSystem.theme.size === 0?"}
    G -->|"Yes"| H["throw new Error（@reference不足エラー）"]
    G -->|"No"| I["汎用未知クラスエラー（No.24）"]
    H --> J["ビルド処理中断"]
    I --> J
```

## データベース参照・更新仕様

### 参照テーブル一覧

| テーブル名 | 用途 | 備考 |
|-----------|------|------|
| N/A | N/A | データベースは使用しない |

### テーブル別参照項目詳細

本通知ではデータベースを参照しない。`designSystem.theme.size`プロパティ（`Theme`クラスの`Map`サイズ）をインメモリで参照する。

### 更新テーブル一覧

| テーブル名 | 操作 | 概要 |
|-----------|------|------|
| N/A | N/A | データベース更新なし |

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| @reference不足エラー | テーマサイズが0でcandidateが見つからない | `@reference "tailwindcss"`等をCSSファイルに追加する |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0（リトライなし） |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A（設定修正が必要） |

## 配信設定

### レート制限

| 項目 | 内容 |
|-----|------|
| 1分あたり上限 | 制限なし |
| 1日あたり上限 | 制限なし |

### 配信時間帯

制限なし。ビルド実行時に即座にエラーが出力される。

## セキュリティ考慮事項

エラーメッセージにはユーティリティクラス名のみが含まれ、個人情報やシークレットは含まれない。外部URLへのリンクが含まれるが、公式ドキュメントへのリンクであるため問題はない。

## 備考

- CSSモジュール（`.module.css`ファイル）では、Tailwind CSSのテーマを直接importすると全体のCSSが出力されてしまうため、`@reference`ディレクティブを使用してテーマ情報のみを読み込むことが推奨される。
- `@reference`はTailwind CSS v4で導入された新しいディレクティブで、CSS出力を生成せずにテーマ情報のみを参照できる。
- `designSystem.theme.size`は`Theme`クラス内部の`Map`のサイズを返し、0の場合はテーマ変数が一切登録されていないことを意味する。

---

## コードリーディングガイド

本通知を理解するために参照すべきファイルと、推奨する読み解き順序を以下に示す。

### 推奨読解順序

#### Step 1: データ構造を理解する

テーマの空判定に使用される`Theme`クラスの構造を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | design-system.ts | `packages/tailwindcss/src/design-system.ts` | `DesignSystem`型の`theme: Theme`フィールド（36行目）。`Theme`クラスは`Map`ベースでありsizeプロパティを持つ |

**読解のコツ**: `Theme`クラスの`size`プロパティは、テーマ変数（`--color-*`, `--spacing-*`等）の登録数を返す。`@import "tailwindcss"`が実行されるとデフォルトテーマが読み込まれてsizeが増加する。

#### Step 2: エントリーポイントを理解する

`@apply`展開処理内でのテーマ空判定ロジックを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | apply.ts | `packages/tailwindcss/src/apply.ts` | 235-239行目のテーマ空判定ブロック。`designSystem.theme.size === 0`でテーマが未ロード状態であることを検出する |

**主要処理フロー**:
1. **232-234行目**: コメントでテーマが空の場合の状況説明
2. **235行目**: `designSystem.theme.size === 0`の判定
3. **236-238行目**: `throw new Error`でエラーメッセージ（`@reference`提案 + ドキュメントURL）を出力

#### Step 3: エラーチェックの実行順序を理解する

このエラーが発生するまでの前段チェックの流れを理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | apply.ts | `packages/tailwindcss/src/apply.ts` | 180-242行目のonInvalidCandidate全体。prefix(182) -> blocklist(196) -> variant(202) -> theme空(235) -> 汎用(242)の順でチェックされる |

### プログラム呼び出し階層図

```
substituteAtApply (apply.ts:10)
    |
    +-- compileCandidates(candidates, designSystem, {...}) (apply.ts:178)
           |
           +-- onInvalidCandidate(candidate) (apply.ts:180)
                  |
                  +-- prefix チェック (apply.ts:182-186)
                  |
                  +-- invalidCandidates チェック (apply.ts:196-199)
                  |
                  +-- variant チェック (apply.ts:202-229)
                  |
                  +-- designSystem.theme.size === 0 (apply.ts:235)
                  |      |
                  |      +-- throw new Error("Cannot apply unknown...missing @reference...") (apply.ts:236-238)
                  |
                  +-- 汎用エラー (apply.ts:242)
```

### データフロー図

```
[入力]                          [処理]                              [出力]

CSSファイル中の            substituteAtApply()              throw new Error
@apply bg-blue-500  ───>   compileCandidates()  ───>       "Cannot apply unknown utility
（@import/@reference       onInvalidCandidate()             class `bg-blue-500`.
  なし）                    theme.size === 0判定             Are you using CSS modules or
                                                            similar and missing `@reference`?
                                                            https://..."
designSystem.theme                                          ↓
  .size = 0         ───>   テーマ空判定               ビルド処理中断
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| apply.ts | `packages/tailwindcss/src/apply.ts` | ソース | @apply展開処理。テーマ空判定エラー（235-238行目） |
| compile.ts | `packages/tailwindcss/src/compile.ts` | ソース | candidateコンパイル処理。onInvalidCandidateコールバック呼び出し |
| design-system.ts | `packages/tailwindcss/src/design-system.ts` | ソース | DesignSystem型定義。themeフィールドを持つ |
| theme.ts | `packages/tailwindcss/src/theme.ts` | ソース | Themeクラスの実装。sizeプロパティを提供 |
