applying-themes

テーマの適用

概要

テーマとは、セマンティックトークンの完全なセットであり、見栄えのよい色のリストではありません。役割が定義されていない4つの16進値では、コンポーネントごとにどれをテキストにし、どれを背景にするか判断しなければならず、出力に一貫性がなくなります。

基本原則： どのテーマも同じ8つのトークンに解決されます。コンポーネントはトークン名を参照し、16進値は参照しません。テーマの切り替えは、1つのブロックを差し替えるだけで済みます。

base  surface  line  ink  ink-2  ink-3  accent  accent-ink

鉄則

NO THEME APPLIED WITHOUT ITS CONTRAST VERIFIED

見栄えのよいパレットでも、コントラスト比が4.5:1を満たさなければ使いものになりません。また、コントラストは目視では判断できません。中間調のアクセントカラーを中間調のサーフェスに使うと、見た目には問題がなくても常に基準を満たしません。付属するすべてのテーマには、機械で検証できるcontrastブロックが含まれています。カスタムテーマも、使用前に同じ検証を行います。

チェックリスト

1. テーマを提示する — 用途を含めて、以下の表を示します
2. 明示的に選んでもらう — 選択を決めつけないでください
3. テーマファイルを読む — themes/<name>.mdが信頼できる唯一の情報源です
4. コントラストを検証する — チェッカーを実行します。カスタムテーマでは必須です
5. トークンブロックを出力する — 成果物の先頭に一度だけ配置します
6. トークン名で適用する — コンポーネント内では生の16進値を使いません
7. レンダリングを確認する — 出力を確認し、特にセカンダリテキストに注意します

テーマ

テーマ	特徴	ベース	最適な用途
ocean-depths	深い海のような静けさ	ダーク	金融、コンサルティング、インフラ
sunset-boulevard	ゴールデンアワーの温かみ	ライト	クリエイティブ、ローンチ、ホスピタリティ
forest-canopy	大地に根ざした色調	ライト	サステナビリティ、クラフト、長文コンテンツ
modern-minimalist	グレースケールの規律	ライト	ドキュメント、ポートフォリオ、システム
golden-hour	アンバーの豊かな色調	ライト	レビュー、食、振り返り
arctic-frost	冷たく明瞭なクリニカルさ	ライト	医療、分析、コンプライアンス
desert-rose	ダスティで洗練された印象	ライト	ブティック、招待状、ウェルネス
tech-innovation	ターミナルのような高コントラスト	ダーク	開発者向けツール、AI、変更履歴、ステータス
botanical-garden	手入れされ、生き生きとした印象	ライト	食、農業、コミュニティ
midnight-galaxy	深宇宙のドラマチックさ	ダーク	ローンチ、エンターテインメント、基調講演

各themes/<name>.mdには、役割を含む完全なパレット、コントラスト要件、ウェブフォントの組み合わせとメトリクスを維持するPDF用フォールバック、スケール比、誤用した場合にテーマがどのように破綻するかについての注意事項が記載されています。

theme-showcase.pdfは、このスキルの以前のバージョンで作成された旧式のビジュアルであり、色やフォントはテーマファイルと一致しなくなっています。正しい情報はMarkdownファイルに記載されています。このPDFを正確なプレビューとして提示しないでください。

提示と選択

表を示し、一度だけ質問して、回答を待ちます。明示的に選ばれるまでテーマを適用しないでください。質問にかかる時間よりも、誤ったパレットでデッキ全体を作り直すほうが時間を無駄にします。

ユーザーがテーマ名ではなくニーズを説明した場合（「役員向けデッキに合う、落ち着いたもの」など）は、理由を一行ずつ添えて2つのテーマを提案し、選んでもらいます。

コントラストの検証

source ~/.local/opencode-venv/bin/activate

python3 scripts/check_contrast.py themes/ocean-depths.md   # one theme
python3 scripts/check_contrast.py themes/*.md              # all of them
python3 scripts/check_contrast.py --pair "#8a7357" "#fbf5ea"   # ad-hoc pair

いずれかのチェックに失敗すると終了コードはゼロ以外になるため、ゲートとして機能します。付属する10種類のテーマは、6つのチェックすべてに合格しています。

適用

HTML / CSS

:rootにトークンブロックを一度だけ出力し、その後はトークンのみを参照します。

:root {
  --base: #0f1c26; --surface: #16283a; --line: #2d4859;
  --ink: #eef6f8; --ink-2: #accad4; --ink-3: #8aa7b3;
  --accent: #4fd1c5; --accent-ink: #04222a;
  --font-display: "Young Serif", Georgia, serif;
  --font-text: "IBM Plex Sans", system-ui, sans-serif;
}
body   { background: var(--base); color: var(--ink); font-family: var(--font-text); }
h1, h2 { font-family: var(--font-display); }
.card  { background: var(--surface); border: 1px solid var(--line); }
.meta  { color: var(--ink-3); }
.btn   { background: var(--accent); color: var(--accent-ink); }

:root以外では生の16進値を使わないでください。 完成前にコンポーネントのスタイルで#を検索してください。16進値が1つでも残っていると、テーマを切り替えられなくなります。

両方のカラースキーム

成果物をライトモードとダークモードの両方で動作させる必要がある場合は、ライトテーマとダークテーマを選び、同じトークン名に割り当てます。

:root { /* forest-canopy tokens */ }
@media (prefers-color-scheme: dark) { :root { /* ocean-depths tokens */ } }
:root[data-theme="dark"]  { /* ocean-depths tokens */ }
:root[data-theme="light"] { /* forest-canopy tokens */ }

