figma-to-ids

スキル：Figma から IDS への変換

目的

Figma のデザインプロパティと構造を、IDS（Iress Design System）のコンポーネント実装に変換します。このスキルは、AI エージェントが Figma のデザインメタデータ（Figma MCP などのツールやエクスポートしたデザイン仕様から取得）を解釈し、正確な IDS コードを生成するために役立ちます。

Figma MCP のセットアップ

AI エージェントが Figma ファイルを直接読み取るには、Figma MCP サーバーが必要です。MCP サーバーがない場合も、エクスポートしたデザイン仕様や Figma コンポーネントの説明を手動で貼り付ければ、このスキルを利用できます。

セットアップ

1. Figma の個人用アクセストークンを取得する — Figma で Settings → Account → Personal access tokens を開き、File content (Read-only) スコープを指定してトークンを作成します。

2. **エージェント設定に MCP サーバーを追加する。**正確な場所は使用するツールによって異なります。

   ツール	設定ファイル
   Kiro CLI	~/.kiro/settings/mcp.json（グローバル）または .kiro/settings/mcp.json（ワークスペース）
   Cursor	.cursor/mcp.json
   Claude Code	.claude/mcp.json または ~/.claude/mcp.json
   VS Code (GitHub Copilot)	.vscode/mcp.json

   コミュニティ製の figma-developer-mcp サーバーを使用した設定例：

   {
     "mcpServers": {
       "Figma": {
         "command": "npx",
         "args": ["-y", "figma-developer-mcp", "--stdio"],
         "env": {
           "FIGMA_API_KEY": "<your-figma-token>"
         }
       }
     }
   }
   

   Kiro CLI では、コマンドラインから追加することもできます。

   kiro-cli mcp add --name Figma --command npx --args "-y figma-developer-mcp --stdio" --env "FIGMA_API_KEY=<your-figma-token>"
   

3. 確認する — Figma ファイルの URL からデータを取得するようエージェントに依頼します。フレームとコンポーネントの情報が返されるはずです。

プロセス

1. Figma の構造を分析する — フレーム、オートレイアウト、コンポーネントインスタンスを特定します
2. コンポーネントを対応付ける — Figma のコンポーネント名／バリアントを IDS コンポーネントに対応付けます
3. トークンを抽出する — Figma のデザイン値を IDS デザイントークンの参照に変換します
4. コードを生成する — 適切な IDS インポートを含む、簡潔で最小限の React/TypeScript を生成します。使用するコンポーネントは必要最小限にしてください。IressInline／IressStack ラッパーを追加する前に、親コンポーネントがすでにレイアウトを処理しているか確認します。単一の子要素をレイアウトコンポーネントでラップしてはいけません。
5. 出力を検証する — すべてのインポートが解決されること、IDS コンポーネントがある箇所で生の HTML が使われていないこと、グリッドレイアウトでレスポンシブな span 値が使われていること、一般的なアンチパターン（無効化されたボタン、slot 属性、冗長な textStyle）がないことを確認します

重要： IDS v6 は現在ベータ版です。@beta タグを付けてインストールしてください。

npm install @iress-oss/ids-components@beta
npm install @iress-oss/ids-tokens@beta  # トークンを直接使用する場合（例：cssVars または CSS vars のインポート）

Figma → IDS の対応付け

Figma コンポーネントを IDS に対応付ける際は、完全な Figma コンポーネント → IDS コンポーネントの対応表について、references/component-mapping.md を参照してください。

Figma のデザイン値（色、間隔、角丸、タイポグラフィ）を IDS トークンに変換する際は、references/token-mapping.md を参照してください。

ニュートラルなテキスト色では、colour.neutral.90 を colour.neutral.80 の後方互換エイリアスとして扱ってください（どちらも #141F4D に解決されます）。新しい IDS 実装では colour.neutral.80 を優先しますが、古い Figma ファイルを変換する場合は、どちらのトークン名にも対応してください。

変換例

Figma：ログインフォームのフレーム

Figma の構造：

• フレーム：縦方向のオートレイアウト、間隔 16px、パディング 24px
  • テキスト：「ログイン」（見出し H2）
  • 入力：「メールアドレス」（テキスト入力）
  • 入力：「パスワード」（パスワード入力）
  • ボタン：「サインイン」（プライマリー）
  • テキスト：「パスワードをお忘れですか？」（リンク）

