# 通知設計書 14-無効なprefix形式警告

## 概要

本ドキュメントは、Tailwind CSSの互換性フック適用時に、prefixの末尾にハイフンが含まれる不正な形式の場合に`console.warn`で警告を出力する通知の設計を記述する。

### 本通知の処理概要

v3互換性フック（compat hooks）の適用処理において、JavaScriptの設定ファイルから読み込まれたprefixの形式を検証し、末尾にハイフン（`-`）が含まれる場合に警告メッセージを出力しつつ、自動修正を行う処理である。

**業務上の目的・背景**：Tailwind CSS v4では、prefixの仕様がv3から変更された。v3ではprefix末尾にハイフンを含める形式（例：`tw-`）が一般的だったが、v4ではハイフンなしの形式（例：`tw`）に変更された。prefixはvariantとして記述される。この警告により、v3の設定をそのまま使用している開発者に対して形式変更を通知し、設定の移行を支援する。自動修正として末尾ハイフンを除去する。

**通知の送信タイミング**：CSSコンパイル処理中に互換性フックを適用する際、JavaScriptの設定ファイルから読み込まれたprefix設定を評価するタイミングで送信される。具体的には`apply-compat-hooks.ts`の364行目付近でのprefix検証時。

**通知の受信者**：Tailwind CSSを設定・使用している開発者。コンソール（stderr）を通じて警告が表示される。

**通知内容の概要**：不正なprefixの値、有効なprefix形式（小文字ASCII文字のみ）の説明、および末尾ハイフンの除去を促すメッセージが出力される。

**期待されるアクション**：開発者はJavaScript設定ファイル（tailwind.config.js等）のprefix設定から末尾のハイフンを除去する。例：`prefix: "tw-"` を `prefix: "tw"` に変更する。

## 通知種別

コンソール警告（console.warn / stderr）

## 送信仕様

### 基本情報

| 項目 | 内容 |
|-----|------|
| 送信方式 | 同期（console.warn による即時出力） |
| 優先度 | 中 |
| リトライ | なし |

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

`console.warn`による標準エラー出力への直接出力。動的な送信先決定ロジックは存在しない。

## 通知テンプレート

### メール通知の場合

該当なし（コンソール警告のみ）

### 本文テンプレート

```
The prefix "{修正後のprefix}" is invalid. Prefixes must be lowercase ASCII letters (a-z) only and is written as a variant before all utilities. We have fixed up the prefix for you. Remove the trailing `-` to silence this warning.
```

注意：メッセージ中の`{修正後のprefix}`は、末尾ハイフンを除去した後の値（`resolvedConfig.prefix`の`slice(0, -1)`結果）である。

### 添付ファイル

該当なし

## テンプレート変数

| 変数名 | 説明 | データ取得元 | 必須 |
|--------|------|-------------|-----|
| resolvedConfig.prefix | 設定ファイルのprefix値（ハイフン除去後） | JavaScript設定ファイル（resolvedConfig） | Yes |

## 送信トリガー・条件

### トリガー一覧

| トリガー種別 | トリガーイベント | 送信条件 | 説明 |
|------------|----------------|---------|------|
| コンパイル処理 | 互換性フック適用時のprefix検証 | resolvedConfig.prefix.endsWith('-') === true | apply-compat-hooks.ts 364行目 |

### 送信抑止条件

| 条件 | 説明 |
|-----|------|
| CSSで既にprefixが設定されている場合 | designSystem.theme.prefixが既に設定済みの場合はJS設定のprefixを適用しない（363行目） |
| resolvedConfig.prefixが未設定の場合 | prefix設定がない場合は検証をスキップ（363行目） |
| 末尾がハイフンでない場合 | 正常なprefix形式の場合は警告をスキップ |

## 処理フロー

### 送信フロー

```mermaid
flowchart TD
    A[互換性フック適用処理] --> B{CSSでprefix設定済み?}
    B -->|Yes| Z[スキップ]
    B -->|No| C{resolvedConfig.prefix あり?}
    C -->|No| Z
    C -->|Yes| D{prefix末尾がハイフン?}
    D -->|No| E{IS_VALID_PREFIX テスト}
    D -->|Yes| F[末尾ハイフンを除去]
    F --> G[console.warn: 不正prefix警告]
    G --> E
    E -->|合格| H[designSystem.theme.prefix に設定]
    E -->|不合格| I[throw Error: 不正なprefix]
```

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

