jp-ui-contracts

キーワードやクリエイターで検索

34 メニュー投稿

見出し画像 DESIGN.mdを日本語UIで本当に使える形へ

500 hirokaji hirokaji 2026年4月11日 22:48 jp-ui-contracts を公開しました AIでUIを作る流れが強くなるほど、逆に目立ってくるものがあります。

それは、日本語の詰めの甘さです。

色はそれらしく見える。余白もそれっぽく整う。カードやボタンの形も、かなり上手に出てくる。

でも最後に崩れるのが、日本語です。

見出しの折り返しが苦しい。本文の行間が浅い。英語のサービス名が混ざると急に浮く。フォームだけ窮屈になる。表の密度が本文のルールを引きずって読みにくくなる。

この違和感は、単に「AIの精度が足りない」から起きているわけではありません。

もっと手前の問題です。日本語UIの設計契約が、まだ十分に書かれていない。

そこで作ったのが、jp-ui-contracts です。

また、以下の記事が “DESIGN.md とは何か” を定義する総論で、今回の記事は “それを日本語UIでどう実装資産にするか” を示す各論です。

目次 jp-ui-contracts を公開しましたこれは何のrepoかなぜ、わざわざ作ったのか日本語UIで本当に壊れやすい場所本文と見出しを同じ理屈で扱ってしまうこと日本語本文に安易に字間を足してしまうこと break-all で全部を解決しようとすること表とフォームが本文ルールを引きずることだから、収集だけでは足りない jp-ui-contracts に入っているもの

すべて表示これは何のrepoか画像見本帳ではなく、契約として置く。ここが発想の転換点です。 jp-ui-contracts は、日本語UI向けの DESIGN.md を書き、見直し、運用するためのrepoです。

ここでやりたかったのは、「海外の DESIGN.md を日本語に翻訳すること」ではありません。

また、「有名サービスの見た目を集めること」でもありません。目指したのは、もっと実務寄りのものです。

AIが読むためのデザイン仕様を、日本語UIで壊れにくい形にすること。

つまりこれは、見本帳ではなく、日本語UIの設計契約キットです。

なぜ、わざわざ作ったのか DESIGN.md という考え方自体は、とても筋がいいです。

見た目の方針を毎回プロンプトで説明するのではなく、プロジェクト側に固定資産として置く。その発想は、これからますます重要になると思っています。

ただ、そのまま使うと、日本語UIでは足りない部分が多い。

問題は、見た目の方向性が抽象的すぎることではありません。むしろ逆です。日本語で本当に効く細部が、契約に落ちていない。

たとえば、こんな論点です。

和文フォントを何にするか。欧文フォントとどう混ぜるか。本文の line-height をどこに置くか。見出しと本文で、どこまで字間を分けるか。和欧混植のとき、どの崩れを許容しないか。長いURLや英単語が入ったとき、どう折り返すか。表やフォームを本文ルールからどう分離するか。

こういう場所が曖昧だと、AIはそれっぽいUIは作れても、読むと苦しい画面を普通に出してきます。そして、この問題は、プロンプトの工夫だけでは解決しません。

毎回「もう少し読みやすく」「日本語っぽく」と言い換えるより、最初からこのプロジェクトでは何を守るかを契約として書いておいた方が強い。

そのためのrepoです。

日本語UIで本当に壊れやすい場所画像最後に崩れるのは、色よりも日本語の詰めです。日本語UIは、色や角丸より前に、文字組みの層で差が出ます。ここを雑に扱うと、全体の完成度が一段落ちます。特に壊れやすいのは、次のあたりです。

本文と見出しを同じ理屈で扱ってしまうこと本文は読むための器です。見出しは導線です。

同じ line-height、同じ letter-spacing の感覚で設計すると、どちらかが苦しくなります。

本文は呼吸が必要です。見出しは強さとまとまりが必要です。ここを分けないまま設計すると、本文が詰まるか、見出しが間延びします。

日本語本文に安易に字間を足してしまうこと見出しやラベルでは、少し効くことがあります。でも本文では、字間を足せば必ず読みやすくなるわけではありません。

むしろ、本文の苦しさは字間不足ではなく、行間不足や折り返し設計の粗さから来ていることが多い。

本文の不快感を tracking でごまかし始めると、だいたい別の場所が崩れます。

break-all で全部を解決しようとすること長いURLや英単語がはみ出す。その瞬間に word-break: break-all を全体へ入れたくなる。

でもこれは、かなり危ない近道です。

一部の overflow は防げても、日本語本文や見出しの自然な読みを壊しやすい。

URL対策と、日本語の禁則寄りの扱いと、 mixed-script の見出し調整は、本来は別々に考えるべきです。

表とフォームが本文ルールを引きずること記事本文で気持ちよく読める line-height は、表やフォームにはそのまま使えません。

逆に、表に合わせた詰め方を本文へ持ち込むと、長文が一気に読みにくくなります。

つまり、日本語UIの品質は、単に「文字を大きくする」「余白を増やす」ではなく、役割ごとの契約分離で決まります。

だから、収集だけでは足りないもちろん、既存の優れたUIを観察すること自体は重要です。

どのサービスがどんなフォントを使っているか。本文と見出しのリズムをどう分けているか。情報密度をどうさばいているか。

そうした観察から学べることは多い。でも、それだけでは足りません。

