コードからのUI仕様
ビデオは製品のインターフェースを録画ではなくHTMLとCSSで再構築するため、インターフェースの品質は仕様の正確さに依存します。近似は見過ごされません。このスキルが生まれた制作現場では、レビュアーが手描きのアイコンとロゴを初回レビューで却下し、サイズと名前が間違った手作りバッジに激怒しました。修正はコードを読むことで行われましたが、コードには目視では見えない落とし穴が潜んでいました。ルートフォントサイズはアプリケーションシェルによって実行時に設定され(スタイルシートで宣言された10pxではなく14px)、いくつかのCSS変数は本番環境に存在せずフォールバック値が適用され、あるコンポーネントは2ヶ月前のコミットでアクセントバーを失い、2つの「ダイアログ」はライブラリのダイアログではなくカスタムポップアップでした。
そのため、仕様のすべての値はリテラルかつ出典付きであり、出典を明記できない値はフラグが立てられ、決して推測されません。
入力
videos/<video>/SOURCES.md(source-reconから):各画面、そのルート、コンポーネント、状態。存在しない場合は、最初にsource-reconを実行してください。sources/<role>/とsources.lock。すべての引用はロックされたshaを使用します。product.yaml:app_canvas.logical(UIが再構築されるビューポート)、app_canvas.theme、app_canvas.rem_px、sources[].framework。- フレームワーク用アダプタ:
references/adapters/<framework>.md。サブエージェントプロンプトを作成する前に読んでください。そのスタックで値がどこに隠れているかが示されています。
| product.yamlのフレームワーク | アダプタ | ステータス |
|---|---|---|
angular-primeng | references/adapters/angular-primeng.md | 本番実績あり |
react | references/adapters/react.md | 未検証 |
vue | references/adapters/vue.md | 未検証 |
| Tailwindを使用するスタック | references/adapters/tailwind.md (フレームワーク固有のものと併用) | 未検証 |
html、other、サーバーテンプレート | references/adapters/html.md | 未検証 |
未検証のアダプタの場合は、ユーザーにその旨を伝え、それに従い、最後に学んだことを追加してください(「<製品>で学んだこと」セクションを短く追加)。そうすることで、次の製品がより先に進めるようになります。
1. グローバルレンダリング情報(製品ごとに1回)
画面の前に、すべての画面が依存する情報を確立し、出典付きで kit/render-facts.md に書き込みます。
- 実行時のルートフォントサイズ(CSSだけでなく、それを設定するアプリケーションシェルのコードを検索)。これにより、
remの変換が正しくなります。異なる場合は、product.yamlのapp_canvas.rem_pxを更新します。 - テーマ:どのセレクタがビデオのテーマを有効にするか、そしてそれがデフォルトでオンかどうか。
- トークンファイル、CSSレイヤーまたはインポート順序(どのルールが優先されるか)、ロックファイルからの正確なバージョンとそのテーマプリセットを持つコンポーネントライブラリ。
- 実際に読み込まれるフォント(linkタグ、
@font-face、フォントパッケージ)。CSSで名前が指定されているだけではありません。宣言されているが読み込まれていないフォントは、本番環境ではフォールバックとしてレンダリングされます。 - デスクトップブレークポイント。
app_canvas.logicalがデスクトップレイアウトを表示していることを確認します。
次に、ビデオのテーマ用にリテラルに解決されたトークンを書き込みます。
PVS_HOME="$(cd "$(cd "${CLAUDE_SKILL_DIR}" && pwd -P)/../.." && pwd)"
"$PVS_HOME/bin/pvs-py" "$PVS_HOME/skills/ui-spec-from-code/scripts/resolve_tokens.py" <product_dir> \
[--role frontend] [--theme-selector "html.dark"] [--files src/styles/tokens.css ...]
これは、sources/<role>/ からCSSカスタムプロパティ、トップレベルのSCSS変数、Tailwind v3テーマ(静的に)を読み取り、すべての var() と $variable を解決し、各行に /* role/path:line@sha */ の出典を付けて kit/tokens.css に書き込みます。UNDEFINED とフラグが立てられた行は、本番環境で定義されていない変数です(潜在的なグリッチ)。needs a Sass compile は、Sass関数で構築された値にマークを付けます。これはサブエージェントが関数とその入力から手動で解決する必要があります。エクスポートに関連のないスタイルシート(ドキュメントサイト、メールテンプレート、ベンダーCSS)が含まれている場合は、--files を使用してください。
2. 画面ごとに1つのサブエージェント
画面ごとに(または大きな画面のパネルごとに)1つの読み取り専用サブエージェントを、すべて並列で起動します。references/ui-spec-prompt.md にアダプタの「値が隠れている場所」リストを追加して埋めます。各サブエージェントを sources/<role>/ (ユーザーのチェックアウトではない)に向け、レンダリングコンテキスト(論理キャンバスサイズ、テーマ、rem、レンダリング情報、トークン、および既に再構築された部分のCSS)を提供します。これにより、新しい部分が一致します。
各サブエージェントは以下を返します:キャンバス内のジオメトリ、状態ごとの静的HTML(フレームワーク構文なし)、リテラル値と値ごとの出典を持つ1つのCSSブロック、追加クラスとしてのホバー/フォーカス/アクティブ/無効/ローディング状態、正確な継続時間とイージングを持つトランジションとキーフレーム、ライブラリと名前によるアイコン(またはそのままのインラインSVG)、すべての表示文字列、および明示的な「未検証」リスト。
コーディネーター(あなた)は自分で仕様を抽出しません。実際のアプリケーションの1つの画面は、数十キロバイトの調査結果になる可能性があり、ビデオの途中でコンテキストがいっぱいになったコーディネーターは、ビルド全体を見失います。
3. アイコンと画像
アイコンは製品独自のアイコンセットとアセットから取得し、描画したり、ブラウザプロファイルや拡張機能フォルダから取得したりすることは決してありません。製品ごとに(そして新しい画面ごとに)references/icon-extraction-prompt.md を実行して、ビデオが必要とするすべてのアイコンをそのライブラリと名前にマッピングし、その名前をproduct-kitの collect_icons.py に渡します。このスクリプトはSVGを出典付きで kit/icons/ にコピーします。SVGファイルがないアイコンフォントの場合、ビルドはライブラリ独自のCSSからコードポイントを書き込み、空のボックスをレンダリングするのではなく、不明な名前では失敗する必要があります。
4. 仕様を書く
画面ごとに、videos/<video>/specs/<screen>.md と specs/<screen>.html を作成します。
# 仕様: <画面>
ソース: frontend@1a2b3c4 (SOURCES.mdを参照)。キャンバス 1440x810、テーマ light、rem 16。
## ジオメトリ
| 要素 | x | y | w | h | 出典 |
## 状態
S1 <名前>: <表示内容、架空のデータ>。<screen>.html 内のHTML、セクション S1。
## CSS
<1つのブロック、リテラル値、各行に /* role/path:line@sha */>
## モーション
| 対象 | プロパティ | 開始値 | 終了値 | 継続時間 | イージング | 遅延 | 出典 |
## アイコン
| キー | ライブラリ | 名前 | kit/icons 内のファイル | 出典 |
## 文字列
| キー | テキスト | 出典 |
## 修正(ビデオで修正された本番環境のグリッチ)
| 対象 | 本番環境の挙動 | ビデオの挙動 | 理由 |
## 未検証
- <値または挙動、理由、および利用可能な最良の参照>
見た目を維持し、グリッチを修正する
レイアウト、トークン、動作を1:1で再構築します。アニメーション、ホバー、タイピング、ローディング状態など、実際の製品のように感じさせるものも含みます。しかし、目に見える本番環境の欠陥は修正します。ビデオは製品を最高の状態で表示し、レビュアーはなぜバグが画面に表示されているのか尋ねるからです。パディング不足、オーバーフロー、テキストの切り捨て、ネイティブブラウザコントロール(製品がデザインしたオーディオプレーヤーの代わりに表示されるグレーのデフォルトオーディオプレーヤー)、フォールバック値を表示する未定義変数、クリック後に残るフォーカスリングなどです。すべての修正を仕様の修正テーブルとBRIEFノートにリストします。設計上の決定である奇妙な点(フィールドを覆うスティッキーフッター、コンテンツと共にスクロールするサイドバー)はそのまま維持します。それらを変更することは修正ではなく、再設計です。
仕様が適用して記録する2つの追加の変換:
- 正規名。
product.yaml namesのレガシー文字列を、ライブUIがまだ古いものを表示している場合でも正規名に置き換えます。その要素の他のすべての点は維持します。 - 禁止用語。実際の画面にベンダーまたは
banned_termsの用語(モデルピッカー、統合カード)が表示されている場合は、その部分をフレームから除外します。空っぽまたは壊れて見えてはいけません。それが自然に存在しないフレーミングまたは状態を選択します。
データ
仕様には、product.yaml cast からの架空のデータのみが含まれます。リポジトリ内のフィクスチャ、シード、スクリーンショットには実際の名前が含まれる場合があります。それらの形状を使用し、値は決して使用しません。
仕様をビルドに渡す前のチェックリスト
- ロックされたコミットが出典として使用されている。レンダリング情報が書き込まれている。ビデオのテーマ用にトークンが解決されている。
- キャンバスサイズがデスクトップブレークポイントより大きい。remが実行時と一致している。
- すべての
var()が解決されている。未定義のものはフォールバックと共にリストされている(またはグリッチとして修正されている)。 - すべての文字列がi18nファイルまたはテンプレートから取得されている。正規名が適用されている。
- すべてのアイコンがアプリのライブラリから取得されている。ビルドはグリフが見つからない場合に失敗する。
- ロゴと画像がリポジトリのアセットから取得されている。
- デフォルト状態(タブ、アコーディオン、トグル)がコードと一致している。
- オーバーレイ、ポップアップ、トランジションのタイミングが正確なイージングと共に取得されている。
- スクロール範囲が実際のコンテンツ内に収まっている。テキストが端で切れていない。
- フレーム内にベンダー、禁止用語、内部ID、実際の顧客データが含まれていない。
- 修正と維持された奇妙な点がリストされている。未検証の値がレビュアー用にリストされている。