Panda CSS 設計書

最終更新: 2026-11-06（既知の基準未達に、OG のカードの文字の実効の比を追加、MorningStatusApp#1805）

1. 概要

フォールダブル端末・広画面対応（MorningStatusApp#1648）を契機に導入した Panda CSS のセットアップ内容と、既存スタック（Tailwind CSS v4・CSS Modules・app/globals.css）との共存方式を扱う設計書（MorningStatusApp#1655）。

Panda CSS は Zero-Runtime（ビルド時にCSSを静的生成する）かつ TypeScript の型補完が効くスタイリングライブラリ。フォールダブル端末の展開判定（~580px付近）のようなカスタムブレークポイントを型安全に扱える点、および Next.js App Router との親和性を理由に採用した。

実際にコンポーネント・画面へ Panda CSS を適用していく段階移行の範囲は本書の対象外で、MorningStatusApp#1656 側で決定する。本書は、その前提となる「導入設定」と「既存スタックとの共存方式」の確定内容に限定する。長期的にはTailwind CSSを撤去しPanda CSS単独の構成へ移行する方針であり、その位置づけは§5を参照。

Panda CSS の活用方針と配色トークンの設計は§8を参照。

2. セットアップ内容

• 依存関係: @pandacss/dev を devDependency として追加
• 設定ファイル: リポジトリルートの panda.config.ts
  • include: ./app/**/*.{js,jsx,ts,tsx} と ./components/**/*.{js,jsx,ts,tsx}（Next.js App Router のディレクトリ構成に合わせる。panda init の初期値である src/・pages/ はこのプロジェクトでは使わない）
  • preflight: false（§3-1参照）
  • outdir: "styled-system"（生成物。.gitignore に追加し、コミット対象外とする。bunx panda codegen または後述のPostCSSプラグインがビルド時に自動生成する）
  • プリセット: presets: ["@pandacss/preset-base", "@pandacss/preset-panda"] を明示し、両パッケージを devDependency として追加する。Panda CSS v2 ではプリセットが暗黙に追加されないため、明示しないと md・fold などのブレークポイントが条件として認識されず、css() の md: { ... } 指定が一切適用されない
• PostCSS統合: postcss.config.mjs の plugins に @tailwindcss/postcss と並べて @pandacss/dev/postcss を追加。panda init --postcss は初期状態で postcss.config.cjs を別ファイルとして生成するため、既存の postcss.config.mjs に統合し、重複するPostCSS設定ファイルを残さないこと
• app/globals.css の @import "tailwindcss"; の直後に @layer reset, base, tokens, recipes, utilities; を追加。@pandacss/dev/postcss はビルド時にこの宣言の位置へ生成CSSを注入する

3. Tailwind CSS v4 との共存方式

3-1. カスケードレイヤーの優先順位

Tailwind CSS v4 は @import "tailwindcss" の展開により @layer theme, base, components, utilities; を、Panda CSS は @layer reset, base, tokens, recipes, utilities; をそれぞれ宣言する。CSSの @layer は同名レイヤーであれば宣言位置に関わらず1つに統合され、初出のレイヤー名だけがその位置に新規追加される仕様のため、実際のレイヤー優先順位（低→高）は次のようになる。

theme < base(Tailwind+Panda共有) < components < utilities(Tailwind+Panda共有) < reset < tokens < recipes

base と utilities は Tailwind・Panda 両方が同名レイヤーを使うため統合され、レイヤー内では後から追加されたCSSほど優先される（globals.css 内で Tailwind の @import より Panda の @layer 宣言が後にあるため、同一プロパティが競合した場合は Panda 側の指定が勝つ）。実機検証（Playwright、class="bg-red-500" と css({ bg: "blue.500" }) を同一要素に適用）でも Panda側が優先されることを確認済。

備考: Panda の preflight（ブラウザデフォルトスタイルのリセット）は false に設定している。Tailwind v4 が @import "tailwindcss" により自前の preflight を base レイヤーへ既に注入しており、二重適用を避けるため。

3-2. レイヤー外（unlayered）CSSは常に最優先

app/globals.css の :root 変数定義や *, html, body 等、@layer で囲まれていないCSSは、CSS仕様上どの @layer 内のCSSよりも常に優先される。既存のグラスモーフィズム等のカスタムスタイルはこの位置にあり、Panda・Tailwindいずれのユーティリティクラスとも衝突しない。

