@jasonsdevspace/design-kit 0.1.0-next.3 → 0.1.0-next.4

package/CHANGELOG.md

@@ -7,6 +7,44 @@ keeping a copy. Each version from `0.1.0-next.1` on is staged on npm from a tag
 workflow, with provenance, goes live when it is promoted, and has a release on GitHub with the
 entry below as its notes.
 
+## 0.1.0-next.4
+
+The strip's first link says whose work it leads to, and the footer's sentence holds to the measure.
+Every optional prop takes `undefined`, the callout takes the props of a `<div>` and is padded as
+steps and code blocks are, and every empty slot is read alike. The sheets show a pointer on what
+takes a click, mark an invalid field in forced colors and keep a token's name whole in a table.
+
+- **Page chrome.** The strip's first link reads "More work by Jason Poteet", where it read "A demo
+  by Jason Poteet", which fits a demo and the kit's own site alike and says where the link goes. A
+  page that writes the strip by hand changes the link's words itself. The footer's sentence holds
+  to the measure, while its rule still runs the page's width.
+- **Types.** Every optional prop of every component takes `undefined`, as if it were left out, so a
+  wrapper that passes on a prop it may not have been given compiles under
+  `exactOptionalPropertyTypes`. Only the types widen, so nothing that compiled before breaks.
+- **Callouts.** `Callout` takes the props of a `<div>` but `style`, `role`, the `title` attribute,
+  inner HTML and the live attributes, among them an `id`, a page's class after the kit's, and a
+  `ref` that holds the callout drawn, so a page can link to an error summary, focus it after a form
+  fails, or lay it out. Its props are exported as `CalloutProps`. Its message takes its role from
+  `live` alone. A tone or a heading level the types refuse, as plain JavaScript can pass, draws news
+  and a paragraph. A callout is padded 0.75rem by 1rem, from 0.5rem by 0.75rem, as steps and code
+  blocks are.
+- **Empty slots.** Every slot a component leaves out when it is empty reads an empty string, or a
+  list or a fragment that holds only false, null or empty strings, as nothing. The strip's switches
+  and the footer's additions now read an empty string so too. A field's hint and error and a
+  callout's title, message and actions now read such a list or fragment as nothing, where before
+  they drew an empty paragraph, which a hint or an error also listed in `aria-describedby`.
+- **Pointers.** `base.css` shows a pointer on a disclosure's summary and on a checkbox or a radio
+  with the label that holds it, and the arrow on one that is unavailable. The label's pointer reads
+  `:has()`, so in Firefox 120 only the box or the dot shows it.
+- **Fields.** In forced colors, where an invalid control's red edge is gone, it gains a dashed line
+  around its edge in the system's text color, `CanvasText`, which moves nothing as the error comes
+  and goes. With focus, the ring takes its place.
+- **Tables.** Code in a table cell within its frame stays on one line, so a token's name never
+  breaks after `--dk-`, and a long expression scrolls the frame as a wide table does.
+- **Docs.** The README shows the strip's switch as a kit button and an unavailable button with the
+  text that says why, says why a field uses `disabled` where a button stays in the tab order, and
+  says the strip's and the footer's link props take only URLs the demo's author writes.
+
 ## 0.1.0-next.3
 
 The page chrome holds still and shows where a reader is, the controls a page moves focus to take a

package/README.md

@@ -1,15 +1,11 @@
 # @jasonsdevspace/design-kit
 
