docs(skills): 複数テーマ運用とカスタムブランドカラーの案内をスキルに反映

[touyou]

Summary

sparkle-design-cli#63（sparkle-design-internal issue #222 発見2・発見3対応）で追加した以下の内容をAIエージェント向けスキルにも反映する:

• primary は7色必須、radius は8値必須（schema validation あり）
• 7色に無いブランドカラーは extend.custom-css で --color-primary-*/--color-gray-* を丸ごと再定義
• 複数の固定配色バリアントを1デプロイで切り替えたい場合は config分割 + 複数回 generate を推奨（単一CSS+属性スコープ上書きは非推奨）

変更内容

• change-sparkle-config:
  • 前提チェックに「複数テーマ運用の要望」検知の分岐を追加し、範囲外として README の推奨パターンに誘導するようにした
  • primary が許可リスト外のときのバリデーション分岐を拡充。7色に無い特定ブランドカラーが目的なら extend.custom-css での再定義方式を案内する
• setup-sparkle-design:
  • radius の選択肢一覧が古く（存在しない full を含み xs/2xl/3xl が欠落）、CLI の実装と矛盾していたため8値に修正
  • primary/radius が必須・型検証ありである旨、複数テーマ運用時のREADME参照を追記

関連

• sparkle-design-cli#63 (未マージ): primary/radius の schema validation 追加、README への推奨パターン追記
• sparkle-design-internal#222: 元issue

補足（フォローアップ）

change-sparkle-config は sparkle-design-internal（pnpm sync:public-skills）→ sparkle-design-docs（pnpm sync:skills）の順で同期される。両スクリプトはリモート（GitHub）から取得するため、本PRと sparkle-design-cli#63 のマージ後に同期が必要（本PRでは実施していません）。install-sparkle-design（sparkle-design-internal 直下で管理）側の追記は別PRで対応予定です。

Test plan

• ドキュメント（Markdown）のみの変更のため、コード実行系のテスト・lintは対象外
• 差分を目視確認し、既存の許可リスト・記載スタイルとの整合性を確認済み

🤖 Generated with Claude Code

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sparkle-design	Ready	Preview, Comment	Jul 6, 2026 8:52am

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: ff91520b-b5af-4fb1-b13d-1510fd260eca

📥 Commits

Reviewing files that changed from the base of the PR and between 866a41b and 8b863c5.

📒 Files selected for processing (2)

• .claude/skills/setup-sparkle-design/SKILL.md
• .claude/skills/setup-sparkle-design/references/config-reference.md

✅ Files skipped from review due to trivial changes (1)

• .claude/skills/setup-sparkle-design/references/config-reference.md

---

Walkthrough

2つのSKILL.mdを更新し、複数固定配色バリアント要望のスコープ外化、primary/radiusの検証記載更新、config参照ドキュメントの追加と参照先整理を行っています。

Changes

SKILLドキュメント更新

Layer / File(s)	Summary
スコープ外要望の明記 .claude/skills/change-sparkle-config/SKILL.md	導入説明と実行方針に、複数固定配色バリアントの1デプロイ切り替え要望はスコープ外であり、config分割＋複数回generateへ誘導する旨を追記。
許可リスト検証と中断時分岐の拡張 .claude/skills/change-sparkle-config/SKILL.md	primaryが許可外の場合の中断後フローを追加し、extend.custom-css を自動編集しない前提の案内と、primary/radiusの注意書きをgenerate実行時エラー停止に更新。
setup-sparkle-design の参照更新 .claude/skills/setup-sparkle-design/SKILL.md, .claude/skills/setup-sparkle-design/references/config-reference.md	参照一覧と Progressive Disclosure に references/config-reference.md を追加し、config仕様の詳細を新規参照ドキュメントへ移動。

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

• goodpatch/sparkle-design#257: 同じSKILL.md群を編集しており、ドキュメント構成や設定案内の変更点が近いです。

Poem

ぴょんと跳ねて、道しるべを整理
スコープ外の願いはふわりと分岐
primary と radius はきちんと確認
参照先もそろって、月夜のノートは静か
うさぎはにこにこ、config を見守る 🐰

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	タイトルは複数テーマ運用とカスタムブランドカラー反映という変更点を的確に要約しています。
Description check	✅ Passed	概要・変更内容・関連・テスト方針が揃っており、テンプレートの必須情報は概ね満たしています。
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch worktree-issue-222-skill-multitheme

