/typography

name: ui-typography
description: >
  Professional typography rules for UI design, web applications, software interfaces, and all screen-based
  text. Enforces timeless typographic correctness that LLMs consistently get wrong: proper quote marks,
  dashes, spacing, hierarchy, and layout. ENFORCEMENT MODE: When generating ANY HTML, CSS, React, JSX,
  or UI code containing visible text, auto-apply every rule in this skill silently — do not ask, do not
  explain, just produce correct typography. AUDIT MODE: When reviewing or improving existing interfaces or
  legacy code, flag violations and provide fixes. Trigger on: any HTML/CSS/React artifact creation, "build
  a landing page", "create a component", "design a UI", "fix the typography", "make this look professional",
  "review this layout", web design, presentation design, dashboard creation, document generation, or any
  task producing visible text for humans. Even if the user doesn't mention typography, apply these rules
  whenever generating UI output.

UI Typography Skill

Attribution

These rules are distilled from **Matthew Butterick's *Practical Typography*** (https://practicaltypography.com). Butterick is a typographer, writer, and type designer whose work bridges professional typography and everyday digital writing. Thank you, Matthew, for making this knowledge accessible and encyclopedic. If you find this skill valuable, consider supporting his work directly.

Mode of Operation

These are **permanent rules** — not trends, not opinions. They come from centuries of typographic practice, validated by how the human eye reads. They do not go out of style.

**ENFORCEMENT (default):** When generating ANY UI with visible text, apply every rule automatically. Use correct HTML entities, proper CSS. Do not ask permission. Do not explain. Just produce correct typography.

**AUDIT:** When reviewing existing code or design, identify violations and provide before/after fixes.

**Reference files** (read when generating CSS or looking up entities):

• `references/css-templates.md` — Full CSS baseline template, responsive patterns, OpenType features
• `references/html-entities.md` — Complete entity table with all characters and codes

---

Characters

Quotes and Apostrophes — Always Curly

Straight quotes are typewriter artifacts. Use `“` `”` for double, `‘` `’` for single.

Apostrophes always point down — identical to closing single quote `’`. Smart-quote engines wrongly insert opening quotes before decade abbreviations ('70s) and word-initial contractions ('n'). Fix with explicit `’`.

The `<q>` tag auto-applies curly quotes when `<html lang="en">` is set.

Hawaiian okina points upward — it's a letter, not an apostrophe. Use opening single quote or anglicize.

JSX/React Implementation Warning

**Unicode escape sequences (`\u2019`, `\u201C`, etc.) do NOT work in JSX text content.** They render as literal characters — the user sees `\u2019` instead of a curly apostrophe. This is because JSX text between tags is treated as string literals by the transpiler, not as JavaScript expressions.

**What fails:**

{/* WRONG — renders literally as \u2019 */}
<p>Don\u2019t do this</p>

**What works (pick one):**

1. **Actual UTF-8 characters (preferred):** Paste the real character directly into the source file.

   <p>Don\u2019t do this</p>  {/* This is the actual curly apostrophe character U+2019 */}

2. **JSX expression with string literal:** Wrap in curly braces so the JS engine interprets the escape.

   <p>Don{'\u2019'}t do this</p>

3. **HTML entity (HTML files only):** Use `&rsquo;` — but this does NOT work in JSX/React.

**For bulk fixes via CLI**, use `sed` with raw UTF-8 bytes (not escape sequences):

CURLY=$(printf '\xe2\x80\x99')  # U+2019 RIGHT SINGLE QUOTATION MARK
sed -i '' "s/don't/don${CURLY}t/g" file.tsx

**In JavaScript data arrays and string literals**, `\u2019` works correctly because the JS engine processes the escape. The bug only affects JSX text content between tags.

Dashes and Hyphens — Three Distinct Characters

| Character | HTML | Use | |-----------|------|-----| | - (hyphen) | `-` | Compound words (cost-effective), line breaks | | – (en dash) | `&ndash;` | Ranges (1–10), connections (Sarbanes–Oxley Act) | | — (em dash) | `&mdash;` | Sentence breaks—like this |

Never approximate with `--` or `---`. If you open with "from", pair with "to" not en dash. Hyphen for compound names (marriage); en dash for joint authorship. Em dash typically flush; add `&thinsp;` if crushed. No slash where en dash belongs. Hyphenate phrasal adjectives (five-dollar bills). No hyphen after -ly adverbs.

Ellipses — One Character

Use `&hellip;` (…), not three periods. Spaces before and after; use `&nbsp;` on the text-adjacent side. For interrupted dialogue, prefer em dash over ellipsis.

Math and Measurement

Use `&times;` for multiplication, `&minus;` for subtraction. Use `+` and `=` from keyboard. En dash is acceptable as simple minus. Dimensions: 8.5″ × 14″ uses `&times;`.

**Foot and inch marks** — the ONE exception to curly quotes. Must be STRAIGHT: `&#39;` for foot, `&quot;` for inch. Use `&nbsp;` between values: `6&#39;&nbsp;10&quot;`.

Trademark and Copyright

Use real symbols: `&copy;` `&trade;` `&reg;`, never (c) (TM) (R). ™/® are superscripts, no space before. © is inline, followed by `&nbsp;` then year. "Copyright ©" is redundant — word OR symbol, not both.

Paragraph and Section Marks

`&sect;` (§) and `&para;` (¶) always followed by `&nbsp;`: `&sect;&nbsp;1782`. Spell out at sentence start. Double for plurals: `&sect;&sect;`.

Accented Characters

Proper names: accents are MANDATORY (François Truffaut, Plácido Domingo). Loanwords: check dictionary — some naturalized (naive), some not (cause célèbre).

Other Punctuation

• **Semicolons** join independent clauses. **Colons** introduce completion. Don't