なぜなら、チームやプロダクトが本当に必要としているのは、参照先の一覧ではなく、自分たちのプロジェクトに置ける契約だからです。

だから jp-ui-contracts では、「見本を増やす」方向より、「書ける・使える・見直せる」方向を優先しました。

ここが、このrepoの立ち位置です。

jp-ui-contracts に入っているもの画像 base を起点に、用途別プロファイルへ分けることで、文脈ごとの正解を持ち込みやすくしています。このrepoには、最初から日本語UIの設計を始めやすくするための骨格を入れています。中心にあるのは、templates/ です。

base は最小共通契約。まずはここから始めます。その上で、用途ごとに

media saas docs dashboard

の4プロファイルを分けました。これには理由があります。日本語UIは一枚岩ではありません。

記事メディアと業務UIでは、正解の密度が違う。技術文書とダッシュボードでは、見出しの役割も、表の扱いも違う。

だから、最初から文脈別に初期化できるようにしています。その周辺にあるのが、recipes/ です。

ここには、日本語本文、mixed-script、見出し、フォームなど、壊れやすい場所に対するCSS断片を置いています。狙いは、魔法のCSSを配ることではありません。

契約に書いた方針を、再利用可能な実装単位へ落とすこと。

さらに、validators/ を入れています。ここが、このrepoのかなり大事な部分です。

AI生成UIは、出して終わりにすると弱い。本当に必要なのは、何を見直すべきかを固定することです。

そこで、

長文本文は苦しくないか。 mixed-script の見出しは崩れていないか。 URL対策が本文を壊していないか。フォームが窮屈になっていないか。表の密度が読める範囲に収まっているか。

そうした観点を、lint-rules と review-checklist として先に置きました。

つまりこのrepoは、テンプレート集であると同時に、レビュー観点のrepo でもあります。

独自性はどこにあるのかこのrepoの独自性は、「日本語対応しています」という一点ではありません。

本質は、日本語UIを“翻訳対象”ではなく“契約対象”として扱っていることです。

海外起点の DESIGN.md を見ていると、どうしても発想が「欧文前提の仕様をどう日本語に寄せるか」になりやすい。

でも、そこから入ると、日本語UIはだいたい後手になります。そうではなく、最初から

日本語本文の可読性和欧混植の安定改行とoverflowの責務分離表とフォームの密度分離モバイルでの折り返し確認

を中心に据えて書く。この順番が大事です。

もう少し強く言うと、日本語UIの品質差は、色より前に、文字組みの契約差で生まれる。

この認識をrepoの中心に置いた、というのが独自性です。

どう使うのか画像契約から生成へ進み、目視で差分を拾い、また契約へ戻す。その循環を短く回します。使い方は、できるだけ単純にしています。

最初に templates/base/DESIGN.md をコピーする。あるいは用途に応じて media や saas を選ぶ。

次に、プロダクトの色、フォント、余白、コンポーネント方針、禁止事項を書く。

そのあと、必要な recipes/ を足す。そこまでできたら、AIに画面を生成させる。生成したら終わりではなく、validators/ の観点で見直す。その差分を、また DESIGN.md に戻す。このrepoが想定しているのは、一発で完璧に当てるフローではありません。

契約 → 生成 → 目視 → 契約修正のループを、短く、強く、回せるようにすることです。

これは誰に効くかいちばん効くのは、AIでUIを作り始めている人です。

フロントエンド開発者。プロダクトデザイナー。社内ツールを量産しているチーム。業務UIや技術文書の画面をAIに作らせている人。

特に、

「毎回それっぽいUIは出るけど、最後の詰めが甘い」「英語だけならいいのに、日本語になると急に完成度が落ちる」「レビューが属人的で、何を直せばいいか固定されない」

という悩みを持っているなら、このrepoはかなり相性がいいはずです。逆に、完全なブランド模写集を探している人には向きません。

やりたいのは、模写の蓄積ではなく、自分のプロダクトに置ける日本語UI契約を育てることだからです。

なぜ今、これが必要なのかここが一番大きい論点です。 AIでUIを作る時代になるほど、「何を作るか」だけでなく、「どんな契約で作らせるか」が重要になります。

プロンプトは、その場の指示です。でも契約は、プロジェクトの記憶になります。この差は大きい。

毎回説明し直す設計は、人間が疲れます。レビューもぶれます。引き継ぎも弱い。

一方で、DESIGN.md のような形で契約が置かれていると、 AIにとっても、人間にとっても、どこを守るべきかが読みやすくなる。

しかも日本語UIでは、この契約の有無が、かなり露骨に完成度へ出ます。だから、これは単なる便利repoではありません。

日本語UIを、プロンプト芸から設計資産へ戻すための一歩だと考えています。

最後に画像プロンプト芸ではなく、設計資産として日本語UIを育てる。その入口としてこのrepoを置きました。今回公開した jp-ui-contracts は、日本語UIの唯一の正解を配るrepoではありません。

そうではなく、日本語UIで毎回起きる崩れを、少しずつ契約へ戻していくための出発点です。

まずは templates/base/DESIGN.md を開いて、自分のプロダクトに必要な契約を書いてみてください。

記事メディアなら media。業務UIなら saas。技術文書なら docs。高密度の分析画面なら dashboard。

日本語UIの品質は、最後に気合いで整えるものではなく、最初に契約として置いておくものへ変わっていく。

