# 画面設計書 4-トップページ

## 概要

本ドキュメントは、Next.js Playgroundのトップページ（`playgrounds/nextjs/app/page.tsx`）の画面設計書である。Next.js App Router構成のホームページコンポーネントであり、CSSモジュール（`page.module.css`）を使用したスタイリングと、`@apply`ディレクティブによるTailwind CSSユーティリティクラスの適用について記述する。

### 本画面の処理概要

本画面は、Next.js Playgroundにおけるルートパス（`/`）に対応するページコンポーネントである。CSSモジュールを通じて`@apply`ディレクティブを使用し、Tailwind CSSのユーティリティクラスを適用する手法のデモを行う。

**業務上の目的・背景**：Tailwind CSS v4の`@apply`ディレクティブ機能が、Next.jsのCSSモジュール環境で正しく動作することを検証するためのデモページである。`@apply skew-7`が`page.module.css`内でTailwind CSSのユーティリティクラスに展開されること、および`@reference`ディレクティブによるglobals.cssの参照が正しく機能することを確認する目的がある。従来のclassName属性での直接適用ではなく、CSSモジュール経由でTailwind CSSを利用するパターンの動作検証を行う。

**画面へのアクセス方法**：Next.js開発サーバー起動後（`next dev`）、ブラウザで`http://localhost:3000/`にアクセスする。No.3レイアウト（layout.tsx）の`{children}`として自動的にマウントされる。

**主要な操作・処理内容**：
1. Next.jsのApp Routerがルートパス（`/`）のリクエストを受信し、`app/page.tsx`をページコンポーネントとして特定する
2. `import styles from './page.module.css'`によりCSSモジュールがインポートされる
3. CSSモジュール内の`@reference "./globals.css"`により、globals.cssのスタイル定義が参照される
4. `@apply skew-7`により、Tailwind CSSの`skew-7`ユーティリティクラスが`.heading`クラスに展開される
5. `<h1 className={styles.heading}>Hello world!</h1>`でスタイル適用済みの見出しが描画される

**画面遷移**：本画面は単一ページ構成であり、他のページへの遷移は存在しない。ルートURL（`/`）のみに対応する。

**権限による表示制御**：認証・認可の仕組みは存在しない。すべてのユーザーが同一の表示内容を閲覧できる。

## 関連機能

| 機能No | 機能名 | 関連種別 | 関連する操作・処理 |
|--------|--------|----------|------------------|
| 24 | @applyの置換（substituteAtApply） | 主機能 | page.module.cssの`@apply skew-7`ディレクティブを検出し、`skew-7`ユーティリティのCSSに展開する |
| 25 | @importの解決（substituteAtImports） | 補助機能 | page.module.cssの`@reference "./globals.css"`により、globals.cssのスタイル定義を参照する |
| 3 | 候補クラスのコンパイル（compileCandidates） | 補助機能 | `@apply skew-7`により指定されたユーティリティクラスのASTノードを生成する |
| 17 | 候補パーサー（parseCandidate） | 補助機能 | `skew-7`のクラス文字列をCandidate構造体に解析する |
| 12 | ユーティリティ登録・生成（Utilities） | 補助機能 | `skew-7`ユーティリティクラスのCSS生成を担当する |

## 画面種別

トップページ（ホームページ）

## URL/ルーティング

- **URL**: `/`（ルート）
- **ルーティング方式**: Next.js App Router。`app/page.tsx`がルートパスに自動的にマッピングされる。

## 入出力項目

本画面にはフォーム入力項目は存在しない。

| 項目名 | 種別 | 説明 |
|--------|------|------|
| なし | - | 入力項目は存在しない |

## 表示項目

| 項目名 | 表示内容 | スタイル | データソース |
|--------|----------|----------|-------------|
| 見出しテキスト | "Hello world!" | `styles.heading`（CSSモジュール: `@apply skew-7` = transform: skewX(7deg)） | page.tsx 4行目 |

## イベント仕様

