create-ampless 1.0.0-alpha.57 → 1.0.0-alpha.59

package/dist/templates/_shared/THEMES.ja.md

@@ -0,0 +1,495 @@
+> 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:<name>` をナビに入れると、そのタグの記事一覧を自動展開できる。
+- コードフォントや技術文書向けの構造を持つ。
+
+向いているカスタマイズ:
+
+- ヘルプ、仕様書、開発者向けドキュメント。
+- 記事をタグで分類し、サイドバーへ自動反映したい。
+- 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/<siteId>/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/<official-name>/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 だけ表示してしまう。