@fusion.dev/helix-docs 0.59.1 → 0.59.3

package/content/metrics.mdx

@@ -395,11 +395,11 @@ column is what was removed rather than part of what remains.
 | Package | Unpacked | Files | Source maps stripped | Runtime dependencies |
 |---|---|---|---|---|
 | `@fusion.dev/helix-core` | 983,274 | 153 | 222,331 | `@floating-ui/dom`, `@fusion.dev/helix-icons` |
-| `@fusion.dev/helix-headless` | 11,342,927 | 464 | 836,712 | `@fusion.dev/helix-core`, `@fusion.dev/helix-icons`, `uqr` |
+| `@fusion.dev/helix-headless` | 11,353,229 | 464 | 836,734 | `@fusion.dev/helix-core`, `@fusion.dev/helix-icons`, `uqr` |
 | `@fusion.dev/helix-icons` | 65,943 | 11 | 20,928 | none |
 | `@fusion.dev/helix-styles` | 101,139 | 6 | 0 | none |
 | `@fusion.dev/helix-theme` | 465,413 | 8 | 4,703 | none |
-| `@fusion.dev/helix` | 12,458,091 | 796 | 333,797 | `@fusion.dev/helix-core`, `@fusion.dev/helix-headless`, `@fusion.dev/helix-styles` |
+| `@fusion.dev/helix` | 12,470,065 | 796 | 333,806 | `@fusion.dev/helix-core`, `@fusion.dev/helix-headless`, `@fusion.dev/helix-styles` |
 
 ## Not measured yet
 

package/content/visual-axes.mdx

@@ -87,6 +87,29 @@ write it with nothing painted.
 and never of controls, which take their height from the region they sit in
 through `data-density`, so it lives only where something is painted.
 
+## When a family takes `neutral`
+
+`tone` is the one axis whose vocabulary the table above leaves open, and
+`neutral` is the value families have kept deciding about one at a time. Three
+have argued it at their own declarations and arrived at the same rule, so it
+belongs here once instead.
+
+**A family that reports a status takes the status words and stops.** `Callout`
+and `Toast` say it in nearly the same sentence: a callout reports a status and
+never a brand role, so it takes four of the seven. There is no neutral status,
+and a value that could not be drawn is worse than a value that cannot be named.
+
+**A family whose resting state is already untoned does not need it.** `Text`
+gives that reason against its own missing `default`: a value matching no rule
+would fall through to the inherited ink and read as working while saying
+nothing. The absent attribute is the resting case and says it better.
+
+**`neutral` is for a thing that carries a tone without reporting one**: a gray
+tag beside six colored ones, a button that is a button rather than the primary
+action. `Announcement` spells its own out rather than leaving the attribute off,
+which is what makes the tone sayable rather than only reachable, and that is the
+whole of when this value is worth taking.
+
 ## What each shape is
 
 `shape` is the axis whose values are geometries that look alike in a table and
@@ -107,6 +130,27 @@ not on a page, so it is worth saying what each one draws.
 `square` too, in the same registered axis. Membership is what a check can see,
 so nothing could have caught that, and a table is what stops it happening again.
 
+## What each separation draws
+
+`separation` says where a box ends, and `elevated` is the value nearly every
+family leaves out, so it is worth saying what each one draws and what that
+omission is about.
+
+| 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 |
+
+**Leaving `elevated` out is a fact about the value rather than about the family
+that skips it.** A shadow says the box floats above the page, which is true of a
+card picked up off a grid and of an announcement laid over the content, and
+false of a row in a feed, a groove a thumb sits in, a checkbox, or a bar across
+a video. A family taking the other three and stopping is following the value,
+not departing from the axis, and owes no argument for it. A family that *does*
+take it is the one saying something, and `Card` and `Announcement` both do.
+
 ## What a step inward means
 
 `nesting` is the one axis whose values are three readings of the same fact, so
@@ -123,3 +167,112 @@ depth and quiets the child; `heading` keys on holding children and relabels the
 parent, which is why a branch at any depth is a heading while the step below
 stops after one, and why a top-level leaf sitting beside a branch is left alone
 by both for opposite reasons.
