Claude Design / CodeでGitHubにある既存PJからデザインシステムをagent skillにする

Claude Designでデザインシステムを作って、それをClaude Codeでプロジェクト固有のスキルとして取り込み、そのままリポジトリのリファクタまで一気にやってみました。GitHubと連携してリポジトリから作らせた生成物が、最終的に自分のリポジトリのコンポーネントをリファクタするPRに化けるところまでの一連の操作ログです。

Claude DesignからStart with a fileで入る

Claude Designにアクセスすると、トップに「Start with a file」「Slides」「Product prototype」「Product wireframe」「Document」「Animation」などのテンプレートが並んでいます。今回は既存リポジトリをベースにデザインシステムを起こしたかったので、左端の「Start with a file」から始めました。

クリックすると「Add a design system」というモーダルが出てきます。2択になっていて、「Create here(Connect to Figma or GitHub, or upload slides and assets)」と、「Create using Claude Code(BEST FIDELITY / Best fidelity if you have React components)」が表示されました。今回はGitHub経由でリポジトリを読ませたかったので、上の「Create here」を選択。

「BEST FIDELITY」のラベルがついている方はReactコンポーネントを持っているなら最良、という案内です。Reactコンポーネントを既に持っていてかつローカルで動かしたいならClaude Code経由が良さそうですが、今回はWeb UI上で完結させたかったのでCreate hereのほうを試しています。

Set up your design system でGitHubリポジトリを連携する

次の画面が「Set up your design system」です。Company name and blurb(or name of design system)を入力するテキストエリアと、Provide examples of your design system and productsという(all optional)とラベルされた領域があります。

素材の入れ方は4種類用意されています。Link code from GitHubでリポジトリURLを貼って追加するか、Link code from your computerでフォルダをドラッグ&ドロップ、Upload a .fig fileでFigmaファイル、Add fonts, logos and assetsでフォントやロゴをアップロードできます。.figファイルについては「Parsed locally in your browser – never uploaded.」と書かれていて、ブラウザ上でパースしてアップロードはしないみたいです。

Link code from your computerのところには「This doesn’t upload the whole codebase; Claude will copy selected files. For large codebases, we recommend attaching a frontend-focused subfolder.」とあり、コードベース全体ではなくフロントエンド側のサブフォルダだけ渡すのを推奨しているみたいです。今回はモノレポではない単独の小さいリポジトリだったので、リポジトリのルートURLをそのまま渡しました。

Link code from GitHubのURL欄に https://github.com/hideokamoto/stripe-apps.hidetaka.dev を入力してAddを押すと、「Connected as hideokamoto – configure to grant access to more repos」と表示され、リポジトリがチップとして追加されました。

Claude Design ImportというGitHub Appをインストールする

初回はGitHubアプリのインストールを求められます。「Install Claude Design Import」「Where do you want to install Claude Design Import?」というタイトルで、自分のユーザーアカウントを選ぶ画面に飛ばされました。

