@fusion.dev/helix-docs 0.206.0 → 0.207.1

package/content/diagnostics.mdx

@@ -0,0 +1,255 @@
+---
+description: Find the Helix mistakes the browser accepts without an error, on your running pages and in your code, with a setup for Vite, React, Next.js, and CI.
+section: Tooling
+title: Diagnostics
+---
+
+# Diagnostics
+
+Helix diagnostics finds the mistakes in your markup and styles that the browser
+accepts without an error. A `::part()` that names a part nothing publishes
+matches nothing, an attribute value outside the set a component takes falls
+back to the default, and `disabled="false"` turns `disabled` on. Each one is
+valid HTML or CSS, so nothing else reports it.
+
+Two tools check your project, in two places:
+
+- **`initDiagnostics()`**, from `@fusion.dev/helix-diagnostics`, checks each
+  page as it runs in development. It prints each finding in DevTools, and a
+  badge in the corner of the page lists them.
+- **`helix scan`**, from `@fusion.dev/helix-cli`, reads every stylesheet,
+  template, and module in your project, and prints each finding with its file
+  and line.
+
+Both judge your code against the lint data of the Helix version you installed.
+A fault that both find has the same kind and the same fingerprint in each, so a
+report can join a page's findings to the scan's.
+
+## Start diagnostics in your app
+
+```sh
+npm install --save-dev @fusion.dev/helix-diagnostics
+```
+
+Call `initDiagnostics()` once, before your app mounts. Put the call in a module
+of its own, so a production build can leave it out:
+
+```ts
+// src/diagnostics.ts
+import { initDiagnostics } from '@fusion.dev/helix-diagnostics'
+import lint from '@fusion.dev/helix/lint.json'
+
+initDiagnostics({ environment: 'development', tiers: [{ lint }] })
+```
+
+`tiers` passes the lint data from your own `node_modules`, so diagnostics loads
+nothing from the network. Without it, diagnostics loads the lint data for the
+version on the page from a public npm CDN.
+
+An add-on package publishes the lint data for its own elements, and you pass it
+in `tiers` the same way. `@fusion.dev/helix-sandbox` publishes it for
+`helix-sandbox-editor`:
+
+```ts
+import lint from '@fusion.dev/helix/lint.json'
+import sandbox from '@fusion.dev/helix-sandbox/lint.json'
+
+initDiagnostics({ environment: 'development', tiers: [{ lint }, { lint: sandbox }] })
+```
+
+The CDN serves the two tiers' lint data alone, so an add-on's elements are
+checked only where its lint data is in `tiers`. Without it, each of them is an
+unknown tag.
+
+Load the module in development only. In Vite, with React or any other
+framework, import it from your entry:
+
+```tsx
+// src/main.tsx
+if (import.meta.env.DEV) {
+  void import('./diagnostics.js')
+}
+```
+
+`vite build` replaces `import.meta.env.DEV` with `false` and drops the import
+with it. In Next.js, import it from `instrumentation-client.ts`, which runs in
+the browser before your app hydrates:
+
+```ts
+// instrumentation-client.ts
+if (process.env.NODE_ENV === 'development') {
+  void import('./app/diagnostics')
+}
+```
+
+Every Helix template starts diagnostics this way. Angular, Svelte, Vue, Solid,
+and a page with no bundler call it the same way, and the package's README says
+where each one's entry is.
+
+From then on, diagnostics runs after the page loads, after a navigation, and
+after the page changes. It prints each finding once per page, and the badge
+shows only while the page has findings. Hover over a finding in the badge's
+list to outline the element it is about.
+
+## Print the findings in your terminal
+
+A page cannot write to your terminal, so the Helix command line receives each
+run beside your dev server. Install it, and turn the relay on where you call
+`initDiagnostics()`:
+
+```sh
+npm install --save-dev @fusion.dev/helix-cli
+```
+
+```ts
+initDiagnostics({
+  environment: 'development',
+  sinks: { relay: true },
+  tiers: [{ lint }],
+})
+```
+
+Then run the relay in your project's directory, beside the dev server:
+
+```sh
+npx helix diagnostics
+```
+
+Each Helix template has the script for it, so `npm run diagnostics` starts it
+there. The command prints each finding the first time a page has it. It listens
+on `127.0.0.1:7417`, takes runs only from pages on a local host, and serves the
+`helix-diagnostics.json` in the directory it runs in to the page.
+
+## Scan your code
+
+```sh
+npx helix scan
+```
+
+`helix scan` judges your code against the lint data of every Helix package you
+install that publishes `lint.json`, the two tiers and an add-on such as
+`@fusion.dev/helix-sandbox`. It reads every file `.gitignore` leaves in, apart
+from tests and the folders a build writes. It reads CSS, Sass, and Less; HTML, Vue, Svelte,
+and Astro templates; MDX; and JSX, Lit's `html` and `css` templates, and
+Angular's inline templates in JavaScript and TypeScript. Each finding has its
+file and line:
+
+```
+helix scan: 1 error, 0 warnings, 0 info, and 0 unsettled, in 42 files
+  error nested-interactive <helix-button> <helix-icon-button>
+    `helix-icon-button` is inside `helix-button`, which draws its content inside a native button. …
+    in src/toolbar.tsx:12
+```
+
+- **It reads every route.** A page sees only the routes someone opened.
+- **What only a page can settle is listed as `unsettled`**, such as a hook set
+  on a tag that does not have it, which works where an element inside the tag
+  has it. An unsettled finding never fails the scan.
+- **It checks an attribute where your code writes it as one.**
+  `disabled="false"` is checked. `?disabled=${false}` in Lit, `:disabled="false"`
+  in Vue, and `disabled={false}` in JSX set the value at run time, and the page
+  judges what they write.
+- **`--file <path>` reports one file's findings**, and still reads the whole
+  project, so an import in another file counts. `--stdin <language>` checks a
+  snippet.
+
+It exits 1 on a finding at `error`, and 3 where it cannot run, such as where no
+installed Helix package has lint data.
+
+## Run the checks in CI
+
+`--out` writes a run to a CI file, and each command keeps the runs the others
+wrote there, so one file holds your code's run and your pages' runs:
+
+```sh
+npx helix scan --out reports/helix-diagnostics.json
+npx helix diagnostics --once http://localhost:4173/ --out reports/helix-diagnostics.json
+```
+
+`helix diagnostics --once <url>` opens a page headless, runs diagnostics on it
+once the page holds still, prints each finding, and exits. Repeat `--once` for
+each page. It needs Playwright installed beside `@fusion.dev/helix-cli`, and
+adds nothing to your app.
+
+Where your own end-to-end tests open the pages, gather their runs with
+`@fusion.dev/helix-diagnostics/ci`:
+
+```ts
+import { ciSink } from '@fusion.dev/helix-diagnostics/ci'
+
+// `runs` are the reports diagnostics returned in each page your job opened.
+const { code, summary } = ciSink(runs, { file: 'reports/helix-diagnostics.json' })
+console.log(summary)
+process.exitCode = code
+```
+
+A fault found on many pages is one line, with the pages it was on. A finding at
+`error` fails the job. `failOn: 'warn'` fails it on warnings too, and
+`failOn: 'never'` reports without failing. `ciSink` writes the whole file, so
+run `helix scan --out` after it to add your code's run.
+
+## What it finds
+
+| Kind | Severity | Found by | Means |
+| --- | --- | --- | --- |
+| `dead-hook` | error | both | A hook is set where nothing answers it, or a name close to a hook is set that nothing reads |
+| `dead-part` | error | both | A `::part()` names a part the element does not publish, or follows another `::part()` |
+| `disabled-attribute` | error | scan | A rule styles a form control's `[disabled]`, which a control a `<fieldset disabled>` disables does not carry. Write `:disabled` |
+| `duplicate-registration` | error | page | Two copies of Helix are on the page |
+| `false-boolean` | error | both | A boolean attribute is written `="false"`, which turns it on, as `disabled="false"` does. An attribute that `"false"` turns off, such as Drawer's `modal`, is not one |
+| `invalid-value` | error | both | An attribute with a closed set of values carries one outside it, so the element falls back to its default |
+| `manifest-skew` | error | page | The lint data is from another version than the page runs, so no other finding is reported |
+| `native-element` | warn | scan | A native element is written where an installed Helix family stands in for it, such as `<button>` for `helix-button` |
+| `nested-interactive` | error | both | An interactive element is inside a button or a link, which HTML forbids, such as `helix-icon-button` inside `helix-button` or `helix-button` inside an `<a>` |
+| `primitive-token` | error | scan | A rule reads a `--_helix-` primitive, which is internal to `@fusion.dev/helix-styles` |
+| `unforwarded-part` | warn | both | The headless tag publishes a part the styled tag does not forward, which is a gap in Helix |
+| `unimported-tag` | warn | scan | An element is written, and nothing in the project imports the entry that registers it |
+| `unknown-attribute` | error | both | A Helix element carries an attribute it does not take |
+| `unknown-event` | error | scan | A React `on` prop names an event the element does not dispatch |
+| `unknown-slot` | error | scan | A child names a slot its Helix element does not have, so it is not drawn |
+| `unknown-tag` | error | both | A rule or an element names a tag no installed package lists |
+| `unknown-token` | error | scan | A rule reads or sets a `--helix-` name the token set does not have |
+| `unreflected-attribute` | warn | both | A rule selects a Helix element by an attribute it never writes back, so it matches only markup a server wrote |
+
+**A button inside a button is judged where the markup settles it.** Button,
+Icon Button, Copy Button, Toggle, Motion Toggle, Radio, and Tab draw their
+content inside a native button, and Skip Link draws its content inside a link.
+A slot for actions, such as a card's `footer-actions`, is not inside anything
+pressable. A framework's component, such as a router's `<Link>`, places its
+children itself, so `helix scan` stops at it, and the page sees the `<a>` it
+renders.
+
+## Configure the checks
+
+Both tools read `helix-diagnostics.json` from your project. The page cannot read
+files, so import it and pass it as `file`, or let the relay serve it:
+
+```json
+{
+  "rules": {
+    "native-element": "off",
+    "unknown-tag": { "severity": "off", "tags": ["helix-mine"] }
+  }
+}
+```
+
+A kind takes `error`, `warn`, `info`, or `off`, for every tag or for the tags
+you name. A setting that names nothing is refused, with the closest one that
+exists. Every setting is in the README of `@fusion.dev/helix-diagnostics`.
+
+## Scope
+
+The checks cover what the lint data can settle. They do not check:
+
+- the value a token or a hook is set to, such as `--helix-radii-md: red`.
+  `helix scan` checks each `--helix-` name you write;
+- a selector that descends into a component, such as `helix-card .title` or
+  `helix-button span`. It matches only the elements you put inside the
+  component;
+- a `::part()` on a selector with no Helix tag in it, such as
+  `.cta::part(label)`, since the class names no element whose parts can be
+  read;
+- an attribute value an expression sets, such as `tone={tone}` in JSX, in
+  `helix scan`. The page judges the attribute it writes;
+- the contrast of a color you write yourself. `helix theme audit` checks the
+  contrast of your theme's tokens.

