@metreeca/skin - v0.2.0

Design system.

Names the tokens an app may override to restyle an interface, and a component reads to inherit that styling, and gives the custom property each one resolves to, for a value taken outside the cascade. A token is read wherever a CSS value is written by hand, and assigned to a subtree through a style declaration any rendering layer accepts. The values behind them are provided by the companion stylesheet.

An app that includes the stylesheet gets the Metreeca look by default, light or dark according to the platform colour scheme; one that redefines the tokens gets its own, with no component change. Components name tokens through this contract rather than through literal strings, so a renamed token breaks the build instead of losing its style.

The tokens cover typography, spacing, sizing, borders, colours, elevation, data palettes, stacking, motion, opacity, viewport breakpoints and the look of an area. skin gathers them all in one place, so a consumer names a token without knowing which of these concerns it belongs to or importing anything beyond the package root.

Example

Include the stylesheet once, at the entry point of the app:

import "@metreeca/skin/index.css";

Override any token to restyle the whole interface, stating a colour for both schemes as a light-dark() pair:

:root {
    --skin--color-strong: light-dark(#06C, #4AF);
    --skin--font-family: Inter, sans-serif;
}

Pin a colour scheme, on the root element or on any subtree that has to differ from the page:

<aside data-theme="dark">

Assign the tokens inline to restyle a single subtree instead:

<section style={css({ colorStrong: "#06C" })}>

Read a token where a single CSS value is written by hand:

<span style={{ backgroundColor: css.var(skin.colorStrong) }}/>

Remarks

Override order — the stylesheet declares its rules in a skin cascade layer, so a rule an app or a component writes outside a layer wins whatever order the two stylesheets reach the document in, and whichever selector is the more specific. An app declaring layers of its own orders them after skin, or the design system outranks them.

Missing and malformed values — a token carrying a literal states it as the registered default of its custom property, so the value lives in one place. A malformed override is caught only where the token has a fixed type: a weight, a duration or an opacity the browser cannot parse stays on its default. Most tokens, the colour anchors and the sizes among them, take an override as written, so a malformed value leaves whatever reads it unstyled rather than on the default. A component styled against a token it cannot count on, because the stylesheet may not be loaded at all, names its own fallback in the reference it writes by hand, the one case css.var does not cover, stating the shipped light default: var(--skin--color-strong, #B74300).

First paint — the stylesheet has to reach the document before it is painted, or the first frame shows the unstyled markup: an app bundling it from the entry point is served by the bundler, while one assembling its own HTML links it in the document head. An override stated in a <style> in the document head is in force from the first frame, so a loader painted before the stylesheet arrives already reads the app's brand.

Values outside the cascade — a consumer painting where a reference doesn't reach, on a canvas or against an API taking a colour as text, takes the value a token resolves to for the element it applies to, rather than a copy of the default, and so keeps whatever the app overrode and whichever colour scheme is in force. A colour token holds a light-dark() pair or a mix until something paints with it, so it is resolved through a colour property of an element in the subtree:

probe.style.color = css.var(skin.colorStrong);
getComputedStyle(probe).color

Variables

skin: The custom property behind every design system token.
css: Overrides design system tokens for a subtree.

Type Aliases

Palette: The scale steps, series slots and area classes, which address a colour by position rather than by role.
Ink: The tokens painting a mark or a passage of text, and the rule between two of them.
Fill: The tokens painting a surface.
Type: The tokens sizing text.
Scaling: The tokens sizing a thing against the text around it.
Spacing: The tokens setting a thing apart from its neighbour.
Radius: The steps a corner is rounded on.
Stroke: The tokens sizing a line.
Tracking: The tokens tracking a run of text.
Weight: The tokens weighting text.
Opacity: The tokens fading a thing present but not available.
Layer: The tokens ordering two things that overlap.
Timing: The tokens timing a change.
Easing: The tokens curving a change.
Shadow: The steps a shadow or an outline is drawn from, each stated as a whole shorthand.
Family: The tokens carrying a font stack.
Flag: The tokens telling which breakpoints the viewport has passed.
Padding: The token padding the element it is assigned to, set from a spacing step.
Rounding: The token rounding the element it is assigned to, set from a radius step.
Lifting: The token lifting the element it is assigned to, set from a shadow step.
Style: An inline style declaration.
Property: The custom property carrying the value of a design system token.
Tokens: The tokens assigned to an area, and what each is assigned.
Token: The name of a design system token.
Value: The value a design system token is assigned.

@metreeca/skin - v0.2.0

Example

Remarks

Variables

Type Aliases

Settings

On This Page