awesome-design-md-jp

# Awesome Design MD JP Skill > Skill by [ara.so](https://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: ```bash 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: ```bash # 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.): ```markdown 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: ```javascript // 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 ```css /* 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 ```css /* 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 ```css /* 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 ```css /* 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 (禁則処理) ```css /* 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 ```css /* 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 ```html <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 ```css /* 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 ```jsx // 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 ```javascript // 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: ```bash # 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 ```javascript // 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, '');