その流れの入口として、このrepoが使われると嬉しいです。

付録

これは「日本語版の見本集」ではなく、日本語UI向けの DESIGN.md を書くための契約キットとして立てます。したがって、最初の公開で必要なのは次の4層です。

README: このrepoは何者か

CONTRIBUTING: どう追加・改善するか

Template: ユーザーが最初に複製する本体

Validator / Recipes / Docs: 実運用で壊れにくくする補助線

まず置くべきディレクトリ構成 jp-ui-contracts/ ├─ README.md ├─ LICENSE ├─ CONTRIBUTING.md ├─ docs/ │ ├─ philosophy.md │ ├─ profiles.md │ ├─ japanese-typography-notes.md │ └─ css-recipes.md ├─ templates/ │ ├─ base/ │ │ └─ DESIGN.md │ ├─ media/ │ │ └─ DESIGN.md │ ├─ saas/ │ │ └─ DESIGN.md │ ├─ docs/ │ │ └─ DESIGN.md │ └─ dashboard/ │ └─ DESIGN.md ├─ recipes/ │ ├─ ja-text.css │ ├─ mixed-script.css │ ├─ headings.css │ └─ forms.css ├─ validators/ │ ├─ review-checklist.md │ ├─ lint-rules.md │ └─ screenshot-review-prompt.md ├─ schema/ │ └─ design-contract.schema.json └─ examples/ ├─ sample-media/ │ ├─ DESIGN.md │ └─ preview.html └─ sample-saas/ ├─ DESIGN.md └─ preview.html

README.md Japanese UI contracts for AI builders.

jp-ui-contracts は、日本語UI向けの DESIGN.md を書き、見直し、検証するためのリポジトリです。

これは公開サイトの見た目を収集する「見本帳」ではありません。
AIエージェントやコード生成ツールが、日本語の本文、見出し、和欧混植、改行、字間、行間、フォーム密度を壊しにくくするための、設計契約キットです。

このrepoがやること

日本語UI向け DESIGN.md テンプレートを提供する
文脈別プロファイルを提供する
- media
- saas
- docs
- dashboard
日本語組版向けの CSS recipe を提供する
AI生成UIを人間が見直すための validator を提供する
サンプル preview を通じて、契約と画面の往復をしやすくする

このrepoがやらないこと

公開サイトの完全再現
ブランド模写の収集
日本語組版の唯一絶対ルールの断定
プロンプトだけで画面品質を保証すること

なぜ必要か

日本語UIは、色や余白だけでは再現できません。

問題になりやすいのは、むしろ次の層です。

和文フォントの不足
和欧混植時の違和感
本文と見出しで違うべき line-height の未分離
本文に対する過剰な letter-spacing
word-break: break-all の乱用
URL と英単語のはみ出し
テーブルやフォームが本文ルールを引きずること

このrepoは、それらを「感覚」ではなく、AIが読める契約として扱います。

設計原則

1. Contract first

毎回のプロンプトで見た目を説明するのではなく、プロジェクト側に契約を置く。

2. Context-aware defaults

日本語UIは一枚岩ではありません。
記事メディア、SaaS、技術文書、ダッシュボードでは、密度も行間も改行戦略も変わります。

3. Mixed-script safety

日本語だけ、英語だけではなく、日本語と英語が混ざった状態で成立することを重視します。

4. Progressive enhancement

新しいCSS機能は活かしつつ、未対応環境で壊れない設計を優先します。

5. Human review before canonization

スクリーンショットがきれいでも終わりません。
実際に読む、詰める、入力する、折り返す、を確認してから採用します。

プロファイル一覧

`base`

最小共通契約です。
ゼロから書き始めるのではなく、まずこれを複製します。

`media`

長文読解向けです。
本文の呼吸を優先し、行間を広めに取ります。

`saas`

業務UI向けです。
可読性を落とさず、密度と安定性を優先します。

`docs`

技術文書向けです。
本文、コード、見出し、表、注釈の切り分けを重視します。

`dashboard`

高密度情報向けです。
表、数値、ラベル、カードの詰まりすぎを避けつつ、視線移動を短く保ちます。

クイックスタート

1. テンプレートを選ぶ

最初は次のいずれかを複製します。

templates/base/DESIGN.md
templates/media/DESIGN.md
templates/saas/DESIGN.md
templates/docs/DESIGN.md
templates/dashboard/DESIGN.md

2. ブランド情報を埋める

色
フォント
余白スケール
コンポーネント方針
禁止事項
review対象

を埋めます。

3. recipe を追加する

recipes/ の CSS を必要なものだけ導入します。

4. validator で見る

validators/ のチェックリストと lint ルールで見直します。

5. preview を作る

契約だけで終わらせず、最小の preview.html を作って見ます。

推奨ワークフロー

DESIGN.md を書く
AIにUIを生成させる
preview を見る
validator で差分を記録する
契約へ戻して修正する
再生成する

このrepoは、1回で当てるためのものではありません。
契約 → 生成 → 目視 → 契約修正 のループを速くするためのものです。

収録物

templates/: 複製して使う契約テンプレート
recipes/: 日本語UI用CSS断片
validators/: AI生成物の見直し規則
docs/: 設計思想と使い分け
schema/: 将来の機械検証用スキーマ
examples/: 最小サンプル

どんな人に向くか

