awesome-design-md-jp

Q: How do I install awesome-design-md-jp?

Run npx skills add https://github.com/reason-machines/trending-skills --skill awesome-design-md-jp in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/awesome-design-md-jp/ (personal) or .claude/skills/awesome-design-md-jp/ (project).

by reason-machinesFrontend & Design

Create accurate Japanese UI DESIGN.md files for AI agents with proper CJK typography, font stacks, line-height, kinsoku shori, and mixed typesetting rules.

Installs: 670
Last 24h: —
Trending rank: —
Security: Not audited

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/reason-machines/trending-skills --skill awesome-design-md-jp

01
Install
Run the command in your project. The CLI asks which agents to install for.
02
Describe the task
Ask your agent for something this skill covers. It loads awesome-design-md-jp automatically when relevant.
03
Review the result
The agent follows the SKILL.md steps, scripts and references bundled with the skill.

SKILL.md

The instructions your agent reads when the skill is triggered.

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.git
cd 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. Overview
Brief 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）**
```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）

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

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

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

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.

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

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

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

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


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

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)
```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 */


### 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
```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: （「『【


### 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 */

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 directory
mkdir design-md/your-service

# 2. Copy template
cp 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 template
cp 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

FAQ

What does the awesome-design-md-jp skill do?

Create accurate Japanese UI DESIGN.md files for AI agents with proper CJK typography, font stacks, line-height, kinsoku shori, and mixed typesetting rules.

How do I install awesome-design-md-jp?

Run npx skills add https://github.com/reason-machines/trending-skills --skill awesome-design-md-jp in your project. The skills CLI detects the agents you use and copies the skill into the right folder. For Claude Code you can also place the skill folder at ~/.claude/skills/awesome-design-md-jp/ (personal) or .claude/skills/awesome-design-md-jp/ (project).

Which AI agents can use awesome-design-md-jp?

Any agent that supports the open Agent Skills format (a folder with a SKILL.md file), including Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Cline, OpenCode and more.

Is awesome-design-md-jp safe to install?

No partner security audit is available yet. Skills can run commands and scripts, so read the SKILL.md and any bundled files before installing.

Who maintains awesome-design-md-jp?

It is published by reason-machines in reason-machines/trending-skills. It has 670 recorded installs.

Popular frontend & design skills

View category →

setup-matt-pocock-skills

mattpocock/skills

Configure this repo for the engineering skills: set up its issue tracker, triage label vocabulary, and domain doc layout. Run once before first use of the other engineering skills.

Frontend & Design1.1M installs

frontend-design

anthropics/skills

Guidance for distinctive, intentional visual design when building new UI or reshaping an existing one. Helps with aesthetic direction, typography, and making choices that don't read as templated defaults.

OfficialFrontend & Design1M installs

hyperframes-animation

heygen-com/hyperframes

All animation knowledge for HyperFrames — atomic motion rules, multi-phase scene blueprints, scene transitions, broader motion-design techniques, AND the seven runtime adapters (GSAP default, plus Lottie, Three.js, Anime.js, CSS keyframes, Web Animations API, TypeGPU). Use for any motion or animation task: pick 2-4 rules and compose, or load a blueprint, or look up runtime-specific API (e.g. GSAP eases / Lottie player / Three.js mixer). Also covers auditing an existing composition's choreography (animation map) and 24 named text-animation effects. HyperFrames-native: single paused timeline, seek-safe, deterministic.

Frontend & Design1M installs

prototype

mattpocock/skills

Build a throwaway prototype to answer a design question. Use when the user wants to sanity-check whether a state model or logic feels right, or explore what a UI should look like.

Frontend & Design999.2K installs

hyperframes-core

heygen-com/hyperframes

The HyperFrames composition contract — build one renderable project. Use for composition structure, the data- timing attributes, class="clip", tracks, sub-compositions, variables, framework-owned media playback, deterministic-render rules, and validation. Read before writing composition HTML.

Frontend & Design930.5K installs

vercel-react-best-practices

vercel-labs/agent-skills

React and Next.js performance optimization guidelines from Vercel Engineering. This skill should be used when writing, reviewing, or refactoring React/Next.js code to ensure optimal performance patterns. Triggers on tasks involving React components, Next.js pages, data fetching, bundle optimization, or performance improvements.

OfficialFrontend & Design843.1K installs

awesome-design-md-jp

Install

Install

Describe the task

Review the result

SKILL.md

Awesome Design MD JP

What This Project Does

Installation / Setup

DESIGN.md Template Structure

Full Template

3.2 Type Scale

3.3 Japanese Typography Rules

4. Spacing & Layout

5. Components

6. Icons & Imagery

7. Motion & Animation

8. Responsive Breakpoints

9. Accessibility

Body

Design Principles

Type Scale

Reading Typography

Font Loading (Google Fonts)

Common Patterns by Service Category

Consumer App (LINE, Mercari)

B2B SaaS (SmartHR, freee, Cybozu)

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

Retail / Lifestyle (MUJI, Toyota)

Viewing Previews

Telling an AI Agent to Use DESIGN.md

Troubleshooting

AI generates wrong Japanese fonts

Punctuation appearing at line start/end incorrectly

Mixed Japanese/Latin spacing looks wrong

Contributing a New DESIGN.md

FAQ

More from reason-machines/trending-skills

Popular frontend & design skills