@fusion.dev/helix-docs 0.228.0 → 0.229.0

package/content/shape-and-borders.mdx

@@ -38,7 +38,7 @@ This makes every card, dialog, input, and button squarer at once, because `sm`,
 See [Deriving a theme](./theming).
 
 Setting `--helix-radii-md` changes only what uses `md`. Buttons, inputs, and
-dialogs use `sm`, and cards use `lg`, so none of them change. Each step is
+dialogs use `sm`, and cards use `md`, so none of them change. Each step is
 computed from the seed on its own, so overriding one step changes only that
 step. To change the rounding everywhere, set the seed.
 
@@ -55,9 +55,8 @@ step. To change the rounding everywhere, set the seed.
 They all have the same corner, whatever their size. You compare a radius with
 the corners next to it, so the size of the panel does not matter.
 
-Circles do not use these tokens. An avatar, a loader, and a radio are circles by
-design, so they set `50%` directly. A theme that squares off everything else
-does not change them.
+An avatar and a radio are circles by design, so they read `--helix-radii-full`.
+A theme that squares off everything else does not change them.
 
 ## Border widths
 

package/content/size-and-density.mdx

@@ -26,8 +26,7 @@ Size does three jobs:
 - Emphasis shows which control matters most. The `emphasis` axis sets it. A
   filled primary button marks the important action much more clearly than eight
   more pixels of height.
-- Fit depends on the region. A toolbar is tight, a hero is spacious, and a table
-  row is tighter still. The region sets the fit for every control in it.
+- Fit depends on the region. A toolbar is tight and a hero is spacious. The region sets the fit for every control in it.
 - Optical role applies only to things that are not controls. An avatar at 24 in
   a list and at 96 on a profile are two different pictures. That is why
   `Avatar`, `Loader`, and `Orb` keep a `size`.

package/content/space-and-size.mdx

@@ -25,6 +25,7 @@ up one step of padding taller than the input beside it.
 | `--helix-space-xl` | `calc(2rem * var(--helix-seed-density, 1))` |
 | `--helix-space-2xl` | `calc(3rem * var(--helix-seed-density, 1))` |
 | `--helix-space-3xl` | `calc(4rem * var(--helix-seed-density, 1))` |
