DESIGN.mdで日本語UIの崩れを防ぐ――jp-ui-contractsの使い方

AIが作る日本語UIはなぜ毎回「惜しい」のか

色や余白は出る。でも日本語が崩れる

これ、わかる人多いと思う。

Claude CodeやCursorでWebのUIを生成すると、配色やレイアウトはけっこういい感じに出てくる。

「お、今回はちゃんとできてる！」と思って日本語テキストを流し込んだ瞬間、「あれ？」ってなる。

見出しと本文の行間がチグハグだったり、長い日本語テキストが変なところで折り返されたり、フォームのラベルだけ妙にスカスカだったり。

あの「惜しい！」感、地味にストレスたまるんだよね。

画像生成AIが日本語テキストをうまく描けないのと似た構造の問題が、UIの世界でも起きている。

でも、これはAIの能力不足じゃない。

英語圏のデフォルト設定がそのまま適用されているだけなんだよね。

原因はAIの精度じゃない――「設計契約」がないだけ

画像生成AIでプロンプトを書くとき、スタイルや色味を細かく指定するほど出力がブレなくなる。

「水彩風、柔らかい色調、白背景」みたいに言語化すればするほど、出力が安定してくる。

UIの生成も同じで、「日本語のときはこうしてね」という仕様を事前に渡しておけば、AIはちゃんとそのとおりに作ってくれる。

問題は、その「仕様書」がプロジェクトに存在しないことだった。

で、その仕様書として登場したのがDESIGN.mdというフォーマットだ。

これが知れてよかった、というより「なんでもっと早く知らなかったんだ」という発見だった。

次のセクションで詳しく見ていく。

DESIGN.mdとは何か――AIエージェントへのデザイン仕様書

Google Stitchが提唱したフォーマット

DESIGN.mdは、Googleのデザインツール「Stitch」が提唱したMarkdownベースのデザイン仕様書フォーマットだ。

プロジェクトのルートディレクトリに DESIGN.md というファイルを置くことで、AIエージェントが「見た目と雰囲気」の指針として参照できるようになる。

記述する内容はこんな感じ。

• カラーパレット（プライマリ、セカンダリ、背景、テキスト色）
• タイポグラフィ（フォントファミリー、サイズスケール、行間）
• スペーシング（余白の基本単位）
• コンポーネントのスタイル指針
• やってはいけないこと（Don'ts）

ここ、ちょっと注目してほしいんだけど。

CLAUDE.md / AGENTS.mdが「実装の方法」を伝えるのに対して、DESIGN.mdは「見た目の方針」を伝える。

つまり、実装とデザインを別々のファイルで管理できる。

Claude Codeなら CLAUDE.md、Cursorなら .cursor/rules/ が実装指示ファイルにあたる。

これらの実装指示ファイルとDESIGN.mdが並列でプロジェクトルートに置かれることで、AIエージェントは実装とデザインの両方を理解して動ける。

プロンプトとの違い（一度書けば毎回指示不要）

これが地味にすごい話なんだよね。

画像生成AIのプロンプトは毎回書く必要がある。

「水彩風、柔らかい色調、白背景」みたいな指示を、生成するたびに入力しなきゃいけない。

DESIGN.mdは違う。

一度書いてリポジトリに置き、AIに読み込ませる設定をしておけば、そのプロジェクトで作業するたびに設計契約として機能し続ける。

「毎回のプロンプト芸」から「一度きりの設計契約」に変わるわけだ。

これは画像生成AIでいうところの「スタイルプリセット」に近い発想で、プロンプトを書く感覚でUIの設計方針も定義できる。

つまり、次にUIを追加するとき、同じ指示を書き直す必要が一切なくなる。

Claude Code / Cursorに読み込ませる設定

仕組みはシンプルだ。

Claude Codeは CLAUDE.md をプロジェクトルートから自動で読み込む。

そこに「DESIGN.mdを参照してUIを生成してほしい」という一行を書いておくだけで、毎回のプロンプトなしにDESIGN.mdが設計の基準になる。

