Skip to content
Back to search

typography-skill

A bilingual Chinese/English typography skill for coding agents: semantic roles, CJK/Latin metrics, tokens, and lint enforcement.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/modenicheng--typography-skill/badge.svg)](/listings/modenicheng--typography-skill)

HTML

<a href="/listings/modenicheng--typography-skill"><img src="/api/listings/modenicheng--typography-skill/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Requires Node.js 22.20+.

# install into the current project, pick the agent(s) interactively
npx skills add modenicheng/typography-skill --skill typography-system

# or install for Claude Code only
npx skills add modenicheng/typography-skill --skill typography-system -a claude-code

# global install
npx skills add modenicheng/typography-skill --skill typography-system -g

The CLI copies the skill to `.agents/skills/typography-system` and links it into the agent's skill directory. `npx skills check` / `npx skills update` keep it current.

You can also clone the repo and copy `skills/typography-system/` into `~/.claude/skills/` or `~/.agents/skills/` manually.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 126 lines
  1. # typography-system
  2. A bilingual (Chinese / English) typography skill for coding agents.
  3. [中文说明](README.zh-CN.md) · [Visual specimen](skills/typography-system/examples/spec.html) · [MIT License](LICENSE)
  4. ![Specimen page](docs/spec-preview.png)
  5. Most agent-generated UI fails typography in the same way: every component decides its own font size, weight, and line height, so every page looks like a different product. The fix is not a prettier style guide — it is a **small, enforceable system** the agent cannot route around.
  6. This skill gives an agent:
  7. - **6 semantic roles** (page, section, body, label, caption, optional display) and a fixed ramp.
  8. - **Separate CJK and Latin metrics** — line height, tracking, punctuation, line breaking, font stacks, and weight availability.
  9. - **Five context modes** — productive, reading, expressive, reference, presentation — plus native platform ramps.
  10. - **Token architecture** — CSS, DTCG, Tailwind v4, and Figma naming that match.
  11. - **Enforcement** — AGENTS.md rules, Stylelint/ESLint config, a zero-dependency audit script, and a visual QA protocol.
  12. English is the default: `SKILL.md` and `references/en/`. A complete Chinese version is included as `SKILL.zh-CN.md` and `references/`.
  13. ## Install
  14. Requires Node.js 22.20+.
  15. ```bash
  16. # install into the current project, pick the agent(s) interactively
  17. npx skills add modenicheng/typography-skill --skill typography-system
  18. # or install for Claude Code only
  19. npx skills add modenicheng/typography-skill --skill typography-system -a claude-code
  20. # global install
  21. npx skills add modenicheng/typography-skill --skill typography-system -g
  22. ```
  23. The CLI copies the skill to `.agents/skills/typography-system` and links it into the agent's skill directory. `npx skills check` / `npx skills update` keep it current.
  24. You can also clone the repo and copy `skills/typography-system/` into `~/.claude/skills/` or `~/.agents/skills/` manually.
  25. ## See it
  26. Open `skills/typography-system/examples/spec.html` in a browser. It is a self-contained spec sheet: the ramp rendered at real size in Chinese and English, density toggles, line-height and measure comparisons, mixed-script spacing and punctuation-trim demos, component samples, and before/after anti-patterns.
  27. ## The default ramp
  28. Product / standard density. Chinese is the default; English leading is applied on `:root:lang(en)`.
  29. | Role | Size | CJK leading | Latin leading | Weight | Use |
  30. |---|---|---|---|---|---|
  31. | display | 48px | 1.1667 (56px) | 1.0833 (52px) | 600 | marketing/cover only |
  32. | page | 28px | 1.4286 (40px) | 1.2857 (36px) | 600 | one per page |
  33. | section | 20px | 1.5 (30px) | 1.4 (28px) | 600 | module heading |
  34. | body | 16px | 1.75 (28px) | 1.5 (24px) | 400 | prose, descriptions |
  35. | label | 14px | 1.5714 (22px) | 1.4286 (20px) | 500 | buttons, forms, tables |
  36. | caption | 12px | 1.5 (18px) | 1.3333 (16px) | 400 | helper, meta |
  37. Rules that matter more than the numbers:
  38. - One screen: ≤5 sizes, ≤3 weights, ≤2 families.
  39. - Measure = `34em` ≈ 34 Chinese characters ≈ 68 Latin characters.
  40. - Chinese body line height ≥ 1.6; never add letter-spacing to Chinese.
  41. - Chinese emphasis uses 500, not 600 — Microsoft YaHei has only 300/400/700.
  42. - Never italicize Chinese; never `word-break: break-all`.
  43. - Mixed-script spacing comes from `text-autospace`, not hand-typed spaces.
  44. ## Structure
  45. ```
  46. skills/typography-system/
  47. ├── SKILL.md # English contract + router (always loaded)
  48. ├── SKILL.zh-CN.md # Chinese contract + router
  49. ├── references/
  50. │ ├── 01-principles.md # Chinese: hierarchy, rhythm, typographic color
  51. │ ├── 02-scale.md
  52. │ ├── 03-bilingual.md
  53. │ ├── 04-scenarios.md
  54. │ ├── 05-components.md
  55. │ ├── 06-tokens.md
  56. │ ├── 07-enforcement.md
  57. │ ├── 08-sources.md
  58. │ └── en/ # English translations, one per layer
  59. │ ├── 01-principles.md
  60. │ ├── 02-scale.md
  61. │ ├── 03-bilingual.md
  62. │ ├── 04-scenarios.md
  63. │ ├── 05-components.md
  64. │ ├── 06-tokens.md
  65. │ ├── 07-enforcement.md
  66. │ └── 08-sources.md
  67. ├── templates/
  68. │ ├── tokens.css
  69. │ ├── tokens.tokens.json
  70. │ ├── AGENTS.typography.md
  71. │ └── audit.mjs
  72. └── examples/
  73. └── spec.html
  74. ```
  75. Progressive disclosure: `SKILL.md` stays small and routes to one reference file per task. The agent reads only what it needs.
  76. ## Design decisions
  77. **Why six roles, not a full type scale.** Carbon and Ant both ship dozens of tokens. That is right for a design-system team and wrong for an agent: the more tokens exist, the more likely the agent picks the wrong one. Six roles cover product UI; optional `display` is explicitly fenced off from product surfaces.
  78. **Why the CJK/Latin split.** At the same pixel size, Han characters fill the em box while Latin letters live around the x-height. Chinese therefore looks larger and denser, needs roughly 0.15–0.25 more line height, and must not receive tracking. These are not stylistic preferences; they come from the square character frame (W3C clreq) and font metrics.
  79. **Why `34em`.** One Han character is about 1em; an average Latin character is about 0.5em. A single measure rule works for both scripts: `max-inline-size: 34em` gives ~34 Chinese characters or ~68 Latin characters per line, inside the 45–90 character range USWDS and Practical Typography recommend.
  80. **Why 500 for Chinese emphasis.** PingFang has six weights, Microsoft YaHei has three (300/400/700), and Noto Sans SC is variable. Requesting 600 on YaHei silently snaps to 700, which looks broken. 500 is the safest emphasis step across platforms.
  81. **Why lint + audit script.** A style guide an agent can ignore is a suggestion. Stylelint blocks raw values at build time; `audit.mjs` covers files that lint does not reach (Vue/Svelte templates, inline styles, Tailwind arbitrary values); the AGENTS.md block makes the rule visible in the prompt.
  82. ## What this is not
  83. - Not a font-pairing catalog. It recommends stacks and criteria, not specific commercial fonts.
  84. - Not a layout or color system. It only covers type and the spacing that type depends on.
  85. - Not a print typesetting engine. It borrows principles from print but targets screens.
  86. - Not a replacement for looking at the page. Every reference ends with a verification checklist.
  87. ## Sources
  88. W3C clreq, GB/T 15834—2011, WCAG 2.2 (1.4.4 / 1.4.12 / 1.4.3), Ant Design Font, IBM Carbon Typography, Microsoft Fluent 2, Apple HIG, USWDS Typography, Butterick's Practical Typography, Refactoring UI, W3C DTCG, Tailwind CSS, CSS Text Level 4. Annotations and caveats in `references/08-sources.md`.
  89. ## License
  90. MIT. See [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.