3-3. .container → .app-container への改名と、Panda化の経緯（重要な注意点）

備考（バグとして顕在化した問題と対策）: 共通レイアウトの最大幅（1200px）を実現していた独自クラス .container（app/globals.css、app/layout.tsx 等）を Panda 化する過程で、2段階の技術的な非互換が技術検証中に判明した。

問題1（クラス名の衝突）: .container という名前のまま Panda の globalCss に移行したところ、幅1920pxで通常画面のmax-widthが意図しない1536pxになった。原因は、Tailwind CSS v4 が @import "tailwindcss" により、ソース内で container というクラス名トークンが使用されていると、組み込みのレスポンシブ .container ユーティリティ（@layer utilities、ブレークポイントごとに max-width が変わる）を自動生成するため。移行前は独自の .container が @layer の外（unlayered）にあり §3-2 の理由で常に最優先されていたため問題にならなかったが、Panda の globalCss（base レイヤー）に移した時点で、より優先度が高い utilities レイヤーにある Tailwind組み込み .container に負けるようになった。

→ 対策として、クラス名を .app-container に改名し、Tailwindの組み込み .container と名前の衝突を避けた（ソース上のトークンcontainerが無くなることで、TailwindのJITスキャンが組み込みユーティリティを生成しなくなる効果もある）。

問題2（プロジェクト自身のレイヤー外リセットとの衝突。改名だけでは解決しない）: .app-container に改名した後も、padding/margin が 0 になる不具合が残った。原因は、app/globals.css の * { box-sizing: border-box; padding: 0; margin: 0; } という、このプロジェクト自身が持つレイヤー外のリセットCSS。§3-2の通りレイヤー外CSSは常に最優先されるため、Panda の globalCss（レイヤー内）に置いた .app-container の padding/margin 指定は、詳細度に関わらずこのリセットに負ける。Tailwindとは無関係に、「レイヤー外CSSを前提にした既存の globals.css の構造」と「Panda の globalCss（レイヤー内）」がそもそも噛み合わないという、より根本的な非互換であることが分かった。

当初の対応（#1655時点）: .app-container のクラス名改名は維持しつつ、CSS定義自体はPandaのglobalCssに移さず、従来通りapp/globals.cssへレイヤー外の生CSSとして書く方針とした。globals.css 側のレイヤー外リセット構造ごと見直す（全廃してPanda/Tailwindのレイヤー体系に揃える）選択肢も検討したが、影響が全画面に及ぶ大改修になるため#1655の範囲外とした。

解決（#1667）: Tailwind撤去（#1656）により @layer reset, base, tokens, recipes, utilities; の宣言順がPanda単独で完全に確定した後、問題2の根本原因だった app/globals.css の * {...} リセットを、レイヤー外の生CSSから明示的に @layer reset { * {...} } へ移した。宣言順（reset が最初＝最も低優先度、base がその次）により、Pandaの globalCss（base レイヤーに出力される）が reset レイヤーより優先されるようになったため、.app-container のCSS定義をPandaの globalCss（panda.config.ts）へ安全に移行できた。Playwrightで getComputedStyle・getBoundingClientRect を計測し、デスクトップ幅（padding: 0 2rem・中央寄せ）・モバイル幅（padding: 0 1rem）・世代マトリックス画面のワイドキャンバス例外（max-width: none）のいずれも意図通り動作することを実機検証済。

.app-container の実体は次の通り（panda.config.ts の globalCss。#1667でレイヤー外の生CSSから移行済）。

globalCss: {
  ".app-container": {
    maxWidth: "1200px",
    marginX: "auto",
    padding: "0 1rem",
    md: {
      padding: "0 2rem",
    },
  },
  "main.app-container:has(> [data-wide-canvas])": {
    maxWidth: "none",
  },
},

app/globals.css の * {...} リセットは @layer reset { ... } へ移行済（レイヤー外の生CSSとしては残っていない）。

ワイドキャンバス例外（世代マトリックス画面のみ最大幅を外す仕組み）の考え方自体は変更していない。世代マトリックス 画面設計書 §4-8を参照。data-wide-canvas 属性をページ直下に付与する実装（app/generational-matrix/page.tsx）も変更なし。

