better-typography
Skill0 starsChanged todayMITView on GitHub
Sets and reviews how text renders, from the type scale and spacing to font features, wrapping, truncation and punctuation.
33 other projects use a version of this, 28 of them edited.
Adopted by
Most recently taken up by
- vaferkhanom/Website-skillsedited, first seen Nov 16, 2026
- AnnenkovLabs/flectenedited, first seen Nov 15, 2026
- Dimon94/dverityedited, first seen Nov 15, 2026
- Dimon94/skillsedited, first seen Nov 15, 2026
- compozy/compozyedited, first seen Nov 13, 2026
- memi-design/design-skillstheir own version, first seen Nov 8, 2026
Used with
Projects with it also use improve-ui, good-css and 4 more.
Other files people use alongside this one.
Files found in the same public projects as a version of this one, more often than they turn up anywhere else. Each project counts once, large collections count for less, and this file's own repository is left out.
Discriminative-shoji607Skillimprove-ui
Audit an existing product surface against its own design evidence, identify verified UI problems, and write self-contained implementation plans for another agent. Strictly read-only on product source. Use when asked to review, refine, improve, or clean up an interface without replacing its identity; investigate design-system drift; or prepare a design handoff.
Also in 3 projects that use this
sanmidableSkillgood-css
Also in 3 projects that use this
ItamarZand88Skillcreate-design-md
Create a new DESIGN.md file for any website, app, or custom design system. Use when the user wants to document a design system in DESIGN.md format, extract design tokens from a URL or existing CSS, create a custom design system from scratch, author a DESIGN.md for their own project, or contribute a new design to the awesome-design-md collection. Also trigger when user mentions "design system documentation", wants to formalize their app's visual language, or asks to create or generate a DESIGN.md file.
Also in 3 projects that use this
agentset-aiSkillfixing-metadata
Ship correct, complete metadata.
Also in 3 projects that use this
studio-lgtmSkillmake-interfaces-feel-better
Apply design engineering best practices to polish UI components - use when reviewing or improving interfaces, animations, typography, or interaction details.
Also in 5 projects that use this
VercelSkillbaseline-ui
Validates animation durations, enforces typography scale, checks component accessibility, and prevents layout anti-patterns in Tailwind CSS projects. Use when building UI components, reviewing CSS utilities, styling React views, or enforcing design consistency.
Also in 3 projects that use this
Other versions33 projects use a version of this.
Word for word · 1
- jakubkrehel/skills★ 12k100% same
Edited · 28
- trycompai/crm★ 12k10% same
- talebook/talebook★ 5.9k13% same
- compozy/compozy★ 2.9k32% same
- moumen-soliman/uitripled★ 1.4k31% same
- genex-games/genex-desktop★ 87432% same
- Atharvsinh-codez/ObsidianUI★ 56213% same
- boraoztunc/skills★ 47313% same
- Dimon94/dverity★ 10732% same
- Dimon94/skills★ 10732% same
- Tresnanda/kybern★ 9232% same
18 more not listed
Wrote their own version · 4
- memi-design/design-skills★ 7same name
- hsynozdamar-byte/claude-skills-edited★ 4same name
- amanjotx/Agent-Skills★ 0same name
- elpiarthera/vantage-starter★ 0same name
How matches are found. Word for word: the exact same text. Edited: shares passages with this file (“99% same” means 99% of its five-word phrases also appear here; 10% or more counts). Their own version: similar meaning, or, weakest, the same name. We can’t tell which project had it first. Projects are counted among the 200 most-starred candidates, and mentions are links to the repository we found, up to 50 per site, so both counts are a floor.
In this repository72 other files it gives its agents.
- animate-expoSkill
- animateSkill
- animation-performanceSkill
- animation-vocabularySkill
- apple-designSkill
- ask-emilSkill
- ask-mattSkill
- ask-sonnerSkill
- break-uiSkill
- chief-of-staffSkill
- choreographSkill
- claritySkill
- claude-handoffSkill
- codebase-designSkill
- code-reviewSkill
- cold-emailSkill
- content-strategySkill
- copywritingSkill
- croSkill
- diagnosing-bugsSkill
- domain-modelingSkill
- emil-design-engSkill
- find-animation-opportunitiesSkill
- frontend-designSkill
- gesturesSkill
- git-guardrails-claude-codeSkill
- grillingSkill
- grill-meSkill
- grill-with-docsSkill
- handoffSkill
- implementSkill
- implement-specSkill
- improve-animationsSkill
- improve-codebase-architectureSkill
- learn-tasteSkill
- loop-meSkill
- marketing-psychologySkill
- migrate-to-shoehornSkill
- mobile-nativeSkill
- persuasionSkill
- pick-ui-librarySkill
- prisma-client-apiSkill
- programmatic-seoSkill
- prototypeSkill
- prototype-variantsSkill
- prSkill
- remove-animationsSkill
- researchSkill
- retroSkill
- review-animationsSkill
- scaffold-exercisesSkill
- seo-auditSkill
- setup-matt-pocock-skillsSkill
- setup-pre-commitSkill
- setup-ts-deep-modulesSkill
- Skillpack Self-testSkill
- software-factorySkill
- supabase-postgres-best-practicesSkill
- tddSkill
- teachSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
6 rules. 0 are common, 0 are distinctive, and 6 are very specific to this project.
0
Common
Most of the 32 edited versions we read keep these.
0
Distinctive
This author's own choices. Worth a look.
6
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 30
When a CSS property exists, use it.
- Very specific: line 32
Leave font-optical-sizing at its default auto.
- Very specific: line 67
Keep interface text at text-align: start.
- Very specific: line 96
Keep font-size: 16px and render the intended size with transform: scale().
- Very specific: line 102
Start long-form body text at 16px, the browser default.
- Very specific: line 124
Keep text selectable by default.
“Common” is measured: kept by at least 6 in 10 of the 32 edited versions of this file we could read. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Typography
This skill sets and reviews how text renders, from the type scale and spacing to font loading, wrapping and punctuation. It writes every fix in the project's styling system, and the cheat sheet maps each declaration to its Tailwind utility.
The words belong to better-writing, semantic heading structure to better-accessibility and spatial RTL layout to better-layout. Measure contrast with better-colors; whether it passes is better-accessibility's.
Measured, not preferred
Some values here are exact. Unitless line-height, weight 400 or heavier below 18px, a 60–75 character measure, 16px inputs on iOS and tabular-nums on changing values are findings when missed.
Letter-spacing, pairing and scale ratios are heuristics. Report them only where they break the project's own scale. Never propose a new typeface, paid or free, unless the task asks for a type change.
Fewer fonts, sizes and weights
Rarely use more than three fonts; marketing pages can carry more than apps. Weight and size carry hierarchy, so each extra one dilutes it. Pair for contrast. A serif headline over a sans body reads as deliberate, two near-identical sans-serifs read as a mistake.
Below 18px, use weight 400 or heavier. Weights 100–300 belong at 28px and up, checked against the background even there. Categories, Display and Text cuts, formats and fallback stacks are in choosing-fonts.md.
Load the faces the design uses
Browsers synthesize a weight or style the family doesn't ship, distorting the face. Load every face the design uses. Disable synthesis only after verifying the fallback stack, and only the unwanted mode. The synthesis longhands show how.
Properties over raw tags
When a CSS property exists, use it. font-weight: 650, not font-variation-settings: "wght" 650. font-variant-numeric: tabular-nums, not font-feature-settings: "tnum" 1. Properties keep working when a non-variable fallback renders.
Leave font-optical-sizing at its default auto. Hard-code "opsz" only when the design deliberately decouples optical size from font size. Reserve raw tags for custom axes like "GRAD" 80 and features with no property, like "ss01" 1. Axes, features and variable versus static files are in variable-fonts-and-opentype.md.
Use a type scale with semantic names
Define a small set of sizes and deviate from it as little as possible. Pair each size with its line-height and weight, so a role is one decision instead of three.
Solo, default names like text-sm are fine when the usage rules are clear. On a team, name sizes by use (text-body-sm) so the rules survive other people. A role-based starting scale is in the reference.
Heading sizes descend with level
Map heading levels to descending steps of the scale, so a subordinate heading never overpowers its parent. Deep levels may share a size where the scale runs out of steps, as long as weight or letter-spacing keeps them distinct. A heading is never smaller than body text unless it is a deliberate overline. See the level mapping.
Line-height by role
Display text 1.1, headings 1.2–1.3, body copy 1.5–1.6. Use unitless values so line-height scales with the font size; a fixed 24px does not.
Tight line-height is for short text. Anything that wraps to three or more lines needs at least 1.4, even in a height-constrained row. See the card description example.
Letter-spacing by size
Headings at 24px and up take -0.01em to -0.02em. Uppercase labels at 14px or smaller take 0.05em. Body copy stays at 0. Use em so tracking scales with the size.
Kerning is built into the font and on by default. font-kerning: none is never a fix.
Cap the measure
Cap long-form text at 60–75 characters per line. Any unit works, as long as a cap exists and the line length lands in range. See unit choices and the pixel equivalents.
Wrap deliberately
text-wrap: balanceevens out headings and short descriptions. Never on paragraphs, and Chromium ignores it past six lines.text-wrap: prettykeeps a lone word off the last line. Safe on any paragraph, long-form included.overflow-wrap: break-wordwhere a long word, link or ID could escape the container.white-space: nowrapon labels and badges where a line break looks broken.
Keep interface text at text-align: start. justify belongs only in specific editorial layouts.
Tabular numbers on changing values
Apply font-variant-numeric: tabular-nums to timers, counters, prices and numeric table columns, so every digit keeps one width and nothing shifts. Leave figures in prose proportional.
Truncate with a way back
For one line, overflow: hidden, text-overflow: ellipsis and white-space: nowrap, which Tailwind's truncate sets together. For several, display: -webkit-box, -webkit-box-orient: vertical, -webkit-line-clamp: 3 and overflow: hidden, which Tailwind's line-clamp-3 emits.
A truncated value needs a way back to the full text, which better-layout owns.
Natural case, typographic punctuation
Store text in natural case and set case with text-transform, so a redesign never means rewriting copy.
Rendered text uses typographic characters, never their keyboard stand-ins. Curly quotes, en dashes, the ellipsis character and non-breaking spaces are in the substitution table. Code keeps straight quotes.
Underlines from the font
Set text-underline-position: from-font and text-decoration-thickness: from-font, or tune text-underline-offset and thickness by hand. A dotted text-decoration-style hints that a word carries extra information, such as an abbreviation or a defined term. See the underline recipes.
Color is the only part of a real underline that animates reliably. Any other underline animation needs a separate element, and its motion is better-ui's.
Inputs at 16px on mobile
iOS Safari zooms the whole page when an input's text is smaller than 16px. Two fixes hold 16px and look different, so ask which one the design wants:
- Size the input up on mobile (
text-base sm:text-sm). Changes how it looks on small screens. - Keep
font-size: 16pxand render the intended size withtransform: scale(). Identical at every viewport, more code to maintain.
Both recipes, plus placeholder and caret styling, are in details-and-accessibility.md.
Size floors
Start long-form body text at 16px, the browser default. Move off it only for a reason you can name, such as a typeface that runs small, a narrow measure or a dense professional tool.
UI text can go smaller. Start inputs and menus at 14px and captions at 13px, and rarely go below 12px. Set font-size in rem so the reader's browser font size still applies.
Font smoothing on the root
Apply -webkit-font-smoothing: antialiased and -moz-osx-font-smoothing: grayscale once on the root, never per component. Tailwind's antialiased sets both.
Language and bidi behavior
Set lang so browsers and assistive technology pick the right quotes, hyphenation and pronunciation. Set dir on the document and wherever direction changes. Wrap a mixed-direction value in <bdi> and never reorder digits by hand. How long paragraphs and numbers behave is in wrapping-and-punctuation.md.
Trim text boxes in tight containers
In buttons and badges, the space a font reserves above and below its letters makes text sit low. text-box: trim-both cap alphabetic trims it as a progressive enhancement. See the edges, keywords and support.
Decorative text in CSS, not images
Build drop caps, gradient text, outlines and text shadows in CSS so the text stays selectable and searchable. The properties and their support are in the reference.
Keep useful text selectable
Keep text selectable by default. ::selection can carry brand into the reading experience, as long as the selected combination stays legible. Styling other ranges such as search matches is in the reference.
user-select: none belongs on a draggable or gesture-driven surface where accidental selection interferes. Never across the interface and never because a button label can be highlighted.
Before you finish
| Pattern | Fix |
font-weight value with no matching weight in the loaded @font-face files | Load that face or use a weight the family ships |
font-synthesis: none on body or interface text | Remove it; set only the unwanted longhand after checking the fallback stack |
font-variation-settings: "wght" or "opsz" | font-weight; drop "opsz" so font-optical-sizing: auto applies |
font-feature-settings: "tnum" or "zero" | font-variant-numeric: tabular-nums or slashed-zero |
line-height in px or rem | A unitless value |
leading-none or leading-tight on a description, card body or anything that can wrap | 1.4 or more |
letter-spacing in px | The same value in em |
Body font-size in px | rem |
Weight 100–300 or font-thin, font-light on text under 18px | 400 or heavier |
text-wrap: balance on a paragraph | text-wrap: pretty |
text-align: justify in application UI | text-align: start |
-webkit-line-clamp without display: -webkit-box | Add display: -webkit-box and -webkit-box-orient: vertical |
A timer, counter, price or numeric column without tabular-nums | font-variant-numeric: tabular-nums |
..., -- or a hyphenated range in rendered strings | …, an em dash or an en dash |
text-decoration-skip-ink: none | Remove it; set text-underline-offset or from-font instead |
<input> with text-sm or 14px and no mobile override | One of the Inputs at 16px on mobile fixes |
-webkit-font-smoothing or antialiased inside a component | Move it to the root |
Mixed-direction value such as a name, number or URL without <bdi> or dir | Wrap it in <bdi> |
user-select: none or select-none on a layout root or text container | Remove it; keep it only on a drag or gesture surface |
Reporting
Severity. HIGH makes text unreadable, truncates content with no way back to it or clips text at 320px width or 200% zoom. The last two are better-interface escalation triggers, so they stay HIGH however minor the surface. MEDIUM breaks the type system or the visual heading hierarchy. LOW is isolated polish.
Verification. Without a browser, check declared size and weight per heading level, descending within each semantic section. Check declared line-height, units and measure. Check truncation rules against realistic string lengths. With one, compare computed values, then resize the viewport with real content to catch wrapping, lone last-line words and truncation. Report every check you could not run as Not verified.
Format. Group findings under the principle each violates, ordered by severity, one row per root cause listing every location it appears in:
| Severity | Location | Before | After | Why |
Location is path/to/file:line. Why names the principle and the user impact.
End with Block when any HIGH remains, Approve otherwise, leaving the rest in the table as work to do. Never Approve coverage you did not inspect. With nothing to report, state "No actionable typography findings" and report verification.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