package/content/graphs.mdx

@@ -452,6 +452,12 @@ helix-graph:state(ready) > div {
 }
 ```
 
+Use the fade where the layout settles in a moment, such as a graph whose notes
+all have places. Leave a cosmos.gl graph shown. Its layout runs for several
+seconds by design, and the view follows the notes as they spread, so the reader
+watches the graph settle. Faded in on the state, its drawing is hidden for that
+whole time.
+
 ## Draw the graph before it loads
 
 `graphSnapshot(nodes, links, options)` draws the graph on your server as an

package/content/iconography.mdx

@@ -167,21 +167,39 @@ bundler can remove that record.
 an order of precedence, the glyph on the page would come from whichever
 directory ranked higher, and nothing would look wrong.
 
-## Add a glyph to the Helix set
+## Draw your own glyphs by name
 
-Add the name to `helix/icons/icons.txt` and run `turbo run icons`. Phosphor
-names resolve from `@phosphor-icons/core` at build time, so adding a glyph takes
-one line. You do not copy a path into a TypeScript object by hand.
+`registerIcons` makes your glyphs resolve by `name`, so plain HTML can draw
+them:
 
-For a mark Phosphor does not draw, add an SVG with the same name to
-`helix/icons/raw`. The build reads it from there when Phosphor has no match.
-Draw it with the same geometry, a 256 box at the bold weight. A glyph drawn at a
-different weight stands out next to the others.
+```ts
+import { registerIcons } from '@fusion.dev/helix/icon'
+import { peak } from './icons'
+
+registerIcons([peak])
+```
+
+```html
+<helix-icon name="peak"></helix-icon>
+```
+
+Each glyph registers under its own `name`. To register a whole set, build it
+with `--index` and pass the `icons` record the command writes to
+`registerIcons`.
+
+`registerIconLibrary` resolves names under a prefix through a function of your
+own, such as one that points into a sprite sheet or fetches from a server. After
+`registerIconLibrary('brand', resolve)`, `name="brand:peak"` draws the glyph that
+`resolve('peak')` returns.
+
+To sit beside the Helix set, draw a glyph with the same geometry, a 256 box at
+the bold weight. A glyph drawn at a different weight stands out next to the
+others.
 
 ## Product marks
 
-Helix and Cortex have product marks. They are in the icon package, and they are
-not part of the icon set. A mark identifies a product. An icon stands for an
-action. **A mark is one rounded body with material removed.** It is never a
-pictogram of a metaphor, because it stands beside the parent brand's mark, a
-geometric monogram. Do not use the icon set to draw a logo.
+The set includes the Fusion, Helix, and Cortex marks, and the React and HTML5
+logos, so `<helix-icon name="helix">` draws the Helix mark. A mark identifies a
+product. An icon stands for an action. **The Helix and Cortex marks are each one
+rounded body with material removed.** Neither is a pictogram of a metaphor,
+because each stands beside the Fusion mark, a geometric monogram.

package/content/installation.mdx

@@ -16,6 +16,24 @@ use its semantic tokens and draw nothing without them. If the elements are
 installed and the tokens are missing, your page shows unstyled boxes. There is
 no fallback theme.
 
+## Start a new project
+
+If you do not have a project yet, the scaffolder writes one with Helix
+installed, the stylesheets imported, and every element registered:
+
+```sh
+npm create @fusion.dev/helix-app@latest my-app -- --template react-vite
+```
+
+Leave out `--template`, and the command lists the templates and writes nothing.
+Each template starts with the same three pages:
+
+- a landing page
+- a sorted, paged data table
+- a form that a `<form>` reads with `FormData`
+
+The rest of this page adds Helix to a project you already have.
+
 ## Import the stylesheets
 
 ```ts