影響を受けた参照元（className="container" → className="app-container" に改名）: app/layout.tsx（header・main・footer）、app/ameba/page.tsx、app/instagram/page.tsx、app/instagram/[accountId]/page.tsx、app/tiktok/page.tsx、app/tiktok/official/[accountId]/page.tsx、app/tiktok/og/[memberId]/page.tsx、app/youtube/page.tsx、app/youtube/official/page.tsx、app/youtube/og/[memberId]/page.tsx。

4. カスタムブレークポイント（fold）

フォールダブル端末の展開時（~580px付近）を判定するため、panda.config.ts の theme.extend.breakpoints に fold: "36.5rem"（584px 相当）を追加した。Panda のブレークポイントは min-width ベース（モバイルファースト）で解釈されるため、CLAUDE.mdのモバイルファースト規約と自然に合致する。

theme: {
  extend: {
    breakpoints: {
      fold: "36.5rem",
    },
  },
},

デフォルトのブレークポイント（sm・md・lg・xl・2xl）は extend により維持される。36.5rem（= 584px）という値は、Samsung Galaxy Fold系の展開時インナーディスプレイ幅を目安とした一般的な業界慣行値。単位は他のブレークポイントに合わせて rem とした。Panda CSS v2 は単位の混在を警告する。

このブレークポイントを一覧画面のグリッド実装で採用するかどうかの検証結果は§6-2を参照（結論としては列数変更には使用していない）。

5. 段階移行の方針と将来方針

本書§1〜4のセットアップと .app-container（ワイドキャンバス機構。§3-3の理由によりCSS定義自体は globals.css に残す）は #1655 の対応範囲。それ以外のコンポーネント・画面をPanda化する範囲・優先順位は、本書で確立した共存方式をもとに MorningStatusApp#1656（一覧画面のグリッド実装。§6参照）で対応する。

将来方針: Tailwind CSS の撤去とPanda CSS単独化

§3-3で判明した2つの非互換（Tailwind組み込みユーティリティとの命名衝突、globals.css のレイヤー外リセットとの構造的な非互換）は、いずれも「TailwindとPandaが同居し、かつ globals.css にレイヤー外CSSが残っている」という過渡的な状態に起因する。共存を維持し続けるコストを避けるため、Tailwind CSS v4 を撤去し、Panda CSS単独の構成へ移行する方針とする。

備考（#1656実装時に判明した記載の誤り）: 当初、この撤去作業の対象は「#1655時点の調査でapp/・components/配下223ファイル中25ファイルがTailwindのユーティリティクラスを使用」としていたが、#1656実装着手時にclassName・テンプレートリテラル・clsx等あらゆるパターンで網羅的に再調査した結果、実際にTailwindユーティリティクラスを使用していたのはcomponents/PageLoadingSkeleton.tsxのanimate-pulse1箇所のみだった。「25ファイル」の根拠となる調査方法の記録は残っておらず、過度に広い検索パターンによる誤検出だった可能性がある。撤去作業自体はanimate-pulseの置き換えと依存関係・設定の削除で完了しており、実害はない。

なお、Tailwind撤去そのものはglobals.cssのレイヤー外リセットとの構造的な非互換（§3-3の問題2）を自動的には解消しないため、.app-containerのPanda化は本Issueの範囲外としてMorningStatusApp#1667 へ切り出した。#1667では、リセット自体を@layer resetへ移すことで問題2を解消し、.app-containerのPanda化を完了している（詳細は§3-3参照）。

6. 一覧画面のレスポンシブグリッド実装パターン（#1656）

対象画面は、既に style={{ display: "grid", gridTemplateColumns: "repeat(auto-fill, minmax(Npx, 1fr))" }} というインラインstyleでグリッドを実装していたが、auto-fill は画面幅に応じて列数が連続的に変化するため、CLAUDE.mdのモバイルファースト規約（「CSS Grid はモバイルファーストで実装する」節）が求める「デフォルト1列、768px以上で複数列」という明確な切り替え点を持たない。Panda CSSのcss()に移行するタイミングで、この切り替え点を明示する。

6-1. 対象画面

