design-engineer-mindset

デザインエンジニアの考え方

デザインされたものと実際にリリースされるものの差を埋めます。実際の値、実際のタイミング、実際の物理特性を使って、デザインを正確に実装し、ブラウザーのレンダリングパイプラインもデザイン素材の一部として扱います。最優先の原則：忠実さは妥協できず、測定可能でなければなりません。「モックアップにだいたい近い」は不具合です。逸脱はすべて、理由を文書化するか、修正してください。 実装と忠実度レポートを提出し、目視だけで確認してリリースすることは避けてください。

使用する場合／使用しない場合

次の用途で使用します：デザインからコードへの実装、デザインと実装の乖離の解消、デザイントークンのコード化、レンダリングレベルでのカクつくアニメーションの修正（レイアウトスラッシング、コンポジター非対応プロパティ）、フレーム予算への対応。

本当に必要なのが次の場合は、代わりに引き継ぎます：

• 継続時間／イージングやモーションの語彙を決める → skills/frontend-design/interaction-physics（このスキルが仕様を決め、こちらは忠実に実装し、60fpsを維持します）
• ネットワーク／体感レイテンシ、Core Web Vitals → skills/frontend-design/performance-optimization
• これから作るコンポーネントの構成 → skills/frontend-design/component-architecture
• デザインそのものを考案する（モックアップがない） → skills/frontend-design/design-foundation とビジュアルレイヤーのスキル

ステップ 0 — デザインとコードベースを調べ、残った点だけを尋ねる

1. デザインのソースから正確な値を抽出します：間隔、サイズ、角丸、色、シャドウ、タイポグラフィスタイル、アニメーションの継続時間／イージング。Figma のリンクがあり、Figma ツールを利用できる場合は、実際の値を取得します。スクリーンショットから測定する場合は、測定値を忠実度レポートで近似値として明記します。
2. コード側を調べます：既存のトークンシステム（CSS 変数、Tailwind テーマ、styled-system など）はありますか？各デザイン値をまず既存のトークンに対応付けます。トークンがない値は、新しいトークンとして追加するか、仕様からの逸脱として指摘する値として一覧にします。
3. デザインの基盤となるシステムを見極めます：間隔は 8（または 4）の倍数ですか？一貫したエレベーションスケールはありますか？継続時間のパターンはありますか？ピクセル値を書き写すより、システムを実装するほうが優れています。
4. 変更するコードのレンダリング上の健全性を確認します：width/height/top/left/margin をアニメーションさせている箇所、ハンドラー内で DOM の読み取りと書き込みが交互に発生する箇所、レイアウト読み取りを行うスクロールハンドラーを検索します。

デザインのソースだけでは答えがわからない場合に限り、ユーザーには一度にまとめて尋ねます。モックアップが 1 つの幅しか示していない場合は対象のブレークポイント／レスポンシブ動作、静的なモックアップでは確認できないインタラクションの動作（ホバー／押下／読み込み状態）を尋ねます。答えがわからない場合は、デザインシステムに沿った妥当な既定値を実装し、前提として記録します。作業を止めないでください。

ワークフロー

1. 値を書き写す前に意図を把握する

特筆すべき値ごとに、その理由（タッチターゲット、グリッド単位、エレベーションレベル、タイミング分類）を明らかにします。ルール：値がデザイン独自のシステムに反する場合（8 ポイントのレイアウトに紛れ込んだ 13px など）は、黙ってコピーしたり修正したりせず、仕様上の誤りと思われる点としてユーザーに伝えます。意図の表の例：references/rendering.md。

2. 直値ではなくトークンを使って実装する

• コード内の色／間隔／サイズ／シャドウ／継続時間はすべてトークンを参照します。生の値はトークンを定義するときだけ使用します。
• トークンレイヤーがなく、同じ値が何度も登場する場合は、新たに作成します（CSS 変数を使うか、そのスタックに Tailwind が含まれている場合は Tailwind テーマを拡張します）。ただし、最小限にとどめ、推測でシステムを作るのではなく、実際のデザインから導き出します。
• 正確さのルール：44px は 44px、300ms は 300ms、イージングカーブは指定された cubic-bezier です。「だいたい近い」値にはしません。

3. パイプラインの物理特性に沿ってアニメーションする

• プロパティのルール： アニメーションさせるのは transform と opacity のみです（コンポジットのみ）。レイアウトプロパティ（width/height/top/left）はレイアウト＋ペイント＋コンポジットを発生させるため、アニメーションさせないでください。疑似要素の opacity クロスフェードで影を再現し、サイズの強調には scale() を使います。
• スラッシングのルール： DOM の読み取りをまとめてから書き込みます。ハンドラーでは、まずジオメトリを読み取り、書き込みは requestAnimationFrame 内でスケジュールします。ループ内で読み取りと書き込みを交互に行っている場合は、必ず修正してください。
• フレーム予算： 60fps は 1 フレームあたり 16.7ms です。JS の予算は約 10ms にしてください。アニメーションがカクつく場合は、コードを変更する前にプロファイル（DevTools Performance）を取得し、原因となるフェーズ（長時間の JS タスク、強制リフロー、またはペイントの多発）を特定します。
• メモ化（React.memo、useMemo、useCallback）は、プロファイルで再レンダーのコストが確認された箇所に適用し、デフォルトですべてに使わないでください。

