@fusion.dev/helix-docs 0.140.0 → 0.142.0

package/content/color.mdx

@@ -39,14 +39,18 @@ separation](./surfaces-and-separation).
 Inks are the colors that go on grounds. The base ink is `foreground`.
 
 - `foreground-muted` and `foreground-subtle` are for text that recedes.
-- `foreground-on-accent` is for text on a filled accent color.
+- Text on a filled color takes the ink named for that fill:
+  - `foreground-on-primary` on `primary-surface`
+  - `foreground-on-accent` on `accent-surface`
+  - `foreground-on-status` on the four status fills
 
 ### Intent
 
 Intent colors show what something means.
 
 - `primary` and `accent` are for emphasis. Each has `-hover`, `-active`, and
-  `-subtle` variants.
+  `-subtle` variants. With no brand color set, both are ink: near-black in
+  light mode and near-white in dark mode.
 - `info`, `success`, `warning`, and `danger` are for status. Each has a
   `-surface` and a `-surface-hover` variant for the tinted box that holds the
   message.
@@ -75,9 +79,10 @@ OKLCH lets the theme engine *solve* for a palette from your brand color. See
 
 ## How the engine meets contrast targets
 
-The engine measures each ink against the ground it will be painted on. It then
-searches for the lightness that meets the target. Every pair it produces meets
-the target.
+The engine measures each ink against the ground it will be painted on. A brand
+color that already meets the target there is used as it is. For any other color,
+the engine searches for the lightness that meets the target. Every pair it
+produces meets the target.
 
 The engine can solve only the pairs it knows about, so we check two things:
 

package/content/intent-reference.mdx

@@ -18,16 +18,17 @@ const theme = engine.derive({ brand: '#2563eb' })
 
 [Deriving a theme](./theming) shows how Node loads the engine.
 
-**`brand` is the only required input.** Every other field has a default,
-computed from `brand` or from the Helix design language. A theme that sets only
-`brand` is a valid theme.
+**Every input is optional.** With no `brand`, the theme is ink: the primary
+color is near-black in light mode and near-white in dark mode. Every other field
+has a default, computed from `brand` or from the Helix design language, so an
+empty intent, `{}`, is a valid theme.
 
 ## Color
 
 | Field | What it controls |
 |---|---|
-| `brand` | Your main brand color. Required |
-| `accent` | The second emphasis color. Defaults to the brand color. `{ from: 'brand', rotate: 180 }` gives the complementary color |
+| `brand` | Your main brand color, or `{ light, dark }` for a different one in each mode. Without one, the theme is ink, and so is a mode the pair leaves out |
+| `accent` | The second emphasis color. Defaults to the brand color, or to ink with no brand. `{ from: 'brand', rotate: 180 }` gives the complementary color, and needs a brand |
 | `background` | The page's color, `{ light, dark }`, for a page that is not pure white or pure black. The surfaces keep their contrast with it, and the grays take its tint. A page no text color can reach the contrast target on is refused |
 | `neutral` | The gray ramp, which can be tinted toward the brand. With `background`, it takes the page's tint |
 | `status` | `info`, `success`, `warning`, and `danger`. A color pins one. An object adjusts its hue while it keeps its meaning |
@@ -35,6 +36,12 @@ computed from `brand` or from the Helix design language. A theme that sets only
 | `scheme` | `'light'` or `'dark'`, for a theme that has only one mode |
 | `tokens` | Literal overrides by token name, for values no other field sets |
 
+**A brand color that already meets the contrast target is used as it is.**
+Where it clears every surface it lands on, it is the primary color, and where
+its label clears on it, it is the fill. A navy brand stays navy on a light page.
+A color that does not meet the target keeps its hue and chroma, and its
+lightness moves only as far as the target needs.
+
 `accent` can be defined relative to the brand. `status` colors cannot. If
 `danger` rotated with the brand, your users would have to learn a new warning
 color for each product.
@@ -47,7 +54,9 @@ settings:
 - `scale` multiplies the chroma the brand color supplies.
 
 Both apply to every derived color, including the brand color, because in a
-monotone theme the brand is gray too. Neither applies to a color you pinned. A
+monotone theme the brand is gray too. A gray brand is solved like any other, to
+the gray nearest the page that meets the contrast target, which is a mid gray.
+For black and white, leave out `brand`. Neither applies to a color you pinned. A
 pinned color is used exactly as you set it.
 
 ## Contrast

package/content/maps.mdx

@@ -91,15 +91,15 @@ fixes a sanitizing flaw in earlier versions, so use 6.4.1 or later.
 - Land uses `surface`.
 - Water uses `info`.
 - Parks use `success`.
-- Main roads use `primary`, your brand color.
+- Main roads use `primary`, your brand color, or ink with no brand.
 - Smaller roads, buildings, borders, and labels use `foreground`.
 
 It also draws landmarks, highway signs, and neighborhood names:
 
 - A landmark is an icon on a disc and its name, in a color for its kind:
   parks, museums, schools, hotels, hospitals, stations, and stadiums from zoom
-  14, and food and shops from zoom 16. Each color is a fixed hue at your brand
-  color's lightness, so the kinds stay apart in any theme.
+  14, and food and shops from zoom 16. Each color is a fixed hue at the
+  lightness of `primary`, so the kinds stay apart in any theme.
 - A highway's number is on its sign, drawn to the Federal Highway
   Administration's outlines: the red and blue Interstate shield, the white US
   route shield, the white circle of a state route, and a plain plate for other