awesome-design-md-jp

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

Awesome Design MD JP

日文UI设计规范MD精选集合

Skill by ara.so — Daily 2026 Skills collection.

A curated collection of

DESIGN.md

files for Japanese web services, extending the Google Stitch DESIGN.md format with CJK typography, Japanese font stacks, kinsoku shori (禁則処理), and mixed typesetting (混植) rules — enabling AI agents to generate accurate Japanese UI.

由ara.so提供的技能——2026每日技能合集。

这是一个为日文网页服务整理的

DESIGN.md

文件集合，在Google Stitch DESIGN.md格式基础上扩展了CJK排版、日文字体栈、禁則処理（kinsoku shori）和混植（mixed typesetting）规则，可让AI Agent生成精准的日文UI。

What This Project Does

项目功能

DESIGN.md is a plain-text markdown file AI coding agents read to generate consistent UI. This project extends that format for Japanese services, covering:

CJK font-family fallback chains (和文 → 欧文 → generic)
Higher line-height (1.5–2.0 vs Western 1.4–1.5)
Japanese letter-spacing (
```
0.04em
```
–
```
0.1em
```
for body text)
Kinsoku shori (禁則処理) — CJK punctuation line-break rules
OpenType features (
```
palt
```
,
```
kern
```
) for proportional typesetting
Mixed typesetting (混植) — combining Japanese and Latin typefaces

24 reference DESIGN.md files are included: Apple Japan, MUJI, Mercari, SmartHR, freee, note, LINE, Rakuten, Qiita, Zenn, pixiv, and more.

DESIGN.md是AI编码Agent用于生成一致UI的纯文本Markdown文件。本项目针对日文服务扩展了该格式，涵盖以下内容：

CJK字体族回退链（日文 → 英文 → 通用字体）
更大的行高（1.5–2.0，对比西方的1.4–1.5）
日文字符间距（正文为
```
0.04em
```
–
```
0.1em
```
）
禁則処理（kinsoku shori）——CJK标点换行规则
OpenType特性（
```
palt
```
、
```
kern
```
用于比例排版）
混植（mixed typesetting）——日文与西文字体结合

项目包含24个参考DESIGN.md文件，涉及Apple Japan、无印良品（MUJI）、Mercari、SmartHR、freee、note、LINE、乐天（Rakuten）、Qiita、Zenn、pixiv等品牌。

Installation / Setup

安装/设置

Clone or reference the repository directly — no build step required.

bash

git clone https://github.com/kzhrknt/awesome-design-md-jp.git
cd awesome-design-md-jp

Copy the template into your project:

bash

cp template/DESIGN.md your-project/DESIGN.md

Or reference an existing service as a starting point:

bash

cp design-md/muji/DESIGN.md your-project/DESIGN.md

直接克隆或引用仓库即可，无需构建步骤。

bash

git clone https://github.com/kzhrknt/awesome-design-md-jp.git
cd awesome-design-md-jp

将模板复制到你的项目中：

bash

cp template/DESIGN.md your-project/DESIGN.md

也可以参考现有品牌的文件作为起点：

bash

cp design-md/muji/DESIGN.md your-project/DESIGN.md

then edit for your brand

然后根据你的品牌进行编辑


Place `DESIGN.md` at your project root alongside `AGENTS.md`:

your-project/ ├── AGENTS.md # how to build ├── DESIGN.md # how it should look and feel ← add this ├── src/ └── ...

---


将`DESIGN.md`放在项目根目录，与`AGENTS.md`同级：

your-project/ ├── AGENTS.md # 构建指南 ├── DESIGN.md # UI外观与风格规范 ← 添加此文件 ├── src/ └── ...

---

DESIGN.md Template Structure

DESIGN.md模板结构

The template extends the standard Google Stitch 9-section format with Japanese typography subsections.

该模板在标准Google Stitch的9节格式基础上，扩展了日文排版相关小节。

Full Template

完整模板

markdown

undefined

markdown

undefined

DESIGN.md

1. Overview

1. 概述

Brief description of the product, target users, and overall visual direction.

产品简介、目标用户及整体视觉方向。

2. Color Palette

2. 调色板

Token	Value	Usage
`--color-primary`	`#0066CC`	CTAs, links
`--color-bg`	`#FFFFFF`	Page background
`--color-text`	`#1A1A1A`	Body text
`--color-muted`	`#666666`	Secondary text

