Awesome Design Md Jp

Awesome Design MD JP

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.

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.

Installation / Setup

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

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

Copy the template into your project:

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

Or reference an existing service as a starting point:

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 Template Structure

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

Full Template

# DESIGN.md
## 1. OverviewBrief description of the product, target users, and overall visual direction.
## 2. Color Palette
| Token           | Value     | Usage            ||-----------------|-----------|------------------|| `--color-primary` | `#0066CC` | CTAs, links      || `--color-bg`     | `#FFFFFF` | Page background  || `--color-text`   | `#1A1A1A` | Body text        || `--color-muted`  | `#666666` | Secondary text   |
## 3. Typography
### 3.1 Font Families
**和文（Japanese）**```cssfont-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）

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.

3.2 Type Scale

3.3 Japanese Typography Rules

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 0 or slightly negative.

Kinsoku shori (禁則処理):

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

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

OpenType features:

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

Text rendering:

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

4. Spacing & Layout

Base unit: 8px

Max content width: 1200px with 24px horizontal padding on mobile.

5. Components

[Describe buttons, inputs, cards, navigation patterns]

6. Icons & Imagery

[Icon set, image ratios, illustration style]

7. Motion & Animation

[Transition durations, easing curves]

8. Responsive Breakpoints

9. Accessibility

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

---
## Reference DESIGN.md Examples
### MUJI Style (Minimalist Retail)
```markdown## Color Palette| Token              | Value     ||--------------------|-----------|| `--color-primary`  | `#000000` || `--color-bg`       | `#F5F5F0` || `--color-text`     | `#333333` || `--color-border`   | `#DDDDDD` |
## Typography
### Font Stack```cssfont-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

Design Principles

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

### SmartHR Style (B2B SaaS)
```markdown## Color Palette| Token             | Value     ||-------------------|-----------|| `--color-primary` | `#0077C8` || `--color-success` | `#28A745` || `--color-warning` | `#FFC107` || `--color-danger`  | `#DC3545` || `--color-bg`      | `#F8F9FA` || `--color-text`    | `#212529` |
## Typography
### Font Stack```cssfont-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

### note Style (Media / Publishing)
```markdown## 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;

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

---
## CSS Boilerplate for Japanese UI
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 */}

Font Loading (Google Fonts)

<!-- 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">

Common Patterns by Service Category

Consumer App (LINE, Mercari)

- 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

B2B SaaS (SmartHR, freee, Cybozu)

- 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

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

- 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

Retail / Lifestyle (MUJI, Toyota)

- 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

Viewing Previews

Each DESIGN.md has an accompanying preview.html that visualizes design tokens:

# Open any preview locallyopen design-md/muji/preview.htmlopen design-md/smarthr/preview.html
# Or view the full galleryopen design-md/gallery.html# or visit: https://kzhrknt.github.io/awesome-design-md-jp/gallery.html

Telling an AI Agent to Use 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.

Troubleshooting

AI generates wrong Japanese fonts

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.

### Font Stack (REQUIRED — do not simplify)```cssfont-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 */

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

Punctuation appearing at line start/end incorrectly

Problem: 。 or 、 wraps to start of next line; 「 hangs at end.
Fix: Add kinsoku rules explicitly:

### Kinsoku Shori (禁則処理) — REQUIRED```cssp { line-break: strict; word-break: normal; overflow-wrap: break-word; }

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

### Proportional punctuation not activating**Problem:** Japanese commas and periods render full-width, looking too spaced.  **Fix:** Ensure font-feature-settings is applied:
```markdownfont-feature-settings: "palt" 1, "kern" 1;/* palt = proportional alternates — narrows full-width punctuation *//* Required for Noto Sans JP, Hiragino fonts */

Mixed Japanese/Latin spacing looks wrong

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

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

Contributing a New DESIGN.md

# 1. Create directorymkdir design-md/your-service
# 2. Copy templatecp template/DESIGN.md design-md/your-service/DESIGN.md
# 3. Fill in all 9 sections including Japanese typography subsections# 4. Create preview.html from the preview templatecp template/preview.html design-md/your-service/preview.html
# 5. Take a screenshot at 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