AIでUIを生成しているフロントエンド開発者
DESIGN.md を使い始めたいプロダクトチーム
日本語UIの詰めが甘くなることに悩んでいるデザイナー
和欧混植と改行で毎回崩れることに疲れている人
日本語向け design contract をチーム資産にしたい人

今後のロードマップ

design-contract.schema.json の拡充
サンプル preview の増加
validator の半自動化
mixed-script review の強化
mobile / desktop の別基準追加
日本語フォームUI、表UI、ナビゲーションUIの細分化

ライセンス

MIT

はじめ方

まずは templates/base/DESIGN.md をコピーし、
あなたのプロダクトに合わせて Locale / Profile / Typography / Validation Targets を埋めてください。 2. CONTRIBUTING.md

Contributing to jp-ui-contracts

このリポジトリは、日本語UI向け design contract を改善するための共同作業場です。
ただし、何でも追加すればよいわけではありません。

このrepoは「思いつきの見た目集」ではなく、再利用可能な設計契約を育てることを目的にしています。

まず守る方針

1. 収集より契約を優先する

新しいブランド例を増やすことよりも、
どういう条件で、どの値を、なぜ使うのかを明確にしてください。

2. 日本語本文を壊さない

派手さより可読性を優先します。
本文の line-height、改行、和欧混植、フォーム密度を軽視しないでください。

3. 文脈を分ける

media と saas では正解が違います。
一つの値を「日本語の標準」と断定しないでください。

4. 実画面で確認する

スクリーンショットだけでは不十分です。
最低でも、段落、見出し、URL、表、フォームのどれかを実画面で確認してください。

受け付けるコントリビューション

テンプレート改善
recipe の追加
validator ルールの追加
docs の補足
example の追加
schema の改善
mixed-script や line break に関する実務知見の整理

受け付けにくいコントリビューション

単なるブランド模写の追加
根拠のない数値断定
日本語本文へ過剰な letter-spacing を推奨する変更
word-break: break-all を全体既定にする提案
実画面確認なしの強い主張
「海外の DESIGN.md ではこうだった」だけを根拠にした提案

Pull Request を出す前に確認すること

A. 何を改善したのか

何が困っていたのか
どの文脈で問題が起きるのか
何をどう直したのか

B. どこで効くのか

media
saas
docs
dashboard

のどれに効くのかを明記してください。

C. 何を壊さないのか

次のどれを守るのかを書いてください。

本文可読性
見出しの折り返し
URLはみ出し防止
mixed-script の違和感低減
フォーム密度の安定
テーブルの読みやすさ

D. どう確認したか

最低限、次のどれかを添えてください。

before / after のスクリーンショット
preview.html の差分
validator の観点での説明
実際のCSS断片

推奨PRフォーマット

## Summary
何を変えたか

## Problem
どの文脈で何が困るのか

## Scope
media / saas / docs / dashboard のどれに効くか

## Change
どう変えたか

## Validation
どう確認したか

## Risk
何を壊す可能性があるか

命名ルール

templates

文脈名を使ってください
例: media, saas, docs, dashboard

recipes

目的が見える名前にしてください
例: ja-text.css, mixed-script.css, forms.css

validators

何を検査するかが分かる名前にしてください
例: lint-rules.md, review-checklist.md

テンプレートを変えるときの注意

テンプレートは、このrepoの中心資産です。
変更するときは、次の順で考えてください。

そのルールは全体共通か
特定profileだけに効く話ではないか
validator に落とすべきではないか
recipe で十分ではないか

テンプレート本体に何でも書き込むと、契約が重くなりすぎます。
共通契約、文脈別契約、CSS断片、レビュー規則の役割を分けてください。

Issue の歓迎内容

「この文脈では line-height をどう考えるべきか」
「mixed-script の見出しが崩れる」
「表だけ詰まりすぎる」
「フォームがスマホで苦しい」
「日本語本文に palt を全体適用してよいか迷う」
「validator をどう自動化できるか」

コミュニケーション方針

断定より検証を優先します。
美しい、読みやすい、詰まっている、は主観で終わらせず、できるだけ画面、文脈、役割、比較で説明してください。

最後に

このrepoの目的は、日本語UIを「海外向けルールの微調整」で済ませないことです。
一つずつ契約を明文化し、AIでも再現しやすく、人間でも見直しやすい形へ育てていきます。 3. templates/base/DESIGN.md

DESIGN.md — [Project Name]

Japanese UI design contract for AI agents and human reviewers.

0. Contract Metadata

Locale: ja-JP
Profile: base
Primary writing mode: horizontal-tb
Target surfaces: web
Review status: draft
Last reviewed at: YYYY-MM-DD
Reviewer: [name/team]

1. Product Intent

What this product is:
Primary audience:
Primary usage context:
Design stance:
Must feel like:
Must not feel like:

2. Visual Theme & Brand Signals

Keywords:
Visual temperature: calm | neutral | warm | sharp
Density: airy | balanced | compact
Tone:
Motion stance: minimal | moderate | expressive

3. Color System

Brand colors

Primary: #000000
Primary hover:
Accent:

Semantic colors

Success:
Warning:
Danger:
Info:

Neutral colors

Text primary:
Text secondary:
Text muted:
Border:
Background:
Surface:
Surface elevated:

Color usage rules

