design-to-react-algorithms

dot-skills デザインから React への変換に関するベストプラクティス

Sketch ファイルをピクセル単位で忠実な React + CSS に変換するリバースエンジニアリングのパイプラインです。回帰を安全に防ぎながら反復できることを、最も重要な制約としています。このスキルは、デザインからコードへの変換におけるカスケード効果を軸に構成されています。つまり、ステージ N での誤った判断は、ステージ N+1 以降のすべての出力を損なうため、各カテゴリは下流に及ぼす影響の大きさに応じて並べられています。

ユーザーの主な要件である 「改善のたびにリグレッションが起きないこと」 を確実にするには、スタイルの仕上げに着手する前に、反復ループ、レイヤーツリー、レイアウトソルバーが正しく機能している必要があります。優先順位の高い順にルールを確認してください。

適用する場面

• .sketch ファイル（または同等のデザインソース）を読み込み、React + CSS を出力するコンバーターを構築するとき
• 改善のたびに他のコンポーネントが壊れるリスクがある既存のコンバーターを反復改善するとき
• 変換後のコンポーネントがデザインに「ほぼ一致」しているのに、ビジュアルリグレッションテストに失敗する理由を診断するとき
• デザインからコードへのパイプラインで、スナップショットゲートやベースラインの戦略を設計するとき
• 元データが自由形式のジオメトリである場合に、フレックスボックス、グリッド、絶対配置のいずれを選ぶか判断するとき
• Sketch 固有のプリミティブ（MSImmutableFlexGroupLayout、attributedString、curvePoint、MSImmutableStyleCorners）を慣用的な CSS に変換するとき

優先度別のルールカテゴリ

この順序はカスケードを表しています。まず前段のステージを修正してください。上流のツリーが間違っていれば、後段の修正は無駄になります。

優先度	カテゴリ	影響度	プレフィックス
1	リバースエンジニアリングの反復戦略	CRITICAL	iter-
2	ツリーの再構築とシンボルの解決	CRITICAL	tree-
3	レイアウトアルゴリズム（フレックス／自由形式の推定）	CRITICAL	layout-
4	座標とジオメトリの計算	HIGH	geom-
5	ビジュアルリグレッションと差分アルゴリズム	HIGH	diff-
6	スタイルの変換（色、グラデーション、シャドウ、ボーダー）	MEDIUM-HIGH	style-
7	タイポグラフィの計算	MEDIUM	type-
8	パスとシェイプの描画	MEDIUM	path-

クイックリファレンス

1. リバースエンジニアリングの反復戦略（CRITICAL）

• iter-bisect-from-root — 上から下へ変換し、下から上へ二分探索して O(log n) でリグレッションの発生箇所を特定します
• iter-baseline-snapshot-gate — すべての変更は、マージ前にコミット済みのベースラインに合格する必要があります
• iter-convert-symbols-before-instances — シンボル → インスタンスの順にトポロジカルソートし、重複をインライン化しないでください
• iter-freeze-design-tokens-first — コンポーネントに着手する前に、sharedSwatches/layerStyles を CSS 変数に抽出します
• iter-one-family-per-pr — 1 回の反復につき、変換対象を 1 つのコンポーネントファミリーに限定します
• iter-keep-known-good-branch — 3 方向のリグレッション切り分けの基準点として、ベースラインブランチを維持します

2. ツリーの再構築とシンボルの解決（CRITICAL）

• tree-resolve-overrides-before-emit — overrideValues をマスターに適用し、名前付きプロパティに変換します
• tree-hash-subtrees-for-componentization — 構造ハッシュにより、デザイナーが見落とした反復を検出します
• tree-collapse-passthrough-groups — スタイルのない単一子グループを削除し、ワールド座標を保持します
• tree-hoist-shared-style-via-subtree-equivalence — プロパティごとの重複排除ではなく、サブツリーの等価性と修飾クラスを使用します
• tree-clipping-mask-is-stacking-context — hasClippingMask には isolation: isolate と clip-path が必要です
• tree-foreign-symbols-become-library-imports — 外部シンボルは重複ではなく、パッケージのインポートになります

3. レイアウトアルゴリズム（CRITICAL）

• layout-flex-group-enum-mapping — MSImmutableFlexGroupLayout の列挙値を CSS のフレックスプロパティに 1 対 1 で対応付けます
• layout-infer-flex-from-axis-projection-overlap — 1D 分離軸テストにより、自由形式からフレックスの行／列を推定します
• layout-detect-grid-via-2d-coordinate-clustering — エッジ座標を ε でクラスタリングし、CSS Grid を検出します
• layout-promote-freeform-when-equal-gaps — 許容誤差内で間隔が等しい場合は、display: flex; gap: Npx を適用します
• layout-reverse-engineer-padding-not-margin — インセットを親のパディングにし、子要素の座標を再設定します
• layout-preserve-wrapping-enabled — レスポンシブ対応の意図を示すソース側の方法は wrappingEnabled だけです
• layout-ignore-layout-is-absolute-escape — flexItem.ignoreLayout: true の場合、position: relative の親要素内で position: absolute を指定します

4. 座標とジオメトリの計算（HIGH）

