design-engineering
Skill1 starsChanged 3 days agoMITView on GitHub
Frontend craft rules for details that break under real use: hover and focus states that move layout, typography that shifts, variable-font axes, motion that costs frames. Use when building or reviewing UI where a state change, a font, or an animation can push neighbouring elements around — nav links that grow on hover, buttons that resize, tables whose numbers jitter, hover effects that reflow. Also use when the user asks about font weight on hover, variable fonts, font-variation-settings, GRAD or grade axes, or layout shift from a style change.
8 other projects use a version of this.
Adopted by
Most recently taken up by
- flowcopilot/skillstheir own version, first seen Nov 15, 2026
- AgentsORG/design-engineeringtheir own version, first seen Nov 7, 2026
- FradSer/skillstheir own version, first seen Nov 1, 2026
- 2bTwist/dotagentstheir own version, first seen Oct 13, 2026
- moumen-soliman/uitripledtheir own version, first seen Oct 8, 2026
- rohitg00/pro-workflowtheir own version, first seen Sep 29, 2026
Other versions8 projects use a version of this.
Word for word · 0
None found.
Edited · 0
None found.
Wrote their own version · 8
- rohitg00/pro-workflow★ 2.9ksame name
- moumen-soliman/uitripled★ 1.4ksame name
- broomva/skills★ 4same name
- FradSer/skills★ 4same name
- AgentsORG/design-engineering★ 3same name
- flowcopilot/skills★ 1same name
- 2bTwist/dotagents★ 0same name
- ryktara/design-engineering-skill★ 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 repository22 other files it gives its agents.
- analyze-logsSkill
- architectSkill
- build-audit-logsSkill
- cloudflareSkill
- code-reviewSkill
- diagnosing-bugsSkill
- full-sendSkill
- full-stopSkill
- ghSkill
- grillingSkill
- impeccableSkill
- improve-animationsSkill
- interrogateSkill
- no-use-effectSkill
- prSkill
- retroSkill
- t3-toolsSkill
- triageSkill
- unslopSkill
- vitestSkill
- wait-whatSkill
- writing-for-agentsSkill
The file
We split this skill into the rules it gives an agent
8 rules. 0 are common, 6 are distinctive, and 2 are very specific to this project.
0
Common
Most of the 8 edited versions we read keep these.
6
Distinctive
This author's own choices. Worth a look.
2
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 12
Use this when the work touches states, typography, or motion.
- Distinctive: line 51
3. Reserve the width: When bold really is the design, hold the space so the swap cannot move anything: keep the widest metrics in the box, …
- Very specific: line 69
Do not reach for min-width in pixels to fake it.
- Distinctive: line 87
Use the property for the axes that have one, and the raw tag only for custom axes.
- Distinctive: line 132
Keep the transition short and on the exit path too, or the row feels sticky.
- Distinctive: line 145
Use it in tables, counters, timers, prices, and any list where one value updates in place.
- Distinctive: line 164
Look at the row with the longest real content, in the longest supported language.
- Distinctive: line 165
Check the state at the sizes it ships at: a hover bug at 1440px can be invisible at 390px and the reverse.
“Common” is measured: kept by at least 6 in 10 of the 8 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
Design engineering
The rules that only show up after the design is built: a hover that moves the nav, a weight that is wider than the one it replaced, a transition that drops frames, a synthetic bold that renders twice.
Use this when the work touches states, typography, or motion. For direction, hierarchy,
colour and the wider craft floor, the impeccable skill has the deeper references.
The rule that catches the most: emphasis must not resize anything
Making nav links bold on hover pushes everything next to them. Heavier weights are also wider.
A weight change is a metric change. In a flex or inline row the wider glyphs take space from the siblings, so the row reflows, wraps, or nudges. Nothing about it looks like a bug: it looks like the page was never designed.
Three ways out, in order of preference:
1. Do not change the weight. Colour, opacity, an underline, or a small scale are
enough to say "this one is hovered". These cost no layout.
/* Good: the box never changes size */
.nav a {
color: var(--fg-muted);
transition: color 140ms ease-out;
}
.nav a:hover {
color: var(--fg);
}2. Use the grade axis, if the family has one. A grade axis darkens the stroke without touching the glyph's advance width, so the text looks bolder and stays exactly as wide.
/* Needs a family that ships GRAD (Roboto Flex and friends) */
.nav a:hover {
font-variation-settings: "GRAD" 150;
}3. Reserve the width. When bold really is the design, hold the space so the swap cannot move anything: keep the widest metrics in the box, always.
/* The invisible bold copy holds the space the bold text will need */
.nav a {
position: relative;
}
.nav a::after {
content: attr(data-label);
font-weight: 700;
visibility: hidden;
display: block;
height: 0;
pointer-events: none;
}Do not reach for min-width in pixels to fake it; that breaks at the next font size and
the next language.
Weight is width
Any time the weight changes, the metrics change with it. The same rule applies to
font-stretch, font-style, letter-spacing, and a different family.
font-weight: 700is not "the same text, darker". It is a different set of glyphs.- Synthetic bold (the browser faking a weight the family lacks) is wider still, and it doubles the paint.
- Interpolating between weights at runtime changes width per frame. Never animate
font-weighton a live element.
Properties over axis tags
font-weight keeps working when a non-variable fallback renders.
font-variation-settings silently does nothing on a fallback that has no such axis.
Use the property for the axes that have one, and the raw tag only for custom axes.
/* Good */
.heading {
font-weight: 650;
font-optical-sizing: auto;
}
/* Good: custom axis, 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;
}Set font-synthesis: none only after verifying the real family is loaded for every
weight and style the design uses. Otherwise the browser fakes the missing ones, and the
fakes are wider than the real thing.
Animating a variable axis
font-variation-settings does not interpolate on its own. Register the number as a
property and animate that.
@property --grade {
syntax: "<number>";
inherits: false;
initial-value: 0;
}
.nav a {
font-variation-settings: "GRAD" var(--grade);
transition: --grade 160ms ease-out;
}
.nav a:hover {
--grade: 150;
}Keep the transition short and on the exit path too, or the row feels sticky.
Numbers that stay put
Digits change width between fonts and between weights, so a table of numbers jitters as it updates.
.data {
font-variant-numeric: tabular-nums;
}Use it in tables, counters, timers, prices, and any list where one value updates in place.
States that do not move
:hoverand:focuschange paint, not geometry.transform,opacity,color,background,border-color,box-shadow,text-decoration-colorare safe.font-weight,font-size,padding,border-width,width,heightare not.:focus-visiblegets a ring that does not shift the layout. Anoutlinedoes not affect layout; aborderdoes.- Underline on hover: animate
text-decoration-color, not the decoration itself. Colour is the only part of a real underline that animates reliably. - Under
prefers-reduced-motion: reduce, cut transforms and long transitions. Keep colour changes: they are not motion.
Verify, do not assume
- Measure the element in the layout at rest and on hover. Any width difference is a failure, whatever the intent.
- Look at the row with the longest real content, in the longest supported language.
- Check the state at the sizes it ships at: a hover bug at 1440px can be invisible at 390px and the reverse.
- Load the real font. A fallback swaps the metrics and hides every bug above.
Reference
- references/typography.md: the axes, what each one does to the metrics, and the fallback behaviour.
impeccable, referencedetails-type.md: type scale, wrapping, truncation, features.impeccable, referencedetails-motion.md: transitions, press feedback, entrances.
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.

