@its-thepoe/better-typography 1.0.0

package/README.md

@@ -0,0 +1,9 @@
+# @its-thepoe/better-typography
+
+**Agent Skill** for better-typography.
+
+Install:
+
+```bash
+npx @its-thepoe/skills@latest install better-typography
+```

package/SKILL.md

@@ -0,0 +1,166 @@
+---
+name: better-typography
+description: Web typography from choosing fonts to spacing, wrapping and accessibility. Use when picking or pairing typefaces, configuring variable fonts or OpenType features, setting up a type scale, checking heading hierarchy, styling text in components, truncating text, styling underlines, selection, placeholders or carets, or reviewing frontend code for typography. Triggers on typography, fonts, font formats, woff2, variable fonts, font-weight, opentype, font-feature-settings, letter-spacing, line-height, type scale, heading hierarchy, heading levels, tabular numbers, text-wrap, truncation, line clamp, underlines, text-decoration, text selection, iOS input zoom, font smoothing, text contrast, measure, line length, text-box, smart punctuation, drop cap.
+---
+
+# Great typography
+
+Good typography is mostly restraint. A sensible scale, comfortable spacing and enough contrast beat any clever effect. A label, a table cell, a marketing headline and an article paragraph should not share one set of rules. Apply these principles when building or reviewing anything with text in it.
+
+**Match the project's styling system.** Before suggesting or writing any fix, check how the codebase styles things and express every change in that system: Tailwind utilities in a Tailwind project, plain declarations in CSS, CSS Modules, styled-components or StyleX. The [cheat sheet](css-cheat-sheet.md) maps each declaration to its Tailwind equivalent. Never introduce a second styling approach just to apply a typography fix.
+
+## Quick Reference
+
+| Category | When to use | Reference |
+| --- | --- | --- |
+| Choosing fonts | Font categories, pairing, formats, typeface anatomy | [choosing-fonts.md](choosing-fonts.md) |
+| Variable fonts & OpenType | Axes, weights, tabular numbers, stylistic sets | [variable-fonts-and-opentype.md](variable-fonts-and-opentype.md) |
+| Spacing & sizing | Type scale, heading hierarchy, line-height, letter-spacing, text trimming | [spacing-and-sizing.md](spacing-and-sizing.md) |
+| Wrapping & punctuation | Measure, wrapping, truncation, smart punctuation, RTL | [wrapping-and-punctuation.md](wrapping-and-punctuation.md) |
+| Details & accessibility | Underlines, selection, forms, decorative text, contrast | [details-and-accessibility.md](details-and-accessibility.md) |
+| CSS cheat sheet | Quick lookup of every property covered, with Tailwind equivalents | [css-cheat-sheet.md](css-cheat-sheet.md) |
+
+## Core Principles
+
+### 1. Serve the Right Format
+
+Use `.woff2` (Brotli compression, broadly supported) on the web. `.woff` is a fallback only for very old browsers; `.ttf` and `.otf` are raw desktop formats with no web compression. How the files are loaded is the project's own concern, this skill does not prescribe it.
+
+### 2. Properties Over Raw Tags
+
+When a CSS property exists, use it. `font-weight: 650` instead of `font-variation-settings: "wght" 650`, `font-optical-sizing: auto` instead of `"opsz"`, `font-variant-numeric: tabular-nums` instead of `font-feature-settings: "tnum" 1`. Properties keep working when a non-variable fallback renders. Reserve the raw-tag properties for custom axes (`"GRAD" 80`) and niche features (`"ss01" 1`) that have no property of their own.
+
+### 3. No Fake Weights
+
+When a weight or style is not loaded, the browser synthesizes it. That is a safety mechanism, not a feature. Set `font-synthesis: none` so missing files fail visibly instead of rendering a faked bold or italic.
+
+### 4. Fewer Fonts, Sizes and Weights
+
+Rarely use more than three fonts. Weight and size define hierarchy, but overusing them hurts readability quickly. Pair for contrast, not similarity: a serif headline with a sans body reads as deliberate, two near-identical sans-serifs read as a mistake.
+
+### 5. Use a Type Scale with Semantic Names
+
+Define a small set of sizes and deviate from it as little as possible. Hard-coded sizes without a system break down at scale. For solo projects, default names like `text-sm` work fine as long as the usage rules are clear. On a team, name sizes by use (`text-body-sm`), not by size, so the rules stay consistent.
+
+### 6. Heading Sizes Descend with Level
+
+Map each heading level used on a page to a descending step of the type scale: a lower level must never render larger than a higher one on the same page. Adjacent levels may share a size toward the small end of the scale as long as weight or spacing keeps them distinct. Pick the tag from the document outline and control the size with CSS; never skip levels or reach for an `h4` because it "looks right".
+
+### 7. Line-Height by Role
+
+Headings tighter, around `1.1`. Body copy `1.5` to `1.6`. Prefer unitless values so line-height scales with the font size; fixed values like `24px` do not.
+
+### 8. Letter-Spacing by Size
+
+Large headings often look better with slightly negative letter-spacing. Small uppercase labels need a little positive letter-spacing so letters do not feel crowded. Body copy at reading sizes needs neither.
+
+### 9. Cap the Measure
+
+Long lines make it hard for the eye to find the next line. Cap long-form text around 60–75 characters per line. Any unit works: `65ch` measures characters directly, and a pixel or rem cap is just as good: at a `16px` body size the range lands roughly between `560px` and `680px` depending on the font, so Tailwind's `max-w-xl` or `max-w-2xl` fit. What matters is that a cap exists and the resulting line length sits in range.
+
+### 10. Wrap Deliberately
+
+`text-wrap: balance` distributes text evenly across lines: use it on headings. `text-wrap: pretty` avoids leaving a single short word on the final line: use it on descriptions. Skip both in long-form text: browsers ignore `balance` past a few lines anyway, and evening out a whole paragraph wastes space and makes it harder to read. `overflow-wrap: break-word` where long words, links or IDs could escape the container. `white-space: nowrap` on labels and badges where a line break looks broken.
+
+### 11. Tabular Numbers on Changing Values
+
+Digits have different widths by default, so timers, counters and prices shift layout as they update. Apply `font-variant-numeric: tabular-nums` to any value that changes.
+
+### 12. Truncate Without Losing Content
+
+Single line: `text-overflow: ellipsis` with `overflow: hidden` and `white-space: nowrap`. Multiple lines: `line-clamp`. Truncation hides content, so if the missing text matters, keep the full value reachable in a tooltip or expanded view.
+
+### 13. Write Copy Naturally, Style with CSS
+
+Store text in natural case and control presentation with `text-transform`, so redesigns never require rewriting copy. Use smart punctuation: curly quotes in prose (straight quotes in code), an en dash for ranges like `2010–2020`, an em dash to set off a thought, the single ellipsis character, ` ` to keep values like `16 px` together and `­` to control where long words may break.
+
+### 14. Underlines from the Font
+
+Default underlines sit wherever the browser decides. Pull position and thickness from the font's own metrics with `text-underline-position: from-font` and `text-decoration-thickness: from-font`, or tune manually with `text-decoration-thickness`, `text-underline-offset` and `text-decoration-skip-ink`. `text-decoration-style` draws the line dotted, dashed or wavy; a dotted underline is a common hint that a word carries extra information, like an abbreviation or a defined term. Unless the only thing animating is a color change, build the underline as a separate element instead of using `text-decoration`: color is the only part of a real underline that animates reliably.
+
+### 15. Inputs at 16px on Mobile
+
+iOS Safari zooms the whole page when an input's text is smaller than `16px`. Keep input text at `16px` on mobile viewports (`text-base sm:text-sm`). Avoid the `maximum-scale=1` viewport meta: Safari ignores it for pinch zoom, but every other browser honors it and blocks zooming, which fails WCAG.
+
+### 16. Size and Contrast Floors
+
+Body text `16px` (the web default and the right reading size). UI text can go smaller: `14px` for inputs and menus (inputs still need `16px` on mobile, see principle 15), `13px` for captions, rarely below `12px`. WCAG AA: `4.5:1` contrast for regular text, `3:1` for large text (roughly `24px` and up).
+
+### 17. Font Smoothing on the Root
+
+On macOS text renders heavier than intended. Apply `-webkit-font-smoothing: antialiased` and `-moz-osx-font-smoothing: grayscale` (both covered by Tailwind's `antialiased`) once on the root layout so they cover all text.
+
+### 18. Logical Properties for Direction
+
+To support right-to-left content, use direction-agnostic properties: `margin-inline-start` instead of `margin-left`, `text-align: start` instead of `left`. Set `lang` so browsers pick the right quotes and hyphenation, and `dir="rtl"` where needed.
+
+### 19. Style the Selection, Disable It Where It Distracts
+
+`::selection` is a subtle way to embed brand in the reading experience; keep the combination legible. Use `user-select: none` on button labels where copying is unlikely and selection feels distracting, and make sure `cmd+A` only grabs text the user expects to copy. In cross-platform apps that feel closer to native, disable selection for the interface and keep it only on content worth copying.
+
+## Review Output Format
+
+Always present changes as a markdown table with **Before** and **After** columns. Include every change you made, not just a subset. Never list findings as separate "Before:" / "After:" lines outside of a table. Group changes by principle using a heading above each table, and keep each row focused on a single diff. Write every **After** snippet in the styling system the project already uses.
+
+### Example
+
+#### Tabular numbers
+| Before | After |
+| --- | --- |
+| `<span>{price}</span>` on live price | `<span className="tabular-nums">{price}</span>` |
+| `font-feature-settings: "tnum" 1` | `font-variant-numeric: tabular-nums` |
+
+#### Line-height and measure
+| Before | After |
+| --- | --- |
+| `leading-none` on body paragraph | `leading-normal` (body needs `1.5`–`1.6`) |
+| Full-width article column | `max-w-2xl` (~65 characters per line at `16px`) |
+
+Rows should cite the specific file and property when it is not obvious from the snippet. If a principle was reviewed but nothing needed to change, omit that table entirely.
+
+## Common Mistakes
+
+| Mistake | Fix |
+| --- | --- |
+| `.ttf`/`.otf` served on the web | Convert to `.woff2` |
+| `font-variation-settings: "wght"` for weight | `font-weight` (works with non-variable fallbacks) |
+| `font-feature-settings: "tnum" 1` | `font-variant-numeric: tabular-nums` |
+| Browser-faked bold or italic | Load the file, set `font-synthesis: none` |
+| Hard-coded one-off font sizes | Use the type scale |
+| `h3` rendered larger than `h2` on the same page | Map heading levels to descending scale steps |
+| Heading tag picked for its size, skipping levels | Level from the document outline, size via CSS |
+| `line-height: 24px` on scalable text | Unitless value (`1.5`) |
+| Full-width paragraphs | Cap around 60–75 characters per line |
+| Orphan on the last line of a paragraph | `text-wrap: pretty` |
+| Lopsided two-line heading | `text-wrap: balance` |
+| Numbers cause layout shift | `tabular-nums` |
+| Truncated text with no way to read it | Tooltip or expanded view for the full value |
+| `UPPERCASE` typed into copy | Natural case + `text-transform` |
+| Justified text in an interface | `text-align: start`; reserve justify for specific editorial layouts |
+| Underline cuts through descenders | `text-decoration-skip-ink: auto`, `from-font` metrics |
+| Inputs below `16px` zoom on iOS | `text-base sm:text-sm` |
+| `margin-left` in RTL-capable UI | `margin-inline-start` |
+| Selectable button labels in native-feel UI | `user-select: none`, keep selection on real content |
+| Extra-info hint with no visual cue | Dotted underline via `text-decoration-style: dotted` |
+| Tailwind classes dropped into a CSS-in-JS codebase (or the reverse) | Express the fix in the styling system the project already uses |
+
+## Review Checklist
+
+- [ ] Web fonts are `.woff2`
+- [ ] `font-weight` / `font-variant-*` used instead of raw axis and feature tags
+- [ ] `font-synthesis: none` set; no faked weights or styles
+- [ ] Sizes come from the type scale, no one-off values
+- [ ] Heading sizes descend with level (`h1` ≥ `h2` ≥ `h3`…), levels stay visually distinct, none skipped
+- [ ] Headings ~`1.1` line-height, body `1.5`–`1.6`, unitless
+- [ ] Large headings have slightly negative tracking, small uppercase labels positive
+- [ ] Long-form text capped around 60–75 characters per line
+- [ ] Headings use `text-wrap: balance`, body uses `text-wrap: pretty`
+- [ ] Changing numbers use `tabular-nums`
+- [ ] Truncated content is reachable in full somewhere
+- [ ] Copy stored in natural case, presentation via `text-transform`
+- [ ] Underlines use `from-font` or tuned thickness, offset and skip-ink
+- [ ] Inputs are `16px`+ on mobile viewports
+- [ ] Text sizes and contrast meet the floors (`16px` body, `4.5:1` / `3:1`)
+- [ ] `antialiased` applied once on the root layout
+- [ ] Directional properties are logical (`inline-start`, `start`)
+- [ ] Any styled `::selection` stays legible

package/choosing-fonts.md

@@ -0,0 +1,63 @@
+# Choosing fonts
+
+Choosing a typeface, the right file format and understanding why fonts look the way they do.
+
+## Choosing a typeface
+
+Font families set the tone before the specific font does.
+
+| Category | Traits | Use for |
+| --- | --- | --- |
+| Serif | Small strokes at the ends of letters guide the eye along a line | Long passages, editorial reading |
+| Sans-serif | Clean, even shapes that stay crisp at small sizes | Default for most interfaces (Helvetica, Inter, Geist) |
+| Monospace | Every glyph the same width so columns line up | Code, tables, tabular data |
+| Display | Drawn for large headlines | Marketing headlines, hero text |
+| Script | Mimics handwriting | Rare, decorative moments |
+
+CSS exposes `cursive` and `fantasy` keywords for the last two categories.
+
+"Display" in a font's name does not make it a display font. Fonts like SF Pro and Heldane ship a `Display` variant for large sizes and a `Text` variant for smaller sizes. Use the variant that matches the size you are setting.
+
+### Rules
+
+- Fewer fonts is usually better. Rarely use more than three. Marketing pages can be more expressive than apps.
+- The same applies to sizes and weights. They define hierarchy, but overusing them hurts readability quickly.
+- Pair for contrast, not similarity. A serif headline with a sans body looks like a deliberate display/reading split. Two near-identical sans-serifs look like a mistake.
+
+## Font family scope
+
+Applying or reviewing typography never requires a new typeface. Use the product's existing type system unless the task explicitly asks for a type change, and do not introduce a paid or proprietary face just to satisfy a review checklist. Rendering details like font smoothing, text wrapping and tabular numbers do not override the project's chosen font family.
+
+When a type change is asked for: a system-native macOS/iOS feel comes from the system stack; a commercial face such as Helvetica Now is a brand decision and keeps a practical fallback stack.
+
+```css
+/* System-native macOS/iOS feel */
+html {
+  font-family: system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
+}
+
+/* Commercial brand face with safe fallbacks */
+html {
+  font-family: "Helvetica Now", "Helvetica Neue", Arial, sans-serif;
+}
+```
+
+## Formats
+
+| Format | Notes |
+| --- | --- |
+| `.woff2` | Brotli compression, broadly supported. Use this on the web. |
+| `.woff` | Older compression. Fallback only for very old browsers. |
+| `.ttf` / `.otf` | Raw formats, no web compression, larger files. Desktop only unless there is no other option. |
+
+## Anatomy of a typeface
+
+| Term | Meaning |
+| --- | --- |
+| x-height | Height of a lowercase `x` |
+| Cap height | Height of uppercase letters |
+| Baseline | The invisible line letters sit on |
+| Ascender | Part of a letter rising above the x-height |
+| Descender | Part dropping below the baseline |
+
+These measurements are why two fonts at the same `font-size` can look like different sizes. A font with a large x-height looks bigger.

package/css-cheat-sheet.md

@@ -0,0 +1,65 @@
+# CSS cheat sheet
+
+One-line lookup for every typography CSS declaration covered by this skill, with the Tailwind 4 equivalent. Where no utility exists, the arbitrary-value form is shown. Pick the column that matches the project: the declaration in plain CSS, CSS Modules, styled-components or StyleX codebases, the utility in Tailwind codebases.
+
+## Font
+
+| Declaration | What it does | Tailwind |
+| --- | --- | --- |
+| `font-family: sans-serif` | The sans family | `font-sans` |
+| `font-family: serif` | The serif family | `font-serif` |
+| `font-family: monospace` | The monospace family | `font-mono` |
+| `font-size` | Size from the type scale | `text-*` |
+| `font-weight` | Any value from 1 to 1000 | `font-*` |
+| `font-style: italic` | Switch to italic style | `italic` |
+| `-webkit-font-smoothing` + `-moz-osx-font-smoothing` | Smooth macOS font rendering | `antialiased` |
+| `font-synthesis: none` | No faux bold or italic | `[font-synthesis:none]` |
+| `font-feature-settings` | Toggle OpenType features | `[font-feature-settings:"ss01"]` |
+| `font-variation-settings` | Tune variable font axes | `[font-variation-settings:"GRAD"_80]` |
+| `font-optical-sizing` | Adjust details per size | `[font-optical-sizing:auto]` |
+| `font-variant-caps` | Real small capitals | `[font-variant-caps:small-caps]` |
+| `font-variant-position` | Real super and subscripts | `[font-variant-position:super]` |
+| `font-variant-numeric: tabular-nums` | Equal-width digits | `tabular-nums` |
+| `font-variant-numeric: slashed-zero` | Tell 0 from O | `slashed-zero` |
+
+## Spacing and layout
+
+| Declaration | What it does | Tailwind |
+| --- | --- | --- |
+| `letter-spacing` | Space between letters | `tracking-*` |
+| `line-height` | Space between lines | `leading-*` |
+| `font-kerning` | Kerning on or off | `[font-kerning:none]` |
+| `text-box: trim-both` | Trim space above and below | `[text-box:trim-both_cap_alphabetic]` |
+| `max-width` on text columns | Cap at ~60–75 characters per line | `max-w-xl` / `max-w-2xl` / `max-w-[65ch]` |
+| `text-align` | Where lines start and end | `text-start` / `text-center` |
+
+## Wrapping and overflow
+
+| Declaration | What it does | Tailwind |
+| --- | --- | --- |
+| `text-wrap: balance` | Even out heading lines | `text-balance` |
+| `text-wrap: pretty` | Avoid orphaned words | `text-pretty` |
+| `text-overflow: ellipsis` | Ellipsis for clipped text | `truncate` |
+| `line-clamp` | Cut off after N lines | `line-clamp-*` |
+| `overflow-wrap: break-word` | Break long strings | `break-words` |
+| `white-space: nowrap` | Stop wrapping | `whitespace-nowrap` |
+| `text-transform` | Change the casing | `uppercase` / `capitalize` |
+
+## Decoration and interaction
+
+| Declaration | What it does | Tailwind |
+| --- | --- | --- |
+| `text-decoration-line: underline` | Draw an underline | `underline` |
+| `text-decoration-color` | Underline color | `decoration-*` |
+| `text-decoration-thickness` | Underline thickness | `decoration-1` / `decoration-2` |
+| `text-underline-offset` | Push the line down | `underline-offset-*` |
+| `text-underline-position: from-font` | Underline position from the font | `[text-underline-position:from-font]` |
+| `text-decoration-style` | Dotted, dashed or wavy | `decoration-dotted` / `decoration-wavy` |
+| `text-decoration-thickness: from-font` | Underline set by the font | `decoration-from-font` |
+| `text-decoration-skip-ink` | Gaps around descenders | `[text-decoration-skip-ink:auto]` |
+| `caret-color` | Tint the text cursor | `caret-*` |
+| `user-select: none` | Stop text selection | `select-none` |
+| `text-shadow` | Shadow behind the letters | `text-shadow-*` |
+| `-webkit-text-stroke` | Outline the letters | `[-webkit-text-stroke:1px_black]` |
+| `background-clip: text` | Clip a background to the letters | `bg-clip-text` |
+| `initial-letter` | Size a drop cap | `[initial-letter:3]` |

package/details-and-accessibility.md

@@ -0,0 +1,117 @@
+# Details and accessibility
+
+Underlines, selection, forms, decorative text and the floors that keep everything readable.
+
+## Underlines
+
+Default underline position is browser-determined: sometimes too close, cutting through descenders or too thin. Pull position and thickness from the font's own metrics:
+
+```css
+a {
+  text-underline-position: from-font;
+  text-decoration-thickness: from-font;
+}
+```
+
+The line does not have to be solid. `text-decoration-style` can draw it dotted, dashed or wavy. A dotted underline is a common hint that a word carries extra information, like an abbreviation or a defined term:
+
+```css
+abbr {
+  text-decoration: underline dotted;
+}
+```
+
+Or tune manually:
+
+```css
+a {
+  text-decoration-thickness: 1px;
+  text-underline-offset: 3px;
+  text-decoration-skip-ink: auto;
+  text-decoration-color: var(--color-gray-1000);
+  transition: text-decoration-color 200ms ease-out;
+}
+
+a:hover {
+  text-decoration-color: var(--color-gray-1200);
+}
+```
+
+Unless the only thing animating is a color change, build the underline as a custom element instead of using `text-decoration`: color is the only part of a real underline that animates reliably. Animate the custom element however the effect requires.
+
+## Selection
+
+- `::selection` changes the background and color of selected text; a subtle way to embed brand. Keep the combination legible.
+- `user-select: none` on button labels: copying a label is unlikely and selection there feels distracting. Also make sure `cmd+A` only grabs text the user expects to copy.
+- In cross-platform apps that feel closer to native, disable text selection for the interface and keep it enabled only for content the user may actually want to copy.
+- `::target-text` styles the phrase a shared link scrolls to.
+- The Custom Highlight API styles ranges you pick yourself, like search matches, without extra markup.
+
+## Forms and editable text
+
+- `::placeholder` styles the hint in an empty field.
+- `caret-color` colors the blinking insertion bar. Color is about as far as caret styling goes: a fully custom caret is very difficult to build and usually not worth it unless a very specific effect calls for it.
+
+### iOS input zoom
+
+Focusing an input with text smaller than `16px` zooms the whole page (an accessibility feature: `16px` is the web default and Safari treats smaller as too hard to read while typing).
+
+```tsx
+// Good: 16px on mobile, smaller from the sm breakpoint up
+<input className="text-base sm:text-sm" type="email" />
+```
+
+Avoid the `maximum-scale=1` viewport meta as a fix: Safari ignores the cap for pinch zoom, but every other browser honors it and restricts pinch zoom, which fails WCAG 1.4.4. The responsive input size solves the zoom with no accessibility cost.
+
+## Decorative text
+
+| Property | Effect |
+| --- | --- |
+| `::first-letter` | Drop cap, widely supported |
+| `::first-line` | Styles only the first line |
+| `initial-letter` | Sizes the drop cap; limited support, no Firefox yet |
+| `background-clip: text` | Clips a background or gradient to the letter shapes |
+| `-webkit-text-stroke` | Outlines the letters; works across modern browsers despite the prefix |
+| `text-shadow` | Like `box-shadow` but follows the character shapes |
+
+If a text stroke draws lines inside the letters, that is the font: the stroke traces every contour and variable fonts usually keep overlapping shapes unmerged. Static fonts do not have this issue.
+
+## Sizes and contrast
+
+Typography must survive the reader changing it: zoom, a larger browser font size, overridden line height or letter spacing.
+
+| Text | Size |
+| --- | --- |
+| Body | `16px` (the web default, the right reading size) |
+| Inputs and menus | `14px` |
+| Captions | `13px` |
+| Floor | Rarely below `12px` |
+
+WCAG AA contrast:
+
+| Text | Minimum |
+| --- | --- |
+| Regular text | `4.5:1` |
+| Large text (~`24px`+) | `3:1` |
+
+Bigger, heavier letters stay legible at lower contrast.
+
+## Font smoothing
+
+On macOS text renders heavier than intended. Apply font smoothing once on the root layout so it covers all text. Tailwind's `antialiased` sets both properties:
+
+```css
+html {
+  -webkit-font-smoothing: antialiased;
+  -moz-osx-font-smoothing: grayscale;
+}
+```
+
+```tsx
+<html lang="en">
+  <body class="font-sans antialiased">
+    <main>{children}</main>
+  </body>
+</html>
+```
+

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@its-thepoe/better-typography",
+  "version": "1.0.0",
+  "description": "Agent Skill: better-typography.",
+  "license": "MIT",
+  "keywords": [
+    "agent-skills",
+    "better-typography",
+    "design",
+    "ui"
+  ],
+  "files": [
+    "README.md",
+    "SKILL.md",
+    "*.md",
+    "package.json"
+  ],
+  "exports": {
+    ".": "./SKILL.md",
+    "./SKILL.md": "./SKILL.md"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/its-thepoe/skills.git",
+    "directory": "design/better-typography"
+  }
+}

