typography✓ Pass

SKILL.md Content

---
name: typography
description: Apply professional typography principles to create readable, hierarchical, and aesthetically refined interfaces. Use when setting type scales, choosing fonts, adjusting spacing, designing text-heavy layouts, or when the user asks about readability, font pairing, line height, measure, or typographic hierarchy.
---

# Typography

Professional typography for user interfaces.

## Output Contract

For type system recommendations:

```markdown
## Type System

### Scale
- Base: [size, e.g., 16px]
- Ratio: [e.g., Minor Third 1.200]
- Rationale: [why this ratio]

### Hierarchy
| Level | Size | Weight | Line Height | Letter Spacing | Use |
|-------|------|--------|-------------|----------------|-----|
| Display | ... | ... | ... | ... | Hero, marketing |
| H1 | ... | ... | ... | ... | Page titles |
| H2 | ... | ... | ... | ... | Section heads |
| Body | ... | ... | ... | ... | Paragraphs |
| Small | ... | ... | ... | ... | Captions, labels |

### Fonts
- Primary: [font] - [rationale]
- Secondary: [font, if applicable]
- Mono: [font, if applicable]

### Implementation
```css
/* Ready-to-use CSS variables */
```
```

For typography audits:

```markdown
## Typography Audit

### Issues
| Element | Problem | Recommendation |
|---------|---------|----------------|
| ... | ... | ... |

### Quick Wins
- [Immediate improvement 1]
- [Immediate improvement 2]
```

## Core Principles

### Hierarchy & Structure
- Establish clear visual hierarchy through size, weight, and spacing
- Limit to 3-4 distinct heading levels in practice
- Use weight contrast (not just size) to differentiate levels
- Maintain consistent hierarchy patterns across the application

### Readability First
- Optimize for scanning: users read in F-patterns
- Left-align body text (centered only for short, formal text)
- Ensure sufficient contrast (4.5:1 minimum, 7:1 preferred)
- Test with real content, not lorem ipsum

### Restraint & Consistency
- Use 1-2 font families maximum (one serif, one sans-serif if pairing)
- Establish a type scale and stick to it
- Avoid decorative fonts for functional UI text
- Let whitespace do the work; resist the urge to fill

## Type Scales

### Modular Scales
Common ratios for harmonious sizing:
- **Minor Second** (1.067): Subtle, conservative
- **Major Second** (1.125): Gentle, professional
- **Minor Third** (1.200): Balanced, versatile
- **Major Third** (1.250): Bold, impactful
- **Perfect Fourth** (1.333): Strong hierarchy
- **Golden Ratio** (1.618): Dramatic, editorial

### Practical Scale (Minor Third, base 16px)
```
text-xs:   12px (0.75rem)
text-sm:   14px (0.875rem)
text-base: 16px (1rem)
text-lg:   18px (1.125rem)
text-xl:   20px (1.25rem)
text-2xl:  24px (1.5rem)
text-3xl:  30px (1.875rem)
text-4xl:  36px (2.25rem)
text-5xl:  48px (3rem)
```

### When to Deviate
- Marketing/hero sections can use larger jumps
- Dense data interfaces may need tighter scales
- Mobile often requires slightly larger base sizes

## Measure (Line Length)

### Optimal Ranges
- **Body text**: 45-75 characters (66 ideal)
- **Short-form**: 40-60 characters
- **Wide layouts**: Use columns or max-width constraints
- **Mobile**: Full width is acceptable due to narrow viewport

### Implementation
```css
/* Tailwind equivalents */
max-w-prose  /* ~65ch */
max-w-2xl    /* 672px, good for articles */
max-w-xl     /* 576px, compact content */
```

### Multi-Column Considerations
- Narrower columns = shorter measure acceptable
- Gutters should be at least 20px (1.25rem)
- Avoid orphaned words at column breaks

## Line Height (Leading)

### Guidelines by Context
- **Body text**: 1.5-1.7 (generous for readability)
- **Headings**: 1.1-1.3 (tighter, especially large sizes)
- **UI labels**: 1.2-1.4 (compact but legible)
- **Buttons**: 1.0-1.25 (single line, tight)

### Adjustments
- Increase line height for wider measure
- Decrease for larger type sizes
- Consider the x-height of the typeface
- Dark mode may benefit from slightly more leading

## Letter Spacing (Tracking)

### General Rules
- **Body text**: Default (0) or very slight increase
- **All caps**: Always add positive tracking (+0.05em to +0.1em)
- **Large headings**: Slight negative tracking (-0.01em to -0.02em)
- **Small text**: Slight positive tracking for legibility

