asdesigned

asdesigned

設計どおりですか？レンダリングされた UI コンポーネントを Figma のソースと比較して、どこに差異が生じたかを正確に確認できます。 コーディングエージェント向けに構築されています。Claude Code や Cursor にこのツールを渡せば、エージェント自身の作業をデザインと照らし合わせて確認できます。

asdesigned compare https://www.figma.com/design/<key>/<file>?node-id=12-345 \
      --url http://localhost:3000 --selector .btn-primary

design   figma  Button / Primary  1:4
rendered dom  <button class="btn-primary">  .btn-primary

box
  ✗ width          design 120px → rendered 112px (−8px)
padding
  ✗ left           design 16px → rendered 12px (−4px)
  ✗ right          design 16px → rendered 12px (−4px)
border
  ✗ color          design #1d4ed8 → rendered #2563eb (Δ29.43)
typography
  ✗ fontFamily     design "Inter" → rendered "Arial"
  ✗ fontWeight     design 600 → rendered 500 (−100)

6 drift · 20 match
FAIL  (tolerance ±1px, color Δ≤4)

この出力は、実際のものです。実際の Figma コンポーネントと examples/button.html を比較しています。6 つのうち 5 つは意図的に仕込まれた差異でした。 残る 1 つは違いました。<button> 要素は font-family を継承しないため、ページは気づかれないまま Arial にフォールバックしていました。 スクリーンショットのレビューでは誰も気づきません。差分ならわかります。

Figma は意図を示します。ブラウザーは現実を示します。asdesigned はその 2 つを比較し、コーディングエージェントから呼び出して自身の作業を確認できます。

ステータス：v0.2 — 初期段階ですが、利用可能です。 Figma → 仕様、DOM → 仕様、差分、ターミナル＋HTML レポート、MCP サーバー、 インタラクション状態に対応しています。1 回の実行で比較するビューポートは 1 つです。対応範囲をご覧ください。

インストール

npx asdesigned --help            # no install
npm i -g asdesigned              # or install the `asdesigned` command globally
npx playwright install chromium   # one-time: the browser used to render pages

環境または .env ファイルに FIGMA_TOKEN（file content: read 権限を持つ Figma 個人用アクセストークン）を設定します。

エージェントから使う（MCP）

asdesigned には MCP サーバーが付属しているため、Claude Code、Cursor、その他の MCP クライアントから直接呼び出せます。 ツール：compare_design、inspect_element、inspect_figma。 3 つとも状態に対応しています。compare_design は states: ["default","hover","focus"]、inspect_element は 単一の state、inspect_figma は variants: true を指定すると、コンポーネントセットにデザインされたバリアントを一覧表示します。

Claude Code — プロジェクト内の .mcp.json：

{
  "mcpServers": {
    "asdesigned": {
      "command": "npx",
      "args": ["-y", "asdesigned", "asdesigned-mcp"],
      "env": { "FIGMA_TOKEN": "figd_…" }
    }
  }
}

Cursor — .cursor/mcp.json。形式は同じです。

エージェントがこのツールをいつ、どのように使うべきかを説明するスキルファイルは skills/asdesigned/SKILL.md にあります。エージェントのスキルフォルダーに配置してください。

ターミナルから使う

asdesigned compare <figma-url> --url http://localhost:3000 --selector .btn-primary
asdesigned compare <figma-url> --url … --selector … --states hover,focus  # interaction states
asdesigned compare <figma-url> --url … --selector … --html report.html   # self-contained visual report
asdesigned compare <figma-url> --url … --selector … --json               # for CI / scripts
asdesigned inspect http://localhost:3000 --selector .btn-primary
asdesigned inspect http://localhost:3000 --selector .btn --state hover   # one rendered state
asdesigned inspect <figma-url> --variants                                # what states are designed

インタラクション状態

--states hover,focus,active,disabled（または --states all）を指定すると、各状態を個別のセクションとして比較します。

レンダリング側では、算出スタイルを読み取る前に該当する疑似クラスを強制的に適用します。:focus と :focus-visible の両方を使うため、モダンなフォーカスリングも見逃しません。デザイン側の状態は Figma の コンポーネントセットのバリアントから取得します。State=Hover、State=Focused のほか、デザイナーが使う 別の表記（Pressed、Rest、Inactive）もすべて解決されます。セット自体、またはその中の任意のバリアントを指定すると、asdesigned は componentSetId をたどって兄弟を見つけます。

Button / Primary  3 variants  1:10

default  1 drift  figma  State=Default  1:11
  border
    ✗ color          design #1d4ed8 → rendered #2563eb (Δ29.43)
  1 drift · 20 match

hover    no drift  figma  State=Hover  1:12
  0 drift · 21 match

focus    skipped  "Button / Primary" has no focus variant (it defines: default, hover) — nothing to compare against