Do not rely on color alone for meaning
Keep primary actions visually distinct
Avoid low-contrast muted text on tinted surfaces

4. Typography System

4.1 Japanese fonts

Sans:
Serif:
Mono:

4.2 Latin fonts

Sans:
Serif:
Mono:

4.3 Fallback policy

font-family: "Preferred Japanese Font", "Preferred Latin Font", sans-serif;

Japanese fallback must be explicit
Font stack must be stable on macOS and Windows
Avoid leaving Japanese rendering to browser defaults

4.4 Type scale

Role	Size	Weight	Line Height	Letter Spacing	Notes
Display
H1
H2
H3
Body L
Body M
Body S
Caption
Label
Mono

4.5 Japanese paragraph rules

Default Japanese body line-height should usually stay within 1.5–2.0
Default Japanese body letter-spacing should usually remain normal or conservative
Do not apply aggressive tracking to body text by default
Heading and label spacing may differ from body spacing

4.6 Mixed-script rules

Review Japanese + Latin text together
Avoid visual collision in headings containing English product names
Do not optimize Latin words in a way that harms Japanese paragraph rhythm
Numeric strings, code, and IDs may require separate handling

4.7 OpenType and rendering

font-kerning: auto;
font-feature-settings: normal;

palt may be used for headings or navigation after visual review
Avoid global palt on body text unless reading comfort is verified
Use proportional settings only where they improve actual reading

4.8 Writing direction

Default writing direction is horizontal
Vertical writing is: not used

5. Line Breaking & Overflow

Default rules

html:lang(ja) {
  line-break: strict;
  word-break: normal;
  overflow-wrap: anywhere;
}

Additional rules

Do not use global word-break: break-all
Use stronger breaking only for logs, hashes, URLs, and machine-like strings
Review headings at narrow widths
Review long English words inside Japanese UI
Prevent URL overflow without breaking paragraph readability

Optional enhancement

h1:lang(ja),
h2:lang(ja),
h3:lang(ja) {
  word-break: auto-phrase;
}

Experimental enhancement

html:lang(ja) {
  text-autospace: normal;
}

Treat text-autospace as progressive enhancement
Do not make it a hard dependency

6. Layout Principles

Container width:
Reading width:
Grid system:
Spacing scale:
Section spacing rule:
Whitespace policy:

Layout rules

Reading width must prioritize comfort for Japanese paragraphs
Dense UI should compress containers before compressing line-height
Visual grouping should rely on spacing before borders when possible

7. Component Guidelines

Buttons

Primary button must be obvious
Label length in Japanese must be tested
Avoid overly short button heights in compact layouts

Inputs

Placeholder is not a label replacement
Japanese IME input states must remain legible
Error and help text must stay readable at smaller sizes

Cards

Keep title, body, meta, and actions visually separated
Do not collapse vertical rhythm to fit more content unless profile requires it

Tables

Table density must be tuned separately from paragraph density
Numeric alignment and label wrapping must be reviewed
Avoid applying article-style line-height to high-density tables

Mixed Japanese and English labels must be reviewed
Active state must be visible without relying on color alone

Modals / Drawers

Long Japanese text must not create cramped vertical rhythm
Confirm and cancel actions must remain distinct

8. Depth, Border, and Surface

Surface levels

Level	Usage	Border	Shadow
0	Page background	none	none
1	Base surface	optional	subtle
2	Raised card	optional	subtle
3	Modal / overlay	optional	moderate

Rules

Prefer subtle depth
Avoid decorative shadows that reduce seriousness
Use border and elevation consistently

9. Responsive Behavior

Breakpoints:
Mobile reading width:
Tablet layout stance:
Desktop layout stance:

Responsive rules

Recheck paragraph rhythm on mobile
Recheck heading wrapping on mobile
Table fallback strategy must be explicit
Form spacing must be verified on small screens
Dense desktop UI must not be copied directly onto mobile

10. Motion & Interaction

Animation stance:
Transition speed:
Reduced motion policy:

Rules

Motion should support hierarchy, not decorate it
Avoid large shifts that disturb reading
Loading states must stay legible in Japanese

11. Do’s and Don’ts

Do

Preserve Japanese reading comfort
Keep mixed-script text visually balanced
Review actual line breaks at real widths
Separate paragraph rules from table rules
Prefer stable defaults over clever tricks

Don’t

Do not globalize word-break: break-all
Do not copy Latin-first typography blindly
Do not increase body letter-spacing without clear reason
Do not use body line-height that feels compressed for long Japanese text
Do not accept screenshots alone as final validation

12. Agent Prompt Guide

Use calm, readable Japanese typography.

Honor the locale and profile before inventing stylistic variations.

Preserve readability first when there is tension between novelty and comfort.

When uncertain:

keep body text conservative
keep headings clear
avoid aggressive spacing
avoid fragile wrapping rules

Do not imitate Western editorial spacing in Japanese body text without review.

13. Validation Targets

Must pass long paragraph review
Must pass mixed-script heading review
Must pass long URL overflow review
Must pass form density review
Must pass mobile layout review
Must pass color contrast review

templates/media/DESIGN.md

DESIGN.md — [Project Name]

Profile: media

0. Contract Metadata

Locale: ja-JP
Profile: media
Review status: draft

1. Reading Experience

Long-form reading is the primary use case
Vertical rhythm must feel spacious
Visual noise must stay low
Headings should guide pace, not overpower paragraphs