@@ -49,18 +67,19 @@ import the two files you want and skip `helix.css`.
   `tokens.css` refers to the primitives throughout, so without
   `primitives.css` every semantic token resolves to nothing. We measured a page without it:
   `--helix-color-background` computes to `rgba(0, 0, 0, 0)`, and so does every
-  other color. [Theming](theming.mdx) also depends on this file, because without
+  other color. [Theming](./theming) also depends on this file, because without
   it, setting `--helix-seed-brand` changes nothing.
 - **`tokens.css`** declares the semantic layer, the custom properties grouped
   by category, plus `color-scheme: light dark` on `:root`. The files below read
   from it, and it reads from `primitives.css`.
 - **`base.css`** holds the element reset, the type scale on bare `h1` through
   `h6`, and the recipes for markup that Helix does not render. It reads tokens.
-- **`elements.css`** styles elements before they upgrade. It is the file most
-  often left out, because a page works without it until the page is
-  server-rendered. An element that has not upgraded has no shadow root and no
-  styles of its own, so the markup flashes unstyled and then jumps into place.
-  `elements.css` makes that interval look like the finished page.
+- **`elements.css`** hides each Helix element until its definition loads. It is
+  the file most often left out, because a page works without it until the page
+  is server-rendered. An element that has not upgraded has no shadow root and no
+  styles of its own, so without the file the markup flashes unstyled. With it,
+  the element stays hidden until it upgrades, and the layout settles when it
+  does.
 
 Import the files from a stylesheet you control, and keep them out of individual
 components. The order then stays visible in one place.
