ref-handout-design-system

Purpose & Output Contract

guide-doc-generator が生成する資料のデザイン言語について、問い合わせに対して規範を 引用で返す参照。返す面は 5 つに限る。

1. 部品カタログの構成データ表現
2. CSS 変数トークン一覧
3. アイコン規約
4. 文章設計の型
5. カードとナビの視覚設計 (R25)

デザイン言語の出所は jp-web-design のモードB「Pop・親しみ」である。実行時に plugin の外を読まないため、採用した規範は assets/jp-web-design-mode-b.md へ vendoring した。回答の組み立て方は references/answer-patterns.md に置く。 ユーザーグローバル資産 (~/.claude 配下など) と絶対パスは参照しない。

責務境界 (Boundary)

• 入力 = 部品またはトークンについての問い合わせ。出力 = 規範の引用。
• HTML の生成とレンダリングはしない。単独 writer は C11 render-handout.py で あり、CSS・部品テンプレート・トークン展開・入場アニメーションを書くのはその 1 本だけである。
• 生成物の検証もしない。自己完結とアイコン様式は C16、a11y と印刷は C17、言語 規約は C18、物語構造は C22 が判定する。
• 語彙を自分の側へ複製しない。部品 id・用途語彙・セクション種別はいずれも別 component が所有するデータファイルが正本で、この skill は毎回それを読む。
• 生成物は外部参照ゼロの単一 HTML である。CDN・web font・外部 URL・外部アイコン フォントを前提とする設計回答をしない。取得を発生させる参照が違反かどうかの判定 規則の正本は C16 verify-handout-selfcontained.py の CR-EXT であり、この skill はその所在を示すだけで自分では判定しない。
• 規範と実装が食い違って見えるときは、描画の実装 (C11) が正本である。この skill は参照回答であって仕様の決定主体ではない。

参照の正本表

問い合わせ	読むファイル	owner
部品の id と属性	config/handout-parts.json	C11
用途の語彙とプリセット	config/handout-purposes.json	C23
セクション種別	config/handout-sections.json	C12 (writer)
冒頭カード・ナビの閾値と見出し語	config/handout-visual-policy.json	C12 (閾値解決)
カードの CSS クラス名と DOM 構造	C11 render-handout.py のブリーフ	C11
外部参照ゼロの判定規則	C16 verify-handout-selfcontained.py の CR-EXT	C16
テーマトークンの実値	assets/tokens/<theme>.json	C11 (スキーマ owner は C11)
採用したデザイン言語	assets/jp-web-design-mode-b.md	C04 (vendoring 実体)
回答の型	references/answer-patterns.md	C04

面 1: 部品カタログの構成データ表現

部品 id の語彙をこの skill は持たない。問い合わせのたびに正本 config/handout-parts.json (owner: C11) のカタログを読んで答える。カタログを 参照せずに記憶から id を答えることを禁じる。

• カタログの各エントリは id と表示名、kind (骨格 / セクション内の具体部品 / メディア)、section_scope、構成データ側のブロック型、初出、出所を持つ。
• 「セクション内の具体部品か」を判定する述語は section_scope であり、id の 範囲指定で判定しない。カタログに部品が増えても述語は変わらない。
• 構成データは部品を直接名指しせず、ブロック型で表現する。ブロック型から部品への 写像はカタログの data_block_type を引く。
• 用途の語彙は config/handout-purposes.json (owner: C23) を、セクション種別は config/handout-sections.json (writer: C12) を読む。どちらもこの本文へ値を 書き写さない。

面 2: CSS 変数トークン一覧

アクセントは 1 色だけ置き、そこから明度の 4 段階を派生させる。派生した値は <style> 冒頭の :root へ展開し、実値が現れるのはそのブロックだけにする。 以降の CSS 規則と SVG はすべて var() 参照で書く。こうしておくと、テーマを 差し替えるときに書き換える場所が 1 か所で済む。

値の正本は assets/tokens/<theme>.json であり、この skill にも生成コードにも 実値を焼かない。テーマを増やすときはトークンファイルを 1 枚足す。以下は形の 例示であって値の正本ではない。

:root {
  --pop-primary: #43a4f5;
  --pop-primary-pastel: #8ecdf8;
  --pop-primary-soft: #d9edfe;
  --pop-primary-deep: #2273b8;
  --pop-bg: #eaf5fe;
  --ink: #1b2733;
  --ink-muted: #5b6b7a;
  --line: #dbe6ef;
  --subtle: #f4f8fc;
  --card-radius: 24px;
  --font-num: "Helvetica Neue", Arial, sans-serif;
}

body {
  background: var(--pop-bg);
  color: var(--ink);
  font-feature-settings: "palt";
}
.card { border: 1px solid var(--line); border-radius: var(--card-radius); }
.chip { background: var(--pop-primary-soft); color: var(--pop-primary-deep); }
.num { font-family: var(--font-num); font-variant-numeric: tabular-nums; letter-spacing: -0.015em; }

@keyframes rise-in {
  from { opacity: 0; transform: translateY(12px); }
  to   { opacity: 1; transform: none; }
}
.section { animation: rise-in 480ms ease-out both; animation-delay: var(--stagger, 0ms); }