2. Typography Defaults

Role	Size	Weight	Line Height	Letter Spacing	Notes
H1	32px	700	1.4	0.02em	calm emphasis
H2	26px	700	1.5	0.02em	section anchor
H3	22px	700	1.55	0.01em	subsection anchor
Body	18px	400	1.85	normal	reading-first
Caption	14px	400	1.7	normal	supportive text

Rules

Body line-height should usually remain within 1.75–2.0
Body letter-spacing should usually remain normal
Paragraph spacing must be generous enough to avoid wall-of-text feeling
Pull quotes and lead text may slightly diverge, but body must remain stable

3. Layout Defaults

Reading width: 38–44em
Prefer single-column reading for article body
Side metadata must not disrupt paragraph rhythm
Images should reset pace, not fragment flow

4. Validation Targets

Must pass long article reading review
Must pass mobile article review
Must pass mixed-script title review
Must pass caption readability review

templates/saas/DESIGN.md

DESIGN.md — [Project Name]

Profile: saas

0. Contract Metadata

Locale: ja-JP
Profile: saas
Review status: draft

1. Product Use

Business task completion is the primary use case
Density and stability matter more than editorial spaciousness
UI must remain readable during repeated daily use

2. Typography Defaults

Role	Size	Weight	Line Height	Notes
H1	28px	700	1.35	page title
H2	22px	700	1.4	section title
H3	18px	600	1.45	group label
Body	14px	400	1.55	operational default
Caption	12px	400	1.45	supportive text
Label	13px	500	1.4	control label

Rules

Body line-height should usually remain within 1.5–1.65
Body letter-spacing should remain conservative
Tables, forms, badges, and tabs must be tuned separately
Compactness must not damage scanability

3. Layout Defaults

Prefer modular surfaces
Form rhythm must be explicit
Dense information should use grouping before shrinking
Buttons and fields must preserve Japanese label readability

4. Validation Targets

Must pass form density review
Must pass table density review
Must pass mixed Japanese-English navigation review
Must pass mobile settings page review

templates/docs/DESIGN.md

DESIGN.md — [Project Name]

Profile: docs

0. Contract Metadata

Locale: ja-JP
Profile: docs
Review status: draft

1. Documentation Intent

Technical explanation is the primary use case
Prose, code, table, callout, and navigation must be distinguishable
Readers must be able to skim and dive

2. Typography Defaults

Role	Size	Weight	Line Height	Letter Spacing	Notes
H1	30px	700	1.35	0	page title
H2	24px	700	1.4	0	section title
H3	20px	600	1.45	0	subsection
Body	16px	400	1.7	normal	explanation
Caption	13px	400	1.6	normal	note/support
Code	14px	400	1.7	0	code/text contrast

Rules

Paragraph rhythm must support sustained reading
Code blocks must not inherit paragraph spacing blindly
Tables must not use article defaults
Mixed Japanese and English technical terms must remain legible

3. Layout Defaults

Reading width should support code and prose balance
Long lines in code must have a clear handling policy
TOC, callouts, and examples must remain visually distinct

4. Validation Targets

Must pass prose reading review
Must pass code block review
Must pass table review
Must pass mixed-script technical heading review

templates/dashboard/DESIGN.md

DESIGN.md — [Project Name]

Profile: dashboard

0. Contract Metadata

Locale: ja-JP
Profile: dashboard
Review status: draft

1. Dashboard Intent

High-density information scan is the primary use case
Metrics, labels, filters, tables, and cards must remain separable
Readability must hold under repeated operational use

2. Typography Defaults

Role	Size	Weight	Line Height	Notes
H1	24px	700	1.3	page title
H2	18px	600	1.35	card title
Body	14px	400	1.5	default text
Caption	12px	400	1.4	support text
Metric	24px	700	1.2	number emphasis
Label	12px	500	1.35	compact metadata

Rules

Paragraph rhythm is secondary to scanability
Table density must remain readable
Numeric alignment and label wrapping must be reviewed together
Filters and controls must keep enough tap area

3. Layout Defaults

Prefer modular cards
Preserve clear information grouping
Avoid decorative whitespace that hides relationships
Compress width before compressing text rhythm too far

4. Validation Targets

Must pass card scan review
Must pass metric readability review
Must pass dense table review
Must pass mobile overflow review

validators/lint-rules.md

lint-rules

このファイルは、日本語UI向け design contract を見直すための実務ルールです。
自動lintの仕様書というより、まずは人間がレビュー時に使う拒否条件と警告条件を明文化します。

Reject

次のいずれかに当てはまる場合、原則として差し戻します。

1. 全体既定で `word-break: break-all` を使っている

日本語本文、見出し、フォーム、表の可読性を壊しやすいため。

2. 本文に強い letter-spacing を既定適用している

目安として、本文に 0.02em を大きく超える tracking を理由なく入れている場合は差し戻します。

3. 長文の日本語本文に対して line-height が低すぎる

目安として、長文本文で 1.5 未満を既定にする場合は、強い理由と実画面確認が必要です。

4. 日本語 fallback を明示していない

和文フォントの描画責任をブラウザ既定に丸投げしないでください。

5. `palt` や proportional 系機能を本文に全体適用している

本文への一括適用は、副作用が出やすいため、実読確認なしでは採用しません。

