create-ampless 1.0.0-alpha.56 → 1.0.0-alpha.58

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

@@ -36,25 +36,12 @@
 - `.amplify/` — Amplify CLI の作業ディレクトリ。
 - `pnpm-lock.yaml` / `package-lock.json` — パッケージマネージャーに任せる。
 
-## テーマのカスタマイズ（標準的な手順）
+## テーマのカスタマイズ
 
-1. 公式テーマをコピーする:
-   ```bash
-   npm run copy-theme blog my-blog
-   ```
-   `my-` プレフィックスがついているコピーは `npm run update-ampless` で上書きされない。ターゲット名が `my-` で始まらない場合、コマンドは実行を拒否する。
-
-2. 以下の優先順位で編集する:
-   - `themes/my-blog/tokens.css` — 色、タイポグラフィ、スペーシング（`[data-theme='my-blog']` スコープの CSS カスタムプロパティ）。
-   - `themes/my-blog/manifest.ts` — 管理 UI（`/admin/sites/<id>/theme`）に公開するフィールドの宣言。
-   - `themes/my-blog/pages/` — レイアウト / 構造（Next.js ページモジュール: フィード、サイトマップ、投稿テンプレート）。
-
-3. テーマを有効化する: `/admin/sites/<siteId>/theme` を開き、`my-blog` を選択する。テーマ切り替えはランタイム設定 — 再デプロイは不要。
-
-4. 動作確認:
-   ```bash
-   npm run dev   # http://localhost:3000
-   ```
+テーマのカスタマイズ手順 — ベーステーマの選び方、`themes/my-*/`
+へのコピーフロー、Claude Design からの反映、AI 支援の実装、
+レスポンシブの目視確認、Markdown 要素のデザイン方針、よくある失敗
+— は [THEMES.ja.md](./THEMES.ja.md) を参照する。
 
 ## MCP サーバー（`@ampless/mcp-server`）
 
@@ -99,6 +86,7 @@ UI / テーマを変更した場合、型チェックだけを根拠にタスク
 
 ## 参照先
 
+- `THEMES.ja.md` — テーマカスタマイズの実務ガイド（ベーステーマの選び方、Claude Design からの反映、AI への依頼、ブラウザ確認、Markdown 要素のスタイリング、よくある失敗）。
 - `README.ja.md` — サイト運営者向けの日常利用ガイド。
 - `RUNBOOK.ja.md` — 定期的な運用手順（キーローテーション、バックアップ復元など）。
 - `themes/<name>/README.ja.md` — テーマごとのカスタマイズ詳細。

package/dist/templates/_shared/AGENTS.md

@@ -36,25 +36,12 @@ This file is written for AI coding agents (Claude Code, Cursor, Codex, etc.). Fo
 - `.amplify/` — Amplify CLI working directory.
 - `pnpm-lock.yaml` / `package-lock.json` — let the package manager update these.
 
-## Customising a theme (the standard flow)
+## Theme customization
 
-1. Copy an official theme:
-   ```bash
-   npm run copy-theme blog my-blog
-   ```
-   The `my-` prefix marks the copy as user-owned so `npm run update-ampless` leaves it alone. The target name must start with `my-` or the command refuses to run.
-
-2. Edit in this priority order:
-   - `themes/my-blog/tokens.css` — colours, typography, spacing (CSS custom properties scoped under `[data-theme='my-blog']`).
-   - `themes/my-blog/manifest.ts` — declare which fields are exposed in the admin UI (`/admin/sites/<id>/theme`).
-   - `themes/my-blog/pages/` — layout / structure (Next.js page modules: feed, sitemap, post templates).
-
-3. Activate the theme: open `/admin/sites/<siteId>/theme` and select `my-blog`. Theme switching is a runtime setting — no redeploy needed.
-
-4. Verify:
-   ```bash
-   npm run dev   # http://localhost:3000
-   ```
+For theme customization workflows — choosing a base theme, the
+standard copy-and-edit flow, Claude Design handoff, AI-assisted
+implementation, responsive visual QA, Markdown styling expectations,
+and the common failure modes — see [THEMES.md](./THEMES.md).
 
 ## MCP server (`@ampless/mcp-server`)
 