标识	值	用途
`--color-primary`	`#0066CC`	按钮、链接
`--color-bg`	`#FFFFFF`	页面背景
`--color-text`	`#1A1A1A`	正文
`--color-muted`	`#666666`	次要文本

3. Typography

3. 排版

3.1 Font Families

3.1 字体族

和文（Japanese）

css

font-family:
  "Noto Sans JP",       /* Google Fonts — preferred web font */
  "Hiragino Kaku Gothic ProN", /* macOS / iOS */
  "Hiragino Sans",      /* macOS newer */
  "Meiryo",             /* Windows */
  "Yu Gothic",          /* Windows 8.1+ */
  sans-serif;

欧文（Latin / alphanumeric）

css

font-family:
  "Inter",              /* preferred web font for Latin */
  -apple-system,
  BlinkMacSystemFont,
  "Segoe UI",
  sans-serif;

混植（Mixed typesetting） Use Japanese font as base; Latin glyphs rendered by Inter layered on top via

@font-face

unicode-range.

和文（日文）

css

font-family:
  "Noto Sans JP",       /* Google Fonts — 首选网页字体 */
  "Hiragino Kaku Gothic ProN", /* macOS / iOS */
  "Hiragino Sans",      /* 新版macOS */
  "Meiryo",             /* Windows */
  "Yu Gothic",          /* Windows 8.1+ */
  sans-serif;

欧文（西文/字母数字）

css

font-family:
  "Inter",              /* 西文首选网页字体 */
  -apple-system,
  BlinkMacSystemFont,
  "Segoe UI",
  sans-serif;

混植（混合排版） 以日文字体为基础；通过

@font-face

的unicode-range属性，让西文字符由Inter字体渲染。

3.2 Type Scale

3.2 字号层级

Role	Size	Weight	Line-height	Letter-spacing
Display	2.5rem	700	1.4	-0.02em
Heading 1	2rem	700	1.5	-0.01em
Heading 2	1.5rem	600	1.5	0
Body	1rem	400	1.8	0.04em
Small	0.875rem	400	1.7	0.04em
Caption	0.75rem	400	1.6	0.06em

角色	字号	字重	行高	字符间距
标题展示	2.5rem	700	1.4	-0.02em
一级标题	2rem	700	1.5	-0.01em
二级标题	1.5rem	600	1.5	0
正文	1rem	400	1.8	0.04em
小号文本	0.875rem	400	1.7	0.04em
说明文字	0.75rem	400	1.6	0.06em

3.3 Japanese Typography Rules

3.3 日文排版规则

Line-height: Use 1.7–2.0 for body text (wider than Western 1.4–1.5).

Letter-spacing: Apply

0.04em

–

0.1em

to body Japanese text; headings may use

or slightly negative.

Kinsoku shori (禁則処理):

css

word-break: normal;
overflow-wrap: break-word;
line-break: strict;          /* enforce JIS kinsoku rules */

行頭禁則文字 (cannot start a line):
```
）」』】、。・：；？！…―
```
行末禁則文字 (cannot end a line):
```
（「『【
```

OpenType features:

css

font-feature-settings: "palt" 1, "kern" 1;
/* palt = proportional alternate widths for punctuation */
/* kern = kerning */

Text rendering:

css

-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
text-rendering: optimizeLegibility;

行高： 正文使用1.7–2.0（比西方的1.4–1.5更宽松）。

字符间距： 日文正文应用

0.04em

–

0.1em

；标题可使用0或轻微负值。

禁則処理（kinsoku shori）：

css

word-break: normal;
overflow-wrap: break-word;
line-break: strict;          /* 强制执行JIS禁则规则 */

行頭禁則文字（不能位于行首）：
```
）」』】、。・：；？！…―
```
行末禁則文字（不能位于行尾）：
```
（「『【
```

OpenType特性：

css

font-feature-settings: "palt" 1, "kern" 1;
/* palt = 标点的比例替代宽度 */
/* kern = 字距调整 */

文本渲染：

css

-webkit-font-smoothing: antialiased;
-moz-osx-font-smoothing: grayscale;
text-rendering: optimizeLegibility;

4. Spacing & Layout

4. 间距与布局

Base unit:

8px