• Instagram一覧画面（app/instagram/page.tsx）
• Instagram公式アカウント管理（デスクトップモード、Instagram一覧画面内）（components/InstagramOfficialAccountsEditor.tsx）
• Instagram公式アカウント詳細画面（app/instagram/[accountId]/page.tsx・components/OfficialInstagramSection.tsx）
• TikTok一覧画面（app/tiktok/page.tsx）
• TikTok公式アカウント管理（デスクトップモード、TikTok一覧画面内）（components/TikTokOfficialAccountsEditor.tsx）
• TikTok公式アカウント詳細画面（app/tiktok/official/[accountId]/page.tsx）
• TikTok OGメンバー投稿画面（app/tiktok/og/[memberId]/page.tsx）
• YouTube一覧画面（app/youtube/page.tsx）
• YouTube公式チャンネル一覧画面（app/youtube/official/page.tsx）
• YouTube OGメンバー投稿画面（app/youtube/og/[memberId]/page.tsx）
• メンバー一覧画面（components/MembersListView.tsx）
• ユニット一覧画面（app/units/page.tsx）
• メンバー詳細画面のInstagram/TikTok/YouTubeセクション（components/member-detail/InstagramSection.tsx・TikTokSection.tsx・YoutubeSection.tsx）
• トップ画面の新着投稿セクション（components/NewPostsSection.tsx）
• 対比詳細画面の楽曲グリッド（app/comparisons/[id]/page.tsx）

既存にグリッドパターンが無く新規のカードレイアウト設計が必要な画面（ライブ一覧・Amebaブログ一覧）は対象外とし、MorningStatusApp#1666 として別途切り出した。

6-2. 実装パターン

import { css } from "@/styled-system/css";

<div
  className={css({
    display: "grid",
    gridTemplateColumns: "1fr",
    gap: "1.5rem",
    md: {
      gridTemplateColumns: "repeat(auto-fill, minmax(280px, 1fr))",
    },
  })}
>

• デフォルト（モバイル幅）は 1fr の1列固定。md（768px、Pandaのデフォルトブレークポイント）以上で、従来と同じ auto-fill, minmax() に切り替える（768px以上では画面幅に応じた自然な列数調整を維持する）
• minmax() の最小幅（カード1枚あたりの幅）は画面ごとに異なるため、既存のインラインstyleに指定されていた値をそのまま踏襲する（例: SNS投稿一覧は140px〜200px、公式アカウント一覧・メンバー一覧・ユニット一覧は280px、対比曲グリッドは360px等）
• fold（36.5rem = 584px）ブレークポイントは、md（768px）に達する前の中間段階での列数変更には使わない。参考実装（app/timeline/page.module.css）も単一のブレークポイント（768px）のみで1列⇔複数列を切り替えており、この慣例に合わせる。フォールダブル端末の展開時（~580px〜768px）は引き続き1列で表示され、レイアウトが崩れないことを実機・シミュレータで検証する

7. 新規カードグリッド設計（ライブ一覧・Amebaブログ一覧、#1666）

§6の対象画面は既存のグリッドパターンをPanda化するだけだったが、以下の画面は元々グリッド自体が存在しない縦積みリストだったため、カードレイアウトを新規に設計した。

7-1. Amebaブログ一覧（app/ameba/page.tsx）

各行が既に.glassクラス（角丸・背景あり）でカード状のスタイルを持っていたため、新規デザインは行わず、flex-direction: column（縦1列固定）を§6-2と同じパターン（デフォルト1列、mdでauto-fill, minmax(280px, 1fr)）に置き換えるのみとした。

7-2. ライブ一覧（年別 app/lives/year/[year]/page.tsx・都道府県別 components/PrefectureLiveEventsSection.tsx）

各公演は罫線区切りの1行（日付・時刻・会場名リンク・都道府県/ツアー名）で、カード化されていなかった。表示項目は変更せず、各行に.glassクラス（角丸・背景）を付与して軽量カード化した上で、グリッド化した。

import { css } from "@/styled-system/css";

<ul
  className={css({
    display: "grid",
    gridTemplateColumns: "1fr",
    gap: "0.75rem",
    md: {
      gridTemplateColumns: "1fr 1fr",
    },
  })}
>
  <li className="glass" style={{ /* 既存のborderBottom区切りをやめ、padding・borderRadiusのみに変更 */ }}>
    {/* 日付・時刻・会場名リンク・都道府県/ツアー名は変更なし */}
  </li>
