figma-to-spirit

Figma から Spirit コンポーネントへの変換

コンポーネントのドキュメント

詳細な API リファレンス、サンプル、よくある間違いについては、以下を参照してください。

• レイアウトコンポーネント - Flex、Grid、Stack、Box、Section、Container
• タイポグラフィコンポーネント - Heading、Text
• カードコンポーネント - Card、CardLink、CardTitle、CardDescription

基本原則

1. 必ず Spirit Web React コンポーネントを使用する - Spirit コンポーネントが存在する場合は、カスタムコンポーネントを作成したり、生の HTML/CSS を使用したりしないでください
2. インライン CSS は絶対に使用しない - 代わりにコンポーネントの props とスタイリング用の props を使用してください。UNSAFE_style または UNSAFE_className は最後の手段としてのみ使用してください
3. このスキルのドキュメントを主要な参照として使用する:
   • Flex、Grid、Stack、Box、Section、Container については レイアウトコンポーネント を確認してください
   • Heading、Text については タイポグラフィコンポーネント を確認してください
   • これらのドキュメントには API リファレンス、よくある間違い、正しい prop 値が記載されています
4. Figma CodeConnect から props を正確に読み取る:
   • get_code_connect_map を呼び出して、Figma から CodeConnect スニペットを取得します
   • CodeConnect のすべての props を表示どおりに正確に使用してください - 決して上書きしたり変更したりしないでください
   • CodeConnect に Card と表示されている場合は、Card を使用してください（Flex や Box ではありません）
5. アイコン名を絶対に置き換えない:
   • Figma/CodeConnect の iconName 値を正確に使用してください（たとえ "placeholder" であっても）
   • 「意味的に適切な」アイコンを選ばないでください - それはデザイナーの判断であり、あなたの判断ではありません
   • プレースホルダーアイコンは意図的なものです - 最終的なアイコンがまだ決定されていないことを示しています
   • 誤り: iconName="placeholder" を見て "shield-dualtone" や "folder" に変更すること
   • 正しい: 表示どおりに iconName="placeholder" を正確に使用すること
6. スクリーンショットから prop 値を絶対に推測しない - すべての prop 値（背景色、余白、サイズ、テキスト色、配置など）は Figma のレイヤーデータ（get_design_context、CodeConnect、レイヤープロパティ）から取得しなければなりません。スクリーンショットは全体の構造とレイアウトを理解するためにのみ役立ち、特定の prop 値を決定するためのものではありません。Figma のデザインデータが利用できない場合（例: Figma デスクトップアプリが開かれていない場合）、次のことをしなければなりません:
   • Figma データから確認できなかった値をユーザーに伝える
   • 前提を明示的に列挙する（例: 「size="xlarge" で背景色なしと仮定しましたが、Figma のレイヤーデータからは確認できませんでした」）
   • 黙って推測しない - 確認されていないすべての値を指摘しなければなりません
   • よくある落とし穴: Figma キャンバスにはグレーの背景がある（デザインの一部ではない）、スクリーンショットの色は信頼できない、余白やサイズはピクセルから正確に読み取ることができない
7. すべての画像プレースホルダーには https://picsum.photos/ を使用する - 形式: https://picsum.photos/seed/{identifier}/{width}/{height}
8. props をデフォルト値に設定しない - props はコンポーネントのデフォルトと異なる場合にのみ設定してください。省略すべき一般的なデフォルト値:
   • レイアウト: Flex direction="horizontal"、alignmentX="stretch"、alignmentY="stretch"、Grid alignmentX="stretch"、alignmentY="stretch"、Box/Stack elementType="div"、Section hasContainer={true}、Container size="xlarge"
   • タイポグラフィ: Heading size="medium"、emphasis="bold"、Text elementType="p"、size="medium"、emphasis="regular"
   • 例外: Heading の elementType はアクセシビリティのために常に必須です
   • 完全なデフォルト値についてはコンポーネント固有のドキュメントを確認してください