package/spacing-and-sizing.md

@@ -0,0 +1,104 @@
+# Spacing and sizing
+
+A sensible scale and comfortable spacing do more for typography than any effect.
+
+## Units
+
+| Unit | Behavior |
+| --- | --- |
+| `px` | Fixed |
+| `em` | Scales with the current font size |
+| `rem` | Scales with the root font size |
+| `%` on `font-size` | Relative to the parent's font size, behaves like `em` |
+
+## Type scale
+
+A small set of predefined sizes used across a product, deviated from as little as possible. Hard-coding sizes without a system breaks down at scale.
+
+```css
+:root {
+  --text-sm: 0.875rem;
+  --text-base: 1rem;
+  --text-lg: 1.125rem;
+  --text-xl: 1.5rem;
+  --text-2xl: 2rem;
+}
+```
+
+There are many existing scales to pick from, or define a custom one. The Tailwind type scale (`text-xs` through `text-9xl`, each class pairing a size with a matching line height) is a solid ready-made choice.
+
+For solo projects the default names work fine as long as there are clear rules for where each size is used. On a team, give sizes semantic names: `text-sm` tells you the size but not the use; `text-body-sm` keeps sizes consistent with clear usage rules.
+
+## Heading hierarchy
+
+Assign each heading level to a descending step of the scale, so hierarchy comes from the scale instead of one-off sizes:
+
+```css
+h1 { font-size: var(--text-2xl); }
+h2 { font-size: var(--text-xl); }
+h3 { font-size: var(--text-lg); }
+```
+
+In Tailwind the same mapping is utility classes per level (`text-2xl`, `text-xl`, `text-lg`), typically centralized in a component or `@layer base` rather than repeated inline.
+
+When reviewing a page, compare the computed size of each heading level across the whole page: a level that renders larger than the one above it (an `h3` bigger than an `h2`) breaks the hierarchy and reads as a mistake. Deep levels (`h4`, `h5`) may share a size when the scale runs out of comfortable steps, as long as weight or letter-spacing keeps them distinct. A heading should not be smaller than body text unless it is deliberately a label-style overline.
+
+Heading levels are also a navigation structure: screen readers jump through a page by level. Keep the outline sequential (one `h1`, no skipped levels) and pick the tag from the document structure, never because a lower level "looks right" at its default size. The size belongs in CSS.
+
+## Kerning and letter-spacing
+
+- **Kerning** adjusts specific pairs like `AV` or `Ye`. It is built into the font and browsers apply it automatically. Only switch it off deliberately with `font-kerning: none`.
+- **`letter-spacing`** adds the same space between every character:
+  - Large headings often look better slightly negative.
+  - Small uppercase labels need a little positive spacing so letters do not feel crowded.
+  - Body copy needs neither.
+
+```css
+/* Good */
+.display-heading {
+  letter-spacing: -0.02em;
+}
+
+.uppercase-label {
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+}
+```
+
+## Line-height
+
+| Text | Value |
+| --- | --- |
+| Headings | ~`1.1` |
+| Body copy | `1.5`–`1.6` |
+
+Prefer unitless values: they scale with the font size, fixed values like `line-height: 24px` do not. Tailwind's `leading-snug`, `leading-normal` and `leading-relaxed` are sensible defaults that rarely need overriding.
+
+## Text trimming with text-box
+
+Fonts reserve space above and below the letters, which is why text sits slightly too low in buttons and badges. `text-box` trims it. Two parts: which edges to trim (`trim-both`, `trim-start`, `trim-end`) and where:
+
+| Keyword | Trims at |
+| --- | --- |
+| `cap` | The cap height (top) |
+| `alphabetic` | The baseline (bottom) |
+| `text` | The font's own text edge, keeping room for descenders |
+
+```css
+/* trim top and bottom */
+.badge {
+  text-box: trim-both cap alphabetic;
+}
+
+/* trim only the top */
+.heading {
+  text-box: trim-start cap;
+}
+
+/* trim only the bottom */
+.label {
+  text-box: trim-end alphabetic;
+}
+```
+
+Browser support is still limited; treat it as progressive enhancement.

