Coming from CSS

Padding is the name of a layer in the CSS box model. What a designer means by it is a geometry: the content sits in from the part’s edge by some distance. inset names that distance, in the word iOS, Figma and layout engines already use, and says nothing about a box model that only the web has. The value is a spacing token, so a density change is a foundations change.

part Demo.card: container {
  inset space.md
}
part Demo.button: container {
  inset space.sm space.lg
}

The React target writes

padding when the four edges agree, padding-block / padding-inline when each axis is symmetric, the four logical longhands otherwise.

Read more

/language/styling

A leading icon wants less room on its own side; a nested row wants its indent on the start edge only. Those are paddings on one edge or one axis, and each is its own statement beside the bare inset. The edges are LOGICAL - start and end along the line, start and end across it - because a design system that says left means the wrong side in Arabic, and one that says inline-start means the leading side in every language.

part Demo.chip: container {
  inset.block space.xs
  inset.inline space.md
}
part Demo.button: container {
  inset space.sm space.lg
  inset.inline-start space.md
}

The React target writes

padding-inline-start and the other logical longhands; padding-inline / padding-block when an axis is symmetric.

Read more

/language/styling

A margin is a child reaching outside its own box and dictating the parent’s layout. In the propose/choose model the parent owns the space between its children, so that space is the parent’s gap; a child that must extend past the parent’s padding says position bleed; and margin: auto was always an alignment, so it is distribute or align on the parent. Each of the three means the same thing on every platform, which no margin does.

part Demo.card: container {
  layout { stack column; gap space.md }
  inset space.lg
}
part Demo.card.cover: content {
  layout { position bleed inline block-start }
}

The React target writes

gap on the container; a bleed is a negative logical margin computed from the parent’s inset.

Read more

/language/layout

The same word, because CSS got this one right: the space between children belongs to the container. It takes a spacing token.

part Demo.row: container {
  layout { stack row; gap space.sm; align center }
}

The React target writes

gap.

Read more

/language/layout

One facet, up to three values in any order: a colour token, a width token, and solid, dashed or dotted. Which slot a word fills is decided by the type of the token it names, so the order never matters. A width token has the type border, which is a length type like spacing: a hairline is a token, not a number.

part Demo.input: input {
  border line hairline solid
}
part Demo.divider: container {
  border.block-end line hairline
}
part Demo.tab: container {
  border.inline-start hairline
}

The React target writes

border-style, border-width and border-color (or the per-side longhands), never the border shorthand.

Read more

/language/styling

A radius is how CSS draws a rounded corner; the design decision is the corner. The value is a radius token, and pill is the radius that fully rounds the shorter side - a word rather than 9999px, so every target can draw a pill without knowing the box’s size.

token radius/sm : radius = 6px
token radius/pill : radius = pill

The React target writes

border-radius.

Read more

/language/styling

A part has one size, and its inset is inside it; there is no content-box to choose. display is a target decision: a part is a container, an item, a text, and the target picks the element and how it flows. Overflow handling is a realization detail that differs by platform (a scroll view is a view on iOS and a property on the web), and the language does not state it yet.

Read more

/thinking

fill is what every drawing API calls the paint inside a shape. “Background” implies there is a foreground drawn over it in the same box, which a text part or an icon does not have. The value is a colour token.

part Demo.button: container {
  fill accent
  state hovered { fill accent-hover }
}

The React target writes

background, with the token’s custom property as the value.

Read more

/language/styling

color in CSS means text colour, inherits down the tree, and is the fallback for borders and SVG through currentColor. ink says the foreground outright: text and icon colour, and the colour a border takes when it states none. The web’s inheritance is one target’s realization of that; the facet does not depend on it.

part Demo.label: text {
  ink text
  when ancestor Demo hovered { ink accent }
}

The React target writes

color.

Read more

/language/styling

A shadow is how the web draws depth. Android draws depth as a tonal step, iOS draws it with a different shadow or not at all. The facet states the intent - this part is raised - and points at an elevation token, which aliases by platform to a shadow token on the web and to whatever the other platforms do. The components never know.

context-group Platform { Web iOS Android }

foundations {
  token shadow/card : shadow = raw "0 4px 12px -2px rgba(15,23,42,0.12)"
  token tonal/1 : tonal = 1
  token elevation/card : elevation = alias by Platform { default -> shadow.card; Android -> tonal.1 }
}

The React target writes

box-shadow.

Read more

/language/tokens