IDS の実装：

import {
  IressStack,
  IressText,
  IressField,
  IressInput,
  IressButton,
  IressLink,
  IressCard,
} from '@iress-oss/ids-components';

function LoginForm() {
  return (
    <IressCard p="lg">
      <IressStack gap="md">
        <IressText element="h2">Log In</IressText>
        <IressField label="Email" htmlFor="email" required>
          <IressInput id="email" type="email" />
        </IressField>
        <IressField label="Password" htmlFor="password" required>
          <IressInput id="password" type="password" />
        </IressField>
        <IressButton mode="primary" type="submit">
          Sign in
        </IressButton>
        <IressLink href="/forgot-password">Forgot password?</IressLink>
      </IressStack>
    </IressCard>
  );
}

Figma：アラートバナー

Figma の構造：

• フレーム：塗り #EBF9F5、角丸 12px、パディング 16px
  • 横方向のオートレイアウト、間隔 8px
  • アイコン：「check_circle」
  • テキスト：「変更が保存されました」（Body MD）

IDS の実装：

import { IressAlert } from '@iress-oss/ids-components';

// IressAlert already handles the layout, icon, and styling
<IressAlert status="success">Your changes have been saved</IressAlert>;

重要なポイント： IDS コンポーネントにはスタイルが組み込まれています。Figma のレイアウトや色を再現するのではなく、コンポーネントのプロパティ（status など）を使い、視覚的なスタイルは IDS に任せてください。

Figma：ステータスモーダル（危険な操作の確認）

Figma の構成：

• ヘッダーに危険アイコンがあるモーダルフレーム
  • 見出し：「レコードを削除しますか？」
  • 本文：「この操作は取り消せません。」
  • フッター：2 つのボタン（キャンセル、削除）

IDS の実装：

import { IressModal } from '@iress-oss/ids-components';

// Status modals use the `status` prop — the icon, colours, and button status are handled automatically.
// Use `actions` instead of `footer` for opinionated action buttons.
<IressModal
  status="danger"
  heading="Delete record?"
  actions={[{ children: 'Cancel', mode: 'tertiary' }, { children: 'Delete' }]}
  show={isOpen}
  onShowChange={setIsOpen}
>
  This action cannot be undone.
</IressModal>;

重要なポイント： IressModal に status を設定すると、footer プロパティは使用できません。代わりに actions を使用してください。各アクションボタンは、モーダルのステータスを自動的に継承します。サイズは sm（デフォルト）または md に制限されます。

Figma：データテーブル

Figma の構成：

• フレーム：ヘッダー行とデータ行のあるテーブル
  • ヘッダー：["名前", "メールアドレス", "ステータス", "アクション"]
  • 行：ステータス列にタグ、アクション列にボタンがあるデータ

IDS の実装：

import { IressTable, IressTag, IressButton } from '@iress-oss/ids-components';
import type { TableColumn } from '@iress-oss/ids-components';

interface User {
  name: string;
  email: string;
  status: string;
  id: string;
}

const columns: TableColumn<User>[] = [
  { key: 'name', label: 'Name' },
  { key: 'email', label: 'Email' },
  {
    key: 'status',
    label: 'Status',
    format: (value) => <IressTag>{value}</IressTag>,
  },
  {
    key: 'actions',
    label: 'Actions',
    format: (_, row) => (
      <IressButton mode="tertiary" icon="edit">
        Edit
      </IressButton>
    ),
  },
];

function UsersTable({ users }: { users: User[] }) {
  return <IressTable caption="Users" rows={users} columns={columns} />;
}

重要なポイント： IressTable はデータ駆動型です。サブコンポーネントを組み合わせるのではなく、rows と columns のプロパティを渡してください。列の format 関数を使用すると、タグやボタンなどのカスタムセルコンテンツをレンダリングできます。

レスポンシブレイアウト

Figma にデスクトップフレームしかない場合でも、常にレスポンシブな出力を作成してください。 IDS は 6 つのブレークポイントを持つ 12 列グリッドを使用します。レイアウトが小さな画面にどのように適応するかを、すべての翻訳で考慮してください。

レスポンシブデザインの原則

モバイル版の Figma フレームが提供されていない場合は、次の原則を適用してください。

