> English: [THEMES.md](./THEMES.md) > # THEMES.md このドキュメントは、ampless プロジェクトでテーマをカスタマイズするときの実務ガイドです。 AI エージェントが読むことも、人間が作業メモとして読むことも想定しています。 テーマ作業の詳細はここに集約し、`AGENTS.md` / `AGENTS.ja.md` には最終的に「テーマ作業は `THEMES.md` を参照」とだけ残す方針です。 ## 基本方針 - 公式テーマは直接編集しない。 - カスタマイズは `themes/my-*/` に閉じ込める。 - 共有シェルである `app/`、`components/`、`lib/` は、テーマだけで解決できない場合に限って触る。 - `themes-registry.ts` は自動生成ファイルなので手動編集しない。 - UI / テーマ変更は、型チェックだけで完了扱いにしない。必ずブラウザで目視確認する。 ## ベーステーマの選び方 ampless のテーマカスタマイズは、既存テーマをベースにして `themes/my-*/` にコピーするところから始める。 最初に「何を作るか」ではなく「どのテーマを土台にするか」を決めると、作業範囲が小さくなる。 ### `blog` 個人ブログ、日記、技術メモ、ニュースへのコメントなど、時系列の投稿を中心にしたサイト向け。 特徴: - ホームに投稿フィード。 - 個別投稿ページ。 - タグ別一覧。 - ヘッダー / フッターナビ。 - カラー、フォント、角丸、固定記事などの調整幅が広い。 向いているカスタマイズ: - 個人メディア風にする。 - 記事一覧の密度を変える。 - 記事詳細の組版を強める。 - Markdown の表、コード、引用まで含めて読み物として整える。 迷ったらまず `blog` をベースにする。 ### `minimal` 装飾を抑えた小さなブログ向け。 特徴: - カスタマイズ項目が少ない。 - 余計な chrome が少ない。 - デザインを主張させず、投稿を淡々と並べる。 向いているカスタマイズ: - 色と角丸だけ軽く変えたい。 - レイアウトはほぼ変えない。 - 文章量が少ないサイト。 大きく作り替えるなら `blog` の方が向く。 ### `landing` 1 ページ完結型の紹介サイト向け。 特徴: - ヒーロー中心。 - CTA ボタン。 - 任意で最新記事。 - サイト説明や導線を前面に出す。 向いているカスタマイズ: - プロダクト、イベント、ポートフォリオ、店舗紹介。 - 投稿一覧よりも最初の訴求を重視するサイト。 - AI に hero / CTA / feature section のデザインを作らせたい場合。 ### `corporate` 企業サイト、事務所、団体サイト向け。 特徴: - 落ち着いたヒーロー。 - お知らせ一覧。 - ヘッダー / フッターがしっかりある。 - フッター注記を持てる。 向いているカスタマイズ: - 会社概要やサービス説明を前面に置く。 - ニュースやお知らせを投稿として管理する。 - 信頼感、読みやすさ、保守性を優先する。 ### `docs` ドキュメントサイト向け。 特徴: - サイドバー主導。 - `tag:` をナビに入れると、そのタグの記事一覧を自動展開できる。 - コードフォントや技術文書向けの構造を持つ。 向いているカスタマイズ: - ヘルプ、仕様書、開発者向けドキュメント。 - 記事をタグで分類し、サイドバーへ自動反映したい。 - Markdown のコードブロックや表が多い。 ### `dads` デジタル庁デザインシステムに寄せた公共系サイト向け。 特徴: - 高コントラスト。 - アクセシビリティ重視。 - 装飾控えめ。 - `@digital-go-jp/tailwind-theme-plugin` ベース。 向いているカスタマイズ: - 政府、自治体、公共系の情報サイト。 - 独自の雰囲気よりも準拠性や読みやすさを優先する。 注意: - DADS 以外の色へ大きく変えると、DADS 準拠の意味は薄れる。 - 公共系では、AI が出した装飾案をそのまま採用せず、アクセシビリティを優先して調整する。 ## 標準フロー 1. 公式テーマをコピーする。 ```bash npm run copy-theme blog my-blog ``` `my-` プレフィックスがついたテーマはユーザー所有のコピーとして扱われ、`npm run update-ampless` で上書きされない。 2. まずテーマ内だけで実装する。 優先順位: - `themes/my-blog/tokens.css` — 色、フォント、余白、罫線、Markdown 本文の見た目。 - `themes/my-blog/manifest.ts` — 管理 UI に公開するテーマ設定。 - `themes/my-blog/pages/` — home / post / tag / feed / sitemap などのルート別レイアウト。 - `themes/my-blog/components.tsx` など — テーマ内でだけ使う共通 UI。ヘッダー、フッター、ワードマークなどはここに切り出してよい。 3. テーマを有効化する。 `/admin/sites//theme` で `my-blog` を選択して保存する。テーマ切り替えはランタイム設定なので、通常は再デプロイ不要。 4. 確認する。 ```bash npm run dev npx tsc --noEmit npm run build npm run lint ``` `npm run lint` がプロジェクトの Next.js バージョンと合っていない場合は、その旨を報告する。代替として型チェック、ビルド、ブラウザ確認は必ず行う。 ## カスタマイズの設計手順 テーマを変更するときは、実装前に次の順で決める。 1. サイトの役割 例: 個人ブログ、技術メモ、ニュースコメント、企業サイト、ドキュメント、ランディングページ。 2. 読ませ方 例: 長文をじっくり読ませる、一覧を高速にスキャンさせる、ヒーローで強く印象づける、検索やタグから探させる。 3. 画面の種類 少なくとも以下を考える。 - home - post detail - tag / archive - empty state - mobile home - mobile detail 4. 変更範囲 `tokens.css` だけで済むのか、`pages/` の構造変更が必要か、テーマ内コンポーネントを追加するかを決める。 5. Markdown の扱い ブログや docs では、本文だけでなく Markdown 要素もテーマの一部として設計する。 ### 変更の優先順位 まず `tokens.css` で変えられることを変える。 - 色 - フォント - 背景 - 罫線 - 余白 - prose / Markdown - レスポンシブ時のサイズ調整 次に `pages/` を変える。 - home の構造。 - 記事一覧の密度。 - post detail の余白とメタ情報。 - tag / archive の見せ方。 - empty state。 最後に、繰り返し出る要素を `components.tsx` などのテーマ内コンポーネントへ切り出す。 共有 `components/` や `app/` へ手を入れるのは、複数テーマで使う必要がある場合だけにする。 ## Claude Design を使わない場合 まず、既存テーマを読む。いきなり作り替えない。 確認するもの: - `tokens.css` のトークン構造。 - `manifest.ts` の公開フィールド。 - `pages/home.tsx`、`pages/post.tsx`、`pages/tag.tsx` のデータ取得と表示責務。 - `themes//README.*` があれば、テーマ固有の意図。 進め方: 1. 要件を「読む体験」「情報密度」「ブランド感」「対応するコンテンツ型」に分解する。 2. 先に `tokens.css` で大きな方向を決める。 3. 必要な場合だけ `pages/` の構造を変更する。 4. 繰り返し出る chrome はテーマローカルコンポーネントに切り出す。 5. Markdown 要素も必ずデザイン対象にする。 Markdown で確認するもの: - 見出し `h1` / `h2` / `h3` - 段落 - リスト - 表 - 引用 - インラインコード - コードブロック - 画像 - リンク 読み物サイトでは、本文の可読性を最優先する。装飾は本文の外側、余白、罫線、ナビゲーション、一覧の密度、メタ情報の組版で出す。 ## AI を使ったテーマカスタマイズ AI は「実装を全部任せる道具」ではなく、複数の役割に分けて使うと精度が上がる。 おすすめの役割分担: - デザイン探索: Claude Design、ChatGPT、画像生成などで方向性を出す。 - 実装計画: Codex / Claude Code に既存テーマを読ませ、どのファイルに反映するか決める。 - 実装: テーマ内ファイルを編集する。 - 検証: ブラウザスクリーンショットで Desktop / Mobile を比較する。 - 仕上げ: はみ出し、空状態、Markdown、長いタイトルを詰める。 ### AI に渡すとよい情報 AI にテーマ案を作らせるときは、次を渡す。 - サイト名。 - サイトの内容。 - 読者。 - 主な投稿タイプ。 - 避けたい雰囲気。 - 参考サイトやスクリーンショット。 - Desktop / Mobile の両方が必要であること。 - home / archive / detail / empty state が必要であること。 - Markdown の表、リスト、コード、引用も使うこと。 例: ```text ishinao.net という個人ブログのテーマを作りたい。 内容は日常、技術メモ、ニュースへの短いコメント。 本文を読ませるサイトなので、記事本文の可読性を最優先。 ただし home / archive / header / meta 情報ではデザイン性を出したい。 Desktop と Mobile の両方で、Top empty、Top with content、Archive、Detail を作って。 Markdown の表、リスト、引用、コードブロックも浮かない雰囲気にしたい。 ``` ### AI 出力をそのまま信じない AI が作ったデザインには、次のような抜けが出やすい。 - Desktop は良いが Mobile が破綻する。 - ヒーローだけ作り込み、記事詳細が普通になる。 - 本文の可読性より装飾が勝つ。 - Markdown の表やコードが未設計。 - 空状態がない。 - 実データの長い日本語タイトルで崩れる。 - 余白や文字サイズが実装時に別物になる。 そのため、AI 出力は「完成コード」ではなく「視覚仕様」として扱う。 ## Claude Design を使う場合 Claude Design の出力 HTML は、多くの場合「ひとつの完成サイト」ではなく「複数画面のアートボード集」です。HTML をそのまま移植するのではなく、画面ごとの設計意図を抽出して、ampless のテーマ構造へ写像する。 ### 読み取り方 まず HTML またはスクリーンショットから、アートボードを画面単位で分類する。 例: - Desktop / Top empty - Desktop / Top with content - Desktop / Archive list - Desktop / Detail - Mobile / Top - Mobile / Archive - Mobile / Detail 次に、各画面から共通トークンを抜き出す。 - 背景色 - アクセントカラー - 罫線色 - フォントファミリー - 見出しのサイズ感 - 本文の行間 - 一覧の密度 - 余白の単位 - ヘッダー / フッターの chrome - モバイル時の幅、余白、改行、情報の省略ルール この段階で、特定アートボードだけを見て実装しない。Desktop と Mobile の両方を見て、同じ UI がどう変化しているかを確認する。 ### 実装への写像 Claude Design の画面を ampless のテーマに対応させる。 - Top / Home 系 → `themes/my-blog/pages/home.tsx` - Detail / Article 系 → `themes/my-blog/pages/post.tsx` - Archive / Tag / List 系 → `themes/my-blog/pages/tag.tsx` - 共通ヘッダー、ワードマーク、フッター → `themes/my-blog/components.tsx` - 色、フォント、グリッド、prose、レスポンシブ → `themes/my-blog/tokens.css` - 管理 UI で変えたい値 → `themes/my-blog/manifest.ts` HTML 内の generated code や inline style を丸ごとコピーしない。必要なのは、実装そのものではなく設計のルール。 ### 実装時のコツ Claude Design の HTML からは、次を手で抽出する。 - 画面タイプ。 - 共通トークン。 - レイアウトグリッド。 - 見出しのサイズ比。 - 一覧行の高さ、罫線、メタ情報の位置。 - モバイル時の省略 / 縦積み / サイズ変更。 - 空状態の扱い。 ampless 側では、それを以下のように分ける。 - 共通デザイン言語 → `tokens.css` - 画面構造 → `pages/*.tsx` - 繰り返し UI → テーマ内 `components.tsx` - 管理 UI で変更可能にする値 → `manifest.ts` Claude Design のアートボードに複数状態がある場合は、最初に状態名をメモする。 例: ```text Final - ishinao.net theme - Top empty - Top with content - Archive list - Detail editorial body - Mobile top empty - Mobile top with content - Mobile archive - Mobile detail ``` このメモを実装チェックリストとして使う。 ### Claude Design 反映チェックリスト - Desktop と Mobile の両方を実装したか。 - 空状態と投稿あり状態の両方を考慮したか。 - 一覧、詳細、タグ一覧など、複数ページに同じデザイン言語が通っているか。 - ワードマーク、ナビ、メタ情報、罫線、背景の扱いが共通化されているか。 - モバイルで横スクロールや文字のはみ出しがないか。 - 長い日本語タイトルでも破綻しないか。 - 投稿が 1 件、複数件、タグなし、タグ複数のときに破綻しないか。 - Markdown の表やコードブロックがテーマの世界観から浮いていないか。 ## Claude Design 以外の AI を使う場合 Claude Design がない場合でも、AI は十分使える。 ### テキストで依頼する まず、AI にデザイン仕様書を書かせる。 依頼例: ```text ampless の blog テーマをベースに、個人技術ブログ向けのテーマ仕様を作って。 出力は実装コードではなく、tokens、home、post detail、tag archive、mobile rules、Markdown styling に分けて。 本文の可読性を最優先し、装飾は chrome と一覧で出す。 ``` この出力をもとに、Codex / Claude Code へ実装させる。 ### 画像やスクリーンショットを使う 参考画像がある場合は、AI に以下を抽出させる。 - 色。 - フォントの雰囲気。 - 余白。 - 罫線。 - 情報密度。 - Desktop / Mobile の差。 - 実装時に `tokens.css` へ入れるべきもの。 - `pages/` の構造変更が必要なもの。 ### AI に実装させるときの依頼 実装 AI には、次のように依頼する。 ```text themes/my-blog だけを編集して、共有 app/components/lib は触らない。 まず既存テーマを読んで、tokens.css、pages、manifest の責務を確認して。 Desktop 1440px と Mobile 390px でスクリーンショット確認して。 Markdown の表、リスト、引用、コードもテーマに合うように調整して。 ``` AI に「全部いい感じにして」とだけ依頼すると、共有ファイルを触ったり、Desktop だけで終わったりしやすい。 ## ブラウザ確認 UI / テーマ変更では dev server を起動し、実際のページを開いて確認する。 ```bash npm run dev ``` 確認する代表幅: - Desktop: `1440 x 1100` - Mobile: `390 x 844` スクリーンショットで確認する場合は、キャッシュの影響を避けるためにクエリ文字列を付けるとよい。 ```text http://localhost:3000/?v=theme-check-1 ``` 見るポイント: - 参照デザインと比べて、第一印象が同じ方向を向いているか。 - テキストが親要素からはみ出していないか。 - モバイルで横スクロールが発生していないか。 - 背景、罫線、余白、文字サイズが画面幅に対して自然か。 - 読むべき本文のコントラストと行間が十分か。 - リンク、タグ、ナビ、フッターが空設定のときに余計な余白を残していないか。 ## テーマ内コンポーネントの使いどころ テーマ専用の共通 UI は `themes/my-blog/components.tsx` のようにテーマ内へ置く。 向いているもの: - ヘッダー - フッター - ワードマーク - 記事行 - メタ情報 - テーマ固有の装飾 UI 共有 `components/` に置くのは、複数テーマや管理 UI でも再利用する場合だけにする。 ## よくある失敗 - Claude Design の最初のサムネイルだけを見て実装してしまう。 - Desktop だけ寄せて、Mobile アートボードを見落とす。 - `tokens.css` だけで済む変更なのに、共有 `components/` を編集してしまう。 - 公式テーマ `themes/blog/` を直接編集してしまう。 - Markdown の表、引用、コードブロックを未調整のままにする。 - ブラウザ確認なしで「ビルドが通ったので完了」とする。 - 空の footer / nav 設定でも chrome だけ表示してしまう。