---

_{Comment @coderabbitai help to get the list of available commands.}

[Copilot]

Pull request overview

sparkle-design-cli 側で追加・更新された「primary/radius の必須・型検証」「7色に無いブランドカラー時の extend.custom-css 再定義方針」「複数テーマ運用の推奨パターン」を、AI エージェント向けスキル（SKILL.md）にも反映するPRです。

Changes:

• setup-sparkle-design スキルの sparkle.config.json リファレンスを更新（primary/radius の必須・型検証、radius の選択肢修正、複数テーマ運用の誘導追記）
• change-sparkle-config スキルに「複数固定配色バリアントを 1 デプロイで切り替えたい」要望の検知と範囲外誘導を追加
• primary が許可リスト外のケースで、7色に無いブランドカラー目的なら extend.custom-css での丸ごと再定義が必要である旨の案内を追記

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 1 comment.

File	Description
.claude/skills/setup-sparkle-design/SKILL.md	sparkle.config.json の項目説明を最新仕様に合わせ、複数テーマ運用時の誘導を追記
.claude/skills/change-sparkle-config/SKILL.md	複数配色バリアント要望を範囲外として検知・誘導し、primary 許可リスト外時の案内を拡充

[touyou]

⚠️ マージ順序に関する重要な注意

このPRの内容（primary/radius が未指定・不正値だと generate がエラーで停止する、README の「複数のテーマ配色を 1 デプロイでサポートしたい場合」セクション）は、sparkle-design-cli#63（未マージ）が前提です。

sparkle-design-cli#63 が merge され、npm に release されるまでは、このPRをmergeしないでください。 npx --yes sparkle-design-cli は常に最新版を取得する運用のため、CLI側が未リリースの間にこのスキルをmergeすると、AIエージェントが「エラーで止まるはず」と誤った前提でユーザーに案内し、実際には（現行CLIでは）壊れたCSSが silent に出力される、という事故に繋がります（セルフレビューで検出）。

推奨マージ順序: sparkle-design-cli#63 → （npm release）→ 本PR → sparkle-design-internal#225 → docs等への同期

セルフレビュー結果と修正

/code-review high で4観点のfinderを実行し、以下を検出・修正しました（追加コミット 866a41b）:

1. 上記のマージ順序依存（最重要）
2. 本PR自体が、change-sparkle-config と setup-sparkle-design の primary 7色列挙順に drift を作っていた → colors.json の実際の順序に統一
3. radius:"full" の既存注記（「silent に壊れる」）と、新規追記（「エラーで停止する」）が矛盾 → schema validation 導入後の挙動に統一
4. README見出しのスペース表記が2ファイルで食い違っていた → 統一
5. primary許可リスト外の分岐が1文に詰め込まれ、「本スキルはextend.custom-cssを自分で編集しない」という重要な注記が埋もれていた → サブ箇条書きに分割
6. 複数テーマ運用の検知分岐がfrontmatter descriptionのトリガーフレーズに反映されておらず、スキル自体が発動しない可能性 → フレーズ追加

[touyou]

追記: スキル文量の分割

setup-sparkle-design/SKILL.md の「sparkle.config.json リファレンス」（primary/radius 選択肢一覧・型検証の挙動・複数テーマ運用の案内）を既存の references/component-catalog.md 等と同じパターンで references/config-reference.md に切り出しました（コミット 8b863c5）。SKILL.md 本体は 263→254 行に減っています。

change-sparkle-config 側は増分が小さく、また追記内容が「実行方針」内の判定ロジック（前提チェック・書き込み前バリデーションの分岐）で毎回参照されるコアデータと密結合なため、分割は見送りました。

install-sparkle-design（internal）は今回の増分がごく小さい（正味2〜4行）ため、こちらも分割は見送っています。

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

Comments suppressed due to low confidence (1)

.claude/skills/setup-sparkle-design/SKILL.md:254

• This file was modified but the "Last Updated" stamp still shows 2026-03-31, which can mislead readers about freshness. Please update it to reflect the current change date.

- **Load for config field details / multi-theme setups**: `references/config-reference.md`

---

Last Updated: 2026-03-31