1. 主なタスクを特定する — ページでユーザーが何を達成しようとしているのかを判断します（例：フォームへの入力、データの確認、意思決定）。モバイルレイアウトでは、このタスクを優先してください。
2. 複数列のレイアウトを縦に並べる — 横並びの列はすべて、モバイルでは全幅にして縦に並べてください（span={{ xs: 12, md: ... }}）。
3. 補助コンテンツを移動する — モバイルでは、主要なタスクを最優先にできるよう、補足 UI（フィルター、サイドバー、二次アクション、メタデータパネル）を IressSlideout または折りたたみ可能なセクションに移動してください。
4. 情報量の多いレイアウトを簡素化する — 多数の列を持つテーブル、複数パネルのダッシュボード、幅の広いフォームは、モバイルに適応させてください。hideBelow で必須でない列を非表示にする、セクションを折りたたむ、または useBreakpoint を使ってカードベースのレイアウトに切り替える方法があります。
5. すべての機能を維持する — モバイルで機能を削除しないでください。モバイルビューを煩雑にせずに機能を利用できるよう、IressSlideout、IressModal、展開可能なセクション、または IressTabSet を使用してください。

ブレークポイント

ブレークポイント	画面幅
xs	0 – 575px
sm	576px – 767px
md	768px – 1023px
lg	1024px – 1279px
xl	1280px – 1599px
xxl	1600px+

レスポンシブプロパティ

多くのプロパティは ResponsiveProp を受け取ります。値を 1 つ指定するか、ブレークポイントをキーとするオブジェクトを指定できます。

// Single value (all breakpoints)
<IressCol span={6} />

// Responsive — full-width on mobile, half on medium+
<IressCol span={{ xs: 12, md: 6 }} />

レスポンシブ値をサポートするプロパティ：span、offset、gap、gutter、rowGap、p、px、py、pt、pr、pb、pl、m、mx、my、mt、mr、mb、ml、width、srOnly、hideFrom、hideBelow。

Figma の複数ビューポート → レスポンシブな列

Figma に同じレイアウトのモバイル版とデスクトップ版のフレームがある場合：

Figma のモバイル版（xs）： 1 列に縦積み Figma のデスクトップ版（md 以上）： サイドバーのある 2 列レイアウト

<IressRow gutter={{ xs: 'sm', md: 'lg' }}>
  <IressCol span={{ xs: 12, md: 4 }}>
    <Sidebar />
  </IressCol>
  <IressCol span={{ xs: 12, md: 8 }}>
    <MainContent />
  </IressCol>
</IressRow>

デスクトップ版のみの Figma → 推定されるレスポンシブレイアウト

Figma にサイドバーとメインコンテンツ領域を持つデスクトップフレームしかない場合は、モバイルレイアウトを推定してください。

import { useState } from 'react';
import {
  useBreakpoint,
  IressSlideout,
  IressButton,
  IressStack,
  IressRow,
  IressCol,
} from '@iress-oss/ids-components';

function Page() {
  const { breakpoint } = useBreakpoint();
  const isMobile = breakpoint === 'xs' || breakpoint === 'sm';
  const [filtersOpen, setFiltersOpen] = useState(false);

  return (
    <>
      {isMobile ? (
        // Mobile: primary content first, secondary content in slideout
        <IressStack gap="md">
          <IressButton
            mode="secondary"
            icon="filter_list"
            onClick={() => setFiltersOpen(true)}
          >
            Filters
          </IressButton>
          <MainContent />
          <IressSlideout
            heading="Filters"
            show={filtersOpen}
            onShowChange={setFiltersOpen}
          >
            <FilterPanel />
          </IressSlideout>
        </IressStack>
      ) : (
        // Desktop: side-by-side layout as designed in Figma
        <IressRow gutter="lg">
          <IressCol span={3}>
            <FilterPanel />
          </IressCol>
          <IressCol span={9}>
            <MainContent />
          </IressCol>
        </IressRow>
      )}
    </>
  );
}

レスポンシブな表示制御

hideFrom／hideBelow CSS プロパティは、任意のコンポーネントに直接使用できます。

<IressButton hideBelow="md">Desktop action</IressButton>
<IressText hideFrom="lg">Mobile only text</IressText>

ブレークポイントに基づく条件付きレンダリング（例：まったく異なるコンポーネントのレンダリング）には、useBreakpoint フックを使用してください。

import { useBreakpoint } from '@iress-oss/ids-components';