### 1-サーバーサイドレンダリング

1. Next.jsのApp Routerがルートパス（`/`）へのリクエストを受信する
2. `app/page.tsx`のHome関数コンポーネントがサーバーサイドで実行される
3. CSSモジュール（page.module.css）がPostCSSパイプラインで処理される：
   - `@reference "./globals.css"`によりglobals.cssのTailwind CSS定義が参照される
   - `@apply skew-7`が`skew-7`ユーティリティのCSSプロパティに展開される
4. JSXが`<h1>`要素として出力され、CSSモジュールのハッシュ化されたクラス名が適用される
5. No.3レイアウト（layout.tsx）の`{children}`に挿入され、完全なHTMLレスポンスが生成される

## データベース更新仕様

### 操作別データベース影響一覧

| 操作（イベント） | 対象テーブル | 操作種別 | 概要 |
|----------------|-------------|---------|------|
| なし | - | - | 本画面はデータベースを使用しない |

## メッセージ仕様

| メッセージID | 種別 | メッセージ内容 | 表示条件 |
|-------------|------|---------------|----------|
| なし | - | - | 本画面にメッセージ表示機能は存在しない |

## 例外処理

| 例外状況 | 動作 | ユーザーへの影響 |
|----------|------|----------------|
| CSSモジュールの読み込み失敗 | `styles.heading`が`undefined`となり、className属性が空になる | 見出しにスタイルが適用されない（デフォルトのh1スタイルで表示） |
| @applyディレクティブの解決失敗 | PostCSSパイプラインでエラーが発生し、ビルドが失敗する | ページが表示されない |
| @referenceの参照先が見つからない | globals.cssの参照が解決できず、@apply内のユーティリティクラスが認識されない | skewスタイルが適用されない |

## 備考

- `@reference`ディレクティブはTailwind CSS v4の機能であり、CSSモジュール環境で別のCSSファイルのスタイル定義を参照するために使用される。`@import`と異なり、参照先のCSSは出力に含まれず、`@apply`の解決にのみ使用される
- `skew-7`は`transform: skewX(7deg)`に相当するTailwind CSSユーティリティクラスである
- CSSモジュールにより、`.heading`クラスは自動的にハッシュ化されたユニークなクラス名に変換される（例: `heading_abc123`）
- `export default function Home()`としてデフォルトエクスポートされており、Next.js App Routerの規約に従っている

---

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

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

### 推奨読解順序

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

CSSモジュールと`@apply`ディレクティブの関係を把握する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 1-1 | page.module.css | `playgrounds/nextjs/app/page.module.css` | 1行目: `@reference "./globals.css"`でglobals.cssのTailwind CSS定義を参照 |
| 1-2 | page.module.css | `playgrounds/nextjs/app/page.module.css` | 3-5行目: `.heading`クラスに`@apply skew-7`でTailwind CSSユーティリティを適用 |
| 1-3 | globals.css | `playgrounds/nextjs/app/globals.css` | 1行目: `@import 'tailwindcss'`が`@apply`で参照されるユーティリティ定義の基盤 |

**読解のコツ**: `@reference`は`@import`と異なり、参照先のCSSを出力に含めない。CSSモジュール内で`@apply`を使用するためにTailwind CSSの定義を認識させる目的で使用される。これはTailwind CSS v4固有の機能である。

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

ページコンポーネントの実装を確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 2-1 | page.tsx | `playgrounds/nextjs/app/page.tsx` | 1行目: `import styles from './page.module.css'`でCSSモジュールをインポート |
| 2-2 | page.tsx | `playgrounds/nextjs/app/page.tsx` | 3行目: `export default function Home()`でデフォルトエクスポート |
| 2-3 | page.tsx | `playgrounds/nextjs/app/page.tsx` | 4行目: `<h1 className={styles.heading}>Hello world!</h1>`でスタイル適用 |