# CLAUDE.md（抜粋）

UIコンポーネントを生成・修正する際は、必ず DESIGN.md を参照してスタイルを決定すること。

Cursorも .cursor/rules/ に同様のルールを追加することで対応できる。

追加プラグインは不要で、設定ファイルに一行加えるだけだ。

「え、それだけ？」って思うかもしれないけど、本当にそれだけでいい。

一度この設定を書いておけば、プロジェクト内でDESIGN.mdが永続的に参照され続ける。

海外ではVoltAgentの「awesome-design-md」というリポジトリに55以上のサービスのDESIGN.mdが収録されていて、参考にできる実例が豊富に揃っている。

GitHub - VoltAgent/awesome-design-md: A collection of DESIGN.md files inspired by popular brand design systems. Drop one into your project and let coding agents generate a matching UI.

A collection of DESIGN.md files inspired by popular brand design systems. Drop one into your project and let coding agents generate a matching UI. - VoltAgent/awesome-design-md

github.com

ただし、ここに収録されているのは基本的に英語圏のサービスだ。

日本語UIには日本語特有の設計が必要で、そのままでは使えない部分がある。

ここからが本題で、日本語に特化したツールが登場している。

jp-ui-contractsとawesome-design-md-jpの違い

日本語UIのためのDESIGN.md関連プロジェクトとして、2つのOSSが登場している。

「そんなものがあったのか！」と思ったのが正直なところで、これを知ってから使い方がガラッと変わった。

jp-ui-contracts――日本語UI向けの「設計契約キット」

jp-ui-contractsは、hirokajiさんがnote記事「DESIGN.mdを日本語UIで本当に使える形へ」で紹介したOSSプロジェクトだ。

DESIGN.mdを日本語UIで本当に使える形へ｜hirokaji

jp-ui-contracts を公開しました AIでUIを作る流れが強くなるほど、逆に目立ってくるものがあります。 それは、日本語の詰めの甘さです。 色はそれらしく見える。 余白もそれっぽく整う。 カードやボタンの形も、かなり上手に出てくる。 でも最後に崩れるのが、日本語です。 見出しの折り返しが苦しい。 本文の行間が浅い。 英語のサービス名が混ざると急に浮く。 フォームだけ窮屈になる。 表の密度が本文のルールを引きずって読みにくくなる。 この違和感は、単に「AIの精度が足りない」から起きているわけではありません。 もっと手前の問題です。 日本語UIの設計契約が、まだ十

note.com

「見本帳」ではなく「設計契約キット」という位置づけがポイント。

リポジトリの構成はこうなっている。

テンプレートが5種類あるのが実用的で、「自分のプロダクトはSaaSだからsaasプロファイルを使おう」みたいに選べる。

baseが最小共通の契約で、そこに文脈別の上乗せをする構造だ。

単なるテンプレートにとどまらず、書いた後に検証できるvalidatorsまで含んでいる。

ここまで揃っているOSSは珍しい。

awesome-design-md-jp――24の日本語サービスの実例集

もうひとつがawesome-design-md-jpで、こちらは「実例集」としての役割を持つ。

GitHub - kzhrknt/awesome-design-md-jp: 日本語UIをAIエージェントに正しくつくらせるためのDESIGN.md集。Japanese DESIGN.md collection for AI agents — extending Google Stitch format with CJK typography.

日本語UIをAIエージェントに正しくつくらせるためのDESIGN.md集。Japanese DESIGN.md collection for AI agents — extending Google Stitch format with CJK typography. - kzhrknt/awesome-design-md-jp

github.com

Apple Japan、SmartHR、freee、note、メルカリ、LINE、Cookpadなど、24の日本語Webサービスについて、Google Stitchフォーマットを日本語CJKタイポグラフィ向けに拡張したDESIGN.mdを収録している。

ギャラリーページもあって、各サービスのデザイン仕様を一覧で確認できる。

