Making DESIGN.md truly usable for Japanese UI

I have released jp-ui-contracts.

As the trend of using AI to build UI grows stronger, something else is becoming increasingly noticeable.

That is, the lack of polish in Japanese text.

The colors look right.
The margins are arranged reasonably well.
The shapes of cards and buttons also come out quite well.

But what falls apart in the end is the Japanese text.

Heading line breaks are awkward.
The line spacing in the body text is too tight.
When English service names are mixed in, they suddenly look out of place.
Forms become cramped.
Table density drags along the rules of the body text, making it hard to read.

This sense of discomfort does not arise simply because "AI accuracy is insufficient."

It is a more fundamental issue.
The design contracts for Japanese UI have not yet been sufficiently written.

That is why I created jp-ui-contracts.

Also, the following article is a general overview defining "what DESIGN.md is," while this article is a specific discussion showing "how to turn that into implementation assets for Japanese UI".

What kind of repo is this?

jp-ui-contracts is a repo for writing, reviewing, and operating DESIGN.md for Japanese UI.

What I wanted to do here was
not "translate overseas DESIGN.md files into Japanese."

Also, it is not "collecting the looks of famous services."
What I aimed for is something more practical.

Making design specifications for AI to read in a format that is less likely to break in Japanese UI.

In other words, this is not a sample book, but a design contract kit for Japanese UI.

Why did I go out of my way to create it?

The concept of DESIGN.md itself is very sound.

Instead of explaining design principles in every prompt,
placing them as fixed assets on the project side.
I believe this approach will become increasingly important.

However, if used as-is, there are many areas where Japanese UI falls short.

The problem is not that the design direction is too abstract.
It is actually the opposite.
The details that truly work for Japanese are not captured in the contract.

For example, these are the points of contention.

Which Japanese font to use.
How to mix it with Western fonts.
Where to set the line-height for body text.
How much to differentiate letter spacing between headings and body text.
When mixing Japanese and Western text, what kind of layout breakdown is unacceptable.
How to wrap long URLs or English words.
How to separate tables and forms from body text rules.

If these areas are ambiguous, even if AI can create a decent-looking UI, it will normally produce
screens that are painful to read.
And this problem cannot be solved just by tweaking prompts.

Rather than rephrasing "make it more readable" or "make it look more Japanese" every time,
it is stronger to write down
what to protect in this project
as a contract from the start.

This repo is for that purpose.

Areas where Japanese UI is truly fragile

Japanese UI shows differences in the typography layer before colors or rounded corners.
If you treat this carelessly, the overall level of completion drops by one notch.
The following areas are particularly fragile.

Treating body text and headings with the same logic

Body text is a vessel for reading.
Headings are navigation.

If you design with the same line-height and letter-spacing sense,
one of them will become uncomfortable.

Body text needs room to breathe.
Headings need strength and cohesion.
If you design without separating these, the body text will feel cramped or the headings will look stretched out.

Easily adding letter spacing to Japanese body text

It can sometimes be effective in headings or labels.
But in body text, adding letter spacing does not necessarily make it easier to read.

Rather, the discomfort in body text often comes from
insufficient line spacing or rough wrapping design.

If you start masking the discomfort of body text with tracking,
other areas will usually fall apart.

Trying to solve everything with break-all

Long URLs or English words overflow.
At that moment, you want to apply word-break: break-all to everything.

But this is a rather dangerous shortcut.

While it may prevent some overflow,
it easily ruins the natural reading flow of Japanese body text and headings.

URL countermeasures,
handling Japanese typography rules,
and adjusting mixed-script headings
should ideally be considered separately.

Tables and forms inheriting body text rules

The line-height that makes body text comfortable to read
cannot be used as-is for tables and forms.

Conversely, if you bring the condensed spacing used for tables into the body text,
long passages of text will suddenly become difficult to read.

In other words, the quality of a Japanese UI is determined not simply by "making text larger" or "increasing margins," but by

separating contracts by role.

That is why collection alone is not enough

Of course, observing existing excellent UIs is important in itself.