**主要処理フロー**:
1. **page.tsx:1行目**: CSSモジュールをインポート。PostCSSパイプラインが`page.module.css`を処理
2. **page.tsx:3行目**: Next.js App Routerのページコンポーネントとしてデフォルトエクスポート
3. **page.tsx:4行目**: `styles.heading`でCSSモジュールのクラス名（ハッシュ化済み）を参照

#### Step 3: @applyディレクティブの処理を理解する

Tailwind CSSの`@apply`が実際にどのように処理されるかを確認する。

| 順序 | ファイル | パス | 読解ポイント |
|-----|---------|------|-------------|
| 3-1 | index.ts（tailwindcss） | `packages/tailwindcss/src/index.ts` | 2行目: `import { substituteAtApply } from './apply'`で@apply処理モジュールをインポート |
| 3-2 | index.ts（tailwindcss） | `packages/tailwindcss/src/index.ts` | 24行目: `compileCandidates`のインポート。@applyで指定されたクラスのCSS生成 |

**主要処理フロー**:
- **packages/tailwindcss/src/index.ts:2行目**: `substituteAtApply`モジュールのインポート
- PostCSSパイプラインがCSSモジュールを処理する際、`@apply skew-7`を検出
- `parseCandidate("skew-7")`でCandidate構造体に解析
- `compileCandidates`でASTノードを生成し、`.heading`クラス内のCSS宣言に展開

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

```
page.tsx (Home)
    |
    +-- import styles from './page.module.css'
    |       |
    |       +-- PostCSS パイプライン
    |               |
    |               +-- @reference "./globals.css"
    |               |       +-- globals.css (@import 'tailwindcss')
    |               |               +-- substituteAtImports() [Tailwind CSS定義の解決]
    |               |
    |               +-- @apply skew-7
    |                       +-- substituteAtApply() [packages/tailwindcss/src/apply.ts]
    |                               |
    |                               +-- parseCandidate("skew-7")
    |                               +-- compileCandidates()
    |                               +-- Utilities.generate() [skew-7のCSS生成]
    |
    +-- <h1 className={styles.heading}>
            +-- CSSモジュールのハッシュ化クラス名が適用
```

### データフロー図

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

page.module.css      ------>  PostCSS パイプライン       ------>  コンパイル済みCSSモジュール
  @reference                   |
  @apply skew-7                +-> @reference解決
                               |     +-> globals.css参照
                               +-> substituteAtApply()
                               |     +-> parseCandidate("skew-7")
                               |     +-> compileCandidates()
                               +-> CSSモジュール変換
                                     +-> .heading -> .heading_xxx

page.tsx             ------>  Next.js SSR              ------>  HTML
  styles.heading               (サーバーサイド                    <h1 class="heading_xxx">
  "Hello world!"                レンダリング)                     Hello world!</h1>
```

### 関連ファイル一覧

| ファイル | パス | 種別 | 役割 |
|---------|------|------|------|
| page.tsx | `playgrounds/nextjs/app/page.tsx` | ソース | トップページコンポーネント。CSSモジュール経由でスタイル適用 |
| page.module.css | `playgrounds/nextjs/app/page.module.css` | スタイル | CSSモジュール。@reference + @applyによるTailwind CSS統合 |
| globals.css | `playgrounds/nextjs/app/globals.css` | スタイル | グローバルCSS。@import 'tailwindcss'によるTailwind CSS定義 |
| layout.tsx | `playgrounds/nextjs/app/layout.tsx` | ソース | ルートレイアウト。本ページを{children}として内包 |
| postcss.config.js | `playgrounds/nextjs/postcss.config.js` | 設定 | PostCSSプラグイン設定 |
| package.json | `playgrounds/nextjs/package.json` | 設定 | 依存関係定義 |
| index.ts | `packages/tailwindcss/src/index.ts` | ソース | Tailwind CSSコア。substituteAtApply、compileCandidates等 |
| index.ts | `packages/@tailwindcss-postcss/src/index.ts` | ソース | PostCSSプラグイン実装 |