</ul>

• auto-fill, minmax()ではなく、1fr 1frの固定2列とした。個々の公演行が短い1行情報（日付・会場名・都道府県）のため、app/timeline/page.module.cssの.eventGrid（grid-template-columns: 1fr 1fr）と同じ考え方を踏襲する
• gapは.eventGridの1.5remより詰めた0.75remとした。踏襲するのは列数の切り替え方針のみで、カード自体が軽量・低情報量なため間隔は独自に調整している
• Playwrightで実機検証（モバイル375px: 1列、デスクトップ1280px: 2列）し、レイアウト崩れがないことを確認済

対象外のapp/lives/page.tsx（年ごとの一覧リンクへの入口）・app/lives/prefecture/[code]/page.tsx（都道府県名・出身メンバーバッジのみ、実データ表示はPrefectureLiveEventsSectionに委譲）は、リスト自体が短い（年数・都道府県コード程度）ため対象外。

8. 配色トークンの設計（#1745）

配色を Panda CSS のトークンで管理し、ダーク／ライトモード（MorningStatusApp#1735）を実現するための設計。

8-1. 方針

• 配色は panda.config.ts の theme.extend.semanticTokens.colors に定義する
• すべてのトークンにダークの値を定義する。ダークの値が標準の配色で、ライトの値は別に定義する。ダークの値だけで、ライトの値がなくても色が決まる。ライトとダークで同じ値の色（ブランドカラー等）には、ライトの値を定義しない
• ダーク／ライトの切り替え方式は §8-6、ライトの配色は §8-8 に定める
• インライン style の css() への移行は、配色トークンとは別に扱う。CSS Modules を含めた移行と、カード・チップのレシピ化は、配色トークンを定義したあとに検討する

8-2. 既存の変数の別名

app/globals.css の :root にある色の変数 12 個は、次のトークンが出力する変数への別名にする。別名は :root { --text-muted: var(--colors-text-muted); } の形で、レイヤー外の生 CSS として書く。既存の使用箇所は書き換えない。フォントの変数 2 個は対象外とする。

8-3. ライトモードの要件

• 色は、すべてトークン経由（var(--colors-…)）で指定する
• カテゴリ色分け辞書（4 つ）の色は、ライトの背景で読めるコントラストを確保する
• 入力系コンポーネント（<input>・<textarea>・<select>）に、背景色と文字色を明示する（開発ノート「UI/UX設計」知見 4）
• ダーク／ライトの切り替えは、<html> のクラスと color-scheme で行う（§8-6）

カテゴリ色分け辞書のトークン

カテゴリ色分け辞書 4 つの色は、辞書ごとのトークンで持つ（計 25 個）。すべてにダークの値を定義する。辞書をまたいで同じ色になるトークンも、辞書ごとに別のトークンとして持つ（辞書は別々の場面で使われる独立した体系のため）。名前は、Panda が出す変数名（トークン名の . を - にしたもの）と一致するよう kebab-case にする。

辞書の値は、var(--colors-event-type-live) のような変数の参照を、文字列として直接書く。辞書はクライアント側のコードからも使われるため、トークン表を丸ごと読み込む token.var()（styled-system/tokens）ではなく、文字列を書く。辞書にないキーの色は var(--colors-category-fallback) とする。参照先の打ち間違いは、test/color-tokens.test.ts で、panda.config.ts に定義されたトークンと突き合わせて検出する。

背景の透明色

辞書の色の背景色（`${色}22` のように 16 進数の透明度 22 を連結する作り方）は、color-mix(in srgb, ${色} 13.33%, transparent) で作る。22 は 34/255（約 13.33%）の不透明度で、16 進数のメンバーカラーと、var() で参照する辞書の色のどちらにも同じ書き方で使える。

透かす不透明度は、用途ごとに決める。withOpacity(色, 不透明度)（lib/color-utils.ts）が color-mix(in srgb, ${色} <不透明度>, transparent) を返し、背景の透かし（tintBackground()）は、不透明度 13.33% の withOpacity() である。年表のクロニクル表示では、ツアーの枠を 30%、節目（加入・卒業・リーダー）の背景を 15% にする。`${色}4d` のように 16 進数の透明度を連結する作り方は、var() の色に使えないため、withOpacity() で作る。

