この記事では日本語UIに特化したDESIGN.mdリソースを解説します。デザインシステム・UI生成全般は デザインシステムとは？仕組み・構成要素・有名事例をエンジニア向けに完全解説 をご覧ください。

awesome-design-md-jp とは — 日本語UIのDESIGN.mdを182サイト収録した日本語版OSS

awesome-design-md-jpは、Google Stitchが提唱した「DESIGN.md」フォーマットを日本語タイポグラフィ向けに拡張した日本語版OSSである。GitHubでkzhrknt氏が2026年4月6日に公開してから約1ヶ月半で670スター近くまで伸びており、現在は182サイトのDESIGN.mdを収録している。

awesome-design-md-jp カバー

公開からの伸びは、海外で先に話題になった本家awesome-design-md（VoltAgent）の文脈に乗っている。本家がVercel、Stripe、Linear、Notionなど欧米55ブランドを集めた一方で、日本語UIの仕様は完全に欠落していた。awesome-design-md-jpはここを埋めるプロジェクトで、Apple Japan・MUJI・freee・mercari・任天堂・サイバーエージェント・虎屋・銀座シックスといった国内サービスのDESIGN.mdを揃えている。

DESIGN.mdの基礎は別記事に
DESIGN.mdの書き方・最小テンプレート・フロントマターの構造は DESIGN.md入門 にまとめている。本記事は日本語タイポグラフィ拡張に絞って解説するので、未読の場合は先に入門記事を確認すると流れがつかみやすい。

DESIGN.mdは、コーディングエージェントが「色・フォント・余白・コンポーネント・Do’s and Don’ts」を機械的に読み取れる形式で記述したマークダウン仕様書である。AGENTS.md（プロジェクトの作り方）と並べてリポジトリのルートに置き、AIエージェントがUIを生成するたびに参照させることで、ブランドトーンの一貫性を保てる。awesome-design-md-jpはこのフォーマットの日本語タイポグラフィ拡張を提案する位置づけだ。

日本語タイポグラフィがAIのUI生成で壊れる理由 — DESIGN.mdに何を書くべきか

AIエージェントに「日本語のダッシュボードを作って」と頼むと、和文フォントが抜け落ち、行間がつまり、句読点が行頭に来るUIが出てくることが多い。これは欧文ベースの学習データと欧文向けのCSSパターンが優先されるためで、日本語UIに必要な仕様が明示されない限り改善は望めない。

awesome-design-md-jpがREADMEで指摘している「日本語UIで欠落しがちな仕様」は以下の6点である。

AIが日本語UIを壊す典型パターン
  • 和文フォントのフォールバックチェーンが指定されない（システムデフォルトで描画）。
  • 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をフォーマットとして整備した点が中心的な貢献だ。

たとえば本文の行間と字間は、READMEで以下のように推奨されている。

観点 欧文の標準 日本語の推奨 理由
本文 line-height 1.4〜1.5 1.7〜2.0 漢字の上下バランスを取り、視線移動を楽にする
本文 letter-spacing 0 0.04〜0.1em 全角文字の詰まりを緩和し、可読性を上げる
見出し letter-spacing -0.02em〜0 0〜0.05em 詰めすぎないことで漢字の重みを保つ
禁則処理 不要 strict 句読点・括弧の行頭・行末ルールを守る
OpenType palt 用途次第 見出しに有効 仮名・約物のプロポーショナル詰め

数値そのものはサイトによって異なるが、「項目として書き残す」ことが重要である。AIは項目が存在しない領域には踏み込まないことが多く、Typography Rulesに6行加えるだけで生成結果が明確に変わる。

awesome-design-md-jp の収録サイト — SaaSから伝統工芸まで182サイトのDESIGN.md

awesome-design-md-jpの強みは収録範囲の広さである。SaaSと一般メディア中心の本家awesome-design-mdに対し、日本語版はビジネスSaaSからファッション、伝統工芸、自動車、化粧品、ホテルまで幅広く182サイトのDESIGN.mdを集めている。GitHub Pages上の Galleryページ で全サイトのデザイントークンを可視化できる。

DESIGN.mdギャラリー

カテゴリ別にどんなサイトが入っているかを整理すると、参考になる組み合わせが見えてくる。

カテゴリ 収録サイト例
ビジネス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

特筆すべきは伝統工芸や老舗ブランドのDESIGN.mdが揃っている点である。虎屋・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セクション構成になっている。