• geom-compose-parent-transforms-before-emit — 2D アフィン行列を合成し、生の x/y を連結しないでください
• geom-round-only-at-leaves — 浮動小数点値を保持し、CSS の境界で一度だけ丸めます
• geom-rotation-is-css-transform — フレームは回転していない AABB とし、transform: rotate() を出力します
• geom-shape-group-bounds-via-union — 境界は子要素の軸平行な和集合とし、原点を基準に座標を再設定します
• geom-clipping-bounds-intersect-not-union — 入れ子のクリップは交差させ、和集合にしたり置き換えたりしないでください

5. ビジュアルリグレッションと差分アルゴリズム（高）

• diff-use-ssim-for-aa-content — アンチエイリアス処理されたコンテンツには SSIM を使用します。生のピクセル差分では、テストを再実行するたびに誤検知が発生します
• diff-region-budgeted-tolerances — 領域ごとの SSIM 下限値（テキスト 0.99、グラデーション 0.95、画像 1.0）
• diff-antialias-aware-pixelmatch-threshold — アイコンの不具合検出には Pixelmatch の includeAA: false を使用します
• diff-perceptual-hash-for-wrong-component-detection — ハミング距離の区分に応じて、トリアージを自動で振り分けます
• diff-subtree-bisection-to-localize-regression — 二分探索中にサブツリーを無効化し、問題のノードを特定します
• diff-baseline-per-component-not-per-page — Storybook でストーリーごとのスナップショットを作成します。範囲は影響範囲に合わせます

6. スタイルの変換（中〜高）

• style-srgb-float-to-hex-via-gamma-correct-path — Sketch の sRGB 浮動小数点値はすでにガンマエンコードされています。直接変換のみを行います
• style-preserve-display-p3 — colorSpace: 1 → color(display-p3 …) を出力し、sRGB にフォールバックします
• style-gradient-angle-via-atan2 — atan2(dx, -dy) で Sketch のベクトルを CSS のグラデーション角度に変換します
• style-stack-multi-shadow-in-paint-order — 影の配列を逆順にします。Sketch は後ろから先に描画し、CSS は先頭から描画します
• style-reconcile-border-position — ボーダー位置 0/1/2 を、フレームの拡張または外側用の outline に変換します
• style-per-corner-radii-shorthand — 各コーナーの角丸を時計回りの TL TR BR BL に対応させます（Sketch の行順ではありません）

7. タイポグラフィの計算（中）

• type-split-attributed-string-runs-only-when-differ — 隣接する同一属性のランを結合します。単一ランの場合は内側の span は不要です
• type-pt-lineheight-to-unitless — lineHeight / fontSize を、フォントサイズに合わせて拡大縮小する CSS の単位なしの値に変換します
• type-kerning-pt-to-em-letter-spacing — kerning / fontSize を em 相対の letter-spacing に変換します
• type-build-font-fallback-ladder — Sketch のフォントファミリーを Web のフォントスタックに変換します。SF Pro には -apple-system, BlinkMacSystemFont, … が必要です
• type-paragraph-spacing-between-not-after — :last-child を使った margin-bottom ではなく、親要素に gap を使用します

8. パスとシェイプの描画（中）

• path-curve-point-to-svg-cubic-bezier — curveFrom／curveTo から、M とセグメントごとの C を生成します
• path-rectangle-with-fixed-radius-is-css — 軸に沿った角丸長方形を早い段階で検出し、<svg> ではなく <div> を出力します
• path-apple-smooth-corners-via-superellipse — Apple の滑らかな角は円弧ではなく、超楕円（n≈5）です
• path-flatten-boolean-ops-at-parse-time — Node の paper.js で和集合／減算を解決し、単一のフラットなパスを出力します
• path-honor-winding-rule — windingRule の 0/1 を SVG の fill-rule の nonzero／evenodd に対応させます。デフォルトに頼らず明示します

使い方

1. references/_sections.md を読みます。カテゴリの定義とカスケードの根拠が記載されています。
2. イテレーション戦略（iter-*）から始めます。回帰ゲートがなければ、ほかのルールはすべて単なるテクニックにすぎません。
3. 次にツリー（tree-*）とレイアウト（layout-*）に進みます。これらは構造を支える重要な判断です。
4. 続いてジオメトリ（geom-*）と差分（diff-*）に進みます。これらは精度と検証のレイヤーです。
5. スタイル、型、パスは仕上げのレイヤーです。忠実度は高いものの、影響は主に局所的です。

新しいコンバーターを作成する場合は、優先順位に従ってルールを適用してください。既存のコンバーターの場合は、発生している回帰をどの段階が受け持つのかを特定します（[[diff-subtree-bisection-to-localize-regression]] と [[diff-perceptual-hash-for-wrong-component-detection]] を使って切り分けます）。その段階を受け持つ最も上位の段階で修正してください。

リファレンスファイル

ファイル	説明
references/_sections.md	カテゴリの定義、影響度、カスケードの根拠
assets/templates/_template.md	このスキルに新しいルールを追加するためのテンプレート
metadata.json	バージョン、分野、リファレンス
AGENTS.md	自動生成される目次（scripts/build-agents-md.js で再生成）