アプリの権限ページに移動すると、Claude Design Importの説明が表示されます。Developed by anthropics(https://claude.ai/design) と書かれていて、「Allow Claude Design to read from your repository to create up to date prototypes of your product」というのが目的のようです。

Permissionsは「Read access to code, issues, metadata, and pull requests」のみで、書き込み権限はなしです。Repository accessはAll repositoriesかOnly select repositoriesの選択ができます。プロトタイピング用途と割り切ってAll repositoriesで進めましたが、業務リポジトリでやる場合はOnly select repositoriesでスコープを絞ったほうが安心ですね。

5分待つとデザインシステムが生成される

素材を渡してContinue to generationを押すと、「It will take about 5 minutes to generate your design system. You can step away. Keep the tab open in the background.」と表示されてGenerateボタンが出てきます。タブを閉じなければ別の作業をしていても良い、という案内です。

Generateすると、Design Systemというプロジェクトが作成され、画面右側に「Creating your design system… Keep this tab open and come back in 5 minutes」と表示されました。左側にはCreate design systemに対するClaudeからの返答として、「I’ll start by exploring the provided resources. Let me check the project state and the GitHub repo.」とあり、Listing files in projectが進んでいきます。

しばらく経つとUpdated todosが出てきました。リポジトリの内容を読んで、自分でやることリストを組み立てています。

• Explore repo + understand Revtrona brand
• Import logos/assets into assets/
• Write token CSS files + fonts + root styles.css
• Write README.md (context, content + visual foundations, iconography)
• Build foundation specimen cards (Type, Colors, Spacing, Brand)
• Author core components (Button, Badge, Card, etc) with .d.ts + cards

渡したリポジトリのコードベースを見て、ブランド名(今回はRevtrona)を識別し、トークンCSS、フォント、styles.css、README、Type/Colors/Spacing/Brandのスペックカード、Button/Badge/Cardなどのコアコンポーネントまでを生成計画として並べてくれているみたいです。

生成完了とCaveatsの正直さ

5分ほど経つとデザインシステムが完成しました。プロジェクト名はRevtrona Design Systemになっています。Finishing upのステップを経て、完了報告が出ます。

完了メッセージはこんな感じです。

The Revtrona Design System is complete. I finished the remaining pieces from the interrupted run: fixed the token annotations, added a dense components showcase card, built the website UI kit, wrote SKILL.md, and updated the README index. The Design System tab now shows 17 cards (Type, Colors, Spacing, Brand, Components, Website).

Design Systemタブに17枚のカードが並ぶ構成になっていて、SKILL.mdも自動生成されたとあります。右側プレビューには「Arrow & CTA language」(View productsボタン、Read the blogボタン、詳細を見る→ボタンと、最新: Stripe Adaptive Pricing 対応のLiveBadge)、「Grid & glow」(Engineering canvas / 60px grid · dual radial glows · fixed, behind content)といったSpecimen cardsが描画されています。

面白いのは、完成と一緒に「Caveats / things to flag」を自分から並べてきたところです。

• Fonts are Google Fonts CDN, not bundled @font-face files – so the compiler reports “Fonts: (none)”. Space Grotesk, Noto Sans JP, and JetBrains Mono are the real brand fonts (loaded via styles.css). If you want them shipped as self-hosted binaries for offline/production use, send the .woff2 files and I’ll add @font-face rules.
• Starting points are deprecated in this system in favor of templates/. I left the @startingPoint tag on the website screen as the spec requested, but I can convert it into a proper templates/marketing-hom...

「フォントはGoogle Fonts CDN参照で、@font-faceでバンドルしていないからコンパイラ上ではFonts: (none)って出ますよ。自前ホスティングしたいなら.woff2送ってもらえれば@font-faceルール追加します」「Starting pointsは今のシステムではdeprecated扱いで、templates/に置き換わっていますよ」など、こちらが指摘する前に「ここはこういう制約・設計判断があるので把握しておいて」を渡してくれます。AIに作らせる時、自己評価を盛らずに留保を出してくるのは助かりますね。

このタイミングで「いいと思う。ただし会話は日本語がいいな。あとはブログなどのフロー系コンテンツの詳細ページとツール紹介などのストック系ページのUI Kitが欲しいかなと思います」と返事をして、追加のUI Kit化を依頼しました。

Claude DesignのプロジェクトURLをClaude Codeに渡して取り込ませる

ここからが本題です。Claude DesignでできたデザインシステムをClaude Code側に持っていって、プロジェクト固有のagent skillとして配置したい。

渡した指示はシンプルにこれだけ。

Import this Claude Design project using the Claude Design connector:
https://claude.ai/design/p/4510a176-0017-4b99-bb3c-e3786415e0a7

.SKILL.md(とデザインシステム一式)を取得し、このPJ固有のagent skillとして配置しなさい

ブラウザ版のClaudeでは「正直な結論」が返ってきた

最初はブラウザ上のClaudeで試しました。まず「セッションを初期化しました」「現在のプロジェクト構造と .claude/ ディレクトリを確認しながら、デザインプロジェクトのURLをフェッチします」と返ってきて、URLをフェッチしようとしますが、「認証が必要なため直接アクセスできません。Claude Design connectorに関連するツールを探します」となり、ClaudSkillsのdesign-importスキルの内容を取得しに行っています。

最終的に返ってきたのは、いわゆる「曖昧に成功っぽく振る舞う」ではなく、ちゃんと「正直な結論」を出してくる答えでした。

正直な結論:
Claude Design connectorが有効なセッション(ブラウザ上でclaude.aiにログインした状態でClaude Codeを使っている状態)でないと、このURLからのインポートはできません。

できることの選択肢:
1. ブラウザでそのClaudeDesignプロジェクトを開いて、エクスポートされたSKILL.mdの内容をここに貼り付けてもらう
2. 既にリポジトリにある globals.css のデザイントークンをベースに、このプロジェクト固有のSKILL.mdを私が作成する
3. Claude.ai/designのブラウザ上で「Export → Handoff to Claude Code」でダウンロードしたファイルを共有してもらう
どうしますか？

Claude Designのconnectorが有効になっているのは「ブラウザでclaude.aiにログインした状態でClaude Codeを使っているとき」、というのが直接の制約のようです。ブラウザ版から動かそうとすると、connector用のOAuthセッションがそちらには来ていない、ということなのでしょう。代わりに、SKILL.mdを手動で貼り付けるか、Export → Handoff to Claude Codeでダウンロードしたものを渡すか、リポジトリのglobals.cssから逆算して自前でSKILL.mdを書いてもらうか、の3案を返してきました。

ここで気になったのは、Claude Designの画面側に「Export → Handoff to Claude Code」というメニューがあると示唆されている点です。Web上のClaude Designで完結させてエクスポート、というルートはちゃんと用意されているみたいですね。

ローカルのClaude Codeに切り替えるとconnectorが効く

同じ指示をローカルマシンのClaude Code CLI上で投げてみると、今度はちゃんと動きました。

「プロジェクトのメタデータとファイル一覧を取得します」のあとに、Design: Read project metadata と Design: List project files というツールが見えています。これがClaude Design connector経由で提供されるツールです。

Tool use

Design: Read project metadata(Read project metadata)
Read and update the user's claude.ai/design design-system projects through their claude.ai login. Use this together with the /design-sync skill to keep a local component library in sync with a Claude Design project — incrementally, one component at a time, never as a wholesale replace.

The tool dispatches on `method`:…

scope expansion — approving persists user:design:write to the OAuth credential store
Do you want to proceed?
> 1. Yes
  2. No

注目したいのは2点あります。1つは Design: Read project metadata の説明文に「Use this together with the /design-sync skill to keep a local component library in sync with a Claude Design project – incrementally, one component at a time, never as a wholesale replace.」とあること。/design-sync という別のスキルが存在していて、ローカルのコンポーネントライブラリをClaude Designプロジェクトと同期する用途で組み合わせて使う設計みたいです。しかも「1コンポーネントずつ差分で同期、wholesale replaceはしない」とわざわざ書いてあるのは、ローカル側の手入れを潰さない設計思想に見えます。

もう1つは「scope expansion – approving persists user:design:write to the OAuth credential store」という確認です。Read project metadataと言いつつ、承認するとuser:design:writeのスコープがOAuthクレデンシャルストアに保存される。書き込みも前提に入っているということになります。Doublecheck系のステップを挟んで、こちらに明示的に承認させているのは丁寧です。Yesで進めました。

.claude/skills/ 配下にProject skillとして配置される

承認後はそのまま .claude/skills/ 配下に書き出していきます。ターミナルにはこんな出力が並びました。

● .claude/skills/ ディレクトリを作成して全ファイルを配置します。

● Bash(mkdir -p
       /Users/okamotohidetaka/development/my-services/sites/stripe-apps.hidetaka.dev/.claude/skills/revtrona-design/tokens
       /Users/okamotohidetaka/development/...)
  ⎿ Done

● Write(.claude/skills/revtrona-design.md)

  Create file
  .claude/skills/revtrona-design.md
  ---
  name: revtrona-design
  description: Use this skill to generate well-branded interfaces and assets for Revtrona, either for production or throwaway prototypes/mocks/etc. Contains essential design guidelines, colors, type, fonts, assets, and UI kit components for prototyping.
  user-invocable: true
  ---

  Read the `.claude/skills/revtrona-design/README.md` file within this skill, and explore the other available files under `.claude/skills/revtrona-design/`

エントリポイントになる revtrona-design.md はuser-invocable: true付きで、本体ディレクトリのREADME.mdを読みに行く構造になっています。Project skillの標準的な作り方そのものですね。

最終的にできたファイル構成はこんな感じになりました。

.claude/skills/
├── revtrona-design.md        ← エントリポイント (user-invocable: true)
└── revtrona-design/
    ├── README.md             ← ブランドガイドライン全文(ビジュアル / コンテンツ / アイコン)
    ├── styles.css            ← グローバルエントリ(これ1枚をlinkすればOK)
    ├── tokens/
    │   ├── colors.css        ← --rvt-* カラートークン(dark/navy/light テーマ)
    │   ├── typography.css    ← フォント・スケール・ウェイト・トラッキング
    │   ├── spacing.css       ← 間隔・角丸・モーション・レイアウト
    │   └── base.css          ← リセット + グリッド背景 + JP テキストルール
    └── components/core/
        ├── Button.prompt.md
        ├── Card.prompt.md
        ├── Badge.prompt.md
        ├── Eyebrow.prompt.md
        ├── Tag.prompt.md
        ├── StatTile.prompt.md
        ├── CodePanel.prompt.md
        └── LiveBadge.prompt.md

整理されているなと思ったのは、グローバルなstyles.css1枚をlinkすれば全部入る構造になっていて、その内訳がtokens/(colors, typography, spacing, base)とコンポーネントがcomponents/core/の *.prompt.md という形に分離されている点です。CSSトークンは普通のCSSとして使え、コンポーネントは「プロンプトとして」配置されているので、Claude Code側からはこのスキルが呼ばれたタイミングで該当コンポーネントのプロンプトを読み込んで生成に反映できます。

カラートークンは --rvt-* というCSS変数プレフィックスで、dark/navy/lightのテーマ切り替えに対応した形になっていました。

使い方の案内はこう書かれていました。

今後この PJ の会話で /revtrona-design と呼び出すと、デザイントークン・コンポーネントルール・ブランドガイドラインを参照したうえでモック・プロトタイプ・本番コードの生成が可能になります。

そのままリポジトリのリファクタに使ってPRまで持っていく

せっかくProject skillとして取り込んだので、デザインシステムのトークンに合わせて既存のコンポーネントをリファクタさせるところまでやってみました。

Claude Codeがリポジトリ全体を見たうえで、リファクタ方針を以下のようにまとめてきました。

● 全体像を把握しました。リファクタリング方針をまとめます：

  1. components/ui/ 新規プリミティブ — Button, Tag, Eyebrow, Card(デザインシステムに対応)
  2. Badge.tsx — dark: を --rvt-* 変数に置換、テストも更新
  3. Feature.tsx — ライトテーマの誤ったスタイルを全面刷新(ブランドの dark aesthetic に合わせる)
  4. CredibilityBadges.tsx / Breadcrumb.tsx / OutdatedNotice.tsx / ErrorPageLayout.tsx — dark: prefix(この PJ では機能していない)を --rvt-* に全置換

  ブランチを切って実装します。

● Bash(git checkout -b refactor/design-system-tokens)
  ⎿ Switched to a new branch 'refactor/design-system-tokens'

面白かったのは、CredibilityBadges.tsx / Breadcrumb.tsx / OutdatedNotice.tsx / ErrorPageLayout.tsx について「dark: prefix(この PJ では機能していない)」とコメントしている点です。元のリポジトリではTailwindのdark:修飾子がついていたものの、テーマ切り替えの方式とは噛み合っておらず、実際には効いていなかった、というのを見抜いて--rvt-*変数経由のテーマ切り替え方式に統一する判断をしています。

このリファクタは2本のPRに分かれて入りました。最初のPR #257でトークンへの刷新を進め、残り作業を #258 で続き、最終的にPR #257「refactor: デザインシステムトークンに基づくコンポーネント刷新」としてmainにマージされています。Conversation 14, Commits 3, Files changed 26, +617 -521 という変更量です。

SummaryにはPR #257の続きとして残っていた dark: prefixをすべて除去したこと、[data-theme="navy"|"light"] 属性ベースのテーマ切り替えで正しく動作するように修正したことが書かれています。CodeRabbitとgemini-code-assistの2つのレビューBotがレビューに入っていて、Conversationが14スレッドついていますが、最終的にmainにマージできているのでBot指摘もある程度こなした上で着地できた格好です。

触ってみた印象

Claude DesignでGitHubリポジトリから「そのプロジェクト用の」デザインシステムを生成し、それをClaude Code側で.claude/skills/のProject skillとして取り込み、その同じスキルを呼んでリポジトリ自身のリファクタPRを出すところまで、一連の流れがほぼ自動でつながりました。Claude Design内で完結する「デザインシステム生成器」というよりは、claude.ai/designをハブにしてClaude Code側のコード生成までを同期させる仕組み、と捉えたほうが実態に近いかなと思います。

引っかかったのは、ブラウザ上のClaude(Claude Code on the web想定)からClaude Design connector経由でImportしようとすると、認証セッションの都合で動かないという点でした。素直にローカルのClaude Code CLIで叩くと Design: Read project metadata / Design: List project files といったツールが使え、user:design:writeスコープの追加承認もちゃんと挟まれます。今のところは「ローカルClaude Codeから取り込む」のが素直なルートみたいです。

もうひとつ、/design-syncというスキルの存在も気になりました。今回はwholesale importで終わらせていますが、生成済みデザインシステムを部分的に取り込んで運用していくフェーズに入ったら、こちらを試す価値がありそうです。