The same word and the same meaning: how see-through the whole part is, from 0 to 1. It points at an opacity token so that a disabled look is one decision in foundations.

foundations {
  token opacity/disabled : opacity = 0.5
}

component Demo {
  part Demo: container {
    state disabled { opacity opacity.disabled }
  }
}

The React target writes

opacity.

Read more

/language/styling

A focus ring is a thing every platform draws and each draws differently; outline is one way to draw it. The facet is the ring’s colour, and nothing else: the width and the offset are the target’s, so a ring looks native everywhere. It is usually stated under state focused or state focus-visible.

part Demo.button: control {
  state focus-visible { ring accent }
}

The React target writes

outline: 2px solid <colour> and outline-offset: 2px.

Read more

/language/styling

A text role - body, title, caption - is one decision with several consequences, so it is one typography token with family, size, weight and line height inside, and the part says text body. A font-size token works in the same slot when only the size is meant.

foundations {
  token font/sans : font-family = { family: "Inter"; fallback: sans-serif; source: google; license: "OFL-1.1" }
  token body : typography = { family: font.sans; size: 15px; weight: 400; line-height: 1.5 }
  token size/sm : font-size = 13px
}

component Demo {
  part Demo: container {
  }
  part Demo.label: text {
    text body
  }
  part Demo.hint: text {
    text size.sm
  }
}

The React target writes

The token’s fields as custom properties; font-size for a size token.

Read more

/language/styling

The weight axis of the role, overridden on its own. It takes a font-weight token or a bare number.

part Demo.title: text {
  text body
  weight weight.bold
}

The React target writes

font-weight.

Read more

/language/styling

The family axis of the role, overridden on its own, pointing at a font-family token. The token carries the fallback, the source and the licence, because a generated package has to ship or load the font and say under what terms.

part Demo.code: text {
  font font.mono
}

The React target writes

font-family, with the family and its fallback.

Read more

/language/tokens

The one typography axis that has nothing to tokenise, so its value is a word: normal, italic or oblique.

part Demo.quote: text {
  slant italic
}

The React target writes

font-style.

Read more

/language/styling

Truncating to N lines is a decision about the text, not about the layout, so it is a facet: text.clamp 2. The reader accepts it today; the document does not carry it yet, and no target draws it. A file that states it is read with a note saying so, and the line survives a round trip only in the text.

part Demo.title: text {
  text.clamp 2
}

Read more

/language/styling

How text breaks: wrap, nowrap, pretty, balance. The same standing as text.clamp: read by the reader, not yet carried into the document or drawn.

part Demo.title: text {
  text.wrap balance
}

Read more

/language/styling

A text part is placed by the stack it sits in, with align and distribute, like any other child. Centring a label is a layout decision of the parent, and stating it there is what keeps a text part the same object on every target.

Read more

/language/layout

stack makes a part a container and names the axis its children flow along. layers is the third axis: children drawn on top of one another, the stack sizing to the largest, which is what position: absolute is usually used for. A part with no stack is not a container, and the generator emits no flex box for it.

part Demo.toolbar: container {
  layout { stack row; gap space.sm; align center }
}
part Demo.form: container {
  layout { stack column; gap space.md }
}

The React target writes

display: flex and flex-direction; a layers stack is display: grid with every child in the same cell.

Read more

/language/layout

The main axis: how children are distributed along the direction of the stack. start, center, end, between, around, evenly - the CSS words without the space- prefix and without the flex- prefix, because neither prefix says anything on a platform that has no flexbox.

part Demo.footer: container {
  layout { stack row; distribute between }
}

The React target writes

justify-content.

Read more

/language/layout

The cross axis: start, center, end, stretch, baseline.

part Demo.row: container {
  layout { stack row; align baseline }
}

The React target writes

align-items.

Read more

/language/layout

Whether children start a new line when out of room: nowrap, wrap, wrap-reverse.

part Demo.tags: container {
  layout { stack row; wrap wrap; gap space.xs }
}

The React target writes

flex-wrap.

Read more

/language/layout

A child does not have a width; it has an intent per axis, and the container decides. Five intents replace lengths and the grow/shrink/basis triple: fit (size to content, the default), fill (all the room offered), weight(n) (a share against the siblings), fixed(size.sidebar) (exactly a token’s length), ratio(16:9) (follow the other axis).

part Demo.sidebar: container {
  layout { size fixed(size.sidebar) fill }
}
part Demo.main: container {
  layout { size fill fill }
}
part Demo.thumb: content {
  layout { size height fit }
}