### Tailwind Classes
```
tracking-tighter: -0.05em
tracking-tight:   -0.025em
tracking-normal:  0
tracking-wide:    0.025em
tracking-wider:   0.05em
tracking-widest:  0.1em
```

### All-Caps Text
- Always use `uppercase tracking-wide` or `tracking-wider`
- Keep short (1-3 words ideal)
- Common for labels, category tags, eyebrow text

## Font Selection

### System Font Stacks
Performant and native-feeling:
```css
/* Sans-serif (modern) */
font-family: ui-sans-serif, system-ui, sans-serif, "Apple Color Emoji", "Segoe UI Emoji";

/* Serif */
font-family: ui-serif, Georgia, Cambria, "Times New Roman", serif;

/* Monospace */
font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, monospace;
```

### Web Font Considerations
- Limit to 2-3 weights per family (400, 500/600, 700)
- Use `font-display: swap` for performance
- Variable fonts reduce file size for multiple weights
- Self-host for privacy and reliability

### Pairing Principles
- Pair by contrast (serif + sans-serif)
- Match x-height for visual harmony
- Use one font for headings, one for body
- Ensure both have needed weights/styles

### Safe Recommendations
- **Sans-serif**: Inter, Source Sans Pro, Open Sans, Work Sans
- **Serif**: Source Serif Pro, Lora, Merriweather, Literata
- **Monospace**: JetBrains Mono, Fira Code, Source Code Pro

## Paragraph Spacing

### Between Paragraphs
- Use margin-bottom equal to line-height or slightly more
- Typically 1em to 1.5em between paragraphs
- First paragraph after heading: reduced or no top margin

### Between Sections
- 2-3x paragraph spacing between major sections
- Use consistent spacing tokens from design system
- Consider visual grouping via proximity

## Typographic Details

### Quotation Marks
- Use curly quotes (" " ' ') not straight quotes (" ')
- Proper apostrophes: it's, don't, '90s
- Consider the locale (French guillemets, German quotes)

### Dashes
- **Hyphen** (-): Word breaks, compound words
- **En dash** (–): Ranges (2020–2024), relationships (New York–London)
- **Em dash** (—): Parenthetical statements, emphasis

### Numbers
- Use tabular (monospace) figures in tables for alignment
- Use proportional figures in body text
- Consider old-style figures for editorial content

### Ellipsis
- Use proper ellipsis character (…) not three periods
- Add thin space before/after in formal typography

## Responsive Typography

### Fluid Type
Scale font sizes smoothly between breakpoints:
```css
/* clamp(min, preferred, max) */
font-size: clamp(1rem, 0.5rem + 1.5vw, 1.5rem);
```

### Breakpoint Adjustments
- Increase base size slightly on mobile (17-18px)
- Reduce heading scale on mobile
- Increase line height for small screens
- Reduce measure on tablets (prose can feel too wide)

### Touch Targets
- Minimum 44x44px for tappable text elements
- Generous padding around links in body text
- Avoid text-only targets without visual indication

## Dark Mode Typography

### Adjustments
- Reduce font weight slightly (medium instead of semibold)
- Increase letter spacing marginally
- Consider warmer white (#f5f5f5) over pure white (#fff)
- Increase line height by ~0.1 for perceived lightness

### Contrast Considerations
- Pure white on pure black is harsh; soften both
- Aim for 10:1 to 15:1 contrast in dark mode
- Test with actual users; perceived contrast differs

## Accessibility

### Font Size Minimums
- Body text: 16px minimum (don't go below)
- Secondary text: 14px minimum, 12px absolute floor
- Legal/caption: 12px with increased tracking

### User Preferences
- Respect `font-size` from browser settings
- Use relative units (rem) not fixed (px) for text
- Provide text scaling options for dense UIs

### Dyslexia Considerations
- Avoid justified text
- Prefer sans-serif with distinct letterforms
- Generous line height and paragraph spacing
- OpenDyslexic as optional font choice

## Common Mistakes

### Avoid
- All-caps body text or long headings
- Centered body paragraphs
- Line length over 80 characters
- Insufficient contrast for "aesthetic" reasons
- Mixing too many font families
- Decorative fonts for UI text
- Justified text on the web (causes rivers)
- Tiny gray text on white backgrounds

### Watch For
- Orphans and widows in prominent text
- Inconsistent heading hierarchy
- Missing font fallbacks
- Layout shift from web font loading
- Underlined text that isn't a link

License

Declared license: MIT

MIT License

Copyright (c) 2026 petekp

Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

View the license in the source repository — the version published there is authoritative.