AIエージェントに「日本語のダッシュボードを作って」と頼むと、和文フォントが抜け落ち、行間が詰まり、句読点が行頭に来るUIが返ってくる。awesome-design-md-jp はこの「AIが日本語UIを壊す」問題を、378サイト分のDESIGN.md（デザイン仕様書）で正面から埋めるプロジェクトだ。この記事では日本語UIに特化したDESIGN.mdリソースを解説します。デザインシステム・UI生成全般は デザインシステムとは？仕組み・構成要素・有名事例をエンジニア向けに完全解説 をご覧ください。
awesome-design-md-jp とは — 378サイトの日本語UI DESIGN.md集
awesome-design-md-jpは、Google Stitchが提唱した「DESIGN.md」フォーマットを日本語タイポグラフィ向けに拡張した日本語版OSSである。GitHubでkzhrknt氏が2026年4月6日に公開してから約3ヶ月で806スターまで伸びており、収録数は当初の182サイトから378サイトへと倍増している（2026年7月時点、ライセンスはMIT）。
このリポジトリが何をできるようにするのかを一言で言えば、「AIエージェントに正しい日本語UIを生成させる」ことだ。DESIGN.mdは、コーディングエージェントが「色・フォント・余白・コンポーネント・Do’s and Don’ts」を機械的に読み取れる形式で記述したマークダウン仕様書である。AGENTS.md（プロジェクトの作り方）と並べてリポジトリのルートに置き、AIがUIを生成するたびに参照させることで、ブランドトーンの一貫性を保てる。awesome-design-md-jpはこのフォーマットの日本語タイポグラフィ拡張を提案する位置づけだ。
公開からの伸びは、海外で先に話題になった本家awesome-design-md（VoltAgent、9万スター超）の文脈に乗っている。本家がVercel、Stripe、Linear、Notionなど欧米ブランドを集めた一方で、日本語UIの仕様は完全に欠落していた。awesome-design-md-jpはここを埋めるプロジェクトで、Apple Japan・MUJI・freee・mercari・任天堂・サイバーエージェント・虎屋・銀座シックスといった国内サービスのDESIGN.mdを揃えている。
DESIGN.mdの書き方・最小テンプレート・フロントマターの構造は DESIGN.md入門 にまとめている。本記事は日本語タイポグラフィ拡張に絞って解説するので、未読の場合は先に入門記事を確認すると流れがつかみやすい。
このOSSが何を解決するのか、何を代替するのかを、以下のセクションでタイポグラフィの崩れ・収録範囲・テンプレート構造・本家との違い・導入手順の順に見ていく。
日本語タイポグラフィがAIのUI生成で壊れる理由 — DESIGN.mdに何を書くべきか
awesome-design-md-jpが解決するのは、AIが生成する日本語UIのタイポグラフィ崩れである。原因は、欧文ベースの学習データと欧文向けのCSSパターンが優先されるためで、日本語UIに必要な仕様が明示されない限り改善は望めない。READMEが指摘している「日本語UIで欠落しがちな仕様」は以下の6点だ。
- 和文フォントのフォールバックチェーンが指定されない（システムデフォルトで描画）。
- line-heightが欧文用の1.4〜1.5のままで、本文が詰まる。
- letter-spacingがゼロのまま、長文の可読性が落ちる。
- 禁則処理が設定されず、句読点や括弧が行頭に来る。
- palt・kernなどのOpenType機能が無効で、見出しのパッキングが甘い。
- 和欧混植ルールがなく、欧文と和文の比率がアンバランスになる。
これらはCSSとフォントの組み合わせで防げる現象だが、AIに毎回口頭で説明するのは現実的でない。DESIGN.mdのTypography Rulesセクションに固定値で書いておけば、Claude CodeやCursorは生成のたびにそこを参照する。awesome-design-md-jpはこの日本語UI向けTypography Rulesをフォーマットとして整備した点が中心的な貢献だ。「指定なしでAIに任せる」場合と「DESIGN.mdを読ませる」場合の差は、次の対比のように現れる。
本文の行間と字間について、awesome-design-md-jpが欧文標準に対して推奨する値を並べると、書き残すべき項目が明確になる。
| 観点 | 欧文の標準 | 日本語の推奨 | 理由 |
|---|---|---|---|
| 本文 line-height | 1.4〜1.5 | 1.5〜2.0 | 漢字の上下バランスを取り、視線移動を楽にする |
| 本文 letter-spacing | 0 | 0.04〜0.1em | 全角文字の詰まりを緩和し、可読性を上げる |
| 見出し letter-spacing | -0.02em〜0 | 0〜0.05em | 詰めすぎないことで漢字の重みを保つ |
| 禁則処理 | 不要 | line-break: strict | 句読点・括弧の行頭・行末ルールを守る |
| OpenType palt | 用途次第 | 見出しに有効 | 仮名・約物のプロポーショナル詰め |
数値そのものはサイトによって異なるが、「項目として書き残す」ことが重要である。AIは項目が存在しない領域には踏み込まないことが多く、Typography Rulesに数行加えるだけで生成結果が明確に変わる。これが、コード生成ツールを日常的に使う開発者にとっての最大の実利だ。
awesome-design-md-jp の収録範囲 — SaaSから伝統工芸まで378サイト
awesome-design-md-jpの強みは収録範囲の広さである。SaaSと一般メディア中心の本家awesome-design-mdに対し、日本語版はビジネスSaaSからファッション、伝統工芸、自動車、化粧品、ホテル、公共・政府まで幅広く378サイトのDESIGN.mdを集めている。GitHub Pages上の Galleryページ で全サイトのデザイントークンを可視化できる。カテゴリ別に整理すると、参考になる組み合わせが見えてくる。
| カテゴリ | 収録サイト例 |
|---|---|
| ビジネスSaaS | freee、SmartHR、MoneyForward、Sansan、Cybozu、STORES、Mercari、PayPay |
| 開発者向けプラットフォーム | Qiita、Zenn、connpass、Notion日本語版、STUDIO |
| メディア・出版 | note、WIRED.jp、BRUTUS、Casa BRUTUS、POPEYE、Pen Online、日経電子版 |
| 大企業コーポレート | Toyota、Sony、Panasonic、Canon、FUJIFILM、SHARP、任天堂、Yamaha、SUBARU |
| アパレル・小売 | UNIQLO、GU、BEAMS、UNITED ARROWS、sacai、ISSEY MIYAKE、mina perhonen |
| 伝統工芸・老舗 | 虎屋、SOU・SOU、中川政七商店、土屋鞄、Maruni木工、HASAMI、HOSOO、HARIO、能作 |
| 化粧品・ビューティ | 資生堂、POLA、ORBIS、KOSÉ、SHIRO、IPSA、Aesop、shu uemura、THREE |
| ホテル・空間 | 星野リゾート、アマン東京、TRUNK(HOTEL)、SANU、GINZA SIX、東京ミッドタウン、teamLab |
| 公共・政府 | デジタル庁、グッドデザイン賞、森美術館、21_21 DESIGN SIGHT |
| 食・飲料 | Calbee、KIRIN、SAPPORO、Suntory、伊藤園、カゴメ、HIGASHIYA、Soup Stock |
特筆すべきは、同じフォーマットでまったく異なるブランドトーンが並ぶ点だ。たとえばSaaSの freee はブルー基調のクリーンな業務UI、伝統工芸の 虎屋（とらや）は明朝体ベースの余白の効いた和のUIになる。この2つを並べると、「同じDESIGN.md形式で何が再現できるか」が一目でわかる。
design-md/freee/preview-screenshot.png
design-md/toraya/preview-screenshot.png虎屋・SOU・SOU・中川政七商店のような明朝体ベースのUIや、銀座シックス・アマン東京のような余白を活かしたラグジュアリーUIは、欧米中心の本家awesome-design-mdには存在しない方向性だ。AIに「和」のニュアンスを再現させたい場合の起点として使える。各サイトのDESIGN.mdは design-md/[サイト名]/ 配下にあり、同じディレクトリに preview.html と preview-screenshot.png が入っている。プレビューHTMLはローカルで開いても動くため、AIに参照させる前に人間が「このトークンセットで本当に違和感がないか」を視覚的に確認できる。
DESIGN.mdテンプレートの9セクション — 日本語向けに拡張された箇所
awesome-design-md-jpが採用するDESIGN.mdは、本家のフォーマットを尊重しつつ、Typography Rulesセクションを大幅に拡張した9セクション構成になっている。テンプレートは template/DESIGN.md として同梱され、各セクションを対象サービスの実際のCSS値で埋めていく。
9セクション構成"] --> B["1. Visual Theme
デザイン哲学・密度・キーワード"] A --> C["2. Color Palette
Primary/Semantic/Neutral"] A --> D["3. Typography Rules
日本語拡張の中心"] A --> E["4. Component Stylings
Button/Input/Card"] A --> F["5. Layout Principles
スペーシング/Container/Grid"] A --> G["6. Depth & Elevation
シャドウ/Elevation階層"] A --> H["7. Do's and Don'ts
禁止事項を明示"] A --> I["8. Responsive Behavior
ブレークポイント"] A --> J["9. Agent Prompt Guide
エージェント向けの例文"] D --> D1["3.1 和文フォント"] D --> D2["3.2 欧文フォント"] D --> D3["3.3 font-family指定"] D --> D4["3.4 サイズ・ウェイト階層"] D --> D5["3.5 行間・字間"] D --> D6["3.6 禁則処理・改行ルール"] D --> D7["3.7 OpenType機能"] D --> D8["3.8 縦書き（任意）"] style D fill:#fff3e0,stroke:#fb8c00 style D1 fill:#fff8e1 style D2 fill:#fff8e1 style D3 fill:#fff8e1 style D4 fill:#fff8e1 style D5 fill:#fff8e1 style D6 fill:#fff8e1 style D7 fill:#fff8e1 style D8 fill:#fff8e1
9セクションのうち Visual Theme・Color Palette・Component Stylings・Layout・Depth・Do’s and Don’ts・Responsive・Agent Prompt Guide は本家と同じ枠組みだが、3. Typography Rules に和文向けの8サブセクション（3.1〜3.8）が追加されている。ここが日本語版の核心だ。実際のDESIGN.mdでは、たとえば freee の font-family 指定は以下のように書かれている（design-md/freee/DESIGN.md より抜粋）。読者が自分のプロジェクトにそのまま真似できる、最も実用的な部分だ。
/* プロダクトUI（Vibes Design System） */
font-family: '-apple-system', BlinkMacSystemFont, 'Helvetica Neue',
'ヒラギノ角ゴ ProN', 'Hiragino Kaku Gothic ProN', Arial,
'メイリオ', Meiryo, sans-serif;
/* コーポレートサイト（本文） */
font-family: "Noto Sans JP", sans-serif;
/* 禁則・改行（Typography Rules 3.6） */
word-break: break-all;
overflow-wrap: break-word;
line-break: strict;
ここで見落とされがちな重要な点がある。READMEの原則として和文フォントのフォールバックチェーンは「和文 → 欧文 → generic」の向きで語られるが、実際の各DESIGN.mdはサイトごとに戦略が異なる。上の freee のプロダクトUIは、逆に -apple-system などの欧文システムフォントを和文より先に指定している。これは欧文（数字・英字）の表示品質を優先し、和文はOS標準（ヒラギノ／メイリオ）に任せる設計だ。一方コーポレートサイトは Noto Sans JP のWebフォントを使う。つまり「和文を先に書くのが常に正解」ではなく、プロダクトかコーポレートか、どの環境で読ませるかで順序が変わる。preview.htmlで両方の挙動を確認しながら使い分けるのが、この収録データを浅い要約以上に使いこなすコツになる。
なお、セクションヘッダーは英語のまま残し、値の説明やDo’s and Don’tsだけ日本語で書くのがawesome-design-md-jpの作法だ。AIエージェントはセクション名を手がかりに値を抽出するため、「Typography Rules」というヘッダーを翻訳すると逆に解析精度が落ちる。ヘッダーは保持し、本文だけ和文で記述する。
本家awesome-design-md との違い — 日本語版が追加した5つの観点
本家awesome-design-mdは欧米のSaaSとプロダクトを中心に55ブランド以上を集めた英語版で、すでに9万を超えるスターを獲得している。日本語UIを作る際に本家のDESIGN.mdをそのまま使うと、いくつかの致命的な欠落が顕在化する。awesome-design-md-jpは以下の5つの観点で本家を拡張した。
| 観点 | 本家awesome-design-md | awesome-design-md-jp |
|---|---|---|
| 収録サイト | 欧米55ブランド以上 | 日本のサービス378サイト（SaaS・伝統工芸まで） |
| 和文フォント | 未指定 | Noto Sans JP・游ゴシック・ヒラギノを優先度付きで列挙 |
| 行間・字間 | line-height 1.4〜1.5想定 | line-height 1.5〜2.0、letter-spacing 0.04〜0.1emを明示 |
| 禁則処理 | 言及なし | word-break・line-break・overflow-wrapを推奨セットで定義 |
| OpenType機能 | font-featureに言及あり | palt・kernを和欧混植の文脈で個別に解説 |
| 配布方法 | npx getdesign で1コマンド導入 | GitHubから直接コピー（CLI未提供） |
| スター / ライセンス | 9万超 / — | 806 / MIT |
注目すべきは、現時点でawesome-design-md-jpには本家のようなnpx getdesign 相当のCLIがない点だ。導入時は対象サイトのディレクトリをGitHubから直接コピーする必要があり、配布まわりはまだ手作業に近い。とはいえ、PRやIssueは活発でCONTRIBUTING.mdも整備されているため、追加サイトの提案やCLI化の貢献に開かれている状態だ。
本家との関係は競合ではなく補完で、README（Credits）でも本家へのリンクとリスペクトが明示されている。9セクションのフォーマットと preview.html の発想は本家由来で、そこに和文タイポグラフィを載せたのが日本語版だ。海外向けプロジェクトには本家のDESIGN.md、国内向けには日本語版、という使い分けが現実的である。
使い方 — Claude Code・Cursorに日本語DESIGN.mdを読ませる導線
awesome-design-md-jpを実プロジェクトで使うときの動線は3ステップで完結する。CLIが未提供のため、現時点ではGit経由のコピーが基本だ。
1. 対象サイトのDESIGN.mdを自プロジェクトに配置
GitHubのリポジトリから対象サイトのディレクトリを取得し、自プロジェクトのルートまたは docs/ 配下に置く。たとえばfreeeに近いトーンを再現したい場合は以下のように取り込む。
# リポジトリを浅くクローン
git clone --depth 1 https://github.com/kzhrknt/awesome-design-md-jp.git tmp-design
# freeeのDESIGN.mdをコピー
cp tmp-design/design-md/freee/DESIGN.md ./DESIGN.md
# 後片付け
rm -rf tmp-design
2. CLAUDE.md / AGENTS.md にDESIGN.mdへの参照を明記
Claude CodeはリポジトリルートのDESIGN.mdを自動的に文脈に含めるが、確実に参照させたい場合はCLAUDE.mdに以下のような一文を入れておく。
# UI Generation Rules
- UIコンポーネントを生成・修正する場合は必ず `./DESIGN.md` を参照すること。
- Typography Rules 3.5 の line-height / letter-spacing を本文に適用する。
- 3.6 の禁則処理（word-break / line-break / overflow-wrap）を必ず設定する。
CursorやWindsurfではプロジェクト固有のルールファイル（.cursorrules、AGENTS.md等）に同等の指示を書く。AIエージェントごとに参照される設定ファイルが違う点だけ留意すれば、運用ロジックは共通だ。
3. 値はプロジェクト固有に置き換える
awesome-design-md-jpのDESIGN.mdはあくまで参考実装で、各社の公式デザインシステムではない。ブランドカラー・有償フォント名・ロゴはそのまま流用せず、自プロジェクトの値に置き換えるのが前提だ。Primaryカラーやfont-familyの具体値、商標を含むフォント名（”游ゴシック体 Pr6N”などのライセンスが絡む表記）は、自社のブランドガイドラインに沿って書き換える。テンプレートとして使うべきは「セクションの粒度と項目構成」であって、値そのものではない。
各サイトのディレクトリには
preview.html が同梱されている。AIに渡す前に人間が開いて「本当にこのトークンセットで違和感がないか」を視覚的に確認すると、AIが生成したUIの違和感が大幅に減る。全サイトを横断して見たいときは Gallery（gallery.html）で一覧プレビューできる。
実務での落とし穴と運用 — 公式デザインシステムではない点を踏まえて
awesome-design-md-jpは魅力的なリソースだが、実プロジェクトに投入するうえで把握しておくべき制約がある。誇張せずに整理すると、主な落とし穴とその対処は次の通りだ。
| 落とし穴 | 実態 | 対処 |
|---|---|---|
| 公式デザインシステムではない | 公開CSSをブラウザのcomputed styleから抽出した参考実装（READMEのDisclaimerに明記） | 商用で「◯◯公式」と扱わない。ロゴ・商標は各社ガイドラインを尊重 |
| 有償フォントのライセンス | 游ゴシック・ヒラギノ・モリサワ系はライセンスが絡む | フォールバックに Noto Sans JP など無償フォントを必ず含める |
| AIが値を鵜呑みにする | 具体的なpx値を忠実に再現し、意図がずれても固まる | Visual Theme と Do’s and Don’ts を必ず埋める |
| 配布まわりが未整備 | npx getdesign 相当のCLIがない |
社内テンプレートリポにフォークして正本を1つに揃える |
| 内製への移行 | 参考実装のまま長期運用すると責任所在が曖昧 | 固まってきたら自社ブランド値で内製DESIGN.mdに書き換える |
とくに重要なのは、READMEのDisclaimerが明示する通り、378サイトのDESIGN.mdが各サービスの公開CSSをブラウザのcomputed styleから抽出した「参考実装」であって、各社が公式に提供しているものではない、という点だ。商用案件で「Toyota公式のデザインシステム」と扱うことはできず、ブランドロゴやカスタム有償フォントの扱いには別途各社のガイドラインを尊重する必要がある。
DESIGN.md単体ではUIの「外観」しか定義できない点も押さえておきたい。コンポーネント命名・ディレクトリ配置・テスト戦略といったコード規約はCLAUDE.md / AGENTS.mdなどのAIコンテキストファイルに書き分けるのが原則で、3層のMarkdownが揃って初めてAIエージェントは「ビルドが通り、規約を守り、ブランドらしい」UIコードを安定して出せる。awesome-design-md-jpはこの3層のうち、最も整備が遅れていた日本語UI領域を埋める役割を担っている。
最後に何を代替できるのかを整理する。awesome-design-md-jpが代替するのは、「AIに日本語UIを作らせるたびに、フォント・行間・禁則を口頭で指定し直す手間」であり、また「和文タイポグラフィの内製DESIGN.mdをゼロから書き起こす初期コスト」だ。逆に、公式デザインシステムそのものや、有償フォントのライセンス、ブランド商標の管理までは代替しない。使い方は明快で、対象サイトのDESIGN.mdをコピーして自プロジェクトのテンプレートにし、CLAUDE.mdまたはAGENTS.mdから参照させ、preview.htmlで人間が事前確認してから、ブランド固有の値を自社の値に書き換える。データやコードを大量に書き換える必要はなく、リポジトリにテキストファイルを1つ置くだけで生成結果が変わる——これがDESIGN.mdというフォーマットの一番強い特徴であり、awesome-design-md-jpはその効果を日本語UIの領域で初めて378サイト規模に体系化したプロジェクトである。日本語UIのプロジェクトを抱えているなら、まず1サイト分のDESIGN.mdをローカルに引っ張ってきて、preview.htmlを開くところから始めると感覚がつかみやすい。
参照ソース
- kzhrknt/awesome-design-md-jp（GitHub） — 本記事で扱った日本語版DESIGN.mdリポジトリ。READMEに収録サイト一覧（378サイト）とTypography Rules拡張の方針が記載されている。2026年4月6日公開、806スター・MITライセンス（2026年7月時点）。
- awesome-design-md-jp Gallery — 全378サイトのDESIGN.mdをデザイントークンと共に一覧できるGitHub Pages。各カードは preview.html を埋め込んでいる。
- DESIGN.md公式ドキュメント（Google Stitch） — DESIGN.mdフォーマットの一次ソース。9セクション構成とフロントマターの定義が記述されている。
- google-labs-code/design.md（GitHub） — Google Labsが公開する公式DESIGN.md仕様レポジトリ。
- VoltAgent/awesome-design-md（GitHub） — 本家英語版awesome-design-md。欧米55ブランド以上のDESIGN.mdとnpx getdesign CLIを提供、9万スター超。