辞書以外の追加トークン

辞書の色以外のトークンは、次のとおり。すべてにダークの値を定義する。

共通のトークン（白の透過・黒の透過・白）

画面をまたいで使う色のトークン。すべてにダークの値を定義する。変数名は --colors- に、トークンのパスを - でつないだ名前を続ける（例: overlay.85 は --colors-overlay-85）。ライトの値は §8-8 に定める。

白い文字のトークンは、背景で選ぶ。overlay.* の面（パネル、ボタンの背景など）の上で、ライトモードでは黒系に反転させる文字には、overlay.100（不透明な白）を使う。メンバーカラーやバッジの色など、色付きの背景の上で、テーマに依存せず白のままにする文字には、white を使う。

メンバー関係性マップ・レーダーチャートの色のトークン

メンバー関係性マップ（/member-map）とメンバー関係性レーダーチャート（/member-map/radar）に固有の色は、次のトークンで持つ。すべてにダークの値を定義する。2 つの対応表では、共通のトークンと合わせて使う。

メンバー関係性マップ画面の部品と色

メンバー関係性レーダーチャート画面の部品と色

その他の画面の色のトークン

リンク編集・メンバーカード・ライブのツアー表示・イベントカード・世代マトリクス・新着投稿などの CSS Modules と app/globals.css の色（MorningStatusApp#1788）は、次のトークンで持つ。すべてにダークの値を定義する。共通のトークン（overlay.*・scrim.*・white）と、既存のトークン（card.bg・event-type.leader・primary）も使う。色の名前（white）で指定する色も、#fff と同じく white を使う。ライトの値は §8-8 に定める。

その他の画面の部品と色

カード・バッジ・詳細表示の色のトークン

メンバー詳細・ライブとフェスの詳細・新着投稿・「今日」「この日の出来事」・年表などの .tsx の色（MorningStatusApp#1789）は、次のトークンで持つ。すべてにダークの値を定義する。共通のトークン（overlay.*・scrim.*・white）と、既存のトークン（card.bg・category.fallback・event-type.live・feedback.error・status.*・tiktok.brand）も使う。色の名前（white）で指定する色も、#fff と同じく white を使う。ライトの値は §8-8 に定める。

備考: 年表の種別の色（timeline-type.*）は、イベントカードの種別の色（event-type.*）と値が異なる（ライブ・フェス・メディア）。別のトークンとして持つ。両者を 1 つにそろえる検討は、別の課題とする。

カード・バッジ・詳細表示の部品と色

画面ページ・編集画面・グラフ・地図の色のトークン

画面ページ・編集画面・グラフ・地図・選択部品の .tsx と、lib/ の色（MorningStatusApp#1790）は、次のトークンで持つ。すべてにダークの値を定義する。共通のトークン（overlay.*・scrim.*・white）と、既存のトークン（input.*・feedback.error・status.*・event-type.leader・youtube.brand・ameba.brand）も使う。constants/colors.ts の INSTAGRAM_COLOR・TIKTOK_COLOR・YOUTUBE_COLOR・NEW_POSTS_BLOCK_COLORS の値は、カテゴリ色分け辞書と同じく、var(--colors-…) の文字列で持つ。ライトの値は §8-8 に定める。

画面ページ・編集画面・グラフ・地図の部品と色

備考: 曲の詳細の「YouTube Music で聴く」ボタンの背景は、Spotify の緑（#1DB954）で作られていた。ボタンの対象に合わせて、YouTube のブランドの色（youtube.brand）を使う。

変数の代替値の扱い

var(--x, 色) の代替値に色が書かれている場合は、変数が定義されているかで扱いを決める。

備考: フィルタチップの選択中の背景は、未定義の --primary-rgb の代替値（紫 139, 92, 246）が常に効き、文字と枠の赤と合っていなかった。主色から作る方式にして、同じ色合いにそろえる。

トークンにしない色

次の色は、トークンにしない。

SVG の fill・stroke 属性の色にも、var() と color-mix() を入れる（Chromium で描画を確認済み。Firefox・Safari は未確認）。グラフ描画の色のうち、var() を指定すると描画されない色は、理由を添えてこの表に載せる。

CSS Modules の色

