Design（デザインキャンバス）

デザインキャンバス

画面上のデザインをプロジェクト内の実際のHTMLファイルとして作成し、ローカルのデザインビューアで表示します。ユーザーは各画面を横並びで見たり、デバイスサイズやライト/ダークテーマを切り替えたり、PNGエクスポートや画面へのコメントができます。コメントは特定のプレフィックス付きのチャットメッセージとしてあなたに返ってきます。

ファイル（契約）

design/
  tokens.json            すべてのデザイントークンの単一真実点
                         （両テーマ共通）；ブランド値が存在する唯一の場所
  design-system.css      tokens.jsonから生成：
                         [data-theme="light"]および[data-theme="dark"]用のデザイントークン（編集禁止）
  utilities.css          tokens.jsonから生成：クローズドユーティリティ
                         ボキャブラリ（編集禁止）
  design-system.md       ブランド上の決定事項を言葉で（簡潔）
  validate.mjs           バリデーター（プロジェクトごとに一度コピー - セットアップ参照）
  serve.mjs              ビューア用の小型静的サーバー（プロジェクトごとに一度コピー）
  viewer.html            ビューア（プロジェクトごとに一度コピー）
  mock.js                インタラクティブ画面用のモックランタイム（プロジェクトごとに一度コピー）
  mock.css               モックランタイムクラス用の静的スタイル（プロジェクトごとに一度コピー）
                         — トースト/オーバーレイ/エンタートランジション状態；
                         画面は `../mock.css` としてリンク；mock.js はこれらのクラスを
                         トグルするだけで、CSSを注入することはありません
  scripts/               プロジェクトごとに一度コピー（セットアップ参照）
    gen-tokens.mjs       tokens.json から design-system.css + utilities.css を再生成
    sync-components.mjs  各コンポーネントマーカー領域をそのパーシャルから再実体化
                         （プロジェクトごとに一度コピー）
    marker-parser.mjs    共有マーカー文法パーサー、ランタイムで同期インポート
                         （プロジェクトごとに一度コピー）
  components/            コンポーネントレジストリ + パーシャルシード（プロジェクトごとに一度コピー）：
                         components.json + コンポーネントごとに1つのパーシャル
  vendor/html-to-image.js  PNGエクスポートライブラリ（プロジェクトごとに一度コピー）
  index.json             {"canvases": ["login", ...]} でビューアがリスト表示できるようにする
  <canvas>/              キャンバスごとに1つのフォルダ、ケバブケース（login、dashboard）
    canvas.json
    data.json            オプションの架空データ；オプションの "scenarios" オブジェクト
                         には名前付きトップレベルオーバーライド（empty, critical…）
    01-<screen>.html     画面ごとに1つの完全なHTML文書
    assets/              オプションのローカル画像/スクリプト

canvas.json（画面はこの順序で表示されます）：

{
  "title": "アプリのログイン",
  "screens": [
    { "id": "login", "name": "ログイン", "file": "01-login.html", "device": "mobile" },
    { "id": "cadastro", "name": "登録", "file": "02-cadastro.html", "device": "mobile" }
  ]
}

• device：mobile = 390×844、tablet = 834×1112、desktop = 1440×900； オプションの width/height（整数 100～10000）で上書きできます。
• group（オプション）：ビューアストリップで画面をタイトル付きブロックにグループ化するラベル — 複雑なプロジェクトでも読みやすく保ちます（例："group": "チェックアウト"）。
• transition（オプション）：fade、slide-left または none（デフォルト）。 Mock.go 後の画面のエンターアニメーションです — 同じキャンバス内/キャンバス間のルールについてはワークフローステップ3を参照。
• id は一意かつ空でない；name は空でない；title はオプション。
• file はキャンバスフォルダからの相対パス：決して ..、先頭の /、\、 スキーム（http:、file: …）を含みません。

プロジェクトごとの初回セットアップ