メディアクエリと明示的な属性の両方が必要です。どちらの方向でもOSの設定を上書きできない切り替え機能は壊れています。

PDF とスライド

テーマのタイポグラフィ表の PDF / slides 列を使用してください。Web フォントは PDF レンダラーで利用できないことが多く、フォントが見つからない場合、異なるメトリクスを持つフォントに警告なしで置き換えられ、元のフォントを前提としたすべてのレイアウトが崩れます。

from reportlab.lib.colors import HexColor
from reportlab.pdfbase import pdfmetrics
from reportlab.pdfbase.ttfonts import TTFont

BASE, SURFACE, LINE = HexColor("#f7f6f0"), HexColor("#fffffb"), HexColor("#dcded1")
INK, INK2, INK3     = HexColor("#1a271a"), HexColor("#4a5a46"), HexColor("#79876f")
ACCENT, ACCENT_INK  = HexColor("#2f6b3c"), HexColor("#f4fbf5")

# Bundled open-licensed faces from the designing-canvas-art skill
pdfmetrics.registerFont(TTFont("Display", "../designing-canvas-art/canvas-fonts/YoungSerif-Regular.ttf"))
pdfmetrics.registerFont(TTFont("Text",    "../designing-canvas-art/canvas-fonts/WorkSans-Regular.ttf"))

印刷で最も問題が起きやすいトークンは ink-3 です。多くのプリンターやプロジェクターは、明るい色の階調を圧縮します。照明のある部屋で投影するスライドでは、聴衆が読む必要のあるものには ink-2 を使用してください。

React

export const theme = {
  base: "#0f1c26", surface: "#16283a", line: "#2d4859",
  ink: "#eef6f8", ink2: "#accad4", ink3: "#8aa7b3",
  accent: "#4fd1c5", accentInk: "#04222a",
};

Tailwind では、トークンを theme.extend.colors にマッピングし、ユーティリティクラスに意味を持たせてください。例：bg-base、text-ink-2、border-line。

カスタムテーマの作成

同梱のテーマが合わない場合は、場当たり的に色を選ぶのではなく、テーマを作成してください。

1. 方向性に名前を付けるため、2語で表現し、実在する参考例を挙げます。「Coastal Survey — 1970s nautical chart」ならパレットを生み出しますが、「モダンでクリーン」では無難な初期設定になります。
2. 色相の方針を選びます。単色、類似色、補色、またはニュートラルカラーにアクセントカラーを加える方法から選び、どれか1つに決めます。
3. 色味を加えてニュートラルカラーを作ります。純粋なグレーは使いません。すべてのニュートラルカラーにアクセントカラーを4〜8％混ぜ、パレット全体に統一感を持たせます。
4. アクセントカラーの色相を基に ink を導き出します。彩度と明度を非常に低くします。これにより、パレットが寄せ集めではなく、意図してデザインされた印象になります。
5. 必要に応じて、アクセントカラーを2通りに設定します。塗りつぶし用の明るい値と、テキスト用の暗い値です。1つの値で両方に対応できることはほとんどありません。
6. themes/ にある既存のテーマをテンプレートとして使い、contrast ブロックも含めてファイルを作成します。
7. チェッカーを実行します。 合格するまで明度を調整してください。チェッカーに不合格のカスタムテーマは公開しないでください。
8. アーティファクト全体に適用する前に、パレットとレンダリングしたサンプルを1つユーザーに提示します。

基礎となる色彩理論（OKLCH による構築、階調の生成、ダークモードのルール）については、designing-frontend-interfaces/references/color-and-theme.md を参照してください。

よくある間違い

確認せずにテーマを適用する。 ユーザーが選んでいないパレットで完成済みのスライド資料を作り直すのは、テーマを適用しないよりも悪い結果になります。

コンポーネントに16進数カラーを直接指定する。 :root ブロックがあるのに、Card.css に #16283a が残っています。テーマを切り替えられなくなります。

本文に ink-3 を使う。 コントラスト比は3:1であり、4.5:1ではありません。大きなサイズのキャプションやメタデータにのみ使用します。

大きな塗りつぶしと小さなテキストの両方にアクセントカラーを使う。 塗りつぶしに適した明るさの色は、テキストには暗さが足りないことがほとんどです。2段階に分けてください。

PDF のパイプラインで Web フォントを使う。 警告なしで置き換えられ、すべてのレイアウトが崩れます。メトリクスが安全な列を使用してください。

「変化を付けるため」に2つ目のアクセントカラーを追加する。 異なる色相の鮮やかなアクセントカラーを2つ使うと、アーティファクトが寄せ集めのように見えます。本当に2つ目の色が必要なら、ink の階調から選んでください。

ダークテーマでも影を変更しない。 暗い背景では影が見えません。ダークテーマの立体感は、暗い影ではなく、明るいサーフェスで表現します。

片方のモードだけでコントラストを確認する。 ライトモードで合格しても、ダークモードについては何も分かりません。