function Navigation() {
  const { breakpoint } = useBreakpoint();
  const isMobile = breakpoint === 'xs' || breakpoint === 'sm';

  return isMobile ? <MobileNav /> : <DesktopNav />;
}

ベストプラクティス

1. コンポーネントのネストを最小限にする — 可能な限り少ないコンポーネントを使用します。すべてのラッパーには、使う理由が必要です。IressInline または IressStack を追加する前に、親コンポーネントがすでにレイアウトを処理していないか確認してください（例：IressCard には heading と footer の props があり、IressModal には actions があり、IressButtonGroup はボタンの横並びレイアウトを処理します）。子が1つだけの要素をレイアウトコンポーネントで囲まないでください。
2. 生の要素ではなく IDS コンポーネントを使う — IDS コンポーネントには、適切な余白、色、角丸、アクセシビリティが組み込まれています。
3. コンポーネントの内部構造を再現しない — Figma で特定のパディングや角丸が設定されたボタンが表示されている場合は、適切な mode を指定して IressButton を使います。スタイルは組み込み済みです。
4. Figma の gap／padding をスペーシングトークンに対応付ける — ピクセル値を4で割ってトークン番号を求め、完全なトークン名を使います。16px → "spacing.4"、24px → "spacing.6"。エイリアストークン（"xs"、"sm"、"md"、"lg"、"xl"）も有効です。gap="4" のような数値だけの値は使わないでください。
5. 手動スタイリングよりセマンティックな props を優先する — bg="colour.system.danger.fill" ではなく status="danger" を使います。
6. すべてのフォーム入力に IressField を使う — ラベル、ヒント、バリデーションのレイアウトが提供されます。
7. レスポンシブのパターンに従う — レスポンシブな表示には hideFrom／hideBelow props または useBreakpoint フックを使い、グリッドレイアウトを画面幅に適応させるには IressCol のレスポンシブな span を使います。
8. グリッドレイアウトは常にレスポンシブにする — Figma の複数列レイアウトを実装する際は、レスポンシブな span の値（例：span={{ xs: 12, md: 6 }}）を使い、モバイルでは列が縦に並ぶようにします。
9. コンポーネントのドキュメントを確認する — props とパターンの詳細について、該当するコンポーネントのドキュメントを読んでください（node_modules/@iress-oss/ids-components/.ai/components/）。

よくある間違い

不要なレイアウトラッパー

価値がない場合は IressInline や IressStack を追加しないでください。Figma のオートレイアウトフレームすべてに、それぞれ独自のレイアウトラッパーが必要なわけではありません。まず IDS コンポーネントを確認してください。

// ❌ Unnecessary nesting — IressStack wrapping a single child
<IressStack gap="md">
  <IressInline gap="sm">
    <IressButton mode="primary">Save</IressButton>
    <IressButton mode="secondary">Cancel</IressButton>
  </IressInline>
</IressStack>

// ✅ Single group of buttons only needs IressInline
<IressInline gap="sm">
  <IressButton mode="primary">Save</IressButton>
  <IressButton mode="secondary">Cancel</IressButton>
</IressInline>

判断の目安： Figma にオートレイアウトフレームが表示されている場合は、ラッパーを追加する前に、対応する IDS コンポーネントがそのレイアウトをすでに提供しているか確認してください。IressModal（actions を使用）や IressButtonGroup などのコンポーネントは、内部のレイアウトをすでに処理します。IressCard では、heading と footer の props を使ってコンテンツを構成します。ただし、footer スロットは子要素を自動でレイアウトしないため、ボタンを横並びにする必要がある場合は footer 内で IressInline を使ってください。

その他によくあるアンチパターン

よくあるアンチパターン（無効化されたボタン、冗長な textStyle、レガシーなスロット属性、生の HTML、ハードコードされた値）の全リストについては、node_modules/@iress-oss/ids-components/.ai/guides/foundations-common-mistakes.md にある Common Mistakes ガイドをお読みください（@iress-oss/ids-components のインストールが必要です）。

Figma 固有の補足： Figma に名前付きのコンテンツ領域（「prepend」、「append」、「footer」）が表示されている場合は、slot 属性ではなく、対応する React prop に割り当ててください。Figma でボタンがグレー表示または無効状態になっている場合は、disabled を使わないでください。代替方法についてはガイドを参照してください。