package/variable-fonts-and-opentype.md

@@ -0,0 +1,102 @@
+# Variable fonts and OpenType
+
+What a font file can do beyond drawing letters, and how to reach those abilities from CSS.
+
+## Static vs variable
+
+- **Static font:** one weight and one style per file. Regular + medium + bold = three files.
+- **Variable font:** an entire range in one file. Any value in the range works, e.g. `font-weight: 589`.
+
+A variable font is not automatically better. One or two weights: static files can be smaller. Several weights, optical sizes or custom axes: a variable font usually makes more sense.
+
+## No fake weights
+
+When you use a weight or style you have not loaded, the browser synthesizes it. It works, but it is a safety mechanism, not a feature. Disable it so missing files fail visibly:
+
+```css
+:root {
+  font-synthesis: none;
+}
+```
+
+## Axes
+
+Variable-font controls, each with a four-letter tag. A font only supports the axes its designer included.
+
+| Axis | Tag | Controls |
+| --- | --- | --- |
+| Weight | `wght` | Stroke thickness (like `font-weight`) |
+| Optical size | `opsz` | Details and spacing tuned for the display size |
+| Width | `wdth` | Glyph width |
+| Slant | `slnt` | Slant angle |
+| Custom | e.g. `GRAD` (Roboto Flex) | Whatever the designer built |
+
+Inter's variable file exposes only `wght` and `opsz`.
+
+Optical sizes predate variable fonts and many fonts still ship them as separate files: Heldane Text is sturdier and more spaced for reading sizes, Heldane Display has finer details for large sizes.
+
+## Properties over axis tags
+
+When a property exists, use it. `font-weight` keeps working when a non-variable fallback renders; `font-variation-settings` silently does nothing. Save the raw tags for custom axes with no property of their own:
+
+```css
+/* Good: common axes use the properties */
+.heading {
+  font-weight: 650;
+  font-optical-sizing: auto;
+}
+
+/* Good: custom axis with no property of its own */
+.heading-grade {
+  font-variation-settings: "GRAD" 80;
+}
+
+/* Bad: weight via raw tag breaks on fallback fonts */
+.heading {
+  font-variation-settings: "wght" 650;
+}
+```
+
+## OpenType features
+
+OpenType is the standard behind almost every modern font. Features are extra built-in options and, unlike axes, they work the same on static and variable fonts. A font only ships the features its designer included.
+
+| Tag | Feature |
+| --- | --- |
+| `tnum` | Tabular numbers: every digit the same width |
+| `zero` | Slashed zero: `0` distinct from `O` |
+| `liga` | Ligatures: joins pairs like "fi" into one shape |
+| `ss01`–`ss20` | Stylistic sets (numbered slots) |
+| `cv01`–`cv99` | Character variants (numbered slots) |
+
+Same rule as axes: prefer the `font-variant-*` properties, reserve `font-feature-settings` for tags with no property:
+
+```css
+/* Good: common features use the properties */
+.price {
+  font-variant-numeric: tabular-nums;
+}
+
+/* Good: slashed zero via the property too */
+.id {
+  font-variant-numeric: slashed-zero;
+}
+
+/* Good: niche feature with no property of its own */
+.logo {
+  font-feature-settings: "ss01" 1;
+}
+```
+
+Tabular numbers matter for changing values: without them each digit has a different width and the layout shifts as values update.
+
+## Small caps, superscripts, subscripts
+
+- **Small capitals:** uppercase letters drawn at a smaller size. Enable real ones with `font-variant-caps`.
+- **Superscripts** sit above the normal line (the 2 in x²), **subscripts** below it (H₂O). Enable proper glyphs with `font-variant-position`.
+
+Both require the font to include the glyphs.
+
+## Stylistic sets and character variants
+
+`ss01` = stylistic set, slot 01. `cv11` = character variant, slot 11. What each slot does differs font to font, which is why they are numbered, not named. Check the font's docs. In Inter, `ss01` switches to open digits and `cv11` swaps in a single-story `a`.