9. Context7 MCP は最後の手段です - このスキルにドキュメント化されていないコンポーネントにのみ使用してください:
   • resolve-library-id を @alma-oss/spirit-design-system で呼び出します
   • query-docs を /alma-oss/spirit-design-system とコンポーネント名で呼び出します
10. 不明な場合は質問する - Spirit コンポーネントで実装する方法がわからないレイアウト、パターン、または問題に遭遇した場合:

• 推測したり即興で対応したりしない - 立ち止まってユーザーにガイダンスを求めてください
• 達成しようとしていることと、不明な点を説明してください
• 使用すべき特定の Spirit コンポーネントやパターンがあるかどうかを尋ねてください
• 進める前にユーザーの返答を待ってください
• これにより、誤った実装を防ぎ、今後のために新しいパターンを学ぶことができます

---

⚠️ 非推奨の props とコンポーネント

実装ではこれらの非推奨機能を絶対に使用しないでください:

非推奨の Props (まだ利用可能ですが、削除される予定です)

• UncontrolledCollapse: hideOnCollapse prop - isDisposable に置き換えられました。常に isDisposable を使用してください。

移行済み (現在のベストプラクティス)

• Flex direction: horizontal/vertical を使用してください (row/column ではありません) - これが現在の標準です。

Figma で非推奨機能に遭遇した場合:

• Figma CodeConnect が非推奨の prop/コンポーネントを表示している場合は、ユーザーに通知し、最新の代替手段を使用してください
• 非推奨機能を黙って使用しないでください
• 必要に応じて、Figma から逸脱する理由を説明するコメントをコードに追加してください
• 非推奨項目を参照している場合は、ユーザーに Figma コンポーネントの更新を提案してください

---

ワークフロー

ステップ 1: Figma の構造を分析する

重要: Figma のレイヤー階層を正確に一致させてください。 各 Figma オートレイアウトレイヤーには、対応する Spirit レイアウトコンポーネントが必要です。

重要: 以下のすべての値は Figma レイヤーデータから抽出する必要があります (get_design_context、CodeConnect、またはレイヤープロパティ経由) - スクリーンショットから推測しないでください。スクリーンショットは全体的な構造を理解するのに役立つだけです。Figma データが利用できない場合は、どの値が仮定であるかをユーザーに通知してください。

Figma から抽出するもの:

• Figma テキストスタイル → Spirit コンポーネント - Heading* テキストスタイル ⇒ Heading コンポーネント; Body* テキストスタイル ⇒ Text コンポーネント。Body スタイル (例: Body/Medium/Semibold) に Heading を絶対に使用しないでください。
• コンテナレイヤー - Figma に 2 つ以上の Container レイヤーがある場合 (例: "Container Medium"、"Container XLarge")、Section の hasContainer={false} を使用し、各レイヤー名から size を取って、その数だけ Container コンポーネントをレンダリングします。レイアウトコンポーネントを参照してください。Section に単一のコンテナがある場合: レイヤーが "Container XLarge" であれば、containerProps を省略します (xlarge がデフォルトです); それ以外の場合は、レイヤー名から containerProps.size を設定します (例: "Container Medium" → containerProps={{ size: "medium" }})。
• コンポーネント名 - Figma に "Card Media NEW"、"Button" などが表示されている場合は、対応する Spirit コンポーネントを使用してください
• props のレイヤー名 - "Section XLarge" → size="xlarge"、"Button Large" → size="large"
• アイコン名 - CodeConnect に表示されているとおりに正確に使用してください (コア原則 #5 を参照)
• スペーシング値 - オートレイアウトプロパティから gap を読み取ります: gap-[var(--global/spacing/space-1400,64px)] → spacing="space-1400"
• カラートークン - レイヤープロパティから正確なトークンを読み取ります: accent-01-subtle、accent-02-subtle など
• すべてのラッパーレイヤー - オートレイアウトを持つ各 Figma レイヤーには、対応する Spirit コンポーネントが必要です
• 配置 - align-items および justify-content プロパティを確認してください
• 幅/高さを埋める - Figma は "fill" 寸法に align-self: stretch を使用します
• 最大幅の制約 - どの特定のレイヤーに max-width があるかを確認し、そのレイヤーにのみ適用してください
• パディング値 - レイヤーの pr、pl、pt、pb、px、py を確認し、Box のパディング props を使用して適用してください
• リンクカラー - themed/link/... トークンを確認してください; これらはクリック可能な要素を示します (Card タイトルには CardLink を使用してください)

レイアウトガイド (グリッド列): Figma のレイアウトガイド (例: "content limited to 7 grid columns") は、Figma API (get_design_context、get_metadata、get_screenshot) を介して公開されません。ユーザーがレイアウトガイドからのグリッド/列の制約に言及した場合は、Spirit の Grid を使用して実装してください (例: 7 列の場合は Grid cols={12} と GridItem columnStart="span 7")。合計列数やガターが不明な場合は、ユーザーに確認するか値を共有するよう依頼してください。

レイヤー構造マッチングの例:

Figma Layers:                          Spirit Components:
├── Section XLarge                     <Section size="xlarge">
│   └── Container XLarge                 (included in Section)
│       └── Content (gap: 32px)          <Flex spacing="space-1000">
│           ├── Heading (max-w: 800px)     <Box UNSAFE_style={{ maxWidth }}>
│           │   ├── Tag                        <Flex spacing="space-700">
│           │   └── Composition                  <Tag />
│           │       ├── Title                    <Flex spacing="space-900">
│           │       ├── Description                <Heading />
│           │       └── ActionGroup                <Text />
│           │                                      <ActionGroup />
│           └── Column (4 items)             </Flex></Box>
│               ├── number                   <Grid cols={4}>
│               ├── number                     <StatCard />
│               ├── number                     ...
│               └── number                   </Grid>

ステップ 2: コンテナタイプを選択する

Figma のパターン	Spirit コンポーネント
「デザインブロック」またはメインページのセクション	Section
コンテンツの幅を制約する必要がある	Section containerProps={{ size: "..." }}
全幅のセクションコンテンツ	Section hasContainer={false}

重要: Section にはデフォルトで Container が含まれています - その中にさらに Container をネストしないでください。

ステップ 3: レイアウトパターンを選択する

Figma のパターン	Spirit コンポーネント	備考
均一で繰り返し可能な項目（カード、統計）	Grid	cols プロップを設定すると、Grid が行の折り返しを処理します
最大幅で中央揃えのコンテンツ	Section containerProps={{ size: "..." }}	Grid ではありません
単一の行または列	Flex	direction="horizontal" または "vertical"
構造が異なる列	複数の Flex 列	水平 Flex が垂直 Flex の子要素をラップします
区切り線付きの垂直リスト	Stack	hasIntermediateDividers を使用します
スタイリングのみ（背景、ボーダー）	Box	レイアウト機能なし
スタイリング + レイアウトの組み合わせ	Box elementType={Flex}	スタイリングとレイアウトを組み合わせます

重要: 実装する前に、API リファレンス、プロップの値、よくある間違いについて レイアウトコンポーネント を確認してください。

ステップ 4: 配置プロップを設定する

配置を設定する前に Figma の子要素に W-Full があるか確認する

Figma を分析する際、子要素に w-full（全幅）または shrink-0 w-full があるか確認してください:

• 子要素に w-full がある場合 → 親は alignmentX="stretch" を使用して、子要素がコンテナの幅を埋めるようにする必要があります
• 子要素に w-full がない場合 → 親は alignmentX="left" を使用して、意図しない幅の拡大を防ぐ必要があります
• 子要素に w-full と max-width の両方がある場合 → 親は alignmentX="stretch" を使用し、子要素はその max-width 制約まで拡張されます

// WRONG - alignmentX="left" prevents children from filling width even when Figma shows w-full
<Flex direction="vertical" spacing="space-1000" alignmentX="left">
  <Box UNSAFE_style={{ maxWidth: "800px" }}>...</Box>  {/* Won't stretch to 800px */}
  <Grid cols={4}>...</Grid>  {/* Won't fill container width */}
</Flex>

// CORRECT - alignmentX="stretch" lets children fill width (respecting their max-width if set)
<Flex direction="vertical" spacing="space-1000" alignmentX="stretch">
  <Box UNSAFE_style={{ maxWidth: "800px" }}>...</Box>  {/* Stretches up to 800px */}
  <Grid cols={4}>...</Grid>  {/* Fills container width */}
</Flex>

値のマッピング（CSS → Spirit）

CSS 値	alignmentX	alignmentY
flex-start	left	top
center	center	center
flex-end	right	bottom
stretch	stretch	stretch

方向に基づくマッピング:

• 垂直 Flex: align-items → alignmentX、justify-content → alignmentY
• 水平 Flex: justify-content → alignmentX、align-items → alignmentY

重要: 垂直 Flex では常に alignmentX を明示的に設定してください。Figma の子要素に w-full がある場合は stretch を選択し、それ以外の場合は left を使用してください。

ステップ 5: タイポグラフィを設定する

Figma テキストスタイル	Spirit コンポーネント	主要なプロップ
見出しスタイル	Heading	elementType（必須）、size、emphasis
本文テキスト	Text	elementType、size、emphasis

アクセシビリティのルール:

• h1-h6 は実際のセマンティックな見出しにのみ使用してください
• 見出しではないスタイル付きテキスト（統計、ラベル）の場合: elementType="div" または "span"
• 見出しの階層を維持してください（h1 → h2 → h3、レベルを飛ばさないでください）
• Flex/Grid/Stack 内で後に兄弟要素があるタイポグラフィ要素には marginBottom="space-0" を追加してください（最後の子要素には必要ありません）

完全なアクセントカラートークン名を使用する

Heading と Text はアクセントカラーを受け付けますが、完全なトークン名を使用する必要があります（短縮形ではありません）。

// WRONG - short form "accent-02" causes TypeScript lint error
<Heading elementType="div" size="xlarge" textColor="accent-02">300K+</Heading>

// CORRECT - use full token name "accent-02-basic"
<Heading elementType="div" size="xlarge" textColor="accent-02-basic" marginBottom="space-0">300K+</Heading>

有効なアクセントトークン: accent-01-basic、accent-01-subtle、accent-02-basic、accent-02-subtle など。

IMPORTANT: 実装する前に、Typography Components で API リファレンス、prop の値、よくある間違いを確認してください。

Step 6: レスポンシブデザイン

Figma でブレークポイントが 1 つだけ提供されている場合:

1. ブレークポイントを特定する - Figma のフレーム幅を確認します（モバイル < 768px、タブレット 768-1024px、デスクトップ > 1024px）
2. 他のブレークポイント用のレスポンシブ prop を追加する:

// Grid: reduce columns on smaller screens
<Grid cols={{ mobile: 1, tablet: 2, desktop: 4 }} />

// Flex: change direction on mobile
<Flex direction={{ mobile: 'vertical', tablet: 'horizontal' }} />

// Spacing: reduce on smaller screens
<Flex spacing={{ mobile: 'space-400', tablet: 'space-800', desktop: 'space-1200' }} />

3. 提供されたブレークポイントではデザインが完全に一致する必要があります

Step 7: デザインのクロスチェック

最終化する前に、Figma データを再取得して検証してください:

1. CodeConnect スニペットがコードと完全に一致する - CodeConnect のすべての prop が含まれている
2. コンポーネント名が一致する - 使用されている Spirit コンポーネントが Figma のコンポーネント名と一致する
3. アイコン名が正確に一致する - CodeConnect が iconName="placeholder" を示している場合、コードは "placeholder" を使用する必要があります（置き換えたアイコンではない）
4. スペーシングの値が一致する - Figma のオートレイアウトプロパティから読み取る
5. カラートークンが一致する - Figma のレイヤープロパティから正確なトークンを使用する
6. レイヤー構造が一致する - すべてのラッパーレイヤーが表現されている
7. 配置が一致する - Figma に一致する明示的な配置 prop を使用する

Step 8: ブラウザでの視覚的比較

実装後、ブラウザを使用して結果を Figma デザインと視覚的に比較します。

ブラウザ自動化ツール（例: ブラウザ MCP サーバー、Playwright、Puppeteer など）にアクセスできる場合は、それらを使用して実行中の開発サーバーを開き、Figma のスクリーンショットと視覚的に比較します。ブラウザツールが利用できない場合は、このステップをスキップしてください。

手順:

1. 開発サーバーが実行中であることを確認する - ターミナルで実行中の開発サーバー（例: yarn dev、npm run dev）を確認します。ローカル URL（通常は http://localhost:3000）をメモします。

2. Figma のスクリーンショットを取得する - Figma ノードに対して get_screenshot を呼び出し、比較用に最新の状態にします。

3. ブラウザでページを開く - ローカル開発サーバーの URL に移動します。ページが読み込まれるのを待ってから、現在のページ状態をキャプチャします（スクリーンショットまたはスナップショット）。

4. 視覚的に比較する - Figma のスクリーンショットとブラウザの出力の両方を確認します。以下をチェックしてください:

   • レイアウト構造 - 全体的な配置は一致していますか？（スペーシング、配置、ネスト）
   • タイポグラフィ - フォントサイズ、ウェイト、色は正しいですか？
   • スペーシング - 要素間の間隔はデザインと一致していますか？
   • コンポーネントのレンダリング - ボタン、タグ、カードなどは正しく表示されていますか？
   • 配置 - コンテンツはデザインと同様に左/中央/右に配置されていますか？
   • 幅の制約 - コンテンツは Figma の max-width 値を尊重していますか？
   • 色 - 背景、テキストの色、ボーダーは一致していますか？

5. 不一致を修正する - 一致しない場合は:

   • 不一致の原因となっている特定のコンポーネントまたは prop を特定します
   • コードを更新して修正します
   • ブラウザでページを再読み込みして再確認します

6. レスポンシブチェック（任意） - Figma デザインが特定のビューポート幅を指定している場合は、比較する前にブラウザのビューポートをその幅に合わせてサイズ変更します。他のブレークポイントについては、レスポンシブな動作が妥当に見えるかを確認します。

重要な注意事項:

• ブラウザでの比較はベストエフォートの視覚的チェックであり、ピクセルパーフェクトな検証ではありません
• 構造的な正確性に焦点を当ててください: レイアウト、スペーシング、配置、色、コンポーネントの使用法
• Figma とブラウザの間の軽微なレンダリングの違いは想定内です（フォントレンダリング、アンチエイリアシングなど）
• ブラウザツールが利用できない場合、または開発サーバーが実行されていない場合は、このステップをスキップし、回答にその旨を記載してください

ステップ 9: リンターのチェック

実装が完了したら、編集したすべてのファイルに対してリンターを実行し、エラーを検出してください。

1. ReadLints を実行する — 実装中に作成または変更したすべてのファイルに対して
2. 新たに発生したリンターエラーを修正する — 自分が導入したもの（TypeScript エラー、不正な prop 値、不足しているインポートなど）
3. 既存のリンターエラーは無視する — 自分の変更によって発生したエラーのみを修正してください
4. よくあるリンターの問題:
   • 不正な prop 値（例: "accent-02-basic" ではなく "accent-02" のような短縮形のアクセントカラー）
   • @alma-oss/spirit-web-react からのインポートの欠落または誤り
   • コンポーネントの props における TypeScript の型の不一致
   • 未使用のインポートや変数

---

クイックリファレンス

スペーストークン

トークンの範囲	典型的な用途
space-100 - space-300	狭い間隔（アイコン、インライン）
space-400 - space-600	小（コンポーネント内）
space-700 - space-900	中（コンポーネント間）
space-1000 - space-1200	大（セクションのパディング）
space-1300 - space-1600	特大（ページセクション）

カラートークンの例

種類	例
背景	primary、secondary、tertiary、accent-01-subtle、accent-02-subtle、neutral-subtle
テキスト	primary、secondary、tertiary、inverted、disabled、accent-01-basic、accent-02-basic
ボーダー	basic、focus、アクセントカラー

注: アクセントカラーには常に完全なトークン名を使用してください（accent-02 ではなく accent-02-basic）。詳しくはタイポグラフィコンポーネントを参照してください。

リンクテキストスタイル

Figma では、リンクは名前の link を含むテキストスタイル（例: Body/Medium/Link Regular、Body/Small/Link Regular）を適用することで作成されます。そのようなスタイルが適用された通常の段落は、Figma におけるリンクの正しい表現です — これは間違いではありません。

link テキストスタイルを使用しているテキストノードに遭遇した場合は、DS の Link コンポーネントとして実装してください:

<Link href="...">Show more</Link>

手動で下線スタイルを適用した <p> や <span> として実装しないでください。

リンクのカラートークン（カードの検出に重要）

Figma がテキスト上にこれらのカラートークンを表示している場合、その要素はリンクであるべきことを示しています:

Figma トークン	意味
themed/link/primary/state-default	プライマリリンク色 - カードタイトルには CardLink を使用
themed/link/primary/state-hover	リンクのホバー状態 - CardLink が自動的に処理
themed/link/secondary/...	セカンダリリンク - CardLink または Link コンポーネントを使用

CardTitle にリンクのカラートークンがある場合は、textColor 付きの Heading ではなく、CardTitle 内で CardLink を使用してください。

完全なドキュメントについてはカードコンポーネントを参照してください。

---

実装チェックリスト

コードを確定する前に:

Figma データ抽出:

• [ ] CodeConnect スニペットを提供されたとおりに使用した
• [ ] コンポーネント名を検証した (Figma → Spirit マッピング)
• [ ] アイコン名を表示されたとおりに正確に使用した (iconName="placeholder" の場合は "placeholder" を使用すること - 絶対に置き換えないこと)
• [ ] レイヤー名を確認し、size/color/variant プロパティを把握した
• [ ] スペーシング値は Figma のオートレイアウトプロパティから読み取った
• [ ] カラートークンは Figma のレイヤープロパティから正確に読み取った
• [ ] 非推奨のプロパティを使用していない (確認: hideOnCollapse、row/column direction の値)
• [ ] 非推奨のコンポーネントを使用していない (確認: hideOnCollapse、row/column direction の値)

レイアウト:

• [ ] Figma の Container レイヤー: Container レイヤーが 2 つ以上ある場合 ⇒ Section に hasContainer={false} を指定し、レイヤー名から size を取得した同数の Container コンポーネントを配置する (例: "Container Medium" → size="medium")。
• [ ] レイアウトコンポーネントに明示的な alignment プロパティを指定した
• [ ] Vertical Flex に alignmentX を明示的に設定した
• [ ] Grid に alignmentX と alignmentY の両方を設定した
• [ ] Figma の「fill」幅には親の alignmentX="stretch" を使用した
• [ ] すべての Figma ラッパーレイヤーをコードに反映した (階層を一致させる)
• [ ] 均一なアイテムには Grid、異なる構造には Flex columns を使用した
• [ ] max-width 制約は最も内側の該当ラッパーにのみ適用した

タイポグラフィ:

• [ ] Figma のテキストスタイルを尊重した: Heading* スタイル ⇒ Heading コンポーネント、Body* スタイル ⇒ Text コンポーネント (Body/Medium/Semibold などに Heading を決して使用しない)
• [ ] Heading の elementType を適切に設定した (見出しには h1-h6、スタイル付きテキストには div/span)
• [ ] Heading の階層を維持した (レベルを飛ばさない)
• [ ] 後続の兄弟要素があるタイポグラフィに marginBottom="space-0" を追加した (最後の子要素には不要)
• [ ] アクセントテキストの色には完全なトークン名を使用した (accent-02 ではなく accent-02-basic)

スタイリング:

• [ ] インライン CSS を使用していない (UNSAFE_style を最後の手段として使用する場合を除く)
• [ ] UNSAFE_style maxWidth は制約されたコンテンツを含む最も内側のラッパーにのみ指定した
• [ ] スタイリングとレイアウトの両方が必要な場合は Box + Flex パターンを使用した
• [ ] すべてのプロパティ値を Figma のレイヤーデータから確認した (スクリーンショットから推測しないこと)
• [ ] Figma データが利用できなかった場合、前提をリストアップしてユーザーに報告した
• [ ] Box の色/ボーダーが Figma と正確に一致している
• [ ] パディング値 (pr、pl、pt、pb、px、py) を Figma から Box プロパティまたは Flex elementType={Box} を使用して適用した
• [ ] デフォルトのプロパティ値を省略した (direction="horizontal"、alignmentX="stretch"、size="medium"、elementType="div" など)

カード & リンク:

• [ ] link テキストスタイルを持つテキストノード (例: Body/Medium/Link Regular) を DS の Link コンポーネントとして実装した
• [ ] themed/link/... カラートークンを持つ CardTitle には CardLink を使用した (textColor 付きの Heading ではなく)
• [ ] クリック可能なカードでは CardTitle 内に CardLink を使用した
• [ ] 適切な場合に CardTitle に isHeading を設定した
• [ ] CardArtwork 内に IconBox を持つ Horizontal Card では、垂直方向の中央揃えに Flex ラッパーを使用した (Card Components を参照)

レスポンシブ:

• [ ] 他のブレークポイント用のレスポンシブプロパティを追加した
• [ ] 指定されたブレークポイントでデザインが正確に一致している

画像:

• [ ] プレースホルダーは picsum.photos 形式を使用した

視覚的比較:

• [ ] ブラウザで実装を開いた (ブラウザツールが利用可能な場合)
• [ ] ブラウザのレンダリングを Figma のスクリーンショットと比較した
• [ ] 見つかった視覚的な差異を修正した

リンター:

• [ ] 作成/変更したすべてのファイルでリンターを実行した
• [ ] 実装によって新たに発生したリンターエラーを修正した
• [ ] Spirit コンポーネントのプロパティに TypeScript エラーがない

不確実な点:

• [ ] 実装方法が不明なレイアウト/パターンについてユーザーにガイダンスを求めた (推測しないこと!)

---

よくある間違い

1. アイコン名の置き換え

重要: アイコン名を独自の判断で置き換えないでください。

// WRONG - Developer substituted "semantically appropriate" icons
<Icon name="shield-dualtone" />  // Was "placeholder" in Figma
<Icon name="folder" />           // Was "placeholder" in Figma
<Icon name="reload" />           // Was "placeholder" in Figma

// CORRECT - Use EXACTLY what Figma/CodeConnect specifies
<Icon name="placeholder" />      // Matches Figma exactly
<Icon name="placeholder" />      // Matches Figma exactly
<Icon name="placeholder" />      // Matches Figma exactly

なぜこれが誤りなのか:

• プレースホルダーのアイコンは、デザイナーがまだアイコンの選択を確定していないことを示しています
• アイコンの選択はデザイン上の判断であり、開発者の判断ではありません
• あなたが「意味的に適切」と考える選択は、デザインシステムのアイコン使用パターンと衝突する可能性があります
• これは核心的な原則「CodeConnect のすべての props を表示どおりに正確に使用する」に違反します

ルール: CodeConnect が iconName="placeholder" を表示している場合、あなたのコードは必ず iconName="placeholder" を使用しなければなりません。それで確定です。

2. 非推奨の Props またはコンポーネントの使用

重要: 古い Figma ファイルに含まれていても、非推奨の機能は決して使用しないでください。

// WRONG - using deprecated hideOnCollapse prop
<UncontrolledCollapse id="collapse-1" hideOnCollapse>
  Content
</UncontrolledCollapse>

// CORRECT - use isDisposable instead
<UncontrolledCollapse id="collapse-1" isDisposable>
  Content
</UncontrolledCollapse>

// WRONG - using deprecated Flex direction values
<Flex direction="row" />
<Flex direction="column" />

// CORRECT - use current direction values
<Flex direction="horizontal" />
<Flex direction="vertical" />

// CORRECT - handle full-width buttons via layout
<Flex alignmentX="stretch">
  <Button>Button</Button>
</Flex>

なぜこれが誤りなのか:

• 非推奨の props/コンポーネントは、将来の Spirit バージョンで削除されます
• これらを使用すると、技術的負債とメンテナンスの負担が生じます
• 最新の代替手段は、より優れた機能を提供します
• Figma ファイルには古いコンポーネントバージョンが含まれている可能性があります

ルール: Figma が古いパターンを示していても、常に最新の非推奨でない API を使用してください。必要に応じて、その逸脱を説明するコメントを追加してください。

3. Figma のスクリーンショットからの Prop 値の推測

Figma のスクリーンショットの見た目から prop 値を導き出さないでください。スクリーンショットは構造を理解するためのものです。

すべての prop 値は、Figma のレイヤーデータ (get_design_context、CodeConnect、レイヤープロパティ) から取得しなければなりません。そのデータが利用できない場合は、黙って推測するのではなく、あなたの仮定についてユーザーに伝えてください。

よくある落とし穴:

• 背景色: Figma のキャンバスはグレーです。背景のないセクションはスクリーンショットではグレーに見えます。これはそのセクションに backgroundColor="secondary" が設定されていることを意味するものではありません。
• スペーシング値: スクリーンショット内のピクセル距離からスペーシングトークンを正確に判断することはできません。
• テキスト色: スクリーンショットのレンダリングは、カラートークンを正確に表現していない可能性があります。
• サイズ: コンポーネントのサイズ (たとえば Section の size、Tag の size) は、スクリーンショットから信頼性をもって読み取ることはできません。

// WRONG - Guessed backgroundColor from screenshot appearance
<Section backgroundColor="secondary" size="xlarge">
  <Heading elementType="h1">Title</Heading>
</Section>

// CORRECT - Only set props confirmed from Figma layer data
<Section size="xlarge">
  <Heading elementType="h1">Title</Heading>
</Section>

Figma データが利用できない場合は、ユーザーに伝えてください:

「Figma のレイヤーデータを取得できませんでした (Figma デスクトップアプリが開かれていない可能性があります)。以下の値は、スクリーンショットから私が立てた仮定であり、誤っている可能性があります:

• Section の size="xlarge" (正確なパディングを検証できませんでした)
• backgroundColor が設定されていない (スクリーンショットの背景はキャンバスであり、デザインではない可能性があります)
• Tag の size="small" (見た目のサイズから推測)

これらを Figma ファイルと照合して確認してください。」

ルール: すべての prop 値は Figma データから確認しなければなりません。確認できない場合は、仮定であることをユーザーに明示してください。