HTML ドキュメントデザインシステム 部品見本

design-system / component samples

技術的な説明 HTML で使う視覚部品と、その用途を確認するための見本です。

  • 背景はオフホワイト #FAF9F6、部品は白地 + 黒罫線 + 角丸で浮かせる
  • 自然言語は Ubuntu Sans（日本語は Noto Sans JP に代替）、コードは UbuntuMono Nerd Font で統一する
  • 有彩色はリンク青 #2990DA とアクセント赤 #D63A2F の2色のみ。赤は1ページに1箇所まで

設計トークン（色と字体）

色は CSS 変数として定義しています。 部品を追加するときも、直接の色指定ではなく変数を参照します。

変数値役割
--mb-bg#FAF9F6ページ背景（オフホワイト）
--mb-surface#FFFFFFカード・表などの面
--mb-ink#111110見出し・強調・罫線（黒）
--mb-ink-body#1A1A1A本文の文字色（墨色）
--mb-rule#DFDFDF構造だけを示す薄い罫線
--mb-muted#595959補助テキスト
--mb-faint#A5A5A5フッターなど最弱の文字
--mb-link#2990DAリンク・URL
--mb-accent#D63A2F最重要語の強調（1ページ1箇所まで）

表は短い対応関係の一覧に使います。セルに句点を含む文を書かず、文で説明したい内容は本文に置きます。 列は3列までを基本とし、長文になる列は最後に置きます。各行の見出しになるラベル列には .mb-rowlabel を付けて折り返しを禁止します（「層1　座標系」が「座標/系」で割れる崩れを防ぎ、 残りの幅が本文列へ配分されます）。

ラベル列内容
層1　座標系ラベル列は mb-rowlabel で折り返されない
層2　フォント本文列が残り幅を受け取る

字体は2系統だけです。自然言語（見出し・本文・補助テキスト）は Ubuntu Sans + Noto Sans JP、 コード・URL・日付などのメタ情報は UbuntuMono Nerd Font（代替: Ubuntu Mono）。 欧文と和文が混ざる本文では、欧文グリフが Ubuntu Sans、和文グリフが Noto Sans JP で描画されます。

見出しと本文

h1 と h2 には左端の黒い縦棒が付きます。CSS が自動で付けるため 書き手は何も指定しません。h3 は縦棒なしの太字です。

本文中の強調は strong（黒の太字） を基本とし、ページ内で最重要の一語だけ em（アクセント赤） を使えます。リンクは example.com/docs のように青になります。

  • 箇条書きの行頭は黒丸（CSSが描画する。文字の ● は使わない）
    • 入れ子は小さいグレーの丸になる
  • チップは 検索 生成 評価 のような並列の分類名の列挙にだけ使う

カードとグリッド

カードは白地 + 黒罫線 + 角丸です。中央揃えのタイトル帯を持つ「タイトル付きカード」と、 左上に小ラベルを置く「ラベル付きカード」の2形があります。並べるときはグリッドで高さを揃えます。

タイトル付きカード

比較対象の名称をタイトル帯へ置き、本文との境界を水平罫線で示します。

ラベル付きカード

「前提」「結果」のような短い欄見出しを左上へ置く形です。

引用

外部の発言・文書の引用は引用カードに入れます。原文と日本語訳は同じカード内で上下に並べ、 間をグレーの罫線で区切ります。訳の文字サイズ・色は原文と同一にします（訳だけ小さくする・薄くするのは禁止）。 出所はカード末尾に等幅で書きます。

Early versions of Claude Code used RAG + a local vector db, but we found pretty quickly that agentic search generally works better.

Claude Code の初期バージョンでは RAG とローカルのベクトルDBを使っていたが、 エージェンティック検索の方が概ね優れていることにすぐ気づいた。

x.com/bcherny/status/2017824286489383315

図とコードと数式

.mb-figure は、画像や SVG とキャプションを一つにまとめる外枠です。 内部の図の種類を表すコンポーネントではありません。 .mb-figure-frame は視覚資料の表示面、figcaption は図番号・説明・出所に使います。

自作の説明図はインライン SVG で、黒一色の線画を基本とします。 矢印でつながった箱は、ここで示す図の一例にすぎません。

原稿 共有CSS HTML文書
fig.1 デザインの一貫性を担保する流れ

コードブロックは白カードの中に等幅で置き、Highlight.js で言語に応じたシンタックスハイライトを適用します。 language-html のように言語を明示します。 

<link rel="stylesheet" href="./design-system/document.css">

コード差分は生の差分を貼らず、変更を論理順の散文で説明しながらコード断片を埋め込みます。 表現は GitHub と同じ慣習（追加 = 緑の淡背景 + 行頭の +、削除 = 赤の淡背景 + 行頭の -）です。 この緑・赤は差分部品に限って許される機能色で、本文の装飾には使えません。 

.mb-quote-ja {
  font-size: 14.5px;
  border-top: var(--mb-border-w) solid var(--mb-rule);
}

数式は MathJax で描画します。書体は MathJax の既定に任せます。 インラインは $p(w_t \mid w_{<t})$ のように、ディスプレイは次のように書きます。

$$ \mathrm{softmax}(z)_i = \frac{\exp(z_i)}{\sum_j \exp(z_j)} $$

再利用方法

成果物と同じ場所へ design-system ディレクトリを配置し、 head から CSS、数式コピー用 JavaScript、MathJax、Highlight.js の順に読み込みます。 

<link rel="stylesheet" href="./design-system/document.css">
<script src="./design-system/math-copy.js"></script>
<script async src="https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"></script>
<script src="https://cdnjs.cloudflare.com/ajax/libs/highlight.js/11.11.1/highlight.min.js"></script>
<script>hljs.highlightAll();</script>