Token	Value
`--space-xs`	`4px`
`--space-sm`	`8px`
`--space-md`	`16px`
`--space-lg`	`32px`
`--space-xl`	`64px`

Max content width:

1200px

with

24px

horizontal padding on mobile.

基础单位：

8px

标识	值
`--space-xs`	`4px`
`--space-sm`	`8px`
`--space-md`	`16px`
`--space-lg`	`32px`
`--space-xl`	`64px`

内容最大宽度：

1200px

，移动端左右内边距为

24px

。

5. Components

5. 组件

[Describe buttons, inputs, cards, navigation patterns]

[描述按钮、输入框、卡片、导航等组件样式]

6. Icons & Imagery

6. 图标与图像

[Icon set, image ratios, illustration style]

[图标集、图片比例、插画风格]

7. Motion & Animation

7. 动效与动画

[Transition durations, easing curves]

[过渡时长、缓动曲线]

8. Responsive Breakpoints

8. 响应式断点

Name	Width
Mobile	< 768px
Tablet	768–1024px
Desktop	> 1024px

名称	宽度范围
移动端	< 768px
平板端	768–1024px
桌面端	> 1024px

9. Accessibility

9. 无障碍设计

Contrast ratio: minimum 4.5:1 for body text
Focus indicators: visible outline
Tap targets: minimum 44×44px

---

对比度：正文文本最低4.5:1
焦点指示器：可见的轮廓线
点击目标：最小44×44px

---

Reference DESIGN.md Examples

参考DESIGN.md示例

MUJI Style (Minimalist Retail)

无印良品（MUJI）风格（极简零售）

markdown

undefined

markdown

undefined

Color Palette

调色板

Token	Value
`--color-primary`	`#000000`
`--color-bg`	`#F5F5F0`
`--color-text`	`#333333`
`--color-border`	`#DDDDDD`

标识	值
`--color-primary`	`#000000`
`--color-bg`	`#F5F5F0`
`--color-text`	`#333333`
`--color-border`	`#DDDDDD`

Typography

排版

Font Stack

字体栈

css

font-family:
  "Noto Serif JP",
  "Hiragino Mincho ProN",
  "Yu Mincho",
  "MS Mincho",
  Georgia,
  serif;

css

font-family:
  "Noto Serif JP",
  "Hiragino Mincho ProN",
  "Yu Mincho",
  "MS Mincho",
  Georgia,
  serif;

Body

正文

font-size: 15px
line-height: 2.0
letter-spacing: 0.08em
font-feature-settings: "palt" 1

font-size: 15px
line-height: 2.0
letter-spacing: 0.08em
font-feature-settings: "palt" 1

Design Principles

设计原则

徹底した余白（generous whitespace as design element）
無彩色を基調（achromatic base palette）
装飾を排除（eliminate decoration）

undefined

徹底した余白（将充足留白作为设计元素）
無彩色を基調（以无彩色为基础调色板）
装飾を排除（去除多余装饰）

undefined

SmartHR Style (B2B SaaS)

SmartHR风格（B2B SaaS）

markdown

undefined

markdown

undefined

Color Palette

调色板

Token	Value
`--color-primary`	`#0077C8`
`--color-success`	`#28A745`
`--color-warning`	`#FFC107`
`--color-danger`	`#DC3545`
`--color-bg`	`#F8F9FA`
`--color-text`	`#212529`

标识	值
`--color-primary`	`#0077C8`
`--color-success`	`#28A745`
`--color-warning`	`#FFC107`
`--color-danger`	`#DC3545`
`--color-bg`	`#F8F9FA`
`--color-text`	`#212529`

Typography

排版

Font Stack

字体栈

css

font-family:
  "Hiragino Kaku Gothic ProN",
  "Hiragino Sans",
  Meiryo,
  "Yu Gothic",
  sans-serif;

css

font-family:
  "Hiragino Kaku Gothic ProN",
  "Hiragino Sans",
  Meiryo,
  "Yu Gothic",
  sans-serif;

Type Scale

字号层级

Display: 28px / weight 700 / line-height 1.4 / ls 0
Body: 14px / weight 400 / line-height 1.8 / ls 0.04em
Label: 12px / weight 500 / line-height 1.6 / ls 0.06em
Note: Dense information layout — prioritize readability at small sizes

undefined

