awesome-design-md-jp

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

Run npx skills add https://github.com/reason-machines/design-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

Generate accurate Japanese UI with proper CJK typography using DESIGN.md specifications for 186+ Japanese web services

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

Install

Works with every agent the skills CLI supports.

npx skills add https://github.com/reason-machines/design-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

Skill by ara.so — Design Skills collection.

What This Project Does

Awesome Design MD JP is a curated collection of DESIGN.md files for 186+ Japanese web services, enabling AI agents to generate accurate Japanese UI with proper CJK typography. It extends the Google Stitch DESIGN.md format with Japanese-specific typographic rules including font stacks, line-height, letter-spacing, OpenType features, and kinsoku shori (禁則処理).

Unlike Western DESIGN.md collections, this addresses fundamental differences in Japanese typography:

Japanese font fallback chains (和文 → 欧文 → generic)
Wider line-height (1.5-2.0 vs 1.4-1.5 for Latin)
Letter-spacing for body text (0.04-0.1em)
Kinsoku shori (禁則処理) for punctuation placement
OpenType features (palt, kern) for proportional typesetting
Mixed script composition rules (和文 + 欧文)

Installation

Clone the repository:

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

No build step required — all DESIGN.md files are ready to use.

Repository Structure

awesome-design-md-jp/
├── design-md/
│   ├── apple/
│   │   ├── DESIGN.md
│   │   ├── preview.html
│   │   └── preview-screenshot.png
│   ├── muji/
│   ├── mercari/
│   ├── studio/
│   └── [186+ other services]/
├── gallery.html          # Visual gallery of all designs
└── README.md

Using DESIGN.md Files

1. Copy to Your Project

Copy the relevant DESIGN.md to your project root:

# Example: Using MUJI design system
cp design-md/muji/DESIGN.md ./DESIGN.md

2. Reference in AI Agent Context

Add to your AI agent's context (.cursorrules, .clinerules, etc.):

Follow the design specifications in DESIGN.md for all UI implementation.
Pay special attention to Japanese typography rules in the Typography section.

3. Direct Integration

Import design tokens programmatically:

// Example: Parsing DESIGN.md for design tokens
import fs from 'fs';
import path from 'path';

