awesome-design-md-jp

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

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

Resources

• Google Stitch DESIGN.md Documentation
• W3C Japanese Layout Task Force
• CSS Writing Modes Level 3
• OpenType Feature Tags