Display: 28px / weight 700 / line-height 1.4 / ls 0
Body: 14px / weight 400 / line-height 1.8 / ls 0.04em
Label: 12px / weight 500 / line-height 1.6 / ls 0.06em
Note: 信息密集型布局——优先保证小字号下的可读性

undefined

note Style (Media / Publishing)

note风格（媒体/出版）

markdown

undefined

markdown

undefined

Typography

排版

Font Stack

字体栈

css

/* Heading */
font-family: "Noto Serif JP", "Hiragino Mincho ProN", serif;

/* Body */  
font-family: "Noto Sans JP", "Hiragino Kaku Gothic ProN", sans-serif;

css

/* 标题 */
font-family: "Noto Serif JP", "Hiragino Mincho ProN", serif;

/* 正文 */  
font-family: "Noto Sans JP", "Hiragino Kaku Gothic ProN", sans-serif;

Reading Typography

阅读排版

Body: 18px / line-height 1.9 / letter-spacing 0.04em
Max line length: 38–40 chars (約38文字で折り返し)
Paragraph spacing: 1.5em
Drop cap on first paragraph of long-form content

---

Body: 18px / line-height 1.9 / letter-spacing 0.04em
最大行宽：38–40字符（約38文字で折り返し）
段落间距：1.5em
长内容首段落使用首字下沉

---

CSS Boilerplate for Japanese UI

日文UI CSS模板

Use this as a starting point in any project informed by these DESIGN.md files:

css

/* ===== Japanese Typography Base ===== */

:root {
  /* Font families */
  --font-ja-sans: "Noto Sans JP", "Hiragino Kaku Gothic ProN",
    "Hiragino Sans", "Meiryo", "Yu Gothic", sans-serif;
  --font-ja-serif: "Noto Serif JP", "Hiragino Mincho ProN",
    "Yu Mincho", "MS Mincho", Georgia, serif;
  --font-en: "Inter", -apple-system, BlinkMacSystemFont,
    "Segoe UI", sans-serif;

  /* Type scale */
  --text-display: 2.5rem;
  --text-h1: 2rem;
  --text-h2: 1.5rem;
  --text-h3: 1.25rem;
  --text-body: 1rem;
  --text-sm: 0.875rem;
  --text-xs: 0.75rem;

  /* Line heights */
  --lh-tight: 1.4;   /* headings */
  --lh-normal: 1.8;  /* body */
  --lh-loose: 2.0;   /* long-form reading */

  /* Letter spacing */
  --ls-tight: -0.02em;
  --ls-normal: 0.04em;
  --ls-wide: 0.08em;
}

/* Base Japanese text rendering */
body {
  font-family: var(--font-ja-sans);
  font-size: var(--text-body);
  line-height: var(--lh-normal);
  letter-spacing: var(--ls-normal);
  font-feature-settings: "palt" 1, "kern" 1;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  text-rendering: optimizeLegibility;
}

/* Kinsoku shori */
p, li, td, th {
  word-break: normal;
  overflow-wrap: break-word;
  line-break: strict;
}

/* Headings */
h1, h2, h3, h4, h5, h6 {
  line-height: var(--lh-tight);
  letter-spacing: var(--ls-tight);
  font-feature-settings: "palt" 1;
}

/* Mixed typesetting — Latin numerals and ASCII via Inter */
@font-face {
  font-family: "Inter-for-JP";
  src: url("https://fonts.gstatic.com/s/inter/v13/...") format("woff2");
  unicode-range: U+0020-007E; /* Basic Latin only */
}

可将以下代码作为项目起点，配合本项目的DESIGN.md文件使用：

css

/* ===== 日文排版基础 ===== */

:root {
  /* 字体族 */
  --font-ja-sans: "Noto Sans JP", "Hiragino Kaku Gothic ProN",
    "Hiragino Sans", "Meiryo", "Yu Gothic", sans-serif;
  --font-ja-serif: "Noto Serif JP", "Hiragino Mincho ProN",
    "Yu Mincho", "MS Mincho", Georgia, serif;
  --font-en: "Inter", -apple-system, BlinkMacSystemFont,
    "Segoe UI", sans-serif;

  /* 字号层级 */
  --text-display: 2.5rem;
  --text-h1: 2rem;
  --text-h2: 1.5rem;
  --text-h3: 1.25rem;
  --text-body: 1rem;
  --text-sm: 0.875rem;
  --text-xs: 0.75rem;

  /* 行高 */
  --lh-tight: 1.4;   /* 标题 */
  --lh-normal: 1.8;  /* 正文 */
  --lh-loose: 2.0;   /* 长文本阅读 */

  /* 字符间距 */
  --ls-tight: -0.02em;
  --ls-normal: 0.04em;
  --ls-wide: 0.08em;
}