自分のサービスに近いものを探して、そこから自分用のDESIGN.mdを作り始められるのが便利だ。

「メルカリに近いサービスだな」と思ったらメルカリのDESIGN.mdを参考に始められる。

ゼロから書き起こすより圧倒的に速い。

使い分けの目安

2つのリポジトリは補完関係にある。

まずawesome-design-md-jpで自分のサービスに近い実例を探し、jp-ui-contractsのテンプレートをベースに自分用のDESIGN.mdを書く。

この組み合わせが一番効率がいい。

で、「そもそも日本語UIのどこが壊れやすいの？」という部分を次のセクションで具体的に見ていく。

日本語UIがDESIGN.mdで変わる具体的なポイント

hirokajiさんの記事で解説されている「日本語UIで壊れやすい場所」が非常にわかりやすかったので、ここで紹介したい。

画像生成AIでもネガティブプロンプトで「やってほしくないこと」を明示するけど、DESIGN.mdでも「日本語UIでやりがちな間違い」を契約に書いておくことが重要だ。

ここを読んで「あ、これやってた」と思った箇所がいくつかあった。

本文と見出しを同じルールで扱わない

日本語UIで最もよくある問題がこれ。

本文は「読むための器」、見出しは「導線」。

役割が違うのに同じline-heightやletter-spacingを使うと、どちらかが必ず苦しくなる。

DESIGN.mdには本文と見出しそれぞれの行間・字間を明確に分けて記述する。

## Typography

### Body Text
- font-size: 16px
- line-height: 1.8
- letter-spacing: 0

### Headings
- line-height: 1.4
- letter-spacing: 0.02em

日本語本文に安易に字間を足さない

「なんか詰まって見える」からといって本文にletter-spacingを足すと、かえって読みにくくなる。

hirokajiさんの推奨では、本文の不快感の原因はたいてい字間不足ではなく、行間不足や折り返しの粗さだとしている。

これは知らないとやりがちなんだよね。

DESIGN.mdには「本文のletter-spacingは0を基本とする」と明記しておくと、AIが余計な調整を入れなくなる。

break-allで全部を解決しようとしない

長いURLがはみ出すから word-break: break-all を全体にかける、というのはよくある力技だけど、これをやると日本語の禁則処理まで壊れてしまう。

正しくは、URL対策と禁則処理と和欧混植の調整を別々に考えること。

jp-ui-contractsの recipes/ にはこの3つを分離して扱うCSSレシピが用意されている。

• ja-text.css -- 日本語本文の基本設定
• mixed-script.css -- 和欧混植の調整
• headings.css -- 見出し専用のタイポグラフィ
• forms.css -- フォーム要素専用の設定

「自分で考えなくていい」という点が本当にありがたい。

表とフォームが本文ルールを引きずらないようにする

本文用に設定した line-height: 1.8 をそのままテーブルやフォームに継承させると、セルやラベルがスカスカになって使いにくくなる。

DESIGN.mdにはコンテキスト別のタイポグラフィルールを書く。

## Context-Specific Typography

### Tables
- line-height: 1.4
- font-size: 14px

### Form Labels
- line-height: 1.4
- font-size: 14px

### Form Inputs
- line-height: 1.5
- padding: 8px 12px

こうやって「本文」「見出し」「表」「フォーム」の4つのコンテキストでルールを分けておくと、AIは場面に応じて適切なスタイルを適用してくれる。

「なんでここだけスカスカなんだ」という謎の苦しさが一気に消える。

実際にどう始めればいいのかを、次のセクションで3ステップにまとめた。

3ステップで始めるDESIGN.md日本語対応

ここ、ハードルが思ってたより全然低い。

テンプレートをコピーして自分のプロダクト情報を埋める、それだけだ。

ステップ1: テンプレートを選ぶ

jp-ui-contractsの templates/ から、自分のプロダクトに合ったプロファイルを選ぶ。

迷ったらまず base を使って、必要に応じて他のプロファイルの記述を足していけばいい。

