@fusion.dev/helix-docs 0.139.0 → 0.141.0

package/content/theme-builder.mdx

@@ -30,6 +30,11 @@ drawn with the theme, and the stylesheet the theme generates beside it.
 The Color scheme field picks which half you see: light, dark, or the site's own
 mode. See [Color modes](./color-modes).
 
+The builder starts from ink, the palette Helix draws with no brand color:
+near-black in light mode and near-white in dark. Turn on **Brand color** to
+derive the palette from a color of your own. The accent angle is measured from
+the brand, so it applies only with one.
+
 ## A page of your own color
 
 The Light page and Dark page fields give the page a color, such as a warm cream

package/content/theming.mdx

@@ -8,6 +8,22 @@ title: Deriving a theme
 
 Helix computes your color tokens from a few inputs, such as your brand color.
 
+## Without a brand color
+
+With no brand color set, Helix draws in ink. The primary color is near-black in
+light mode and near-white in dark mode, and a filled button is the opposite of
+the page, with the page's own color for its label. The neutral ramp supplies
+both, so a gray with a tint gives a tinted ink. Set a brand color to replace the
+ink, as a seed in CSS or as `brand` in the theme engine.
+
+Before ink, the default was a blue. To keep it, set it as your seed:
+
+```css
+:root {
+  --helix-seed-brand: oklch(0.539 0.19 258);
+}
+```
+
 When a design system ships two hundred fixed color values, you theme it by
 changing them one at a time. A change to one value can break the contrast of a
 component elsewhere, and nothing tells you.
@@ -38,8 +54,9 @@ resolved at the root. The stylesheet declares the ramp again on each
 
 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 are
-exact for the default seed and approximate for any other.
+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.
 
 **Verified** uses the theme engine. It searches for each color that meets its
 target, measures every pair, and returns the theme with any violations:
@@ -110,6 +127,16 @@ console.log(css[':root'])
 A value that is not a color and still changes with the mode, such as the edge
 of a floating surface, is set by rules after the block, one for each mode.
 
+The CLI writes the same block. `helix theme init` writes a `helix.theme.json`,
+with your brand color if you pass `--brand`. `helix theme build` derives it in
+both modes, unless the file names a `scheme`, and refuses to write a theme with
+a pair that misses its target:
+
+```sh
+helix theme init --brand '#0b3d91'
+helix theme build --out theme.css
+```
+
 ## Color one section
 
 A section in a color of its own, such as a deep teal band on a cream page, is a
@@ -149,8 +176,10 @@ Equal numeric steps in sRGB do not look like equal steps. That makes scales and
 contrast math in sRGB unreliable. Helix computes themes in OKLCH for this
 reason. Colors are written in OKLCH and converted to other formats on output.
 
-The engine keeps your brand color's hue and chroma and changes only its
-lightness to meet the target. Your brand color stays recognizable, and its
+The engine keeps your brand color's hue and chroma. Where the color already
+meets the contrast target, the engine uses it as it is: a navy brand stays navy
+on a light page. Where it does not, the engine changes only its lightness, by as
+little as the target needs. Your brand color stays recognizable, and its
 contrast is guaranteed.
 
 ## Errors the engine prevents