/* 基础日文文本渲染 */
body {
  font-family: var(--font-ja-sans);
  font-size: var(--text-body);
  line-height: var(--lh-normal);
  letter-spacing: var(--ls-normal);
  font-feature-settings: "palt" 1, "kern" 1;
  -webkit-font-smoothing: antialiased;
  -moz-osx-font-smoothing: grayscale;
  text-rendering: optimizeLegibility;
}

/* 禁則処理 */
p, li, td, th {
  word-break: normal;
  overflow-wrap: break-word;
  line-break: strict;
}

/* 标题 */
h1, h2, h3, h4, h5, h6 {
  line-height: var(--lh-tight);
  letter-spacing: var(--ls-tight);
  font-feature-settings: "palt" 1;
}

/* 混植排版——西文数字与ASCII字符使用Inter字体 */
@font-face {
  font-family: "Inter-for-JP";
  src: url("https://fonts.gstatic.com/s/inter/v13/...") format("woff2");
  unicode-range: U+0020-007E; /* 仅基础西文字符 */
}

Font Loading (Google Fonts)

字体加载（Google Fonts）

html

<!-- In <head> — preconnect for performance -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>

<!-- Noto Sans JP (recommended for most Japanese UI) -->
<link href="https://fonts.googleapis.com/css2?family=Noto+Sans+JP:wght@400;500;700&display=swap" rel="stylesheet">

<!-- Noto Serif JP (for editorial / reading-focused UI) -->
<link href="https://fonts.googleapis.com/css2?family=Noto+Serif+JP:wght@400;700&display=swap" rel="stylesheet">

<!-- Combined with Inter for mixed typesetting -->
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Noto+Sans+JP:wght@400;500;700&display=swap" rel="stylesheet">

html

<!-- 在<head>中添加——预连接以提升性能 -->
<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>

<!-- Noto Sans JP（大多数日文UI推荐使用） -->
<link href="https://fonts.googleapis.com/css2?family=Noto+Sans+JP:wght@400;500;700&display=swap" rel="stylesheet">

<!-- Noto Serif JP（适用于编辑/阅读类UI） -->
<link href="https://fonts.googleapis.com/css2?family=Noto+Serif+JP:wght@400;700&display=swap" rel="stylesheet">

<!-- 与Inter结合用于混植排版 -->
<link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600;700&family=Noto+Sans+JP:wght@400;500;700&display=swap" rel="stylesheet">

Common Patterns by Service Category

按服务分类的通用模式

Consumer App (LINE, Mercari)

消费类应用（LINE、Mercari）

markdown

- Font: Noto Sans JP + system fallbacks
- Line-height body: 1.7
- Letter-spacing: 0.04em
- Primary color: brand-specific bold color
- Mobile-first, 375px base
- Tap targets: 48px minimum

markdown

- 字体：Noto Sans JP + 系统回退字体
- 正文行高：1.7
- 字符间距：0.04em
- 主色调：品牌专属醒目颜色
- 移动端优先，基础宽度375px
- 点击目标：最小48px

B2B SaaS (SmartHR, freee, Cybozu)

B2B SaaS（SmartHR、freee、Cybozu）

markdown

- Font: Hiragino Kaku Gothic ProN preferred (system), Noto Sans JP web
- Line-height body: 1.8 (dense data tables may use 1.5)
- Letter-spacing: 0.04em
- Neutral palette with clear action color
- Information density: high
- Data tables with sticky headers

markdown

- 字体：首选系统字体Hiragino Kaku Gothic ProN，网页字体可选Noto Sans JP
- 正文行高：1.8（密集数据表可使用1.5）
- 字符间距：0.04em
- 中性调色板搭配清晰的操作色
- 信息密度：高
- 带固定表头的数据表

Editorial / Media (note, WIRED.jp, Qiita, Zenn)

编辑/媒体类（note、WIRED.jp、Qiita、Zenn）