@@ -91,13 +110,14 @@ Render one element and check whether it upgraded:
 
 ```ts
 await customElements.whenDefined('helix-button')
-console.log(document.querySelector('helix-button')?.shadowRoot !== null)
+console.log(document.querySelector('helix-button')?.shadowRoot instanceof ShadowRoot)
 ```
 
 `true` means the definition loaded and the element built its shadow root.
-`false`, or a promise that never settles, means the registration import did not
-run. Usually the import is outside a `'use client'` boundary, or you imported
-the subpath of a component you did not end up using.
+`false` means the page has no `helix-button` to check. A promise that never
+settles means the registration import did not run. Usually the import is outside
+a `'use client'` boundary, or you imported the subpath of a component you did
+not end up using.
 
 If the element upgraded and the page still looks wrong, check the stylesheets
 in the order above. The symptom tells you which layer is missing:
@@ -107,6 +127,10 @@ in the order above. The symptom tells you which layer is missing:
 - Components that look right once JavaScript runs, but flash unstyled before
   it, mean `elements.css` is missing.
 
+To check the rest of your markup and styles against the Helix you installed,
+start [Diagnostics](./diagnostics) in development, and run `helix scan` on your
+code. Each template starts diagnostics for you.
+
 ## Framework setup
 
 The elements are custom elements, and every framework can render them.

package/content/intent-reference.mdx