Which services use which fonts.
How they differentiate the rhythm between body text and headings.
How they manage information density.

There is much to learn from such observations.
But that alone is not enough.

This is because what teams and products truly need
is not a list of references, butcontracts that can be applied to their own projects.

Therefore, in jp-ui-contracts,
we prioritized the direction of "being able to write, use, and review"
over the direction of "increasing examples."

This is the positioning of this repo.

What is included in jp-ui-contracts

This repo contains a framework to make it easier to start designing Japanese UI from the beginning.
At the center is templates/.

base is the minimum common contract. Start here first.
On top of that, for each purpose

media
saas
docs
dashboard

I have separated the four profiles.
There is a reason for this.
Japanese UI is not monolithic.

The density of the correct answer differs between article media and business UI.
The roles of headings and the handling of tables also differ between technical documentation and dashboards.

That is why I have made it possible to initialize by context from the start.
Surrounding that is recipes/.

Here, I have placed CSS fragments for fragile areas such as Japanese body text, mixed-script, headings, and forms.
The goal is not to distribute magic CSS.
The aim is to:

Translate the policies written in the contract into reusable implementation units.

Furthermore, I have included validators/.
This is a very important part of this repo.

AI-generated UI is weak if you just output it and finish.
What is truly needed is to fix what should be reviewed.

Therefore,

Is the long-form body text uncomfortable?
Are the mixed-script headings broken?
Are URL countermeasures breaking the body text?
Are the forms becoming cramped?
Is the table density within a readable range?

I have placed these perspectives as lint-rules and a review-checklist in advance.

In other words, this repo is not only a collection of templates but also a
repo for review perspectives.

Where does the uniqueness lie?

The uniqueness of this repo is not just the single point of "supporting Japanese."

The essence is
treating Japanese UI not as a 'translation target' but as a 'contract target'.

When looking at DESIGN.md files originating from overseas,
the mindset inevitably tends to become
"how to adapt specifications based on Western languages to Japanese."

However, if you start from there, Japanese UI will almost always be an afterthought.
Instead, start from the beginning by focusing on

Readability of Japanese body text
Stability of Japanese-European mixed-script
Separation of concerns for line breaks and overflow
Density separation for tables and forms
Confirmation of wrapping on mobile

Writing with these at the center.
This order is important.

To put it more strongly,
the quality difference in Japanese UI is born from the contract of typesetting before color.

Placing this recognition at the center of the repo is its uniqueness.

How to use it

The usage is kept as simple as possible.

First, copy templates/base/DESIGN.md.
Alternatively, choose media or saas depending on your needs.

Next, write down your product's colors, fonts, spacing, component policies, and prohibitions.

After that, add the necessary recipes/.
Once that is done, have the AI generate the screens.
It doesn't end with generation; review them from the perspective of the validators/.
Feed those differences back into DESIGN.md.
This repo does not assume a flow where you get it perfect on the first try.

Contract → Generation → Visual Review → Contract Revision
The goal is to be able to run this loop quickly and effectively.

Who is this for?

It is most effective for those who have started building UI with AI.

Frontend developers.
Product designers.
Teams mass-producing internal tools.
People having AI build business UI or technical documentation screens.

Especially if you have concerns like:

“It always produces a decent-looking UI, but the final polish is lacking.”
“It works fine in English, but the quality drops significantly when it's in Japanese.”
“Reviews are subjective, and there's no fixed standard for what needs to be fixed.”

If you have these problems, this repo should be a great fit.
Conversely, it is not suitable for those looking for a complete collection of brand imitations.

What I want to do is not accumulate imitations, but rather
cultivate a Japanese UI contract that can be applied to your own productthat is why.

Why is this necessary now?

This is the biggest point of discussion.
As we enter an era where UI is built with AI,
not only 'what to build' but
'what kind of contract to build it with' becomes important.

A prompt is an instruction for the moment.
But a contract becomes the memory of the project.
This difference is significant.

A design that requires re-explaining every time
tires out humans.
Reviews become inconsistent.
Handovers are weak.