flowchart TB A["DESIGN.md
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

セクション全体は本家フォーマットと同じだが、3. Typography Rulesに以下の8つのサブセクションが追加されている。

## 3. Typography Rules

### 3.1 和文フォント
- ゴシック体: Noto Sans JP, 游ゴシック, ヒラギノ角ゴ ProN
- 明朝体: Noto Serif JP, 游明朝, ヒラギノ明朝 ProN

### 3.2 欧文フォント
- サンセリフ: Helvetica Neue, Arial
- セリフ: Georgia
- 等幅: SFMono-Regular, Consolas, Menlo

### 3.3 font-family指定
font-family: "和文フォント", "欧文フォント", sans-serif;

### 3.4 文字サイズ・ウェイト階層
（Role / Size / Weight / Line Height / Letter Spacing / 備考 のテーブル）

### 3.5 行間・字間
- 本文 line-height: 1.7〜2.0
- 本文 letter-spacing: 0.04〜0.1em

### 3.6 禁則処理・改行ルール
word-break: break-all;
overflow-wrap: break-word;
line-break: strict;

### 3.7 OpenType機能
font-feature-settings: "palt" 1;

### 3.8 縦書き（該当する場合）
writing-mode: vertical-rl;
text-orientation: mixed;

特に3.3のfont-family指定は、和文フォントを先に置くか欧文を先に置くかでレンダリング結果が変わる重要な箇所だ。READMEでは「和文を先に書く」が基本方針として推奨されているが、欧文を綺麗に見せたいヒーロー部分などでは欧文を先に置く戦術もあり、サブディレクトリのpreview.htmlで両方の挙動を確認しながら使い分ける必要がある。

セクションヘッダーは英語のまま残し、値の説明やDo’s and Don’tsだけ日本語で書く方針も興味深い。AIエージェントはセクション名を手がかりに値を抽出するため、ヘッダーを翻訳すると逆に解析精度が落ちる。日本語版DESIGN.mdでも「Typography Rules」というヘッダーは保持し、本文だけ和文で記述するのがawesome-design-md-jpの作法である。

awesome-design-md（本家）との違い — 日本語版が追加した5つの観点

本家awesome-design-mdは欧米のSaaSとプロダクトを中心に55ブランドを集めた英語版で、すでに数万スターを獲得している。日本語UIを作る際に本家のDESIGN.mdをそのまま使うと、いくつかの致命的な欠落が顕在化する。awesome-design-md-jpは以下の5つの観点で本家を拡張した。

観点 本家awesome-design-md awesome-design-md-jp
収録サイト 欧米55ブランド中心 日本のサービス182サイト（SaaS・伝統工芸まで）
和文フォント 未指定 Noto Sans JP・游ゴシック・ヒラギノを優先度付きで列挙
行間・字間 line-height 1.4〜1.5想定 line-height 1.7〜2.0、letter-spacing 0.04〜0.1emを明示
禁則処理 言及なし word-break・line-break・overflow-wrapを推奨セットで定義
OpenType機能 font-featureに言及あり palt・kernを和欧混植の文脈で個別に解説
配布方法 npx getdesign で1コマンド導入 GitHubから直接コピー（CLI未提供）

注目すべきは、現時点でawesome-design-md-jpには本家のようなnpx getdesign 相当のCLIがない点だ。導入時は対象サイトのディレクトリをGitHubから直接コピーする必要があり、配布まわりはまだ手作業に近い。とはいえ、PRやIssueは活発でCONTRIBUTING.mdも整備されているため、追加サイトの提案やCLI化の貢献に開かれている状態だ。

本家との関係は競合ではなく補完で、READMEでも本家へのリンクとリスペクトが明示されている。海外向けプロジェクトには本家の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で先に挙動を見る
各サイトのディレクトリには preview.html が同梱されている。AIに渡す前に人間が開いて「本当にこのトークンセットで違和感がないか」を視覚的に確認すると、AIが生成したUIの違和感が大幅に減る。Gallery（gallery.html）で一覧プレビューも可能だ。

実務での落とし穴と運用 — 公式デザインシステムではない点を踏まえて

awesome-design-md-jpは魅力的なリソースだが、実プロジェクトに投入するうえで把握しておくべき制約と落とし穴がある。誇張せずに整理する。

公式デザインシステムではない

182サイトのDESIGN.mdは、公開されているCSSやデザインパターンからリバースエンジニアリングして生成された「参考実装」であり、各社が公式に提供しているものではない。READMEにも「インスピレーション」の位置づけが明示されている。商用案件で「Toyota公式のデザインシステム」と扱うことはできず、ブランドロゴやカスタム有償フォントの扱いには別途各社のガイドラインを尊重する必要がある。

有償フォントは代替フォントへの差し替えが必要

游ゴシック・ヒラギノ・モリサワ系のフォントはライセンスが絡む。font-family にそのまま記載してもユーザー環境にインストールされていなければフォールバックされ、開発者のローカル環境とは違う見た目になる。Webフォントを使う場合はライセンスを確認し、フォールバックチェーンに「Noto Sans JP」のような無償フォントを必ず含めるのが安全だ。

AIが値を「鵜呑み」にしすぎる懸念

DESIGN.mdに具体的なpx値を書くと、AIはそれを忠実に再現する。これは強みでもあるが、デザインの意図（「行間を広めにとる」「カードの影は弱く」など）が伝わらず、想定外のサイズで全要素が固まる事故が起きやすい。awesome-design-md-jpのテンプレートが Visual Theme（雰囲気）と Do’s and Don’ts（禁止事項）を厳密に分けているのはこの問題への対処で、Visual Themeセクションを軽視せず必ず埋めるのが運用のコツだ。

配布まわりの整備はこれから

本家awesome-design-mdが npx getdesign@latest add stripe のような1コマンドで導入できるのに対し、awesome-design-md-jpは現時点でCLIを提供していない。GitHubから手でコピーする運用は、社内のメンバーが増えると揃え方がブレやすい。チームで使う場合は、社内のテンプレートリポジトリにDESIGN.mdを取り込んだ状態でフォークし、そこを正本にする運用が現実的だ。

内製DESIGN.mdへの移行を前提に使う

awesome-design-md-jpの最大の用途は「初期のたたき台」である。プロジェクトが固まってきたら、自社のブランドガイドライン・カラートークン・フォント仕様を反映した内製DESIGN.mdに書き換え、awesome-design-md-jpはあくまで構造の参考として残す。AIに対して「これに従え」と書くファイルは、最終的には自社が責任を持って管理するものだ。

Claude Skills / AGENTS.md との組み合わせで威力が出る

DESIGN.md単体ではUIの「外観」しか定義できない。コンポーネント命名・ディレクトリ配置・テスト戦略といったコード規約はCLAUDE.md / AGENTS.mdなどのAIコンテキストファイルに書き分けるのが原則で、3層のMarkdownが揃って初めてAIエージェントは「ビルドが通り、規約を守り、ブランドらしい」UIコードを安定して出せる。awesome-design-md-jpはこの3層のうち、最も整備が遅れていた日本語UI領域を埋める役割を担っている。

まとめ — 日本語UIのDESIGN.mdが「揃った」状態をどう活かすか

awesome-design-md-jpは、日本語UIのDESIGN.md整備というこれまで放置されていた領域に、182サイト分の参考実装を一気に積み上げた意欲的なプロジェクトだ。海外発のDESIGN.mdムーブメントが「日本語UIをAIエージェントが正しく作れない」というギャップを残していた問題に対し、和文タイポグラフィの仕様を真正面から扱う数少ないリソースになっている。

実務での使い方は、対象サイトのDESIGN.mdをコピーして自プロジェクトのテンプレートにし、CLAUDE.mdまたはAGENTS.mdから参照させる。Visual Themeと Do’s and Don’ts を埋め、ブランド固有のカラー・フォント・余白を自社の値に書き換える。preview.htmlで人間が事前確認し、AIに渡してから「期待通りの和文UIが出るか」を観察する。1サイト試すだけで、AIの日本語UI生成精度が体感で明確に変わる。

データやコードを大量に書き換える必要はなく、リポジトリにテキストファイルを1つ置くだけで生成結果が変わる点が、DESIGN.mdというフォーマットの一番強い特徴である。awesome-design-md-jpはその効果を日本語UIの領域で初めて体系化したもので、AIエージェントを使ったUI開発を進めるチームにとっては「とりあえず触ってみる」コストが極めて低い。日本語UIのプロジェクトを抱えているなら、まず1サイト分のDESIGN.mdをローカルに引っ張ってきて、preview.htmlを開くところから始めると感覚がつかみやすい。

参照ソース