awesome-design-md-jp: The Prompt Library That Teaches AI How to Typeset Japanese UI

The current DESIGN.md format and this awesome collection cover Western typography excellently, but have no coverage for CJK (Chinese, Japanese, Korean) typography — which requires fundamentally different specifications for AI agents to generate correct UI.

kzhrknt, Author and Maintainer · Issue #172 on VoltAgent/awesome-design-md

When AI Gets Japanese UI Wrong

AI can draft an interface fast, but Japanese UI exposes a common failure mode. The text may be technically correct and still feel cramped, cheap, or off-balance because the model defaults to Western typographic habits. In Japanese, that is not a cosmetic miss. It changes readability and trust.

DESIGN.md Becomes a Design API

The first smart move in this repo is treating a plain Markdown file like an interface contract. A `DESIGN.md` file is not just documentation. It is a structured prompt that tells an AI agent how to think about layout, typography, and visual hierarchy before it writes code.

## 3. Japanese Typography

### 3.1 Font Family
Use a Japanese-first fallback chain.

### 3.2 Line Height
Prefer taller line spacing for body text.

### 3.3 Letter Spacing
Tune spacing for Japanese readability.

### 3.4 Kinsoku Shori
Avoid prohibited line breaks.

### 3.5 OpenType Features
Enable proportional and kerning features where appropriate.

What awesome-design-md-jp Adds That the Parent Project Does Not

The parent awesome-design-md established the broader idea: design systems can be expressed as readable Markdown for AI agents. `awesome-design-md-jp` narrows that idea into a specific problem space, where the details of CJK typography matter more than generic visual polish.

That difference sounds narrow until you watch a model generate a Japanese screen with the wrong fallback chain. Then it becomes obvious that typography is part of the system, not a post-processing layer.

The Forensic Layer: Real CSS, Not Design Vibes

This repo gets persuasive because it does not stop at principles. It includes production-derived values, such as explicit font stacks and the kind of spacing decisions that usually live buried inside a polished site’s computed styles. That matters because AI responds better to operational detail than to abstract advice.

One of the strongest signals in the collection is how much it relies on evidence from real products. When a design spec says a Japanese body style needs a specific fallback chain or a more generous line height, it gives the model fewer excuses and fewer degrees of freedom to wander into broken output.

How the Repository Turns Research Into Something Reusable

The repo is organized like a workflow, not a scrapbook. Each service folder holds a `DESIGN.md`, a preview HTML file, and a screenshot. The template defines the common shape, and the gallery proves the spec works across examples.

design-md/
  template/
    DESIGN.md
  apple/
    DESIGN.md
    preview.html
    preview-screenshot.png
  smarthr/
    DESIGN.md
    preview.html
    preview-screenshot.png
  gallery.html

That structure is what makes the repo reusable. A contributor is not just dropping in inspiration. They are giving an AI agent a repeatable surface area, then showing the rendered result in a form the browser can verify.

Why This Matters for AI-Native Development

The bigger lesson is not limited to Japanese UI. `awesome-design-md-jp` shows how niche expertise can be encoded for AI systems without flattening the nuance out of it. Localization, typography, and prompt design become the same discipline when the output has to work in the real world.

That is the promise of this repo. It does not merely collect good examples. It turns hard-won design knowledge into something AI can consume, repeat, and improve on. For vibe coders, that is a big step from “make it look nice” to “make it render correctly.”

Sources