@@ -31,7 +31,7 @@ empty intent, `{}`, is a valid theme.
 | `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 |
+| `status` | `info`, `success`, `warning`, and `danger`. A color pins one. `{ hue }` moves its hue within the band that keeps its meaning |
 | `chroma` | How saturated the palette is, independent of hue |
 | `scheme` | `'light'` or `'dark'`, for a theme that has only one mode |
 | `tokens` | Literal overrides by token name, for values no other field sets |
@@ -46,6 +46,17 @@ lightness moves only as far as the target needs.
 `danger` rotated with the brand, your users would have to learn a new warning
 color for each product.
 
+**A status hue stays in its band.** Each band, in OKLCH degrees, covers the
+colors that still read as that status. A hue outside its band is refused, and
+the error names the band.
+
+| Status | Hue band | Colors |
+|---|---|---|
+| `danger` | 15 to 40 | The reds, from crimson to red-orange |
+| `warning` | 45 to 105 | Orange and amber to yellow |
+| `success` | 125 to 180 | The greens, from yellow-green to teal-green |
+| `info` | 200 to 280 | Cyan and blue to indigo |
+
 `chroma` sets how saturated the theme feels. Monotone, muted, restrained, and
 vivid all describe chroma, and none of them describes a hue. `chroma` has two
 settings:
@@ -59,12 +70,20 @@ 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.
 
+`tokens` sets each value after the engine has solved the rest, so no other color
+is solved against it. Each pair that names the token measures it, and a value
+that misses its target is reported in `violations`. A name the engine does not
+emit is added as a token of your own. No default pair names it, so only a pair
+you list in `pairings` measures it. A value the engine cannot read is skipped: a
+token the engine emits keeps its derived value, and a name it does not emit is
+left out.
+
 ## Contrast
 
 | Field | What it controls |
 |---|---|
 | `contrastTarget` | Target contrast for body text. 4.5 is WCAG AA, and 7 is AAA |
-| `pairings` | Extra foreground and background pairs to solve, in addition to the pairs in the engine's surface model |
+| `pairings` | The foreground and background pairs to measure, by token name. A background of `color-well over color-surface` is a field's well over that surface. The list replaces the pairs from the engine's surface model. The engine measures each pair and solves none of them, and a pair that names a token the engine does not emit is reported as `unverifiable` |
 
 The default is 4.5, the WCAG 2.1 AA figure. The European Accessibility Act
 refers to WCAG 2.1 AA, so 4.5 is the figure with legal weight.
@@ -118,8 +137,13 @@ you the trade-off that a theme with heavy material makes.
 
 | Field | What it controls |
 |---|---|
-| `namespace` | The token prefix. Defaults to `helix` |
+| `namespace` | The token prefix. Defaults to `helix`. `acme` emits `--acme-color-primary` |
 
 Use `namespace` when your product ships its own token layer built on the
 engine. The rest of the library still reads `--helix-*`, so a new namespace
 changes only your own tokens.
+
+**A namespace is ASCII letters, digits, hyphens, and underscores, with no
+hyphen at either end.** The engine writes the hyphens around it. Any other
+namespace is refused with the value it received, such as an empty one, `--acme`,
+or `acme tokens`.

package/content/introduction.mdx

@@ -18,8 +18,9 @@ The components are custom elements, so you can use them in any framework or
 without one.
 
 **Helix computes your theme.** You enter a few inputs, such as your brand color,
-and Helix computes every token from them. Every text and background pair meets
-its contrast target. See [Theming](./theming).
+and Helix computes every token from them. Helix measures the contrast of each
+text and background pair it solves, and reports any pair that misses its target.
+See [Theming](./theming).
 
 **AI agents can read it.** A custom elements manifest describes every component,
 with typed options, documented parts, and generated React prop names, so an

package/content/localization.mdx

@@ -1,5 +1,5 @@
 ---
-description: Set the locale of date, time, and number controls, translate the built-in words, and lay out pages right to left.
+description: Set the locale of date, time, and number controls, translate the built-in words, lay out pages right to left, and color a rise and a fall for your market.
 section: Essentials
 title: Localization and RTL
 ---
@@ -163,7 +163,7 @@ Register the words for a language once, and every element in that language
 speaks them:
 
 ```js