On the other hand, when a contract is placed in a form like DESIGN.md,
it becomes easier for both AI and humans
to read what needs to be protected.

Moreover, with Japanese UI, the presence or absence of this contract shows up quite explicitly in the level of completion.
Therefore, this is not just a convenient repo.

I believe this is a step toward moving Japanese UI from prompt engineering back to design assets.

Finally

The jp-ui-contracts released this time is
not a repo that distributes the only correct answer for Japanese UI.

Instead, it is a starting point for gradually returning the inconsistencies that occur every time in Japanese UI
back to a contract.

First, open templates/base/DESIGN.md and
try writing the contracts necessary for your product.

media for article media.
saas for business UI.
docs for technical documentation.
dashboard for high-density analysis screens.

The quality of Japanese UI should not be something adjusted by sheer willpower at the end,
but something that changes into being established as a contract at the beginning.

I would be happy if this repo is used as the entrance to that flow.

Appendix

This is not a "collection of Japanese samples," but is established as a contract kit for writing DESIGN.md for Japanese UI.
Therefore, the following four layers are necessary for the initial release.

• README: What this repo is

• CONTRIBUTING: How to add/improve

• Template: The main body that users replicate first

• Validator / Recipes / Docs: Guidelines to make it harder to break in actual operation

Directory structure to place first

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

1. README.md

# jp-ui-contracts

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` を作って見ます。

---

## 推奨ワークフロー

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

この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フォーマット

```md
## 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の中心資産です。  
変更するときは、次の順で考えてください。

1. そのルールは全体共通か
2. 特定profileだけに効く話ではないか
3. validator に落とすべきではないか
4. 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
```css
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
```css
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
```css
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
```css
h1:lang(ja),
h2:lang(ja),
h3:lang(ja) {
  word-break: auto-phrase;
}
```

### Experimental enhancement
```css
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

### Navigation
- 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

4. `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

5. 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 | Letter Spacing | Notes |
|------|------|--------|-------------|----------------|------|
| H1 | 28px | 700 | 1.35 | 0 | page title |
| H2 | 22px | 700 | 1.4 | 0 | section title |
| H3 | 18px | 600 | 1.45 | 0 | group label |
| Body | 14px | 400 | 1.55 | 0 | operational default |
| Caption | 12px | 400 | 1.45 | 0 | supportive text |
| Label | 13px | 500 | 1.4 | 0 | 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

6. 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

7. 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 | Letter Spacing | Notes |
|------|------|--------|-------------|----------------|------|
| H1 | 24px | 700 | 1.3 | 0 | page title |
| H2 | 18px | 600 | 1.35 | 0 | card title |
| Body | 14px | 400 | 1.5 | 0 | default text |
| Caption | 12px | 400 | 1.4 | 0 | support text |
| Metric | 24px | 700 | 1.2 | 0 | number emphasis |
| Label | 12px | 500 | 1.35 | 0 | 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

8. 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` 本体に戻されている

9. validators/review-checklist.md

# review-checklist

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

---

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

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

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

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

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

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

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

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

10. validators/screenshot-review-prompt.md

# screenshot-review-prompt

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

---

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

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

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

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

11. 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

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

17. 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

It is better not to be too strict at first.
For the first version, it is safer to limit it to a declaration that 'this can be machine-verified in the future'.

{
  "$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. If you want to refine how it looks on 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

initial commit message

chore: initialize jp-ui-contracts with templates, recipes, validators, and docs

File download

Included are the README, all templates, validator, CSS recipes, schema, two types of sample previews, LICENSE, and .gitignore.

The contents are as follows:

• README.md

• CONTRIBUTING.md

• LICENSE (MIT, copyright notice temporarily set to hirokaji)

• 5 profiles in templates/

• CSS collection in recipes/

• Review rules in validators/

• Initial JSON Schema in schema/

• sample-media / sample-saas and preview.html in examples/

It is a framework that can be uploaded to GitHub as is.

#CreativeAward2026 #AllCategoryDivision