The React target writes

fit-content, 100% across the main axis, a length for fixed; see flex below for fill along the main axis.

Read more

/language/layout

On the axis the siblings share, fill takes the leftover room and weight(2) takes twice the share of a weight(1) sibling. The grow/shrink/basis mechanics are the web’s way of computing that, and the generator writes them.

part Demo.split: container {
  layout { stack row }
}
part Demo.split.list: container {
  layout { size weight(1) fill }
}
part Demo.split.detail: container {
  layout { size weight(2) fill }
}

The React target writes

flex-grow: n, flex-shrink: 1, flex-basis: 0% (or auto when wrapping), plus min-width: 0.

Read more

/language/layout

A clamp on an intent: the axis never shrinks below the one nor grows past the other. The bounds are size tokens.

part Demo.column: container {
  layout { size fill min(size.min) max(size.max) fit }
}

The React target writes

min-width and max-width (or the height pair).

Read more

/language/layout

The axis that follows the other one is the axis that carries the ratio, so the ratio is an intent on that axis: size fill ratio(16:9) is a width that fills and a height that keeps 16:9.

part Demo.video: content {
  layout { size fill ratio(16:9) }
}

The React target writes

aspect-ratio.

Read more

/language/layout

Grid tracks (fr, minmax, auto-fit) are web-leaning concepts with no faithful native equivalent, and a layout concept earns a word only when it means the same thing on every target. grid cols 2 is read and reported, and no target draws it until a second one can.

part Demo.gallery: container {
  layout { grid cols 3 }
}

Read more

/language/layout

An absolutely positioned child is placed by coordinates in a box its parent established. The portable half of that is “on top of its siblings, placed in the parent’s box”, and the stack’s align and distribute place it: a badge sits at the top-end of an avatar because the stack says so. The coordinates are what no other platform would read the same way.

part Demo.avatar: container {
  layout { stack layers; align start; distribute end }
}
part Demo.avatar.badge: container {
  layout { position overlay }
}

The React target writes

position: absolute in a position: relative grid cell, aligned by the grid’s item properties.

Read more

/language/layout

A pinned part stays at an edge of its scroll container: a toolbar at block-start, a bottom bar at block-end. The edges are logical so the layout survives a right-to-left locale.

part Demo.header: container {
  layout { position pinned block-start }
}

The React target writes

position: sticky with the logical inset of the edge set to 0.

Read more

/language/layout

The negative margin trick extends a child past its parent’s padding to the parent’s edge. bleed says that outright, on the edges named, and the generator computes the number from the parent’s inset - so a change to the padding token moves the bleed with it, which the hand-written negative margin never did.

part Demo.card: container {
  layout { stack column; gap space.md }
  inset space.lg
}
part Demo.card.cover: content {
  layout { position bleed inline block-start }
}

The React target writes

margin-inline-start: calc(-1 * var(--ds-spacing-…)) and its siblings, one per bled edge.

Read more

/language/layout

In a layers stack the later child is on top, as in every z-stack. A number that competes across unrelated stacking contexts has no portable meaning, and the problems it solves on the web (a popover above a sticky header) are the overlay realization’s job, not the file’s.

Read more

/language/layout

A state comes from a behaviour, not from a platform: a toggle emits checked, pressability emits pressed, a selection emits selected. The part styles the state by name, and the web generator picks the pseudo-class or data attribute that its realization of the behaviour exposes. pressed rather than active, because active is a state of its own (the current item of a collection).

part Demo.button: control {
  fill accent
  state hovered { fill accent-hover }
  state pressed { fill accent-pressed }
  state focus-visible { ring accent }
  state disabled { opacity opacity.disabled }
}

The React target writes

:hover, :active, :focus, :focus-visible, :disabled, :checked; [data-selected], [data-open], [data-loading] for the states the element has no pseudo-class for.

Read more

/language/styling

A modifier class or a data attribute is a prop made visible to a selector. The file conditions on the prop itself, and the generator decides how the prop reaches the stylesheet.

part Demo.button: container {
  fill accent
  when variant = ghost {
    fill transparent
    ink accent
  }
  state hovered when variant = ghost { fill accent-subtle }
}

The React target writes

A data-variant attribute on the element and an attribute selector in the rule.

Read more

/language/styling

The selector reads outward from the child; the predicate does too, naming the ancestor part and the state. Stating it on the child keeps the ancestor’s part free of knowledge about who styles against it.