-Design tokens, base styles, a theme script, the page chrome, buttons, fields and callouts, and the
-explainer page, for the demos on [jasonsdevspace.com](https://jasonsdevspace.com). Every rule sits
-in a cascade layer of the kit's own, so a page's own rule outside a layer wins over every rule of
-the kit's but the cut to motion, without any extra weight. A page with layers of its own has to
-name where the kit's go among them, in the order the section on layers below gives. The script
-sets the theme a visitor chose on the portfolio before the page paints. The components are the
-page chrome a demo draws around its page, a skip link, a strip and a footer, and the buttons,
-text fields, selects and callouts on the page itself, as markup a sheet styles and as React
-components that draw it. The explainer that says how a demo works, with its steps, panels, tables
-and code blocks, is markup a page writes by hand, with no component.
+Design tokens, base styles, a theme script, page chrome, buttons, fields and callouts, and an
+explainer layout, for the demos on [jasonsdevspace.com](https://jasonsdevspace.com). The styles are
+plain CSS in cascade layers, so a page's own rules outside a layer win without extra weight. The
+theme script sets the theme a visitor chose on the portfolio before the page paints. The chrome and
+the controls come as markup a sheet styles and as React components that draw it. The explainer is
+markup a page writes by hand.
 
 ```sh
 npm install @jasonsdevspace/design-kit
@@ -21,6 +17,10 @@ components. Prereleases are under npm's `next` tag, as `@jasonsdevspace/design-k
 changed in each version is in
 [CHANGELOG.md](https://github.com/jasonsdevspace/design-kit/blob/main/packages/design-kit/CHANGELOG.md).
 
+A page with cascade layers of its own must name where the kit's layers go, as [Layers and
+palettes](#layers-and-palettes) describes. The cut to motion for a visitor who asks for less holds
+over a page's ordinary styles, as that section explains.
+
 A page loads the sheets, tokens first, through a bundler that resolves package exports, such as
 Vite.
 
@@ -52,15 +52,16 @@ export default defineConfig({ plugins: [themeScriptPlugin()] });
   `--dk-surface`, `--dk-raised`, `--dk-fg`, `--dk-muted`, `--dk-line`, `--dk-control`,
   `--dk-accent`, `--dk-on-accent`, `--dk-highlight`, `--dk-success`, `--dk-success-bg`,
   `--dk-danger`, `--dk-danger-bg` and the scrim, `--dk-scrim`. Beside them are steps of space, text
-  size and corners, a code size in em that follows the text around it, two line heights, three
-  weights, a sans and a mono font stack, the focus ring's width and offset, a field's height and
-  inline padding, the size of a touch target, the height of the portfolio's strip, the measure
-  and column widths, a shadow and a short duration.
+  size and corners, a code size in em that follows the text around it, line heights, weights, a sans
+  and a mono font stack, the focus ring's width and offset, a field's height and inline padding, the
+  size of a touch target, the height of the portfolio's strip, the measure and column widths, a
+  shadow and a short duration.
 - `@jasonsdevspace/design-kit/base.css` gives the page its type and colors, one focus ring in the
-  accent for every link and control the keyboard reaches, code in running text a step under the
-  text around it, the `.dk-visually-hidden` class for a label a screen reader reads and the eye
-  does not, and less motion for a visitor who asks for it. It loads after the tokens, since the
-  tokens' first statement declares the kit's layer order.
+  accent for every link and control the keyboard reaches, code in running text a step under the text
+  around it, the `.dk-visually-hidden` class for a label a screen reader reads and the eye does not,
+  a pointer on a disclosure's summary and on a box or a dot with the label that holds it, and less
+  motion for a visitor who asks for it. It loads after the tokens, since the tokens' first statement
+  declares the kit's layer order.
 - `@jasonsdevspace/design-kit/components.css` styles the page chrome, the skip link, the strip and
   the footer, the buttons, fields and callouts, and the explainer page with its steps, panels,
   tables and code blocks, by the classes in the markup the sections below give. It loads after
@@ -71,10 +72,11 @@ export default defineConfig({ plugins: [themeScriptPlugin()] });
 - `@jasonsdevspace/design-kit/react` exports `SkipLink`, `PortfolioStrip` and `DemoFooter`, which
   draw the chrome's markup, and `Button`, `InputField`, `SelectField` and `Callout`, which draw the
   markup of the buttons, fields and callouts, with the types `ButtonProps`, `InputFieldProps`,
-  `SelectFieldProps` and `CalloutTone`. It also exports `PORTFOLIO_URL`, `PORTFOLIO_WORK_URL` and
-  `GITHUB_PROFILE_URL`, the portfolio, its list of work and the GitHub profile the chrome links to.
-  It has no component for the explainer or the pieces in it, which a page writes by hand. It takes
-  React `^19.3.0` as an optional peer, which a page that writes the markup itself never needs.
+  `SelectFieldProps`, `CalloutProps` and `CalloutTone`. It also exports `PORTFOLIO_URL`,
+  `PORTFOLIO_WORK_URL` and `GITHUB_PROFILE_URL`, the portfolio, its list of work and the GitHub
+  profile the chrome links to. It has no component for the explainer or the pieces in it, which a
+  page writes by hand. It takes React `^19.3.0` as an optional peer, which a page that writes the
+  markup itself never needs.
 - `@jasonsdevspace/design-kit/vite` exports `themeScriptPlugin()`, the Vite plugin that puts the
   script inline in place of `THEME_PLACEHOLDER`, the comment `<!-- theme-script -->`, and
   `themeScriptHash`, the script's hash as a Content Security Policy source. It runs in Node, and
@@ -102,31 +104,36 @@ The skip link is the keyboard's first stop, out of sight until it takes focus, a
 column's inset, where the strip's links start. Following it moves focus to the page's main content,
 which has a tabindex of -1 so it can take focus.
 
+<!-- example: skipLink -->
+
 ```html
 <a class="dk-skip" href="#main-content">Skip to content</a>
 <main id="main-content" tabindex="-1">...</main>
 ```
 
-A skip link may also sit inside a box of the page's own, such as one at the top of a column of
+A skip link can also sit inside a box of the page's own, such as one at the top of a column of
 filters that leads past them to the results. It waits in its own place as the visually hidden class
 does, one pixel clipped to nothing, so it draws nothing and takes no click wherever the box starts
 on the page. A box that is positioned holds it, and it shows at the top of that box, inset as it is
 at the top of a page, when a keyboard reaches it.
 
-The strip holds a navigation landmark named Portfolio, with three links in this order: whose demo
-it is, how it works and the source. The strip on the demo's explainer marks the explainer's link
-with `aria-current="page"`. A demo with switches of its own puts them in a section after the links,
-named for them, and a demo with none leaves the section out.
+The strip holds a navigation landmark named Portfolio, with links in this order: the author's other
+work, which names who made the demo, how it works and the source. It reads "More work by Jason
+Poteet", which fits a demo and the kit's own site alike. The strip on the demo's explainer marks the
+explainer's link with `aria-current="page"`. A demo with switches of its own puts them in a section
+after the links, named for them, and a demo with none leaves the section out.
+
+<!-- example: strip -->
 
 ```html
 <div class="dk-strip">
     <nav class="dk-strip-links" aria-label="Portfolio">
-        <a href="https://jasonsdevspace.com/#work">A demo by Jason Poteet</a>
+        <a href="https://jasonsdevspace.com/#work">More work by Jason Poteet</a>
         <a href="./about/">How it works</a>
         <a href="https://github.com/jasonsdevspace/example">Source on GitHub</a>
     </nav>
     <section class="dk-strip-tools" aria-label="Demo">
-        <button type="button">Tour</button>
+        <button type="button" class="dk-button">Tour</button>
     </section>
 </div>
 ```
@@ -136,6 +143,8 @@ room so nothing below the strip moves when they come. The section is drawn with
 only the room, with no text, so it is no landmark and a screen reader finds nothing in it. When the
 switches come they take the room's place in the same section, and the section takes its name.
 
+<!-- example: stripWaiting -->
+
 ```html
 <section class="dk-strip-tools"><span class="dk-strip-room"></span></section>
 ```
@@ -152,11 +161,14 @@ of their own below them.
 The footer is one paragraph that says whose project the demo is, with the author's name linking the
 portfolio, and links how it works, the source, the rest of the work and the license. The footer on
 the demo's explainer marks the link to how it works with `aria-current="page"`, as the strip does.
-Anything the demo adds follows the license, as sentences of its own. Every link in the chrome keeps
-its underline, and in the footer's sentence the underline is what tells a link from the text around
-it. The link marked as the current page, in the strip or the footer, stands in the page's text at
-the heading's weight, so it is told from the links around it by more than its color, in forced
-colors too, and still reads as a link.
+Anything the demo adds follows the license, as sentences of its own. The sentence holds to the
+measure, as prose does, while the footer's rule runs the page's width. Every link in the chrome
+keeps its underline, and in the footer's sentence the underline is what tells a link from the text
+around it. The link marked as the current page, in the strip or the footer, stands in the page's
+text at the heading's weight, so it is told from the links around it by more than its color, in
+forced colors too, and still reads as a link.
+
+<!-- example: footer -->
 
 ```html
 <footer class="dk-footer">
@@ -177,18 +189,14 @@ is another width sets `--dk-column` to it, as it sets a color role.
 A page with React draws the same markup from the components.
 
 ```tsx
-import { DemoFooter, PortfolioStrip, SkipLink } from '@jasonsdevspace/design-kit/react';
+import { Button, DemoFooter, PortfolioStrip, SkipLink } from '@jasonsdevspace/design-kit/react';
 
 const source = 'https://github.com/jasonsdevspace/example';
 
 export const Page = () => (
     <>
         <SkipLink />
-        <PortfolioStrip
-            about="./about/"
-            source={source}
-            tools={<button type="button">Tour</button>}
-        />
+        <PortfolioStrip about="./about/" source={source} tools={<Button>Tour</Button>} />
         <main id="main-content" tabIndex={-1}>
             <h1>Example</h1>
         </main>
@@ -199,18 +207,23 @@ export const Page = () => (
 
 - `SkipLink` leads to `main-content` unless `target` names another id, and its children replace
   the words "Skip to content".
-- `PortfolioStrip` takes `about`, the demo's explainer, and `source`, its repository. `current`
-  set to `about` marks the explainer's link as the current page. `tools` holds the demo's own
-  switches, and `toolsLabel` names their landmark, `Demo` unless given. With `tools` undefined,
-  null or false the strip draws no section for them, so a demo can pass `hasTour && <Tour />`.
-  `toolsWaiting` keeps the room of one row of the kit's controls while `tools` draws nothing, for a
-  page drawn before the switches can be, in the same section unnamed until they come.
+- `PortfolioStrip` takes `about`, the demo's explainer, and `source`, its repository. `current` set
+  to `about` marks the explainer's link as the current page. `tools` holds the demo's own switches,
+  and `toolsLabel` names their landmark, `Demo` unless given. With `tools` undefined, null, false,
+  an empty string, or a list or a fragment of only those, the strip draws no section for them, so a
+  demo can pass `hasTour && <Tour />`. `toolsWaiting` keeps the room of one row of the kit's
+  controls while `tools` draws nothing, for a page drawn before the switches can be, in the same
+  section unnamed until they come.
 - `DemoFooter` takes `name`, the demo's name as the sentence opens with it, `about` and `source`.
   `current` set to `about` marks the explainer's link as the current page, as on the strip.
   `license` is the link to the license, `LICENSE` on the main branch of `source` unless given, with
-  any trailing slash on `source` dropped first. `licenseName` is the license's name in the
-  sentence, `MIT license` unless given. Its children follow the license, and children that are
-  undefined, null or false add nothing.
+  any trailing slash on `source` dropped first. `licenseName` is the license's name in the sentence,
+  `MIT license` unless given. Its children follow the license, and children that are undefined,
+  null, false, an empty string, or a list or a fragment of only those, add nothing.
+
+The strip's and the footer's `about`, `source` and `license` go into their links unchecked, so each
+is a URL the demo's author writes, never one taken from the page's address or a visitor's input,
+since one taken from either could send a visitor anywhere.
 
 ## Buttons, fields and callouts
 
@@ -225,11 +238,16 @@ wins over all of them.
 
 ### Buttons
 
+<!-- example: buttons -->
+
 ```html
 <button type="button" class="dk-button">Filters</button>
 <button type="button" class="dk-button dk-button-accent">Save rule</button>
 <button type="button" class="dk-button" aria-pressed="true">Members only</button>
-<button type="button" class="dk-button" aria-disabled="true">Previous</button>
+<button aria-describedby="previous-why" type="button" class="dk-button" aria-disabled="true">
+    Previous
+</button>
+<p id="previous-why" class="dk-field-hint">This is the first page.</p>
 ```
 
 A button is `type="button"` unless the page gives it another type, so it never submits a form by
@@ -239,15 +257,16 @@ toggle that stands alone carries `aria-pressed`, `"true"` or `"false"`, and keep
 both states, since the attribute already says which it is. An action carries no `aria-pressed` at
 all. A button with `aria-expanded="true"`, whose panel is open, is drawn as a pressed one.
 
-A button that is off carries `aria-disabled="true"` rather than `disabled`. A disabled button that
-has focus drops it, and leaves the tab order, while an aria-disabled one stays where the keyboard
-can reach it and find out why. The attribute does nothing by itself, so a page that writes this
-markup makes its own click handler check `aria-disabled` and return early, calling
+An unavailable button, `off` in React, carries `aria-disabled="true"` rather than `disabled`. A
+disabled button that has focus drops it, and leaves the tab order, while an aria-disabled one stays
+where the keyboard can reach it and find out why. The attribute does nothing by itself, so a page
+that writes this markup makes its own click handler check `aria-disabled` and return early, calling
 `preventDefault()` so a submit button does not submit. The sheet draws a `disabled` button, and one
-inside a disabled fieldset, the same as an off one, and an accent button that is off keeps its
-class and is drawn as any off button is. A page says why a button is off in text beside it. A
-form's submit button is better left on while the form is incomplete, so a press shows the errors
-rather than doing nothing.
+inside a disabled fieldset, the same as an off one, and an accent button that is off keeps its class
+and is drawn as any off button is. A page says why a button is off in text beside it, such as a
+`.dk-field-hint` paragraph the button's `aria-describedby` names, a class that works beside any
+control. A form's submit button is better left on while the form is incomplete, so a press shows the
+errors rather than doing nothing.
 
 A button is 2.25rem tall, `--dk-field-height`, as tall as a field, and 2.75rem, `--dk-target`, at
 48rem wide or less, and it is never narrower than it is tall. It has no ground of its own, so it
@@ -262,22 +281,24 @@ off toggle that is on an edge in `Highlight`.
 
 ### Fields
 
+<!-- example: fields -->
+
 ```html
 <div class="dk-field">
     <label class="dk-field-label" for="email">Email</label>
     <p class="dk-field-hint" id="email-hint">Where the receipt goes</p>
     <p class="dk-field-error" id="email-error">
-        <span class="dk-visually-hidden">Error: </span>Enter an email address
+        <span class="dk-visually-hidden">Error: </span>
+        Enter an email address
     </p>
     <input
         class="dk-input"
-        id="email"
         type="email"
+        id="email"
         aria-describedby="email-hint email-error"
         aria-invalid="true"
     />
 </div>
-
 <div class="dk-field">
     <label class="dk-field-label" for="sort">Sort by</label>
     <select class="dk-select" id="sort">
@@ -303,24 +324,31 @@ error, best after a submit is tried rather than while someone is typing.
 A control is as tall as a button, at both widths, and its text is never under 16px, so a phone does
 not zoom the page when the field is tapped. It sits on the page's own ground, so it reads as a well
 on a card. The hint and the error are in the caption size, the error in the danger color, and an
-invalid control's edge in the danger color too. A disabled control is drawn on the surface ground
-in the muted text. The select is a native `<select>`, its caret drawn as a background, and in forced
-colors the browser's own arrow comes back. A select that shows its options as a list, with
-`multiple` or a `size`, is left as the browser draws it, with no caret.
+invalid control's edge in the danger color too. In forced colors, where that color is gone, an
+invalid control gains a dashed line around its edge in `CanvasText`, which moves nothing as the
+error comes and goes, and gives way to the focus ring when it has focus. A disabled control is drawn
+on the surface ground in the muted text. The select is a native `<select>`, its caret drawn as a
+background, and in forced colors the browser's own arrow comes back. A select that shows its options
+as a list, with `multiple` or a `size`, is left as the browser draws it, with no caret. A field a
+visitor cannot change uses `disabled`, unlike a button, which stays in the tab order when it is off.
+The field's hint says why it cannot be changed, and a screen reader reads that hint wherever it
+announces the field. A button's reason sits beside it in text its `aria-describedby` names, read
+when the keyboard reaches the button.
 
 ### Callouts
 
+<!-- example: callout -->
+
 ```html
 <div class="dk-callout dk-callout-danger">
     <div class="dk-callout-body">
         <p class="dk-callout-title">
-            <span class="dk-visually-hidden">Error: </span>The products could not be loaded
+            <span class="dk-visually-hidden">Error: </span>
+            The products could not be loaded
         </p>
         <p>Check the file, then load it again.</p>
     </div>
-    <div class="dk-callout-actions">
-        <button type="button" class="dk-button">Try again</button>
-    </div>
+    <div class="dk-callout-actions"><button type="button" class="dk-button">Try again</button></div>
 </div>
 ```
 
@@ -382,6 +410,9 @@ export const Checkout = ({ error, saved }: Props) => {
 };
 ```
 
+Every optional prop of every component takes `undefined` as if it were left out, so a wrapper that
+passes on a prop it may not have been given compiles under `exactOptionalPropertyTypes` too.
+
 - `Button` takes the props of a `<button>` but `style`, `disabled`, `aria-disabled` and
   `aria-pressed`, and is `type="button"` unless `type` says otherwise. `accent` adds
   `dk-button-accent`. `pressed` writes `aria-pressed`, `false` included, and left undefined makes
@@ -392,11 +423,12 @@ export const Checkout = ({ error, saved }: Props) => {
   `className` follows the kit's classes. A `ref` holds the `<button>` drawn, for a page that moves
   focus to it, such as the button that opened a panel when the panel closes.
 - `InputField` takes `label`, and `hint` and `error`, each drawn only when given, an empty string,
-  null or false drawing nothing. `id` is the control's, made with React's `useId` unless given, and
-  a page gives one when something links to the field, such as an error summary. Every other prop
-  goes to the `<input>` but `style` and `aria-invalid`. A `className` follows `dk-input`, and an
-  `aria-describedby` of the page's own is listed after the hint and the error. A `ref` holds the
-  `<input>` drawn, for a page that moves focus to the field, such as a form that fails.
+  null, false, or a list or a fragment of only those drawing nothing. `id` is the control's, made
+  with React's `useId` unless given, and a page gives one when something links to the field, such as
+  an error summary. Every other prop goes to the `<input>` but `style` and `aria-invalid`. A
+  `className` follows `dk-input`, and an `aria-describedby` of the page's own is listed after the
+  hint and the error. A `ref` holds the `<input>` drawn, for a page that moves focus to the field,
+  such as a form that fails.
 - `SelectField` takes the same props, with its children as the options of the `<select>` and its
   `ref` holding the `<select>`.
 - `Callout` takes `tone`, `info` unless given, `success` or `danger`, and `title`, drawn at the
@@ -405,8 +437,11 @@ export const Checkout = ({ error, saved }: Props) => {
   before the title or the message, the tone's own unless given, and an empty string drops it.
   `live`, `status` or `alert`, puts that role on the message and draws the message even when it is
   empty, and a live callout whose message draws nothing, with no title or actions, draws nothing
-  until it is filled. A callout takes no other props, so a page that needs a class or an id on one
-  puts it on an element around it.
+  until it is filled. Every other prop goes to the callout's `<div>` but `style`, `role` and the
+  `title` attribute, inner HTML and the live attributes, since its message takes its role from
+  `live` alone, so a page gives it an `id`, such as one an error summary is linked by, and a
+  `className`, which follows the kit's. A `ref` holds the `<div>` drawn, for a page that moves focus
+  to it, as to a summary of what went wrong in a form that fails.
 
 ## Explainer pages
 
@@ -420,6 +455,8 @@ class would outweigh every piece set inside it.
 
 ### The page
 
+<!-- example: explainerPage -->
+
 ```html
 <a class="dk-skip" href="#main-content">Skip to content</a>
 <div class="dk-strip">
@@ -468,11 +505,13 @@ caption size, its heading in the title size, and its text, with an h3 at the bod
 
 ### Steps
 
+<!-- example: steps -->
+
 ```html
 <ol class="dk-steps" role="list">
     <li>
         <strong class="dk-steps-title">The order names a product.</strong>
-        <span class="dk-steps-note">And how many of it.</span>
+        <span class="dk-steps-note">It says how many it wants.</span>
     </li>
     <li>
         <span class="dk-steps-arrow" aria-hidden="true">↓</span>
@@ -492,10 +531,15 @@ drops a list's meaning when its markers are gone.
 
 ### Panels
 
+<!-- example: panel -->
+
 ```html
 <div class="dk-panel">
     <p class="dk-panel-title">How the numbers were taken</p>
-    <p>...</p>
+    <p>
+        Each strategy ran three times on the same laptop with the same orders, and the table shows
+        the middle run.
+    </p>
 </div>
 ```
 
@@ -514,6 +558,8 @@ complementary to it. Nor is it a named `section`, which would be a region landma
 
 ### Tables
 
+<!-- example: table -->
+
 ```html
 <p class="dk-table-title" id="bench-title">Orders a second under each strategy</p>
 <div class="dk-table-scroll" role="region" aria-labelledby="bench-title" tabindex="0">
@@ -552,13 +598,16 @@ WebKit. It scrolls in its frame instead.
 
 A table is in the small text, with each row ruled in the line color. Its column headers are the
 muted text at medium weight, and a row's header is at medium weight too. The outer cells keep no
-padding on their outer side, so the table's text lines up with the prose around it. Figures sit
-to the right and never wrap, while text in a cell wraps and keeps its first line level with the
-rest of its row. A header gives its unit in words a screen reader says well, "Slowest 1%, ms"
-rather than "p99 ms".
+padding on their outer side, so the table's text lines up with the prose around it. Figures sit to
+the right and never wrap, while text in a cell wraps and keeps its first line level with the rest of
+its row. Code in a cell stays on one line, hyphens and spaces alike, so a token's name never breaks
+after `--dk-`, and a long expression scrolls the frame as a wide table does. A header gives its unit
+in words a screen reader says well, "Slowest 1%, ms" rather than "p99 ms".
 
 ### Code blocks
 
+<!-- example: code -->
+
 ```html
 <p class="dk-code-title" id="lock-title">The statement that holds the stock</p>
 <pre
@@ -586,11 +635,11 @@ script, so a block has no copy button.
 ### Code in running text
 
 `base.css` sets code in running text on every page, not only an explainer, at `--dk-text-code`,
-0.9em, so it follows the size of the text around it, a step under it since a mono face looks
-larger at the same size. It breaks anywhere it must, with `overflow-wrap: anywhere`, since a long
-name has no spaces to break at and would push a narrow column wider. Inside a `pre` it takes the
-block's size and keeps its lines whole. It has no ground of its own, and in a link it keeps the
-link's underline.
+0.9em, so it follows the size of the text around it, a step under it since a mono face looks larger
+at the same size. It breaks anywhere it must, with `overflow-wrap: anywhere`, since a long name has
+no spaces to break at and would push a narrow column wider, except in a table cell, as Tables
+describes. Inside a `pre` it takes the block's size and keeps its lines whole. It has no ground of
+its own, and in a link it keeps the link's underline.
 
 ## Layers and palettes
 
@@ -655,7 +704,8 @@ from the package rather than keeping a copy.
 
 The colors are written with `light-dark()`, which sets the floor: Chrome and Edge 123, Firefox 120
 and Safari 17.5. An empty live callout draws nothing by `:has()`, which Firefox has from 121, so in
-Firefox 120 it draws its ground until it is filled. The kit's browser tests run in Chromium.
+Firefox 120 it draws its ground until it is filled, and a label that holds a checkbox or a radio
+shows no pointer there, though the box or the dot does. The kit's browser tests run in Chromium.
 
 ## License
 

package/dist/base.css

@@ -114,6 +114,28 @@
         accent-color: var(--dk-accent);
     }
 
+    /*
+     * What takes a click shows a pointer: a disclosure's summary, and a box or a dot with the label
+     * that holds it, which ticks it from anywhere on its words. One that is unavailable keeps the
+     * arrow. A label for a text field only moves focus to it, so it keeps the browser's own.
+     */
+    :where(
+        summary,
+        input[type='checkbox'],
+        input[type='radio'],
+        label:has(> input[type='checkbox'], > input[type='radio'])
+    ) {
+        cursor: pointer;
+    }
+
+    :where(
+        input[type='checkbox']:disabled,
+        input[type='radio']:disabled,
+        label:has(> input[type='checkbox']:disabled, > input[type='radio']:disabled)
+    ) {
+        cursor: default;
+    }
+
     /*
      * Out of sight but still read by a screen reader, as for a label the eye takes from what is
      * around it. It keeps one pixel, since a screen reader may skip an element with no size at all.

package/dist/components.css

@@ -100,7 +100,9 @@
         font-size: var(--dk-text-small);
     }
 
+    /* The footer sentence holds to the measure, as prose does, while its rule runs full width. */
     :where(.dk-footer p) {
+        max-width: var(--dk-measure);
         margin: 0;
     }
 
@@ -350,7 +352,7 @@
     :where(.dk-callout) {
         display: grid;
         gap: var(--dk-space-2);
-        padding: var(--dk-space-2) var(--dk-space-3);
+        padding: var(--dk-space-3) var(--dk-space-4);
         border: 1px solid transparent;
         border-radius: var(--dk-radius);
         background: var(--dk-highlight);
@@ -440,6 +442,22 @@
             padding-inline-end: var(--dk-field-inline);
             background-image: none;
         }
+
+        /*
+         * An invalid field loses its red edge to the system's colors, so it gains a dashed line
+         * around its edge in the text color, which keeps its contrast in every theme and moves
+         * nothing as the error comes and goes. With focus, the ring takes its place, so a
+         * keyboard sees where it landed.
+         */
+        :where(.dk-input[aria-invalid='true'], .dk-select[aria-invalid='true']) {
+            outline: var(--dk-ring-width) dashed CanvasText;
+            outline-offset: 1px;
+        }
+
+        :where(.dk-input[aria-invalid='true'], .dk-select[aria-invalid='true']):focus-visible {
+            outline: var(--dk-ring-width) solid var(--dk-accent);
+            outline-offset: var(--dk-ring-offset);
+        }
     }
 
     /*
@@ -643,8 +661,8 @@
     }
 
     /* Code in a cell keeps its name whole, so the frame scrolls rather than the name breaking. */
-    :where(.dk-table code) {
-        overflow-wrap: normal;
+    :where(.dk-table-scroll .dk-table code) {
+        white-space: nowrap;
     }
 
     /*

package/dist/react.d.ts

@@ -11,7 +11,7 @@ export declare const GITHUB_PROFILE_URL = "https://github.com/jasonsdevspace";
  */
 export declare const SkipLink: ({ target, children, }: {
     /** The id of the element the link leads to. */
-    readonly target?: string;
+    readonly target?: string | undefined;
     readonly children?: ReactNode;
 }) => import("react").JSX.Element;
 /** A page of the demo's that the chrome links to, and can mark as the one it sits on. */
@@ -24,22 +24,22 @@ type ChromePage = 'about';
  * unnamed and so no landmark.
  */
 export declare const PortfolioStrip: ({ about, source, current, tools, toolsLabel, toolsWaiting, }: {
-    /** The demo's explainer, relative to the page or absolute. */
+    /** The demo's explainer, relative to the page or absolute, written by the demo's author. */
     readonly about: string;
-    /** The demo's repository. */
+    /** The demo's repository, written by the demo's author. */
     readonly source: string;
     /** The link that is the page the strip sits on, marked as the current page. */
-    readonly current?: ChromePage;
+    readonly current?: ChromePage | undefined;
     /** The demo's own switches, drawn beside the links. */
     readonly tools?: ReactNode;
     /** The name a screen reader gives the switches' landmark. */
-    readonly toolsLabel?: string;
+    readonly toolsLabel?: string | undefined;
     /**
      * The switches are on their way, so the strip keeps the room of one row of the kit's controls
      * in their section, empty and unnamed, so no landmark, until `tools` holds them and the section
      * takes its name.
      */
-    readonly toolsWaiting?: boolean;
+    readonly toolsWaiting?: boolean | undefined;
 }) => import("react").JSX.Element;
 /**
  * The exit after a long scroll: whose project this is, how it works, where the source and the rest
@@ -48,16 +48,19 @@ export declare const PortfolioStrip: ({ about, source, current, tools, toolsLabe
 export declare const DemoFooter: ({ name, about, source, current, license, licenseName, children, }: {
     /** The demo's name, as the footer's sentence opens with it. */
     readonly name: string;
-    /** The demo's explainer, relative to the page or absolute. */
+    /** The demo's explainer, relative to the page or absolute, written by the demo's author. */
     readonly about: string;
-    /** The demo's repository. */
+    /** The demo's repository, written by the demo's author. */
     readonly source: string;
     /** The link that is the page the footer sits on, marked as the current page. */
-    readonly current?: ChromePage;
-    /** The demo's license, the LICENSE file on the repository's main branch unless given. */
-    readonly license?: string;
+    readonly current?: ChromePage | undefined;
+    /**
+     * The demo's license, written by the demo's author, or `LICENSE` on the main branch of `source`
+     * unless given.
+     */
+    readonly license?: string | undefined;
     /** What the license is called, as the footer's sentence names it. */
-    readonly licenseName?: string;
+    readonly licenseName?: string | undefined;
     /** What the demo adds after the license, as sentences of its own. */
     readonly children?: ReactNode;
 }) => import("react").JSX.Element;
@@ -70,14 +73,14 @@ type NativeButton = Omit<ComponentPropsWithRef<'button'>, 'style' | 'disabled' |
  */
 export type ButtonProps = NativeButton & {
     /** Off, but still in the tab order, so a keyboard keeps its place and finds out why. */
-    readonly off?: boolean;
+    readonly off?: boolean | undefined;
 } & ({
     readonly accent: true;
-    readonly pressed?: never;
+    readonly pressed?: undefined;
 } | {
-    readonly accent?: false;
+    readonly accent?: false | undefined;
     /** Whether the toggle is on. False still marks it a toggle, undefined an action. */
-    readonly pressed?: boolean;
+    readonly pressed?: boolean | undefined;
 });
 /**
  * A button, of type button unless a page gives another, so it never submits a form by surprise.
@@ -95,7 +98,7 @@ type FieldParts = {
     /** What is wrong with the value, drawn only when given, which marks the control invalid. */
     readonly error?: ReactNode;
     /** The control's id, made with useId unless a page gives one, as it does for a link to it. */
-    readonly id?: string;
+    readonly id?: string | undefined;
 };
 export type InputFieldProps = FieldParts & Omit<ComponentPropsWithRef<'input'>, 'style' | 'id' | 'aria-invalid' | 'children'>;
 /**
@@ -113,25 +116,31 @@ export declare const SelectField: (props: SelectFieldProps) => import("react").J
 /** What a callout is about: news, something that went right, or something that went wrong. */
 export type CalloutTone = 'info' | 'success' | 'danger';
 /**
- * A message set apart from the page, with an optional title before it and actions after it. It has
- * no role unless the page gives `live`, whatever its tone, since a message on the page when it
- * loads is read in its place. A live message is drawn even when empty, so the page can mount it
- * first and fill it after, which is when a screen reader reads it. The role sits on the message,
- * which holds the title and the tone's word too, so they are read with it, and the actions are
- * not.
+ * A callout's own props, beside a `<div>`'s own, its `id`, a page's class, drawn after the kit's,
+ * and its `ref` among them, which holds the callout drawn for a page that moves focus to it, such
+ * as a summary of what went wrong in a form. Its `title` is the callout's, not the attribute.
  */
-export declare const Callout: ({ tone, title, headingLevel, live, prefix, actions, children, }: {
-    readonly tone?: CalloutTone;
+export type CalloutProps = Omit<ComponentPropsWithRef<'div'>, 'style' | 'role' | 'title' | 'children' | 'dangerouslySetInnerHTML' | 'aria-live' | 'aria-atomic' | 'aria-relevant'> & {
+    readonly tone?: CalloutTone | undefined;
     /** What the callout is about, drawn before its message. */
     readonly title?: ReactNode;
     /** The title's heading level, where the callout is a section a visitor would jump to. */
-    readonly headingLevel?: 2 | 3 | 4 | 5 | 6;
+    readonly headingLevel?: 2 | 3 | 4 | 5 | 6 | undefined;
     /** A message a screen reader reads when it changes, politely or at once. */
-    readonly live?: "status" | "alert";
+    readonly live?: 'status' | 'alert' | undefined;
     /** The word read before the title or the message, the tone's own unless given. */
-    readonly prefix?: string;
+    readonly prefix?: string | undefined;
     /** Buttons or links that act on the message. */
     readonly actions?: ReactNode;
     readonly children?: ReactNode;
-}) => import("react").JSX.Element;
+};
+/**
+ * A message set apart from the page, with an optional title before it and actions after it. It has
+ * no role unless the page gives `live`, whatever its tone, since a message on the page when it
+ * loads is read in its place. A live message is drawn even when empty, so the page can mount it
+ * first and fill it after, which is when a screen reader reads it. The role sits on the message,
+ * which holds the title and the tone's word too, so they are read with it, and the actions are
+ * not.
+ */
+export declare const Callout: ({ tone, title, headingLevel, live, prefix, actions, className, children, ...native }: CalloutProps) => import("react").JSX.Element;
 export {};

package/dist/react.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx, jsxs as _jsxs, Fragment as _Fragment } from "react/jsx-runtime";
-import { useId } from 'react';
+import { Children, Fragment, isValidElement, useId, } from 'react';
 /*
  * The page chrome a demo draws around its page, a skip link, a strip above the page that says
  * whose demo it is and a footer below it, and the buttons, fields and callouts on the page itself.
@@ -8,8 +8,15 @@ import { useId } from 'react';
  * page whose policy allows styles only from its own origin draws it. A control's state is a
  * native or ARIA attribute, never a class of the kit's.
  */
-/** Whether a slot holds something to draw: a demo's `cond && <X />` leaves false or null. */
-const drawn = (node) => node !== undefined && node !== null && node !== false;
+/**
+ * Whether a slot holds something to draw: a demo's `cond && <X />` leaves false or null, an empty
+ * string draws nothing either, and nor does a list or a fragment of only those. Every slot a
+ * component leaves out when it is empty is read the same way. A number draws, 0 included, as React
+ * draws it, so a page that writes `count && <X />` writes `count > 0 && <X />` instead.
+ */
+const filled = (node) => Children.toArray(node).some((child) => isValidElement(child) && child.type === Fragment
+    ? filled(child.props.children)
+    : child !== '');
 /** Where the portfolio is, and the section of it that lists the work. */
 export const PORTFOLIO_URL = 'https://jasonsdevspace.com/';
 export const PORTFOLIO_WORK_URL = 'https://jasonsdevspace.com/#work';
@@ -30,14 +37,12 @@ const currentAs = (current, page) => current === page ? 'page' : undefined;
  * named for them, and while they are on their way the strip keeps their room in that section,
  * unnamed and so no landmark.
  */
-export const PortfolioStrip = ({ about, source, current, tools, toolsLabel = 'Demo', toolsWaiting = false, }) => (_jsxs("div", { className: "dk-strip", children: [_jsxs("nav", { className: "dk-strip-links", "aria-label": "Portfolio", children: [_jsx("a", { href: PORTFOLIO_WORK_URL, children: "A demo by Jason Poteet" }), _jsx("a", { href: about, "aria-current": currentAs(current, 'about'), children: "How it works" }), _jsx("a", { href: source, children: "Source on GitHub" })] }), drawn(tools) ? (_jsx("section", { className: "dk-strip-tools", "aria-label": toolsLabel, children: tools })) : toolsWaiting ? (_jsx("section", { className: "dk-strip-tools", children: _jsx("span", { className: "dk-strip-room" }) })) : null] }));
+export const PortfolioStrip = ({ about, source, current, tools, toolsLabel = 'Demo', toolsWaiting = false, }) => (_jsxs("div", { className: "dk-strip", children: [_jsxs("nav", { className: "dk-strip-links", "aria-label": "Portfolio", children: [_jsx("a", { href: PORTFOLIO_WORK_URL, children: "More work by Jason Poteet" }), _jsx("a", { href: about, "aria-current": currentAs(current, 'about'), children: "How it works" }), _jsx("a", { href: source, children: "Source on GitHub" })] }), filled(tools) ? (_jsx("section", { className: "dk-strip-tools", "aria-label": toolsLabel, children: tools })) : toolsWaiting ? (_jsx("section", { className: "dk-strip-tools", children: _jsx("span", { className: "dk-strip-room" }) })) : null] }));
 /**
  * The exit after a long scroll: whose project this is, how it works, where the source and the rest
  * of the work are, and the license, with anything the demo adds of its own after them.
  */
-export const DemoFooter = ({ name, about, source, current, license = `${source.endsWith('/') ? source.slice(0, -1) : source}/blob/main/LICENSE`, licenseName = 'MIT license', children, }) => (_jsx("footer", { className: "dk-footer", children: _jsxs("p", { children: [name, " is a portfolio project by ", _jsx("a", { href: PORTFOLIO_URL, children: "Jason Poteet" }), ".", ' ', _jsx("a", { href: about, "aria-current": currentAs(current, 'about'), children: "How it works" }), ", in plain words. The ", _jsx("a", { href: source, children: "source" }), " and", ' ', _jsx("a", { href: GITHUB_PROFILE_URL, children: "more work" }), " are on GitHub, under the", ' ', _jsx("a", { href: license, children: licenseName }), ".", drawn(children) ? _jsxs(_Fragment, { children: [" ", children] }) : null] }) }));
-/** Whether a slot holds words to draw, an empty string being none. */
-const filled = (node) => drawn(node) && node !== '';
+export const DemoFooter = ({ name, about, source, current, license = `${source.endsWith('/') ? source.slice(0, -1) : source}/blob/main/LICENSE`, licenseName = 'MIT license', children, }) => (_jsx("footer", { className: "dk-footer", children: _jsxs("p", { children: [name, " is a portfolio project by ", _jsx("a", { href: PORTFOLIO_URL, children: "Jason Poteet" }), ".", ' ', _jsx("a", { href: about, "aria-current": currentAs(current, 'about'), children: "How it works" }), ", in plain words. The ", _jsx("a", { href: source, children: "source" }), " and", ' ', _jsx("a", { href: GITHUB_PROFILE_URL, children: "more work" }), " are on GitHub, under the", ' ', _jsx("a", { href: license, children: licenseName }), ".", filled(children) ? _jsxs(_Fragment, { children: [" ", children] }) : null] }) }));
 /**
  * A list of names an attribute holds, such as the classes a component draws, its own first and a
  * page's after them, or the ids that describe a control, with any left out or empty dropped.
@@ -112,6 +117,12 @@ const TONE_WORDS = {
 };
 /** The element a callout's title is drawn as, at each heading level a page may give it. */
 const HEADINGS = { 2: 'h2', 3: 'h3', 4: 'h4', 5: 'h5', 6: 'h6' };
+/**
+ * A tone or a heading level the types refuse, as a page in plain JavaScript can pass, draws news
+ * and a paragraph, rather than a class the sheet has no rule for or an element React refuses.
+ */
+const toneOf = (tone) => Object.hasOwn(TONE_WORDS, tone) ? tone : 'info';
+const titleOf = (level) => level !== undefined && Object.hasOwn(HEADINGS, level) ? HEADINGS[level] : 'p';
 /**
  * A message set apart from the page, with an optional title before it and actions after it. It has
  * no role unless the page gives `live`, whatever its tone, since a message on the page when it
@@ -120,11 +131,12 @@ const HEADINGS = { 2: 'h2', 3: 'h3', 4: 'h4', 5: 'h5', 6: 'h6' };
  * which holds the title and the tone's word too, so they are read with it, and the actions are
  * not.
  */
-export const Callout = ({ tone = 'info', title, headingLevel, live, prefix = TONE_WORDS[tone], actions, children, }) => {
-    // A level the types refuse, as a page in plain JavaScript can pass, draws a paragraph.
-    const Title = (headingLevel === undefined ? undefined : HEADINGS[headingLevel]) ?? 'p';
+export const Callout = ({ tone = 'info', title, headingLevel, live, prefix, actions, className, children, ...native }) => {
+    const kind = toneOf(tone);
+    const spoken = prefix ?? TONE_WORDS[kind];
+    const Title = titleOf(headingLevel);
     const titled = filled(title);
     const said = filled(children);
-    const word = prefix === '' ? null : _jsx("span", { className: "dk-visually-hidden", children: prefix });
-    return (_jsxs("div", { className: spaced('dk-callout', tone !== 'info' && `dk-callout-${tone}`), children: [titled || said || live !== undefined ? (_jsxs("div", { className: "dk-callout-body", role: live, children: [titled ? (_jsxs(Title, { className: "dk-callout-title", children: [word, title] })) : null, !titled && said ? word : null, said ? children : null] })) : null, filled(actions) ? _jsx("div", { className: "dk-callout-actions", children: actions }) : null] }));
+    const word = spoken === '' ? null : _jsx("span", { className: "dk-visually-hidden", children: spoken });
+    return (_jsxs("div", { ...native, role: undefined, style: undefined, dangerouslySetInnerHTML: undefined, "aria-live": undefined, "aria-atomic": undefined, "aria-relevant": undefined, className: spaced('dk-callout', kind !== 'info' && `dk-callout-${kind}`, className), children: [titled || said || live !== undefined ? (_jsxs("div", { className: "dk-callout-body", role: live, children: [titled ? (_jsxs(Title, { className: "dk-callout-title", children: [word, title] })) : null, !titled && said ? word : null, said ? children : null] })) : null, filled(actions) ? _jsx("div", { className: "dk-callout-actions", children: actions }) : null] }));
 };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@jasonsdevspace/design-kit",
-    "version": "0.1.0-next.3",
+    "version": "0.1.0-next.4",
     "description": "Design tokens, base styles, a theme script, page chrome, buttons, fields, callouts and an explainer layout for the demos on jasonsdevspace.com.",
     "keywords": [
         "design-tokens",