6. 表やフォームが本文ルールをそのまま継承している

本文、表、フォームは密度の要件が違います。分離してください。

Warn

次に当てはまる場合は警告です。
即差し戻しではありませんが、理由と確認結果を添えてください。

1. `text-autospace` を使っている

新しい機能なので、段階適用か、フォールバック方針を書いてください。

2. 見出しのモバイル折り返しを確認していない

PC表示だけで判断しないでください。

3. mixed-script を含む見出しを確認していない

日本語 + 英語サービス名、英単語、略称が入る場合は要確認です。

4. URL や長い英単語の overflow を見ていない

記事、docs、FAQ、ナレッジUIでは特に確認が必要です。

5. Windows描画を考慮していない

macOSだけで見て終わると、日本語描画の印象差が大きく出ることがあります。

6. compact UI で tap target が細すぎる

情報密度を優先しすぎて、操作性を落としていないか確認してください。

Require rationale

次の項目は、値だけでなく理由を書いてください。

なぜ media / saas / docs / dashboard のどれを採用したか
本文の line-height をその値にした理由
本文の letter-spacing をその値にした理由
mixed-script の主な出現場所
表やフォームを本文からどのように分離したか
モバイルで何を優先し、何を削ったか

Good signs

次の状態は、良い contract に近いサインです。

本文と表とフォームが分離されている
heading と body の spacing logic が別れている
overflow 戦略が明示されている
mixed-script の扱いが書かれている
validator 観点が DESIGN.md 本体に戻されている

validators/review-checklist.md

review-checklist

UIをAI生成したあと、最低限ここを見ます。

1. 長文本文

日本語段落が詰まりすぎていないか
行間が不足していないか
字間が不自然に開いていないか
段落の切れ目が視認できるか

2. 見出し

モバイル幅で不自然に折れていないか
日本語 + 英語混在タイトルが崩れていないか
見出しが本文より騒がしくなりすぎていないか

3. URL / 長語

URLがはみ出さないか
長い英単語でUIが崩れないか
その対策が本文可読性を壊していないか

4. フォーム

ラベルが読めるか
エラーメッセージが読めるか
IME入力中も不自然でないか
ボタンが窮屈すぎないか

5. 表

行高が低すぎないか
数値とラベルの視認性が保てているか
折り返しが破綻していないか

6. mixed-script

日本語の中に入る英語が浮きすぎていないか
英語サービス名や固有名詞が潰れていないか
記号や括弧の前後が苦しくないか

7. モバイル

余白が潰れすぎていないか
読む画面と操作する画面の両方で成立しているか
デスクトップ前提のまま縮小していないか

8. コントラスト

本文の薄さが過剰でないか
補助テキストが読める範囲か
色だけで状態を伝えていないか

validators/screenshot-review-prompt.md

screenshot-review-prompt

以下をAIレビュー用の共通プロンプトとして使います。

あなたは日本語UIレビュー担当です。
与えられたスクリーンショットを見て、見た目の好みではなく、日本語UIの可読性・折り返し・密度・混植・フォーム安定性の観点でレビューしてください。

次の順で出力してください。

総評
重大な問題
軽微な問題
良い点
修正優先順位
DESIGN.md に戻すべき契約差分

制約:

色や余白だけで終わらない
日本語本文、見出し、URL、mixed-script、表、フォームの観点を優先する
修正案はできるだけ contract に戻せる形で書く
「なんとなく」ではなく、画面上の何がどう苦しいかを具体化する

recipes/ja-text.css html:lang(ja) { line-break: strict; word-break: normal; overflow-wrap: anywhere; font-kerning: auto; font-feature-settings: normal; }

body { text-rendering: optimizeLegibility; }

p, li, dd { line-break: strict; word-break: normal; overflow-wrap: anywhere; }

:where(article, .prose, .content) p { max-width: 42em; } 12. recipes/mixed-script.css html:lang(ja) { text-autospace: normal; }

:lang(ja) em, :lang(ja) strong, :lang(ja) a, :lang(ja) .latin, :lang(ja) .product-name { word-break: normal; overflow-wrap: anywhere; }

:lang(ja) h1, :lang(ja) h2, :lang(ja) h3 { word-break: auto-phrase; } 13. recipes/headings.css :lang(ja) h1, :lang(ja) h2, :lang(ja) h3, :lang(ja) h4 { line-break: strict; word-break: normal; overflow-wrap: anywhere; font-kerning: auto; }

:lang(ja) h1 { line-height: 1.35; }

:lang(ja) h2 { line-height: 1.4; }

:lang(ja) h3 { line-height: 1.45; } 14. recipes/forms.css :lang(ja) label, :lang(ja) input, :lang(ja) textarea, :lang(ja) select, :lang(ja) button { line-break: strict; word-break: normal; }

:lang(ja) input, :lang(ja) textarea, :lang(ja) select { line-height: 1.5; }

:lang(ja) .form-help, :lang(ja) .form-error { line-height: 1.5; overflow-wrap: anywhere; } 15. docs/philosophy.md

philosophy

jp-ui-contracts は、見た目の装飾仕様を増やすためのrepoではありません。
日本語UIで毎回起きる崩れを、プロンプトの言い換えではなく、契約として固定するためのrepoです。

1. なぜ contract なのか

AIでUIを作るとき、色、角丸、余白は比較的再現されやすい一方で、日本語本文や見出しの質は不安定になりやすいです。

