This repo distills Butterick's Practical Typography into an agent skill. Contributions are welcome, and the bar is specific — please read it before writing.
- Rule corrections, with provenance. If the skill misstates a rule, cite the chapter on practicaltypography.com that shows the correct one.
- New coverage for media or elements the skill handles thinly (e.g., footnotes, forms, ebooks) — sourced from the book's chapters, or explicitly marked as a deviation with reasoning.
- New presets for the user-preference protocol, with real-world grounding (what actual publications ship, measured — not guessed).
- Fixes: broken links, unclear steps, typos, structural problems.
Every rule is classified and traceable. Add or update a stable rule ID in skills/typography/provenance.md. Use PT for a faithful Practical Typography paraphrase, DEVIATION for a project-authored heuristic or workflow choice, and CURRENT for an accessibility, internationalization, platform, semantic, or legal requirement from another primary authority. Record scope, source or rationale, verification date when time-sensitive, and evaluation IDs. Unclassified guidance is a bug even when it is good advice.
Ranges stay ranges and units keep their meaning. Butterick gives ranges because many solutions work. Do not narrow them to a single “best” value or add precision the source does not carry. CSS ch is the width of the zero glyph, so it may set up a measure but cannot prove an actual character count.
Edits are tested before they ship. Add or update a versioned scenario in evals/scenarios.json, a minimal fixture, the pre-change failure, required and prohibited findings, priority expectations, and the necessary evidence level. Run node evals/check.mjs and the affected risk classes. “It reads better” is not an observable result.
Higher-risk changes need broader regression. Changes involving character transformations, web layout, fonts, exports, accessibility, or language/script behavior must run every affected risk class, not only the happy path. A public claim must identify its scenario, fixture, output, tool context, and result.
Freshness is explicit. Source-derived lists, publication measurements, platform behavior, and standards references must carry a verification date. Run the review-only node evals/source-drift.mjs when changing source-backed guidance; a drift warning prompts human review and never rewrites rules automatically.
Worked examples come from real sessions. Do not compose a plausible transcript — the difference is visible, and a fabricated example undermines the demo's credibility.
Scope discipline. The skill prescribes typography, not tooling. Reveal.js config, hex color palettes, framework specifics stay out of SKILL.md; if they're genuinely needed, they belong in media.md as clearly-scoped implementation notes.
These skills run across different agents. Keep them portable:
- Frontmatter is
nameanddescriptiononly. No other keys. - No tool-specific syntax in any skill body: no agent names, no slash-commands, no vendor-specific formatting conventions.
- Relative paths only. Portable skill files reference siblings such as
fonts.mdandweb.md, never absolute paths. - English only, plain markdown.
- Open an issue first for new coverage or a new preset. State the source chapter (or the deviation and its reasoning) and the scenario where agents currently fail without it.
- Then open a PR meeting the quality bar above.
For corrections and fixes, a PR without a prior issue is fine — include the source citation in the PR description.