-import { registerWords } from '@fusion.dev/helix'
+import { registerWords } from '@fusion.dev/helix/words'
 
 registerWords('pl', {
   'helix-combobox': {
@@ -179,8 +179,12 @@ registerWords('pl', {
 ```
 
 Each family's words are keyed by its tag, such as `helix-combobox`, and then
-by the property name. The headless and styled tiers share one key. To type the
-keys, import the generated types once:
+by the property name. The headless and styled tiers share one key.
+`@fusion.dev/helix/words` holds `registerWords` without the elements, so a page
+can register its words before it loads any, and it types each key and property.
+A page that uses only the headless tier imports
+`@fusion.dev/helix-headless/words`. With `registerWords` imported from another
+entry, import the types once:
 
 ```ts
 import type {} from '@fusion.dev/helix/words'
@@ -330,6 +334,81 @@ Aria's `@react-stately/color` translates, so you can reuse that table.
 Helix ships English words and no translations. Pass the words from your own
 translation system, either to `registerWords` or to the properties.
 
+## Rise and fall colors
+
+Markets draw a price movement in different colors:
+
+- Mainland China, Taiwan, and Japan draw a rise in red and a fall in green.
+- Hong Kong, like most other markets, draws a rise in green and a fall in red.
+
+Colors that show a status, such as an error or a warning, are the same in all
+of these markets. Only a color that shows which way a value moved changes.
+
+Two tokens hold these colors:
+
+| Token | Default |
+|---|---|
+| `--helix-color-rise` | `--helix-color-success`, which is green |
+| `--helix-color-fall` | `--helix-color-danger`, which is red |
+
+`Trend` uses them when you set `color-by="movement"`. Without it, the color of a
+trend follows `good`, which says whether the change is an improvement.
+
+For a page that shows one of the markets that draw a rise in red, swap the two
+tokens at the root of the page, and set `color-by` on each trend:
+
+```css
+:root,
+[data-helix-theme] {
+  --helix-color-fall: var(--helix-color-success);
+  --helix-color-rise: var(--helix-color-danger);
+}
+```
+
+```html
+<helix-trend
+  color-by="movement"
+  format-options='{"style":"percent","maximumFractionDigits":2}'
+  value="0.0124"
+>
+  <span slot="label">Shanghai Composite</span>
+</helix-trend>
+```
+
+An element with `data-helix-theme` declares every token again for the part of
+the page it themes, so the rule names `[data-helix-theme]` beside `:root`. To
+color one part of a page, such as a panel of Shanghai prices on a page about
+several markets, set the two tokens on that panel.
+
+The two tokens point at the status colors, so after the swap each one still
+measures at least 4.5:1 on the page and on every surface, in both modes. A
+theme that changes `success` and `danger` changes them too.
+
+**Helix does not set these from `lang`.** The language of a page does not name
+its market. A page in Chinese for Hong Kong draws a rise in green, a `zh-Hant`
+page with no region could be for Taiwan or for Hong Kong, and a page in English
+can show Shanghai prices. If the language of your page does decide its market,
+select on the language yourself:
+
+```css
+:is(:root, [data-helix-theme]):is(:lang(zh-CN), :lang(zh-TW), :lang(ja)) {
+  --helix-color-fall: var(--helix-color-success);
+  --helix-color-rise: var(--helix-color-danger);
+}
+```
+
+A page in `zh-HK` matches none of these, so it keeps green for a rise.
+
+Other components color a series by its place in the list, or by a tone you
+name. To draw one in the color of a rise or a fall, set its own color to the
+token, such as `--sparkline-color: var(--helix-color-rise)` on the sparkline of
+a price that went up.
+
+Sources:
+
+- [Benzinga, on the colors of stock prices in China, Japan, and Taiwan](https://www.benzinga.com/general/education/21/10/23258001/did-you-know-you-dont-want-to-be-in-the-green-if-youre-trading-in-china-japan-or-taiwan)
+- [Feng Jiang, Rui Zhang, and Su Lu, on red and green in the Chinese and Hong Kong markets](https://www.behavioraleconomics.com/when-red-means-go)
+
 ## What to check when you add a language
 
 - **Long strings.** Labels in German and Finnish are often long. A control sized
@@ -338,6 +417,9 @@ translation system, either to `registerWords` or to the properties.
   buttons may now fit four.
 - **The `lang` attribute.** Set it as well as translating the strings.
   Hyphenation, quotation marks, and font fallback all depend on it.
+- **A market's colors.** If the new language comes with a market that draws a
+  rise in red, swap the rise and fall tokens. See
+  [Rise and fall colors](#rise-and-fall-colors).
 - **Numerals.** `Intl` formats the digits. A `%` or a currency symbol hardcoded
   in your own markup does not move to the correct side.
 - **Icons that point.** A caret that a component draws turns by itself. An icon