awesome-design-md-jpのギャラリーで自分のサービスに近い実例を見つけたら、そのDESIGN.mdも参考にする。

ステップ2: 自分のプロダクトに合わせて埋める

テンプレートをコピーしたら、自分のプロダクトの情報で埋めていく。

最低限これだけは設定しておきたいポイントがある。

• フォントファミリー: 日本語フォントのフォールバックチェーンを明示的に書く。"Noto Sans JP", "Hiragino Sans", sans-serif のように和文→欧文→genericの順で指定するのが基本
• 本文の行間: 日本語は 1.7 以上を推奨（英語の 1.5 だと詰まって見える）。記事メディアなら 1.85 くらいまで広げてもいい
• 見出しの行間: 本文とは別に 1.3〜1.5 を指定。本文と同じ行間だと見出しが間延びする
• 本文の字間: 0 を基本とする（足さない）。見出しやラベルには 0.02em 程度なら効くことがある
• 改行ルール: overflow-wrap: anywhere と word-break: normal の組み合わせ。break-all は使わない
• Don'ts: やってほしくないことを明記する

Don'tsの記述は画像生成AIのネガティブプロンプトと同じ発想で、「こうしないで」を先に言語化しておくのがコツだ。

## Don'ts
- Do not use `word-break: break-all` for Japanese text（日本語にbreak-allを使わない）
- Do not add letter-spacing to Japanese body text（本文に字間を足さない）
- Do not use the same line-height for body text and headings（本文と見出しで同じ行間にしない）
- Do not inherit body typography rules to tables and forms（表やフォームに本文ルールを継承しない）

セクション見出しは英語で書く（AIの可読性が上がるため）けど、括弧内に日本語で補足しておくと人間のレビューもしやすくなる。

ステップ3: AIに読み込ませて生成→レビュー→契約修正のループ

DESIGN.mdをプロジェクトルートに置いたら、あとはAIにUIを生成させてみる。

hirokajiさんが推奨しているワークフローはこうだ。

1. DESIGN.mdを書く
2. AIにUIを生成させる
3. プレビューを目視で確認する
4. jp-ui-contractsのvalidator（review-checklist.md）で差分を記録する
5. DESIGN.mdの契約を修正する
6. 再度生成する

契約 → 生成 → 目視 → 契約修正のループを速く回すのがポイント。

これも画像生成AIのワークフローと似ている。

プロンプトを書いて、出力を見て、プロンプトを修正して、再生成する。

違うのは、DESIGN.mdはリポジトリに残る「資産」になること。

次にUIを追加するとき、同じ指示を書き直す必要がない。

まとめ――毎回のプロンプト芸から設計資産へ

AIが作る日本語UIの崩れは、AIの能力不足ではなく「設計契約の不在」が原因だった。

これ、わかってしまえばシンプルな話なんだよね。

DESIGN.mdというフォーマットがその解決策として登場し、さらに日本語特有の問題に対応するためにjp-ui-contractsとawesome-design-md-jpという2つのOSSが生まれている。

やるべきことはシンプルだ。

1. jp-ui-contractsからテンプレートを選ぶ
2. awesome-design-md-jpの実例を参考にしながら自分用に埋める
3. プロジェクトルートに置いてAIに読み込ませる

毎回「日本語フォントはこれで、行間はこれで、禁則処理はこうで...」と指示し続ける時代は終わった。

プロンプトを書く感覚でDESIGN.mdを一度書けば、あとはAIが設計契約に従って一貫したUIを作ってくれる。

センスじゃない、言語化だ。

画像もUIも、言語化の精度がそのまま出力の品質になる。

DESIGN.mdはその言語化を「使い捨てのプロンプト」から「再利用可能な設計資産」に変えるツールだった。

まずbaseテンプレートをコピーして、自分のプロダクトのフォントと行間だけ埋めてみてほしい。

それだけで、次にAIが作るUIは「惜しい」じゃなくなるはずだ。