+| `--helix-space-field` | `var(--helix-space-sm)` |
 | `--helix-space-control` | `var(--helix-space-md)` |
 
 [//]: # (/tokens)
@@ -34,7 +35,7 @@ arithmetic, such as `space-4` being twice `space-2`. That stops being true as
 soon as the scale is tuned, and it leads to a `space-4.5` the first time
 something does not fit.
 
-`--helix-space-control` is a tenth token of a different kind. It is the inset a
+`--helix-space-control` and `--helix-space-field` are two more of a different kind. It is the inset a
 control uses, and it follows the region's density. It is not a step on the
 scale. See [Size and density](./size-and-density).
 
@@ -50,7 +51,7 @@ Use the space tokens for gap, padding, and margin:
 
 ## Size
 
-The size scale has forty-one tokens, and almost all of them name a specific
+Almost all of the size tokens name a specific
 thing:
 
 - `--helix-size-control`

package/content/surfaces-and-separation.mdx

@@ -6,11 +6,11 @@ title: Surfaces and separation
 
 # Surfaces and separation
 
-**Separate each surface from what is behind it with exactly one of four
-things.** The four are a fill, an edge, a lift, and space. A design language
-leads with one of them. Helix uses an edge for surfaces on the page and a lift
-for surfaces above it. A card has a hairline border and no shadow. A menu has a
-shadow and no hairline border. The surface ladder below sets the ground color
+**Separate each surface from what is behind it with four things: a fill, an
+edge, a lift, and space.** A design language leads with one of them. Helix leads
+with an edge for surfaces on the page and a lift for surfaces above it. A card
+has a hairline border and no shadow. A menu has a shadow and a hairline border,
+because a shadow cannot show on a near-black page. The surface ladder below sets the ground color
 for each place a surface can sit.
 
 ## The four ways to separate a surface
@@ -59,16 +59,16 @@ A surface's ground color token names where the surface sits:
 | --- | --- | --- |
 | `--helix-color-background` | <span data-token-swatch style={{ background: 'var(--helix-color-background)' }} /> | The page background. Every other surface sits on it. |
 | `--helix-color-surface` | <span data-token-swatch style={{ background: 'var(--helix-color-surface)' }} /> | A surface on the page, such as a card or a panel. The separation policy sets it apart with a fill, a border, or a shadow. |
-| `--helix-color-surface-raised` | <span data-token-swatch style={{ background: 'var(--helix-color-surface-raised)' }} /> | A raised surface on the page, such as a selected tab or a hovered row. Its fill is one step down the ramp. |
+| `--helix-color-surface-raised` | <span data-token-swatch style={{ background: 'var(--helix-color-surface-raised)' }} /> | A panel raised inside a surface, such as a card inside a card. Its fill is one step down the ramp. |
 | `--helix-color-surface-overlay` | <span data-token-swatch style={{ background: 'var(--helix-color-surface-overlay)' }} /> | A surface over the page, such as a menu, a popover, or a dialog. Its edge and its shadow set it apart. |
-| `--helix-color-surface-sunken` | <span data-token-swatch style={{ background: 'var(--helix-color-surface-sunken)' }} /> | A recessed surface that holds a value, such as an input, a track, or a groove. Its fill sets it apart. |
+| `--helix-color-surface-sunken` | <span data-token-swatch style={{ background: 'var(--helix-color-surface-sunken)' }} /> | A recessed surface, such as a track or a groove. Its fill sets it apart. A field reads `well`. |
 
 [//]: # (/tokens)
 
-**`raised` goes one step down the ramp.** A selected tab's pill, a hovered row,
-and an option under the pointer all have the page on every side. Only their
-fill separates them, and on a white page a fill has to be a step darker to be
-seen. `overlay` works the other way. Its edge and its shadow separate it, so on
+**`raised` goes one step down the ramp.** A panel inside a surface has a surface
+on every side. Only its fill separates it, and on a white page a fill has to be a
+step darker to be seen. A lit row is different: it takes `hover`, a wash measured
+against whatever it sits on. `overlay` works the other way. Its edge and its shadow separate it, so on
 a white page it is white.
 
 ## Using the page color inside a component

package/content/theming.mdx

@@ -60,7 +60,9 @@ Tuned does not guarantee contrast. CSS has no contrast function.
 `oklch(from …)` can step and rotate a color, but it cannot search for the
 lightness that meets a target. The contrast figures built into the ramp were
 measured on one blue seed, so they are exact for that seed and approximate for
-any other.
+any other. The label on a solid button turns black on a seed lighter than L 0.68.
+The focus ring still follows the seed, so use the verified engine for a very
+light brand, where the ring measures 1.23:1 on white.
 
 **Verified** uses the theme engine. It searches for each color that meets its
 target, measures every pair, and returns the theme with any violations:

package/content/visual-axes.mdx

@@ -114,8 +114,9 @@ reached the same rule in their own declarations, so the rule is stated here.
 
 **A family that reports a status accepts only the status values.** `Callout` and
 `Toast` both state this. A callout reports a status and never a brand role, so
-it accepts four of the seven tones. There is no neutral status. Accepting a
-value the family cannot draw is worse than leaving the value out.
+it accepts five of the seven tones, the four statuses and `neutral`, which is a
+note that reports no status. Accepting a value the family cannot draw is worse
+than leaving the value out.
 
 **A family whose resting state has no tone does not need `neutral`.** `Text`
 gives this reason for having no `default` value. A value that matches no rule
@@ -159,13 +160,13 @@ and this section explains why.
 | Value | What it draws |
 |---|---|
 | `elevated` | A surface lifted off the page, with a shadow under it |
-| `filled` | A ground of its own, and no edge |
-| `outlined` | An edge over the ground it already has |
-| `plain` | Neither, so the box ends where its content does |
+| `filled` | A ground of its own, and no edge. What the ground is belongs to the family |
+| `outlined` | An edge and no fill. A family whose text or thumb needs its ground to read, such as Log or Toggle Group, does not offer it. On Card, this differs from unset, which has a fill and an edge |
+| `plain` | No frame of its own. A family keeps what its content needs to stay readable, and its reference says what stays |
 
 **Most families leave out `elevated` because of what the value means.** A shadow
 shows that the box floats above the page. That is true of a card picked up off a
-grid and of an announcement laid over the content. It is false of:
+grid and of a node on a board. It is false of:
 
 - a row in a feed
 - a groove a thumb sits in
@@ -173,7 +174,7 @@ grid and of an announcement laid over the content. It is false of:
 - a bar across a video
 
 A family that accepts only the other three values needs no reason for it. A
-family that accepts `elevated` has made a choice, and `Card` and `Announcement`
+family that accepts `elevated` has made a choice, and `Card` and `Canvas Node`
 both accept it.
 
 ## What each nesting value does
@@ -203,7 +204,7 @@ value changes meaning partway along.
 | Value | What it draws |
 |---|---|
 | `solid` | The tone as a full ground, with the ink flipped to read on it |
-| `subtle` | A wash of the tone and no edge, the quietest thing that still has a surface |
+| `subtle` | A wash of the tone and no edge, the quietest thing that still has a surface. A chart mark keeps its edge |
 | `outlined` | An edge in the tone |
 | `ghost` | Nothing at rest, the tone carried by the ink alone |
 | `muted` | Quieter ink, where there is no surface to quiet |
@@ -214,8 +215,9 @@ fill stays under the edge, because the area shows a value and removing the fill
 would hide that value. In both cases, `outlined` sets how much ink the element
 uses, based on what the element needs the ink for.
 
-**`muted` is for something whose only ink is its letterforms.** Only text takes
-it, because everything else has a surface to make quieter first. Leaving it off
+**`muted` is for something whose only ink is its letterforms.** Text takes it,
+because everything else has a surface to make quieter first. Spatial Bar Chart
+also takes it, to draw neutral bars with one lit in its tone. Leaving it off
 other families is intentional.
 
 ## What each material draws
@@ -229,7 +231,7 @@ smeared, and a filter behind an opaque ground cannot be seen. With no
 | Value | What it draws |
 |---|---|
 | `glass` | A translucent ground and the backdrop filter that makes it read |
-| `frosted` | The same pair turned up, a heavier ground under a heavier blur |
+| `frosted` | The same pair turned up, a heavier ground under a heavier blur. A Dialog or Drawer's `glass` is already as heavy in light, so there the two differ by blur alone |
 | `transparent` | Neither, so the page shows through structure and spacing |
 
 Use `frosted` for a surface that has to stay readable over a busy page. A theme
@@ -260,15 +262,17 @@ the width the splitter actually has.
 
 ## What each size draws
 
-`size` applies to pictures and regions, and never to controls. That rule sets
-the scope of the axis. One of the four values is a different kind of step.
+`size` applies to pictures and regions, and never to one control. Toolbar and
+Button Group take it because they are regions: it sets every control inside
+them at once, as `data-density` does for a block. That rule sets the scope of
+the axis. One of the four values is a different kind of step.
 
 | Value | What it draws |
 |---|---|
 | `sm` | The small step |
-| `md` | The middle step, and the resting state for a family that has one |
+| `md` | The middle step, and the resting state for most families. Toolbar rests at `sm`, being dense by nature |
 | `lg` | The large step |
-| `full` | The whole region, less the same inset every other step already leaves |
+| `full` | The whole width of the region, less the same inset every other step already leaves |
 
 **`full` is one more step on the `size` axis.** A takeover dialog is the same
 setting taken further, so it belongs on this axis. A separate `fullscreen`
@@ -291,7 +295,7 @@ The table at the top describes `tone` in words and names four of its values.
 | `danger` | Destructive, or already wrong |
 
 The first three are intents, and the last four are statuses. A family that
-accepts a subset is choosing between these two groups. The section on `neutral`
+accepts a subset usually chooses between these two groups. The section on `neutral`
 above says when to accept it.
 
 ## What each width value does
@@ -302,7 +306,7 @@ component, separate from `size`.
 
 | Value | What it draws |
 |---|---|
-| `auto` | As wide as its content. This is the resting behavior, written out |
+| `auto` | As wide as its content. This is the resting behavior on most families, written out. On Description List, which fills the row at rest, it is the departure |
 | `full` | All the inline space its parent gives it |
 
 **A `width` that takes a number is a different property with the same name.** A