+
+## What each emphasis claims
+
+`emphasis` is how loud a control is, and its values are one ladder with a rung
+that changes meaning halfway along, so it is worth saying what each draws.
+
+| 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 |
+| `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 |
+
+**`outlined` is the rung that changes.** On a control the edge arrives and the
+fill leaves, which is what makes it quieter than `solid`. On a chart mark the
+fill stays under the edge, because there the area encodes a value and dropping
+it would drop the reading. Both are the same question, how much ink this claims,
+answered by what the thing has to spend it on.
+
+**`muted` is for a thing whose only ink is its letterform.** Text carries it and
+nothing else does, because everything else has a surface to quiet first. That is
+a fact about the value, not a gap.
+
+## What each material is made of
+
+`material` is one pair of declarations at three strengths, and the pair is the
+point: a translucent ground without a backdrop filter is a smear, and a filter
+behind an opaque ground is invisible. Absent is opaque.
+
+| 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 |
+| `transparent` | Neither, so the page shows through structure and spacing |
+
+`frosted` is for a surface that has to stay readable over a busy page. It is not
+"more glass than `glass`" in a theme's sense: a theme owns how strong the pair
+is, and these three are which pair.
+
+## What each orientation turns
+
+`orientation` is not paint, which is why it is a value a component reads rather
+than a rule a stylesheet applies: the drag axis, the arrow keys and
+`aria-orientation` all turn with it, and a CSS-only version would look stacked
+while behaving side by side, with the keyboard moving the wrong way.
+
+| Value | What it does |
+|---|---|
+| `horizontal` | Lays along the inline axis and says so in `aria-orientation` |
+| `vertical` | Along the block axis, and says that |
+| `auto` | Lets the component decide from the room it has, and turn again when that changes |
+
+**`auto` asks the component's own width and never the viewport.** A splitter in a
+300px panel of a 1400px window has no room for two panes side by side, and a
+media query would hand it the desktop branch, so a `ResizeObserver` on the host
+asks the only question with an honest answer.
+
+## What each size step is
+
+`size` is asked of pictures and regions and never of controls, which is the
+domain and not a list of who carries it. The table is worth having because one
+of the four is not a rung of the same kind.
+
+| Value | What it draws |
+|---|---|
+| `sm` | The small rung |
+| `md` | The middle one, and the resting case where a family has one |
+| `lg` | The large one |
+| `full` | The region less the same inset every rung already stops short by |
+
+**`full` is one more rung and not a second property.** A takeover dialog is the
+same question answered further along, so it belongs on this axis rather than in
+a `fullscreen` boolean beside it, which would be a private spelling of a
+registry question.
+
+## What each tone means
+
+`tone` is the one axis whose cell in the table above is prose rather than a
+list, because a page naming four of the seven reads better than a page reciting
+all of them. The seven are still fixed, and this is where they are said.
+
+| Value | What it means |
+|---|---|
+| `primary` | The main action, or the brand speaking in its own voice |
+| `accent` | The second brand voice, for a thing that must not read as primary |
+| `neutral` | A tone that reports no status |
+| `info` | Worth knowing, with nothing to do about it |
+| `success` | Finished, or correct |
+| `warning` | May go wrong, or needs attention before it does |
+| `danger` | Destructive, or already wrong |
+
+The first three are intent and the last four are status, which is the split a
+family is really choosing between when it takes a subset. See above for when
+`neutral` is worth taking.
+
+## What each width policy is
+
+`width` here is a policy, not a measurement: two buttons sitting together may
+legitimately differ, which is the test that keeps this off `size`.
+
+| Value | What it draws |
+|---|---|
+| `auto` | As wide as its content, the resting behavior said out loud |
+| `full` | The whole of the inline space its parent offers |
+
+**A `width` taking a number is a different property wearing the same name.** A
+canvas and a table column are measured rather than given a policy, so they take
+a length and are not on this axis. The name is shared and the question is not.

package/dist/sources.generated.js

@@ -2359,11 +2359,11 @@ column is what was removed rather than part of what remains.
 | Package | Unpacked | Files | Source maps stripped | Runtime dependencies |
 |---|---|---|---|---|
 | \`@fusion.dev/helix-core\` | 983,274 | 153 | 222,331 | \`@floating-ui/dom\`, \`@fusion.dev/helix-icons\` |
-| \`@fusion.dev/helix-headless\` | 11,342,927 | 464 | 836,712 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-icons\`, \`uqr\` |
+| \`@fusion.dev/helix-headless\` | 11,353,229 | 464 | 836,734 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-icons\`, \`uqr\` |
 | \`@fusion.dev/helix-icons\` | 65,943 | 11 | 20,928 | none |
 | \`@fusion.dev/helix-styles\` | 101,139 | 6 | 0 | none |
 | \`@fusion.dev/helix-theme\` | 465,413 | 8 | 4,703 | none |
-| \`@fusion.dev/helix\` | 12,458,091 | 796 | 333,797 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-headless\`, \`@fusion.dev/helix-styles\` |
+| \`@fusion.dev/helix\` | 12,470,065 | 796 | 333,806 | \`@fusion.dev/helix-core\`, \`@fusion.dev/helix-headless\`, \`@fusion.dev/helix-styles\` |
 
 ## Not measured yet
 
@@ -5156,6 +5156,29 @@ write it with nothing painted.
 and never of controls, which take their height from the region they sit in
 through \`data-density\`, so it lives only where something is painted.
 
+## When a family takes \`neutral\`
+
+\`tone\` is the one axis whose vocabulary the table above leaves open, and
+\`neutral\` is the value families have kept deciding about one at a time. Three
+have argued it at their own declarations and arrived at the same rule, so it
+belongs here once instead.
+
+**A family that reports a status takes the status words and stops.** \`Callout\`
+and \`Toast\` say it in nearly the same sentence: a callout reports a status and
+never a brand role, so it takes four of the seven. There is no neutral status,
+and a value that could not be drawn is worse than a value that cannot be named.
+
+**A family whose resting state is already untoned does not need it.** \`Text\`
+gives that reason against its own missing \`default\`: a value matching no rule
+would fall through to the inherited ink and read as working while saying
+nothing. The absent attribute is the resting case and says it better.
+
+**\`neutral\` is for a thing that carries a tone without reporting one**: a gray
+tag beside six colored ones, a button that is a button rather than the primary
+action. \`Announcement\` spells its own out rather than leaving the attribute off,
+which is what makes the tone sayable rather than only reachable, and that is the
+whole of when this value is worth taking.
+
 ## What each shape is
 
 \`shape\` is the axis whose values are geometries that look alike in a table and
@@ -5176,6 +5199,27 @@ not on a page, so it is worth saying what each one draws.
 \`square\` too, in the same registered axis. Membership is what a check can see,
 so nothing could have caught that, and a table is what stops it happening again.
 
+## What each separation draws
+
+\`separation\` says where a box ends, and \`elevated\` is the value nearly every
+family leaves out, so it is worth saying what each one draws and what that
+omission is about.
+
+| 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 |
+
+**Leaving \`elevated\` out is a fact about the value rather than about the family
+that skips it.** A shadow says the box floats above the page, which is true of a
+card picked up off a grid and of an announcement laid over the content, and
+false of a row in a feed, a groove a thumb sits in, a checkbox, or a bar across
+a video. A family taking the other three and stopping is following the value,
+not departing from the axis, and owes no argument for it. A family that *does*
+take it is the one saying something, and \`Card\` and \`Announcement\` both do.
+
 ## What a step inward means
 
 \`nesting\` is the one axis whose values are three readings of the same fact, so
@@ -5192,6 +5236,115 @@ depth and quiets the child; \`heading\` keys on holding children and relabels th
 parent, which is why a branch at any depth is a heading while the step below
 stops after one, and why a top-level leaf sitting beside a branch is left alone
 by both for opposite reasons.
+
+## What each emphasis claims
+
+\`emphasis\` is how loud a control is, and its values are one ladder with a rung
+that changes meaning halfway along, so it is worth saying what each draws.
+
+| 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 |
+| \`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 |
+
+**\`outlined\` is the rung that changes.** On a control the edge arrives and the
+fill leaves, which is what makes it quieter than \`solid\`. On a chart mark the
+fill stays under the edge, because there the area encodes a value and dropping
+it would drop the reading. Both are the same question, how much ink this claims,
+answered by what the thing has to spend it on.
+
+**\`muted\` is for a thing whose only ink is its letterform.** Text carries it and
+nothing else does, because everything else has a surface to quiet first. That is
+a fact about the value, not a gap.
+
+## What each material is made of
+
+\`material\` is one pair of declarations at three strengths, and the pair is the
+point: a translucent ground without a backdrop filter is a smear, and a filter
+behind an opaque ground is invisible. Absent is opaque.
+
+| 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 |
+| \`transparent\` | Neither, so the page shows through structure and spacing |
+
+\`frosted\` is for a surface that has to stay readable over a busy page. It is not
+"more glass than \`glass\`" in a theme's sense: a theme owns how strong the pair
+is, and these three are which pair.
+
+## What each orientation turns
+
+\`orientation\` is not paint, which is why it is a value a component reads rather
+than a rule a stylesheet applies: the drag axis, the arrow keys and
+\`aria-orientation\` all turn with it, and a CSS-only version would look stacked
+while behaving side by side, with the keyboard moving the wrong way.
+
+| Value | What it does |
+|---|---|
+| \`horizontal\` | Lays along the inline axis and says so in \`aria-orientation\` |
+| \`vertical\` | Along the block axis, and says that |
+| \`auto\` | Lets the component decide from the room it has, and turn again when that changes |
+
+**\`auto\` asks the component's own width and never the viewport.** A splitter in a
+300px panel of a 1400px window has no room for two panes side by side, and a
+media query would hand it the desktop branch, so a \`ResizeObserver\` on the host
+asks the only question with an honest answer.
+
+## What each size step is
+
+\`size\` is asked of pictures and regions and never of controls, which is the
+domain and not a list of who carries it. The table is worth having because one
+of the four is not a rung of the same kind.
+
+| Value | What it draws |
+|---|---|
+| \`sm\` | The small rung |
+| \`md\` | The middle one, and the resting case where a family has one |
+| \`lg\` | The large one |
+| \`full\` | The region less the same inset every rung already stops short by |
+
+**\`full\` is one more rung and not a second property.** A takeover dialog is the
+same question answered further along, so it belongs on this axis rather than in
+a \`fullscreen\` boolean beside it, which would be a private spelling of a
+registry question.
+
+## What each tone means
+
+\`tone\` is the one axis whose cell in the table above is prose rather than a
+list, because a page naming four of the seven reads better than a page reciting
+all of them. The seven are still fixed, and this is where they are said.
+
+| Value | What it means |
+|---|---|
+| \`primary\` | The main action, or the brand speaking in its own voice |
+| \`accent\` | The second brand voice, for a thing that must not read as primary |
+| \`neutral\` | A tone that reports no status |
+| \`info\` | Worth knowing, with nothing to do about it |
+| \`success\` | Finished, or correct |
+| \`warning\` | May go wrong, or needs attention before it does |
+| \`danger\` | Destructive, or already wrong |
+
+The first three are intent and the last four are status, which is the split a
+family is really choosing between when it takes a subset. See above for when
+\`neutral\` is worth taking.
+
+## What each width policy is
+
+\`width\` here is a policy, not a measurement: two buttons sitting together may
+legitimately differ, which is the test that keeps this off \`size\`.
+
+| Value | What it draws |
+|---|---|
+| \`auto\` | As wide as its content, the resting behavior said out loud |
+| \`full\` | The whole of the inline space its parent offers |
+
+**A \`width\` taking a number is a different property wearing the same name.** A
+canvas and a table column are measured rather than given a policy, so they take
+a length and are not on this axis. The name is shared and the question is not.
 `,
     vue: `---
 description: The one compiler setting Vue needs, and why props and events already work.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@fusion.dev/helix-docs",
   "description": "Versioned documentation content and registry for Helix.",
-  "version": "0.59.1",
+  "version": "0.59.3",
   "license": "MIT",
   "author": "Ross Sheppard <ross.sheppard@fusion.dev>",
   "repository": {
@@ -36,8 +36,8 @@
   },
   "bugs": "https://github.com/project-fusion/fusion/issues",
   "devDependencies": {
-    "@fusion.dev/helix-cem": "0.59.1",
-    "@fusion.dev/helix-testing": "0.59.1",
+    "@fusion.dev/helix-cem": "0.59.3",
+    "@fusion.dev/helix-testing": "0.59.3",
     "@fusion.dev/scripts": "0.0.0-dev",
     "lit": "^3.2.1",
     "playwright": "^1.62.1"