理由は単純で、それらが曖昧なままだからです。

どのフォントを使うか
fallback をどうするか
本文の行間をどこに置くか
mixed-script をどう扱うか
URL はみ出しをどう防ぐか
表やフォームを本文とどう分けるか

これらを毎回プロンプトで説明すると、抜けます。
だから契約として置きます。

2. 日本語UIは一枚岩ではない

記事メディアとSaaSを同じ rule で扱うと、どちらかが壊れます。

記事は読むリズムが重要
SaaSは作業密度が重要
docsは本文とコードの両立が重要
dashboardは走査性が重要

このrepoが profile を分けるのはそのためです。

3. 目指すのは唯一の正解ではない

日本語組版に普遍的な絶対値を配ることは目的ではありません。
目的は、文脈ごとの妥当な初期値と、壊れやすい点の検査観点を共有することです。

4. 契約は固定物ではない

一度書いて終わりではありません。

契約
→ 生成
→ 目視
→ 差分発見
→ 契約更新

このループで育てます。 16. docs/profiles.md

profiles

このrepoの profile は、日本語UIを用途別に初期化するためのものです。

media

向いているもの:

note
ブログ
オウンドメディア
インタビュー記事
長文読み物

重視するもの:

本文の呼吸
段落リズム
見出しの導線
画像との間合い

saas

向いているもの:

管理画面
設定画面
社内業務ツール
B2B SaaS

重視するもの:

安定した密度
ラベルの読めやすさ
フォームの扱いやすさ
表の走査性

docs

向いているもの:

開発者向け文書
ナレッジベース
ヘルプセンター
技術ブログ

重視するもの:

本文とコードの共存
注釈の分離
長い見出しの扱い
mixed-script の安定

dashboard

向いているもの:

BI画面
KPI画面
運用監視画面
分析UI

重視するもの:

数値の視認性
高密度でも潰れないこと
フィルタやラベルの扱い
カードと表のバランス

docs/japanese-typography-notes.md

japanese-typography-notes

このメモは、日本語UI設計で見落としやすい論点をまとめたものです。

1. 本文と見出しは別物

本文は読むための器です。
見出しは導線です。
同じ spacing logic で扱わないでください。

2. 本文の字間は慎重に

見出しやラベルでは少し効く場合がありますが、本文ではむしろ不自然になることがあります。
特に長文では、行間の不足を字間でごまかさないことが重要です。

3. 改行戦略を分ける

禁則寄りの扱い
URL や英単語の折り返し
mixed-script 見出しの自然な分割

これらは一つのCSS値では片づきません。

4. 表とフォームは本文から分離する

本文が読みやすくても、表やフォームにはそのまま使えません。
逆に表に合わせた詰め方を本文へ持ち込むと、読みにくくなります。

5. mixed-script は最後に崩れる

日本語単体では成立しても、日本語 + 英語のサービス名、略称、英数字が入ると一気に崩れます。
見出しとナビゲーションで特に確認してください。 18. docs/css-recipes.md

css-recipes

recipes/ は、何でも貼る場所ではありません。
契約で決めた方針を、再利用しやすいCSS断片にしたものです。

基本方針

契約に書くべきことは DESIGN.md に残す
recipe は implementation の再利用単位に留める
recipe は万能化しすぎない
特に word-break は乱暴に全体へ広げない

代表的なrecipe

ja-text.css

日本語本文の基本。
line-break、overflow、font-kerning の安定化に使います。

mixed-script.css

日本語 + 英語混在時の安全策。
見出しや product name の扱いで役立ちます。

headings.css

見出し専用の折り返しと line-height をまとめます。

forms.css

フォーム、ラベル、エラー表示の窮屈さを防ぎます。 19. schema/design-contract.schema.json 最初は厳密にしすぎない方がよいです。初版は「将来こう機械検証できる」という宣言に留めるのが安全です。

{ “$schema”: “https://json-schema.org/draft/2020-12/schema”, “title”: “Design Contract Schema”, “type”: “object”, “properties”: { “locale”: { “type”: “string” }, “profile”: { “type”: “string”, “enum”: [“base”, “media”, “saas”, “docs”, “dashboard”] }, “reviewStatus”: { “type”: “string”, “enum”: [“draft”, “verified”, “production”] }, “typography”: { “type”: “object” }, “layout”: { “type”: “object” }, “validationTargets”: { “type”: “array”, “items”: { “type”: “string” } } }, “required”: [“locale”, “profile”, “reviewStatus”] } 20. GitHub の見え方まで詰めるなら repo description Japanese UI design contracts for AI builders. Templates, CSS recipes, and validation rules for DESIGN.md. topics design-md japanese-ui typography ai-design-system cjk frontend css ui-contracts 初回コミットメッセージ chore: initialize jp-ui-contracts with templates, recipes, validators, and docs ファイルダウンロード中には、README、全テンプレート、validator、CSS recipe、schema、2種類のサンプル preview、LICENSE、.gitignore を入れています。

入っているものは次の通りです。

README.md

CONTRIBUTING.md

LICENSE（MIT、権利表記は hirokaji で仮置き）

templates/ の5プロファイル

recipes/ のCSS群

validators/ のレビュー規則

schema/ の初期JSON Schema

examples/ の sample-media / sample-saas と preview.html