markdown

- Font: Noto Serif JP or Hiragino Mincho for body; sans for UI chrome
- Line-height body: 1.9–2.0
- Letter-spacing: 0.06em
- Max line length: 38–42 characters (約40文字)
- Code blocks: monospace with JIS-compatible fallback

markdown

- 字体：正文使用Noto Serif JP或Hiragino Mincho；UI控件使用无衬线字体
- 正文行高：1.9–2.0
- 字符间距：0.06em
- 最大行宽：38–42字符（約40文字）
- 代码块：等宽字体搭配兼容JIS的回退字体

Retail / Lifestyle (MUJI, Toyota)

零售/生活方式类（MUJI、丰田）

markdown

- Font: Serif for premium feel; sans for utility text
- Line-height: 2.0 (generous whitespace)
- Letter-spacing: 0.08em (airy)
- Achromatic or very restrained palette
- High-quality imagery as primary content

markdown

- 字体：正文使用衬线字体营造高端感；实用文本使用无衬线字体
- 行高：2.0（充足留白）
- 字符间距：0.08em（宽松）
- 无彩色或极简调色板
- 高质量图像作为核心内容

Viewing Previews

预览查看

Each DESIGN.md has an accompanying

preview.html

that visualizes design tokens:

bash

undefined

每个DESIGN.md都配有对应的

preview.html

，可可视化展示设计标识：

bash

undefined

Open any preview locally

本地打开任意预览文件

open design-md/muji/preview.html open design-md/smarthr/preview.html

Or view the full gallery

或查看完整预览画廊

open design-md/gallery.html

or visit: https://kzhrknt.github.io/awesome-design-md-jp/gallery.html

或访问在线地址：https://kzhrknt.github.io/awesome-design-md-jp/gallery.html

---

---

Telling an AI Agent to Use DESIGN.md

告知AI Agent使用DESIGN.md

When the file is at your project root, reference it explicitly in your prompt:

Read DESIGN.md and create a Japanese landing page hero section following 
the typography and color specifications defined there. Use the exact 
font-family fallback chain, line-height, and letter-spacing values specified.
Implement kinsoku shori with line-break: strict.

For Claude Code / Cursor, you can also reference specific sections:

Following DESIGN.md section 3.3 (Japanese Typography Rules), update the 
global CSS to add proper kinsoku shori, font-feature-settings, and 
-webkit-font-smoothing for all text elements.

当文件位于项目根目录时，在提示词中明确引用：

读取DESIGN.md并按照其中定义的排版和颜色规范创建日文着陆页的Hero区域。使用指定的精确字体族回退链、行高和字符间距值。通过line-break: strict实现禁則処理。

对于Claude Code / Cursor，还可以引用特定章节：

遵循DESIGN.md的3.3节（日文排版规则），更新全局CSS为所有文本元素添加正确的禁則処理、font-feature-settings和-webkit-font-smoothing。

Troubleshooting

故障排除

AI generates wrong Japanese fonts

AI生成错误的日文字体

Problem: Agent uses

"MS Gothic"

or generic

sans-serif

only.
Fix: Make font-family fallback chain explicit in DESIGN.md with comments explaining each fallback's platform target.

markdown

undefined

问题： Agent仅使用

"MS Gothic"

或通用

sans-serif

。
解决方法： 在DESIGN.md中明确字体族回退链，并添加注释说明每个回退字体对应的平台。

markdown

undefined

Font Stack (REQUIRED — do not simplify)

字体栈（必填——请勿简化）

css

font-family:
  "Noto Sans JP",              /* web font — always load via Google Fonts */
  "Hiragino Kaku Gothic ProN", /* macOS / iOS system */
  "Hiragino Sans",             /* macOS 10.11+ */
  "Meiryo",                    /* Windows */
  "Yu Gothic",                 /* Windows 8.1+ */
  sans-serif;                  /* absolute fallback */

undefined

css

font-family:
  "Noto Sans JP",              /* 网页字体——务必通过Google Fonts加载 */
  "Hiragino Kaku Gothic ProN", /* macOS / iOS系统字体 */
  "Hiragino Sans",             /* macOS 10.11+ */
  "Meiryo",                    /* Windows */
  "Yu Gothic",                 /* Windows 8.1+ */
  sans-serif;                  /* 最终回退字体 */