@@ -99,6 +86,7 @@ Do not report a task complete based solely on type checks if a UI/theme was modi
 
 ## See also
 
+- `THEMES.md` — theme customization workflows (base-theme selection, Claude Design handoff, AI prompts, browser QA, Markdown styling, common pitfalls).
 - `README.md` — day-to-day usage for site owners.
 - `RUNBOOK.md` — occasional ops procedures (key rotation, backup restore, etc.).
 - `themes/<name>/README.md` — per-theme customization details.

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

@@ -86,7 +86,13 @@ npm run sandbox
 npm run copy-theme
 ```
 
-独自テーマを作る場合: 既存テーマをコピーから始める（`cp -R themes/blog themes/your-theme`）→ `manifest.ts`、`tokens.css`、`pages/*.tsx` を編集 → `themes-registry.ts` に追加。フルガイド: [docs/THEMES.ja.md](https://github.com/heavymoons/ampless/blob/main/docs/THEMES.ja.md) ([English](https://github.com/heavymoons/ampless/blob/main/docs/THEMES.md))
+インストール済みテーマを `npm run update-ampless` で上書きされない形でカスタマイズしたい場合は、`my-` プレフィックス付きにコピーする:
+
+```bash
+npm run copy-theme blog my-blog
+```
+
+テーマカスタマイズの実務ガイド — ベーステーマの選び方、コピー / 編集 / 切り替えの標準フロー、Claude Design からの反映、AI を使った実装、レスポンシブ確認、Markdown 要素のスタイリング、よくある失敗 — はこのプロジェクト内の [THEMES.ja.md](./THEMES.ja.md)（[English](./THEMES.md)）に集約しています。
 
 ## プラグイン
 

package/dist/templates/_shared/README.md

@@ -86,7 +86,13 @@ To install another official theme into this project:
 npm run copy-theme
 ```
 
-To author your own theme: copy an existing one as a starting point (`cp -R themes/blog themes/your-theme`), edit `manifest.ts`, `tokens.css`, and `pages/*.tsx`, then add it to `themes-registry.ts`. Full guide: [docs/THEMES.md](https://github.com/heavymoons/ampless/blob/main/docs/THEMES.md) ([日本語](https://github.com/heavymoons/ampless/blob/main/docs/THEMES.ja.md)).
+To customize an installed theme without losing the customization on `npm run update-ampless`, copy it under the `my-` prefix:
+
+```bash
+npm run copy-theme blog my-blog
+```
+
+The full working guide for theme customization — base-theme selection, the standard copy / edit / activate flow, Claude Design handoff, AI-assisted implementation, responsive QA, Markdown styling, and the common pitfalls — lives in [THEMES.md](./THEMES.md) (and [THEMES.ja.md](./THEMES.ja.md)) right in this project.
 
 ## Plugins
 

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 だけ表示してしまう。

package/dist/templates/_shared/THEMES.md

@@ -0,0 +1,523 @@
+> 日本語版: [THEMES.ja.md](./THEMES.ja.md)
+>
+# THEMES.md
+
+Working guide for customizing themes in an ampless project. Written
+for AI coding agents and humans alike — keep it as your day-to-day
+reference when designing or restyling a site.
+
+All theme-related instructions live here. `AGENTS.md` / `AGENTS.ja.md`
+deliberately keep only a one-line pointer back to this file.
+
+## Ground rules
+
+- Never edit the official themes directly.
+- Keep customizations inside `themes/my-*/`.
+- The shared shell (`app/`, `components/`, `lib/`) is touched only when
+  the change genuinely can't be solved inside a theme.
+- `themes-registry.ts` is auto-generated — don't hand-edit it.
+- UI / theme changes are NOT done when type-checks pass. Always verify
+  in a browser.
+
+## Picking a base theme
+
+Theme customization in ampless starts by copying an existing theme
+into `themes/my-*/`. Deciding "which theme to start from" first keeps
+the scope small — much smaller than deciding "what to build" first.
+
+### `blog`
+
+Personal blogs, journals, technical notes, short news commentary —
+anything chronological where individual posts are the primary unit.
+
+Out of the box:
+
+- Post feed on the home page.
+- Per-post detail page.
+- Per-tag archive page.
+- Header / footer nav.
+- Wide tuning surface for colors, fonts, radii, pinned posts, etc.
+
+Good fits:
+
+- Personal-media feel.
+- Adjusting the density of the post list.
+- Strengthening typography on the detail page.
+- Designing Markdown elements (tables, code, blockquotes) as part of
+  the reading experience.
+
+When in doubt, start from `blog`.
+
+### `minimal`
+
+Restrained, small-surface blog.
+
+Out of the box:
+
+- Few manifest customization fields.
+- Minimal chrome.
+- Design steps back so the posts take the lead.
+
+Good fits:
+
+- Light color / radius tweaks only.
+- Layout largely untouched.
+- Low-content sites.
+
+If you want to redesign meaningfully, start from `blog` instead.
+
+### `landing`
+
+Single-page introduction sites.
+
+Out of the box:
+
+- Hero-centric layout.
+- CTA button.
+- Optional latest-posts strip.
+- Site description and primary CTAs front and center.
+
+Good fits:
+
+- Products, events, portfolios, shop introductions.
+- Sites that prioritize the first impression over a long post list.
+- Letting an AI design the hero / CTA / feature sections.
+
+### `corporate`
+
+Company sites, firms, organizations.
+
+Out of the box:
+
+- Restrained hero.
+- News / announcements list.
+- Substantial header / footer.
+- Footer disclaimer slot.
+
+Good fits:
+
+- Putting company overview / services up front.
+- Managing news and announcements as posts.
+- Trust, readability, maintainability as priorities.
+
+### `docs`
+
+Documentation sites.
+
+Out of the box:
+
+- Sidebar-driven navigation.
+- Putting `tag:<name>` into a sidebar entry auto-expands the matching
+  post list.
+- Structure tuned for code fonts and technical writing.
+
+Good fits:
+
+- Help docs, specifications, developer reference.
+- Categorizing posts by tag and surfacing them in the sidebar.
+- Heavy use of Markdown code blocks and tables.
+
+### `dads`
+
+Public-sector sites following Japan's Digital Agency Design System.
+
+Out of the box:
+
+- High contrast.
+- Accessibility-first.
+- Restrained decoration.
+- Built on `@digital-go-jp/tailwind-theme-plugin`.
+
+Good fits:
+
+- Government, municipal, public-sector information sites.
+- Compliance and readability prioritized over a distinctive look.
+
+Caveats:
+
+- Reskinning to non-DADS palettes erodes the "DADS-compliant" claim.
+- For public-sector work, don't take AI-suggested decorative changes
+  at face value — keep accessibility first.
+
+## Standard workflow
+
+1. Copy an official theme.
+
+   ```bash
+   npm run copy-theme blog my-blog
+   ```
+
+   The `my-` prefix marks the copy as user-owned;
+   `npm run update-ampless` leaves anything under `themes/my-*/` alone.
+
+2. Implement inside the theme first.
+
+   In priority order:
+
+   - `themes/my-blog/tokens.css` — colors, fonts, spacing, rules,
+     Markdown body styling.
+   - `themes/my-blog/manifest.ts` — fields exposed to the admin UI.
+   - `themes/my-blog/pages/` — per-route layouts (home / post / tag /
+     feed / sitemap).
+   - `themes/my-blog/components.tsx` (or similar) — shared UI used
+     only within this theme. Header, footer, wordmark, and such can
+     live here.
+
+3. Activate the theme.
+
+   Open `/admin/sites/<siteId>/theme`, select `my-blog`, save. Theme
+   switching is a runtime setting — no redeploy required.
+
+4. Verify.
+
+   ```bash
+   npm run dev
+   npx tsc --noEmit
+   npm run build
+   npm run lint
+   ```
+
+   If `npm run lint` is misaligned with the project's Next.js version,
+   say so — but type-check, build, and browser verification still all
+   have to pass.
+
+## Design before you implement
+
+Before changing a theme, decide in this order:
+
+1. **Site role.** Personal blog? Technical notes? News commentary?
+   Company site? Documentation? Landing page?
+2. **Reading mode.** Slow reading of long-form posts? Fast scanning
+   of a list? Strong hero impression? Search / tag discovery?
+3. **Screen inventory.** At minimum, think through:
+   - home
+   - post detail
+   - tag / archive
+   - empty state
+   - mobile home
+   - mobile detail
+4. **Change surface.** Is `tokens.css` enough? Does `pages/` structure
+   change? Do you need a new theme-local component?
+5. **Markdown.** For blog or docs themes, Markdown elements are part
+   of the design — not afterthought.
+
+### Order of operations
+
+First, change what `tokens.css` can change:
+
+- Colors
+- Fonts
+- Backgrounds
+- Rules
+- Spacing
+- Prose / Markdown
+- Responsive sizing
+
+Then change `pages/`:
+
+- Home structure.
+- Post-list density.
+- Post-detail spacing and meta.
+- Tag / archive presentation.
+- Empty state.
+
+Last, extract repeated UI into theme-local components like
+`components.tsx`.
+
+Reach for shared `components/` or `app/` only when the change has to
+be used across multiple themes.
+
+## Working without Claude Design
+
+Read the existing theme first. Don't restart from scratch.
+
+What to read:
+
+- `tokens.css` token structure.
+- Public fields in `manifest.ts`.
+- Data fetching and rendering responsibilities in `pages/home.tsx`,
+  `pages/post.tsx`, `pages/tag.tsx`.
+- `themes/<official-name>/README.*` if present — theme-specific intent.
+
+How to proceed:
+
+1. Decompose the requirements into "reading experience", "information
+   density", "brand feel", and "content types".
+2. Set the broad direction in `tokens.css`.
+3. Change `pages/` only where needed.
+4. Extract repeated chrome into theme-local components.
+5. Always include Markdown elements in the design.
+
+Markdown elements to check:
+
+- Headings `h1` / `h2` / `h3`
+- Paragraphs
+- Lists
+- Tables
+- Blockquotes
+- Inline code
+- Code blocks
+- Images
+- Links
+
+For reading-focused sites, body legibility is the top priority.
+Express the design through the framing — spacing, rules, navigation,
+list density, meta typography — not the body itself.
+
+## Using AI for theme customization
+
+Don't treat AI as a single "implement everything" tool. Accuracy goes
+up when you split the work across roles.
+
+A workable split:
+
+- **Design exploration**: Claude Design, ChatGPT, image generation —
+  produce a direction.
+- **Implementation plan**: Codex / Claude Code reads the existing
+  theme and decides which files reflect the plan.
+- **Implementation**: edits inside the theme.
+- **Verification**: Desktop / Mobile browser screenshots.
+- **Polish**: overflow, empty states, Markdown, long titles.
+
+### What to feed the AI
+
+When you ask an AI to draft a theme, include:
+
+- Site name.
+- Site content.
+- Audience.
+- Primary post types.
+- Vibes to avoid.
+- Reference sites or screenshots.
+- That both Desktop and Mobile are required.
+- That home / archive / detail / empty-state are all required.
+- That Markdown — tables, lists, code, blockquotes — is in scope.
+
+Example:
+
+```text
+Design a theme for ishinao.net, a personal blog. The content is
+day-to-day life, technical notes, and short news commentary.
+Body legibility is the top priority because this is a reading site,
+but the home, archive, header, and meta deserve real design.
+Produce Top-empty, Top-with-content, Archive, and Detail for both
+Desktop and Mobile. Markdown tables, lists, blockquotes, and code
+blocks should sit cleanly inside the theme's world.
+```
+
+### Don't trust AI output verbatim
+
+Common gaps in AI-produced themes:
+
+- Desktop looks great; Mobile breaks.
+- Hero is polished but post detail looks generic.
+- Decoration wins over body legibility.
+- Markdown tables / code aren't designed.
+- No empty state.
+- Long real-world Japanese titles overflow.
+- Spacing / type sizes drift between mockup and implementation.
+
+Treat AI output as a **visual spec**, not finished code.
+
+## Using Claude Design
+
+Claude Design output HTML is usually a collection of artboards across
+multiple screens, not a single finished site. Don't port the HTML
+verbatim — extract the design intent per screen and map it onto the
+ampless theme structure.
+
+### Reading the output
+
+First, classify the artboards by screen from the HTML or screenshots:
+
+- Desktop / Top empty
+- Desktop / Top with content
+- Desktop / Archive list
+- Desktop / Detail
+- Mobile / Top
+- Mobile / Archive
+- Mobile / Detail
+
+Then pull the shared tokens out of each screen:
+
+- Background color
+- Accent color
+- Rule color
+- Font family
+- Heading size relationships
+- Body line-height
+- List density
+- Spacing unit
+- Header / footer chrome
+- Mobile widths, padding, line breaks, info-elision rules
+
+Don't implement from a single artboard in isolation. Look at Desktop
+and Mobile together to see how the same UI transforms.
+
+### Mapping to ampless
+
+Map Claude Design screens onto the ampless theme structure:
+
+- 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`
+- Shared header / wordmark / footer →
+  `themes/my-blog/components.tsx`
+- Colors, fonts, grid, prose, responsive → `themes/my-blog/tokens.css`
+- Values exposed in the admin UI → `themes/my-blog/manifest.ts`
+
+Don't copy generated code or inline styles wholesale. What you need
+is the design rules, not the implementation.
+
+### Implementation tips
+
+Extract by hand from the Claude Design HTML:
+
+- Screen types.
+- Shared tokens.
+- Layout grid.
+- Heading size scale.
+- List row height, rule treatment, meta position.
+- Mobile elision / vertical stacking / size changes.
+- Empty-state handling.
+
+On the ampless side, slot those into:
+
+- Shared design language → `tokens.css`
+- Screen structure → `pages/*.tsx`
+- Repeating UI → theme-local `components.tsx`
+- Admin-editable values → `manifest.ts`
+
+If a Claude Design board carries multiple states, note them first.
+Example:
+
+```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
+```
+
+Treat the list as your implementation checklist.
+
+### Claude Design reflection checklist
+
+- Implemented both Desktop and Mobile?
+- Handled both empty and populated states?
+- Same design language flows through list / detail / tag pages?
+- Wordmark, nav, meta, rules, background treated consistently?
+- No horizontal scroll or text overflow on mobile?
+- Long Japanese titles don't break the layout?
+- 1 / many / no-tag / multi-tag posts all render cleanly?
+- Markdown tables / code blocks don't float outside the theme world?
+
+## Using other AI tools (no Claude Design)
+
+You can still get a lot out of AI without Claude Design.
+
+### Ask in text
+
+Have the AI write a design spec first:
+
+```text
+Based on the blog theme, draft a theme spec for a personal technical
+blog. Output is a written spec — not code — split across tokens,
+home, post detail, tag archive, mobile rules, and Markdown styling.
+Body legibility is the top priority; decoration lives in the chrome
+and lists.
+```
+
+Then hand the spec to Codex / Claude Code for implementation.
+
+### Use reference images / screenshots
+
+If you have reference imagery, have the AI extract:
+
+- Colors.
+- Font vibes.
+- Spacing.
+- Rules.
+- Information density.
+- Desktop / Mobile differences.
+- What should land in `tokens.css`.
+- Whether `pages/` structure has to change.
+
+### Asking AI to implement
+
+Phrase the implementation ask narrowly:
+
+```text
+Edit only themes/my-blog. Don't touch shared app / components / lib.
+Read the existing theme first to learn the tokens.css / pages /
+manifest responsibilities. Verify Desktop 1440px and Mobile 390px in
+the browser. Style Markdown tables, lists, blockquotes, and code
+blocks consistently with the theme.
+```
+
+A vague "make it look good" prompt is how you end up with shared
+files edited and Mobile forgotten.
+
+## Browser verification
+
+UI / theme changes need a real dev server. Open the actual pages.
+
+```bash
+npm run dev
+```
+
+Representative widths:
+
+- Desktop: `1440 x 1100`
+- Mobile: `390 x 844`
+
+When taking screenshots, append a query string to bypass any
+intermediate cache:
+
+```text
+http://localhost:3000/?v=theme-check-1
+```
+
+What to look for:
+
+- First impression matches the reference direction.
+- Text doesn't overflow its parent.
+- No horizontal scroll on mobile.
+- Background, rules, spacing, and type scale all feel right at the
+  width.
+- Body contrast and line-height are comfortable to read.
+- Empty link / tag / nav / footer configurations don't leave dead
+  chrome behind.
+
+## Theme-local components
+
+Theme-specific shared UI belongs in the theme, e.g.
+`themes/my-blog/components.tsx`.
+
+Good candidates:
+
+- Header
+- Footer
+- Wordmark
+- Post row
+- Meta block
+- Theme-specific decorative UI
+
+Put something in shared `components/` only when it has to be reused
+across multiple themes or by the admin UI.
+
+## Common failure modes
+
+- Implementing only the first Claude Design thumbnail you opened.
+- Hugging Desktop and missing the Mobile artboards.
+- Editing shared `components/` for a change `tokens.css` could have
+  handled.
+- Editing the official `themes/blog/` directly.
+- Leaving Markdown tables, blockquotes, and code blocks unstyled.
+- Calling a change "done" because the build passed, with no browser
+  check.
+- Empty footer / nav configurations still rendering empty chrome.