標準パターン（パイプラインの表、スラッシングの修正、GPU キーフレーム、FPS メーター、トークンブロック）：references/rendering.md を参照してください。実装時に確認してください。

4. 再現性とパフォーマンスを検証する

• 再現性レポートを作成します。デザイン上の値と実装値を並べて記載し、不一致にはすべて理由を添えた差異の列を設けます。環境でレンダリングできる場合は、スクリーンショットを比較します。
• 指定された状態（ホバー、押下、フォーカス、読み込み中、エラー、空）をすべて確認します。モックアップに示されているのは通常そのうちの1つですが、実装ではすべての状態をカバーする必要があります。また、独自に追加した状態は仮定として明記します。
• プロジェクトにビジュアルリグレッションツール（Percy/Chromatic/Storybook）がある場合は、新しい状態のスナップショットを追加します。ない場合は、レポートで一度だけ導入を推奨し、依頼なしにインストールしないでください。
• アニメーションを実装した場合は、レイアウトプロパティのアニメーションが残っていないことを確認し、最も負荷の高いインタラクションのフレームコストをプロファイルするか、理論的に見積もります。

必須の出力形式

次の成果物を両方提出してください。

1. コード — プロジェクト既存のスタックと規約を使用した、トークンベースの忠実な実装。

2. 再現性レポート（Markdown）：

## Implementation summary
What was implemented, from which design source, into which files.

## Fidelity table
| Property | Design | Implemented | Token | Deviation & why |
| Button height | 44px | 44px | --size-control-lg | — |
| Card shadow | y4 b6 10% | same | --shadow-md | — |
| Modal duration | 300ms ease-out | 300ms cubic-bezier(0.16,1,0.3,1) | --duration-base | curve per motion spec, approved values |
| Sidebar gap | 13px (off-grid) | 12px | --spacing-sm+xs | flagged: mockup off its own 4pt grid — confirm |

## States implemented
| State | Source | Notes |
| hover/press/focus | inferred (not in mockup) | assumption — matches system patterns |
| loading | mockup frame 3 | — |

## Performance notes
- All animations on transform/opacity ✓
- [Any profiling done, frame costs, thrash fixes applied]

## Assumptions & open questions
[Responsive behavior chosen, off-grid values flagged, unverifiable measurements from screenshots]

品質基準（提出前に確認）

• すべてのデザイン値が完全に一致しているか、差異の理由が記載されていること — 理由のない近似はゼロ
• コンポーネントコードに生のマジックナンバーがなく、すべての値がトークンを経由していること
• アニメーションがレイアウトプロパティに触れておらず、変更箇所のコードに読み取りと書き込みが交互に行われるループがないこと
• すべてのインタラクティブ状態が実装され、独自に追加した状態には仮定として明記されていること
• モックアップ内のシステム外の値が明示され、黙ってそのまま採用または修正されていないこと
• スクリーンショットから測定した値には近似値と明記され、誤った精度を示していないこと
• 再現性のためにアクセシビリティが犠牲になっていないこと：フォーカスの可視性、コントラスト、タッチターゲットの最小サイズ（WCAG 2.2 AA では 24×24 CSS px、タッチ操作では 44×44 を推奨）が維持されていること
• パフォーマンスに関する主張（fps、レンダーコスト）は、実際に測定した場合にのみ記載されていること

絶対に避けること：実装中にデザインを「改善」しないでください。変更案は別途提案してください。依頼なしにビジュアルリグレッションツールやアニメーションツールをインストールしないでください。プロファイリングなしに 60fps と主張しないでください。デザインが実際に使用している範囲を超えて、推測でトークンアーキテクチャを構築しないでください。

統合

• skills/frontend-design/interaction-physics → このスキルが忠実かつフレームレートを維持して実装するモーション仕様（期間／イージング）を提供します。
• skills/frontend-design/component-architecture → 構築するものの構造を定めます。そのコンポーネントの境界と props の規約の中で、再現性を実装してください。
• skills/frontend-design/design-foundation → トークンシステムのデザインを担います。このスキルでは、それをコード化して利用します。
• skills/frontend-design/performance-optimization → 遅さの原因がレンダリングではなくネットワークやデータにある場合に引き継ぎます。気づいたフェッチのウォーターフォールに関する調査結果を共有してください。

参考資料

• references/rendering.md — レンダリングパイプラインのコストモデル、レイアウトスラッシングの修正、GPU セーフなアニメーションパターン、フレーム予算の測定コード、デザイントークンの CSS ブロック、React のメモ化パターン、ビジュアルリグレッションおよびパフォーマンステストの例、デザイン意図の表。実装時、または動作がカクつくインタラクションをデバッグする際に参照してください。