@media (prefers-reduced-motion: reduce) {
  .section { animation: none; }
  html { scroll-behavior: auto; }
  * { transition: none; }
}

• 4 段階の役割: ブライトは CTA とトグル ON、パステルは面、soft は選択状態と チップとリング、deep は文字とリンクと線画。deep を面に使わない。
• 和文は font-feature-settings: "palt" を body に置いて字間を詰める。
• 数値は tabular-nums で桁を揃える。桁が揃わない表は読み比べができない。
• 入場は rise-in のスタガー。段差はインライン変数 --stagger で各要素へ与え、 JavaScript を使わない形で成立させる。段差の上限は C11 が決める。
• prefers-reduced-motion: reduce では animation と scroll-behavior と transition を無効化する。
• テーマトークンには text_limits.block_body_max_chars (既定 400) が入る。この スキーマの owner は C11 であり、上限を超えた本文の折り畳み規則は C12 の CR-TEXT-FOLD が正本である。この skill は既定値を引用するだけで、値も規則も 決めない。

面 3: アイコン規約

様式は 4 点で固定する。viewBox="0 0 24 24" / stroke="currentColor" / fill="none" / stroke-linecap="round"。塗りつぶしアイコンと 24 以外の viewBox を混ぜない。

<svg width="0" height="0" aria-hidden="true" style="position:absolute">
  <symbol id="hbic-check" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
    <path d="M4 12l5 5L20 6" />
  </symbol>
</svg>

<svg class="ic" aria-hidden="true"><use href="#hbic-check" /></svg>

• 定義は <symbol> に 1 回だけ置き、使う側は <use> で参照する。同じ図形を 複数回インライン展開しない。
• 色は stroke="currentColor" 経由で親の文字色に従う。アイコン側に実値を 書かない。
• 構成データから実際に参照されたアイコンだけを sprite に入れる。 未使用の symbol は 0 件にする。
• sprite の生成と symbol id の採番は C15 build-icon-sprite.py が行う。この skill は様式を答えるだけで生成しない。採番規則を自分で決めない。
• アイコンの代わりに絵文字を使わない。装飾でも見出しでも絵文字は使わない。 意味を持つ記号が要るなら線画アイコンを sprite へ足す。

面 4: 文章設計の型

読み手は初心者・非エンジニアである。抽象と具体を往復させる型を守る。

1. 冒頭は一文の主題。到達ゴールはチップで並べ、読み終えた後の状態を示す。
2. 全体像を先に出し、読み手が残量を把握できるようにする。
3. 各セクションは「番号 + 見出し」から始め、次に絵、その後に 1 行の抽象 (lead-line) と具体部品を置く。
4. 抽象を出したら具体例を続け、最後に判断軸を一文で締める。判断軸が無い節は 読み手が自分の状況へ当てはめられない。
5. 専門用語には必ず括弧書きの言い換えを添える。初出で言い換えなかった語は以降も 通じない。
6. 一文を短くする。補足文はおおむね 20 から 45 字に収める。
7. 断定できないことは「未確定」と書く。推測を事実の形で書かない。

判定は人手ではなく C18 と C22 と C06 が行う。この skill はその規範の出典を 示すだけで、個別の原稿を採点しない。

面 5: カードとナビの視覚設計 (R25)

冒頭は段落で埋めず、1 行の宣言とカードで見せる。ナビは読み手が残量を把握する ための導線である。この面で返すのは「どこに正本があるか」であって、閾値の実値 でも DOM の写しでもない。値も構造もこの本文へ複製しない。

• 冒頭を hero-card 化する対象フィールドと、そこで用いる見出し語は config/handout-visual-policy.json の #opening.hero_card_fields.layout / #opening.list_headings.headings / #opening.connector_card.heading を 読んで答える。
• nav 項目のラベル上限は同じファイルの #micro_copy.roles のうち role="label" のエントリ (fields に nav_item を含むもの) を読む。 上限の数値をこの本文へ書き写さない。
• nav の置き場所 (左の柱か上の帯か)・柱の幅・帯へ戻す画面幅は同じファイルの #nav.layout / #nav.sidebar_width_px / #nav.collapse_below_px を読む。 どちらの置き場所でも sticky は維持する (スクロールしても目次は消えない)。 柱では札を縦に積み、行頭を左で揃える。値をこの本文へ書き写さない。
• CSS クラス名と DOM 構造の正本は C11 render-handout.py のブリーフにある block_to_component_map の冒頭ブロックのエントリである。.hero-card-grid / .hero-card / .hero-card-label / .hero-card-body / .section-card と いった名前はそこで決まる。この skill は所在を示すだけで複製しない。
• 冒頭の分量が上限を超えているかの判定 (W-HERO-LONG / W-HERO-HEAVY) は C12 validate-handout-config.py の責務である。この skill は値を読まないし 判定もしない。
• 参照先のキーが正本ファイルに存在しないときは、記憶や推測で埋めない。 「未確定」と答え、正本の owner へ差し戻す。