CSS Modules の色は、var(--colors-<トークン名>) で参照する。CSS Modules はレイヤー外の CSS のまま、値だけが変数の参照になるため、スタイルの優先度は変わらない（開発ノート「実装」知見 144・147）。対応するトークンがない色は、トークンを追加する。追加するトークンにもダークの値を定義する。

8-4. 補足: 活用方針の検討経緯（案A〜D）

MorningStatusApp#1745 の検討結果。判断軸は、①ダーク／ライトモードの実現しやすさ、②色の一元管理による保守性。2026-10-22 時点の実測（main）に基づく。

8-5. 補足: 別名方式の検証結果

Panda CSS 2.3.0 とブラウザ（Chromium、Playwright）で検証した。

8-6. テーマ切替の仕組み

ダーク／ライトの切り替えは、<html> のクラスと CSS 変数だけを前提にする。CSS エンジン（Panda CSS・Tailwind CSS など）の API には依存しない。

境界

切り替えの仕組みと CSS エンジンの境界は、次の 3 つ。

切替ボタン・先頭スクリプト・localStorage の保存は、この 3 つだけを前提にする。Panda CSS の生成物（styled-system）は、これらから import しない。

エンジンを替えるときに移すのは、.dark・.light の下に色の変数を出す部分（panda.config.ts のトークン定義）である。変数名 --colors-* は Panda CSS の命名規則で、Tailwind CSS v4 は --color-* を使う。エンジンを替えるときは、変数名の移行が要る。

選択肢と保存

• 選択肢は「システム」「ダーク」「ライト」の 3 つ。初期値は「システム」
• 選択は localStorage のキー theme に、system・dark・light のいずれかで保存する。保存された値がないとき、または 3 つ以外の値のときは「システム」とする
• 「システム」のときは、matchMedia('(prefers-color-scheme: dark)') の結果で dark と light のどちらかを決め、<html> に付ける。OS の設定が変わったときも、同じ matchMedia の変更イベントで付け替える

初回描画の前の適用

<head> の先頭に、同期で実行するインラインスクリプトを置く。スクリプトは、<body> の描画より前に、保存された選択から <html> のクラスと color-scheme を決める。ダークの値が :root（クラスなしの状態）に出力されるため、クラスが付く前はダークで描画される。スクリプトを描画より前に実行することで、ライトの利用者にダークの表示が一瞬出ることを防ぐ。

先頭スクリプトと切替ボタンの担当

• 先頭スクリプト: 初回描画の前に、保存された選択から <html> のクラスと color-scheme を決める。「システム」のときは、OS の設定の変更を matchMedia の変更イベントで監視し、クラスを付け替える
• 切替ボタン: 選択が変わったときに、localStorage へ保存し、<html> のクラスと color-scheme を更新する
• 両者は、保存のキー（theme）と、選択からクラスへの対応（system は matchMedia の結果、dark と light はそのまま）に、同じ決まりを使う

8-7. グローバルヘッダーの配置

全画面共通のグローバルヘッダー（app/layout.tsx）は、タイトルを左端に置き、右側に 👉（タイムライン）・🔍（曲検索）・テーマの切替ボタンを、一定の間隔（gap）で並べる。

• 右側の並びは、👉・🔍・切替ボタンの順。切替ボタンが右端
• 切替ボタンは、押すたびに「システム → ダーク → ライト → システム」の順に巡回する。現在の選択を表すアイコン（システムは 🖥️、ダークは 🌙、ライトは ☀️）を表示し、aria-label で現在の選択（例: 「テーマ: システム」）を伝える
• 各アイコンのタップ領域は、44px 前後にする
• 画面幅 320px 以上で、タイトルは全文が表示され、アイコンと重ならない。タイトルの文字サイズは、画面幅に合わせて 0.9rem〜1.25rem（md 以上は 1.5rem）にし、それでも収まらない幅では、末尾を省略記号にする
• 切替ボタンは、移動ではなく設定のため、ページ間の移動の <nav>（aria-label は「ページ移動」）の外に置く

8-8. ライトの配色

ライトの値は、トークンごとに、ダークの値とは別に定義する。ダークと同じ値のトークンには、ライトの値を定義しない。

区分

背景を持つトークンと、その上に載る文字・線のトークンは、同じ区分で定義する。overlay.* は、ライトでは暗い色の透過になるため、暗い色の背景の上では読めなくなるためである。

