@fusion.dev/helix-templates 0.139.0 → 0.141.0

package/templates/react-vite/src/landing.tsx

@@ -3,43 +3,43 @@ import { DOCS } from './docs.js'
 import { Link } from './routes.js'
 
 /**
- * **A locale named rather than left to the machine.** `toLocaleString()` with no
- * argument reads the environment's locale, which is the server's in one template
- * and the reader's in both, so the same number is grouped two ways and the
- * markup React hydrates does not match the markup it rendered.
+ * **A locale named, so the number reads the same everywhere.**
+ * `toLocaleString()` with no argument reads the machine's locale: the server's
+ * in the Next.js template, and the browser's in both. The same number is then
+ * grouped two ways, and the markup React hydrates does not match the markup it
+ * rendered.
  */
 const figure = new Intl.NumberFormat('en-US')
 
 /**
- * The first screen, and the only page here that is about the starter rather
- * than built out of it.
+ * The first screen, and the only page here about the starter itself.
  *
  * Delete it once you know your way around: nothing else imports it, and the
  * route it answers becomes yours.
  *
- * **The heading says what this is, and the project's name stays in the bar.** A
- * scaffold called `my-app` opening on an `<h1>my-app</h1>` tells its reader
- * nothing they did not type thirty seconds ago, and spends the loudest line on
- * the page doing it.
- *
- * **Anchors, not a `Button` with an `href`.** A button that navigates is a link
- * wearing a button's clothes, and the two are different things to a keyboard and
- * to a screen reader. The base stylesheet styles an anchor that asks with
- * `data-button`, so a link can look like one without being one.
+ * **The calls to action are anchors.** A button that navigates is a link
+ * dressed as a button, and the two are different things to a keyboard and to
+ * a screen reader. The base stylesheet styles an anchor that asks with
+ * `data-button`, so a link can look like one and stay a link.
  */
 export function Landing() {
   return (
     <div className="stack">
       <header className="first-screen">
+        {/* **The light behind the first screen**: a helix, drawn by the library
+            in the theme's colors, so a new brand color relights it. It shows
+            one still frame where motion is reduced, and a gradient where the
+            browser draws without a GPU. */}
+        <helix-aura className="first-light" data-layer speed={0.4} terminus={0.8} variant="braid" />
         <div className="hero">
-          <helix-text emphasis="muted" variant="label">
-            Helix starter
+          <helix-tag emphasis="subtle" tone="primary">
+            Starter
+          </helix-tag>
+          <helix-text as="h1" variant="display">
+            Helix design system
           </helix-text>
-          <helix-text as="h1">Every tag on this page is Helix</helix-text>
-          <helix-text as="p" className="lede" emphasis="muted" variant="body">
-            Nothing here is a wrapper: the tags are the library's own elements, and every color,
-            size and space inside them comes from one set of tokens. Three routes are laid down, and
-            all of them are yours.
+          <helix-text as="p" className="lede" variant="body">
+            Web components in your brand's colors, drawn from one set of tokens.
           </helix-text>
           <div className="actions">
             <Link data-button="solid" data-button-tone="primary" href="/overview">
@@ -51,17 +51,13 @@ export function Landing() {
           </div>
         </div>
 
-        {/* **What the first screen has to look at, and the honest thing to look
-            at is the library working.** The figures are the roster the data view
-            draws, read from the same module, so the panel is the app rather than
-            a decoration of it. `helix-stat` sets the number on the display face
-            at a size the type scale does not reach, which is the one place on a
-            page where the number is the design. */}
-        <helix-card className="specimen" separation="outlined">
-          <helix-text as="h2" slot="header" variant="title">
-            The roster, in three figures
-          </helix-text>
-          <helix-stat-group divided>
+        {/* **The library at work, on the first screen.** The figures are the
+            roster the data view draws, read from the same module, so the panel
+            is the app itself, on glass over the light. It has no link of its own:
+            the button beside it goes to the same page. */}
+        <helix-card className="specimen" material="glass" separation="outlined">
+          <helix-text as="h2" slot="header" variant="title">Roster</helix-text>
+          <helix-stat-group>
             <helix-stat>
               {roster.people}
               <span slot="label">People</span>
@@ -75,9 +71,6 @@ export function Landing() {
               <span slot="label">Reviews</span>
             </helix-stat>
           </helix-stat-group>
-          <Link data-link href="/overview" slot="footer">
-            Open the data view
-          </Link>
         </helix-card>
       </header>
 
@@ -85,106 +78,51 @@ export function Landing() {
         <helix-text as="h2" variant="subheading">
           What you have
         </helix-text>
-        {/* Three paragraphs about one installed thing, so they take a rule each
-            rather than a box each. `app.css` says why at more length. */}
-        <div className="facts">
-          <article className="fact">
-            <helix-text as="h3" variant="title">
-              Elements, not wrappers
-            </helix-text>
-            <helix-text as="p" emphasis="muted" variant="body">
-              They are custom elements, so you write the tags and there is no per-component import
-              to keep in step. One line in <helix-code>src/main.tsx</helix-code> registers all of
-              them, and a subpath like <helix-code>@fusion.dev/helix/tabs</helix-code> registers
-              one.
-            </helix-text>
-            <a data-link href={DOCS.elements}>
-              Using the elements
-            </a>
-          </article>
-
-          <article className="fact">
-            <helix-text as="h3" variant="title">
-              One set of tokens
-            </helix-text>
-            <helix-text as="p" emphasis="muted" variant="body">
-              Every color is written once as a light and dark pair, so the control in the bar moves
-              the whole page by setting a single attribute on the root. Type, spacing, radii and
-              control sizes come from the same place.
-            </helix-text>
-            <a data-link href={DOCS.tokens}>
-              Tokens
-            </a>
-          </article>
-
-          <article className="fact">
-            <helix-text as="h3" variant="title">
-              A short stylesheet
-            </helix-text>
-            <helix-text as="p" emphasis="muted" variant="body">
-              <helix-code>src/app.css</helix-code> holds this page's measure, the rhythm between its
-              blocks, and nothing a component already draws. Where a component leaves a decision
-              open it names a part: the data view reaches one to paint the row you tick.
-            </helix-text>
-            <a data-link href={DOCS.parts}>
-              Overriding a component
-            </a>
-          </article>
-        </div>
-      </section>
-
-      <section className="section">
-        <helix-text as="h2" variant="subheading">
-          Where to go next
-        </helix-text>
-        {/* **The whole card is the link, which is what `data-card` is for.** A
-            card with an anchor in its footer gives a reader a target the size of
-            three words inside a box the size of a paragraph, and the box is what
-            they aim at. The recipe is in the base layer: it draws the ring, moves
-            the card's border to the brand on hover, and leaves focus alone. So
-            nothing inside may be interactive, a link inside a link being neither
-            valid nor reachable. */}
-        <helix-grid columns={2} gap="md">
-          <Link data-card href="/overview">
+        {/* **Each tile is a link, which is what `data-card` is for.** The base
+            layer draws the ring, moves the card's border to the brand on hover,
+            and leaves focus alone. Nothing inside may be interactive, since a
+            link inside a link is neither valid nor reachable. */}
+        <div className="features">
+          <a className="feature" data-card href={DOCS.elements}>
             <helix-card separation="outlined">
-              {/* The route beside the name rather than under the text: slotted
-                  into the header the two sit on one baseline, and a row of
-                  cards stretched to a common height has nothing left floating
-                  in the middle of it. */}
-              <helix-flex align-items="baseline" gap="sm" justify-content="between" slot="header">
-                <helix-text as="h3" variant="title">
-                  The data view
-                </helix-text>
-                <helix-text emphasis="subtle" variant="code">
-                  /overview
-                </helix-text>
-              </helix-flex>
+              <span className="feature-mark">
+                <helix-icon name="cube" />
+              </span>
+              <helix-text as="h3" variant="title">
+                Custom elements
+              </helix-text>
               <helix-text as="p" emphasis="muted" variant="body">
-                Twelve people from a local module, sorted, paged and selected with nothing wired up.
-                The columns are markup you can read and the rows are one property, which is what
-                keeps the same component working at ten thousand.
+                One import in <helix-code>src/main.tsx</helix-code> registers every tag.
               </helix-text>
             </helix-card>
-          </Link>
-
-          <Link data-card href="/join">
+          </a>
+          <a className="feature" data-card href={DOCS.tokens}>
             <helix-card separation="outlined">
-              <helix-flex align-items="baseline" gap="sm" justify-content="between" slot="header">
-                <helix-text as="h3" variant="title">
-                  The form
-                </helix-text>
-                <helix-text emphasis="subtle" variant="code">
-                  /join
-                </helix-text>
-              </helix-flex>
+              <span className="feature-mark">
+                <helix-icon name="palette" />
+              </span>
+              <helix-text as="h3" variant="title">
+                One set of tokens
+              </helix-text>
               <helix-text as="p" emphasis="muted" variant="body">
-                Five controls a <helix-code>&lt;form&gt;</helix-code> reads with{' '}
-                <helix-code>FormData</helix-code>, because every one of them is a real form
-                participant. The email field's complaint is the browser's own.
+                Every color, size, and space, in light and dark.
               </helix-text>
             </helix-card>
-          </Link>
-        </helix-grid>
+          </a>
+          <a className="feature" data-card href={DOCS.parts}>
+            <helix-card separation="outlined">
+              <span className="feature-mark">
+                <helix-icon name="sliders-horizontal" />
+              </span>
+              <helix-text as="h3" variant="title">
+                Parts to style
+              </helix-text>
+              <helix-text as="p" emphasis="muted" variant="body">
+                Reach inside a component with <helix-code>::part()</helix-code>.
+              </helix-text>
+            </helix-card>
+          </a>
+        </div>
       </section>
     </div>
   )

package/templates/react-vite/src/overview.tsx

@@ -6,13 +6,13 @@ import { DOCS } from './docs.js'
  *
  * **The schema is markup and the data is a property.** The columns are elements
  * you can read in the HTML, and `rows` is the whole result handed over at once,
- * because a table of ten thousand rows cannot be written out as elements. The
- * table sorts, pages and selects out of that array on its own: none of it is
- * wired up here, and none of it is a handler you have to write.
+ * since a table of ten thousand rows cannot be written out as elements. The
+ * table sorts, pages, and selects out of that array on its own, with no handler
+ * for you to write.
  *
  * **Selection is keyed on `row-key`, so it survives a sort and a page.** A row
- * is chosen by its identity rather than by where it happened to be sitting, and
- * `app.css` paints the chosen row through the parts the table names for it.
+ * is chosen by its identity, wherever it sits, and `app.css` paints the chosen
+ * row through the parts the table names for it.
  */
 export function Overview() {
   return (
@@ -39,18 +39,18 @@ export function Overview() {
           rows={members}
           selectable
         >
-          {/* **Every column declares what it may give up, and that is the whole of
+          {/* **Every column declares what it may give up, which is the whole of
               the narrow-window story.** A column left to itself takes
-              `minmax(max-content, 1fr)`, which refuses to go below its longest
-              cell however little room there is, so the last column is pushed
-              outside the box and the reader has to scroll the table sideways to
-              read a value. A floor and a share instead: the floor is what the
-              words need, the share is how the slack is divided. Measured 16 Sep
-              2026: at 390 the four columns and the checkboxes come to 358 in a box
-              of 358, so nothing is cut and nothing wraps; the floors alone come to
-              344, so at a 376 pixel window they exactly fit and below it the table
-              scrolls its own box, which is honest, and it fades whichever edge has
-              more behind it. */}
+              `minmax(max-content, 1fr)`, which never goes below its longest
+              cell, so the last column is pushed outside the box and you have to
+              scroll the table sideways to read a value. Each column here has a
+              floor and a share: the floor is what the words need, and the share
+              is how the spare width is divided. Measured September 16, 2026: at
+              390 the four columns and the checkboxes come to 358 in a box of
+              358, so nothing is cut and nothing wraps. The floors alone come to
+              344, so at a 376 pixel window they exactly fit, and below it the
+              table scrolls its own box and fades whichever edge has more behind
+              it. */}
           <helix-table-column field="name" sortable width="minmax(5.5rem, 1.6fr)">
             Name
           </helix-table-column>
@@ -60,26 +60,24 @@ export function Overview() {
           <helix-table-column field="role" width="minmax(4.5rem, 1fr)">
             Role
           </helix-table-column>
-          {/* `end` lines the digits up under each other, which is the whole reason
-              a number column is a different thing from a text one. `max-content`
-              because a column of numerals has one right width and no reason to
-              take a share of anything. */}
+          {/* `end` lines the digits up under each other, which is what makes a
+              number column different from a text one. `max-content`, since a
+              column of numerals has one right width. */}
           <helix-table-column field="reviews" sortable text-align="end" width="max-content">
             Reviews
           </helix-table-column>
 
-          {/* The footer is a row across the table, not a corner: anything you slot
-              goes at the start and the table's own pagination sits at the end. */}
+          {/* The footer is a row across the table: anything you slot goes at the
+              start, and the table's own pagination sits at the end. */}
           <helix-text emphasis="subtle" slot="footer" variant="caption">
             {members.length} people
           </helix-text>
         </helix-data-table>
 
-        {/* A footnote to the table rather than the next block of the page, so it
-            takes the section's gap and not the stack's. */}
+        {/* A footnote to the table, so it takes the section's gap. */}
         <helix-text as="p" emphasis="muted" variant="caption">
-          Filtering, column reordering, resizing, virtualized rows and a server mode that asks you
-          for a page are all on{' '}
+          Filtering, column reordering, resizing, virtualized rows, and a server mode for large
+          results are on{' '}
           <a data-link href={DOCS.table}>
             the component's own page
           </a>

package/templates/react-vite/src/routes.tsx

@@ -2,26 +2,24 @@ import { type AnchorHTMLAttributes, useEffect, useState } from 'react'
 
 /* **The whole router, which is a hash and a listener.**
 
-   A starter should not pick your router for you, and two pages need
-   `location.hash` and one event. Swap this file for the router you want: the two
-   names it exports are Next.js's, so the rest of the app reads the same in
-   either template and nothing else here has to change.
+   Three pages need `location.hash` and one event, so the starter leaves the
+   router to you. Swap this file for the router you want: the two names it
+   exports are Next.js's, so the rest of the app reads the same in either
+   template, and nothing else has to change.
 
-   A hash rather than the History API, because the History API wants a server
-   that answers every path with the same document, and `vite preview` and
-   whatever you deploy to each have to be told to. A hash asks nothing of
-   either. */
+   A hash, because the History API wants a server that answers every path with
+   the same document, and `vite preview` and wherever you deploy each have to be
+   told to. A hash asks nothing of either. */
 
-/** Where the reader is, as a path, so the overview is `/`. */
+/** The current path, read from the hash, so the first page is `/`. */
 const read = (): string => window.location.hash.slice(1) || '/'
 
 /**
  * A destination, addressed the way the Next.js template addresses one.
  *
- * Everything but `href` goes straight through to the anchor, which is what
- * `next/link` does and is why a `data-button` or a `slot` reads the same in both
- * templates. The path is written as a path: the hash is this component's
- * business and nobody else's.
+ * Everything but `href` goes straight through to the anchor, as `next/link`
+ * does, which is why a `data-button` or a `slot` reads the same in both
+ * templates. The path is written as a path, and this component adds the hash.
  */
 export function Link({ href, ...rest }: AnchorHTMLAttributes<HTMLAnchorElement>) {
   return <a {...rest} href={`#${href ?? '/'}`} />

package/templates/react-vite/src/signup-form.tsx

@@ -12,21 +12,21 @@ interface Message {
  * The form.
  *
  * **Every control here is a form-associated custom element**, so a `<form>`
- * collects them, resets them and validates them the way it does an `<input>`.
- * That is what `ElementInternals` buys, and the submit below proves it: it reads
- * the answers with `new FormData(form)` and nothing gathers them by hand.
+ * collects them, resets them, and validates them the way it does an `<input>`.
+ * `ElementInternals` makes that possible, and the submit below proves it: it
+ * reads the answers with `new FormData(form)`, and nothing gathers them by hand.
  *
- * There is no wrapping `Field` component. A label in one shadow root cannot name
- * a control in another, so every control renders its own `label`, `hint` and
- * `feedback` instead.
+ * There is no wrapping `Field` component. A label in one shadow root cannot
+ * name a control in another, so every control renders its own `label`, `hint`,
+ * and `feedback`.
  */
 export function SignupForm() {
   const [handle, setHandle] = useState('')
   const [messages, setMessages] = useState<readonly Message[]>([])
 
   const join = (event: FormEvent<HTMLFormElement>) => {
-    /* The page answers this, so nothing navigates. Remove the line and the form
-       posts to the server like any other, with the same names. */
+    /* The page takes the submit, so nothing navigates. Remove the line and the
+       form posts to the server like any other, with the same names. */
     event.preventDefault()
     const answers = [...new FormData(event.currentTarget).entries()]
       .map(([field, value]) => `${field}=${value}`)
@@ -49,18 +49,16 @@ export function SignupForm() {
         </helix-text>
       </header>
 
-      {/* The form takes a column of its own and the notes take what is left, so a
-          wide window is a page rather than a form with a void beside it. At 390
-          the two stack and the notes read as a postscript. */}
+      {/* The form takes a column of its own and the notes take what is left. At
+          390 the two stack, and the notes read as a postscript. */}
       <div className="split">
       <form className="form" onSubmit={join}>
         <helix-input autocomplete="name" label="Name" name="name" required />
 
         {/* Validation is the platform's: `type` and `required` are set on the
-            real input inside, and its own message is what shows once the reader
-            has touched the field. Set `feedback` to say it in your own words
-            instead, and it shows from the first paint rather than after a
-            mistake. */}
+            real input inside, and its own message shows once the field has been
+            touched. Set `feedback` to say it in your own words, and it shows
+            from the first paint. */}
         <helix-input
           hint="Where we send the welcome note."
           label="Email"
@@ -72,11 +70,11 @@ export function SignupForm() {
         {/* **A controlled value, which is the one habit to unlearn.** The handler
             is a prop named for the event, so `onhelix-before-change` hears
             `helix-before-change`. A Helix element is not read-only: writing
-            `value` seeds it and the element goes on applying its own changes, so
-            taking the decision means refusing the change with `preventDefault()`
-            and then setting the value you want. Declining to call `setHandle` is
-            not a refusal, and leaves the element holding what you did not
-            accept. */}
+            `value` seeds it, and the element goes on applying its own changes.
+            So taking the decision means refusing the change with
+            `preventDefault()`, then setting the value you want. Leaving
+            `setHandle` uncalled refuses nothing, and the element keeps the value
+            you meant to turn down. */}
         <helix-input
           hint="Lowercase and hyphens, whatever you type."
           label="Handle"
@@ -96,8 +94,8 @@ export function SignupForm() {
           ))}
         </helix-select>
 
-        {/* A switch is a thing happening now rather than an answer a form asks
-            for, which is why it says on and off. It still submits, as `on`. */}
+        {/* A switch is a thing happening now, which is why it says on and off.
+            It still submits, as `on`. */}
         <helix-switch label="Send me the weekly digest" name="digest" />
 
         <helix-button emphasis="solid" tone="primary" type="submit">
@@ -106,27 +104,25 @@ export function SignupForm() {
       </form>
 
         <aside className="notes">
-          {/* The one fact a reader needs before typing their name into a page
-              they have had for five minutes, which is why it is a callout and
-              not the fourth line of a paragraph. `tone` is the meaning and the
-              component decides what that looks like: a tint mixed from the
-              status color and a bar on the inline start, so it survives being
-              read in grayscale. */}
-          <helix-callout tone="info">
-            Nothing is posted anywhere. Submit it and the message shows exactly what a server would
-            have been handed.
+          {/* The one fact you need before typing your name into a page you have
+              had for five minutes, so it is a callout. `neutral` is a note that
+              reports no status, drawn in the muted ink with a bar on the inline
+              start, so it stays in the palette, ink or brand. */}
+          <helix-callout tone="neutral">
+            The form posts nothing. Submit it, and a message shows exactly what a server would
+            receive.
           </helix-callout>
           <helix-text as="h2" variant="title">
-            What this is showing
+            What the form shows
           </helix-text>
           <helix-text as="p" emphasis="muted" variant="body">
-            Every control is a form-associated custom element, so the submit reads them with{' '}
-            <helix-code>new FormData(form)</helix-code> and nothing gathers the answers by hand.
-            Reset the form and they all go back, the way an <helix-code>input</helix-code> does.
+            Every control is a form-associated custom element, so the submit reads them all
+            with <helix-code>new FormData(form)</helix-code>. Reset the form and they all go back,
+            the way an <helix-code>input</helix-code> does.
           </helix-text>
           <helix-text as="p" emphasis="muted" variant="body">
-            Leave the email wrong and the complaint is the browser's own, in the reader's language.
-            Handle is the controlled one: it refuses the change and writes back what it will accept.
+            Leave the email wrong and the browser shows its own message, in your language. Handle is
+            the controlled field: the page refuses each change and writes back a cleaned value.
           </helix-text>
           <a data-link href={DOCS.forms}>
             Forms
@@ -136,9 +132,9 @@ export function SignupForm() {
 
       {/* **The region is rendered whether or not there is anything in it.**
           Assistive technology subscribes to a live region, and one that arrives
-          already holding its message is frequently never announced. Nothing
-          creates or destroys a message here either: the items are state, and a
-          dismissed one asks to go through `helix-dismiss`. */}
+          already holding its message is often never announced. Messages are
+          state, so nothing creates or destroys one here, and a dismissed one
+          asks to go through `helix-dismiss`. */}
       <helix-toast>
         {messages.map((message) => (
           <helix-toast-item

package/templates/react-vite/src/site-footer.tsx

@@ -3,32 +3,26 @@ import { DOCS } from './docs.js'
 /**
  * The bar's counterpart, on every route.
  *
- * **It is here so that a page ends rather than stops.** The overview is a
- * heading, a table and a caption, which on a tall window left the bottom third
- * of the screen empty and read as a layout that had run out. A footer is the
- * ordinary answer: it puts a floor under the content, and it is where the links
- * a reader wants once rather than constantly belong, which is why the landing
- * page no longer carries them itself.
+ * **It puts a floor under the content.** The overview is a heading, a table,
+ * and a caption, which on a tall window left the bottom third of the screen
+ * empty, as if the layout had run out. The footer is also where the links you
+ * want once belong, so the landing page no longer carries them.
  *
- * `data-link="subtle"` reads as body text until it is hovered, which is what a
- * row of links under a rule should do: they are a destination, not a sentence
- * asking to be read.
+ * `data-link="quiet"` sets a link in the muted ink with no underline, and it
+ * takes the foreground on hover, which suits a row of links under a rule.
  */
 export function SiteFooter() {
   return (
     <footer className="site-footer">
       <div className="footer-row">
-        <helix-text as="p" emphasis="subtle" variant="caption">
-          Every component in here, with its API, its parts and its examples, has a page.
-        </helix-text>
         <div className="footer-links">
-          <a data-link="subtle" href={DOCS.gallery}>
+          <a data-link="quiet" href={DOCS.gallery}>
             Components
           </a>
-          <a data-link="subtle" href={DOCS.elements}>
+          <a data-link="quiet" href={DOCS.elements}>
             Documentation
           </a>
-          <a data-link="subtle" href={DOCS.react}>
+          <a data-link="quiet" href={DOCS.react}>
             React
           </a>
         </div>

package/templates/react-vite/src/site-header.tsx

@@ -18,18 +18,16 @@ export function SiteHeader() {
      control draws the same glyph on the server and on the first client paint. */
   const [mode, setMode] = useState<Mode>('system')
 
-  /**
+    /**
    * One attribute, two modes, and no second stylesheet.
    *
-   * Every Helix token is written once as a `light-dark()` pair, so which half
-   * resolves is decided by `color-scheme` and nothing else. `data-color-mode`
-   * sets it, and because `color-scheme` inherits the attribute works on any
-   * element, not only on the root: put it on a panel for a light preview inside
-   * a dark page.
+   * Every Helix token is written once as a `light-dark()` pair, so
+   * `color-scheme` decides which half resolves. `data-color-mode` sets it, and
+   * since `color-scheme` inherits, the attribute works on any element: put it
+   * on a panel for a light preview inside a dark page.
    *
-   * `system` removes the attribute rather than writing out whichever mode is
-   * current, which would freeze the page there the moment the reader's machine
-   * changed.
+   * `system` removes the attribute. Writing out whichever mode is current would
+   * hold the page there when the system's own setting changed.
    */
   const cycle = () => {
     const next = MODES[(MODES.indexOf(mode) + 1) % MODES.length]
@@ -43,22 +41,17 @@ export function SiteHeader() {
 
   return (
     <helix-app-header material="glass" sticky>
-      {/* The wordmark is the way back to the first page, which is what a reader
-          expects of one, so there is no third destination in the bar saying the
-          same thing. It is also the only name of the project on the screen: the
-          landing page leads with what this is rather than with what you called
-          it.
-
-          The mark is a placeholder for your own, and it is drawn in
-          `--helix-color-brand-mark`, the token for the brand as a graphic. */}
+      {/* The wordmark is the way back to the first page, as a wordmark usually
+          is, so there is no third destination in the bar saying the same thing.
+          It names the library the starter is built on, and it is the place for
+          your own name or logo. */}
       <Link className="wordmark" data-link="quiet" href="/" slot="start">
-        <helix-icon name="cube" />
-        <helix-text variant="body-strong">__PROJECT_NAME__</helix-text>
+        <helix-text variant="body-strong">Helix</helix-text>
       </Link>
 
       {/* The links are yours. Navigation owns the marker that travels between
-          them and renders no anchors of its own, because a router renders its
-          own and could not render them inside this shadow root. The base layer
+          them and renders no anchors of its own, since a router renders its
+          own, which could not sit inside this shadow root. The base layer
           styles them, `aria-current="page"` included. */}
       <helix-navigation label="Pages">
         <Link aria-current={path === '/overview' ? 'page' : undefined} href="/overview">
@@ -69,9 +62,8 @@ export function SiteHeader() {
         </Link>
       </helix-navigation>
 
-      {/* An icon with no words has no accessible name unless it is given one,
-          which is the whole reason this is its own element rather than a button
-          with a glyph in it. */}
+      {/* An icon with no words has no accessible name until it is given one,
+          which is why this is its own element. */}
       <helix-icon-button
         label={`Color mode: ${mode}`}
         onClick={cycle}