part Demo.icon: icon {
  ink text-muted
  when ancestor Demo hovered { ink accent }
}

The React target writes

A descendant selector: .demo:hover .icon.

Read more

/language/styling

Dark mode is a dimension of the system, and a dimension lives in foundations: the token answers per context, and the components never mention it. A facet cannot be aliased (fill alias by … is an error) because the alias belongs where it can be shared.

context-group ColorScheme { Light Dark }

foundations {
  layer Base {
    token white : color = hex(ffffff)
    token gray/900 : color = hex(0f172a)
  }
  layer Semantic {
    token surface : color = alias by ColorScheme { default -> white; Dark -> gray.900 }
  }
}

The React target writes

A [data-color-scheme="dark"] block in theme.css that redefines the custom properties.

Read more

/language/tokens

A token is typed: spacing, radius, size, border, font-size, color, duration and the rest. The type is what a facet checks, what the Studio offers in a picker, and what Figma turns into a Variable of the right kind. It is declared with a slash path and referenced with a dotted one.

foundations {
  layer Base {
    token space/sm : spacing = 8px
    token space/lg : spacing = 16px
  }
}

component Demo {
  part Demo: container {
    inset space.sm space.lg
  }
}

The React target writes

One custom property per token in theme.css, --ds-<type>-<id>, and var(…) wherever a facet points at it.

Read more

/language/tokens

Two kinds of length, both portable. px is not a CSS pixel: it is the density-independent unit Android calls dp, and every target converts it. scaled(1.25) is a length relative to the reader’s text size, which is what rem is for on the web and sp on Android.

token space/md : spacing = 12px
token size/text-md : font-size = scaled(1)

Read more

/language/values

A colour literal names its space, so a wide-gamut colour survives a round trip and a target that cannot show it knows what it is approximating. hex(7c3aed) has no #, because the literal is a function like the others.

token violet/600 : color = hex(7c3aed)
token violet/glow : color = oklch(0.62 0.19 300)
token scrim : color = srgb(0 0 0 0.4)

Read more

/language/values

A derived value is a token computed from another by steps, and it follows its base when the base changes. Colour steps happen in a named space; length steps scale, offset and round.

token accent : color = hex(7c3aed)
token accent-hover : color = compute accent in oklch { darken 10% }
token space/md : spacing = 12px
token space/lg : spacing = compute space.md { scale 1.5 }

Read more

/language/values

There is no currentColor keyword because there is a rule instead: a border with no colour of its own follows the ink, everywhere. inherit is the absence of a facet - a part that states no ink takes whatever its target’s inheritance gives it, which on the web is the parent’s colour.

The React target writes

currentColor for the border; the property left unset for the absent facet.

Read more

/language/styling

There is no cascade to win. Each part states its facets; a state or when block changes them under its condition; nothing from outside the component reaches in. Consumers restyle through tokens and through the seams the component declares, never by out-specifying its rules.

Read more

/thinking

The facets that animate between states, timed by duration and easing tokens. Motion adds no state; the behaviour states are its anchors.

foundations {
  token fast : duration = 120ms
  token standard : easing = raw "cubic-bezier(0.2, 0, 0, 1)"
}

component Demo {
  part Demo: container {
    motion {
      transition fill ink duration fast easing standard
    }
  }
}

The React target writes

transition on the facets’ properties.

Read more

/language/styling

Keyframe animation and transforms are realization work each platform does very differently, and the language has no words for them yet. A spinner or a slide-in is the archetype’s realization (a progress archetype spins; a dialog’s presentation animates) rather than a thing the file draws.

Read more

/language/styling

Hiding a part is a structural fact - it is not there - and the file says that with a presence condition on the part. A hidden part is not rendered at all, on every target, which visibility: hidden never meant.

part Demo.icon: icon {
  present when icon
}

Read more

/language/parts

A pointer cursor is what the web shows over a pressable thing; the archetype knows the part is pressable and the web realization sets the cursor. The same for selectability and hit testing: they follow from the behaviour the part composes, not from a property.

Read more

/language/behaviors

No vocabulary covers everything. When the model cannot say what you need, the answer is a seam declared in the document: a slot where consumers put their own content, a per-target option at release time, or, as a last resort, foreign content that carries one target’s code in quarantine, tagged so every other reader skips it honestly. Editing the generated CSS is never the answer: the next release overwrites it.

Read more

/thinking