agentleFS
RIJUDEVxRIJUDEVx/agent-skills/design-engineering/SKILL.md

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

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
  1. Very specific:

    Use this when the work touches states, typography, or motion.

    line 12
  2. Distinctive:

    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, …

    line 51
  3. Very specific:

    Do not reach for min-width in pixels to fake it.

    line 69
  4. Distinctive:

    Use the property for the axes that have one, and the raw tag only for custom axes.

    line 87
  5. Distinctive:

    Keep the transition short and on the exit path too, or the row feels sticky.

    line 132
  6. Distinctive:

    Use it in tables, counters, timers, prices, and any list where one value updates in place.

    line 145
  7. Distinctive:

    Look at the row with the longest real content, in the longest supported language.

    line 164
  8. Distinctive:

    Check the state at the sizes it ships at: a hover bug at 1440px can be invisible at 390px and the reverse.

    line 165

“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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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: 700 is 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-weight on 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

  • :hover and :focus change paint, not geometry. transform, opacity, color, background, border-color, box-shadow, text-decoration-color are safe. font-weight, font-size, padding, border-width, width, height are not.
  • :focus-visible gets a ring that does not shift the layout. An outline does not affect layout; a border does.
  • 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, reference details-type.md: type scale, wrapping, truncation, features.
  • impeccable, reference details-motion.md: transitions, press feedback, entrances.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.