design/ がまだ存在しない場合、それを作成し、このスキルのフォルダ（この SKILL.md が含まれるフォルダ）からコピーします：

• scripts/validate.mjs → design/validate.mjs
• assets/viewer.html → design/viewer.html
• assets/serve.mjs → design/serve.mjs
• assets/mock.js → design/mock.js
• assets/mock.css → design/mock.css（モックランタイムクラス用のスタイル； 画面は ../mock.css をリンク）
• assets/docs.html → design/docs.html（使用ガイド、ビューアの 📘 ドキュメントボタンからリンク）
• assets/vendor/html-to-image.js → design/vendor/html-to-image.js
• scripts/gen-tokens.mjs → design/scripts/gen-tokens.mjs
• assets/components/ → design/components/（レジストリ + パーシャルシード）
• scripts/sync-components.mjs → design/scripts/sync-components.mjs
• scripts/marker-parser.mjs → design/scripts/marker-parser.mjs（共有パーサーモジュール 同期インポート、ランタイムで必要）
• scripts/export-tokens.mjs → design/scripts/export-tokens.mjs（W3C/DTCG 相互運用エクスポート：tokens.json → tokens.w3c.json；派生アーティファクト、 手動で編集しないこと）

このコピーリストのルール：すでに存在するファイルのみがリストに入ります（「só entra no copy list arquivo que já existe」）。まだこれから作成されるファイルは、その契約の波でのみ追加されます：export-tokens.mjs は契約の波6（todo 30）で追加され、上記にリストされています — ルールは満たされています（ファイルはtodo 26から存在します）。（mock.css は波3で追加され、上記にリストされています。）

tokens.json が変更されるたびに、プロジェクトルートから2つの生成ファイルを再生成します：

node design/scripts/gen-tokens.mjs

design/index.json（{"canvases": []}）を作成し、新しいキャンバスを作成するたびにキャンバス名を追加します。完全で有効な例は、このスキルの assets/example/ にあります — 2つのキャンバスにわたる動作するストックアプリシステム： login/（ログイン、サインアップ、プレーンリンクからオーバーレイとして開くアカウント削除確認モーダル）および dashboard/（長いアイテムリスト、同じキャンバス内の「リストを更新」リフレッシュ（fade トランジションとスクロール復元をデモ）、ログインとサインアップがキャンバス間をナビゲートして概要画面に移動し、架空のアイテムを読み取り、名前付きシナリオをサポートし、ログインキャンバスにログアウトするインタラクティブな概要）。新しいデザインシステムやキャンバスを開始する前にこれを読み、適応させてください。シード example/components/ は assets/components/ のバイト単位の同一コピーです（「example/components/ は assets/components/（単一ソース）のバイト単位の同一コピー」）：パーシャルは assets/components/ でのみ編集し、例のコピーでは決して編集しないでください。

ワークフロー