基本トークンのライトの値

overlay.* のライトの値は、純黒ではなく、text.main のライトの値と同じ色相（#0f172a、slate-900）の透過にする。

overlay.35〜95 のライトの透明度（%）は、次のとおり。

overlay.* は、塗りや線のほかに、文字にも使う。白の透過（ダーク）と暗色の透過（ライト）は、同じ透明度でも文字のコントラストが対称にならない（透明度 45% の文字は、ダークが約 4.5:1、ライトが約 2.9:1 になる。相対輝度からの概算）。そのため、文字にも使う 35〜95 の段階は、ライトの透明度を引き上げる。body の背景は、surface から surface-deep へのグラデーションのため、下限は両端の背景の上で決める。下限の 62% は、surface のライト（#f8fafc）と surface-deep のライト（#e2e8f0）のどちらの上でも、4.5:1 以上（概算）になる。4〜30 の段階は、塗りと線に使うため、ダークと同じ透明度にする。

コントラストは、通常のテキストで 4.5:1 以上を目安にする。text.muted と overlay.* の文字は、画面ごとに確認し、必要なら調整する。

残りのトークンのライトの値

残りのトークンのライトの値は、次の基準で決める。

文字の色とチップの色は、ダークの -400 前後のシェードを、白い背景で読める濃さまで暗くするため、ダークより濃い色（-600〜-900）になる。チップの薄い背景は、tintBackground() の 13.33% と、イベントカードの文字だけのカードのラベルの約 18% を含めるため、18% で確かめる。

カテゴリ色分け辞書

状態・結果・ブランドの色

年表・見出し・同期状況・新着投稿の色

世代マトリクス・レーダーチャートの色

メンバー関係性マップ・レーダーチャートの色

メンバーカラー

メンバーカラー（§8-3 でトークンにしない色）は、データから決まる色のため、値の表を持たない。文字の色や背景の色に使う箇所は、次のとおり、ライトで読める色にする。

• ライトの文字の色の基準は、チップの色（上の表）と同じ。surface のライト・surface-deep のライト・カードの背景（#dae0e8）の 3 つの上と、それぞれの上に同じメンバーカラーの 13.33%・18% を重ねた背景の上で、4.5:1 以上
• カードの文字色は、白と黒のうち高い方を選ぶ。メンバーカラーがどの明るさでも、最悪で約 4.58:1（相対輝度からの概算）になり、4.5:1 以上を満たす。名前と期のラベルは、不透明な色で描く。卒業メンバー（OG）のカードは、opacity: 0.65 で下地に透けるため、実効の比を「既知の基準未達」に定める
• メンバーカラーを背景にする箇所は、ダークとライトで背景の色が変わらないため、文字色の選び方もダークとライトで同じ

ダークと同じ値のトークン（残り）

次のトークンは、ライトでも、ダークと同じ値を使い、ライトの値を定義しない。ブランドの固定色の薄い背景・白い文字の背景・半透明の背景や枠線で、ライトの背景の上でも読み取れる、または、白い文字との組み合わせで使うため。

• 状態・結果: status.success-bg、status.neutral-bg、status.error-bg、status.warning-bg、status.error-solid、status.error-border、live-tour.join-bg、live-tour.graduate-bg、live-tour.birthday-bg、leader-badge.bg、leader-period.border、leader-period.bg、tiktok.brand-bg
• 画面の装飾: primary-glow、today-card.border、today-card.accent、map-marker.bg、release-badge.single・album・ep・live・soundtrack・compilation・other
• 関係性: relationship.accent-bg、relationship.accent-border、relationship.selected-bg、relationship.selected-border、relationship.danger-border、relationship.info-bg、edge-label.bg、edge-label.text

リリースのバッジの背景（release-badge.*）は、白い文字の背景のため、ダーク・ライトとも、白の上で 4.5:1 以上になる色にする。

既知の基準未達

2026-11-06 の実測（MorningStatusApp#1805）で、基準の 4.5:1 に届いていない箇所。測り方は、開発ノートの「テスト手法」知見 64・65 に従う。

トークンにしない色（§8-3）は、ライトでも 16 進数のまま使う。

改訂履歴（バージョン降順に記載）