CSS font-variation-settings: use a verified custom axis

When to use it

A licensed annotation typeface offers a custom grade axis named GRAD, with the range and value 40 confirmed from that particular file's metadata. The annotation label needs a slightly heavier stroke without changing its width, so the component sets the custom axis while ordinary font-weight remains a high-level property. The asset path in the sample is illustrative and must be replaced with a real font carrying that axis before release. Verify the axis in the shipped binary, its license, fallback appearance, and glyph coverage for localized text. Test regular and bold labels, because a low-level registered wght setting could override font-weight even if placed in another rule. If a later rule changes font-variation-settings, it replaces the entire axis list; redeclare all needed axes or coordinate through custom properties. Do not animate grade simply because the file permits it: repeated glyph rasterization may cost more than the small visual gain, and motion can distract from the annotation itself.

@font-face { font-family: "Annotation Axis"; src: url("/assets/annotation-axis.woff2") format("woff2"); font-weight: 300 700; }
.annotation-label { font-family: "Annotation Axis", sans-serif; font-weight: 520; font-variation-settings: "GRAD" 40; }
.annotation-label--quiet { font-variation-settings: "GRAD" 0; }

Cost and verification

A variable font can reduce the need for separate static files, but the actual file size and subset strategy determine transfer cost. The illustrative asset is not present in this repository. Do not publish the example as a working feature until that licensed file is supplied and its GRAD range verified. Axis values outside a font's design range can be clamped, and a fallback font will ignore the custom setting. Validate in the target browser and inspect actual glyph output, not only computed CSS. Avoid setting registered axes through this low-level property when a dedicated CSS property can express the intent; that prevents confusing precedence during maintenance.

Common Mistakes

• Do not invent a custom axis or its range from the CSS alone.
• Do not use low-level wght to fight an existing font-weight rule.
• Do not assume a fallback font responds to GRAD.

Connected lessons

• CSS Property Decisions
• CSS variable fonts: declare the supported weight range
• CSS font-optical-sizing: inspect the font's size-specific drawings
• CSS font loading: keep content readable while a font arrives
• CSS unicode-range: request only the font subset a page uses