Typography and Color Systems
Few type styles, chosen on purpose; colors named by role and checked for contrast in both themes.
When to Use
- Starting a design system or a new app's CSS
- After
visual-direction, to turn the direction into concrete tokens
- When text is hard to read, a palette fails contrast, or dark mode looks muddy
- When a codebase has dozens of one-off font sizes and hex values
When NOT to Use
- You are working inside an existing design system — use its tokens and propose changes upstream
Workflow
Step 1: Choose Faces with a Reason
Most interfaces need one or two families. Write one line per face explaining the job it does.
| Role |
Job |
Selection questions |
| Text |
Long reading, UI labels |
Is it readable at 16px? Does it have the weights and numerals you need? Licence allows web use? |
| Display (optional) |
Headlines, the signature element |
Does it come from the direction (subject, era, material)? Is it distinct from the text face, not a near-twin? |
| Mono (optional) |
Code, tabular IDs |
Only if the product shows code or fixed-width data |
A monospace face used for decorative labels is a common template tell (see ui-template-audit). Use mono where fixed width means something.
System fonts are a legitimate choice for product UI (fast, familiar, no licence). Pair them with a deliberate scale and spacing rather than treating them as "no decision".
Step 2: Set a Small Type Scale
Pick a ratio and generate only the steps you will use. Fewer steps make hierarchy clearer.
:root {
--step--1: 0.875rem; /* metadata, captions */
--step-0: 1rem; /* body */
--step-1: 1.25rem; /* subheads */
--step-2: 1.5625rem; /* section heads */
--step-3: clamp(1.9rem, 1.4rem + 2vw, 2.45rem); /* page title */
}
body { font-size: var(--step-0); line-height: 1.5; }
h1 { font-size: var(--step-3); line-height: 1.1; text-wrap: balance; }
p { max-width: 65ch; text-wrap: pretty; }
Notes:
rem-based sizes respect the user's browser font-size setting; avoid fixed px for body text
- Keep a
clamp() minimum readable; fluid type must still scale with browser zoom
text-wrap: balance applies only to short blocks (MDN notes browser line-count limits); pretty trades speed for better breaks and falls back to normal wrapping where unsupported
Step 3: Control Line Length and Spacing
- Constrain paragraphs with
max-width in ch. WCAG 1.4.8 (Level AAA) asks that width be no more than 80 characters (40 for CJK); the frontend-design skill also recommends staying under 80. Many teams aim lower for body copy; treat the exact target as a judgment call
- Leave room for user overrides. WCAG 1.4.12 Text Spacing (Level AA) requires no loss of content when users set line height to 1.5x font size, paragraph spacing to 2x, letter spacing to 0.12x, and word spacing to 0.16x. Avoid fixed-height text containers that clip
- Serif or small-x-height text faces usually need more leading than the default
Step 4: Use Numerals Deliberately
.table td.numeric, .price, .timer {
font-variant-numeric: tabular-nums; /* aligned columns, no jitter on change */
}
.prose { font-variant-numeric: oldstyle-nums; } /* only if the face supports it */
font-variant-numeric is Baseline widely available, but each value works only if the font includes the OpenType feature.
Step 5: Name Colors by Role, Not Value
:root {
color-scheme: light dark;
/* Primitive palette (never used directly in components) */
--ink-900: oklch(22% 0.02 250);
--ink-600: oklch(45% 0.02 250);
--paper-50: oklch(98% 0.005 90);
--signal-600: oklch(52% 0.17 145);
/* Semantic tokens (components use only these) */
--color-text: light-dark(var(--ink-900), oklch(94% 0.01 90));
--color-text-muted: light-dark(var(--ink-600), oklch(76% 0.01 90));
--color-bg: light-dark(var(--paper-50), oklch(18% 0.01 250));
--color-accent: light-dark(var(--signal-600), oklch(72% 0.15 145));
--color-focus: var(--color-accent);
--color-danger: light-dark(oklch(50% 0.19 27), oklch(72% 0.15 27));
}
Why oklch(): its lightness channel tracks perceived lightness better than HSL, which makes building even ramps easier. It is Baseline widely available. Hue angles differ from HSL (MDN notes red is around 41 degrees in OKLCH), so don't port HSL hues directly.
Step 6: Check Contrast for Every Pairing You Ship
Build a matrix of real foreground/background pairs, in both themes:
| Pair |
Requirement (WCAG 2.2) |
| Body text on background |
4.5:1 (1.4.3, AA) |
| Large text (at least 18pt, or 14pt bold; roughly 24px / 18.5px) |
3:1 (1.4.3, AA) |
| Muted/metadata text |
Still 4.5:1 unless it qualifies as large |
| Input borders, icons that convey meaning, focus indicators |
3:1 against adjacent colors (1.4.11, AA) |
| Text on accent buttons |
4.5:1 |
Do not round: W3C's understanding document states 4.499:1 does not meet 4.5:1. Check with a contrast tool against the computed colors, including text over images and gradients (test the worst spot).
Step 7: Design Dark Mode as Its Own Theme
- Re-pick values; don't just invert. Saturated accents usually need higher lightness and lower chroma on dark surfaces
- Avoid pure black backgrounds with pure white body text if it causes glare for your audience; test, don't assume
- Shadows read poorly on dark surfaces; use surface lightness steps for elevation
- Set
color-scheme so form controls and scrollbars match
light-dark() is Baseline 2024 and requires color-scheme; for older browsers, use @media (prefers-color-scheme: dark) overrides
- Re-run the contrast matrix for the dark theme
Step 8: Lock It Down
- Lint for raw hex/px values outside the tokens file if your tooling supports it
- Document each token's role in one line
- Add new tokens only when a real component needs a role that doesn't exist
Best Practices
- One or two families, each with a stated job
- A short type scale beats a long one; hierarchy comes from contrast between steps
- Body text in
rem, measured lines in ch, no clipped containers
- Components consume semantic tokens only; primitives stay private
- Contrast-check every shipped pair in both themes, unrounded
- Treat dark mode as a second palette, not a filter
- Color is never the only signal (WCAG 1.4.1); pair it with text, shape, or icon
References
1---2name: typography-and-color-systems3description: |4 Build a small, deliberate typography and color system — type scale, font pairing, line length, numeric styles, semantic color tokens, contrast-checked palettes, and dark mode — instead of inheriting framework defaults.5 Use this skill when setting up a design system, choosing fonts or palettes, adding dark mode, or fixing text that is hard to read or colors that fail contrast.6 Activate when: type scale, font pairing, typography system, color palette, design tokens, dark mode, contrast ratio, color system, line length, readable text.7metadata:8 source: https://skillmd.com/skills/latestaiagents/typography-and-color-systems9---1011# Typography and Color Systems1213**Few type styles, chosen on purpose; colors named by role and checked for contrast in both themes.**1415## When to Use1617- Starting a design system or a new app's CSS18- After `visual-direction`, to turn the direction into concrete tokens19- When text is hard to read, a palette fails contrast, or dark mode looks muddy20- When a codebase has dozens of one-off font sizes and hex values2122## When NOT to Use2324- You are working inside an existing design system — use its tokens and propose changes upstream2526## Workflow2728### Step 1: Choose Faces with a Reason2930Most interfaces need one or two families. Write one line per face explaining the job it does.3132| Role | Job | Selection questions |33|------|-----|---------------------|34| Text | Long reading, UI labels | Is it readable at 16px? Does it have the weights and numerals you need? Licence allows web use? |35| Display (optional) | Headlines, the signature element | Does it come from the direction (subject, era, material)? Is it distinct from the text face, not a near-twin? |36| Mono (optional) | Code, tabular IDs | Only if the product shows code or fixed-width data |3738A monospace face used for decorative labels is a common template tell (see `ui-template-audit`). Use mono where fixed width means something.3940System fonts are a legitimate choice for product UI (fast, familiar, no licence). Pair them with a deliberate scale and spacing rather than treating them as "no decision".4142### Step 2: Set a Small Type Scale4344Pick a ratio and generate only the steps you will use. Fewer steps make hierarchy clearer.4546```css47:root {48 --step--1: 0.875rem; /* metadata, captions */49 --step-0: 1rem; /* body */50 --step-1: 1.25rem; /* subheads */51 --step-2: 1.5625rem; /* section heads */52 --step-3: clamp(1.9rem, 1.4rem + 2vw, 2.45rem); /* page title */53}5455body { font-size: var(--step-0); line-height: 1.5; }56h1 { font-size: var(--step-3); line-height: 1.1; text-wrap: balance; }57p { max-width: 65ch; text-wrap: pretty; }58```5960Notes:6162- `rem`-based sizes respect the user's browser font-size setting; avoid fixed `px` for body text63- Keep a `clamp()` minimum readable; fluid type must still scale with browser zoom64- `text-wrap: balance` applies only to short blocks (MDN notes browser line-count limits); `pretty` trades speed for better breaks and falls back to normal wrapping where unsupported6566### Step 3: Control Line Length and Spacing6768- Constrain paragraphs with `max-width` in `ch`. WCAG 1.4.8 (Level AAA) asks that width be no more than 80 characters (40 for CJK); the `frontend-design` skill also recommends staying under 80. Many teams aim lower for body copy; treat the exact target as a judgment call69- Leave room for user overrides. WCAG 1.4.12 Text Spacing (Level AA) requires no loss of content when users set line height to 1.5x font size, paragraph spacing to 2x, letter spacing to 0.12x, and word spacing to 0.16x. Avoid fixed-height text containers that clip70- Serif or small-x-height text faces usually need more leading than the default7172### Step 4: Use Numerals Deliberately7374```css75.table td.numeric, .price, .timer {76 font-variant-numeric: tabular-nums; /* aligned columns, no jitter on change */77}78.prose { font-variant-numeric: oldstyle-nums; } /* only if the face supports it */79```8081`font-variant-numeric` is Baseline widely available, but each value works only if the font includes the OpenType feature.8283### Step 5: Name Colors by Role, Not Value8485```css86:root {87 color-scheme: light dark;8889 /* Primitive palette (never used directly in components) */90 --ink-900: oklch(22% 0.02 250);91 --ink-600: oklch(45% 0.02 250);92 --paper-50: oklch(98% 0.005 90);93 --signal-600: oklch(52% 0.17 145);9495 /* Semantic tokens (components use only these) */96 --color-text: light-dark(var(--ink-900), oklch(94% 0.01 90));97 --color-text-muted: light-dark(var(--ink-600), oklch(76% 0.01 90));98 --color-bg: light-dark(var(--paper-50), oklch(18% 0.01 250));99 --color-accent: light-dark(var(--signal-600), oklch(72% 0.15 145));100 --color-focus: var(--color-accent);101 --color-danger: light-dark(oklch(50% 0.19 27), oklch(72% 0.15 27));102}103```104105Why `oklch()`: its lightness channel tracks perceived lightness better than HSL, which makes building even ramps easier. It is Baseline widely available. Hue angles differ from HSL (MDN notes red is around 41 degrees in OKLCH), so don't port HSL hues directly.106107### Step 6: Check Contrast for Every Pairing You Ship108109Build a matrix of real foreground/background pairs, in both themes:110111| Pair | Requirement (WCAG 2.2) |112|------|------------------------|113| Body text on background | 4.5:1 (1.4.3, AA) |114| Large text (at least 18pt, or 14pt bold; roughly 24px / 18.5px) | 3:1 (1.4.3, AA) |115| Muted/metadata text | Still 4.5:1 unless it qualifies as large |116| Input borders, icons that convey meaning, focus indicators | 3:1 against adjacent colors (1.4.11, AA) |117| Text on accent buttons | 4.5:1 |118119Do not round: W3C's understanding document states 4.499:1 does not meet 4.5:1. Check with a contrast tool against the computed colors, including text over images and gradients (test the worst spot).120121### Step 7: Design Dark Mode as Its Own Theme122123- Re-pick values; don't just invert. Saturated accents usually need higher lightness and lower chroma on dark surfaces124- Avoid pure black backgrounds with pure white body text if it causes glare for your audience; test, don't assume125- Shadows read poorly on dark surfaces; use surface lightness steps for elevation126- Set `color-scheme` so form controls and scrollbars match127- `light-dark()` is Baseline 2024 and requires `color-scheme`; for older browsers, use `@media (prefers-color-scheme: dark)` overrides128- Re-run the contrast matrix for the dark theme129130### Step 8: Lock It Down131132- Lint for raw hex/px values outside the tokens file if your tooling supports it133- Document each token's role in one line134- Add new tokens only when a real component needs a role that doesn't exist135136## Best Practices1371381. One or two families, each with a stated job1392. A short type scale beats a long one; hierarchy comes from contrast between steps1403. Body text in `rem`, measured lines in `ch`, no clipped containers1414. Components consume semantic tokens only; primitives stay private1425. Contrast-check every shipped pair in both themes, unrounded1436. Treat dark mode as a second palette, not a filter1447. Color is never the only signal (WCAG 1.4.1); pair it with text, shape, or icon145146## References147148- WCAG 2.2: https://www.w3.org/TR/WCAG22/149- Understanding 1.4.3 Contrast (Minimum): https://www.w3.org/WAI/WCAG22/Understanding/contrast-minimum.html150- MDN, `oklch()`: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/oklch151- MDN, `light-dark()`: https://developer.mozilla.org/en-US/docs/Web/CSS/color_value/light-dark152- MDN, `prefers-color-scheme`: https://developer.mozilla.org/en-US/docs/Web/CSS/@media/prefers-color-scheme153- MDN, `text-wrap`: https://developer.mozilla.org/en-US/docs/Web/CSS/text-wrap154- MDN, `font-variant-numeric`: https://developer.mozilla.org/en-US/docs/Web/CSS/font-variant-numeric155- Anthropic `frontend-design` skill: https://github.com/anthropics/skills/blob/main/skills/frontend-design/SKILL.md