1. まずデザインシステム。 design/design-system.css と design/design-system.md を読んでください。それらが存在しない場合、ユーザーにブランド （プライマリカラー、タイプフェースの雰囲気、トーン；ニュートラルパレットを一つの選択肢として提供）を尋ね、その後両方を作成します。後続のキャンバスはそれらを再利用します。トークンは尋ねた後にのみ変更してください。
2. 不足しているものだけを尋ねてください。 リクエストが曖昧な場合（どの画面、どのプラットフォーム、どんなデータ）、一度尋ねてください；明確な場合は、開始してください。
3. キャンバスを構築します。 最初にこのスキルのフォルダから assets/craft.md を読んでください（これは兄弟スキル（taste、emil-design-eng、impeccable）を統合してキャンバス画面用のルールにしています）、そしてそれをすべての画面に適用します。その後、canvas.json と画面を作成します。すべての画面のルール：
   • スタイリングポリシー：ユーティリティボキャブラリがボキャブラリです。トークンベースのもの（色、タイポグラフィ、スペーシング、角丸）はすべて生成されたユーティリティを介します：<link rel="stylesheet" href="../design-system.css"> と <link rel="stylesheet" href="../utilities.css"> をリンクし、bg-accent、p-2、text-heading、rounded-md などのクラスを使用します。インタラクティブな画面は <link rel="stylesheet" href="../mock.css">（モックランタイムクラス：トースト、オーバーレイ、エンタートランジション）もリンクします。セマンティッククラスは構造とレイアウトのみを運びます。var(--…) は適切なユーティリティがない場合に許可され、インライン <style> ブロックは許可されますが、リテラルカラーを一切含んではなりません。禁止スイープは <style>、style=""、SVG の fill=/stroke= の値位置にあるリテラルカラーをスキャンします；また、画面内の http(s)://、Tailwind パレットクラス（bg-zinc-900 など）、および text-[13px] のような任意の値も禁止します。
   • 両方のテーマでトークンを介して動作します；テーマは <html> の data-theme として届きます（デフォルトは light — 属性を含めてください）。
   • いかなる種類の CDN やリモート URL も使用しないでください（キャンバスはオフラインでサンドボックス化されています）：インライン SVG アイコン、システムフォント、または design/ 下のフォントファイル、ローカル画像。
   • ユーザーの言語（デフォルトはブラジルポルトガル語）で実際のコピーを使用し、もっともらしいサンプルデータ — lorem ipsum は使用しないでください。
   • 重要な場合、空、ロード中、エラー状態を追加の画面としてカバーしてください。
   • アクセシビリティの基本：入力にラベル、可視のフォーカス、十分なコントラスト、モバイルでタップターゲット ≥ 44px。
   • レイアウトは画面のデバイス幅で保持される必要があります。
   • コンポーネントはパーシャルのインスタンスであり、決してバラバラのコンポーネントマークアップではありません（「instância usa partial, nunca markup solto de componente」）。すべてのインスタンスをマーカーペア <!-- component:id size=md tone=primary state=default -->…<!-- /component:id --> でラップし、3つの必須引数 size=、tone=、state=（値は design/components/components.json のレジストリ enum に含まれている必要があります）を指定し、そのスロットをペアマーカー <!-- slot:name -->…<!-- /slot:name --> として埋めてください。優先順位：マーカー引数が真実のソースです（marker-args-win）。同期は実行のたびにマーカーから data-size/data-tone/data-state とバリアントクラスを再出力します；スロットの内容とルート上のユーザー追加 data-* 属性は保持されます。
   • ポスターではなく、システムプレビューにしてください。 リクエストが動作する製品を暗示する場合、モックランタイム（セットアップでコピーされた <script src="../mock.js"></script>）で画面を配線します：フォームは検証および送信され、ボタンはフィードバックを提供し、画面は Mock.go('03-dashboard.html') でナビゲートし、架空のデータはキャンバスの data.json に存在し（await Mock.data('items')）、フロー状態（ログインユーザー、途中で作成されたアイテム）は Mock.state（セッション、キャンバスごとに名前空間）に存在し、シミュレートされたアクションは Mock.toast('…') で確認します。すべての画面は、JS が失敗した場合でも静的な構成としてレンダリングされる必要があります。ビューアは、ナビゲートしたカードに ↺ 最初から ボタン、フロー全体を最初からやり直すための 「⟲ フローリセット」 を表示します。重要な状態は data.json の名前付き scenarios としてカバーします（トップレベルのオーバーライド、例："vazio": {"items": []}）— ビューアはそれらのセレクターを取得し、選択はナビゲーション間で保持され、各シナリオは適切に構成される必要があります（空のリスト、すべてのアイテムが最小値未満、API 障害）。システムは複数のキャンバスにまたがることができます（フローごとに1つ）：Mock.go('../<canvas>/<screen>.html') でキャンバス間をナビゲートします — フロー状態はプロジェクト全体で共有されるため、ログインキャンバスがユーザーを設定し、ダッシュボードキャンバスがそれを読み取ります。ビューアのキャンバスセレクターはキャンバス間をジャンプします（各キャンバスは独自のシナリオ、テーマ、デバイスを保持します）。モーダルと確認ダイアログも完全なキャンバス画面です（単一の真実点）：トリガーはプレーンな画面リンク、<a href="03-modal.html"> であり、モックランタイムはそれを Mock.overlay('03-modal.html') にインターセプトします — JS がない場合、変更されていない href はモーダル画面自体にナビゲートします（JSオフのフォールバック）。永続的なナビゲーション（サイドバー、トップメニュー、タブ）は実際に画面を切り替える必要があります：各アイテムに data-go="02-cadastro.html" を配置し（同じリンクに実際の href="02-cadastro.html" を JSオフのフォールバックとして保持 — ランタイムは data-go を Mock.go にルーティングし、?scenario= とエンタートランジションを保持します）。プレーンリンクはオーバーレイトリガー（モーダル/詳細 — プレーンな画面リンクは常にオーバーレイを開きます）のために予約されています；キャンバスのすべての画面で同じナビゲーションブロックを繰り返し、アクティブなアイテムをマークします。画面は canvas.json で "transition": "fade"|"slide-left"|"none" を宣言できます：Mock.go は宛先にエンタークラス（mock-enter-fade/mock-enter-slide-left、300 ms 以内に自己削除）を付与します。ハンドオフは宛先ファイル名に一致する現在のキャンバスの canvas.json を読み取るため、同じキャンバス内のホップ（Mock.go('01-overview.html') のような自己ナビゲーションはリフレッシュパターン）で機能します — キャンバス間の Mock.go('../<canvas>/<screen>.html') はエンタークラスなしのプレーンなナビゲーションです。スクロール位置は画面ごとに保持されます（sessionStorage の scroll.<canvas>.<file>、画面が戻ったときに復元され、⟲ フローリセット（mock.* のみをクリア）の影響を受けません）。