function parseDesignMd(filePath) {
  const content = fs.readFileSync(filePath, 'utf-8');
  const tokens = {
    colors: {},
    typography: {},
    spacing: {}
  };
  
  // Extract color palette
  const colorMatch = content.match(/### Color Palette\n\n```css\n([\s\S]*?)```/);
  if (colorMatch) {
    const colorLines = colorMatch[1].split('\n');
    colorLines.forEach(line => {
      const match = line.match(/--([^:]+):\s*([^;]+);/);
      if (match) {
        tokens.colors[match[1]] = match[2].trim();
      }
    });
  }
  
  return tokens;
}

const tokens = parseDesignMd('./DESIGN.md');
console.log(tokens.colors);
// { primary: '#1976d2', background: '#ffffff', ... }

Japanese Typography Patterns

Font Stack Implementation

/* Proper Japanese font fallback chain */
body {
  font-family: 
    "Hiragino Kaku Gothic ProN",  /* macOS Japanese */
    "Hiragino Sans",               /* macOS modern */
    "Yu Gothic Medium",            /* Windows 8.1+ */
    "Meiryo",                      /* Windows fallback */
    "Noto Sans JP",                /* Web font */
    sans-serif;                    /* Generic fallback */
}

/* For mixed Japanese + English content */
.body-text {
  font-family: 
    "Hiragino Kaku Gothic ProN", 
    "Helvetica Neue",              /* English portions */
    Arial, 
    "Noto Sans JP", 
    sans-serif;
}

Line Height for Japanese

/* Japanese text requires more vertical space */
.ja-body {
  line-height: 1.8;  /* vs 1.5 for English */
}

.ja-heading {
  line-height: 1.6;  /* vs 1.2 for English */
}

.ja-caption {
  line-height: 1.7;  /* vs 1.4 for English */
}

Letter Spacing

/* Japanese body text needs slight letter-spacing */
.ja-body {
  letter-spacing: 0.05em;  /* 0.04-0.1em typical */
}

.ja-heading {
  letter-spacing: 0.08em;  /* Slightly more for headings */
}

/* No letter-spacing for Latin text */
.en-text {
  letter-spacing: 0;
}

OpenType Features

/* Enable proportional metrics for Japanese fonts */
.ja-text {
  font-feature-settings: 
    "palt" 1,    /* Proportional alternate metrics */
    "kern" 1;    /* Kerning */
}

/* For vertical text */
.vertical-text {
  writing-mode: vertical-rl;
  font-feature-settings: 
    "vpal" 1,    /* Vertical proportional alternates */
    "vkrn" 1;    /* Vertical kerning */
}

Kinsoku Shori (禁則処理)

/* Proper line-breaking rules for Japanese */
.ja-text {
  word-break: normal;
  overflow-wrap: break-word;
  line-break: strict;           /* Enforce strict kinsoku */
  /* or auto, normal, loose, anywhere, strict */
}

/* Prevent widows/orphans */
.ja-paragraph {
  orphans: 2;
  widows: 2;
}

Common Implementation Patterns

Pattern 1: Apply Complete DESIGN.md System

/* Import design tokens from MUJI DESIGN.md */
:root {
  /* Colors from DESIGN.md */
  --primary: #000000;
  --background: #ffffff;
  --text: #333333;
  --border: #e0e0e0;
  
  /* Typography from DESIGN.md */
  --font-ja: "Hiragino Kaku Gothic ProN", "Yu Gothic Medium", "Noto Sans JP", sans-serif;
  --font-en: "Helvetica Neue", Arial, sans-serif;
  
  /* Spacing from DESIGN.md */
  --space-xs: 4px;
  --space-sm: 8px;
  --space-md: 16px;
  --space-lg: 24px;
  --space-xl: 32px;
}

body {
  font-family: var(--font-ja);
  line-height: 1.8;
  letter-spacing: 0.05em;
  color: var(--text);
  background: var(--background);
}

h1, h2, h3 {
  line-height: 1.6;
  letter-spacing: 0.08em;
}

Pattern 2: Mix Japanese and English Typography

<style>
.mixed-content {
  font-family: "Hiragino Kaku Gothic ProN", "Helvetica Neue", sans-serif;
}

/* Target Japanese characters */
.mixed-content:lang(ja) {
  line-height: 1.8;
  letter-spacing: 0.05em;
}

/* Target English characters */
.mixed-content:lang(en) {
  line-height: 1.5;
  letter-spacing: 0;
}
</style>

<div class="mixed-content">
  <p lang="ja">これは日本語のテキストです。</p>
  <p lang="en">This is English text.</p>
</div>

Pattern 3: Responsive Japanese Typography

/* Mobile-first Japanese typography */
.ja-heading {
  font-size: 1.5rem;
  line-height: 1.6;
  letter-spacing: 0.08em;
}

@media (min-width: 768px) {
  .ja-heading {
    font-size: 2rem;
    line-height: 1.5;
    letter-spacing: 0.1em;
  }
}

@media (min-width: 1024px) {
  .ja-heading {
    font-size: 2.5rem;
    line-height: 1.4;
  }
}

Pattern 4: Component with DESIGN.md Tokens

// React component using parsed DESIGN.md tokens
import React from 'react';
import designTokens from './design-tokens.json';

const JapaneseCard = ({ title, description }) => {
  const styles = {
    card: {
      backgroundColor: designTokens.colors.background,
      border: `1px solid ${designTokens.colors.border}`,
      borderRadius: designTokens.radii.md,
      padding: designTokens.spacing.lg,
    },
    title: {
      fontFamily: designTokens.typography.fontFamily.japanese,
      fontSize: designTokens.typography.fontSize.h3,
      lineHeight: designTokens.typography.lineHeight.heading,
      letterSpacing: designTokens.typography.letterSpacing.heading,
      color: designTokens.colors.text,
      marginBottom: designTokens.spacing.md,
    },
    description: {
      fontFamily: designTokens.typography.fontFamily.japanese,
      fontSize: designTokens.typography.fontSize.body,
      lineHeight: designTokens.typography.lineHeight.body,
      letterSpacing: designTokens.typography.letterSpacing.body,
      color: designTokens.colors.textSecondary,
    },
  };

  return (
    <div style={styles.card}>
      <h3 style={styles.title}>{title}</h3>
      <p style={styles.description}>{description}</p>
    </div>
  );
};

export default JapaneseCard;

Pattern 5: CSS-in-JS with Japanese Typography

// Styled-components with Japanese typography
import styled from 'styled-components';

const JapaneseText = styled.p`
  font-family: "Hiragino Kaku Gothic ProN", "Yu Gothic Medium", "Noto Sans JP", sans-serif;
  line-height: 1.8;
  letter-spacing: 0.05em;
  font-feature-settings: "palt" 1, "kern" 1;
  word-break: normal;
  overflow-wrap: break-word;
  line-break: strict;
`;

const JapaneseHeading = styled.h2`
  font-family: "Hiragino Kaku Gothic ProN", "Yu Gothic Medium", "Noto Sans JP", sans-serif;
  font-size: 2rem;
  line-height: 1.6;
  letter-spacing: 0.08em;
  font-weight: 600;
  font-feature-settings: "palt" 1, "kern" 1;
`;

// Usage
const App = () => (
  <div>
    <JapaneseHeading>見出しテキスト</JapaneseHeading>
    <JapaneseText>
      本文のテキストです。適切な行間と字間が設定されています。
    </JapaneseText>
  </div>
);

Browsing the Collection

View Gallery

Open gallery.html in your browser or visit:

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

Preview Individual Designs

Each design includes a preview.html file:

# Open MUJI preview
open design-md/muji/preview.html

# Open Apple preview
open design-md/apple/preview.html

Available Design Systems (186+)

Tech Companies: Apple, LINE, Mercari, SmartHR, freee, note, Cybozu, Qiita, Zenn, pixiv, connpass, Sansan, PayPay, MOSH, STORES, Wantedly

Media & Publishing: WIRED, 日経電子版, BRUTUS, Casa BRUTUS, Pen Online, POPEYE, ほぼ日

E-commerce & Retail: MUJI, UNIQLO, Rakuten, Tabelog, Cookpad, 一休.com, Snow Peak, JINS, BEAMS

Design & Creative: STUDIO, nendo, Takram, teamLab, 21_21 DESIGN SIGHT, NDC, Droga5

Automotive: Toyota, Mazda, LEXUS

Government: デジタル庁 (Digital Agency)

Traditional & Crafts: とらや, 中川政七商店, 吉田カバン, SOU・SOU, カキモリ

Luxury & Fashion: ISSEY MIYAKE, AURALEE, ミナペルホネン, 45R

Home & Lifestyle: 星野リゾート, BALMUDA, ±0, KINTO, IDÉE, ACTUS, Karimoku New Standard

Beauty & Cosmetics: Shiseido, POLA, OSAJI

And 140+ more…

Configuration

Create design-tokens.json

// scripts/extract-tokens.js
const fs = require('fs');
const path = require('path');

function extractTokens(designMdPath) {
  const content = fs.readFileSync(designMdPath, 'utf-8');
  const tokens = {
    colors: {},
    typography: {
      fontFamily: {},
      fontSize: {},
      lineHeight: {},
      letterSpacing: {}
    },
    spacing: {},
    radii: {}
  };

  // Extract CSS custom properties
  const cssBlocks = content.match(/```css\n([\s\S]*?)```/g) || [];
  cssBlocks.forEach(block => {
    const css = block.replace(/```css\n|```/g, '');
    const lines = css.split('\n');
    
    lines.forEach(line => {
      const match = line.match(/--([^:]+):\s*([^;]+);/);
      if (match) {
        const [, key, value] = match;
        
        if (key.startsWith('color-')) {
          tokens.colors[key.replace('color-', '')] = value.trim();
        } else if (key.startsWith('font-family-')) {
          tokens.typography.fontFamily[key.replace('font-family-', '')] = value.trim();
        } else if (key.startsWith('font-size-')) {
          tokens.typography.fontSize[key.replace('font-size-', '')] = value.trim();
        } else if (key.startsWith('line-height-')) {
          tokens.typography.lineHeight[key.replace('line-height-', '')] = value.trim();
        } else if (key.startsWith('letter-spacing-')) {
          tokens.typography.letterSpacing[key.replace('letter-spacing-', '')] = value.trim();
        } else if (key.startsWith('space-')) {
          tokens.spacing[key.replace('space-', '')] = value.trim();
        } else if (key.startsWith('radius-')) {
          tokens.radii[key.replace('radius-', '')] = value.trim();
        }
      }
    });
  });

  return tokens;
}

// Usage
const tokens = extractTokens('./design-md/muji/DESIGN.md');
fs.writeFileSync(
  './design-tokens.json',
  JSON.stringify(tokens, null, 2)
);

Tailwind CSS Integration

// tailwind.config.js
const designTokens = require('./design-tokens.json');

module.exports = {
  theme: {
    extend: {
      colors: designTokens.colors,
      fontFamily: {
        ja: designTokens.typography.fontFamily.japanese?.split(',').map(f => f.trim()) || [],
        en: designTokens.typography.fontFamily.english?.split(',').map(f => f.trim()) || [],
      },
      fontSize: designTokens.typography.fontSize,
      lineHeight: designTokens.typography.lineHeight,
      letterSpacing: designTokens.typography.letterSpacing,
      spacing: designTokens.spacing,
      borderRadius: designTokens.radii,
    },
  },
  plugins: [],
};

Troubleshooting

Font Not Loading Properly

Problem: Japanese fonts not displaying correctly.

Solution: Ensure font fallback chain is complete and in correct order:

/* Wrong - missing fallbacks */
font-family: "Noto Sans JP", sans-serif;

/* Correct - full fallback chain */
font-family: 
  "Hiragino Kaku Gothic ProN",
  "Hiragino Sans",
  "Yu Gothic Medium",
  "Meiryo",
  "Noto Sans JP",
  sans-serif;

Line Breaking Issues

Problem: Punctuation appearing at beginning of lines.

Solution: Enable proper kinsoku shori:

.ja-text {
  word-break: normal;      /* Not 'break-all' */
  overflow-wrap: break-word;
  line-break: strict;      /* Enforce kinsoku */
}

Mixed Script Spacing

Problem: English words too close to Japanese text.

Solution: Add word-spacing for mixed content:

.mixed-content {
  word-spacing: 0.25em;  /* Space between words */
  letter-spacing: 0.05em; /* Space between Japanese chars */
}

Web Font Loading

Problem: Flash of unstyled text (FOUT) with Japanese web fonts.

Solution: Use font-display and preload:

<link rel="preconnect" href="https://fonts.googleapis.com">
<link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
<link href="https://fonts.googleapis.com/css2?family=Noto+Sans+JP:wght@400;500;700&display=swap" rel="stylesheet">

@font-face {
  font-family: 'Noto Sans JP';
  font-display: swap;  /* or 'fallback', 'optional' */
  src: url('...') format('woff2');
}

OpenType Features Not Working

Problem: font-feature-settings not applying.

Solution: Ensure font supports the feature and use correct syntax:

/* Check if font supports 'palt' */
.ja-text {
  font-feature-settings: "palt" 1, "kern" 1;
  /* Not "palt" on or "palt" true */
}

/* Alternative: use font-variant */
.ja-text {
  font-variant-ligatures: common-ligatures;
  font-kerning: normal;
}

Vertical Text Issues

Problem: Vertical text not rendering correctly.

Solution: Use proper writing-mode and text-orientation:

.vertical-text {
  writing-mode: vertical-rl;  /* or vertical-lr */
  text-orientation: upright;  /* Keep characters upright */
  font-feature-settings: "vpal" 1, "vkrn" 1;
}

/* For mixed vertical/horizontal */
.vertical-mixed {
  writing-mode: vertical-rl;
  text-orientation: mixed;  /* Rotate Latin text */
}

Best Practices

Always include complete font fallback chains — don't rely on single web fonts
Use appropriate line-height — 1.8+ for Japanese body text vs 1.5 for English
Apply letter-spacing — 0.04-0.1em for Japanese body text
Enable OpenType features — palt and kern for better spacing
Enforce kinsoku shori — use line-break: strict for proper punctuation handling
Test on multiple platforms — macOS, Windows, iOS, Android have different default fonts
Consider web font loading — use font-display: swap to avoid FOUT
Separate Japanese and English styles — use :lang() or separate classes

Resources

FAQ

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

Generate accurate Japanese UI with proper CJK typography using DESIGN.md specifications for 186+ Japanese web services

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

Run npx skills add https://github.com/reason-machines/design-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/design-skills. It has 150 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 Skill

What This Project Does

Installation

Repository Structure

Using DESIGN.md Files

1. Copy to Your Project

2. Reference in AI Agent Context

3. Direct Integration

Japanese Typography Patterns

Font Stack Implementation

Line Height for Japanese

Letter Spacing

OpenType Features

Kinsoku Shori (禁則処理)

Common Implementation Patterns

Pattern 1: Apply Complete DESIGN.md System

Pattern 2: Mix Japanese and English Typography

Pattern 3: Responsive Japanese Typography

Pattern 4: Component with DESIGN.md Tokens

Pattern 5: CSS-in-JS with Japanese Typography

Browsing the Collection

View Gallery

Preview Individual Designs

Available Design Systems (186+)

Configuration

Create design-tokens.json

Tailwind CSS Integration

Troubleshooting

Font Not Loading Properly

Line Breaking Issues

Mixed Script Spacing

Web Font Loading

OpenType Features Not Working

Vertical Text Issues

Best Practices

Resources

FAQ

More from reason-machines/design-skills

Popular frontend & design skills