undefined

Line-height too tight on Japanese text

日文文本行高过窄

Problem: Agent uses

line-height: 1.5

from a Western design system.
Fix: Specify explicitly in DESIGN.md with a note:

markdown

**IMPORTANT:** Japanese body text requires line-height 1.7–2.0, 
NOT the Western default of 1.4–1.5. Use 1.8 for standard body copy.

问题： Agent使用西方设计系统的

line-height: 1.5

。
解决方法： 在DESIGN.md中明确指定并添加说明：

markdown

**重要提示：** 日文正文需要1.7–2.0的行高，而非西方默认的1.4–1.5。标准正文请使用1.8。

Punctuation appearing at line start/end incorrectly

标点错误地出现在行首/行尾

Problem:

。

、

wraps to start of next line;

「

hangs at end.
Fix: Add kinsoku rules explicitly:

markdown

undefined

问题：

。

或

、

换行到下一行开头；

「

留在行尾。
解决方法： 明确添加禁则规则：

markdown

undefined

Kinsoku Shori (禁則処理) — REQUIRED

禁則処理（必填）

css

p { line-break: strict; word-break: normal; overflow-wrap: break-word; }

Characters that MUST NOT start a line: ）」』】、。・：；？！…― Characters that MUST NOT end a line: （「『【

undefined

css

p { line-break: strict; word-break: normal; overflow-wrap: break-word; }

禁止出现在行首的字符：）」』】、。・：；？！…― 禁止出现在行尾的字符：（「『【

undefined

Proportional punctuation not activating

比例标点未生效

Problem: Japanese commas and periods render full-width, looking too spaced.
Fix: Ensure font-feature-settings is applied:

markdown

font-feature-settings: "palt" 1, "kern" 1;
/* palt = proportional alternates — narrows full-width punctuation */
/* Required for Noto Sans JP, Hiragino fonts */

问题： 日文逗号和句号显示为全角，间距过大。
解决方法： 确保应用font-feature-settings：

markdown

font-feature-settings: "palt" 1, "kern" 1;
/* palt = 比例替代——缩小全角标点宽度 */
/* Noto Sans JP、Hiragino字体必填 */

Mixed Japanese/Latin spacing looks wrong

日文/西文混合排版间距异常

Problem: Latin letters inside Japanese text have no breathing room.
Fix: Document the spacing rule in DESIGN.md:

markdown

undefined

问题： 日文文本中的西文字符没有足够间距。
解决方法： 在DESIGN.md中记录间距规则：

markdown

undefined

Mixed Typesetting (混植)

混植排版

Insert a thin space (U+202F or 0.25em margin) between Japanese and Latin runs
OR use CSS:
```
ruby { margin: 0 0.1em; }
```
pattern
Preferred: use a font that handles this (Noto CJK with auto-spacing)

---

在日文与西文段落之间插入窄空格（U+202F或0.25em边距）
或使用CSS：
```
ruby { margin: 0 0.1em; }
```
模式
首选方案：使用支持自动间距的字体（如Noto CJK）

---

Contributing a New DESIGN.md

贡献新的DESIGN.md

bash

undefined

bash

undefined

1. Create directory

1. 创建目录

mkdir design-md/your-service

2. Copy template

2. 复制模板

cp template/DESIGN.md design-md/your-service/DESIGN.md

3. Fill in all 9 sections including Japanese typography subsections

3. 填写所有9个章节，包括日文排版相关小节

4. Create preview.html from the preview template

4. 从预览模板创建preview.html

cp template/preview.html design-md/your-service/preview.html

5. Take a screenshot at 1280×800 → preview-screenshot.png

5. 截取1280×800的截图 → preview-screenshot.png


Required sections for acceptance:
- ✅ Color palette with CSS custom property names
- ✅ Japanese font-family fallback chain with platform comments
- ✅ Type scale table with line-height AND letter-spacing columns
- ✅ Kinsoku shori CSS rules
- ✅ font-feature-settings specification
- ✅ Responsive breakpoints


接受贡献所需的必填章节：
- ✅ 带CSS自定义属性名称的调色板
- ✅ 带平台注释的日文字体族回退链
- ✅ 包含行高和字符间距列的字号层级表
- ✅ 禁則処理CSS规则
- ✅ font-feature-settings规范
- ✅ 响应式断点