package/dist/templates/_shared/package.json

@@ -25,15 +25,15 @@
     "@tiptap/pm": "^3.23.6",
     "@tiptap/react": "^3.23.6",
     "@tiptap/starter-kit": "^3.23.6",
-    "@ampless/plugin-og-image": "^0.2.0-alpha.14",
-    "@ampless/plugin-rss": "^0.2.0-alpha.14",
-    "@ampless/plugin-seo": "^0.2.0-alpha.14",
-    "@ampless/plugin-webhook": "^0.2.0-alpha.14",
-    "@ampless/admin": "^1.0.0-alpha.36",
-    "@ampless/backend": "^1.0.0-alpha.27",
-    "@ampless/runtime": "^1.0.0-alpha.20",
+    "@ampless/plugin-og-image": "^0.2.0-alpha.15",
+    "@ampless/plugin-rss": "^0.2.0-alpha.15",
+    "@ampless/plugin-seo": "^0.2.0-alpha.15",
+    "@ampless/plugin-webhook": "^0.2.0-alpha.15",
+    "@ampless/admin": "^1.0.0-alpha.37",
+    "@ampless/backend": "^1.0.0-alpha.28",
+    "@ampless/runtime": "^1.0.0-alpha.21",
     "@digital-go-jp/tailwind-theme-plugin": "^0.3.4",
-    "ampless": "^1.0.0-alpha.14",
+    "ampless": "^1.0.0-alpha.15",
     "aws-amplify": "^6.17.0",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-ampless",
-  "version": "1.0.0-alpha.56",
+  "version": "1.0.0-alpha.58",
   "description": "Create a new ampless project",
   "license": "MIT",
   "type": "module",