package/wrapping-and-punctuation.md

@@ -0,0 +1,70 @@
+# Wrapping and punctuation
+
+Where lines start, where they end, where they break and which characters they use.
+
+## Measure (line length)
+
+Long lines make it harder for the eye to find the start of the next line. For long-form text, aim for 60–75 characters per line.
+
+Any unit works. `65ch` measures characters directly (one `ch` is the width of the `0` in the current font), but a pixel or rem cap is just as good: at a `16px` body size the 60–75 character range lands roughly between `560px` and `680px` depending on the font, so Tailwind's `max-w-xl` (`576px`) or `max-w-2xl` (`672px`) fit. What matters is that a cap exists and the resulting line length sits in range; recheck it if the body font size changes.
+
+## Alignment
+
+`text-align` controls where each line starts and ends. `text-align: justify` stretches spaces until both edges line up; it can work in specific editorial layouts but avoid it in most interfaces.
+
+## Wrapping
+
+| Property | Use |
+| --- | --- |
+| `text-wrap: balance` | Distributes text evenly across multiple lines |
+| `text-wrap: pretty` | Avoids leaving a single short word on the final line |
+| `overflow-wrap: break-word` | Lets long words, links and IDs break before escaping the container |
+| `white-space: nowrap` | Keeps labels and badges on one line where a break looks broken |
+
+Use `balance` on headings and `pretty` on descriptions; combined they give the best outcome. Skip both in long-form text: browsers ignore `balance` past a few lines anyway, and evening out a whole paragraph wastes space and makes it harder to read.
+
+## Truncation
+
+- Single line: `text-overflow: ellipsis`, which needs `overflow: hidden` and `white-space: nowrap`.
+- Multiple lines: `line-clamp` allows any number of lines before the ellipsis.
+
+Truncation hides content. If the missing text matters, make the full value available elsewhere (tooltip or expanded view).
+
+## Case
+
+`text-transform` changes how case appears without changing the underlying text. Write copy naturally and control presentation with CSS, so changing presentation never requires rewriting copy.
+
+## Smart punctuation
+
+Keyboard characters are not always the best characters:
+
+| Instead of | Use |
+| --- | --- |
+| Straight quotes `"..."` | Curly quotes that curve around the text (keep straight quotes in code) |
+| Hyphen in ranges | En dash: `2010–2020` |
+| Two hyphens for an aside | Em dash character |
+| Three periods `...` | The single ellipsis character `…` |
+| Regular space in `16 px` | ` ` so the value never breaks apart |
+| Uncontrolled word breaks | `­` to mark where a word may break |
+
+## Internationalization
+
+- Set the `lang` attribute so browsers choose the right quotes, hyphenation and pronunciation.
+- Use `dir="rtl"` for right-to-left content.
+- To support both directions, use logical properties everywhere a directional one exists:
+
+```css
+/* Good */
+p {
+  margin-inline-start: 8px;
+  text-align: start;
+}
+
+/* Bad: breaks in RTL */
+p {
+  margin-left: 8px;
+  text-align: left;
+}
+```
+
+The same applies to `padding` and every other directional property.