4. 検証して修正します。 最初に必須の同期：design/components/ 内のパーシャル（またはマーカーの引数）を編集した後、何かを提示する前にプロジェクトルートから node design/scripts/sync-components.mjs を実行します；これはすべてのインスタンスをそのパーシャルから再実体化します（marker-args-win）。--check はドライラン形式です：発散する領域ごとに file:line の差分を出力し、発散がある場合は終了コード1で終了し（クリーンな場合は0）、書き込みは行いません。次にプロジェクトルートから実行します：node design/validate.mjs design/<canvas>。リストされたすべての問題を修正し、サマリー行だけが残るまで再度実行します。問題があるキャンバスを決して提示しないでください。バリデーターの引数はデザインルート（プロジェクトモード）または単一のキャンバスフォルダ（キャンバスモード）です；引数がない場合、デフォルトは ./design です。構造チェックは canvas.json にリストされた画面のみをカバーします；プロジェクトモードではさらにトークン/生成CSSの古さ、コンポーネント、コメントをチェックします。コンポーネントルールは、canvas.json とは独立して、すべての非除外 .html でスキャンされ、コード component-unknown、component-variant、component-marker、component-divergence、slot-marker があります。--allow-stale は古さチェックのみをスキップします；--mark-stale はバリデーターの唯一の書き込み操作です（アンカーがなくなったコメントピンをマークします）；--example-inventory は例の契約チェックです（inventory.json + すべてのピンに "_demo": true の正確なファイルリスト；inventory.json がない場合 = スキップ、終了コード0）。 4b. 完璧な監査。 検証後、兄弟スキル impeccable の技術監査をキャンバスに対して実行します（インストール済み、win32）：<skill-impeccable>/scripts/impeccable.cmd audit design/<canvas> - パスはインストールされたスキルパスから解決されます。

…（以降は翻訳対象外のため省略）