1 drift · 41 match · 2 states compared · 1 skipped
FAIL

デザインで定義されていない状態は、失敗ではなくスキップされます。asdesigned が期待値を勝手に作ることはありません。 このスキップ自体も確認する価値があります。Focused バリアントがないなら、フォーカスリングはデザインされていません。これはコードのバグではなく、デザインファイル側の不足です。リクエストした状態が すべてデザインされていない場合、実行結果は NOTHING COMPARED となり、ゼロ以外の値で終了します。そのため、何も確認せずに状態チェックが 暗黙に成功することはありません。

差異が見つかった場合の終了コードは 1 です。そのため、compare を CI チェックとして利用できます。

仕組み

両側を、フラットな StyleSpec に正規化します。値は px 単位の数値と RGBA カラーで、すべてのフィールドは省略可能です。純粋な差分比較では、妥当な許容範囲（±1px、わずかな色差、フォントの太さは許容差なし）を使って両者を比較します。 片側にないフィールドは報告されますが、実行は失敗しません。実際の差異がある場合にのみ失敗します。

インタラクション状態も、これらすべてをそのまま再利用します。各状態は 1 組の spec ペアなので、diff に状態の対応を追加する必要はありませんでした。

• src/spec.ts — 共通フォーマット
• src/diff.ts — 比較処理
• src/states.ts — 状態の語彙と、Figma のバリアントから状態への対応付け
• src/compare.ts — 状態ごとの比較と、状態がデザインされていない場合の報告内容
• src/readers/figma.ts — Figma REST から spec への変換。コンポーネントセットのバリアントも含みます
• src/readers/dom.ts — Playwright の計算済みスタイルから spec への変換。CDP 経由で疑似クラスを強制します
• src/report.ts、src/report-html.ts — 出力

チェック対象と対象外

asdesigned は、指定した UI 状態において、1 つのデザインノードと 1 つのレンダリング済み要素を、1 つのビューポートで比較します。 これにより、最もよく見られる差異、つまりパディング、サイズ、色、そして上記の Arial フォールバックのような継承フォントに関する問題をチェックできます。また、--states を使って、ホバー、フォーカス、アクティブ、無効の各状態もチェックできます。

インタラクション状態には、明記しておくべき要件が 1 つあります。デザインで状態をバリアントとして定義する必要があります。 State=Hover を持つコンポーネントセットは解決できますが、フラットなフレームや、ホバーがプロトタイプのインタラクションとしてしか存在しないファイルでは、asdesigned が比較対象を得られず、その状態はスキップされます。inspect <figma-url> --variants を実行すると、チェックの前にコンポーネントで実際にデザインされている状態を確認できます。

対象外：

• リフロー。 1 回の実行でレンダリングするのは 1 つのビューポートです。デフォルトは 1280×800 で、--viewport WxH で指定できます。ブレークポイントをまたいでコンポーネントをチェックするには、デザイナーが各ブレークポイント用に作成したフレームに対して、ブレークポイントごとに compare を実行します。すべてのブレークポイントを一括で調べるコマンドはありません。
• モーション。 トランジションの持続時間やイージングは比較しないため、状態の 終了時 の値はチェックしますが、そこに至る過程はチェックしません。
• 計算済みスタイルではないもの。 兄弟要素との相対的なレイアウト、コンテンツ、動作は、すべて対象外です。

また、ロードマップの項目ではない境界が 1 つあります。デザインされたブレークポイントの間には、デザイン上の正解はありません。 ファイルに 768 のフレームと 1280 のフレームがあっても、900px での指定はどこにもありません。asdesigned が差異を示せるのは、誰かがデザインした幅 での コンポーネントであり、幅と幅の 間 ではありません。デザインを正とするツールなら、どれも同じです。

開発

npm install
npm test
npm run build
node dist/cli.js --help

ASDESIGNED_BROWSER=/path/to/chrome を指定すると、Playwright がダウンロードするブラウザーの代わりに、既存の Chrome/Chromium を使用します。

他のツールとの関係

• Figma の MCP サーバーはエージェントにデザインを提供します。Chrome DevTools MCPはエージェントにブラウザーを提供します。asdesigned は、その間に欠けている動詞、つまり 比較する を担います。
• ビジュアルリグレッションツール（Percy、Chromatic、ピクセル差分）は、アプリのスクリーンショットを過去のアプリのスクリーンショットと比較します。asdesigned はアプリを デザイン と比較し、ピクセルではなくプロパティを報告するため、結果はヒートマップではなく修正につながります。
• design-drift は、ピクセルと要素の差分比較およびビューアーを使って、同様の領域を探っています。asdesigned は意図的により小さく、動詞 1 つ、エージェント優先、23 kB です。

ライセンス

MIT