design-it

design-it

概要

固定的ハウススタイルで、自己完結型の HTML ファイル 1 つとして技術設計書を生成します。これにより、新しい要件が追加されるたびに、見た目がまったく同じページになります。デザインを毎回その場で考えるのではなく、固定の <style> ブロックと固定のセクション構成を使います。あなたの役割は、その構成に内容を埋めることであり、再デザインすることではありません。

基本原則： template.html をそのままコピーし、内容だけを置き換えます。<style> ブロックはバイト単位で変更しないでください。デザインシステムに手を加えないことが、一貫性につながります。

使用する場面

• ユーザーが新しい要件／仕様／機能を提示し、設計書を求めている場合。
• .md の技術仕様書を共有可能な HTML 形式に変換する場合。
• 「同じ html を生成して／このテンプレートを使って／設計書を作成して」といった依頼の場合。

使用しない場面： 使い捨ての簡単なメモ、ユーザーが Markdown のままにしておきたい正式な成果物、スライド資料。

ワークフロー

1. テンプレートをコピーします。 このスキルのディレクトリにある template.html を使います。<head>／<style> を手作業で作らず、全体をそのままコピーしてください。
2. まず実際の内容を集めます。 セクションのタイトル、フィールド名、SQL、file:line のコード位置、protoIds はすべて、実際の要件ドキュメントとコードベースを参照してください。コードを読み、識別子を捏造しないでください。事実が不明な場合は、推測せずに <span class="pill todo">要確認</span> と記載してください。
3. 構成に内容を埋めます。 機能に合わせて <section> を改名／並べ替えます。セクションの種類は維持してください：認識済みの結論 → ビジネスルール → アーキテクチャ図 → シーケンス → データモデル → コントラクト → チェックリスト → 冪等性と縮退動作 → テストケース → コード索引 → 変更履歴。該当しないものは削除し、機能固有のセクションは同じスタイルで追加してください。
4. 目次とセクションの整合性を保ちます。 すべての <a href="#x"> に対応する <section id="x"> が必要で、その逆も同様です。これは最もよく起こる不具合です。最後に必ず確認してください（クイックリファレンスを参照）。
5. 保存します。 docs/<要件名>.html として保存します。依頼がない限り、コミットしないでください。

ハウススタイルのルール（必須）

要素	ルール
<style> ブロック	そのままコピーします。スタイルを変更しないでください。色は :root の CSS 変数のみを使います。
コード／SQL／YAML	必ずテンプレートの <pre style="background:#f8fafc;..."> を使います。<pre> 内では <→&lt;、>→&gt;、&→&amp; のようにエスケープします。 < をエスケープしないと、内容が気付かないうちに欠落します。
コールアウトボックス	.note（オレンジ、注意／間違いやすい点）、.tip（青、前向きな補足）、.warn（赤、リスク）。意味に合った色を使います。
図	<figure> 内にインライン <svg> を手書きします。テキストには .svg-t／.svg-s／.svg-title を使い、ノードの塗りつぶしには .legend と一致する :root の変数（var(--new-bg) など）を使います。
導入文	各セクションの冒頭に、そのセクションで何に答えるのかを示す <p class="lead"> を 1 つ置きます。
ピル	ステータスタグには .pill.new/.old/.infra/.mq/.prod/.tech/.done/.todo を使います。既存のクラスを再利用し、新しいクラスを作らないでください。
テーブル	通常の <table> を使います。ゼブラストライプとヘッダーの背景色は CSS が適用します。
言語	<html lang="zh"> とし、本文はドキュメントの言語（通常は中国語）で記述します。

よくある間違い

• CSS を再デザインする。 出力を同一にすることが目的です。色、余白、フォントを「改善」しないでください。<style> は変更せずにコピーします。
• <pre> 内の山括弧をエスケープしない。 List<String> は壊れたタグとして表示されます。List<String> のようにエスケープしてください。
• リンク切れの目次。 TOC 項目なしでセクションを追加したり、id を変更して href を更新し忘れたりしないでください。必ず照合してください。
• コード位置を捏造する。 file:line、テーブル名、protoIds はリポジトリから確認してください。不明な場合は、もっともらしい値を推測せず「要確認」ピルを付けます。
• 提案書にする。 説得力のある提案ではなく、決定事項を確定した設計書（内容と方法）にしてください。

クイックリファレンス — 最終セルフチェック

f="docs/<需求名>.html"
# TOC hrefs vs section ids must match exactly (no output = perfect):
diff <(grep -oE 'href="#[a-z0-9-]+"' "$f" | sed 's/.*#//;s/"//' | sort -u) \
     <(grep -oE '<section id="[a-z0-9-]+"' "$f" | sed 's/.*"//' | sort -u)
# open in browser to eyeball diagrams + code blocks render cleanly