### 参照テーブル一覧

該当なし（データベースは使用しない）

### 更新テーブル一覧

該当なし（データベースは使用しない）

## エラー処理

### エラーケース一覧

| エラー種別 | 発生条件 | 対処方法 |
|----------|---------|---------|
| 末尾ハイフン付きprefix | prefix末尾にハイフンがある場合 | 自動修正＋警告（ハイフン除去） |
| 不正なprefix文字 | IS_VALID_PREFIXテストに不合格 | throw Errorでプロセス停止 |

### リトライ仕様

| 項目 | 内容 |
|-----|------|
| リトライ回数 | 0 |
| リトライ間隔 | N/A |
| リトライ対象エラー | N/A（警告のみ。自動修正後に処理は継続） |

## 配信設定

### レート制限

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

### 配信時間帯

制限なし（CSSコンパイル時に随時出力）

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

prefix値（英字のみ）が出力されるのみであり、機密情報の漏洩リスクはない。

## 備考

- 自動修正により末尾ハイフンが除去されるため、CSSの生成は継続される（365行目）
- 自動修正後のprefixがIS_VALID_PREFIXテスト（小文字ASCII文字のみ）に合格しない場合はError例外がスローされる（372-376行目）
- CSSの`@theme prefix(...)`で既にprefixが設定されている場合はJSの設定は無視される（363行目）
- IS_VALID_PREFIX正規表現による検証は自動修正後にも適用される

---

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

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

### 推奨読解順序

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

resolvedConfigのprefix設定とdesignSystem.theme.prefixの関係を理解する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | apply-compat-hooks.ts | `packages/tailwindcss/src/compat/apply-compat-hooks.ts` | 363行目: prefix設定の前提条件 |

**読解のコツ**: `resolvedConfig`はJavaScript設定ファイルから解決された設定オブジェクトであり、`designSystem.theme.prefix`はCSSレベルでのprefix設定。両者の優先順位に注目。

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

互換性フック適用の流れとprefix検証の位置づけを特定する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | apply-compat-hooks.ts | `packages/tailwindcss/src/compat/apply-compat-hooks.ts` | 355-378行目: prefix設定と検証のブロック全体 |

**主要処理フロー**:
1. **363行目**: `!designSystem.theme.prefix && resolvedConfig.prefix`の前提条件チェック
2. **364行目**: `resolvedConfig.prefix.endsWith('-')`で末尾ハイフンチェック
3. **365行目**: `resolvedConfig.prefix.slice(0, -1)`で末尾ハイフン除去
4. **367-369行目**: console.warnで警告メッセージ出力
5. **372行目**: IS_VALID_PREFIX正規表現テスト
6. **373-376行目**: テスト不合格時にthrow Error
7. **378行目**: `designSystem.theme.prefix`に値を設定

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

```
applyCompatHooks() [apply-compat-hooks.ts]
    |
    +-- resolvedConfig.prefix チェック [363行目]
            |
            +-- endsWith('-') チェック [364行目]
            |       |
            |       +-- slice(0, -1) [365行目]
            |       +-- console.warn() [367-369行目]
            |
            +-- IS_VALID_PREFIX.test() [372行目]
            |       |
            |       +-- [不合格] throw Error [373-376行目]
            |
            +-- designSystem.theme.prefix = prefix [378行目]
```

### データフロー図

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

tailwind.config.js     --->  resolvedConfig.prefix    --->  [末尾ハイフンあり]
  prefix: "tw-"                    |                              |
                                   v                              v
                            endsWith('-')             console.warn (stderr)
                                   |                   + 自動修正 (slice)
                                   v
                            IS_VALID_PREFIX.test()    --->  designSystem.theme.prefix
                                                            または throw Error
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| apply-compat-hooks.ts | `packages/tailwindcss/src/compat/apply-compat-hooks.ts` | ソース | 互換性フック適用処理（prefix検証・自動修正・警告出力） |
| design-system.ts | `packages/tailwindcss/src/design-system.ts` | ソース | DesignSystem定義（theme.prefix プロパティ） |
