From 13913a335ad49f64d0aed241b9c4ac3183ef09a7 Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Wed, 7 Oct 2026 17:44:35 -0400
Subject: [PATCH 01/30] Give Pret UI's usage page, Viewport and test targets
 data-test hooks, and check every usage page shows its example

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/components/autocomplete.gts   |  6 ++-
 packages/pretui/components/descriptions.gts   |  2 +
 .../pretui/components/freestyle-usage.gts     | 40 +++++++++++----
 .../components/freestyle-usage.test.gts       | 24 ++++-----
 .../pretui/components/segmented-control.gts   |  1 +
 packages/pretui/components/usage-argument.gts |  8 ++-
 .../pretui/components/usage-argument.test.gts |  6 +--
 .../components/usage-css-variable.test.gts    |  6 +--
 .../pretui/components/usage-object.test.gts   |  8 +--
 packages/pretui/components/viewport.gts       | 13 ++++-
 packages/pretui/controls-entry.test.gts       | 10 +++-
 packages/pretui/design-layers.test.gts        |  8 ++-
 packages/pretui/feedback-toaster.test.gts     |  2 +-
 packages/pretui/foundations-render.test.gts   |  8 ++-
 packages/pretui/internal/freestyle.gts        |  4 +-
 packages/pretui/media-library.test.gts        |  8 ++-
 packages/pretui/menu-context.test.gts         |  2 +-
 packages/pretui/overlay-confirm.test.gts      |  6 +--
 packages/pretui/pretui-component.gts          |  8 +--
 packages/pretui/pretui-component.test.gts     | 16 +++---
 packages/pretui/pretui-note.gts               |  2 +-
 packages/pretui/reading-listing.test.gts      | 18 +++----
 packages/pretui/scripts/usage-proof.mjs       |  8 ++-
 packages/pretui/structure-flow.test.gts       |  2 +-
 packages/pretui/usage-pages.test.gts          |  8 ++-
 packages/pretui/viewport.test.gts             | 51 +++++++------------
 26 files changed, 168 insertions(+), 107 deletions(-)

diff --git a/packages/pretui/components/autocomplete.gts b/packages/pretui/components/autocomplete.gts
index 4e830dfddab..3a24a1f768a 100644
--- a/packages/pretui/components/autocomplete.gts
+++ b/packages/pretui/components/autocomplete.gts
@@ -769,7 +769,11 @@ export class Autocomplete extends Component<AutocompleteSignature> {
                 {{!-- the face carries the chrome and is invisible to AT, so a
                       caller may yield ANY markup into it without tripping
                       require-presentational-children in their own file --}}
-                <span class='pretui-ac-face' aria-hidden='true'>
+                <span
+                  class='pretui-ac-face'
+                  aria-hidden='true'
+                  data-test-pretui-autocomplete-face
+                >
                   {{#if (has-block 'item')}}
                     {{yield row.item (this.rowState row) to='item'}}
                   {{else}}
diff --git a/packages/pretui/components/descriptions.gts b/packages/pretui/components/descriptions.gts
index 70bab24e5e6..e6ae6dd2600 100644
--- a/packages/pretui/components/descriptions.gts
+++ b/packages/pretui/components/descriptions.gts
@@ -183,11 +183,13 @@ export class Descriptions extends Component<DescriptionsSignature> {
             class='pretui-desc-pair'
             data-span={{entry.span}}
             data-mono={{entry.mono}}
+            data-test-pretui-descriptions-pair
           >
             <dt class='pretui-desc-label'>
               {{entry.item.label}}{{#if this.colon}}<span
                   class='pretui-desc-colon'
                   aria-hidden='true'
+                  data-test-pretui-descriptions-colon
                 >:</span>{{/if}}
             </dt>
             <dd class='pretui-desc-value'>
diff --git a/packages/pretui/components/freestyle-usage.gts b/packages/pretui/components/freestyle-usage.gts
index 8a6a61877c5..cf2d2ff6dd2 100644
--- a/packages/pretui/components/freestyle-usage.gts
+++ b/packages/pretui/components/freestyle-usage.gts
@@ -50,13 +50,19 @@ export interface FreestyleUsageSignature {
 
 export const FreestyleUsage: TemplateOnlyComponent<FreestyleUsageSignature> =
   <template>
-    <div class='FreestyleUsage' ...attributes>
+    <div class='FreestyleUsage' data-test-pretui-usage ...attributes>
       {{! identity lives in the page header (breadcrumb) — no h2 here; one
           compact description line, then straight to the artboard }}
       {{#if (has-block 'description')}}
-        <p class='FreestyleUsage-description'>{{yield to='description'}}</p>
+        <p
+          class='FreestyleUsage-description'
+          data-test-pretui-usage-description
+        >{{yield to='description'}}</p>
       {{else if @description}}
-        <p class='FreestyleUsage-description'>{{@description}}</p>
+        <p
+          class='FreestyleUsage-description'
+          data-test-pretui-usage-description
+        >{{@description}}</p>
       {{/if}}
 
       <div class='FreestyleUsage-stage'>
@@ -66,8 +72,11 @@ export const FreestyleUsage: TemplateOnlyComponent<FreestyleUsageSignature> =
               {{yield to='example'}}
             </Viewport>
             {{#if @source}}
-              <div class='wb-codestrip'>
-                <code class='wb-code'>{{@source}}</code>
+              <div class='wb-codestrip' data-test-pretui-usage-source>
+                <code
+                  class='wb-code'
+                  data-test-pretui-usage-source-code
+                >{{@source}}</code>
                 <CopyButton
                   @text={{@source}}
                   @label='Copy usage'
@@ -78,8 +87,11 @@ export const FreestyleUsage: TemplateOnlyComponent<FreestyleUsageSignature> =
           </div>
         </div>
         {{#if (has-block 'api')}}
-          <aside class='FreestyleUsage-props'>
-            <h3 class='FreestyleUsage-sectionTitle'>Properties</h3>
+          <aside class='FreestyleUsage-props' data-test-pretui-usage-props>
+            <h3
+              class='FreestyleUsage-sectionTitle'
+              data-test-pretui-usage-section-title
+            >Properties</h3>
             {{yield
               (hash
                 Action=(component UsageAction mode='prop')
@@ -105,9 +117,12 @@ export const FreestyleUsage: TemplateOnlyComponent<FreestyleUsageSignature> =
       </div>
 
       {{#if (has-block 'api')}}
-        <div class='FreestyleUsage-api wb-panel'>
+        <div class='FreestyleUsage-api wb-panel' data-test-pretui-usage-api>
           <div class='wb-panel-h'>
-            <h3 class='FreestyleUsage-sectionTitle wb-cap'>API</h3>
+            <h3
+              class='FreestyleUsage-sectionTitle wb-cap'
+              data-test-pretui-usage-section-title
+            >API</h3>
           </div>
           <Table>
             <:head>
@@ -139,9 +154,12 @@ export const FreestyleUsage: TemplateOnlyComponent<FreestyleUsageSignature> =
       {{/if}}
 
       {{#if (has-block 'cssVars')}}
-        <div class='FreestyleUsage-api wb-panel'>
+        <div class='FreestyleUsage-api wb-panel' data-test-pretui-usage-css-vars>
           <div class='wb-panel-h'>
-            <h3 class='FreestyleUsage-sectionTitle wb-cap'>CSS Variables</h3>
+            <h3
+              class='FreestyleUsage-sectionTitle wb-cap'
+              data-test-pretui-usage-section-title
+            >CSS Variables</h3>
           </div>
           <Table>
             <:head>
diff --git a/packages/pretui/components/freestyle-usage.test.gts b/packages/pretui/components/freestyle-usage.test.gts
index f11a592e00a..a70be0a4a93 100644
--- a/packages/pretui/components/freestyle-usage.test.gts
+++ b/packages/pretui/components/freestyle-usage.test.gts
@@ -9,10 +9,10 @@ import { setupCardTest } from '@cardstack/host/tests/helpers';
 import { FreestyleUsage } from './freestyle-usage';
 
 function root(): HTMLElement {
-  return document.querySelector('.FreestyleUsage') as HTMLElement;
+  return document.querySelector('[data-test-pretui-usage]') as HTMLElement;
 }
 function titles(): string[] {
-  return Array.from(root().querySelectorAll('.FreestyleUsage-sectionTitle')).map((h) => h.textContent?.trim() ?? '');
+  return Array.from(root().querySelectorAll('[data-test-pretui-usage-section-title]')).map((h) => h.textContent?.trim() ?? '');
 }
 
 module('Pretui | components/freestyle-usage', function (hooks) {
@@ -26,9 +26,9 @@ module('Pretui | components/freestyle-usage', function (hooks) {
         </FreestyleUsage>
       </template>,
     );
-    assert.strictEqual(root().querySelector('.FreestyleUsage-description')?.textContent, 'Primary action.');
-    assert.ok(root().querySelector('[data-test-pretui-viewport] .pretui-artboard-body [data-test-demo]'), 'the example is framed, so it can be resized');
-    assert.strictEqual(root().querySelector('.wb-codestrip'), null, 'no source, no code strip');
+    assert.strictEqual(root().querySelector('[data-test-pretui-usage-description]')?.textContent, 'Primary action.');
+    assert.ok(root().querySelector('[data-test-pretui-viewport] [data-test-pretui-artboard-body] [data-test-demo]'), 'the example is framed, so it can be resized');
+    assert.strictEqual(root().querySelector('[data-test-pretui-usage-source]'), null, 'no source, no code strip');
     assert.deepEqual(titles(), [], 'no api block, no Properties aside and no API table');
   });
 
@@ -41,9 +41,9 @@ module('Pretui | components/freestyle-usage', function (hooks) {
         </FreestyleUsage>
       </template>,
     );
-    assert.strictEqual(root().querySelector('.FreestyleUsage-description')?.textContent, 'From the block');
-    assert.strictEqual(root().querySelector('.wb-codestrip .wb-code')?.textContent, '<Button>Go</Button>');
-    assert.ok(root().querySelector('.wb-codestrip button'), 'copy usage');
+    assert.strictEqual(root().querySelector('[data-test-pretui-usage-description]')?.textContent, 'From the block');
+    assert.strictEqual(root().querySelector('[data-test-pretui-usage-source-code]')?.textContent, '<Button>Go</Button>');
+    assert.ok(root().querySelector('[data-test-pretui-usage-source] [data-test-pretui-copy-button]'), 'copy usage');
   });
 
   test('the api block is yielded twice — once as knobs in the Properties aside, once as rows in the API table', async function (assert) {
@@ -66,12 +66,12 @@ module('Pretui | components/freestyle-usage', function (hooks) {
       </template>,
     );
     assert.deepEqual(titles(), ['Properties', 'API', 'CSS Variables']);
-    let aside = root().querySelector('.FreestyleUsage-props') as HTMLElement;
-    assert.deepEqual(Array.from(aside.querySelectorAll('.proprow-label')).map((l) => l.textContent?.trim()), ['label', 'disabled', '--pretui-btn-radius'], 'actions and yields have no knob');
-    let apiRows = Array.from(root().querySelectorAll('.FreestyleUsage-api')[0]?.querySelectorAll('tr.FreestyleUsageArgument') ?? []);
+    let aside = root().querySelector('[data-test-pretui-usage-props]') as HTMLElement;
+    assert.deepEqual(Array.from(aside.querySelectorAll('[data-test-pretui-prop-row-label]')).map((l) => l.textContent?.trim()), ['label', 'disabled', '--pretui-btn-radius'], 'actions and yields have no knob');
+    let apiRows = Array.from(root().querySelector('[data-test-pretui-usage-api]')?.querySelectorAll('[data-test-pretui-usage-arg]') ?? []);
     assert.deepEqual(apiRows.map((r) => r.querySelector('td')?.textContent?.replace(/\s+/g, ' ').trim()), ['@label', '@disabled', '@onClick', '{{default}}']);
     assert.deepEqual(apiRows.map((r) => r.querySelectorAll('td')[1]?.textContent?.trim()), ['String', 'Bool', 'Action', 'Yield']);
-    let cssRows = Array.from(root().querySelectorAll('.FreestyleUsage-api')[1]?.querySelectorAll('tr.FreestyleUsageArgument') ?? []);
+    let cssRows = Array.from(root().querySelector('[data-test-pretui-usage-css-vars]')?.querySelectorAll('[data-test-pretui-usage-arg]') ?? []);
     assert.deepEqual(cssRows.map((r) => Array.from(r.querySelectorAll('td')).map((td) => td.textContent?.replace(/\s+/g, ' ').trim())), [['--pretui-btn-radius', 'CSS', '', '6px']]);
   });
 });
diff --git a/packages/pretui/components/segmented-control.gts b/packages/pretui/components/segmented-control.gts
index c50fde46612..53331623a4c 100644
--- a/packages/pretui/components/segmented-control.gts
+++ b/packages/pretui/components/segmented-control.gts
@@ -100,6 +100,7 @@ export class SegmentedControl extends Component<SegmentedControlSignature> {
             checked={{this.isActive option}}
             disabled={{@disabled}}
             {{on 'change' (fn this.pick option)}}
+            data-test-pretui-segmented-option={{option.value}}
           />
           {{option.label}}
         </label>
diff --git a/packages/pretui/components/usage-argument.gts b/packages/pretui/components/usage-argument.gts
index dc7b249a1d4..6887e1029c8 100644
--- a/packages/pretui/components/usage-argument.gts
+++ b/packages/pretui/components/usage-argument.gts
@@ -44,12 +44,16 @@ export class UsageArgument extends Component<UsageArgumentSignature> {
   }
   <template>
     {{#if this.isDoc}}
-      <tr class='FreestyleUsageArgument'>
+      <tr class='FreestyleUsageArgument' data-test-pretui-usage-arg>
         <td class='FreestyleUsageArgument-name'>
           <span class='u-sig'>{{this.sigilPre}}</span>{{#if @name}}{{@name}}{{/if}}<span
             class='u-sig'
           >{{this.sigilPost}}</span>
-          {{#if @required}}<span class='u-req' title='Required'>*</span>{{/if}}
+          {{#if @required}}<span
+              class='u-req'
+              title='Required'
+              data-test-pretui-usage-arg-required
+            >*</span>{{/if}}
         </td>
         <td class='FreestyleUsageArgument-type'>{{this.typeLabel}}</td>
         <td class='FreestyleUsageArgument-description'>{{@description}}</td>
diff --git a/packages/pretui/components/usage-argument.test.gts b/packages/pretui/components/usage-argument.test.gts
index 4d2eb4c235f..fb702854f2f 100644
--- a/packages/pretui/components/usage-argument.test.gts
+++ b/packages/pretui/components/usage-argument.test.gts
@@ -9,7 +9,7 @@ import { setupCardTest } from '@cardstack/host/tests/helpers';
 import { UsageArgument } from './usage-argument';
 
 function cellTexts(): string[] {
-  return Array.from(document.querySelectorAll('tr.FreestyleUsageArgument td')).map((td) => td.textContent?.replace(/\s+/g, ' ').trim() ?? '');
+  return Array.from(document.querySelectorAll('[data-test-pretui-usage-arg] td')).map((td) => td.textContent?.replace(/\s+/g, ' ').trim() ?? '');
 }
 
 module('Pretui | components/usage-argument', function (hooks) {
@@ -18,13 +18,13 @@ module('Pretui | components/usage-argument', function (hooks) {
   test('doc mode is one API-table row: sigil + name, type, description, default', async function (assert) {
     await render(<template><table><tbody><UsageArgument @name='variant' @type='String' @description='Visual weight' @defaultValue='primary' /></tbody></table></template>);
     assert.deepEqual(cellTexts(), ['@variant', 'String', 'Visual weight', 'primary']);
-    assert.strictEqual(document.querySelector('.u-req'), null);
+    assert.strictEqual(document.querySelector('[data-test-pretui-usage-arg-required]'), null);
   });
 
   test('a missing default reads as a dash, required adds the asterisk, and typeLabel overrides type', async function (assert) {
     await render(<template><table><tbody><UsageArgument @name='items' @type='Array' @typeLabel='Item[]' @required={{true}} /></tbody></table></template>);
     assert.deepEqual(cellTexts(), ['@items *', 'Item[]', '', '—']);
-    assert.strictEqual(document.querySelector('.u-req')?.getAttribute('title'), 'Required');
+    assert.strictEqual(document.querySelector('[data-test-pretui-usage-arg-required]')?.getAttribute('title'), 'Required');
     await render(<template><table><tbody><UsageArgument @name='count' @type='Number' @defaultValue={{0}} /></tbody></table></template>);
     assert.strictEqual(cellTexts()[3], '0', 'zero is a real default, not a missing one');
   });
diff --git a/packages/pretui/components/usage-css-variable.test.gts b/packages/pretui/components/usage-css-variable.test.gts
index 6e521829196..c4894fcfdd1 100644
--- a/packages/pretui/components/usage-css-variable.test.gts
+++ b/packages/pretui/components/usage-css-variable.test.gts
@@ -13,7 +13,7 @@ module('Pretui | components/usage-css-variable', function (hooks) {
 
   test('doc mode is an API row typed CSS with no sigil', async function (assert) {
     await render(<template><table><tbody><UsageCssVariable @name='--pretui-gap' @description='Grid gutter' @defaultValue='8px' /></tbody></table></template>);
-    let cells = Array.from(document.querySelectorAll('tr.FreestyleUsageArgument td')).map((td) => td.textContent?.replace(/\s+/g, ' ').trim());
+    let cells = Array.from(document.querySelectorAll('[data-test-pretui-usage-arg] td')).map((td) => td.textContent?.replace(/\s+/g, ' ').trim());
     assert.deepEqual(cells, ['--pretui-gap', 'CSS', 'Grid gutter', '8px']);
   });
 
@@ -21,8 +21,8 @@ module('Pretui | components/usage-css-variable', function (hooks) {
     let seen: string[] = [];
     let onInput = (v: string) => seen.push(v);
     await render(<template><UsageCssVariable @mode='prop' @name='--pretui-gap' @value='8px' @onInput={{onInput}} /></template>);
-    assert.strictEqual(document.querySelector('.proprow-label')?.textContent?.trim(), '--pretui-gap');
-    let input = document.querySelector('.proprow input') as HTMLInputElement;
+    assert.strictEqual(document.querySelector('[data-test-pretui-prop-row-label]')?.textContent?.trim(), '--pretui-gap');
+    let input = document.querySelector('[data-test-pretui-prop-row] input') as HTMLInputElement;
     assert.strictEqual(input.getAttribute('aria-label'), '--pretui-gap');
     assert.strictEqual(input.value, '8px');
     await fillIn(input, '12px');
diff --git a/packages/pretui/components/usage-object.test.gts b/packages/pretui/components/usage-object.test.gts
index 5184ee6e09e..8b33131829e 100644
--- a/packages/pretui/components/usage-object.test.gts
+++ b/packages/pretui/components/usage-object.test.gts
@@ -13,15 +13,15 @@ module('Pretui | components/usage-object', function (hooks) {
 
   test('doc mode is an API row typed Object', async function (assert) {
     await render(<template><table><tbody><UsageObject @name='item' @description='The record' @required={{true}} /></tbody></table></template>);
-    let cells = Array.from(document.querySelectorAll('tr.FreestyleUsageArgument td')).map((td) => td.textContent?.replace(/\s+/g, ' ').trim());
+    let cells = Array.from(document.querySelectorAll('[data-test-pretui-usage-arg] td')).map((td) => td.textContent?.replace(/\s+/g, ' ').trim());
     assert.deepEqual(cells, ['@item *', 'Object', 'The record', '—']);
   });
 
   test('prop mode shows the value as a labelled JSON tree, or nothing when controls are hidden', async function (assert) {
     const VALUE = { id: 7, tags: ['a', 'b'] };
     await render(<template><UsageObject @mode='prop' @name='item' @value={{VALUE}} @required={{true}} /></template>);
-    assert.strictEqual(document.querySelector('.proprow-label')?.textContent?.replace(/\s+/g, ' ').trim(), 'item *');
-    let tree = document.querySelector('.proprow [data-test-pretui-json-tree]') as HTMLElement;
+    assert.strictEqual(document.querySelector('[data-test-pretui-prop-row-label]')?.textContent?.replace(/\s+/g, ' ').trim(), 'item *');
+    let tree = document.querySelector('[data-test-pretui-prop-row] [data-test-pretui-json-tree]') as HTMLElement;
     assert.ok(tree, 'a JsonTree, not a <pre> of stringified JSON');
     assert.true(tree.textContent?.includes('tags'));
     assert.true(tree.textContent?.includes('7'));
@@ -32,7 +32,7 @@ module('Pretui | components/usage-object', function (hooks) {
 
   test('prop mode with no value still renders the tree, so a call site that passes no @value gets an empty state rather than "undefined"', async function (assert) {
     await render(<template><UsageObject @mode='prop' @name='item' /></template>);
-    let tree = document.querySelector('.proprow [data-test-pretui-json-tree]') as HTMLElement;
+    let tree = document.querySelector('[data-test-pretui-prop-row] [data-test-pretui-json-tree]') as HTMLElement;
     assert.ok(tree);
     assert.false(tree.textContent?.includes('undefined'));
   });
diff --git a/packages/pretui/components/viewport.gts b/packages/pretui/components/viewport.gts
index 067383e4b0e..bc0e0230b0a 100644
--- a/packages/pretui/components/viewport.gts
+++ b/packages/pretui/components/viewport.gts
@@ -175,6 +175,7 @@ export class Viewport extends Component<ViewportSignature> {
             <Switch
               @checked={{this.gutter}}
               @onCheckedChange={{this.setGutter}}
+              data-test-pretui-viewport-gutter
             />
             <span>Gutter</span>
           </label>
@@ -202,11 +203,14 @@ export class Viewport extends Component<ViewportSignature> {
             data-label={{this.frameCaption}}
             data-width={{this.widthLabel}}
             style={{htmlWidth this.frameStyleWidth}}
+            data-test-pretui-artboard
           >
             <div
               class='pretui-artboard-body'
               data-surface={{this.surface}}
               data-gutter={{if this.gutter 'true' 'false'}}
+              data-test-pretui-artboard-body
+              data-test-pretui-viewport-specimen
             >
               {{yield}}
             </div>
@@ -224,11 +228,14 @@ export class Viewport extends Component<ViewportSignature> {
                 class='pretui-artboard'
                 data-bp={{b.bp}}
                 data-label={{b.caption}}
+                data-test-pretui-artboard
               >
                 <div
                   class='pretui-artboard-body'
                   data-surface={{this.surface}}
                   data-gutter={{if this.gutter 'true' 'false'}}
+                  data-test-pretui-artboard-body
+                  data-test-pretui-viewport-specimen
                 >
                   {{yield}}
                 </div>
@@ -236,7 +243,10 @@ export class Viewport extends Component<ViewportSignature> {
             {{/each}}
           </div>
         {{else if (isInline this.mode)}}
-          <p class='pretui-viewport-prose'>The order ledger closes at noon, and
+          <p
+            class='pretui-viewport-prose'
+            data-test-pretui-viewport-specimen
+          >The order ledger closes at noon, and
             {{yield}}
             sits inline with the running text — cap-line trim and optical
             spacing judged mid-paragraph, exactly where machine values live.</p>
@@ -246,6 +256,7 @@ export class Viewport extends Component<ViewportSignature> {
               <div
                 class='pretui-viewport-cell'
                 data-surface={{this.surface}}
+                data-test-pretui-viewport-specimen
               >{{yield}}</div>
             {{/each}}
           </div>
diff --git a/packages/pretui/controls-entry.test.gts b/packages/pretui/controls-entry.test.gts
index aa9dc6e8ba2..eb179bfc02f 100644
--- a/packages/pretui/controls-entry.test.gts
+++ b/packages/pretui/controls-entry.test.gts
@@ -567,7 +567,7 @@ module('controls-entry | Autocomplete', function (hooks) {
       0,
       'the option is a bare overlay; every glyph lives in the aria-hidden face',
     );
-    let face = one('.pretui-ac-face');
+    let face = one('[data-test-pretui-autocomplete-face]');
     assert.strictEqual(face.getAttribute('aria-hidden'), 'true');
   });
 
@@ -669,7 +669,13 @@ module('controls-entry | usage pages', function (hooks) {
       let Demo = PAGES[name] as AnyComponent;
       assert.ok(Demo, name + ' is present in the registry');
       await render(<template><Demo /></template>);
-      assert.ok(one('.FreestyleUsage'), name + ' rendered a FreestyleUsage shell');
+      assert.ok(one('[data-test-pretui-usage]'), name + ' rendered a FreestyleUsage shell');
+      assert.ok(
+        Array.from(root().querySelectorAll('[data-test-pretui-viewport-specimen]')).some(
+          (s) => s.childElementCount > 0 || Boolean(s.textContent?.trim()),
+        ),
+        name + ' shows its example',
+      );
     });
   }
 });
diff --git a/packages/pretui/design-layers.test.gts b/packages/pretui/design-layers.test.gts
index 02a0c795c8c..cc687f06b82 100644
--- a/packages/pretui/design-layers.test.gts
+++ b/packages/pretui/design-layers.test.gts
@@ -722,9 +722,15 @@ module('Pretui | design-layers | demo pages', function (hooks) {
       assert.ok(Demo, name + ' is in the registry');
       await render(<template><Demo /></template>);
       assert.ok(
-        root().querySelector('.FreestyleUsage'),
+        root().querySelector('[data-test-pretui-usage]'),
         name + ' rendered its usage shell',
       );
+      assert.ok(
+        Array.from(root().querySelectorAll('[data-test-pretui-viewport-specimen]')).some(
+          (s) => s.childElementCount > 0 || Boolean(s.textContent?.trim()),
+        ),
+        name + ' shows its example',
+      );
     });
   }
 });
diff --git a/packages/pretui/feedback-toaster.test.gts b/packages/pretui/feedback-toaster.test.gts
index a29e021de18..9cdefdbf5e6 100644
--- a/packages/pretui/feedback-toaster.test.gts
+++ b/packages/pretui/feedback-toaster.test.gts
@@ -441,6 +441,6 @@ module('Pretui | Toaster | usage page', function (hooks) {
     let Page = PAGES['Toaster'];
     assert.ok(Page, 'the page is in the registry');
     await render(<template><Page /></template>);
-    assert.dom('.FreestyleUsage').exists('the page mounted');
+    assert.dom('[data-test-pretui-usage]').exists('the page mounted');
   });
 });
diff --git a/packages/pretui/foundations-render.test.gts b/packages/pretui/foundations-render.test.gts
index cce3eb9af93..a280a7d6868 100644
--- a/packages/pretui/foundations-render.test.gts
+++ b/packages/pretui/foundations-render.test.gts
@@ -27,7 +27,13 @@ module('Pretui | foundation usage pages', function (hooks) {
     test(`${name} mounts with representative data`, async function (assert) {
       let Demo = PAGES[name] as AnyComponent;
       await render(<template><Demo /></template>);
-      assert.ok(document.querySelector('.FreestyleUsage'), `${name} rendered`);
+      assert.ok(document.querySelector('[data-test-pretui-usage]'), `${name} rendered`);
+      assert.ok(
+        Array.from(document.querySelectorAll('[data-test-pretui-viewport-specimen]')).some(
+          (s) => s.childElementCount > 0 || Boolean(s.textContent?.trim()),
+        ),
+        `${name} shows its example`,
+      );
       assert.notOk(
         document.body.textContent?.includes('There is no JSON to display.'),
         `${name} has no empty object fixture`,
diff --git a/packages/pretui/internal/freestyle.gts b/packages/pretui/internal/freestyle.gts
index c83353c5595..b4e4c6c3b36 100644
--- a/packages/pretui/internal/freestyle.gts
+++ b/packages/pretui/internal/freestyle.gts
@@ -29,8 +29,8 @@ interface PropRowSignature {
 }
 
 export const PropRow: TemplateOnlyComponent<PropRowSignature> = <template>
-  <div class='proprow' ...attributes>
-    <span class='proprow-label'>
+  <div class='proprow' data-test-pretui-prop-row ...attributes>
+    <span class='proprow-label' data-test-pretui-prop-row-label>
       {{@label}}
       {{#if @required}}<span class='proprow-req'>*</span>{{/if}}
     </span>
diff --git a/packages/pretui/media-library.test.gts b/packages/pretui/media-library.test.gts
index 3d3b800eb6d..3c2e834d088 100644
--- a/packages/pretui/media-library.test.gts
+++ b/packages/pretui/media-library.test.gts
@@ -588,9 +588,15 @@ module('Pretui | media-library | demo pages', function (hooks) {
       assert.ok(Demo, name + ' is in the registry');
       await render(<template><Demo /></template>);
       assert.ok(
-        root().querySelector('.FreestyleUsage'),
+        root().querySelector('[data-test-pretui-usage]'),
         name + ' rendered its usage shell',
       );
+      assert.ok(
+        Array.from(root().querySelectorAll('[data-test-pretui-viewport-specimen]')).some(
+          (s) => s.childElementCount > 0 || Boolean(s.textContent?.trim()),
+        ),
+        name + ' shows its example',
+      );
     });
   }
 });
diff --git a/packages/pretui/menu-context.test.gts b/packages/pretui/menu-context.test.gts
index b33af3d238f..02818448dd5 100644
--- a/packages/pretui/menu-context.test.gts
+++ b/packages/pretui/menu-context.test.gts
@@ -422,6 +422,6 @@ module('Pretui | ContextMenu | usage page', function (hooks) {
     let Page = PAGES['ContextMenu'];
     assert.ok(Page, 'the page is in the registry');
     await render(<template><Page /></template>);
-    assert.dom('.FreestyleUsage').exists('the page mounted');
+    assert.dom('[data-test-pretui-usage]').exists('the page mounted');
   });
 });
diff --git a/packages/pretui/overlay-confirm.test.gts b/packages/pretui/overlay-confirm.test.gts
index 3fe784ac410..9058a83f5d5 100644
--- a/packages/pretui/overlay-confirm.test.gts
+++ b/packages/pretui/overlay-confirm.test.gts
@@ -607,20 +607,20 @@ module('Pretui | DEMOS_OVERLAY_CONFIRM | usage pages', function (hooks) {
     let Page = PAGES['AlertDialog'];
     assert.ok(Page, 'the page is in the registry');
     await render(<template><Page /></template>);
-    assert.dom('.FreestyleUsage').exists('the page mounted');
+    assert.dom('[data-test-pretui-usage]').exists('the page mounted');
   });
 
   test('the Popconfirm usage page renders', async function (assert) {
     let Page = PAGES['Popconfirm'];
     assert.ok(Page, 'the page is in the registry');
     await render(<template><Page /></template>);
-    assert.dom('.FreestyleUsage').exists('the page mounted');
+    assert.dom('[data-test-pretui-usage]').exists('the page mounted');
   });
 
   test('the HoverCard usage page renders', async function (assert) {
     let Page = PAGES['HoverCard'];
     assert.ok(Page, 'the page is in the registry');
     await render(<template><Page /></template>);
-    assert.dom('.FreestyleUsage').exists('the page mounted');
+    assert.dom('[data-test-pretui-usage]').exists('the page mounted');
   });
 });
diff --git a/packages/pretui/pretui-component.gts b/packages/pretui/pretui-component.gts
index a71ba9e6504..07cf0f71c77 100644
--- a/packages/pretui/pretui-component.gts
+++ b/packages/pretui/pretui-component.gts
@@ -132,8 +132,8 @@ class NoteComposer extends GlimmerComponent<NoteComposerSignature> {
           @tone='primary'
           @size='s'
           @disabled={{this.draftEmpty}}
-          data-test-pretui-note-save
           {{on 'click' this.save}}
+          data-test-pretui-note-save
         >Stick it</Button>
       </div>
     </div>
@@ -467,7 +467,7 @@ export class PretUISpec extends Spec {
       >
       <article class='page' data-demo-policy={{this.demoPolicy}}>
         <nav class='wb-topbar'>
-          <div class='wb-crumb'>
+          <div class='wb-crumb' data-test-pretui-spec-crumb>
             <span class='wb-crumb-root'>Pretui</span>
             <span class='wb-sep'>/</span>
             <span class='wb-crumb-dim'>{{if
@@ -514,8 +514,8 @@ export class PretUISpec extends Spec {
                       type='button'
                       class='note-add'
                       aria-expanded={{if open 'true' 'false'}}
-                      data-test-pretui-note-add
                       {{on 'click' toggle}}
+                      data-test-pretui-note-add
                     >+ Note</button>
                   </:trigger>
                   <:default as |close|>
@@ -537,8 +537,8 @@ export class PretUISpec extends Spec {
                     <button
                       type='button'
                       class='note'
-                      data-test-pretui-note
                       {{on 'click' (fn this.openNote n.id)}}
+                      data-test-pretui-note
                     >
                       <span class='note-text'>{{if
                           n.note
diff --git a/packages/pretui/pretui-component.test.gts b/packages/pretui/pretui-component.test.gts
index e60d96927e4..7a80b614b7d 100644
--- a/packages/pretui/pretui-component.test.gts
+++ b/packages/pretui/pretui-component.test.gts
@@ -21,8 +21,8 @@ module('Pretui | PretUISpec', function (hooks) {
   test('renders the usage page and examples it loads', async function (assert) {
     let model = specModel('Button');
     await render(<template><Isolated @model={{model}} /></template>);
-    await waitFor('[data-demo-policy="included"] .FreestyleUsage');
-    assert.dom('[data-demo-policy="included"] .FreestyleUsage').exists();
+    await waitFor('[data-demo-policy="included"] [data-test-pretui-usage]');
+    assert.dom('[data-demo-policy="included"] [data-test-pretui-usage]').exists();
     await waitFor('[data-test-pretui-examples]');
     assert.dom('[data-test-pretui-examples]').containsText('Examples');
   });
@@ -30,8 +30,8 @@ module('Pretui | PretUISpec', function (hooks) {
   test('a page in a shared usage module renders too', async function (assert) {
     let model = specModel('EmailInput');
     await render(<template><Isolated @model={{model}} /></template>);
-    await waitFor('[data-demo-policy="included"] .FreestyleUsage');
-    assert.dom('[data-demo-policy="included"] .FreestyleUsage').exists();
+    await waitFor('[data-demo-policy="included"] [data-test-pretui-usage]');
+    assert.dom('[data-demo-policy="included"] [data-test-pretui-usage]').exists();
   });
 
   test('a component with no usage page says so', async function (assert) {
@@ -46,8 +46,8 @@ module('Pretui | PretUISpec', function (hooks) {
   test('a planned entry that has a page shows it', async function (assert) {
     let model = specModel('Button', 'planned');
     await render(<template><Isolated @model={{model}} /></template>);
-    await waitFor('[data-demo-policy="included"] .FreestyleUsage');
-    assert.dom('[data-demo-policy="included"] .FreestyleUsage').exists();
+    await waitFor('[data-demo-policy="included"] [data-test-pretui-usage]');
+    assert.dom('[data-demo-policy="included"] [data-test-pretui-usage]').exists();
   });
 
   test('a Runtime entry without a page is excluded', async function (assert) {
@@ -78,8 +78,8 @@ module('Pretui | PretUISpec', function (hooks) {
   test('the breadcrumb names the kit without linking to a catalog card this package does not ship', async function (assert) {
     let model = specModel('Button');
     await render(<template><Isolated @model={{model}} /></template>);
-    assert.dom('.wb-crumb').containsText('Pretui');
-    assert.dom('.wb-crumb button').doesNotExist('no navigation to a card that is not here');
+    assert.dom('[data-test-pretui-spec-crumb]').containsText('Pretui');
+    assert.dom('[data-test-pretui-spec-crumb] button').doesNotExist('no navigation to a card that is not here');
   });
 
   test('a note adopts from the PretuiNote module in this package, wherever the Spec lives', async function (assert) {
diff --git a/packages/pretui/pretui-note.gts b/packages/pretui/pretui-note.gts
index a4ac13c0265..2a8c1691b7d 100644
--- a/packages/pretui/pretui-note.gts
+++ b/packages/pretui/pretui-note.gts
@@ -107,8 +107,8 @@ export class PretuiNote extends CardDef {
           <button
             type='button'
             class='note-target'
-            data-test-pretui-note-target
             {{on 'click' this.openTarget}}
+            data-test-pretui-note-target
           >
             On
             <strong>{{if
diff --git a/packages/pretui/reading-listing.test.gts b/packages/pretui/reading-listing.test.gts
index 9ba48218811..40748c63807 100644
--- a/packages/pretui/reading-listing.test.gts
+++ b/packages/pretui/reading-listing.test.gts
@@ -524,7 +524,7 @@ module('Pretui | reading-listing', function (hooks) {
           @onExpandedChange={{knobs.onExpandedChange}}
         >
           <:expanded as |row|>
-            <p class='t-detail'>{{row.place}}</p>
+            <p data-test-detail>{{row.place}}</p>
           </:expanded>
         </DataTable>
       </template>,
@@ -544,7 +544,7 @@ module('Pretui | reading-listing', function (hooks) {
     let controls = toggle.getAttribute('aria-controls') as string;
     let detail = tableRoot().querySelector('#' + controls) as HTMLElement;
     assert.ok(detail, 'aria-controls resolves to a real element');
-    assert.dom(detail.querySelector('.t-detail')).hasText('Uji');
+    assert.dom(detail.querySelector('[data-test-detail]')).hasText('Uji');
     assert.strictEqual(
       detail.querySelector('td')?.getAttribute('colspan'),
       '5',
@@ -762,11 +762,11 @@ module('Pretui | reading-listing', function (hooks) {
     await render(
       <template>
         <List @items={{LOTS}} @key={{rowKey}} @rowLabel={{rowLabel}} @selectionMode={{knobs.selectionMode}} @onActivate={{knobs.onActivate}}>
-          <:item as |row|><span class='t-tea'>{{row.tea}}</span></:item>
+          <:item as |row|><span data-test-tea>{{row.tea}}</span></:item>
         </List>
       </template>,
     );
-    await click(listRoot().querySelectorAll('.t-tea')[1] as HTMLElement);
+    await click(listRoot().querySelectorAll('[data-test-tea]')[1] as HTMLElement);
     assert.deepEqual(knobs.activations, ['B-2'], 'the row text activates');
     await click(listRoot().querySelectorAll('[data-test-pretui-list-select]')[0] as HTMLElement);
     assert.deepEqual(knobs.activations, ['B-2'], 'the radio does not');
@@ -837,7 +837,7 @@ module('Pretui | reading-listing', function (hooks) {
     );
     assert.deepEqual(terms, ['Lot', 'Tea', 'Note', 'Empty']);
     let pairs = Array.from(
-      root.querySelectorAll('.pretui-desc-pair'),
+      root.querySelectorAll('[data-test-pretui-descriptions-pair]'),
     ) as HTMLElement[];
     assert.strictEqual(pairs[2]?.getAttribute('data-span'), 'fill');
     assert.strictEqual(root.getAttribute('data-bordered'), 'true');
@@ -853,15 +853,15 @@ module('Pretui | reading-listing', function (hooks) {
     await render(
       <template>
         <Descriptions @items={{items}} @colon={{true}}>
-          <:value as |item|><b class='t-v'>{{item.label}} block</b></:value>
+          <:value as |item|><b data-test-value>{{item.label}} block</b></:value>
         </Descriptions>
       </template>,
     );
     let root = document.querySelector(
       '[data-test-pretui-descriptions]',
     ) as HTMLElement;
-    assert.dom(root.querySelector('.t-v')).hasText('Lot block');
-    let colon = root.querySelector('.pretui-desc-colon') as HTMLElement;
+    assert.dom(root.querySelector('[data-test-value]')).hasText('Lot block');
+    let colon = root.querySelector('[data-test-pretui-descriptions-colon]') as HTMLElement;
     assert.strictEqual(
       colon.getAttribute('aria-hidden'),
       'true',
@@ -935,7 +935,7 @@ module('Pretui | reading-listing | usage pages', function (hooks) {
       assert.ok(Page, name + ' present');
       await render(<template><Page /></template>);
       assert.ok(
-        document.querySelector('.FreestyleUsage'),
+        document.querySelector('[data-test-pretui-usage]'),
         name + ' rendered a FreestyleUsage shell',
       );
     });
diff --git a/packages/pretui/scripts/usage-proof.mjs b/packages/pretui/scripts/usage-proof.mjs
index d5e60fd6519..7e4a09101ad 100644
--- a/packages/pretui/scripts/usage-proof.mjs
+++ b/packages/pretui/scripts/usage-proof.mjs
@@ -83,7 +83,13 @@ module('Pretui | usage pages', function (hooks) {
         let Demo = registry[name] as AnyComponent;
         assert.ok(Demo, \`\${name} present\`);
         await render(<template><Demo /></template>);
-        assert.ok(document.querySelector('.FreestyleUsage'), \`\${name} rendered a FreestyleUsage shell\`);
+        assert.ok(document.querySelector('[data-test-pretui-usage]'), \`\${name} rendered a FreestyleUsage shell\`);
+        assert.ok(
+          Array.from(document.querySelectorAll('[data-test-pretui-viewport-specimen]')).some(
+            (s) => s.childElementCount > 0 || Boolean(s.textContent?.trim()),
+          ),
+          \`\${name} shows its example\`,
+        );
       });
     }
   }
diff --git a/packages/pretui/structure-flow.test.gts b/packages/pretui/structure-flow.test.gts
index 275df219763..8e7442db6d4 100644
--- a/packages/pretui/structure-flow.test.gts
+++ b/packages/pretui/structure-flow.test.gts
@@ -834,7 +834,7 @@ module('Pretui | structure-flow | usage pages', function (hooks) {
       assert.ok(Demo, name + ' is present in the registry');
       await render(<template><Demo /></template>);
       assert.ok(
-        document.querySelector('.FreestyleUsage'),
+        document.querySelector('[data-test-pretui-usage]'),
         name + ' rendered a FreestyleUsage shell',
       );
     });
diff --git a/packages/pretui/usage-pages.test.gts b/packages/pretui/usage-pages.test.gts
index 838fdba4ba4..665ee5e326d 100644
--- a/packages/pretui/usage-pages.test.gts
+++ b/packages/pretui/usage-pages.test.gts
@@ -592,7 +592,13 @@ module('Pretui | usage pages', function (hooks) {
         let Demo = registry[name] as AnyComponent;
         assert.ok(Demo, `${name} present`);
         await render(<template><Demo /></template>);
-        assert.ok(document.querySelector('.FreestyleUsage'), `${name} rendered a FreestyleUsage shell`);
+        assert.ok(document.querySelector('[data-test-pretui-usage]'), `${name} rendered a FreestyleUsage shell`);
+        assert.ok(
+          Array.from(document.querySelectorAll('[data-test-pretui-viewport-specimen]')).some(
+            (s) => s.childElementCount > 0 || Boolean(s.textContent?.trim()),
+          ),
+          `${name} shows its example`,
+        );
       });
     }
   }
diff --git a/packages/pretui/viewport.test.gts b/packages/pretui/viewport.test.gts
index a59a264f6e0..f11d8d31e53 100644
--- a/packages/pretui/viewport.test.gts
+++ b/packages/pretui/viewport.test.gts
@@ -7,13 +7,12 @@ import { Viewport } from './components/viewport';
 // SegmentedControl is a radiogroup over native <input type='radio'>. Click
 // the input: a synthetic click on the label would rely on label
 // activation forwarding, and the input is the thing that actually changes.
-function segButton(label: string): HTMLElement {
-  let labels = Array.from(
-    document.querySelectorAll('[data-test-pretui-viewport] .pretui-seg label'),
-  );
-  let target = labels.find((b) => b.textContent?.trim() === label);
-  if (!target) throw new Error(`no viewport segment labeled ${label}`);
-  return target.querySelector('input') as HTMLElement;
+function segButton(mode: string): HTMLElement {
+  let target = document.querySelector(
+    `[data-test-pretui-viewport] [data-test-pretui-segmented-option='${mode}']`,
+  ) as HTMLElement | null;
+  if (!target) throw new Error(`no viewport segment for ${mode}`);
+  return target;
 }
 
 module('Pretui | Viewport artboard', function (hooks) {
@@ -25,14 +24,14 @@ module('Pretui | Viewport artboard', function (hooks) {
     </template>);
 
     let artboard = () =>
-      document.querySelector('.pretui-artboard') as HTMLElement;
+      document.querySelector('[data-test-pretui-artboard]') as HTMLElement;
     assert.strictEqual(
       artboard().getAttribute('data-width'),
       'fill',
       'starts at fill',
     );
 
-    await click(segButton('Tablet'));
+    await click(segButton('tablet'));
     assert.strictEqual(
       artboard().style.width,
       '768px',
@@ -44,7 +43,7 @@ module('Pretui | Viewport artboard', function (hooks) {
       'caption carries name and true width',
     );
 
-    await click(segButton('Phone'));
+    await click(segButton('phone'));
     assert.strictEqual(artboard().style.width, '375px', 'phone is 375px');
   });
 
@@ -52,8 +51,8 @@ module('Pretui | Viewport artboard', function (hooks) {
     await render(<template>
       <Viewport @label='Probe'><span>content</span></Viewport>
     </template>);
-    await click(segButton('3-up'));
-    let boards = document.querySelectorAll('.pretui-bp-row .pretui-artboard');
+    await click(segButton('bp'));
+    let boards = document.querySelectorAll('[data-test-pretui-artboard]');
     assert.strictEqual(boards.length, 3, 'three artboards');
     assert.deepEqual(
       Array.from(boards).map((b) => b.getAttribute('data-label')),
@@ -67,29 +66,15 @@ module('Pretui | Viewport artboard', function (hooks) {
       <Viewport @label='Probe'><span>content</span></Viewport>
     </template>);
     let body = () =>
-      document.querySelector('.pretui-artboard-body') as HTMLElement;
+      document.querySelector('[data-test-pretui-artboard-body]') as HTMLElement;
     assert.strictEqual(body().getAttribute('data-surface'), 'background');
     assert.strictEqual(body().getAttribute('data-gutter'), 'true');
 
-    let gutterSwitch = document.querySelector(
-      '.pretui-viewport-gutter [data-test-pretui-switch]',
-    ) as HTMLElement | null;
-    if (gutterSwitch) {
-      await click(gutterSwitch);
-      assert.strictEqual(
-        body().getAttribute('data-gutter'),
-        'false',
-        'gutter toggles off',
-      );
-    } else {
-      let anySwitch = document.querySelector(
-        '.pretui-viewport-gutter button',
-      ) as HTMLElement | null;
-      assert.ok(anySwitch, 'gutter switch rendered');
-      if (anySwitch) {
-        await click(anySwitch);
-        assert.strictEqual(body().getAttribute('data-gutter'), 'false');
-      }
-    }
+    await click('[data-test-pretui-viewport-gutter]');
+    assert.strictEqual(
+      body().getAttribute('data-gutter'),
+      'false',
+      'gutter toggles off',
+    );
   });
 });

From fabdb19f5469bab34847644f93c513521b961a71 Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Wed, 7 Oct 2026 17:54:10 -0400
Subject: [PATCH 02/30] Put Toast and Snackbar on the theme contract and drop
 Toast's own stacking tier

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/components/snackbar.usage.gts |  5 ++-
 packages/pretui/components/toast.gts          | 39 ++++++++++---------
 packages/pretui/components/toast.md           |  4 +-
 packages/pretui/components/toast.usage.gts    |  3 +-
 packages/pretui/pretui-css.gts                |  2 +
 5 files changed, 30 insertions(+), 23 deletions(-)

diff --git a/packages/pretui/components/snackbar.usage.gts b/packages/pretui/components/snackbar.usage.gts
index c25c4b8b905..99093e83988 100644
--- a/packages/pretui/components/snackbar.usage.gts
+++ b/packages/pretui/components/snackbar.usage.gts
@@ -1,6 +1,7 @@
 // Pretui — Snackbar usage page.
 import type { TemplateOnlyComponent } from '@ember/component/template-only';
 import { FreestyleUsage } from './freestyle-usage';
+import CheckIcon from '@cardstack/boxel-icons/check';
 import { Button } from './button';
 import { Snackbar } from './snackbar';
 
@@ -12,8 +13,8 @@ const SnackbarUsage: TemplateOnlyComponent = <template>
   >
     <:example>
       <Snackbar @title='Lot saved' @message='B-103 is ready for review'>
-        <:icon>✓</:icon>
-        <:action><Button @variant='ghost'>Review</Button></:action>
+        <:icon><CheckIcon width='14' height='14' aria-hidden='true' /></:icon>
+        <:action><Button @tone='neutral' @appearance='plain'>Review</Button></:action>
       </Snackbar>
     </:example>
     <:api as |Args|>
diff --git a/packages/pretui/components/toast.gts b/packages/pretui/components/toast.gts
index 7b4e51fae83..1d238dc4b24 100644
--- a/packages/pretui/components/toast.gts
+++ b/packages/pretui/components/toast.gts
@@ -24,32 +24,35 @@ export const Toast: TemplateOnlyComponent<ToastSignature> = <template>
           class='pretui-toast-msg'
         >{{@description}}</div>{{/if}}
     </div>
-    {{#if (has-block 'action')}}<div class='pretui-toast-action'>{{yield to='action'}}</div>{{/if}}
+    {{#if (has-block 'action')}}<div class='pretui-toast-action'>{{yield
+          to='action'
+        }}</div>{{/if}}
   </div>
   <style scoped>
     @layer PretComponent {
       .pretui-toast {
+        --pretui-toast-max-w: 22.5rem;
+
         display: flex;
         align-items: center;
-        gap: 9px;
-        /* kit stacking scale (pretui-css.gts): a toast reports something that
-           just happened and must stay readable over whatever is open, so it is
-           the one tier deliberately above `dialog`. `relative` is what makes
-           the z-index apply — the toast is otherwise in flow and its consumer
-           owns where it sits. */
-        position: relative;
-        z-index: var(--pretui-z-toast, 100);
-        background: var(--popover);
-        border-radius: 10px;
-        box-shadow: var(--pretui-shadow-raised, 0 0 0 1px var(--border), 0 2px 10px rgb(0 0 0 / 0.08));
-        padding: 7px 10px;
-        font-size: var(--text-ui-md, 12.5px);
+        gap: var(--boxel-sp-xs);
+        /* no stacking tier of its own: the toast is in flow, so whatever
+           positions it (Toaster's fixed region, or the host's) owns its
+           z-index; one here would paint an in-flow toast over sticky chrome */
+        background-color: var(--popover);
+        color: var(--popover-foreground);
+        border-radius: var(--boxel-border-radius);
+        box-shadow:
+          0 0 0 1px var(--border),
+          var(--shadow-md);
+        padding: var(--boxel-sp-2xs) var(--boxel-sp-xs);
+        font-size: var(--boxel-font-size-xs);
         width: max-content;
-        max-width: 360px;
+        max-width: var(--pretui-toast-max-w);
       }
       .pretui-toast-body {
         display: grid;
-        gap: 1px;
+        gap: var(--boxel-sp-6xs);
         min-width: 0;
       }
       .pretui-toast-title {
@@ -57,10 +60,10 @@ export const Toast: TemplateOnlyComponent<ToastSignature> = <template>
       }
       .pretui-toast-msg {
         color: var(--muted-foreground);
-        font-size: var(--text-ui-sm, 11.5px);
+        font-size: var(--boxel-caption-font-size);
       }
       .pretui-toast-action {
-        margin-left: 8px;
+        margin-inline-start: var(--boxel-sp-xs);
         flex: none;
       }
     }
diff --git a/packages/pretui/components/toast.md b/packages/pretui/components/toast.md
index d27acfea868..8ad6ab1dd16 100644
--- a/packages/pretui/components/toast.md
+++ b/packages/pretui/components/toast.md
@@ -14,7 +14,7 @@ That is all. There is no `duration`, no `placement`, no `variant`, no close butt
 
 **The omissions are the design.** A toast stack is a host concern: it needs a single top-layer region, an ordering policy, a pause-on-hover rule, and one shared live region — and none of that belongs to a component that a card might render three of. Pretui ships the card here and the stack as **Toaster**, which draws its own item so the clock, roles and controls are one implementation. The upside is that a Toast composes into anything; the downside is that using it correctly requires you to build the parts that are hard.
 
-`width: max-content` with a 360px cap means a toast is as wide as its content and no wider, which is what makes a stack of them read as a column of distinct messages rather than a wall.
+`width: max-content` with a 22.5rem cap (`--pretui-toast-max-w`) means a toast is as wide as its content and no wider, which is what makes a stack of them read as a column of distinct messages rather than a wall.
 
 ## Prior art
 
@@ -43,7 +43,7 @@ Practical guidance: render Toast inside a host-owned region that carries the liv
 
 ## Theming
 
-`--popover` (surface), `--pretui-shadow-raised`, `--border`, `--foreground` (title), `--muted-foreground` (message), `--text-ui-md`. The 10px radius, 7px/10px padding, 9px gap and 360px max width are fixed.
+`--popover` / `--popover-foreground` (surface and title), `--muted-foreground` (message), `--border` and `--shadow-md` (edge and lift), `--boxel-border-radius`, the `--boxel-sp-*` spacing scale, and `--boxel-font-size-xs` / `--boxel-caption-font-size` (title and message). `--pretui-toast-max-w` sets the width cap.
 
 Because the surface is `--popover` rather than `--card`, a toast matches **Menu** and **Popover** rather than **Panel** — the "floating above" vocabulary. A season must keep `--popover` distinct from the page background, since the only other separation is a shadow, and shadows disappear on dark surfaces.
 
diff --git a/packages/pretui/components/toast.usage.gts b/packages/pretui/components/toast.usage.gts
index 13e888d1e8f..f2e13910397 100644
--- a/packages/pretui/components/toast.usage.gts
+++ b/packages/pretui/components/toast.usage.gts
@@ -1,12 +1,13 @@
 // Pretui — Toast usage page.
 import type { TemplateOnlyComponent } from '@ember/component/template-only';
 import { FreestyleUsage } from './freestyle-usage';
+import CheckIcon from '@cardstack/boxel-icons/check';
 import { Button } from './button';
 import { Toast } from './toast';
 
 const ToastUsage: TemplateOnlyComponent = <template>
     <FreestyleUsage @name='Toast' @description='A brief in-flow status receipt. Positioning and lifetime belong to its host; title, message and action remain ordinary content.' @source='<Toast @title="Lot saved" @message="B-103 is ready for review">…</Toast>'>
-      <:example><Toast @title='Lot saved' @message='B-103 is ready for review'><:icon>✓</:icon><:action><Button @variant='ghost'>Review</Button></:action></Toast></:example>
+      <:example><Toast @title='Lot saved' @message='B-103 is ready for review'><:icon><CheckIcon width='14' height='14' aria-hidden='true' /></:icon><:action><Button @tone='neutral' @appearance='plain'>Review</Button></:action></Toast></:example>
       <:api as |Args|><Args.String @name='title' @value='Lot saved' /><Args.String @name='message' @value='B-103 is ready for review' /><Args.Yield @name='icon' /><Args.Yield @name='action' /></:api>
     </FreestyleUsage>
   </template>;
diff --git a/packages/pretui/pretui-css.gts b/packages/pretui/pretui-css.gts
index 88dd22199ca..8ab3b32e263 100644
--- a/packages/pretui/pretui-css.gts
+++ b/packages/pretui/pretui-css.gts
@@ -70,6 +70,8 @@
 //   toast   100  the last word. A toast reports something that just happened
 //                and must stay readable over whatever is open, including a
 //                modal — so it is the only tier deliberately above `dialog`.
+//                Toaster's fixed region takes it; a bare Toast is in flow and
+//                takes no tier, so whatever positions one owns its z-index.
 //
 // The numbers are gapped so a host can interleave its own chrome (a global
 // nav at 65, an assistant panel at 85) without editing Pretui.

From b7a7cd3f8844e78fac50cc38e29a30cdf9e180e1 Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Wed, 7 Oct 2026 17:54:12 -0400
Subject: [PATCH 03/30] Give Chip a tone with an ink ring, and let StatusChip
 pass it through

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/components/chip.gts        | 102 ++++++++++++++++++---
 packages/pretui/components/chip.md         |  18 ++--
 packages/pretui/components/chip.usage.gts  |  36 ++++++--
 packages/pretui/components/status-chip.gts |  22 ++++-
 packages/pretui/components/status-chip.md  |   9 +-
 packages/pretui/ink.test.gts               |  30 ++++++
 6 files changed, 179 insertions(+), 38 deletions(-)

diff --git a/packages/pretui/components/chip.gts b/packages/pretui/components/chip.gts
index 43eed33496f..693fab0c958 100644
--- a/packages/pretui/components/chip.gts
+++ b/packages/pretui/components/chip.gts
@@ -1,9 +1,23 @@
-// Pretui — Chip: a compact label in one hue (Law 2: one hue in, complete treatment out).
+// Pretui — Chip: a compact label, muted or outlined in a tone; @hue colors the dot.
 import Component from '@glimmer/component';
 import { hueStyle } from '../internal/ink';
+import {
+  PRETUI_TONES,
+  resolveTone,
+  type PretuiTone,
+  type PretuiToneArg,
+} from '../pretui-primitives';
 
 export interface ChipSignature {
-  Args: { label?: string; hue?: string; dot?: boolean };
+  Args: {
+    label?: string;
+    /** the dot's color */
+    hue?: string;
+    /** neutral (the default) is the muted pill; any other tone is outlined in
+     * that tone, with its -ink as the text */
+    tone?: PretuiToneArg;
+    dot?: boolean;
+  };
   Blocks: { default: [] };
   Element: HTMLSpanElement;
 }
@@ -12,36 +26,94 @@ export class Chip extends Component<ChipSignature> {
   get showDot() {
     return this.args.dot ?? true;
   }
+  get tone(): PretuiTone {
+    return resolveTone(this.args.tone, PRETUI_TONES, 'neutral');
+  }
   get style() {
     return hueStyle('--pretui-chip-hue', this.args.hue);
   }
   <template>
-    <span class='pretui-chip' style={{this.style}} data-test-pretui-chip ...attributes>
+    <span
+      class='pretui-chip'
+      style={{this.style}}
+      data-tone={{this.tone}}
+      data-test-pretui-chip
+      ...attributes
+    >
       {{#if this.showDot}}<span class='pretui-chip-dot'></span>{{/if}}
       {{#if @label}}{{@label}}{{else}}{{yield}}{{/if}}
     </span>
     <style scoped>
       @layer PretComponent {
         .pretui-chip {
+          --pretui-chip-hue: var(--muted-foreground);
+          --pretui-chip-height: 1.125rem;
+          --pretui-chip-dot-size: 0.3125rem;
+
           display: inline-flex;
           align-items: center;
-          gap: 5px;
-          height: 18px;
-          padding: 0 7px;
-          border-radius: var(--radius-chip, 6px);
-          font-size: var(--text-ui-xs, 11px);
+          gap: var(--boxel-sp-3xs);
+          height: var(--pretui-chip-height);
+          padding: 0 var(--boxel-sp-2xs);
+          border-radius: var(--boxel-border-radius-xs);
+          font-size: var(--boxel-font-size-2xs);
           font-weight: 500;
-          letter-spacing: var(--track-ui, 0.01em);
+          letter-spacing: var(--boxel-lsp-xs);
           white-space: nowrap;
-          background: color-mix(in oklch, var(--pretui-chip-hue, var(--muted-foreground)) var(--pretui-chip-mix, 20%), var(--card));
-          color: color-mix(in oklch, var(--foreground) var(--pretui-ink-mix, 34%), var(--pretui-chip-hue, var(--muted-foreground)));
-          box-shadow: 0 0 0 1px color-mix(in oklch, var(--pretui-chip-hue, var(--muted-foreground)) 45%, var(--border));
+          /* --pretui-chip-mix / --pretui-ink-mix are legacy knobs catalog chips
+             still set: 0% / 100% (unset) resolve to plain --muted / --foreground */
+          background-color: color-mix(
+            in oklch,
+            var(--pretui-chip-hue) var(--pretui-chip-mix, 0%),
+            var(--muted)
+          );
+          color: color-mix(
+            in oklch,
+            var(--foreground) var(--pretui-ink-mix, 100%),
+            var(--pretui-chip-hue)
+          );
+        }
+        /* a toned chip is outlined on --card: its -ink draws the text and the
+           ring (the fill hue misses 3:1 as a ring), the dot takes the tone */
+        .pretui-chip:not([data-tone='neutral']) {
+          background-color: var(--card);
+          box-shadow: inset 0 0 0 1px currentColor;
+        }
+        .pretui-chip[data-tone='primary'] {
+          --pretui-chip-hue: var(--primary);
+
+          color: var(--primary-ink);
+        }
+        .pretui-chip[data-tone='info'] {
+          --pretui-chip-hue: var(--info);
+
+          color: var(--info-ink);
+        }
+        .pretui-chip[data-tone='success'] {
+          --pretui-chip-hue: var(--success);
+
+          color: var(--success-ink);
+        }
+        .pretui-chip[data-tone='warning'] {
+          --pretui-chip-hue: var(--warning);
+
+          color: var(--warning-ink);
+        }
+        .pretui-chip[data-tone='danger'] {
+          --pretui-chip-hue: var(--destructive);
+
+          color: var(--destructive-ink);
+        }
+        .pretui-chip[data-tone='attention'] {
+          --pretui-chip-hue: var(--attention);
+
+          color: var(--attention-ink);
         }
         .pretui-chip-dot {
-          width: 5px;
-          height: 5px;
+          width: var(--pretui-chip-dot-size);
+          height: var(--pretui-chip-dot-size);
           border-radius: 50%;
-          background: var(--pretui-chip-hue, var(--muted-foreground));
+          background-color: var(--pretui-chip-hue);
           flex: none;
         }
       }
diff --git a/packages/pretui/components/chip.md b/packages/pretui/components/chip.md
index a092695a790..eb1c6c88786 100644
--- a/packages/pretui/components/chip.md
+++ b/packages/pretui/components/chip.md
@@ -1,25 +1,23 @@
 ## What it is
 
-A small tinted pill for a categorical value: a status, a tag, a label. It is display only — no click, no dismiss, no selection. Use it wherever a value is a _category_ rather than a number or a name. If the hue should be derived from the value automatically, use **StatusChip**, which is this component with `statusHue()` applied. If the value is machine-readable (an id, a hash, a path), use **Token**, which is the mono jewelry treatment. If the pill filters a list, use **FilterChips**. If it represents a record, **RecordPill**.
+A small pill for a categorical value: a status, a tag, a label. It is display only — no click, no dismiss, no selection. Use it wherever a value is a _category_ rather than a number or a name. If the dot's hue should be derived from the value automatically, use **StatusChip**, which is this component with `statusHue()` applied. If the value is machine-readable (an id, a hash, a path), use **Token**, which is the mono jewelry treatment. If the pill filters a list, use **FilterChips**. If it represents a record, **RecordPill**.
 
 ## The contract
 
 ```
-@label?, @hue?, @dot? (default true)
+@label?, @tone? (default neutral), @hue?, @dot? (default true)
 <:default>   — used when @label is absent
 ```
 
-**One hue in, a complete treatment out.** This is the kit's Law 2 and Chip is its purest expression: `@hue` sets a single custom property and the stylesheet derives everything with `color-mix` — a 20% tint over `--card` for the fill, a 45% mix with `--border` for the hairline, a 34% mix with `--foreground` for the ink, and the hue neat for the dot. There are no variants and no colour enum. Passing any CSS colour, or any `var(--chart-3)`, produces a complete, coherent chip.
+**Tone outlines, hue colors the dot.** A neutral chip (the default) is the theme's `--muted` surface with `--foreground` text. Any other `@tone` outlines it on `--card` instead: the tone's `-ink` (`--success-ink`, `--destructive-ink` for `danger`…) for the text and the ring, and the tone itself for the dot, the same tone names and inks Button and Alert use. `@hue` recolors only the dot (any CSS color, or a `var(--chart-3)`).
 
 **The dot is on by default.** That is the decision most kits get backwards: without it, a row of chips is distinguished only by fill colour, and colour alone is a WCAG 1.4.1 problem _and_ hard to scan. The dot gives the hue a saturated anchor next to muted ink, so the category reads at a glance even when the fills are close. Turn it off (`@dot={{false}}`) only when the chip's own text already names the category unambiguously.
 
-The mix ratios are tokens (`--pretui-chip-mix`, `--pretui-ink-mix`).
-
 ## Prior art
 
 **Web Awesome `wa-tag`** takes `variant` (brand/success/neutral/warning/danger), `appearance` (accent/filled/outlined/plain), `size` and `with-remove` — a closed enum of five semantic colours plus a removable mode. **shadcn `Badge`** is `default | secondary | destructive | outline`, a `cva` map. **React Spectrum** splits it in two: `Badge` (static, eleven `variant` colours) and `Tag`/`TagGroup` (interactive, removable, selectable, with keyboard navigation).
 
-Where Pretui is better: **the hue is open, and the treatment is derived.** Every kit above enumerates its colours, so a chip for "Region: EMEA" has to be shoehorned into `secondary` or a new variant added. Here you pass a hue — most usefully one of the five `--chart-*` tokens — and get a correct fill, ink and hairline for it automatically. Adding a category costs nothing.
+Where Pretui is better: **the hue is open, and the treatment is derived.** Every kit above enumerates its colors, so a chip for "Region: EMEA" has to be shoehorned into `secondary` or a new variant added. Here you pass a hue — most usefully one of the `--chart-*` tokens — and it colors the dot, while the text stays the theme's guaranteed pair. Adding a category costs nothing.
 
 Where it is thinner, and the gaps are real: **no remove affordance** (Web Awesome and Spectrum both have one, and it is the single most-requested chip feature), **no size axis**, **no icon slot** (the dot is the only leading element), and **no interactive mode** — Spectrum's `TagGroup` with its roving tabindex and Delete-key removal has no analogue here. Reach for **FilterChips** or **RecordPill** when you need behaviour.
 
@@ -32,17 +30,17 @@ That is the right answer for a static chip, and it means the accessibility quest
 - **The dot is an empty `<span>` with no `aria-hidden`.** It contributes nothing to the announced text (there is nothing in it), so this is correct in effect, though an explicit `aria-hidden="true"` would be clearer about intent.
 - **The chip's meaning must survive without colour.** `@label` carries it, so a chip reading "Blocked" is fine; a chip reading "3" whose colour means severity is a **WCAG 1.4.1** failure. The component cannot enforce this, and it is the most common way chips go wrong.
 - **The chip has no accessible relationship to what it describes.** A status chip next to a record name is announced as loose adjacent text. If the chip _is_ the value of a labelled property, put it inside a **KeyValue** or a **FormField**'s static block so the label reaches it.
-- **Contrast is derived, not verified.** Ink is `color-mix(--foreground 34%, hue)` on a `color-mix(hue 20%, --card)` background at **11px, weight 500**. That is the kit's smallest text on a tinted ground, and it is the most likely **1.4.3** failure in the ink territory. A pale `--chart-*` hue produces pale ink on a pale fill; check all five chart hues per season, not just one.
+- **Text contrast is a guaranteed theme pair**: `--foreground` on `--muted` for a neutral chip, the tone's `-ink` on `--card` for a toned one, at **11px, weight 500**, the same for every hue. The dot is decorative; a pale hue makes a faint dot, never faint text.
 - **`white-space: nowrap`** means a long label overflows rather than wraps. Chips are for short values; nothing enforces that.
 - Nothing is focusable, which is correct — there is nothing to do.
 
 ## Theming
 
-`--pretui-chip-hue` (the per-instance hue, defaulting to `--muted-foreground`), `--pretui-chip-mix` (fill strength, default 20%), `--pretui-ink-mix` (ink strength, default 34%), `--card` (the mix base), `--foreground` (mixed into ink), `--border` (mixed into the hairline), `--radius-chip` (6px), `--text-ui-xs`, `--track-ui`.
+`--muted` / `--foreground` (a neutral pill and its text), `--card` with each tone's `--x-ink` (text and ring) and `--x` (dot) for a toned chip, `--pretui-chip-hue` (the dot, defaulting to `--muted-foreground`, or the tone on a toned chip), `--boxel-border-radius-xs`, `--boxel-font-size-2xs`, `--boxel-lsp-xs`, and the `--boxel-sp-*` spacing scale. `--pretui-chip-height` and `--pretui-chip-dot-size` set the pill height and dot size.
 
-The 18px height, 7px padding and 5px dot are fixed.
+A theme restyles every chip through `--muted` and `--foreground`, and the dot colors through the `--chart-*` tokens. Dark mode needs nothing extra: the theme's dark `--muted` / `--foreground` pair applies.
 
-A season retunes every chip in the product through `--pretui-chip-mix` and `--pretui-ink-mix`, and defines the palette through `--chart-1` … `--chart-5`. Because every derived colour mixes against `--card`, a dark season gets correct dark chips automatically — but it must pick chart hues that survive a 20% mix against a dark `--card`, or all five chips converge on the same near-black pill and the dot becomes the only distinction.
+`--pretui-chip-mix` and `--pretui-ink-mix` are legacy knobs that tint a neutral chip's surface and text toward `--pretui-chip-hue`; they are kept for callers that still set them, and new code uses `@tone`.
 
 The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
 
diff --git a/packages/pretui/components/chip.usage.gts b/packages/pretui/components/chip.usage.gts
index 8ecfebf52df..4a62368a388 100644
--- a/packages/pretui/components/chip.usage.gts
+++ b/packages/pretui/components/chip.usage.gts
@@ -4,25 +4,32 @@ import { tracked } from '@glimmer/tracking';
 import { FreestyleUsage } from './freestyle-usage';
 import { Chip } from './chip';
 import { HUE_OPTIONS } from '../demo-ink-feedback';
+import { PRETUI_TONES, type PretuiTone } from '../pretui-primitives';
+
+const TONE_OPTIONS = [...PRETUI_TONES];
 
 // ── Chip ← pill/usage.gts + tag/usage.gts ────────────────────────────────
-// Dropped knobs: kind (Chip is never a button), variant + size (one hue in,
-// complete treatment out — no variant/size matrix), pillBorderColor /
-// pillFontColor / borderColor / fontColor (the single @hue derives fill,
-// ring, and ink), ellipsize (chips never wrap or truncate), htmlTag (Chip is
-// always a span).
+// Dropped knobs: kind (Chip is never a button), variant + size (no
+// variant/size matrix), pillBorderColor / pillFontColor / borderColor /
+// fontColor (@tone picks the pill's treatment; @hue colors the dot),
+// ellipsize (chips never wrap or truncate), htmlTag (Chip is always a span).
 class ChipUsage extends GlimmerComponent {
   @tracked label = 'Meeting Minutes';
   @tracked hue = '';
+  @tracked tone: PretuiTone = 'neutral';
   @tracked dot = true;
   setLabel = (v: string) => (this.label = v);
   setHue = (v: string) => (this.hue = v);
+  setTone = (v: string) => (this.tone = v as PretuiTone);
   toggleDot = (v: boolean) => (this.dot = v);
   get hueVal() {
     return this.hue || undefined;
   }
   get usage() {
     let bits = [`@label='${this.label}'`];
+    if (this.tone !== 'neutral') {
+      bits.push(`@tone='${this.tone}'`);
+    }
     if (this.hue) {
       bits.push(`@hue='${this.hue}'`);
     }
@@ -38,11 +45,18 @@ class ChipUsage extends GlimmerComponent {
       @source={{this.usage}}
     >
       <:example>
-        <Chip @label={{this.label}} @hue={{this.hueVal}} @dot={{this.dot}} />
+        <Chip
+          @label={{this.label}}
+          @tone={{this.tone}}
+          @hue={{this.hueVal}}
+          @dot={{this.dot}}
+        />
         <Chip @label='Gelato' @hue='var(--chart-3)' />
         <Chip @label='Catering' @hue='var(--chart-4)' />
         <Chip @label='Seasonal' @hue='var(--chart-1)' />
         <Chip @label='draft' />
+        <Chip @label='live' @tone='success' />
+        <Chip @label='blocked' @tone='danger' />
       </:example>
       <:api as |Args|>
         <Args.String
@@ -53,11 +67,19 @@ class ChipUsage extends GlimmerComponent {
         />
         <Args.String
           @name='hue'
-          @description='Background color of the pill — in Pretui the one hue drives fill, ring, and ink together (Law 2); empty derives no hue.'
+          @description='Color of the dot; empty uses the tone, or the muted ink when neutral.'
           @options={{HUE_OPTIONS}}
           @value={{this.hue}}
           @onInput={{this.setHue}}
         />
+        <Args.String
+          @name='tone'
+          @description='Neutral is the muted pill; any other tone outlines it in that tone.'
+          @options={{TONE_OPTIONS}}
+          @defaultValue='neutral'
+          @value={{this.tone}}
+          @onInput={{this.setTone}}
+        />
         <Args.Bool
           @name='dot'
           @description='Leading status dot (Pretui addition).'
diff --git a/packages/pretui/components/status-chip.gts b/packages/pretui/components/status-chip.gts
index c73cfced0bf..350b13b9637 100644
--- a/packages/pretui/components/status-chip.gts
+++ b/packages/pretui/components/status-chip.gts
@@ -2,9 +2,14 @@
 import Component from '@glimmer/component';
 import { Chip } from './chip';
 import { statusHue } from '../internal/ink';
+import {
+  PRETUI_TONES,
+  resolveTone,
+  type PretuiToneArg,
+} from '../pretui-primitives';
 
 export interface StatusChipSignature {
-  Args: { value: string; hue?: string };
+  Args: { value: string; hue?: string; tone?: PretuiToneArg };
   Element: HTMLSpanElement;
 }
 
@@ -13,7 +18,20 @@ export class StatusChip extends Component<StatusChipSignature> {
   get hue() {
     return this.args.hue ?? statusHue(this.args.value);
   }
+  // a toned chip's dot takes its tone unless @hue says otherwise; neutral,
+  // passed or defaulted, keeps the status hue
+  get dotHue() {
+    return resolveTone(this.args.tone, PRETUI_TONES, 'neutral') === 'neutral'
+      ? this.hue
+      : this.args.hue;
+  }
   <template>
-    <Chip @label={{@value}} @hue={{this.hue}} data-test-pretui-status-chip ...attributes />
+    <Chip
+      @label={{@value}}
+      @hue={{this.dotHue}}
+      @tone={{@tone}}
+      data-test-pretui-status-chip
+      ...attributes
+    />
   </template>
 }
diff --git a/packages/pretui/components/status-chip.md b/packages/pretui/components/status-chip.md
index 12ec6418871..0c33a55ce6f 100644
--- a/packages/pretui/components/status-chip.md
+++ b/packages/pretui/components/status-chip.md
@@ -7,9 +7,10 @@ A **Chip** whose colour is derived from the value rather than chosen. Pass `@val
 ```
 @value: string   (required)
 @hue?            — override; the exception, not the norm
+@tone?           — Chip's tone (default neutral)
 ```
 
-Two args, and the second one you should rarely reach for.
+Three args, and the last two you should rarely reach for. A toned StatusChip is outlined in that tone and its dot takes the tone, so `@tone` is for a status whose meaning is fixed, like `live`; the hash hue stays on a neutral chip.
 
 **The hue is a hash, and the hash is the point.** `statusHue()` runs a 32-bit polynomial rolling hash (`h * 31 + charCode`, unsigned) over the string and takes `h % 5` to index `--chart-1` … `--chart-5`. Deterministic, dependency-free, and — the property that matters — **stable across cards, realms and sessions**. No registry, no config, no design review to add a status.
 
@@ -34,7 +35,7 @@ No APG pattern; it is text with a background and carries no role — correct.
 Everything **Chip** says applies, and one thing more, which is the important one:
 
 - **Colour conveys nothing here, and that is a feature.** Because the hue is a hash, it is _not_ meaningful, so a user who cannot perceive it loses nothing that the label does not already carry. That makes StatusChip trivially **WCAG 1.4.1** compliant in a way that a semantic-colour chip is not — the label is always the message.
-- **But contrast still applies.** Ink is `color-mix(--foreground 34%, hue)` on a `color-mix(hue 20%, --card)` fill at **11px, weight 500**. All five `--chart-*` hues must clear **WCAG 1.4.3** at that size, in every season, in both modes — and unlike Chip, you cannot avoid a bad hue by not using it, because the hash will eventually pick it. Testing one chart hue is not enough; test all five.
+- **Contrast does not depend on the hue.** The text is Chip's `--foreground` on `--muted` (or a tone's `-ink` on `--card`), at **11px, weight 500**; the hash hue only colors the dot, so no `--chart-*` value can make the label illegible.
 - **The dot inherits from Chip and is on by default**, giving each hue a saturated anchor. Since the hues are arbitrary, the dot is doing less work here than it does on a semantic Chip — but it still helps distinguish adjacent chips whose fills are close.
 - **The chip has no relationship to the field it describes.** "In Review" announced next to a record name is loose text; put it in a **KeyValue** row or a **FormField** static block if the property name matters.
 - **No `aria-label` and no title.** The value is the visible text and the accessible text, which is right.
@@ -42,6 +43,6 @@ Everything **Chip** says applies, and one thing more, which is the important one
 
 ## Theming
 
-Inherits **Chip**'s entire token set: `--pretui-chip-hue` (set here from the hash), `--pretui-chip-mix` (20%), `--pretui-ink-mix` (34%), `--card`, `--foreground`, `--border`, `--radius-chip`, `--text-ui-xs`, `--track-ui`.
+Inherits **Chip**'s entire token set; `--pretui-chip-hue` is set here from the hash.
 
-The palette a season must define is `--chart-1` through `--chart-5`, and this component is the reason those five need to work as a _set_ rather than individually: they will appear side by side in a list, assigned arbitrarily, so they must be mutually distinguishable at 18px and each legible as an ink/fill pair. A season that tunes its chart palette for line charts — where hues sit apart and at full saturation — and does not re-check it at 20% tint behind 11px text will get a status list that is either muddy or illegible. This is the single most common season failure in the ink territory.
+The theme's `--chart-1` through `--chart-5` color the dots, and this component is the reason those five need to work as a _set_: they appear side by side in a list, assigned arbitrarily, so they must be mutually distinguishable as small dots on `--muted`.
diff --git a/packages/pretui/ink.test.gts b/packages/pretui/ink.test.gts
index ea77eb9ac52..6abd09d440e 100644
--- a/packages/pretui/ink.test.gts
+++ b/packages/pretui/ink.test.gts
@@ -76,6 +76,17 @@ module('Pretui | ink', function (hooks) {
     );
   });
 
+  test('Chip is neutral by default and reflects a known @tone', async function (assert) {
+    await render(
+      <template>
+        <Chip @label='Draft' data-test-neutral />
+        <Chip @label='Live' @tone='success' data-test-toned />
+      </template>,
+    );
+    assert.strictEqual(q('[data-test-neutral]').getAttribute('data-tone'), 'neutral');
+    assert.strictEqual(q('[data-test-toned]').getAttribute('data-tone'), 'success');
+  });
+
   // ── StatusChip ──────────────────────────────────────────────────────────
   test('StatusChip derives its hue from the value and renders it as the label', async function (assert) {
     await render(<template><StatusChip @value='blocked' /></template>);
@@ -95,6 +106,25 @@ module('Pretui | ink', function (hooks) {
     );
   });
 
+  test('a toned StatusChip hands its dot to the tone, and neutral keeps the status hue', async function (assert) {
+    await render(
+      <template>
+        <StatusChip @value='live' @tone='success' data-test-toned />
+        <StatusChip @value='live' @tone='neutral' data-test-neutral />
+      </template>,
+    );
+    assert.strictEqual(q('[data-test-toned]').getAttribute('data-tone'), 'success');
+    assert.strictEqual(
+      q('[data-test-toned]').getAttribute('style'),
+      null,
+      'no status hue overrides the tone on a toned chip',
+    );
+    assert.true(
+      q('[data-test-neutral]').getAttribute('style')?.includes(statusHue('live')),
+      'an explicit neutral tone renders like an omitted one',
+    );
+  });
+
   // ── Delta ───────────────────────────────────────────────────────────────
   test('Delta signs the number and reflects the direction', async function (assert) {
     await render(

From 0e5c4023091d4c959ff5b2fea004487eda0fb359 Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Wed, 7 Oct 2026 17:54:14 -0400
Subject: [PATCH 04/30] Bring Token's hues, sizes and docs onto the theme
 contract

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/components/token.gts       | 28 ++++++++++++----------
 packages/pretui/components/token.md        | 18 +++++---------
 packages/pretui/components/token.usage.gts | 25 +++++++++----------
 3 files changed, 35 insertions(+), 36 deletions(-)

diff --git a/packages/pretui/components/token.gts b/packages/pretui/components/token.gts
index 96894289a10..dfaa0943844 100644
--- a/packages/pretui/components/token.gts
+++ b/packages/pretui/components/token.gts
@@ -13,7 +13,7 @@ export interface TokenSignature {
   Args: {
     value?: string;
     hue?: string;
-    /** house scale xs|s|m|l|xl; omitted or 'default', the size follows `--text-body` */
+    /** house scale xs|s|m|l|xl; omitted or 'default', Chip's size */
     size?: PretuiSizeArg;
     /** let a long value wrap instead of overflowing on one line */
     wrap?: boolean;
@@ -146,22 +146,23 @@ export class Token extends Component<TokenSignature> {
     </code>
     <style scoped>
       @layer PretComponent {
+        /* Chip's radius, padding and height, so the two line up side by side,
+           but outlined on --card where Chip is filled with --muted: a value,
+           not a label. --pretui-token-hue is the text color; callers set it on
+           the Token or an ancestor, so it is read with a fallback rather than
+           declared here. */
         .pretui-token {
-          --_th: var(--pretui-token-hue, var(--pretui-primary-ink, var(--primary)));
           display: inline-block;
           margin-inline: 0.35ch;
           vertical-align: baseline;
           font-family: var(--font-mono);
-          font-size: var(
-            --pretui-token-font-size,
-            calc(var(--text-body, 15px) - 3.5px)
-          );
-          line-height: 1.5;
-          padding: 0 5px;
-          border-radius: 4px;
-          background: color-mix(in oklch, var(--_th) 8%, var(--card));
-          color: color-mix(in oklch, var(--foreground) 26%, var(--_th));
-          box-shadow: 0 0 0 1px color-mix(in oklch, var(--_th) 30%, var(--border));
+          font-size: var(--pretui-token-font-size, var(--boxel-font-size-2xs));
+          line-height: 1.125rem;
+          padding: 0 var(--boxel-sp-2xs);
+          border-radius: var(--boxel-border-radius-xs);
+          background-color: var(--card);
+          color: var(--pretui-token-hue, var(--card-foreground));
+          box-shadow: inset 0 0 0 1px var(--border);
           white-space: nowrap;
           font-variant-numeric: tabular-nums;
         }
@@ -174,12 +175,15 @@ export class Token extends Component<TokenSignature> {
         }
         .pretui-token[data-size='m'] {
           font-size: var(--pretui-size-m, var(--text-ui-md, 0.78rem));
+          line-height: 1.5;
         }
         .pretui-token[data-size='l'] {
           font-size: var(--pretui-size-l, var(--text-ui-lg, 0.875rem));
+          line-height: 1.5;
         }
         .pretui-token[data-size='xl'] {
           font-size: var(--pretui-size-xl, var(--text-ui-xl, 1rem));
+          line-height: 1.5;
         }
         .pretui-token[data-wrap] {
           white-space: normal;
diff --git a/packages/pretui/components/token.md b/packages/pretui/components/token.md
index a1fd5d65dc5..48b53e3db90 100644
--- a/packages/pretui/components/token.md
+++ b/packages/pretui/components/token.md
@@ -12,7 +12,7 @@ Element: HTMLElement (a <code>)
 
 **It renders `<code>`**, which is the correct element and is what makes it a Token rather than a styled span.
 
-**`@size`** takes the house scale `xs | s | m | l | xl` (and the `sm` / `md` / `lg` / `small` / `medium` / `large` aliases), the same steps and the same `--pretui-size-*` → `--text-ui-*` tokens as **Button**'s `@size`. Like Button's, it sets the font-size only; the padding, radius and margins stay as they are. It lands as `data-size` on the element. Without `@size`, or with `@size='default'` (as on Button, the component's own default), the size is derived from the surrounding type (see Prior art); `--pretui-token-font-size` pins it to an exact value instead, such as `var(--boxel-font-size-xs)`. `@size` wins over that property.
+**`@size`** takes the house scale `xs | s | m | l | xl` (and the `sm` / `md` / `lg` / `small` / `medium` / `large` aliases), the same steps and the same `--pretui-size-*` → `--text-ui-*` tokens as **Button**'s `@size`. Like Button's, it sets the font-size only; the padding, radius and margins stay as they are. It lands as `data-size` on the element. Without `@size`, or with `@size='default'` (as on Button, the component's own default), the size is `--boxel-font-size-2xs`; `--pretui-token-font-size` pins it to an exact value instead, such as `var(--boxel-font-size-xs)`. `@size` wins over that property.
 
 **`@hue` and a caller's `style` work together.** Glimmer lets a caller's `style` attribute replace a component's own, so `@hue` is also written as a single `--pretui-token-hue` property on top of whatever style the element ends up with, and written again if the caller's style changes later. The caller's own declarations are kept, and so is a property another modifier on the element sets, such as boxel-ui's `setCssVar`. If the caller's style sets `--pretui-token-hue` as well, `@hue` wins, and the hue the caller's style last set comes back when `@hue` is cleared, including when the caller rewrote its style to `@hue`'s own value. One rewrite is not told apart from another modifier's write: a caller style that sets the hue exactly as `@hue` wrote it and changes some other declaration (dropping a property another modifier set counts). Its hue is not taken as the caller's, so clearing `@hue` brings back the caller's earlier hue, or none. `@size` and `@wrap` are data attributes, so a caller's style cannot remove them.
 
@@ -24,7 +24,7 @@ Two details worth knowing, both about how it behaves in context:
 
 **`:where(td, dd) > .pretui-token { margin-inline: 0 }`.** As a direct child of a table cell or a definition-list value, the margins go away so the pill aligns flush with the cell edge. The `:where()` keeps specificity at zero so a call site can override without a fight. This is a small thing that makes tables of ids look right without anyone thinking about it.
 
-The hue defaults to `--pretui-primary-ink` falling back to `--primary`, and derives fill, ink and hairline from it by `color-mix` — 8% fill, 26% ink mix, 30% hairline. Note these are **much quieter ratios than Chip's** (20/34/45): a Token is meant to recede into prose, a Chip to stand out in a list.
+It has Chip's radius, padding and height, but the opposite treatment: outlined on `--card` with `--card-foreground` text and a `--border` ring, where Chip is filled with `--muted`. The hue, when set, is the text color only.
 
 `font-variant-numeric: tabular-nums` keeps a column of ids from jittering.
 
@@ -37,7 +37,7 @@ So the comparison is against "a global `code { }` rule", and the improvements ar
 - **It is a component, so a season can retune every machine value in the product at once** rather than hunting for a global rule that some card overrode.
 - **`@hue` makes it tintable per instance**, which is what lets **FieldError**'s rule-id provenance, an error trace and a normal id look related but distinguishable.
 - **The context-aware margins** (above) — a global `code` rule cannot know it is in a table cell without the same `:where()` trick, and almost none do it.
-- **The size is derived**: `calc(var(--text-body) - 3.5px)`, so mono at the same optical size as the surrounding proportional text rather than the visually-larger result you get from matching point sizes. That is the detail that makes it read as jewelry rather than as a foreign object.
+- **The size is a fixed small step** (`--boxel-font-size-2xs` by default), so the mono value sits at about the optical size of body text rather than the visually larger result you get from matching point sizes.
 
 Where it is thinner: no copy affordance (compose **CopyButton** beside it), no truncation for long values (it stays on one line unless `@wrap` is set, so a long path overflows), and no block variant.
 
@@ -50,18 +50,12 @@ Notes and gaps:
 - **`<code>` semantics are announced inconsistently.** Some screen readers say "code" before the content, some enter a verbatim/character-by-character mode, and most say nothing. That is a property of `<code>`, not of this component, and it is generally the right trade — the element is the honest markup for a machine value.
 - **Long or opaque values are hostile to speech.** A UUID or a hash announced character by character is unusable, and announced as a word is meaningless. If a Token holds something a screen-reader user might need to transcribe, pair it with a **CopyButton** — that is the accessible affordance, not the text.
 - **`white-space: nowrap`** is the default, so a long value overflows its container rather than wrapping, which can push a card horizontally and fail **WCAG 1.4.10 Reflow** at 320px. This is the most likely practical problem: paths and URLs are exactly what people put in Tokens. Set `@wrap` wherever the value can be long.
-- **Contrast.** Ink is `color-mix(--foreground 26%, hue)` on an **8%** hue fill — so the fill is nearly `--card` and the ink is nearly the hue. That is a better-behaved combination than **Chip**'s, but the text is `--text-body - 3.5px` (≈11.5px), or smaller at `@size='xs'`, and a pale `@hue` will produce pale ink on white. Check any custom hue at the size it is used.
+- **Contrast.** By default the text is `--card-foreground` on `--card`, the theme's own guaranteed pair. A `@hue` replaces the text color, so pass an ink (`--primary-ink`, `--muted-foreground`), not a pale fill hue, and check it at the size it is used (11px by default, smaller at `@size='xs'`).
 - **The hue carries no meaning** and there is no non-colour channel, so do not use `@hue` to encode state — use two components, or add text.
 - Nothing is focusable, correctly.
 
 ## Theming
 
-`--pretui-token-hue` (per instance, defaulting to `--pretui-primary-ink` → `--primary`), `--card` (mix base), `--foreground` (mixed into ink), `--border` (mixed into the hairline), `--font-mono`, `--pretui-token-font-size` (an exact size; unset, the size is derived from `--text-body`), `--pretui-size-*` / `--text-ui-*` (the `@size` steps), `--pretui-shadow-hairline` semantics via `box-shadow`.
+`--card` (the surface) with `--card-foreground` (the text) and `--border` (the ring), plus `--boxel-border-radius-xs`, `--boxel-sp-2xs` and `--font-mono`. `--pretui-token-hue` sets the text color, on the Token (through `@hue`, a class or `style`) or on any ancestor; pass an ink such as `--primary-ink` or `--muted-foreground`, not a pale fill hue. `--pretui-token-font-size` sets an exact size; unset, the default is `--boxel-font-size-2xs`, and `@size` takes the house scale (`--pretui-size-*`).
 
-Both `--pretui-token-hue` and `--pretui-token-font-size` can be set on the Token, through a class or `style`, or on any ancestor.
-
-The 8% / 26% / 30% mix ratios, the 4px radius, 5px padding and `0.35ch` margins are fixed — unlike **Chip**, whose mixes are tokenised. A season wanting quieter or louder tokens must change `--pretui-primary-ink`, which is the only lever.
-
-Note that `--pretui-primary-ink` is meant to be a _readable-on-light-surfaces_ variant of `--primary`; a season that leaves it undefined falls back to `--primary` neat, and a saturated brand colour at 26% ink mix on an 8% fill is usually too light. Defining `--pretui-primary-ink` is effectively required for this component.
-
-The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+The default line height matches Chip's 18px, so a Token and a Chip side by side line up.
diff --git a/packages/pretui/components/token.usage.gts b/packages/pretui/components/token.usage.gts
index de4ba243255..3f1da613f65 100644
--- a/packages/pretui/components/token.usage.gts
+++ b/packages/pretui/components/token.usage.gts
@@ -5,17 +5,18 @@ import { FreestyleUsage } from './freestyle-usage';
 import { Token } from './token';
 import { PRETUI_SIZES, type PretuiSize } from '../pretui-primitives';
 
-// The size knob's choices: the --text-body default plus the house scale.
-const BODY_SIZE = 'body';
+// The size knob's choices: the 2xs default plus the house scale.
+const BODY_SIZE = 'default';
 const SIZES = [BODY_SIZE, ...PRETUI_SIZES];
-// The hue knob's choices: the default plus the contract's muted and state hues.
-const DEFAULT_HUE = 'var(--pretui-primary-ink, var(--primary))';
+// The hue knob's choices: the default plus inks, since the hue is the text
+// color and has to read on --card.
+const DEFAULT_HUE = 'var(--card-foreground)';
 const HUES = [
   DEFAULT_HUE,
   'var(--muted-foreground)',
-  'var(--chart-2)',
-  'var(--chart-4)',
-  'var(--destructive)',
+  'var(--primary-ink)',
+  'var(--success-ink)',
+  'var(--destructive-ink)',
 ];
 
 class TokenUsage extends Component {
@@ -78,7 +79,7 @@ class TokenUsage extends Component {
           @value={{this.size}}
           @options={{SIZES}}
           @defaultValue={{BODY_SIZE}}
-          @description='House scale xs|s|m|l|xl, the same steps as Button; sets the font-size only. Omitted, the size follows --text-body, or --pretui-token-font-size when that is set (Pretui addition).'
+          @description='House scale xs|s|m|l|xl, the same steps as Button; sets the font-size only. Omitted, the size is --boxel-font-size-2xs, or --pretui-token-font-size when that is set (Pretui addition).'
           @onInput={{this.setSize}}
         />
         <Args.String
@@ -86,7 +87,7 @@ class TokenUsage extends Component {
           @value={{this.hue}}
           @options={{HUES}}
           @defaultValue={{DEFAULT_HUE}}
-          @description='Validated CSS colour for the fill, ink and hairline. Sets --pretui-token-hue, and stays set when the caller also passes a style attribute.'
+          @description='Validated CSS color for the text. Sets --pretui-token-hue, and stays set when the caller also passes a style attribute.'
           @onInput={{this.setHue}}
         />
         <Args.Bool
@@ -105,14 +106,14 @@ class TokenUsage extends Component {
         <Css.Basic
           @name='pretui-token-hue'
           @type='color'
-          @description='Colour the fill, ink and hairline are mixed from. Set on the Token or any ancestor, or through @hue.'
-          @defaultValue='var(--pretui-primary-ink, var(--primary))'
+          @description='Text color. Set on the Token or any ancestor, or through @hue.'
+          @defaultValue='var(--card-foreground)'
         />
         <Css.Basic
           @name='pretui-token-font-size'
           @type='dimension'
           @description='Exact font-size for a Token with no @size, such as var(--boxel-font-size-xs). Set on the Token or any ancestor; @size wins over it.'
-          @defaultValue='calc(var(--text-body, 15px) - 3.5px)'
+          @defaultValue='var(--boxel-font-size-2xs)'
         />
       </:cssVars>
     </FreestyleUsage>

From f6dfe5ad11eabb1fdd0e86179e74cebd9c0da38c Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Wed, 7 Oct 2026 17:54:16 -0400
Subject: [PATCH 05/30] Let Table drop its frame inside a panel, and paint
 zebra and hover on the row

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/components/table.gts       | 31 +++++++++++++++++-----
 packages/pretui/components/table.md        |  5 ++--
 packages/pretui/components/table.test.gts  | 17 ++++++++++++
 packages/pretui/components/table.usage.gts | 12 ++++++++-
 4 files changed, 56 insertions(+), 9 deletions(-)

diff --git a/packages/pretui/components/table.gts b/packages/pretui/components/table.gts
index 03bba532fbf..6ff142e9809 100644
--- a/packages/pretui/components/table.gts
+++ b/packages/pretui/components/table.gts
@@ -1,5 +1,6 @@
 // Pretui — Table: the DataGrid shell as a yieldable primitive for custom tables.
 import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { eq } from '@cardstack/boxel-ui/helpers';
 
 // Table — the DataGrid shell as a yieldable primitive (added for the
 // freestyle dogfood pass: composite tables that need custom cell content —
@@ -15,6 +16,9 @@ export interface TableSignature {
     /** id of an on-screen element (a heading) that names the table; lands as
      * `aria-labelledby` on the `<table>` and is dropped when a caption renders */
     labelledBy?: string;
+    /** false drops the table's own radius and hairline, for a table seated
+     * inside a panel that already draws them (default true) */
+    framed?: boolean;
   };
   Blocks: { caption: []; head: []; body: [] };
   Element: HTMLDivElement;
@@ -25,7 +29,12 @@ export interface TableSignature {
 // @labelledBy and @label only land when neither renders, and @labelledBy wins
 // over @label, as aria-labelledby does over aria-label.
 export const Table: TemplateOnlyComponent<TableSignature> = <template>
-  <div class='pretui-tablewrap' data-test-pretui-table ...attributes>
+  <div
+    class='pretui-tablewrap'
+    data-framed={{if (eq @framed false) 'false'}}
+    data-test-pretui-table
+    ...attributes
+  >
     <table
       class='pretui-table'
       aria-labelledby={{if
@@ -59,11 +68,15 @@ export const Table: TemplateOnlyComponent<TableSignature> = <template>
         min-width: 0;
         max-width: 100%;
         max-height: var(--pretui-table-max-height, none);
-        border-radius: var(--radius);
+        border-radius: var(--boxel-border-radius);
         box-shadow: 0 0 0 1px var(--border);
         background-color: var(--card);
         color: var(--card-foreground);
       }
+      .pretui-tablewrap[data-framed='false'] {
+        border-radius: 0;
+        box-shadow: none;
+      }
       .pretui-table {
         --pretui-table-head-height: 1.875rem;
         width: 100%;
@@ -110,19 +123,25 @@ export const Table: TemplateOnlyComponent<TableSignature> = <template>
         padding: var(--boxel-sp-2xs) var(--boxel-sp-xs);
         box-shadow: inset 0 -1px 0 var(--border);
       }
+      /* the frame (Table's own ring, or the panel a frameless table sits in)
+         already draws the bottom edge */
+      .pretui-table :deep(tbody tr:last-child td),
+      .pretui-table :deep(tbody tr:last-child th) {
+        box-shadow: none;
+      }
       /* Kept off td: at this specificity it would beat a caller's own td
          alignment in the same layer, such as UsageArgument's right-aligned
          Default column. */
       .pretui-table :deep(tbody th) {
         text-align: start;
       }
-      .pretui-table :deep(tbody tr:nth-child(even) td),
-      .pretui-table :deep(tbody tr:nth-child(even) th) {
+      /* zebra and hover paint the row, beneath its cells, so a caller's
+         own cell background still shows */
+      .pretui-table :deep(tbody tr:nth-child(even)) {
         background-color: var(--stripe);
       }
       @media (hover: hover) {
-        .pretui-table :deep(tbody tr:hover td),
-        .pretui-table :deep(tbody tr:hover th) {
+        .pretui-table :deep(tbody tr:hover) {
           background-color: var(--hover);
         }
       }
diff --git a/packages/pretui/components/table.md b/packages/pretui/components/table.md
index ae74fd5208f..21f2e628580 100644
--- a/packages/pretui/components/table.md
+++ b/packages/pretui/components/table.md
@@ -10,6 +10,7 @@ It was added for the freestyle dogfood pass, when composite tables like the Comp
 @caption?   — the table's name, rendered as a real <caption>
 @labelledBy? — id of an on-screen element that names the table (aria-labelledby on the <table>)
 @label?     — the name when it is nowhere on screen (aria-label on the <table>)
+@framed?    — false drops the radius and hairline, for a table inside a panel (default true)
 <:caption>  — a rich caption; wins over @caption
 <:head>   <:body>
 Element: HTMLDivElement
@@ -19,7 +20,7 @@ Element: HTMLDivElement
 
 **`@label` and `@labelledBy` name the `<table>`, which deliberately differs from DataTable.** DataTable's `@label` names its scroll region (a `role='region'` box with a tab stop) and sits alongside its caption: the caption names the table, the label names the region. Table has no such region — its wrapper is a plain `<div>` — so the only thing left to name is the `<table>`, and a caption already does that. Hence `@label` and `@labelledBy` here are the caption's stand-ins rather than a second name, and are dropped when a caption renders.
 
-The one non-obvious thing: **the yielded cells are styled partly through `:deep()`.** The component renders `<thead>` and `<tbody>` itself, so the inherited properties sit on those two elements and flow into your cells: the mono header voice, its ink and `nowrap` on `thead`, and top alignment on `tbody`. What the browser's `th` rule overrides (weight, alignment) and what doesn't inherit (padding, height, backgrounds, row rules, the sticky position) has to reach into content the component did not render, so `.pretui-table :deep(thead th)`, `:deep(td)`, `:deep(tbody th)`, `:deep(tbody tr:nth-child(even) td)` and `:deep(tbody tr:hover td)` (and their `th` twins) do that work. This is a legitimate, narrow use of the escape hatch — the alternative would be a `<Table.Row>`/`<Table.Cell>` component pair, which buys type safety at the cost of the "just write a table" affordance the component exists to provide.
+The one non-obvious thing: **the yielded cells are styled partly through `:deep()`.** The component renders `<thead>` and `<tbody>` itself, so the inherited properties sit on those two elements and flow into your cells: the mono header voice, its ink and `nowrap` on `thead`, and top alignment on `tbody`. What the browser's `th` rule overrides (weight, alignment) and what doesn't inherit (padding, height, backgrounds, row rules, the sticky position) has to reach into content the component did not render, so `.pretui-table :deep(thead th)`, `:deep(td)`, `:deep(tbody th)`, `:deep(tbody tr:nth-child(even))`, `:deep(tbody tr:hover)` and `:deep(tbody tr:last-child td)` (with its `th` twin, which drops the last row rule where the frame already draws the edge) do that work. Zebra and hover paint the row, beneath its cells, so a caller's own cell background still shows. This is a legitimate, narrow use of the escape hatch — the alternative would be a `<Table.Row>`/`<Table.Cell>` component pair, which buys type safety at the cost of the "just write a table" affordance the component exists to provide.
 
 **The header band is scoped to `thead`.** Only the column headers in `<:head>` get the sticky mono band; the header voice is set on `thead`, so it never reaches the body. A row header — `<th scope='row'>` in `<:body>` — wears the body-cell rules instead: the cell padding, the row rule, zebra and hover, top alignment and start alignment, keeping the browser's bold `th` weight. So a matrix with row headers needs no override to undo the band.
 
@@ -33,7 +34,7 @@ Pretui differs from shadcn on one axis and it is the interesting one: **shadcn g
 
 The improvement over both: it **reads the boxel theme contract**, so a hand-built table follows whatever theme the card wears — surface, header band, zebra, hover, type roles and spacing ladder — with no season tokens and no literal fallbacks. DataGrid still reads the Pret season tokens and fixed metrics for the same parts, so the two differ outside a season: Table's header is set in the label role at the label size, DataGrid's in a fixed 10px eyebrow.
 
-The cost, stated plainly: no sorting, no selection, no virtualisation, no column definitions, and no way to add them without switching components.
+The cost, stated plainly: no sorting, no selection, no virtualization, no column definitions, and no way to add them without switching components.
 
 ## Accessibility
 
diff --git a/packages/pretui/components/table.test.gts b/packages/pretui/components/table.test.gts
index 615abc034e6..d65112adb6e 100644
--- a/packages/pretui/components/table.test.gts
+++ b/packages/pretui/components/table.test.gts
@@ -186,4 +186,21 @@ module('Pretui | components/table', function (hooks) {
     assert.strictEqual(table.getAttribute('aria-labelledby'), 'lots-heading', 'the on-screen name is used');
     assert.notOk(table.hasAttribute('aria-label'), 'and the typed-in name is dropped, so the two cannot disagree');
   });
+
+  test('a table is framed by default, and @framed=false marks it frameless', async function (assert) {
+    await render(
+      <template>
+        <Table data-test-framed>
+          <:head><tr><th>Lot</th></tr></:head>
+          <:body><tr><td>Keemun</td></tr></:body>
+        </Table>
+        <Table @framed={{false}} data-test-frameless>
+          <:head><tr><th>Lot</th></tr></:head>
+          <:body><tr><td>Keemun</td></tr></:body>
+        </Table>
+      </template>,
+    );
+    assert.notOk(q('[data-test-framed]').hasAttribute('data-framed'), 'the default carries no frameless marker');
+    assert.strictEqual(q('[data-test-frameless]').getAttribute('data-framed'), 'false', 'a frameless table says so');
+  });
 });
diff --git a/packages/pretui/components/table.usage.gts b/packages/pretui/components/table.usage.gts
index 7817705f747..f75b223dfd2 100644
--- a/packages/pretui/components/table.usage.gts
+++ b/packages/pretui/components/table.usage.gts
@@ -1,5 +1,6 @@
 // Pretui — Table usage page.
 import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
 import { FreestyleUsage } from './freestyle-usage';
 import { Token } from './token';
 import { Table } from './table';
@@ -7,6 +8,8 @@ import { LOT_ROWS } from '../demo-foundations';
 
 class TableUsage extends Component {
   rows = LOT_ROWS;
+  @tracked framed = true;
+  setFramed = (v: boolean) => (this.framed = v);
   <template>
     <FreestyleUsage
       @name='Table'
@@ -15,13 +18,20 @@ class TableUsage extends Component {
       @viewportMode='wide'
     >
       <:example>
-        <Table>
+        <Table @framed={{this.framed}}>
           <:head><tr><th>Lot</th><th>Tea</th><th>Origin</th><th>Chests</th></tr></:head>
           <:body>{{#each this.rows as |row|}}<tr><td><Token @value={{row.lot}} /></td><td>{{row.tea}}</td><td>{{row.origin}}</td><td>{{row.chests}}</td></tr>{{/each}}</:body>
         </Table>
       </:example>
       <:api as |Args|>
         <Args.Object @name='sample rows' @value={{this.rows}} />
+        <Args.Bool
+          @name='framed'
+          @value={{this.framed}}
+          @defaultValue={{true}}
+          @description='Off drops the radius and hairline, for a table inside a panel.'
+          @onInput={{this.setFramed}}
+        />
         <Args.Yield @name='head' @description='Table header rows.' />
         <Args.Yield @name='body' @description='Table body rows.' />
       </:api>

From a77d20944bf7e3c17919c2186fc17dfea9f32838 Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Wed, 7 Oct 2026 17:54:17 -0400
Subject: [PATCH 06/30] Keep SegmentedControl's segments at their bold width
 and give its pill a strong edge

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../pretui/components/segmented-control.gts    | 18 +++++++++++++++++-
 .../pretui/components/sliding-highlight.gts    | 12 ++++++------
 2 files changed, 23 insertions(+), 7 deletions(-)

diff --git a/packages/pretui/components/segmented-control.gts b/packages/pretui/components/segmented-control.gts
index 53331623a4c..022a231cb70 100644
--- a/packages/pretui/components/segmented-control.gts
+++ b/packages/pretui/components/segmented-control.gts
@@ -102,7 +102,10 @@ export class SegmentedControl extends Component<SegmentedControlSignature> {
             {{on 'change' (fn this.pick option)}}
             data-test-pretui-segmented-option={{option.value}}
           />
-          {{option.label}}
+          <span
+            class='pretui-seg-text'
+            data-text={{option.label}}
+          >{{option.label}}</span>
         </label>
       {{/each}}
     </div>
@@ -162,6 +165,19 @@ export class SegmentedControl extends Component<SegmentedControlSignature> {
              SlidingHighlight in its pill cut — identical treatment, one
              element, and it travels */
           color: var(--foreground);
+          font-weight: 600;
+        }
+        /* a hidden bold copy under the label holds every segment at its bold
+           width, so selecting one never shifts its neighbors or the pill */
+        .pretui-seg-text {
+          display: inline-grid;
+        }
+        .pretui-seg-text::after {
+          content: attr(data-text);
+          height: 0;
+          overflow: hidden;
+          visibility: hidden;
+          font-weight: 600;
         }
         /* coarse pointers get a real hit target without moving the fine one */
         @media (any-pointer: coarse) {
diff --git a/packages/pretui/components/sliding-highlight.gts b/packages/pretui/components/sliding-highlight.gts
index 77715c73896..a9f29504dc2 100644
--- a/packages/pretui/components/sliding-highlight.gts
+++ b/packages/pretui/components/sliding-highlight.gts
@@ -206,13 +206,13 @@ export class SlidingHighlight extends Component<SlidingHighlightSignature> {
             var(--pretui-ease-snap, cubic-bezier(0.23, 1, 0.32, 1))
           );
         }
+        /* a strong edge, so the pill reads even when its track blends into
+           the surface behind it */
         .pretui-highlight[data-variant='pill'] {
-          background: var(--card);
-          box-shadow: var(
-            --pretui-shadow-control,
-            0 0 0 1px var(--border),
-            0 1px 2px rgb(16 24 40 / 0.1)
-          );
+          background-color: var(--card);
+          box-shadow:
+            0 0 0 1px var(--border-strong),
+            var(--shadow-sm);
         }
         .pretui-highlight[data-variant='soft'] {
           background: color-mix(

From 5face9aedecc0006b5e0d18da2c310a192e456a3 Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Wed, 7 Oct 2026 17:54:19 -0400
Subject: [PATCH 07/30] Label Viewport's controls, caption Fill as 100%, and
 size 3-up artboards from the presets

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/components/viewport.gts | 229 +++++++++++++-----------
 packages/pretui/components/viewport.md  |   8 +-
 packages/pretui/viewport.test.gts       |  35 ++--
 3 files changed, 151 insertions(+), 121 deletions(-)

diff --git a/packages/pretui/components/viewport.gts b/packages/pretui/components/viewport.gts
index bc0e0230b0a..0122255f1ed 100644
--- a/packages/pretui/components/viewport.gts
+++ b/packages/pretui/components/viewport.gts
@@ -1,6 +1,7 @@
 // Pretui — Viewport: the artboard every usage example renders in.
 import Component from '@glimmer/component';
 import { tracked } from '@glimmer/tracking';
+import { htmlSafe } from '@ember/template';
 import { modifier } from 'ember-modifier';
 import { SegmentedControl } from './segmented-control';
 import { Select } from './select';
@@ -8,7 +9,7 @@ import { Slider } from './slider';
 import { Switch } from './switch';
 
 function htmlWidth(w: string) {
-  return `width: ${w}`;
+  return htmlSafe(`width: ${w}`);
 }
 function isInline(mode: string) {
   return mode === 'inline';
@@ -32,19 +33,20 @@ const VIEWPORT_MODES = [
   { value: 'grid', label: 'Grid' },
 ];
 const PRESET_WIDTHS: Record<string, number> = {
-  phone: 375,
-  tablet: 768,
+  phone: 320,
+  tablet: 600,
   desktop: 1120,
 };
-const BREAKPOINTS = [
-  { bp: 'phone', caption: 'Phone · 375px' },
-  { bp: 'tablet', caption: 'Tablet · 768px' },
-  { bp: 'desktop', caption: 'Desktop · 1120px' },
-];
+const BREAKPOINTS = Object.entries(PRESET_WIDTHS).map(([bp, px]) => ({
+  bp,
+  width: `${px}px`,
+  caption: `${VIEWPORT_MODES.find((m) => m.value === bp)?.label} · ${px}px`,
+}));
 const SURFACES = [
   { value: 'background', label: 'Background' },
   { value: 'card', label: 'Card' },
   { value: 'inset', label: 'Inset' },
+  { value: 'sidebar', label: 'Sidebar' },
 ];
 // pre-artboard mode names still referenced by older pages
 const LEGACY_MODES: Record<string, string> = {
@@ -65,7 +67,8 @@ export interface ViewportSignature {
       | 'grid'
       | 'narrow'
       | 'wide';
-    // artboard caption, e.g. the component name — renders "Name · <width>"
+    // the specimen's name, e.g. the component name: the caption of a
+    // dragged width ("Name · <width>"); presets are captioned by mode
     label?: string;
   };
   Blocks: { default: [] };
@@ -100,13 +103,15 @@ export class Viewport extends Component<ViewportSignature> {
     return this.customWidth || PRESET_WIDTHS[this.mode] || 0;
   }
   get widthLabel() {
-    return this.artboardWidth ? `${this.artboardWidth}px` : 'fill';
-  }
-  get frameStyleWidth() {
     return this.artboardWidth ? `${this.artboardWidth}px` : '100%';
   }
+  // a preset (Fill or a device) is named by its mode, like the 3-up
+  // captions; a dragged width names the specimen
   get frameCaption() {
-    return `${this.args.label ?? 'Specimen'} · ${this.widthLabel}`;
+    let device = this.customWidth
+      ? undefined
+      : VIEWPORT_MODES.find((m) => m.value === this.mode)?.label;
+    return `${device ?? this.args.label ?? 'Specimen'} · ${this.widthLabel}`;
   }
   // Drag-to-resize on the artboard edge. Pointer capture keeps every event
   // on the handle — no document listeners (backdrop-close discipline).
@@ -159,6 +164,7 @@ export class Viewport extends Component<ViewportSignature> {
     <div class='pretui-viewport' data-test-pretui-viewport ...attributes>
       <div class='pretui-viewport-bar'>
         <SegmentedControl
+          @label='Viewport mode'
           @options={{VIEWPORT_MODES}}
           @value={{this.mode}}
           @onValueChange={{this.setMode}}
@@ -166,6 +172,7 @@ export class Viewport extends Component<ViewportSignature> {
         <div class='pretui-viewport-settings'>
           <div class='pretui-viewport-surface'>
             <Select
+              @label='Stage surface'
               @options={{this.surfaces}}
               @value={{this.surface}}
               @onValueChange={{this.setSurface}}
@@ -177,7 +184,7 @@ export class Viewport extends Component<ViewportSignature> {
               @onCheckedChange={{this.setGutter}}
               data-test-pretui-viewport-gutter
             />
-            <span>Gutter</span>
+            <span>Padding</span>
           </label>
         </div>
         <div class='pretui-viewport-width'>
@@ -202,7 +209,7 @@ export class Viewport extends Component<ViewportSignature> {
             class='pretui-artboard'
             data-label={{this.frameCaption}}
             data-width={{this.widthLabel}}
-            style={{htmlWidth this.frameStyleWidth}}
+            style={{htmlWidth this.widthLabel}}
             data-test-pretui-artboard
           >
             <div
@@ -228,6 +235,7 @@ export class Viewport extends Component<ViewportSignature> {
                 class='pretui-artboard'
                 data-bp={{b.bp}}
                 data-label={{b.caption}}
+                style={{htmlWidth b.width}}
                 data-test-pretui-artboard
               >
                 <div
@@ -243,13 +251,15 @@ export class Viewport extends Component<ViewportSignature> {
             {{/each}}
           </div>
         {{else if (isInline this.mode)}}
-          <p
-            class='pretui-viewport-prose'
-            data-test-pretui-viewport-specimen
-          >The order ledger closes at noon, and
-            {{yield}}
+          {{! a div, not a p: the specimen may be block-level markup }}
+          <div class='pretui-viewport-prose'>The order ledger closes at noon,
+            and
+            <div
+              class='pretui-viewport-inline'
+              data-test-pretui-viewport-specimen
+            >{{yield}}</div>
             sits inline with the running text — cap-line trim and optical
-            spacing judged mid-paragraph, exactly where machine values live.</p>
+            spacing judged mid-paragraph, exactly where machine values live.</div>
         {{else}}
           <div class='pretui-viewport-grid'>
             {{#each this.cells}}
@@ -266,6 +276,28 @@ export class Viewport extends Component<ViewportSignature> {
     <style scoped>
       @layer PretComponent {
         .pretui-viewport {
+          --pretui-viewport-bar-min-h: 2.25rem;
+          --pretui-viewport-width-min-w: 10rem;
+          --pretui-viewport-width-max-w: 18.75rem;
+          --pretui-viewport-readout-min-w: 3rem;
+          --pretui-viewport-surface-w: 8.125rem;
+          --pretui-viewport-canvas-min-h: 13.75rem;
+          --pretui-viewport-canvas-max-h: 34rem;
+          --pretui-viewport-dot-gap: 1.25rem;
+          /* a translucent --background follows the theme in light and dark,
+             which the fixed --boxel-light-* overlays don't */
+          --pretui-viewport-veil: color-mix(
+            in oklch,
+            var(--background) 70%,
+            transparent
+          );
+          --pretui-artboard-min-h: 4.5rem;
+          --pretui-artboard-handle-w: 1rem;
+          --pretui-artboard-grip-w: 0.25rem;
+          --pretui-artboard-grip-h: 1.875rem;
+          --pretui-viewport-tile-min-w: 12.5rem;
+          --pretui-viewport-cell-min-h: 4rem;
+
           display: grid;
           min-width: 0;
         }
@@ -282,45 +314,45 @@ export class Viewport extends Component<ViewportSignature> {
           display: flex;
           align-items: center;
           justify-content: space-between;
-          gap: var(--space-4, 11px);
+          gap: var(--boxel-sp-sm);
           flex-wrap: wrap;
-          min-height: 36px;
-          padding: 6px var(--space-4, 11px);
+          min-height: var(--pretui-viewport-bar-min-h);
+          padding: var(--boxel-sp-2xs) var(--boxel-sp-sm);
           box-shadow: inset 0 -1px 0 var(--border);
         }
         .pretui-viewport-width {
           display: flex;
           align-items: center;
-          gap: 8px;
+          gap: var(--boxel-sp-xs);
           flex: 1;
-          min-width: 160px;
-          max-width: 300px;
+          min-width: var(--pretui-viewport-width-min-w);
+          max-width: var(--pretui-viewport-width-max-w);
         }
         .pretui-viewport-width > :first-child {
           flex: 1;
         }
         .pretui-viewport-readout {
           font-family: var(--font-mono);
-          font-size: var(--text-ui, 12px);
+          font-size: var(--boxel-font-size-xs);
           color: var(--muted-foreground);
-          min-width: 48px;
+          min-width: var(--pretui-viewport-readout-min-w);
           text-align: right;
           font-variant-numeric: tabular-nums;
         }
         .pretui-viewport-settings {
           display: flex;
           align-items: center;
-          gap: var(--space-4, 11px);
+          gap: var(--boxel-sp-sm);
         }
         .pretui-viewport-surface {
-          width: 130px;
-          font-size: var(--text-ui, 12px);
+          width: var(--pretui-viewport-surface-w);
+          font-size: var(--boxel-font-size-xs);
         }
         .pretui-viewport-gutter {
           display: inline-flex;
           align-items: center;
-          gap: 6px;
-          font-size: var(--text-ui, 12px);
+          gap: var(--boxel-sp-2xs);
+          font-size: var(--boxel-font-size-xs);
           font-weight: 500;
           color: var(--muted-foreground);
           white-space: nowrap;
@@ -329,85 +361,75 @@ export class Viewport extends Component<ViewportSignature> {
         .pretui-viewport-canvas {
           /* the canvas floor: dot grid on the inset surface (Figma idiom).
              R1: true widths — wide artboards pan, they are never clamped */
-          background-color: var(--inset, var(--boxel-100));
+          background-color: var(--inset);
+          color: var(--foreground);
           background-image: radial-gradient(
             circle,
-            var(
-                --pretui-canvas-dot,
-                color-mix(in oklch, var(--foreground) 13%, transparent)
-              )
-              1px,
+            var(--border) 1px,
             transparent 1px
           );
-          background-size: 20px 20px;
-          min-height: 220px;
-          max-height: 60vh;
-          padding: 34px var(--space-6, 19px) var(--space-6, 19px);
+          background-size: var(--pretui-viewport-dot-gap)
+            var(--pretui-viewport-dot-gap);
+          min-height: var(--pretui-viewport-canvas-min-h);
+          max-height: var(--pretui-viewport-canvas-max-h);
+          padding: var(--boxel-sp-2xl) var(--boxel-sp-lg) var(--boxel-sp-lg);
           overflow: auto;
           min-width: 0;
         }
         .pretui-artboard {
-          /* exact width from inline style or data-bp; centered while it fits,
-             panned once it doesn't */
+          /* exact width from its inline style; centered while it fits, panned
+             once it doesn't. The preset widths stay in px: they stand in for
+             device widths in CSS pixels. */
           position: relative;
           margin-inline: auto;
-          min-height: 72px;
+          min-height: var(--pretui-artboard-min-h);
         }
         .pretui-artboard[data-label]::before {
           content: attr(data-label);
           position: absolute;
-          top: -21px;
-          left: 0;
+          top: calc(-1 * var(--boxel-sp-lg));
+          inset-inline-start: 0;
           font-family: var(--font-mono);
-          font-size: var(--text-ui-xs, 11px);
+          font-size: var(--boxel-font-size-2xs);
           letter-spacing: 0.02em;
-          /* luminance clamp: a season's accent can be too light for small
-             text on the floor — always mix toward ink */
-          color: color-mix(
-            in oklch,
-            var(--pretui-accent, var(--primary)) 55%,
-            var(--foreground)
-          );
+          color: var(--primary-ink);
           white-space: nowrap;
         }
-        .pretui-artboard:hover {
-          outline: 1px solid
-            color-mix(
-              in oklch,
-              var(--pretui-accent, var(--primary)) 45%,
-              transparent
-            );
-          outline-offset: 8px;
-        }
         .pretui-artboard-body {
           /* R2: a neutral stage — normal block flow, no centering opinion */
-          min-height: 72px;
-          border-radius: 8px;
+          min-height: var(--pretui-artboard-min-h);
+          border-radius: var(--boxel-border-radius-sm);
           box-shadow: 0 0 0 1px var(--border);
         }
         .pretui-artboard-body[data-gutter='true'] {
-          padding: var(--space-5, 14px);
+          padding: var(--boxel-sp);
         }
         .pretui-artboard-body[data-surface='background'] {
-          /* the specimen sits directly on the dot floor — no extra box */
-          background: transparent;
-          box-shadow: none;
-          border-radius: 0;
+          /* a veil of the page color over the dot floor, so the stage reads as
+             an area while the specimen still sits on the page background */
+          background-color: var(--pretui-viewport-veil);
         }
         .pretui-artboard-body[data-surface='card'] {
-          background: var(--card);
-          box-shadow: var(--pretui-shadow-card, 0 0 0 1px var(--border), 0 1px 3px var(--shadow-ink-soft, rgb(16 24 40 / 0.06)));
+          background-color: var(--card);
+          box-shadow:
+            0 0 0 1px var(--border),
+            var(--shadow-sm);
+        }
+        .pretui-artboard-body[data-surface='sidebar'] {
+          background-color: var(--sidebar);
+          color: var(--sidebar-foreground);
+          box-shadow: 0 0 0 1px var(--sidebar-border);
         }
         .pretui-artboard-body[data-surface='inset'] {
-          background: var(--inset, var(--boxel-100));
+          background-color: var(--inset);
           box-shadow: inset 0 0 0 1px var(--border);
         }
         .pretui-artboard-handle {
           position: absolute;
           top: 0;
           bottom: 0;
-          right: -18px;
-          width: 16px;
+          right: calc(-1 * var(--pretui-artboard-handle-w) - var(--boxel-sp-6xs));
+          width: var(--pretui-artboard-handle-w);
           display: flex;
           align-items: center;
           justify-content: center;
@@ -416,54 +438,53 @@ export class Viewport extends Component<ViewportSignature> {
         }
         .pretui-artboard-handle::after {
           content: '';
-          width: 4px;
-          height: 30px;
-          border-radius: 4px;
-          background: var(--line-strong, var(--boxel-400));
+          width: var(--pretui-artboard-grip-w);
+          height: var(--pretui-artboard-grip-h);
+          border-radius: var(--boxel-border-radius-xs);
+          background-color: var(--border-strong);
         }
         .pretui-artboard-handle:hover::after {
-          background: var(--pretui-accent, var(--primary));
+          background-color: var(--primary-ink);
         }
         .pretui-bp-row {
           /* R3: the same specimen at every breakpoint, side by side */
           display: flex;
-          gap: 34px;
+          gap: var(--boxel-sp-2xl);
           align-items: flex-start;
           width: max-content;
           margin-inline: auto;
         }
-        .pretui-bp-row .pretui-artboard[data-bp='phone'] {
-          width: 375px;
-        }
-        .pretui-bp-row .pretui-artboard[data-bp='tablet'] {
-          width: 768px;
-        }
-        .pretui-bp-row .pretui-artboard[data-bp='desktop'] {
-          width: 1120px;
-        }
         .pretui-viewport-prose {
-          margin: 0;
           max-width: 62ch;
-          font-size: var(--text-body, 15px);
-          line-height: calc(var(--leading-body, 24px) / var(--text-body, 15px));
-          color: var(--foreground);
+          font-size: var(--boxel-body-font-size);
+          line-height: var(--boxel-body-line-height);
+        }
+        /* a block specimen (a toast, a segmented control) still sits on the
+           line instead of breaking the paragraph */
+        .pretui-viewport-inline {
+          display: inline-block;
+          max-width: 100%;
+          vertical-align: middle;
         }
         .pretui-viewport-grid {
           display: grid;
-          grid-template-columns: repeat(auto-fill, minmax(200px, 1fr));
-          gap: var(--space-4, 11px);
+          grid-template-columns: repeat(
+            auto-fill,
+            minmax(var(--pretui-viewport-tile-min-w), 1fr)
+          );
+          gap: var(--boxel-sp-sm);
         }
         .pretui-viewport-cell {
           display: flex;
           align-items: center;
           justify-content: center;
-          gap: var(--space-3, 8px);
+          gap: var(--boxel-sp-xs);
           flex-wrap: wrap;
-          background: var(--background);
-          border-radius: 8px;
+          background-color: var(--background);
+          border-radius: var(--boxel-border-radius-sm);
           box-shadow: 0 0 0 1px var(--border);
-          padding: var(--space-4, 11px);
-          min-height: 64px;
+          padding: var(--boxel-sp-sm);
+          min-height: var(--pretui-viewport-cell-min-h);
         }
       }
     </style>
diff --git a/packages/pretui/components/viewport.md b/packages/pretui/components/viewport.md
index cc57cc67eaf..1f08db8f487 100644
--- a/packages/pretui/components/viewport.md
+++ b/packages/pretui/components/viewport.md
@@ -6,15 +6,15 @@ The artboard: a framed stage that renders its content at a chosen device width,
 
 ```
 @defaultMode? 'fill' | 'phone' | 'tablet' | 'desktop' | 'bp' | 'inline' | 'grid' | 'narrow' | 'wide'
-@label?   — artboard caption; renders "Name · <width>"
+@label?   — the specimen's name, captioning a dragged width as "Name · <width>"; presets are captioned by mode
 <:default>
 ```
 
-**True widths that pan rather than clamp.** A `phone` artboard is genuinely 390px wide and the stage scrolls horizontally to show it, rather than scaling the content down or clamping to the available space. That is the difference between an artboard and a resized div: a clamped preview lies about what the component does at that width, and a scaled one lies about its type size.
+**True widths that pan rather than clamp.** A `phone` artboard is genuinely 320px wide and the stage scrolls horizontally to show it, rather than scaling the content down or clamping to the available space. That is the difference between an artboard and a resized div: a clamped preview lies about what the component does at that width, and a scaled one lies about its type size.
 
 **`bp` is a 3-up mode** — three breakpoints side by side, which is how you actually check a responsive component.
 
-**The caption is live**: `"Name · 390px"`, updating as the drag handle moves. An artboard whose label does not track its real width is worse than no label, because it invites you to trust it.
+**The caption is live**: `"Phone · 320px"` for a preset and `"Name · 412px"` once you drag, updating as the drag handle moves. An artboard whose label does not track its real width is worse than no label, because it invites you to trust it.
 
 **The drag handle uses pointer capture, not document listeners.** Same discipline as **Popover**'s backdrop and **SplitPanes**' handle: the element's lifetime is the interaction's lifetime, so there is nothing to leak and nothing to remove on teardown.
 
@@ -48,7 +48,7 @@ Gaps, and the first two are the ones that matter for a tool:
 
 ## Theming
 
-Stage and gutter surfaces (`--canvas` or `--inset`), the frame's `--border` and `--pretui-shadow-card`, `--muted-foreground` for the caption, and **SegmentedControl**'s tokens for the mode picker.
+Stage surfaces (`--background`, `--card`, `--inset`, and `--sidebar` / `--sidebar-foreground` / `--sidebar-border`), `--border` for frames and the canvas dots, `--shadow-sm` on the card surface, `--border-strong` for the resize grip, `--primary-ink` for the artboard caption and the hovered grip, `--muted-foreground` for the width readout and the Padding label, a translucent `--background` veil over the dot floor on the Background surface, and **SegmentedControl**'s tokens for the mode picker.
 
 **The stage is deliberately neutral** with explicit surface and gutter settings, because an artboard that shares the page's background makes the framed component's own surface invisible. A season must keep the stage distinguishable from `--card` — otherwise every example appears to float in nothing, which is exactly the illusion an artboard exists to prevent.
 
diff --git a/packages/pretui/viewport.test.gts b/packages/pretui/viewport.test.gts
index f11d8d31e53..968224432ac 100644
--- a/packages/pretui/viewport.test.gts
+++ b/packages/pretui/viewport.test.gts
@@ -14,6 +14,9 @@ function segButton(mode: string): HTMLElement {
   if (!target) throw new Error(`no viewport segment for ${mode}`);
   return target;
 }
+function artboard(): HTMLElement {
+  return document.querySelector('[data-test-pretui-artboard]') as HTMLElement;
+}
 
 module('Pretui | Viewport artboard', function (hooks) {
   setupCardTest(hooks);
@@ -23,28 +26,27 @@ module('Pretui | Viewport artboard', function (hooks) {
       <Viewport @label='Probe'><span>content</span></Viewport>
     </template>);
 
-    let artboard = () =>
-      document.querySelector('[data-test-pretui-artboard]') as HTMLElement;
     assert.strictEqual(
-      artboard().getAttribute('data-width'),
-      'fill',
-      'starts at fill',
+      artboard().getAttribute('data-label'),
+      'Fill · 100%',
+      'starts at fill, captioned as the full width',
     );
+    assert.strictEqual(artboard().style.width, '100%', 'fill is 100% wide');
 
     await click(segButton('tablet'));
     assert.strictEqual(
       artboard().style.width,
-      '768px',
-      'tablet artboard is exactly 768px',
+      '600px',
+      'tablet artboard is exactly 600px',
     );
     assert.strictEqual(
       artboard().getAttribute('data-label'),
-      'Probe · 768px',
-      'caption carries name and true width',
+      'Tablet · 600px',
+      'a device preset is captioned with the device and its true width',
     );
 
     await click(segButton('phone'));
-    assert.strictEqual(artboard().style.width, '375px', 'phone is 375px');
+    assert.strictEqual(artboard().style.width, '320px', 'phone is 320px');
   });
 
   test('R3: 3-up renders all three labeled breakpoints', async function (assert) {
@@ -52,13 +54,20 @@ module('Pretui | Viewport artboard', function (hooks) {
       <Viewport @label='Probe'><span>content</span></Viewport>
     </template>);
     await click(segButton('bp'));
-    let boards = document.querySelectorAll('[data-test-pretui-artboard]');
+    let boards = Array.from(
+      document.querySelectorAll('[data-test-pretui-artboard]'),
+    ) as HTMLElement[];
     assert.strictEqual(boards.length, 3, 'three artboards');
     assert.deepEqual(
-      Array.from(boards).map((b) => b.getAttribute('data-label')),
-      ['Phone · 375px', 'Tablet · 768px', 'Desktop · 1120px'],
+      boards.map((b) => b.getAttribute('data-label')),
+      ['Phone · 320px', 'Tablet · 600px', 'Desktop · 1120px'],
       'each labeled with its true width',
     );
+    assert.deepEqual(
+      boards.map((b) => b.style.width),
+      ['320px', '600px', '1120px'],
+      'each is exactly the width its caption states',
+    );
   });
 
   test('R2/R9: surface and gutter are explicit, reflected settings', async function (assert) {

From 95e28b05877cc8eeca99702ae8be25a0c8807779 Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Wed, 7 Oct 2026 17:54:20 -0400
Subject: [PATCH 08/30] Make ThemeFrame's mode a light/dark switch inside the
 PretComponent layer

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/components/theme-frame.gts | 258 +++++++--------------
 packages/pretui/components/theme-frame.md  |  44 ++--
 packages/pretui/theme-frame.test.gts       |  52 +++--
 3 files changed, 131 insertions(+), 223 deletions(-)

diff --git a/packages/pretui/components/theme-frame.gts b/packages/pretui/components/theme-frame.gts
index 57b36ba13a0..79675107acc 100644
--- a/packages/pretui/components/theme-frame.gts
+++ b/packages/pretui/components/theme-frame.gts
@@ -2,15 +2,15 @@
 import Component from '@glimmer/component';
 import { tracked } from '@glimmer/tracking';
 import type { TemplateOnlyComponent } from '@ember/component/template-only';
-import { on } from '@ember/modifier';
 import { guidFor } from '@ember/object/internals';
+import { Switch } from '@cardstack/boxel-ui/components';
 import { themeScope, themeScopedCss } from '@cardstack/boxel-ui/helpers';
+import Moon from '@cardstack/boxel-icons/moon';
+import Sun from '@cardstack/boxel-icons/sun';
 import { realmURL } from 'https://cardstack.com/base/card-api';
-import { Popover } from './popover';
 import { Select } from './select';
-import { SegmentedControl } from './segmented-control';
 
-// Wraps a page in a theme island with a Light/Dark/Auto switch, built the
+// Wraps a page in a theme island with a dark mode switch, built the
 // way the monorepo's own theme cards preview themselves (see
 // base/default-templates/theme-dashboard.gts). No custom theming code: the
 // outer div stamps data-theme, which theme.css translates into the
@@ -30,15 +30,8 @@ import { SegmentedControl } from './segmented-control';
 // and the element reset) which the frame then has to undo. The scoping
 // helpers are the part that was actually wanted.
 //
-// 'Auto' stamps no attribute, so the island follows the ambient host
-// scheme. Components never branch on dark — the flip is
-// entirely token re-resolution.
-
-const THEME_MODES = [
-  { value: 'auto', label: 'Auto' },
-  { value: 'light', label: 'Light' },
-  { value: 'dark', label: 'Dark' },
-];
+// Components never branch on dark — the flip is entirely token
+// re-resolution.
 
 interface ThemeLike {
   id?: string;
@@ -53,144 +46,84 @@ export interface ThemeFrameSignature {
   Args: {
     // the Theme card linked from the page card's cardInfo (model.cardTheme)
     theme?: ThemeLike | null;
-    // pass @context to enable the season selector: the frame queries the
-    // realm for every Theme instance so all shipped seasons are choosable
+    // pass @context to enable the theme selector: the frame queries the
+    // realm for every Theme instance so each one can be previewed
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
     context?: any;
-    // false hides the frame's own pill — for pages that place the yielded
-    // collapsed control in their own header instead
+    // false hides the frame's own bar — for pages that place the yielded
+    // controls in their own header instead
     bar?: boolean;
   };
-  // yields two header-seatable controls: [collapsed popover trigger,
-  // expanded inline segmented+select] — pages pick their presentation
+  // yields the controls (dark mode switch, and the theme select when the
+  // realm has more than one theme) for pages that seat them in a header
   // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  Blocks: { default: [any, any] };
+  Blocks: { default: [any] };
   Element: HTMLDivElement;
 }
 
-// The collapsed presentation: one small ◐ button; mode + season live in a
-// Popover that opens on demand.
-interface ThemePopoverControlsSignature {
+// The same switch the base ThemeDashboard's ModeToggle renders, so a theme
+// previews light and dark the way it does everywhere else in Boxel.
+interface ThemeControlsSignature {
   Args: { frame: ThemeFrame };
   Element: HTMLSpanElement;
 }
 
-// The expanded presentation: mode segmented + season select side by side,
-// for pages that give theme controls a permanent seat in their header.
-const ThemeInlineControls: TemplateOnlyComponent<ThemePopoverControlsSignature> =
-  <template>
-    <span class='pretui-theme-inline' data-test-pretui-theme-bar ...attributes>
-      <SegmentedControl
-        @options={{THEME_MODES}}
-        @value={{@frame.mode}}
-        @onValueChange={{@frame.setMode}}
-      />
-      {{#if @frame.showThemeSelect}}
-        <span class='pretui-theme-inline-pick'>
-          <Select
-            @options={{@frame.themeOptions}}
-            @value={{@frame.activeThemeId}}
-            @onValueChange={{@frame.pickTheme}}
-          />
-        </span>
-      {{/if}}
-    </span>
-    <style scoped>
-      @layer PretComponent {
-        .pretui-theme-inline {
-          display: inline-flex;
-          align-items: center;
-          gap: 8px;
-        }
-        .pretui-theme-inline-pick {
-          min-width: 170px;
-          font-size: var(--text-ui, 12px);
-        }
-      }
-    </style>
-  </template>
-;
+const ThemeControls: TemplateOnlyComponent<ThemeControlsSignature> = <template>
+  <span class='pretui-theme-controls' data-test-pretui-theme-bar ...attributes>
+    <Switch
+      @isEnabled={{@frame.isDarkMode}}
+      @onChange={{@frame.toggleDarkMode}}
+      @size='touch'
+      @checkedIcon={{Moon}}
+      @uncheckedIcon={{Sun}}
+      @label='Dark mode'
+      data-test-pretui-theme-mode
+    />
+    {{#if @frame.showThemeSelect}}
+      <span class='pretui-theme-pick' data-test-pretui-theme-pick>
+        <Select
+          @options={{@frame.themeOptions}}
+          @value={{@frame.activeThemeId}}
+          @onValueChange={{@frame.pickTheme}}
+          @label='Theme'
+        />
+      </span>
+    {{else if @frame.activeTheme}}
+      <span
+        class='pretui-theme-name'
+        data-test-pretui-theme-name
+      >{{@frame.themeName}}</span>
+    {{/if}}
+  </span>
+  <style scoped>
+    @layer PretComponent {
+      .pretui-theme-controls {
+        --pretui-theme-pick-min-w: 11.25rem;
 
-const ThemePopoverControls: TemplateOnlyComponent<ThemePopoverControlsSignature> =
-  <template>
-    <Popover @placement='bottom-end' @label='Theme' ...attributes>
-      <:trigger as |open toggle|>
-        <button
-          type='button'
-          class='pretui-theme-trigger'
-          data-state={{if open 'open'}}
-          title='Theme — {{@frame.themeName}}'
-          aria-label='Theme controls'
-          {{on 'click' toggle}}
-        >◐</button>
-      </:trigger>
-      <:default>
-        <div class='pretui-theme-pop' data-test-pretui-theme-bar>
-          <span class='pretui-theme-pop-cap'>Mode</span>
-          <SegmentedControl
-            @options={{THEME_MODES}}
-            @value={{@frame.mode}}
-            @onValueChange={{@frame.setMode}}
-          />
-          {{#if @frame.showThemeSelect}}
-            <span class='pretui-theme-pop-cap'>Season</span>
-            <Select
-              @options={{@frame.themeOptions}}
-              @value={{@frame.activeThemeId}}
-              @onValueChange={{@frame.pickTheme}}
-            />
-          {{else}}
-            <span class='pretui-theme-name'>{{@frame.themeName}}</span>
-          {{/if}}
-        </div>
-      </:default>
-    </Popover>
-    <style scoped>
-      @layer PretComponent {
-        .pretui-theme-trigger {
-          display: inline-flex;
-          align-items: center;
-          justify-content: center;
-          width: 26px;
-          height: 26px;
-          border: 0;
-          border-radius: var(--radius-chip, 6px);
-          background: transparent;
-          color: var(--muted-foreground);
-          font-size: 14px;
-          line-height: 1;
-          cursor: pointer;
-        }
-        .pretui-theme-trigger:hover,
-        .pretui-theme-trigger[data-state='open'] {
-          background: var(--hover, var(--boxel-100));
-          color: var(--foreground);
-        }
-        .pretui-theme-pop {
-          display: grid;
-          gap: 8px;
-          min-width: 210px;
-        }
-        .pretui-theme-pop-cap {
-          font-size: var(--text-ui-xs, 11px);
-          font-weight: 600;
-          letter-spacing: 0.06em;
-          text-transform: uppercase;
-          color: var(--muted-foreground);
-        }
-        .pretui-theme-name {
-          font-size: var(--text-ui, 12px);
-          color: var(--muted-foreground);
-        }
+        display: inline-flex;
+        align-items: center;
+        gap: var(--boxel-sp-xs);
       }
-    </style>
-  </template>
-;
+      .pretui-theme-pick {
+        min-width: var(--pretui-theme-pick-min-w);
+      }
+      .pretui-theme-name {
+        font-size: var(--boxel-font-size-xs);
+        color: var(--muted-foreground);
+        white-space: nowrap;
+      }
+    }
+  </style>
+</template>;
 
 export class ThemeFrame extends Component<ThemeFrameSignature> {
-  @tracked mode: string = 'auto';
+  // Starts light, like ThemeDashboard: the Boxel chrome around the island
+  // has fixed colors, so the switch previews dark rather than following the OS.
+  @tracked isDarkMode = false;
   @tracked selectedThemeId: string | undefined;
-  setMode = (v: string) => (this.mode = v);
+  // a toggle, not a setter: the Switch in the CLI test harness passes its
+  // click event to @onChange, not a boolean
+  toggleDarkMode = () => (this.isDarkMode = !this.isDarkMode);
   pickTheme = (v: string) => (this.selectedThemeId = v);
 
   // All Theme instances in the linked theme's realm. Absent context
@@ -246,7 +179,7 @@ export class ThemeFrame extends Component<ThemeFrameSignature> {
   }
 
   get dataTheme() {
-    return this.mode === 'auto' ? undefined : this.mode;
+    return this.isDarkMode ? 'dark' : 'light';
   }
   get themeCss() {
     return this.activeTheme?.cssVariables ?? undefined;
@@ -260,7 +193,7 @@ export class ThemeFrame extends Component<ThemeFrameSignature> {
     return themeScope(this.activeThemeId, this.themeCss) ?? guidFor(this);
   }
   get themeName() {
-    return this.activeTheme?.cardTitle ?? 'No theme';
+    return this.activeTheme?.cardTitle ?? 'Untitled theme';
   }
   get showBar() {
     return this.args.bar ?? true;
@@ -288,29 +221,11 @@ export class ThemeFrame extends Component<ThemeFrameSignature> {
           {{! template-lint-enable require-scoped-style }}
         {{/if}}
         {{#if this.showBar}}
-          <div class='pretui-theme-bar' data-test-pretui-theme-bar>
-            <SegmentedControl
-              @options={{THEME_MODES}}
-              @value={{this.mode}}
-              @onValueChange={{this.setMode}}
-            />
-            {{#if this.showThemeSelect}}
-              <div class='pretui-theme-pick'>
-                <Select
-                  @options={{this.themeOptions}}
-                  @value={{this.activeThemeId}}
-                  @onValueChange={{this.pickTheme}}
-                />
-              </div>
-            {{else}}
-              <span class='pretui-theme-name'>{{this.themeName}}</span>
-            {{/if}}
+          <div class='pretui-theme-bar'>
+            <ThemeControls @frame={{this}} />
           </div>
         {{/if}}
-        {{yield
-          (component ThemePopoverControls frame=this)
-          (component ThemeInlineControls frame=this)
-        }}
+        {{yield (component ThemeControls frame=this)}}
       </div>
     </div>
     <style scoped>
@@ -326,31 +241,20 @@ export class ThemeFrame extends Component<ThemeFrameSignature> {
         .pretui-theme-frame[data-theme='light'] {
           color-scheme: light;
         }
+        /* the island's tokens flip below the card's own surface, so the island
+           applies its own background, foreground and font, or the card's show
+           through */
         .pretui-theme-surface {
           min-height: 100%;
+          background-color: var(--canvas);
+          color: var(--foreground);
+          font-family: var(--font-sans);
         }
+        /* in-flow, not sticky: pages may carry their own sticky top bar */
         .pretui-theme-bar {
-          /* in-flow (not sticky): pages may carry their own sticky top bar
-             (the workbench format) and the bar must not collide with it.
-             No box of its own — the segmented control and select carry their
-             own rounded chrome, and wrapping rounded controls in another
-             rounded container reads as double chrome. */
-          display: flex;
-          align-items: center;
-          justify-content: flex-start;
-          gap: 8px;
           width: fit-content;
-          margin: 10px 0 0 10px;
-        }
-        .pretui-theme-name {
-          font-size: var(--text-ui, 12px);
-          letter-spacing: var(--track-ui, 0.01em);
-          color: var(--muted-foreground);
-          white-space: nowrap;
-        }
-        .pretui-theme-pick {
-          min-width: 180px;
-          font-size: var(--text-ui, 12px);
+          margin-block-start: var(--boxel-sp-xs);
+          margin-inline-start: var(--boxel-sp-xs);
         }
       }
     </style>
diff --git a/packages/pretui/components/theme-frame.md b/packages/pretui/components/theme-frame.md
index 7a30e6ea71d..73af2148718 100644
--- a/packages/pretui/components/theme-frame.md
+++ b/packages/pretui/components/theme-frame.md
@@ -1,48 +1,44 @@
 ## What it is
 
-The season switcher for a documentation or catalogue surface: it applies a theme to everything inside it and yields the controls for changing which one.
+The theme previewer for a documentation or catalog surface: it applies a theme to everything inside it, light or dark, and yields the controls for changing them.
 
-It is a tool, not a product control — a real application's theme setting belongs in its own settings surface. This exists so a reader can see any component under any season.
+It is a tool, not a product control — a real application's theme setting belongs in its own settings surface. This exists so a reader can see any component under any theme in the realm, in both modes.
 
 ## The contract
 
 ```
 @theme?   — the Theme card linked from the page card's cardInfo
-@context? — pass it to enable the season selector: the frame queries the realm
-            for every Theme instance, so all shipped seasons are choosable
-@bar?     — false hides the frame's own pill, for pages that place the yielded
-            control in their own header instead
+@context? — pass it to enable the theme selector: the frame queries the realm
+            for every Theme instance, so each one can be previewed
+@bar?     — false hides the frame's own bar, for pages that place the yielded
+            controls in their own header instead
 
-<:default> — yields TWO header-seatable controls:
-             [collapsed popover trigger, expanded inline segmented + select]
+<:default> — yields the controls: the dark mode switch, and the theme select
+             when the realm has more than one theme
 ```
 
-**The frame owns the switching state**: the light/dark/auto mode and the selected theme id live here, defaulting to `auto`. What it does not own is _persistence_ — nothing is written to storage, so a host that wants the choice to survive a reload stores it itself.
+**The mode switch is the one Boxel's ThemeDashboard uses**: a boxel-ui **Switch** labeled "Dark mode", with sun and moon icons. Off stamps `data-theme='light'` on the frame and on stamps `data-theme='dark'`, so the theme's light or dark variables apply through the same `--boxel-color-scheme` signal the host uses.
 
-**`@context` is the switch between one season and all of them.** Without it the frame dresses its content in `@theme` and offers only a mode toggle; with it, the frame queries the realm for every Theme instance and the season select appears.
+**The frame owns the switching state**: the mode and the selected theme id live here, starting light like ThemeDashboard. The Boxel chrome around the frame has fixed colors, so the switch previews dark mode rather than following the reader's system setting. What it does not own is _persistence_ — nothing is written to storage, so a host that wants the choice to survive a reload stores it itself.
 
-**It yields two presentations of the same controls, and the page picks one.** The collapsed form is a single trigger opening a **Popover**; the expanded form is an inline **SegmentedControl** plus a **Select**. A page with room seats the expanded one in its own header; a cramped one takes the trigger. `@bar={{false}}` is what stops the frame drawing its own pill when you have seated a yielded control elsewhere.
+**`@context` is the switch between one theme and all of them.** Without it the frame dresses its content in `@theme` and offers only the mode switch and the theme's name; with it, the frame queries the realm for every Theme instance and a **Select** replaces the name.
 
-## Prior art
+**`@bar={{false}}`** stops the frame drawing its own bar when the page seats the yielded controls in its own header.
 
-The theme switcher in every component-documentation site.
+## Prior art
 
-Where Pretui is better: yielding the controls rather than only rendering them. A switcher that can only appear where the frame is drawn forces every catalogue page into the same header layout; yielding both presentations lets the page decide, and `@bar` lets it opt out of the default entirely.
+The theme switcher in every component-documentation site, and Boxel's own ThemeDashboard, whose mode switch this reuses.
 
-Where it is thinner: no persistence, no per-component theme override, and no way to preview two seasons side by side — the frame dresses one subtree at a time.
+Where it is thinner: no persistence, no per-component theme override, and no way to preview two themes side by side — the frame dresses one subtree at a time.
 
 ## Accessibility
 
-- **Mode and season are real controls** — a **SegmentedControl** and a **Select** — so both are reachable and announced, in either presentation.
-- **The collapsed trigger carries the active theme's name in its title**, so what is currently applied is discoverable without opening the popover.
-- **The popover is the kit's**, so light-dismiss, Escape and focus return come with it.
-- **Changing season changes contrast across the whole subtree.** That is the component's purpose, and it means a catalogue can be put into a season whose tokens fail contrast — the frame applies what it is given and does not check it.
-- **`auto` follows the platform**, which is the right default: a reader who has set a system preference should not have to set it again to browse a catalogue.
+- **The mode switch is a native checkbox with `role='switch'`**, named "Dark mode", so it is reachable, announced with its on/off state, and toggled with Space or Enter.
+- **The theme select is named "Theme".**
+- **Changing theme changes contrast across the whole subtree.** That is the component's purpose, and it means a catalog can be put into a theme whose tokens fail contrast — the frame applies what it is given and does not check it.
 
 ## Theming
 
-The frame applies a theme rather than being themed by one — it is the component that establishes the token scope its subtree renders in, using boxel-ui's own theme helpers rather than hand-rolling the scoping.
-
-Its own chrome takes the kit's control and overlay tokens, which means the switcher itself is dressed by whichever season is active. That is deliberate and occasionally disorienting: switching to a low-contrast season restyles the control you switched with.
+The frame applies a theme rather than being themed by one — it establishes the token scope its subtree renders in, using boxel-ui's own theme helpers rather than hand-rolling the scoping.
 
-The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+Its own controls take the active theme's tokens, so the switch and select restyle with the theme they switch to.
diff --git a/packages/pretui/theme-frame.test.gts b/packages/pretui/theme-frame.test.gts
index 06901d148b0..29df7040323 100644
--- a/packages/pretui/theme-frame.test.gts
+++ b/packages/pretui/theme-frame.test.gts
@@ -26,18 +26,17 @@ function probeColor(): string {
   return getComputedStyle(probe).backgroundColor;
 }
 
-// The mode picker is a SegmentedControl: a radiogroup over native
-// <input type='radio'>. The helper accepts a tab shape too, so it survives
-// the theme bar being re-cut.
-async function clickMode(label: string) {
-  let candidates = Array.from(
-    document.querySelectorAll('[data-test-pretui-theme-bar] button, [data-test-pretui-theme-bar] label'),
-  );
-  let target = candidates.find((b) => b.textContent?.trim() === label);
-  if (!target) {
-    throw new Error(`no mode button labeled ${label}`);
+// The mode control is the dark mode switch: a checkbox with role='switch'.
+async function setDarkMode(on: boolean) {
+  let input = document.querySelector(
+    '[data-test-pretui-theme-mode] input',
+  ) as HTMLInputElement | null;
+  if (!input) {
+    throw new Error('no dark mode switch rendered');
+  }
+  if (input.checked !== on) {
+    await click(input);
   }
-  await click(target.querySelector('input') ?? target);
 }
 
 module('Pretui | ThemeFrame', function (hooks) {
@@ -56,22 +55,31 @@ module('Pretui | ThemeFrame', function (hooks) {
     assert.strictEqual(
       probeColor(),
       'rgb(10, 20, 30)',
-      'auto mode resolves the light token set',
+      'the frame starts light',
     );
+    assert
+      .dom('[data-test-pretui-theme-frame]')
+      .hasAttribute('data-theme', 'light', 'the frame stamps light, not an auto scheme');
 
-    await clickMode('Dark');
+    await setDarkMode(true);
     assert.strictEqual(
       probeColor(),
       'rgb(40, 50, 60)',
       'dark mode re-resolves the theme dark block — no component changed',
     );
+    assert
+      .dom('[data-test-pretui-theme-frame]')
+      .hasAttribute('data-theme', 'dark', 'dark mode stamps dark');
 
-    await clickMode('Light');
+    await setDarkMode(false);
     assert.strictEqual(
       probeColor(),
       'rgb(10, 20, 30)',
       'light mode forces the light set back on',
     );
+    assert
+      .dom('[data-test-pretui-theme-frame]')
+      .hasAttribute('data-theme', 'light', 'light mode stamps light');
   });
 
   test('frame without a theme still flips boxel-ui ambient tokens', async function (assert) {
@@ -85,7 +93,7 @@ module('Pretui | ThemeFrame', function (hooks) {
     </template>);
 
     let lightBg = probeColor();
-    await clickMode('Dark');
+    await setDarkMode(true);
     assert.notStrictEqual(
       probeColor(),
       lightBg,
@@ -146,13 +154,13 @@ module('Pretui | ThemeFrame · seasons', function (hooks) {
       </ThemeFrame>
     </template>);
 
-    await clickMode('Light');
+    await setDarkMode(false);
     let lightBg = probeBg();
     let lightPrimary = readVar('--primary');
     let lightFg = readVar('--foreground');
     assert.ok(lum(lightBg) > 0.9, `light --background is paper (${lightBg})`);
 
-    await clickMode('Dark');
+    await setDarkMode(true);
     let darkBg = probeBg();
     let darkPrimary = readVar('--primary');
     let darkFg = readVar('--foreground');
@@ -205,7 +213,7 @@ module('Pretui | ThemeFrame · seasons', function (hooks) {
           <div data-test-probe style='background: var(--primary)'>probe</div>
         </ThemeFrame>
       </template>);
-      await clickMode('Light');
+      await setDarkMode(false);
       seen.push(probeBg());
     }
     assert.strictEqual(
@@ -246,12 +254,12 @@ module('Pretui | ThemeFrame · season selector', function (hooks) {
       document.querySelector('[data-test-pretui-theme-bar]'),
       'the theme bar rendered — the selector branch does not throw',
     );
-    assert.dom('.pretui-theme-name').doesNotExist(
+    assert.dom('[data-test-pretui-theme-name]').doesNotExist(
       'with 3 themes found the static name is replaced by the picker',
     );
     assert.ok(
-      document.querySelector('.pretui-theme-pick'),
-      'the season picker is present',
+      document.querySelector('[data-test-pretui-theme-pick]'),
+      'the theme picker is present',
     );
   });
 
@@ -303,7 +311,7 @@ module('Pretui | ThemeFrame · season selector', function (hooks) {
         <div data-test-probe style='background: var(--primary)'>probe</div>
       </ThemeFrame>
     </template>);
-    assert.dom('.pretui-theme-name').hasText(
+    assert.dom('[data-test-pretui-theme-name]').hasText(
       'AW26',
       'prerender/test contexts still name the linked theme',
     );

From b6ec47d7685b66c549a4cd1f9e4c00f1af05c7a6 Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Wed, 7 Oct 2026 17:54:22 -0400
Subject: [PATCH 09/30] Rebuild the usage page shell on the theme contract with
 real headings and labeled knobs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/README.md                     |   2 +-
 .../pretui/components/freestyle-usage.gts     | 247 +++++++++---------
 packages/pretui/components/freestyle-usage.md |   4 +-
 packages/pretui/components/usage-argument.gts |  89 +++----
 packages/pretui/components/usage-number.gts   |  32 +--
 packages/pretui/components/usage-object.gts   |  14 +-
 packages/pretui/components/usage-string.gts   |   1 +
 packages/pretui/internal/freestyle.gts        |  62 ++---
 packages/pretui/scripts/usage-proof.mjs       |   8 +-
 9 files changed, 230 insertions(+), 229 deletions(-)

diff --git a/packages/pretui/README.md b/packages/pretui/README.md
index dce349004ca..b9f134e47e1 100644
--- a/packages/pretui/README.md
+++ b/packages/pretui/README.md
@@ -37,7 +37,7 @@ Every component's `<style scoped>` content sits in one of two layers, so a calle
 
 Rules that restyle a boxel-ui component whose own CSS is unlayered stay outside the layer, since unlayered CSS beats any layer. Select is the one case: BoxelSelect's trigger and option styles are unlayered.
 
-The `Pret` prefix matters because layer names are document-global. Usage pages, example galleries, `pretui-component.gts` and `pretui-note.gts` stay unlayered: they are callers of the kit, and their styles win the way any caller's do.
+The `Pret` prefix matters because layer names are document-global. Usage pages and their shell (`freestyle-usage`, the `usage-*` argument rows and `internal/freestyle`), example galleries, `pretui-component.gts` and `pretui-note.gts` stay unlayered: they are callers of the kit, and their styles win the way any caller's do.
 
 ## Development
 
diff --git a/packages/pretui/components/freestyle-usage.gts b/packages/pretui/components/freestyle-usage.gts
index cf2d2ff6dd2..07e67424d12 100644
--- a/packages/pretui/components/freestyle-usage.gts
+++ b/packages/pretui/components/freestyle-usage.gts
@@ -50,23 +50,23 @@ export interface FreestyleUsageSignature {
 
 export const FreestyleUsage: TemplateOnlyComponent<FreestyleUsageSignature> =
   <template>
-    <div class='FreestyleUsage' data-test-pretui-usage ...attributes>
+    <div class='pretui-usage' data-test-pretui-usage ...attributes>
       {{! identity lives in the page header (breadcrumb) — no h2 here; one
           compact description line, then straight to the artboard }}
       {{#if (has-block 'description')}}
         <p
-          class='FreestyleUsage-description'
+          class='pretui-usage-description'
           data-test-pretui-usage-description
         >{{yield to='description'}}</p>
       {{else if @description}}
         <p
-          class='FreestyleUsage-description'
+          class='pretui-usage-description'
           data-test-pretui-usage-description
         >{{@description}}</p>
       {{/if}}
 
-      <div class='FreestyleUsage-stage'>
-        <div class='FreestyleUsage-previewCol'>
+      <div class='pretui-usage-stage'>
+        <div class='pretui-usage-preview-col'>
           <div class='wb-panel'>
             <Viewport @defaultMode={{@viewportMode}} @label={{@name}}>
               {{yield to='example'}}
@@ -87,11 +87,14 @@ export const FreestyleUsage: TemplateOnlyComponent<FreestyleUsageSignature> =
           </div>
         </div>
         {{#if (has-block 'api')}}
-          <aside class='FreestyleUsage-props' data-test-pretui-usage-props>
-            <h3
-              class='FreestyleUsage-sectionTitle'
+          <aside
+            class='pretui-usage-props wb-panel'
+            data-test-pretui-usage-props
+          >
+            <h2
+              class='pretui-usage-section-title'
               data-test-pretui-usage-section-title
-            >Properties</h3>
+            >Properties</h2>
             {{yield
               (hash
                 Action=(component UsageAction mode='prop')
@@ -117,14 +120,14 @@ export const FreestyleUsage: TemplateOnlyComponent<FreestyleUsageSignature> =
       </div>
 
       {{#if (has-block 'api')}}
-        <div class='FreestyleUsage-api wb-panel' data-test-pretui-usage-api>
+        <div class='pretui-usage-api wb-panel' data-test-pretui-usage-api>
           <div class='wb-panel-h'>
-            <h3
-              class='FreestyleUsage-sectionTitle wb-cap'
+            <h2
+              class='pretui-usage-section-title wb-cap'
               data-test-pretui-usage-section-title
-            >API</h3>
+            >API</h2>
           </div>
-          <Table>
+          <Table @framed={{false}}>
             <:head>
               <tr>
                 <th>Argument</th>
@@ -154,14 +157,14 @@ export const FreestyleUsage: TemplateOnlyComponent<FreestyleUsageSignature> =
       {{/if}}
 
       {{#if (has-block 'cssVars')}}
-        <div class='FreestyleUsage-api wb-panel' data-test-pretui-usage-css-vars>
+        <div class='pretui-usage-api wb-panel' data-test-pretui-usage-css-vars>
           <div class='wb-panel-h'>
-            <h3
-              class='FreestyleUsage-sectionTitle wb-cap'
+            <h2
+              class='pretui-usage-section-title wb-cap'
               data-test-pretui-usage-section-title
-            >CSS Variables</h3>
+            >CSS Variables</h2>
           </div>
-          <Table>
+          <Table @framed={{false}}>
             <:head>
               <tr>
                 <th>Variable</th>
@@ -181,112 +184,106 @@ export const FreestyleUsage: TemplateOnlyComponent<FreestyleUsageSignature> =
       {{/if}}
     </div>
     <style scoped>
-      @layer PretComponent {
-        .FreestyleUsage {
-          display: grid;
-          gap: var(--space-3, 8px);
-          align-content: start;
-          min-width: 0;
-          max-width: 100%;
-        }
-        .FreestyleUsage-description {
-          margin: 0;
-          max-width: 78ch;
-          font-size: var(--text-ui-md, 12.5px);
-          color: var(--muted-foreground);
-          line-height: 1.5;
-        }
-        .FreestyleUsage-stage {
-          display: grid;
-          grid-template-columns: minmax(0, 1fr) 280px;
-          gap: var(--space-5, 14px);
-          align-items: start;
-        }
-        @media (max-width: 900px) {
-          .FreestyleUsage-stage {
-            grid-template-columns: minmax(0, 1fr);
-          }
-        }
-        .FreestyleUsage-previewCol {
-          display: grid;
-          gap: var(--space-3, 8px);
-          min-width: 0;
-        }
-        /* workbench panel chrome: bordered card, header row, clipped body */
-        .wb-panel {
-          background: var(--card);
-          border-radius: 6px;
-          box-shadow: var(--pretui-shadow-hairline, 0 0 0 1px var(--border));
-          overflow: hidden;
-          min-width: 0;
-        }
-        .wb-panel-h {
-          display: flex;
-          align-items: center;
-          gap: 10px;
-          min-height: 36px;
-          padding: 8px var(--space-4, 11px);
-          box-shadow: inset 0 -1px 0 var(--border);
-        }
-        h3.wb-cap {
-          margin: 0;
-        }
-        .wb-th-right {
-          text-align: right;
-        }
-        .wb-codestrip {
-          display: flex;
-          align-items: center;
-          gap: var(--space-4, 11px);
-          padding: 6px var(--space-4, 11px);
-          box-shadow: inset 0 1px 0 var(--border);
-          background: var(--card);
-          overflow-x: auto;
-        }
-        .wb-code {
-          font-family: var(--font-mono);
-          font-size: var(--text-ui, 12px);
-          color: var(--muted-foreground);
-          white-space: pre;
-          flex: 1;
-        }
-        .wb-codestrip > :last-child {
-          flex: none;
-          margin-left: auto;
-        }
-        .FreestyleUsage-props {
-          background: var(--card);
-          border-radius: 6px;
-          box-shadow: var(--pretui-shadow-hairline, 0 0 0 1px var(--border));
-          padding: var(--space-4, 11px) var(--space-5, 14px)
-            var(--space-5, 14px);
-          min-width: 0;
-          align-self: start;
-          position: sticky;
-          top: 52px;
-        }
-        /* THE caps treatment — panel and group headers only */
-        .FreestyleUsage-sectionTitle {
-          margin: 0 0 var(--space-3, 8px);
-          font-size: var(--text-ui-xs, 11px);
-          font-weight: 600;
-          letter-spacing: 0.06em;
-          text-transform: uppercase;
-          color: var(--muted-foreground);
-        }
-        .FreestyleUsage-api {
-          min-width: 0;
-        }
-        .FreestyleUsage-source {
-          margin: 0;
-          font-family: var(--font-mono);
-          font-size: var(--text-ui-sm, 11.5px);
-          background: var(--inset, var(--boxel-100));
-          border-radius: var(--radius);
-          box-shadow: inset 0 0 0 1px var(--border);
-          padding: var(--space-4, 11px);
-          overflow-x: auto;
-        }
+      .pretui-usage {
+        --pretui-usage-props-w: 22rem;
+        --pretui-usage-panel-h: 2.25rem;
+        --pretui-usage-description-max-w: 64rem;
+
+        display: grid;
+        gap: var(--boxel-sp-xs);
+        align-content: start;
+        min-width: 0;
+        max-width: 100%;
+      }
+      .pretui-usage-description {
+        max-inline-size: var(--pretui-usage-description-max-w);
+        color: var(--muted-foreground);
+      }
+      /* the Properties rail wraps under the preview when the preview would
+         drop below 60% of the row, so it needs no viewport or container
+         query (a container would also capture the examples' fixed popups) */
+      .pretui-usage-stage {
+        display: flex;
+        flex-wrap: wrap;
+        gap: var(--boxel-sp);
+        /* the props panel is at least as tall as the preview beside it */
+        align-items: stretch;
+      }
+      .pretui-usage-stage > .pretui-usage-preview-col {
+        flex: 999 1 0;
+        min-inline-size: 60%;
+        align-self: start;
+      }
+      /* never narrower than its width: the row stacks first */
+      .pretui-usage-stage > .pretui-usage-props {
+        flex: 1 1 var(--pretui-usage-props-w);
+        /* capped at the row, so a stacked panel on a narrow screen still fits */
+        min-inline-size: min(var(--pretui-usage-props-w), 100%);
+      }
+      .pretui-usage-preview-col {
+        display: grid;
+        gap: var(--boxel-sp-xs);
+      }
+      /* workbench panel chrome: bordered card, header row, clipped body */
+      .wb-panel {
+        background-color: var(--card);
+        color: var(--card-foreground);
+        border-radius: var(--boxel-border-radius);
+        box-shadow: 0 0 0 1px var(--border);
+        overflow: hidden;
+        min-width: 0;
+      }
+      .wb-panel-h {
+        display: flex;
+        align-items: center;
+        gap: var(--boxel-sp-xs);
+        min-height: var(--pretui-usage-panel-h);
+        padding: var(--boxel-sp-xs) var(--boxel-sp-sm);
+        box-shadow: inset 0 -1px 0 var(--border);
+      }
+      .wb-th-right {
+        text-align: end;
+      }
+      .wb-codestrip {
+        display: flex;
+        align-items: center;
+        gap: var(--boxel-sp-sm);
+        padding: var(--boxel-sp-2xs) var(--boxel-sp-sm);
+        box-shadow: inset 0 1px 0 var(--border);
+        overflow-x: auto;
+      }
+      .wb-code {
+        font-family: var(--font-mono);
+        font-size: var(--boxel-font-size-xs);
+        color: var(--muted-foreground);
+        white-space: pre;
+        flex: 1;
+      }
+      .wb-codestrip > :last-child {
+        flex: none;
+        margin-inline-start: auto;
+      }
+      /* a wb-panel that keeps its controls' focus rings and menus unclipped */
+      .pretui-usage-props {
+        padding: var(--boxel-sp-sm) var(--boxel-sp) var(--boxel-sp);
+        overflow: visible;
+      }
+      /* THE caps treatment — panel and group headers only */
+      .pretui-usage-section-title {
+        margin-block-end: var(--boxel-sp-xs);
+        font-family: var(--boxel-eyebrow-font-family);
+        font-size: var(--boxel-eyebrow-font-size);
+        font-weight: var(--boxel-eyebrow-font-weight);
+        line-height: var(--boxel-eyebrow-line-height);
+        letter-spacing: var(--boxel-eyebrow-letter-spacing);
+        text-transform: uppercase;
+        color: var(--muted-foreground);
+      }
+      .wb-cap {
+        margin-block-end: 0;
+      }
+      .pretui-usage-api {
+        min-width: 0;
       }
     </style>
   </template>;
diff --git a/packages/pretui/components/freestyle-usage.md b/packages/pretui/components/freestyle-usage.md
index 96bfc245406..9875b4a3cc5 100644
--- a/packages/pretui/components/freestyle-usage.md
+++ b/packages/pretui/components/freestyle-usage.md
@@ -35,7 +35,7 @@ No pattern governs it; it is a page composed of the kit's own components, and it
 
 Gaps worth knowing, because a documentation surface is read by exactly the people who care about these:
 
-- **The page's regions have no landmark or heading structure of their own.** Description, example, knobs, API table and source are four or five regions with no `role`, no `aria-label` and — verify — possibly no headings. A screen-reader user cannot jump between "the example" and "the API table". For a docs page that is the single most useful thing to add.
+- **Only part of the page has heading structure.** Properties, API and CSS Variables are headed by `h2`s, so heading navigation reaches the knobs and the tables, and Properties is an `<aside>`. The description and the example have no heading, and no region carries an `aria-label`, so a screen-reader user cannot jump to "the example", and landmark navigation finds an unnamed complementary region.
 - **`@name` is not necessarily a heading**, and if it is, its level is fixed — the kit-wide problem (**Panel**, **Toolbar**, **EmptyState**, **Stat**, **FittedCard** all share it).
 - **The knobs and the API table describe the same arguments and are not linked.** A user reading a row in the docs table has no route to the control that changes it.
 - **The `<pre>` source block** needs `tabindex="0"` if it scrolls, or a keyboard user cannot reach the end of a long line (**WCAG 2.1.1**), and it has no language annotation.
@@ -47,5 +47,3 @@ Gaps worth knowing, because a documentation surface is read by exactly the peopl
 Composes **Viewport**, **Table**, **Select**, **Input**, **Switch**, **Slider**, **SegmentedControl**, **CopyButton** and **Popover**, so it consumes their token sets rather than defining many of its own. Page structure uses `--card`, `--inset`, `--border`, `--foreground`, `--muted-foreground` and the type scale; the property list and API table pick up **Label**'s eyebrow voice.
 
 The whole page renders inside the theme island, so a season change re-dresses both the documentation chrome _and_ the example — which is the point, and is what **ThemeFrame** exists to drive.
-
-The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
diff --git a/packages/pretui/components/usage-argument.gts b/packages/pretui/components/usage-argument.gts
index 6887e1029c8..4806a4425d5 100644
--- a/packages/pretui/components/usage-argument.gts
+++ b/packages/pretui/components/usage-argument.gts
@@ -44,20 +44,20 @@ export class UsageArgument extends Component<UsageArgumentSignature> {
   }
   <template>
     {{#if this.isDoc}}
-      <tr class='FreestyleUsageArgument' data-test-pretui-usage-arg>
-        <td class='FreestyleUsageArgument-name'>
-          <span class='u-sig'>{{this.sigilPre}}</span>{{#if @name}}{{@name}}{{/if}}<span
-            class='u-sig'
-          >{{this.sigilPost}}</span>
+      <tr class='pretui-usage-arg' data-test-pretui-usage-arg>
+        <td class='pretui-usage-arg-name'>
+          <span class='u-sig'>{{this.sigilPre}}</span>{{#if
+            @name
+          }}{{@name}}{{/if}}<span class='u-sig'>{{this.sigilPost}}</span>
           {{#if @required}}<span
               class='u-req'
               title='Required'
               data-test-pretui-usage-arg-required
             >*</span>{{/if}}
         </td>
-        <td class='FreestyleUsageArgument-type'>{{this.typeLabel}}</td>
-        <td class='FreestyleUsageArgument-description'>{{@description}}</td>
-        <td class='FreestyleUsageArgument-default'>
+        <td class='pretui-usage-arg-type'>{{this.typeLabel}}</td>
+        <td class='pretui-usage-arg-description'>{{@description}}</td>
+        <td class='pretui-usage-arg-default'>
           {{#if this.shouldRenderDefaultValue}}
             {{this.defaultText}}
           {{else}}
@@ -67,42 +67,43 @@ export class UsageArgument extends Component<UsageArgumentSignature> {
       </tr>
     {{/if}}
     <style scoped>
-      @layer PretComponent {
-        .FreestyleUsageArgument-name {
-          font-family: var(--font-mono);
-          font-size: var(--text-ui, 12px);
-          white-space: nowrap;
-          width: 1%;
-        }
-        .u-sig {
-          color: var(--ink-3, var(--boxel-400));
-        }
-        .u-req {
-          color: var(--pretui-destructive-ink, var(--boxel-danger));
-        }
-        .FreestyleUsageArgument-type {
-          font-family: var(--font-mono);
-          font-size: var(--text-ui, 12px);
-          color: var(--muted-foreground);
-          white-space: nowrap;
-          width: 1%;
-          text-transform: lowercase;
-        }
-        .FreestyleUsageArgument-description {
-          color: var(--foreground);
-          max-width: 520px;
-        }
-        .FreestyleUsageArgument-default {
-          font-family: var(--font-mono);
-          font-size: var(--text-ui, 12px);
-          color: var(--muted-foreground);
-          text-align: right;
-          white-space: nowrap;
-          width: 1%;
-        }
-        .u-none {
-          color: var(--ink-3, var(--boxel-400));
-        }
+      .pretui-usage-arg {
+        --pretui-usage-arg-description-max-w: 32.5rem;
+      }
+      .pretui-usage-arg-name {
+        font-family: var(--font-mono);
+        font-size: var(--boxel-font-size-xs);
+        white-space: nowrap;
+        width: 1%;
+      }
+      .u-sig {
+        color: var(--muted-foreground);
+      }
+      .u-req {
+        color: var(--destructive-ink);
+      }
+      .pretui-usage-arg-type {
+        font-family: var(--font-mono);
+        font-size: var(--boxel-font-size-xs);
+        color: var(--muted-foreground);
+        white-space: nowrap;
+        width: 1%;
+        text-transform: lowercase;
+      }
+      .pretui-usage-arg-description {
+        color: var(--foreground);
+        max-width: var(--pretui-usage-arg-description-max-w);
+      }
+      .pretui-usage-arg-default {
+        font-family: var(--font-mono);
+        font-size: var(--boxel-font-size-xs);
+        color: var(--muted-foreground);
+        text-align: end;
+        white-space: nowrap;
+        width: 1%;
+      }
+      .u-none {
+        color: var(--muted-foreground);
       }
     </style>
   </template>
diff --git a/packages/pretui/components/usage-number.gts b/packages/pretui/components/usage-number.gts
index c8e3737b883..b39ff4a71a1 100644
--- a/packages/pretui/components/usage-number.gts
+++ b/packages/pretui/components/usage-number.gts
@@ -90,22 +90,22 @@ export class UsageNumber extends Component<UsageNumberSignature> {
       />
     {{/if}}
     <style scoped>
-      @layer PretComponent {
-        .numrange {
-          display: flex;
-          align-items: center;
-          gap: 8px;
-        }
-        .numrange > :first-child {
-          flex: 1;
-        }
-        .numrange-readout {
-          font-family: var(--font-mono);
-          font-size: var(--text-ui-sm, 11.5px);
-          min-width: 30px;
-          text-align: right;
-          font-variant-numeric: tabular-nums;
-        }
+      .numrange {
+        --numrange-readout-min-w: 1.875rem;
+
+        display: flex;
+        align-items: center;
+        gap: var(--boxel-sp-xs);
+      }
+      .numrange > :first-child {
+        flex: 1;
+      }
+      .numrange-readout {
+        font-family: var(--font-mono);
+        font-size: var(--boxel-font-size-xs);
+        min-width: var(--numrange-readout-min-w);
+        text-align: end;
+        font-variant-numeric: tabular-nums;
       }
     </style>
   </template>
diff --git a/packages/pretui/components/usage-object.gts b/packages/pretui/components/usage-object.gts
index ed5ab64ea12..24dc9efb9c3 100644
--- a/packages/pretui/components/usage-object.gts
+++ b/packages/pretui/components/usage-object.gts
@@ -67,14 +67,12 @@ export class UsageObject extends Component<UsageObjectSignature> {
       />
     {{/if}}
     <style scoped>
-      @layer PretComponent {
-        /* JsonTree brings its own surface; the knob channel is all that is
-           needed here. */
-        .jsonviewer {
-          --pretui-json-max-height: 120px;
-          --pretui-json-indent: 12px;
-          --pretui-json-row-height: 20px;
-        }
+      /* JsonTree brings its own surface; the knob channel is all that is
+         needed here. */
+      .jsonviewer {
+        --pretui-json-max-height: 7.5rem;
+        --pretui-json-indent: var(--boxel-sp-sm);
+        --pretui-json-row-height: 1.25rem;
       }
     </style>
   </template>
diff --git a/packages/pretui/components/usage-string.gts b/packages/pretui/components/usage-string.gts
index b791c016cfd..229ba572878 100644
--- a/packages/pretui/components/usage-string.gts
+++ b/packages/pretui/components/usage-string.gts
@@ -52,6 +52,7 @@ export class UsageString extends Component<UsageStringSignature> {
                 @options={{this.selectOptions}}
                 @value={{this.valueStr}}
                 @onValueChange={{this.callOnInput}}
+                @label={{@name}}
               />
             {{else}}
               <Input
diff --git a/packages/pretui/internal/freestyle.gts b/packages/pretui/internal/freestyle.gts
index b4e4c6c3b36..6fa7feddbdb 100644
--- a/packages/pretui/internal/freestyle.gts
+++ b/packages/pretui/internal/freestyle.gts
@@ -37,27 +37,27 @@ export const PropRow: TemplateOnlyComponent<PropRowSignature> = <template>
     <span class='proprow-control'>{{yield}}</span>
   </div>
   <style scoped>
-    @layer PretComponent {
-      /* workbench inspector row: label rail left, control right */
-      .proprow {
-        display: grid;
-        grid-template-columns: 76px minmax(0, 1fr);
-        gap: 10px;
-        align-items: center;
-        padding: 4px 0;
-      }
-      .proprow-label {
-        font-family: var(--font-mono);
-        font-size: var(--text-ui, 12px);
-        color: var(--muted-foreground);
-        overflow-wrap: anywhere;
-      }
-      .proprow-req {
-        color: var(--pretui-destructive-ink, var(--boxel-danger));
-      }
-      .proprow-control {
-        min-width: 0;
-      }
+    /* workbench inspector row: label rail left, control right */
+    .proprow {
+      --proprow-label-w: 8rem;
+
+      display: grid;
+      grid-template-columns: var(--proprow-label-w) minmax(0, 1fr);
+      gap: var(--boxel-sp-xs);
+      align-items: center;
+      padding-block: var(--boxel-sp-3xs);
+    }
+    .proprow-label {
+      font-family: var(--font-mono);
+      font-size: var(--boxel-font-size-xs);
+      color: var(--muted-foreground);
+      overflow-wrap: break-word;
+    }
+    .proprow-req {
+      color: var(--destructive-ink);
+    }
+    .proprow-control {
+      min-width: 0;
     }
   </style>
 </template>;
@@ -67,22 +67,24 @@ interface PropReadOnlySignature {
   Element: HTMLSpanElement;
 }
 
-export const PropReadOnly: TemplateOnlyComponent<PropReadOnlySignature> = <template>
-  <span class='proprow-readonly' data-test-pretui-prop-readonly>{{@value}}</span>
-  <style scoped>
-    @layer PretComponent {
+export const PropReadOnly: TemplateOnlyComponent<PropReadOnlySignature> =
+  <template>
+    <span
+      class='proprow-readonly'
+      data-test-pretui-prop-readonly
+    >{{@value}}</span>
+    <style scoped>
       .proprow-readonly {
         display: block;
         min-width: 0;
-        overflow-wrap: anywhere;
+        overflow-wrap: break-word;
         color: var(--muted-foreground);
         font-family: var(--font-mono);
-        font-size: var(--text-ui-sm, 11.5px);
+        font-size: var(--boxel-font-size-xs);
         line-height: 1.4;
       }
-    }
-  </style>
-</template>;
+    </style>
+  </template>;
 // ── Action / Yield / Component presets (doc-only rows) ───────────────────
 export interface UsagePresetSignature {
   Args: {
diff --git a/packages/pretui/scripts/usage-proof.mjs b/packages/pretui/scripts/usage-proof.mjs
index 7e4a09101ad..3e4d1c32411 100644
--- a/packages/pretui/scripts/usage-proof.mjs
+++ b/packages/pretui/scripts/usage-proof.mjs
@@ -57,7 +57,9 @@ function registries() {
 }
 
 function render(list) {
-  let imports = list.map((r) => `import { ${r.name} } from '${r.module}';`).join('\n');
+  let imports = list
+    .map((r) => `import { ${r.name} } from '${r.module}';`)
+    .join('\n');
   let names = list.map((r) => `  ${r.name},`).join('\n');
   return `// Pretui — render proof: every usage page in the package mounts. Generated by
 // \`node scripts/usage-proof.mjs --write\`; \`pnpm lint\` fails when a page module
@@ -109,7 +111,9 @@ if (process.argv.includes('--write')) {
     // reported below
   }
   if (actual !== expected) {
-    console.error('usage-pages.test.gts is out of date: run `node scripts/usage-proof.mjs --write`.');
+    console.error(
+      'usage-pages.test.gts is out of date: run `node scripts/usage-proof.mjs --write`.',
+    );
     process.exit(1);
   }
 }

From d00a4b4d8ba2509215a7044e64930e2fd21135a7 Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Wed, 7 Oct 2026 17:54:24 -0400
Subject: [PATCH 10/30] Bring the Pret UI Spec page, its example gallery and
 the Note card onto the theme contract

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/example-gallery.gts       |   66 +-
 packages/pretui/pretui-component.gts      | 1089 +++++++++++----------
 packages/pretui/pretui-component.test.gts |    2 +-
 packages/pretui/pretui-note.gts           |  354 +++----
 packages/pretui/pretui-note.test.gts      |    6 +-
 5 files changed, 776 insertions(+), 741 deletions(-)

diff --git a/packages/pretui/example-gallery.gts b/packages/pretui/example-gallery.gts
index 81806ecd477..2ba6f4c807e 100644
--- a/packages/pretui/example-gallery.gts
+++ b/packages/pretui/example-gallery.gts
@@ -17,7 +17,7 @@ export class ExampleGallery extends Component<{
     {{#if this.specs}}
       <section class='exg' data-test-pretui-examples>
         <header class='exg-h'>
-          <span class='exg-cap'>Examples</span>
+          <h2 class='exg-cap'>Examples</h2>
           <span class='exg-count'>{{this.countLabel}}</span>
         </header>
         <div class='exg-grid'>
@@ -28,7 +28,9 @@ export class ExampleGallery extends Component<{
               </div>
               <div class='exg-meta'>
                 <span class='exg-title'>{{spec.title}}</span>
-                {{#if spec.note}}<span class='exg-note'>{{spec.note}}</span>{{/if}}
+                {{#if spec.note}}<span
+                    class='exg-note'
+                  >{{spec.note}}</span>{{/if}}
               </div>
             </div>
           {{/each}}
@@ -37,62 +39,78 @@ export class ExampleGallery extends Component<{
     {{/if}}
     <style scoped>
       .exg {
+        --_exg-tile-min-w: 18.75rem;
+        --_exg-demo-shadow-room: var(--boxel-sp-sm);
+
         display: grid;
-        gap: var(--space-4, 11px);
+        gap: var(--boxel-sp-sm);
         align-content: start;
       }
       .exg-h {
         display: flex;
         align-items: baseline;
-        gap: 8px;
+        gap: var(--boxel-sp-xs);
       }
       /* THE caps treatment — one per page region (workbench type spec) */
       .exg-cap {
-        font-size: var(--text-ui-xs, 11px);
-        font-weight: 600;
-        letter-spacing: 0.06em;
+        font-family: var(--boxel-eyebrow-font-family);
+        font-size: var(--boxel-eyebrow-font-size);
+        font-weight: var(--boxel-eyebrow-font-weight);
+        line-height: var(--boxel-eyebrow-line-height);
+        letter-spacing: var(--boxel-eyebrow-letter-spacing);
         text-transform: uppercase;
         color: var(--muted-foreground);
       }
       .exg-count {
-        font-size: var(--text-ui, 12px);
-        color: var(--ink-3, var(--boxel-400));
+        font-size: var(--boxel-caption-font-size);
+        color: var(--muted-foreground);
       }
       .exg-grid {
         display: grid;
-        grid-template-columns: repeat(auto-fill, minmax(300px, 1fr));
-        gap: var(--space-4, 11px);
+        grid-template-columns: repeat(
+          auto-fill,
+          minmax(var(--_exg-tile-min-w), 1fr)
+        );
+        gap: var(--boxel-sp-sm);
         align-items: stretch;
       }
       .exg-card {
-        background: var(--card);
-        border-radius: 6px;
-        box-shadow: var(--pretui-shadow-hairline, 0 0 0 1px var(--border));
-        padding: var(--space-4, 11px);
+        background-color: var(--card);
+        color: var(--card-foreground);
+        border-radius: var(--boxel-border-radius);
+        box-shadow: 0 0 0 1px var(--border);
+        padding: var(--boxel-sp-sm);
+        /* each card takes two of the grid's rows as a subgrid, so the demo
+           and meta rows line up across every card in a row */
         display: grid;
-        grid-template-rows: 1fr auto;
-        gap: 10px;
+        grid-row: span 2;
+        grid-template-rows: subgrid;
+        /* at least the demo's shadow room, so its clip box stops short of
+           the meta row */
+        gap: var(--_exg-demo-shadow-room);
         min-width: 0;
       }
+      /* clips a wide demo, with a margin of room so a demo's own shadow
+         isn't cut off; the negative margin keeps the layout where it was */
       .exg-demo {
         min-width: 0;
         align-self: center;
-        padding: 4px 0;
+        margin: calc(-1 * var(--_exg-demo-shadow-room));
+        padding: var(--_exg-demo-shadow-room);
         overflow: hidden;
       }
       .exg-meta {
         display: grid;
-        gap: 2px;
-        padding-top: 8px;
+        gap: var(--boxel-sp-6xs);
+        padding-block-start: var(--boxel-sp-xs);
         box-shadow: inset 0 1px 0 var(--border);
       }
       .exg-title {
-        font-size: var(--text-ui, 12px);
-        font-weight: 500;
-        color: var(--foreground);
+        font-size: var(--boxel-caption-font-size);
+        font-weight: var(--boxel-caption-font-weight);
       }
       .exg-note {
-        font-size: var(--text-ui, 12px);
+        font-size: var(--boxel-caption-font-size);
         color: var(--muted-foreground);
       }
     </style>
diff --git a/packages/pretui/pretui-component.gts b/packages/pretui/pretui-component.gts
index 07cf0f71c77..c865ceaf5aa 100644
--- a/packages/pretui/pretui-component.gts
+++ b/packages/pretui/pretui-component.gts
@@ -17,23 +17,26 @@ import {
 } from 'https://cardstack.com/base/card-api';
 import { Spec } from 'https://cardstack.com/base/spec';
 import { MarkdownDef } from 'https://cardstack.com/base/markdown-file-def';
+import { MarkdownPreview } from 'https://cardstack.com/base/file-formats/index';
 import StringField from 'https://cardstack.com/base/string';
 import BooleanField from 'https://cardstack.com/base/boolean';
 import NumberField from 'https://cardstack.com/base/number';
 import GlimmerComponent from '@glimmer/component';
+import { guidFor } from '@ember/object/internals';
 import { tracked } from '@glimmer/tracking';
 import { on } from '@ember/modifier';
-import { cssStyle } from './pretui-css';
 import { fn } from '@ember/helper';
 import type { Query, RealmResourceIdentifier } from '@cardstack/runtime-common';
 import { ThemeFrame } from './components/theme-frame';
 import { EmptyState } from './components/empty-state';
 import { StatusChip } from './components/status-chip';
+import { Chip } from './components/chip';
 import { Token } from './components/token';
-import { statusHue } from './internal/ink';
 import { Button } from './components/button';
+import { VisuallyHidden } from './components/visually-hidden';
 import { Textarea } from './components/textarea';
 import { StepList } from './components/step-list';
+import { toIsoDate } from './components/known-date';
 import type { StepItem, StepState } from './components/step-list';
 import { Popover } from './components/popover';
 import {
@@ -47,21 +50,12 @@ import { iconFor } from './icon-registry';
 import { ExampleGallery } from './example-gallery';
 import type { ExampleSpec } from './examples-kit';
 
-// Today's callers pass a statusHue() result, which is always a `var(--chart-N)`
-// we built ourselves — but the hue originates in card data, so it goes through
-// the kit-wide allowlist rather than straight to htmlSafe. Nothing unvalidated
-// reaches an inline style anywhere in the kit.
-function htmlSafeHue(hue: string) {
-  return cssStyle('--pretui-fit-hue', hue);
-}
-
 // Structural shape of a PretuiNote instance as read off a getCards result.
 // Declared rather than imported: pretui-note.gts imports THIS module for its
 // linksTo target, so importing it back would make the pair circular. The
 // query names the type by module + name strings instead.
 interface NoteLike {
   id?: string;
-  title?: string;
   note?: string;
   status?: string;
 }
@@ -87,6 +81,116 @@ function createCardAction(context: unknown): CreateCardAction | undefined {
 // resolves wherever it is written.
 const NOTE_REF = { module: siblingHref('./pretui-note'), name: 'PretuiNote' };
 
+// The stage as shown: capitalized, from the stored lowercase value.
+function stageLabel(stage: string | undefined): string {
+  let value = stage || 'planned';
+  return value.charAt(0).toUpperCase() + value.slice(1);
+}
+
+// A live component's stage chip takes the success tone; every other stage
+// keeps StatusChip's muted pill with its name-derived dot.
+function stageTone(stage: string | undefined): 'success' | undefined {
+  return stage === 'live' ? 'success' : undefined;
+}
+
+// The write-up shows its first lines under a fade, with a centered toggle
+// over the fade; opening it grows the region to the content's height. Its own
+// component for the same reason as NoteComposer: the open state can't live in
+// the format class.
+interface WriteupFoldSignature {
+  Args: { writeup: MarkdownDef };
+  Element: HTMLDivElement;
+}
+
+class WriteupFold extends GlimmerComponent<WriteupFoldSignature> {
+  @tracked open = false;
+  regionId = `${guidFor(this)}-writeup`;
+  toggle = () => (this.open = !this.open);
+
+  <template>
+    <div class='wb-fold' data-open={{if this.open 'true'}} ...attributes>
+      {{! the write-up's prose only — the panel owns the padding, so the
+          file's own embedded chrome and surface stay out }}
+      <div id={{this.regionId}} class='wb-fold-region'>
+        <div class='wb-fold-prose'>
+          <MarkdownPreview
+            @model={{@writeup}}
+            @format='isolated'
+            @displayContainer={{false}}
+          />
+        </div>
+      </div>
+      <div class='wb-fold-more'>
+        <Button
+          @tone='neutral'
+          @appearance='outlined'
+          @size='xs'
+          aria-expanded={{if this.open 'true' 'false'}}
+          aria-controls={{this.regionId}}
+          {{on 'click' this.toggle}}
+          data-test-pretui-writeup-toggle
+        >{{if this.open 'Show less' 'Show more'}}</Button>
+      </div>
+    </div>
+    <style scoped>
+      /* closed, the preview fills whatever height the fold is given, never
+         less than --wb-fold-preview-h; open, it grows to the content */
+      .wb-fold {
+        --wb-fold-preview-h: 14rem;
+        --wb-fold-fade-h: 2rem;
+
+        position: relative;
+        display: flex;
+        flex-direction: column;
+      }
+      .wb-fold-region {
+        flex: 1 1 0;
+        min-block-size: var(--wb-fold-preview-h);
+        overflow: hidden;
+        /* the open state changes the flex basis and grow, not height, so those
+           are what animate; interpolate-size lets the basis reach auto */
+        interpolate-size: allow-keywords;
+        transition:
+          flex-basis 250ms ease,
+          flex-grow 250ms ease;
+      }
+      .wb-fold[data-open='true'] .wb-fold-region {
+        flex: 0 0 auto;
+      }
+      /* mono reads larger than sans at the same size; a step down in em
+         matches the prose around it optically */
+      .wb-fold-prose {
+        --markdown-code-font-size: 0.875em;
+        --markdown-pre-font-size: 0.875em;
+        --markdown-pre-border-radius: var(--boxel-border-radius-sm);
+
+        padding: var(--boxel-sp-sm);
+      }
+      /* closed, the toggle sits over a fade into the panel's surface; open,
+         it follows the content */
+      .wb-fold-more {
+        display: flex;
+        justify-content: center;
+        position: absolute;
+        inset-inline: 0;
+        inset-block-end: 0;
+        padding: var(--wb-fold-fade-h) var(--boxel-sp-sm) var(--boxel-sp-xs);
+        background-image: linear-gradient(transparent, var(--card) 70%);
+      }
+      .wb-fold[data-open='true'] .wb-fold-more {
+        position: static;
+        padding-block-start: 0;
+        background-image: none;
+      }
+      @media (prefers-reduced-motion: reduce) {
+        .wb-fold-region {
+          transition: none;
+        }
+      }
+    </style>
+  </template>
+}
+
 // ── The sticky-note composer ─────────────────────────────────────────────
 // A top-level component, not an inline block in the page: reactive state
 // cannot live in a format-class expression (`static isolated = class …`),
@@ -134,24 +238,22 @@ class NoteComposer extends GlimmerComponent<NoteComposerSignature> {
           @disabled={{this.draftEmpty}}
           {{on 'click' this.save}}
           data-test-pretui-note-save
-        >Stick it</Button>
+        >Save note</Button>
       </div>
     </div>
     <style scoped>
-      /* Widened past the popover's default through the knobs Popover
-         exposes, rather than reaching into its panel with :deep() — a note
-         wants room to write. */
       .note-compose {
-        --pretui-popover-width: 320px;
+        --note-compose-min-w: 17.5rem;
+
         display: flex;
         flex-direction: column;
-        gap: var(--space-2, 6px);
-        min-width: 280px;
+        gap: var(--boxel-sp-2xs);
+        min-width: var(--note-compose-min-w);
       }
       .note-compose-cap {
-        font-size: var(--text-ui-xs, 11px);
+        font-size: var(--boxel-font-size-2xs);
         font-weight: 600;
-        letter-spacing: var(--track-eyebrow, 0.06em);
+        letter-spacing: 0.06em;
         text-transform: uppercase;
         color: var(--muted-foreground);
       }
@@ -162,10 +264,10 @@ class NoteComposer extends GlimmerComponent<NoteComposerSignature> {
         display: flex;
         align-items: center;
         justify-content: space-between;
-        gap: var(--space-3, 10px);
+        gap: var(--boxel-sp-xs);
       }
       .note-compose-hint {
-        font-size: var(--text-ui-xs, 11px);
+        font-size: var(--boxel-font-size-2xs);
         color: var(--muted-foreground);
       }
     </style>
@@ -294,10 +396,10 @@ export class PretUISpec extends Spec {
     }
     get metaItems() {
       let m = this.args.model;
-      let rows = [
+      let rows: { key: string; value: string; dots?: boolean[] }[] = [
         { key: 'Category', value: m.category ?? m.territory ?? '—' },
         { key: 'Tier', value: m.tier ?? '—' },
-        { key: 'Stage', value: m.stage ?? '—' },
+        { key: 'Stage', value: m.stage ? stageLabel(m.stage) : '—' },
         // versions are earned by use — nothing worn shows no number
         ...(m.liveInUse
           ? [{ key: 'Version', value: m.version ?? '0.0.0' }]
@@ -313,6 +415,13 @@ export class PretUISpec extends Spec {
       if (m.refs) {
         rows.push({ key: 'Elsewhere', value: m.refs });
       }
+      if (this.demand) {
+        rows.push({
+          key: 'Demand',
+          value: `${this.demand} of 5`,
+          dots: [1, 2, 3, 4, 5].map((i) => i <= this.demand!),
+        });
+      }
       return rows;
     }
     get facetPills() {
@@ -338,36 +447,10 @@ export class PretUISpec extends Spec {
         state: (f.on ? 'complete' : 'upcoming') as StepState,
       }));
     }
-    get railFacts() {
-      let m = this.args.model;
-      return [
-        { label: 'Category', value: m.category ?? m.territory ?? '—', dim: true },
-        { label: 'Tier', value: m.tier ?? '—', dim: true },
-        {
-          label: 'Stage',
-          value: m.stage ?? 'planned',
-          accent: m.stage === 'live',
-        },
-        ...(m.liveInUse
-          ? [{ label: 'Version', value: m.version ?? '0.0.0' }]
-          : []),
-        { label: 'Source', value: m.source ?? '—', dim: true },
-        ...(m.lineage
-          ? [{ label: 'Lineage', value: `boxel-ui/${m.lineage}`, dim: true }]
-          : []),
-        ...(this.demandDots
-          ? [{ label: 'Demand', value: this.demandDots, accent: true }]
-          : []),
-      ];
-    }
-    get demandDots() {
+    get demand(): number | undefined {
       let d = this.args.model.demand;
       if (!d || d < 1) return undefined;
-      let n = Math.min(5, Math.round(d));
-      return '●'.repeat(n) + '○'.repeat(5 - n);
-    }
-    get titleHue() {
-      return htmlSafeHue(statusHue(this.args.model.stage ?? 'planned'));
+      return Math.min(5, Math.round(d));
     }
     // ── Sticky notes ───────────────────────────────────────────────────
     // Notes are their own cards (pretui-note.gts) that LINK to this one, so
@@ -443,7 +526,13 @@ export class PretUISpec extends Spec {
       // card must prerender identically); recording when a note was written
       // is data capture at the moment of a user action, which is exactly
       // what a timestamp is for.
-      let noted = new Date().toISOString().slice(0, 10);
+      // the author's local date, not toISOString()'s UTC one
+      let now = new Date();
+      let noted = toIsoDate(
+        now.getFullYear(),
+        now.getMonth() + 1,
+        now.getDate(),
+      );
       create(ref, realm, {
         realmURL: realm,
         doc: {
@@ -460,277 +549,292 @@ export class PretUISpec extends Spec {
 
     <template>
       <ThemeFrame
+        class='wb-frame'
         @theme={{@model.cardTheme}}
         @context={{@context}}
         @bar={{false}}
         as |ThemeControls|
       >
-      <article class='page' data-demo-policy={{this.demoPolicy}}>
-        <nav class='wb-topbar'>
-          <div class='wb-crumb' data-test-pretui-spec-crumb>
-            <span class='wb-crumb-root'>Pretui</span>
-            <span class='wb-sep'>/</span>
-            <span class='wb-crumb-dim'>{{if
-                @model.category
-                @model.category
-                (if @model.territory @model.territory 'components')
-              }}</span>
-            <span class='wb-sep'>/</span>
-            <span class='wb-here'>{{if
-                @model.componentName
-                @model.componentName
-                'Component'
-              }}</span>
-          </div>
-          <div class='wb-badges'>
-            {{#if @model.liveInUse}}
-              <Token @value={{if @model.version @model.version '0.0.0'}} />
-            {{/if}}
-            <StatusChip @value={{if @model.stage @model.stage 'planned'}} />
-            {{#if @model.isNew}}<span class='flag flag-new'>NEW</span>{{/if}}
-            {{#if @model.featured}}<span class='flag flag-feat'>★</span>{{/if}}
-          </div>
-          <div class='wb-grow'></div>
-          <ThemeControls />
-        </nav>
+        <article class='page' data-demo-policy={{this.demoPolicy}}>
+          <header class='wb-topbar'>
+            <div class='wb-crumb' data-test-pretui-spec-crumb>
+              <span class='wb-crumb-root'>Pret UI</span>
+              <span aria-hidden='true'>/</span>
+              <span class='wb-crumb-dim'>{{if
+                  @model.category
+                  @model.category
+                  (if @model.territory @model.territory 'components')
+                }}</span>
+              <span aria-hidden='true'>/</span>
+              <span class='wb-here'>{{if
+                  @model.componentName
+                  @model.componentName
+                  'Component'
+                }}</span>
+            </div>
+            <div class='wb-badges'>
+              {{#if @model.liveInUse}}
+                <Token @value={{if @model.version @model.version '0.0.0'}} />
+              {{/if}}
+              <StatusChip
+                @value={{stageLabel @model.stage}}
+                @tone={{stageTone @model.stage}}
+              />
+              {{#if @model.isNew}}<Chip @label='New' @tone='attention' />{{/if}}
+              {{#if @model.featured}}<Chip @tone='warning' @dot={{false}}><span
+                    aria-hidden='true'
+                  >★</span><VisuallyHidden
+                  >Featured</VisuallyHidden></Chip>{{/if}}
+            </div>
+            <div class='wb-grow'></div>
+            <ThemeControls />
+          </header>
 
-        {{! Sticky notes live top-right, where you left them. Visible by
+          {{! Sticky notes live top-right, where you left them. Visible by
             design: an annotation hidden behind a disclosure is an annotation
             nobody reads. }}
-        {{#if this.showNotes}}
-          <aside
-            class='notes'
-            aria-label='Sticky notes on this component'
-            data-test-pretui-notes
-          >
-            {{! The trigger sits FIRST — directly under the theme control and
+          {{#if this.showNotes}}
+            <aside
+              class='notes'
+              aria-label='Sticky notes on this component'
+              data-test-pretui-notes
+            >
+              {{! The trigger sits FIRST — directly under the theme control and
                 above the artboard — so leaving a note is a fixed target on
                 every page, not something that moves as notes accumulate. }}
-            <div class='notes-foot'>
-              {{#if this.canAddNote}}
-                <Popover @placement='bottom-end' @label='Leave a sticky note'>
-                  <:trigger as |open toggle|>
-                    <button
-                      type='button'
-                      class='note-add'
-                      aria-expanded={{if open 'true' 'false'}}
-                      {{on 'click' toggle}}
-                      data-test-pretui-note-add
-                    >+ Note</button>
-                  </:trigger>
-                  <:default as |close|>
-                    <NoteComposer
-                      @componentName={{@model.componentName}}
-                      @onSave={{fn this.saveNote close}}
-                    />
-                  </:default>
-                </Popover>
+              <div class='notes-foot'>
+                {{#if this.canAddNote}}
+                  <Popover
+                    class='note-popover'
+                    @placement='bottom-end'
+                    @label='Leave a sticky note'
+                  >
+                    <:trigger as |open toggle|>
+                      <Button
+                        @tone='neutral'
+                        @appearance='outlined'
+                        @size='xs'
+                        aria-expanded={{if open 'true' 'false'}}
+                        {{on 'click' toggle}}
+                        data-test-pretui-note-add
+                      >Add note</Button>
+                    </:trigger>
+                    <:default as |close|>
+                      <NoteComposer
+                        @componentName={{@model.componentName}}
+                        @onSave={{fn this.saveNote close}}
+                      />
+                    </:default>
+                  </Popover>
+                {{/if}}
+                {{#if this.addressedCount}}
+                  <span class='notes-done'>{{this.addressedCount}}
+                    addressed</span>
+                {{/if}}
+              </div>
+              {{#if this.openNotes}}
+                <ul class='notes-list'>
+                  {{#each this.openNotes key='id' as |n|}}
+                    <li>
+                      <button
+                        type='button'
+                        class='note'
+                        {{on 'click' (fn this.openNote n.id)}}
+                        data-test-pretui-note
+                      >
+                        <span class='note-text'>{{if
+                            n.note
+                            n.note
+                            'Empty note'
+                          }}</span>
+                      </button>
+                    </li>
+                  {{/each}}
+                </ul>
               {{/if}}
-              {{#if this.addressedCount}}
-                <span class='notes-done'>{{this.addressedCount}} addressed</span>
+            </aside>
+          {{/if}}
+          <h1 class='wb-title'>
+            {{#let (iconFor @model.icon) as |TitleIcon|}}
+              {{#if TitleIcon}}
+                <span class='wb-title-frame'>
+                  <TitleIcon width='22' height='22' role='presentation' />
+                </span>
               {{/if}}
-            </div>
-            {{#if this.openNotes}}
-              <ul class='notes-list'>
-                {{#each this.openNotes key='id' as |n|}}
-                  <li>
-                    <button
-                      type='button'
-                      class='note'
-                      {{on 'click' (fn this.openNote n.id)}}
-                      data-test-pretui-note
-                    >
-                      <span class='note-text'>{{if
-                          n.note
-                          n.note
-                          'Empty note'
-                        }}</span>
-                    </button>
-                  </li>
-                {{/each}}
-              </ul>
-            {{/if}}
-          </aside>
-        {{/if}}
-        <h1 class='wb-title'>
-          {{#let (iconFor @model.icon) as |TitleIcon|}}
-            {{#if TitleIcon}}
-              <span class='wb-title-frame' style={{this.titleHue}}>
-                <TitleIcon class='wb-title-icon' role='presentation' />
-              </span>
+            {{/let}}
+            {{if @model.componentName @model.componentName 'Component'}}
+          </h1>
+          {{#unless this.demo}}
+            {{#if @model.brief}}
+              <p class='brief'>{{@model.brief}}</p>
             {{/if}}
-          {{/let}}
-          {{if @model.componentName @model.componentName 'Component'}}
-        </h1>
-        {{#unless this.demo}}
-          {{#if @model.brief}}
-            <p class='brief'>{{@model.brief}}</p>
-          {{/if}}
-        {{/unless}}
-        <div class='wb-work'>
-          {{#if this.demo}}
-            <this.demo />
-          {{else if this.isDemoLoading}}
-            <section class='panel' aria-busy='true'></section>
-          {{else if this.isDemoExcluded}}
-            <section class='panel'>
-              {{#if this.isHost}}
+          {{/unless}}
+          <div class='wb-work'>
+            {{#if this.demo}}
+              <this.demo />
+            {{else if this.isDemoLoading}}
+              <section class='panel' aria-busy='true'></section>
+            {{else if this.isDemoExcluded}}
+              <section class='panel'>
+                {{#if this.isHost}}
+                  <EmptyState
+                    @title='Catalog infrastructure — demo excluded'
+                    @message='Host chrome stays in boxel-ui by design. It is indexed here for vocabulary coverage, not as a Pret UI demo target.'
+                  />
+                {{else}}
+                  <EmptyState
+                    @title='Catalog infrastructure — demo excluded'
+                    @message='This Runtime primitive builds the fitting room itself. It is indexed for API coverage and explicitly excluded from missing-demo QA.'
+                  />
+                {{/if}}
+              </section>
+            {{else}}
+              <section class='panel'>
                 <EmptyState
-                  @title='Catalog infrastructure — demo excluded'
-                  @message='Host chrome stays in boxel-ui by design. It is indexed here for vocabulary coverage, not as a Pretui demo target.'
+                  @title='No usage page yet'
+                  @message='This component has no freestyle page in the fitting room yet — see the kit showcase for the territory rail.'
                 />
-              {{else}}
-                <EmptyState
-                  @title='Catalog infrastructure — demo excluded'
-                  @message='This Runtime primitive builds the fitting room itself. It is indexed for API coverage and explicitly excluded from missing-demo QA.'
+              </section>
+            {{/if}}
+          </div>
+          <ExampleGallery @specs={{this.examples}} />
+          <div class='wb-below'>
+            {{#if @model.writeup}}
+              <section class='wb-panel wb-writeup-panel' aria-label='Write-up'>
+                <div class='wb-panel-h'>
+                  <span class='wb-cap'>Write-up</span>
+                </div>
+                <WriteupFold
+                  class='wb-writeup-fold'
+                  @writeup={{@model.writeup}}
                 />
-              {{/if}}
-            </section>
-          {{else}}
-            <section class='panel'>
-              <EmptyState
-                @title='No usage page yet'
-                @message='This component has no freestyle page in the fitting room yet — see the kit showcase for the territory rail.'
+              </section>
+            {{/if}}
+            <section class='wb-panel wb-provenance' aria-label='Provenance'>
+              <div class='wb-panel-h'>
+                <span class='wb-cap'>Provenance</span>
+              </div>
+              <StepList
+                class='wb-pipe'
+                @steps={{this.provenanceSteps}}
+                @variant='track'
+                @label='Provenance pipeline'
+                @summary={{true}}
               />
+              <dl class='wb-kv'>
+                {{#each this.metaItems as |row|}}
+                  <div class='wb-krow'>
+                    <dt>{{row.key}}</dt>
+                    <dd>
+                      {{#if row.dots}}
+                        {{! drawn, not ●/○ glyphs, so filled and hollow share one
+                        size and baseline }}
+                        <span
+                          class='wb-dots'
+                          role='img'
+                          aria-label={{row.value}}
+                        >
+                          {{#each row.dots as |on|}}
+                            <span
+                              class='wb-dot'
+                              data-on={{if on 'true'}}
+                            ></span>
+                          {{/each}}
+                        </span>
+                      {{else}}
+                        {{row.value}}
+                      {{/if}}
+                    </dd>
+                  </div>
+                {{/each}}
+              </dl>
             </section>
-          {{/if}}
-        </div>
-        <ExampleGallery @specs={{this.examples}} />
-        {{#if @model.writeup}}
-          <section class='wb-panel' aria-label='Write-up'>
-            <div class='wb-panel-h'>
-              <span class='wb-cap'>Write-up</span>
-            </div>
-            <@fields.writeup @format='embedded' />
-          </section>
-        {{/if}}
-        <div class='wb-below'>
-          <section class='wb-panel' aria-label='Provenance'>
-            <div class='wb-panel-h'>
-              <span class='wb-cap'>Provenance</span>
-            </div>
-            <StepList
-              class='wb-pipe'
-              @steps={{this.provenanceSteps}}
-              @variant='track'
-              @label='Provenance pipeline'
-              @summary={{true}}
-            />
-            <dl class='wb-kv'>
-              {{#each this.metaItems as |row|}}
-                <div class='wb-krow'>
-                  <dt>{{row.key}}</dt>
-                  <dd>{{row.value}}</dd>
-                </div>
-              {{/each}}
-            </dl>
-          </section>
-          <aside class='wb-rail' aria-label='Component facts'>
-            <div class='wb-igroup'>
-              <span class='wb-cap'>Component</span>
-              {{#each this.railFacts as |f|}}
-                <div class='wb-irow'>
-                  <span class='wb-ilabel'>{{f.label}}</span>
-                  <span
-                    class='wb-ival'
-                    data-dim={{if f.dim 'true'}}
-                    data-accent={{if f.accent 'true'}}
-                  >{{f.value}}</span>
-                </div>
-              {{/each}}
-            </div>
-            <div class='wb-igroup'>
-              <span class='wb-cap'>Provenance</span>
-              {{#each this.facetPills as |f|}}
-                <div class='wb-irow'>
-                  <span class='wb-ilabel'>{{f.label}}</span>
-                  <span
-                    class='wb-ival'
-                    data-accent={{if f.on 'true'}}
-                    data-dim={{unless f.on 'true'}}
-                  >{{if f.on '✓' '—'}}</span>
-                </div>
-              {{/each}}
-            </div>
-          </aside>
-        </div>
-      </article>
+          </div>
+        </article>
       </ThemeFrame>
       <style scoped>
+        /* the isolated root: exactly the card's height and the one scroller, so
+           the sticky topbar sticks to it and an overscroll can't bounce past
+           the island or carry on into the page behind */
+        .wb-frame {
+          height: 100%;
+          overflow-y: auto;
+          overscroll-behavior: none;
+        }
         .page {
+          --wb-topbar-h: 2.75rem;
+          --wb-panel-h: 2.25rem;
+          --wb-title-frame-size: 3rem;
+          --wb-notes-w: 17.5rem;
+          --wb-writeup-min-w: 48rem;
+          /* StepList's track turns vertical at 24rem; with the panel's
+             padding, provenance needs 26rem to keep it horizontal */
+          --wb-provenance-min-w: 26rem;
+          --wb-provenance-max-w: 30rem;
+          --wb-krow-label-w: 6.875rem;
+          --wb-dot-size: 0.5rem;
+
           min-height: 100%;
-          background: var(--background);
-          color: var(--foreground);
-          font-family: var(--font-sans);
-          font-size: var(--text-body, 15px);
-          letter-spacing: var(--track-ui, 0.01em);
-          padding: 0 var(--space-6, 19px) var(--space-8, 34px);
+          padding: 0 var(--boxel-sp-lg) var(--boxel-sp-2xl);
           display: grid;
-          gap: var(--space-5, 14px);
+          gap: var(--boxel-sp);
           align-content: start;
         }
         /* ── workbench chrome (pretui-alert-workbench format) ── */
         .wb-title {
-          margin: 6px 0 -4px;
+          margin: var(--boxel-sp-2xs) 0 calc(-1 * var(--boxel-sp-3xs));
           font-family: var(--font-serif);
-          font-size: var(--text-display, 33px);
-          font-weight: var(--weight-heading, 700);
-          letter-spacing: var(--track-heading, -0.02em);
+          font-size: var(--boxel-font-size-xl);
+          font-weight: 700;
+          letter-spacing: var(--boxel-lsp-xs);
           line-height: 1.1;
           display: flex;
           align-items: center;
-          gap: 10px;
+          gap: var(--boxel-sp-xs);
         }
-        /* the icon sits framed — same box language as catalog cells and
-           the fitted disc: stage hue tint + hairline, fixed scale */
+        /* the component's icon beside its title: a --background tile with a
+           hairline ring on the page's --canvas, not a raised button */
         .wb-title-frame {
+          --icon-color: currentColor;
+          --icon-bg: none;
+
           display: grid;
           place-items: center;
-          width: 40px;
-          height: 40px;
+          width: var(--wb-title-frame-size);
+          height: var(--wb-title-frame-size);
           flex: none;
-          border-radius: 9px;
-          background: color-mix(in oklch, var(--pretui-fit-hue, var(--chart-1)) 14%, var(--card));
-          box-shadow: inset 0 0 0 1px color-mix(in oklch, var(--pretui-fit-hue, var(--chart-1)) 32%, var(--border));
-          color: color-mix(in oklch, var(--pretui-fit-hue, var(--chart-1)) 60%, var(--foreground));
-          --icon-color: currentColor;
-          --icon-bg: none;
-        }
-        .wb-title-icon {
-          width: 22px;
-          height: 22px;
+          border-radius: var(--boxel-border-radius-sm);
+          box-shadow: inset 0 0 0 1px var(--border);
+          background-color: var(--background);
+          color: var(--muted-foreground);
         }
         .wb-topbar {
           position: sticky;
           top: 0;
-          /* kit stacking scale (pretui-css.gts): sticky page chrome sits
-             above content and well below every floating surface, so a menu
-             opened FROM this bar clears it. */
+          /* sticky page chrome sits above content and well below every
+             floating surface, so a menu opened from this bar clears it */
           z-index: var(--pretui-z-sticky, 10);
           display: flex;
           align-items: center;
-          gap: var(--space-4, 11px);
-          min-height: 44px;
-          margin: 0 calc(-1 * var(--space-6, 19px));
-          padding: 6px var(--space-6, 19px);
-          background: var(--card);
+          gap: var(--boxel-sp-sm);
+          min-height: var(--wb-topbar-h);
+          margin: 0 calc(-1 * var(--boxel-sp-lg));
+          padding: var(--boxel-sp-2xs) var(--boxel-sp-lg);
+          background-color: var(--card);
+          color: var(--card-foreground);
           box-shadow: inset 0 -1px 0 var(--border);
           flex-wrap: wrap;
         }
         .wb-crumb {
           display: flex;
           align-items: center;
-          gap: 8px;
-          font-size: var(--text-ui, 12px);
+          gap: var(--boxel-sp-xs);
+          font-size: var(--boxel-font-size-xs);
           color: var(--muted-foreground);
           min-width: 0;
         }
         .wb-crumb-root {
-          padding: 3px 5px;
-        }
-        .wb-sep {
-          color: var(--ink-3, var(--boxel-400));
-          user-select: none;
+          padding: var(--boxel-sp-5xs) var(--boxel-sp-3xs);
         }
         .wb-here {
           color: var(--foreground);
@@ -739,8 +843,8 @@ export class PretUISpec extends Spec {
         .wb-badges {
           display: flex;
           align-items: center;
-          gap: 6px;
-          margin-left: 2px;
+          gap: var(--boxel-sp-2xs);
+          margin-inline-start: var(--boxel-sp-6xs);
         }
         .wb-grow {
           flex: 1;
@@ -758,54 +862,53 @@ export class PretUISpec extends Spec {
           display: flex;
           flex-direction: column;
           align-items: flex-end;
-          gap: var(--space-2, 6px);
-          width: min(280px, 100%);
+          gap: var(--boxel-sp-2xs);
+          width: min(var(--wb-notes-w), 100%);
           min-width: 0;
         }
+        /* a note wants room to write: Popover reads its width knob on the
+           panel, which inherits it from the Popover root */
+        .note-popover {
+          --pretui-popover-width: 20rem;
+        }
         .notes-list {
           display: flex;
           flex-direction: column;
-          gap: var(--space-2, 6px);
+          gap: var(--boxel-sp-2xs);
           width: 100%;
           margin: 0;
           padding: 0;
           list-style: none;
         }
         .note {
-          /* Law 2: one hue in, a complete treatment out — a tint of the hue
-             over --card with ink derived from the same hue, so the sticky
-             holds contrast in light and dark with no branch. */
-          --hue: var(--pretui-note-hue, var(--chart-3));
+          /* a tint of --attention over --card, so the sticky holds
+             contrast in light and dark */
           width: 100%;
-          text-align: left;
-          padding: var(--space-3, 10px);
+          text-align: start;
+          padding: var(--boxel-sp-xs);
           border: 0;
-          border-radius: var(--radius-surface, 10px);
-          background: color-mix(in oklch, var(--hue) 14%, var(--card));
-          /* Law 1: depth is hairline + shadow, never contrast. */
-          box-shadow: var(
-            --pretui-shadow-card,
-            0 0 0 1px var(--border),
-            0 1px 2px rgb(0 0 0 / 0.2),
-            0 2px 6px rgb(0 0 0 / 0.2)
+          border-radius: var(--boxel-border-radius);
+          background-color: color-mix(
+            in oklch,
+            var(--attention) 14%,
+            var(--card)
           );
-          font: inherit;
-          font-size: var(--text-ui-md, 12.5px);
-          line-height: 1.5;
-          color: var(--foreground);
-          cursor: pointer;
-        }
-        .note:hover {
-          box-shadow: var(
-            --pretui-shadow-raised,
+          color: var(--card-foreground);
+          box-shadow:
             0 0 0 1px var(--border),
-            0 2px 10px rgb(0 0 0 / 0.22)
-          );
+            var(--shadow-sm);
+          font-size: var(--boxel-font-size-xs);
+          line-height: 1.5;
         }
         .note:focus-visible {
           outline: 2px solid var(--ring);
           outline-offset: 2px;
         }
+        .note:hover {
+          box-shadow:
+            0 0 0 1px var(--border),
+            var(--shadow-md);
+        }
         /* Clamp long notes: the rail is a pointer to the note card, not the
            note card. Clicking opens the whole thing. */
         .note-text {
@@ -813,106 +916,74 @@ export class PretUISpec extends Spec {
           -webkit-line-clamp: 4;
           -webkit-box-orient: vertical;
           overflow: hidden;
-          /* a pasted URL or a long identifier is one "word" — without this
-             it blows the rail out of the narrow-pane layout instead of
-             clamping */
-          overflow-wrap: anywhere;
+          /* a pasted URL or a long identifier is one "word"; the rail has a
+             fixed width, so break-word wraps it instead of overflowing */
+          overflow-wrap: break-word;
         }
         .notes-foot {
           display: flex;
           align-items: center;
-          gap: var(--space-3, 10px);
-        }
-        .note-add {
-          padding: 3px 9px;
-          border: 0;
-          border-radius: var(--radius-control, 7px);
-          background: transparent;
-          box-shadow: var(
-            --pretui-shadow-hairline,
-            0 0 0 1px var(--border)
-          );
-          font-family: var(--font-mono);
-          font-size: var(--text-ui-xs, 11px);
-          color: var(--muted-foreground);
-          cursor: pointer;
-        }
-        .note-add:hover {
-          background: var(--card);
-          color: var(--foreground);
-        }
-        .note-add:focus-visible {
-          outline: 2px solid var(--ring);
-          outline-offset: 2px;
+          gap: var(--boxel-sp-xs);
         }
         .notes-done {
           font-family: var(--font-mono);
-          font-size: var(--text-ui-xs, 11px);
+          font-size: var(--boxel-font-size-2xs);
           color: var(--muted-foreground);
         }
-        /* The composer inside the popover. Widened past the popover's default
-           through the knobs Popover exposes, rather than reaching into its
-           panel with :deep() — a note wants room to write. */
-        .note-compose {
-          --pretui-popover-width: 320px;
+        /* the write-up and provenance share a row when both fit, and stack
+           otherwise; provenance stops at its cap and the write-up takes the
+           rest */
+        .wb-below {
+          container-type: inline-size;
           display: flex;
-          flex-direction: column;
-          gap: var(--space-2, 6px);
-          min-width: 280px;
-        }
-        .note-compose-cap {
-          font-size: var(--text-ui-xs, 11px);
-          font-weight: 600;
-          letter-spacing: var(--track-eyebrow, 0.06em);
-          text-transform: uppercase;
-          color: var(--muted-foreground);
-        }
-        .note-compose-field {
-          width: 100%;
+          flex-wrap: wrap;
+          gap: var(--boxel-sp);
+          /* on a shared row the write-up is at least as tall as provenance */
+          align-items: stretch;
         }
-        .note-compose-foot {
+        .wb-below > .wb-writeup-panel {
+          flex: 1 1 var(--wb-writeup-min-w);
           display: flex;
-          align-items: center;
-          justify-content: space-between;
-          gap: var(--space-3, 10px);
+          flex-direction: column;
         }
-        .note-compose-hint {
-          font-size: var(--text-ui-xs, 11px);
-          color: var(--muted-foreground);
+        .wb-writeup-fold {
+          flex: 1;
         }
-        /* the below-the-demo band: panels left, facts rail right — the rail
-           column matches FreestyleUsage's 280px properties rail so the two
-           read as one continuous inspector */
-        .wb-below {
-          display: grid;
-          grid-template-columns: minmax(0, 1fr) 280px;
-          gap: var(--space-5, 14px);
-          align-items: start;
+
+        .wb-below > .wb-provenance {
+          flex: 1 1 var(--wb-provenance-min-w);
+          align-self: start;
         }
-        @media (max-width: 1100px) {
-          .wb-below {
-            grid-template-columns: minmax(0, 1fr);
+        /* capped only while it shares the row: 75rem is the write-up's 48rem
+           minimum plus provenance's 26rem plus the 1rem gap (a container query
+           can't read the variables). Stacked, it runs full width. Unnamed: a
+           named container query doesn't survive the realm's scoped-CSS
+           transpiler. */
+        @container (width >= 75rem) {
+          .wb-below > .wb-writeup-panel ~ .wb-provenance {
+            max-inline-size: var(--wb-provenance-max-w);
           }
         }
         .wb-panel {
-          background: var(--card);
-          border-radius: 6px;
-          box-shadow: var(--pretui-shadow-hairline, 0 0 0 1px var(--border));
+          background-color: var(--card);
+          color: var(--card-foreground);
+          border-radius: var(--boxel-border-radius);
+          box-shadow: 0 0 0 1px var(--border);
           overflow: hidden;
           min-width: 0;
         }
         .wb-panel-h {
           display: flex;
           align-items: center;
-          gap: 10px;
-          min-height: 36px;
-          padding: 8px var(--space-4, 11px);
+          gap: var(--boxel-sp-xs);
+          min-height: var(--wb-panel-h);
+          padding: var(--boxel-sp-xs) var(--boxel-sp-sm);
           box-shadow: inset 0 -1px 0 var(--border);
         }
         /* THE caps treatment — panel and group headers only (type spec:
            one caps style, everything else sentence case) */
         .wb-cap {
-          font-size: var(--text-ui-xs, 11px);
+          font-size: var(--boxel-font-size-2xs);
           font-weight: 600;
           letter-spacing: 0.06em;
           text-transform: uppercase;
@@ -922,131 +993,68 @@ export class PretUISpec extends Spec {
            the panel only positions it; every bar, glyph, state text and the
            completion summary belong to the component */
         .wb-pipe {
-          padding: 12px var(--space-4, 11px) 6px;
+          padding: var(--boxel-sp-sm) var(--boxel-sp-sm) var(--boxel-sp-2xs);
         }
         .wb-kv {
           margin: 0;
-          padding: 4px 0 6px;
+          padding: var(--boxel-sp-3xs) 0 var(--boxel-sp-2xs);
         }
         .wb-krow {
           display: grid;
-          grid-template-columns: 110px minmax(0, 1fr);
-          gap: 12px;
-          padding: 6.5px var(--space-4, 11px);
+          grid-template-columns: var(--wb-krow-label-w) minmax(0, 1fr);
+          gap: var(--boxel-sp-sm);
+          padding: var(--boxel-sp-2xs) var(--boxel-sp-sm);
           align-items: baseline;
         }
-        .wb-krow:hover {
-          background: var(--stripe, var(--boxel-100));
-        }
         .wb-krow dt {
-          font-size: var(--text-ui, 12px);
+          font-size: var(--boxel-font-size-xs);
           font-weight: 500;
           color: var(--muted-foreground);
         }
-        .wb-krow dd {
-          margin: 0;
-          font-size: var(--text-ui-md, 12.5px);
-          overflow-wrap: anywhere;
-        }
-        .wb-rail {
-          display: grid;
-          gap: 0;
-          background: var(--card);
-          border-radius: 6px;
-          box-shadow: var(--pretui-shadow-hairline, 0 0 0 1px var(--border));
-          align-self: start;
-          overflow: hidden;
-        }
-        .wb-igroup {
-          padding: 10px var(--space-4, 11px) 14px;
-          box-shadow: inset 0 -1px 0 var(--border);
-        }
-        .wb-igroup:last-child {
-          box-shadow: none;
-        }
-        .wb-igroup > .wb-cap {
-          display: block;
-          margin-bottom: 10px;
-        }
-        .wb-irow {
-          display: grid;
-          grid-template-columns: 76px minmax(0, 1fr);
-          gap: 10px;
+        .wb-dots {
+          display: inline-flex;
           align-items: center;
-          margin-bottom: 8px;
-        }
-        .wb-irow:last-child {
-          margin-bottom: 0;
-        }
-        .wb-ilabel {
-          font-size: var(--text-ui, 12px);
-          font-weight: 500;
-          color: var(--muted-foreground);
-        }
-        .wb-ival {
-          font-family: var(--font-mono);
-          font-size: var(--text-ui, 12px);
-          color: var(--foreground);
-          overflow-wrap: anywhere;
+          gap: var(--boxel-sp-4xs);
+          vertical-align: middle;
         }
-        .wb-ival[data-dim='true'] {
-          color: var(--muted-foreground);
+        .wb-dot {
+          width: var(--wb-dot-size);
+          height: var(--wb-dot-size);
+          border-radius: 50%;
+          box-shadow: inset 0 0 0 1px currentColor;
         }
-        .wb-ival[data-accent='true'] {
-          color: var(--pretui-accent, var(--primary));
+        .wb-dot[data-on='true'] {
+          background-color: currentColor;
         }
-        .wb-pad {
-          padding: 10px var(--space-4, 11px);
+        .wb-krow dd {
+          margin: 0;
+          font-size: var(--boxel-font-size-xs);
+          overflow-wrap: break-word;
         }
         .panel {
-          background: var(--card);
-          border-radius: var(--radius-surface, 10px);
-          box-shadow: var(--pretui-shadow-card, 0 0 0 1px var(--border));
-          padding: var(--space-5, 14px);
+          background-color: var(--card);
+          color: var(--card-foreground);
+          border-radius: var(--boxel-border-radius);
+          box-shadow: 0 0 0 1px var(--border);
+          padding: var(--boxel-sp);
           display: grid;
-          gap: var(--space-4, 11px);
+          gap: var(--boxel-sp-sm);
           align-content: start;
         }
         .brief {
-          margin: 0;
           max-width: 78ch;
-          font-size: var(--text-ui-md, 12.5px);
+          font-size: var(--boxel-font-size-xs);
           line-height: 1.5;
           color: var(--muted-foreground);
         }
-        /* flags share the single caps treatment, sized to chip scale */
-        .flag {
-          font-size: 10px;
-          font-weight: 600;
-          letter-spacing: 0.06em;
-          text-transform: uppercase;
-          border-radius: 999px;
-          padding: 2px 8px;
-        }
-        .flag-new {
-          color: var(--pretui-attention-ink, var(--boxel-fuschia));
-          background: color-mix(in oklch, var(--pretui-attention, var(--boxel-fuschia)) 14%, var(--card));
-          box-shadow: 0 0 0 1px color-mix(in oklch, var(--pretui-attention, var(--boxel-fuschia)) 35%, var(--border));
-        }
-        .flag-feat {
-          color: color-mix(in oklch, var(--warning, var(--boxel-warning)) 75%, var(--foreground));
-          background: color-mix(in oklch, var(--warning, var(--boxel-warning)) 13%, var(--card));
-          box-shadow: 0 0 0 1px color-mix(in oklch, var(--warning, var(--boxel-warning)) 35%, var(--border));
-        }
       </style>
     </template>
   } as unknown as typeof Spec.isolated;
 
   static fitted = class Fitted extends Component<typeof PretUISpec> {
-    get hue() {
-      return statusHue(this.args.model.stage ?? 'planned');
-    }
     get monogram() {
       return (this.args.model.componentName ?? '?').charAt(0);
     }
-    get monoStyle() {
-      return htmlSafeHue(this.hue);
-    }
     <template>
       {{! The container element and the element the queries STYLE must be
           two different elements. An unnamed `@container` resolves against
@@ -1057,10 +1065,10 @@ export class PretUISpec extends Spec {
           root; this is the same shape. }}
       <div class='fit' data-test-pretui-component-fitted>
         <div class='fit-root'>
-          <div class='mono' style={{this.monoStyle}}>
+          <div class='mono'>
             {{#let (iconFor @model.icon) as |FitIcon|}}
               {{#if FitIcon}}
-                <FitIcon class='mono-icon' role='presentation' />
+                <FitIcon width='60%' height='60%' role='presentation' />
               {{else}}
                 {{this.monogram}}
               {{/if}}
@@ -1069,7 +1077,10 @@ export class PretUISpec extends Spec {
           <div class='fit-body'>
             <div class='fit-name'>
               {{@model.componentName}}
-              {{#if @model.featured}}<span class='fit-star'>★</span>{{/if}}
+              {{#if @model.featured}}<span class='fit-star'><span
+                    aria-hidden='true'
+                  >★</span><VisuallyHidden
+                  >Featured</VisuallyHidden></span>{{/if}}
             </div>
             <div class='fit-sub'>
               <span class='fit-terr'>{{if
@@ -1082,10 +1093,15 @@ export class PretUISpec extends Spec {
               {{/if}}
             </div>
             <div class='fit-extra'>
-              <StatusChip @value={{if @model.stage @model.stage 'planned'}} />
-              {{#if @model.isNew}}<span class='fit-new'>NEW</span>{{/if}}
+              <StatusChip
+                @value={{stageLabel @model.stage}}
+                @tone={{stageTone @model.stage}}
+              />
+              {{#if @model.isNew}}<Chip @label='New' @tone='attention' />{{/if}}
             </div>
-            {{#if @model.brief}}<div class='fit-brief'>{{@model.brief}}</div>{{/if}}
+            {{#if @model.brief}}<div
+                class='fit-brief'
+              >{{@model.brief}}</div>{{/if}}
           </div>
         </div>
       </div>
@@ -1097,58 +1113,57 @@ export class PretUISpec extends Spec {
           overflow: hidden;
         }
         .fit-root {
+          --fit-mono-size: 1.875rem;
+          --fit-mono-font-size: var(--boxel-font-size-sm);
+          --fit-mono-radius: var(--boxel-border-radius);
+
           width: 100%;
           height: 100%;
           display: flex;
           align-items: center;
-          gap: 10px;
-          padding: 8px 10px;
-          background: var(--card);
-          font-family: var(--font-sans);
+          gap: var(--boxel-sp-xs);
+          padding: var(--boxel-sp-xs);
+          background-color: var(--card);
+          color: var(--card-foreground);
           overflow: hidden;
           box-sizing: border-box;
         }
         .mono {
+          --icon-color: currentColor;
+          --icon-bg: none;
+
           flex: none;
-          width: 30px;
-          height: 30px;
-          border-radius: 9px;
+          width: var(--fit-mono-size);
+          height: var(--fit-mono-size);
+          border-radius: var(--fit-mono-radius);
           display: grid;
           place-items: center;
           font-weight: 800;
-          font-size: 15px;
-          background: color-mix(in oklch, var(--pretui-fit-hue, var(--chart-1)) 16%, var(--card));
-          color: color-mix(in oklch, var(--pretui-fit-hue, var(--chart-1)) 60%, var(--foreground));
-          box-shadow: inset 0 0 0 1px color-mix(in oklch, var(--pretui-fit-hue, var(--chart-1)) 32%, var(--border));
-        }
-        .mono {
-          --icon-color: currentColor;
-          --icon-bg: none;
-        }
-        .mono-icon {
-          width: 60%;
-          height: 60%;
+          font-size: var(--fit-mono-font-size);
+          background-color: var(--muted);
+          color: var(--foreground);
+          box-shadow: inset 0 0 0 1px var(--border);
         }
         .fit-body {
           min-width: 0;
           display: grid;
-          gap: 2px;
+          gap: var(--boxel-sp-6xs);
         }
         .fit-name {
           font-weight: 600;
-          font-size: var(--text-ui-md, 12.5px);
+          font-size: var(--boxel-font-size-xs);
           white-space: nowrap;
           overflow: hidden;
           text-overflow: ellipsis;
         }
         .fit-star {
-          color: var(--warning, var(--boxel-warning));
+          color: var(--accent-ink);
         }
         .fit-sub {
           display: flex;
-          gap: 8px;
+          gap: var(--boxel-sp-xs);
           font-family: var(--font-mono);
-          font-size: 10px;
+          font-size: var(--boxel-font-size-2xs);
           letter-spacing: 0.06em;
           text-transform: uppercase;
           color: var(--muted-foreground);
@@ -1157,24 +1172,15 @@ export class PretUISpec extends Spec {
         .fit-brief {
           display: none;
         }
-        .fit-new {
-          font-family: var(--font-mono);
-          font-size: 9px;
-          font-weight: 700;
-          letter-spacing: 0.08em;
-          color: var(--pretui-attention-ink, var(--boxel-fuschia));
-        }
         /* badge: monogram + name only */
         @container ((max-width: 139px) or (max-height: 47px)) {
           .fit-root {
-            gap: 7px;
-            padding: 5px 8px;
-          }
-          .mono {
-            width: 22px;
-            height: 22px;
-            font-size: 12px;
-            border-radius: 7px;
+            --fit-mono-size: 1.375rem;
+            --fit-mono-font-size: var(--boxel-font-size-xs);
+            --fit-mono-radius: var(--boxel-border-radius-sm);
+
+            gap: var(--boxel-sp-2xs);
+            padding: var(--boxel-sp-3xs) var(--boxel-sp-xs);
           }
           .fit-sub {
             display: none;
@@ -1183,22 +1189,20 @@ export class PretUISpec extends Spec {
         /* tile & card: stack vertically, grow the monogram */
         @container ((min-width: 140px) and (min-height: 140px)) {
           .fit-root {
+            --fit-mono-size: 2.75rem;
+            --fit-mono-font-size: var(--boxel-font-size-lg);
+            --fit-mono-radius: var(--boxel-border-radius-lg);
+
             flex-direction: column;
             align-items: flex-start;
             justify-content: flex-end;
-            padding: 12px;
-            gap: 8px;
-          }
-          .mono {
-            width: 44px;
-            height: 44px;
-            font-size: 22px;
-            border-radius: 12px;
+            padding: var(--boxel-sp-sm);
+            gap: var(--boxel-sp-xs);
           }
           .fit-extra {
             display: flex;
             align-items: center;
-            gap: 7px;
+            gap: var(--boxel-sp-2xs);
           }
         }
         /* full card: show the brief */
@@ -1208,7 +1212,7 @@ export class PretUISpec extends Spec {
             -webkit-box-orient: vertical;
             -webkit-line-clamp: 3;
             overflow: hidden;
-            font-size: var(--text-ui-sm, 11.5px);
+            font-size: var(--boxel-font-size-xs);
             color: var(--muted-foreground);
             line-height: 1.45;
             white-space: normal;
@@ -1223,7 +1227,10 @@ export class PretUISpec extends Spec {
       <div class='tile'>
         <div class='tile-head'>
           <span class='tile-name'>{{@model.componentName}}</span>
-          <StatusChip @value={{if @model.stage @model.stage 'planned'}} />
+          <StatusChip
+            @value={{stageLabel @model.stage}}
+            @tone={{stageTone @model.stage}}
+          />
         </div>
         <div class='tile-meta'>
           <span class='territory'>{{if
@@ -1236,31 +1243,31 @@ export class PretUISpec extends Spec {
       </div>
       <style scoped>
         .tile {
-          padding: var(--space-4, 11px) var(--space-5, 14px);
+          padding: var(--boxel-sp-sm) var(--boxel-sp);
           display: grid;
-          gap: var(--space-3, 8px);
+          gap: var(--boxel-sp-xs);
           align-content: start;
         }
         .tile-head {
           display: flex;
           align-items: center;
           justify-content: space-between;
-          gap: var(--space-3, 8px);
+          gap: var(--boxel-sp-xs);
         }
         .tile-name {
           font-weight: 600;
-          font-size: var(--text-ui-md, 12.5px);
+          font-size: var(--boxel-font-size-xs);
         }
         .tile-meta {
           display: flex;
           align-items: center;
           justify-content: space-between;
-          gap: var(--space-3, 8px);
+          gap: var(--boxel-sp-xs);
         }
         .territory {
           font-family: var(--font-mono);
-          font-size: var(--text-ui-xs, 11px);
-          letter-spacing: var(--track-eyebrow, 0.08em);
+          font-size: var(--boxel-font-size-2xs);
+          letter-spacing: 0.08em;
           text-transform: uppercase;
           color: var(--muted-foreground);
         }
@@ -1338,38 +1345,42 @@ export class PretUISpec extends Spec {
       </div>
       <style scoped>
         .wb-edit {
+          --wb-field-min-w: 12.5rem;
+
           display: grid;
-          gap: var(--space-5, 14px);
-          padding: var(--space-5, 14px);
+          gap: var(--boxel-sp);
+          padding: var(--boxel-sp);
         }
         .wb-group {
           border: 1px solid var(--border);
-          border-radius: var(--radius-md, 8px);
-          padding: var(--space-4, 11px) var(--space-5, 14px)
-            var(--space-5, 14px);
+          border-radius: var(--boxel-border-radius-sm);
+          padding: var(--boxel-sp-sm) var(--boxel-sp) var(--boxel-sp);
           margin: 0;
           min-width: 0;
         }
         .wb-group > legend {
-          font-size: var(--text-ui-xs, 11px);
+          font-size: var(--boxel-font-size-2xs);
           font-weight: 600;
-          letter-spacing: var(--track-eyebrow, 0.08em);
+          letter-spacing: 0.08em;
           text-transform: uppercase;
           color: var(--muted-foreground);
-          padding-inline: var(--space-2, 6px);
+          padding-inline: var(--boxel-sp-2xs);
         }
         .wb-fields {
           display: grid;
-          grid-template-columns: repeat(auto-fit, minmax(200px, 1fr));
-          gap: var(--space-3, 8px) var(--space-4, 11px);
+          grid-template-columns: repeat(
+            auto-fit,
+            minmax(min(var(--wb-field-min-w), 100%), 1fr)
+          );
+          gap: var(--boxel-sp-xs) var(--boxel-sp-sm);
         }
         .wb-fields > label,
         .wb-fields > div {
           display: grid;
-          gap: var(--space-2, 6px);
-          font-size: var(--text-ui-xs, 11px);
+          gap: var(--boxel-sp-2xs);
+          font-size: var(--boxel-font-size-2xs);
           font-weight: 600;
-          letter-spacing: var(--track-eyebrow, 0.04em);
+          letter-spacing: 0.04em;
           text-transform: uppercase;
           color: var(--muted-foreground);
           min-width: 0;
diff --git a/packages/pretui/pretui-component.test.gts b/packages/pretui/pretui-component.test.gts
index 7a80b614b7d..e20b11669c7 100644
--- a/packages/pretui/pretui-component.test.gts
+++ b/packages/pretui/pretui-component.test.gts
@@ -78,7 +78,7 @@ module('Pretui | PretUISpec', function (hooks) {
   test('the breadcrumb names the kit without linking to a catalog card this package does not ship', async function (assert) {
     let model = specModel('Button');
     await render(<template><Isolated @model={{model}} /></template>);
-    assert.dom('[data-test-pretui-spec-crumb]').containsText('Pretui');
+    assert.dom('[data-test-pretui-spec-crumb]').containsText('Pret UI');
     assert.dom('[data-test-pretui-spec-crumb] button').doesNotExist('no navigation to a card that is not here');
   });
 
diff --git a/packages/pretui/pretui-note.gts b/packages/pretui/pretui-note.gts
index 2a8c1691b7d..fea1a8c9159 100644
--- a/packages/pretui/pretui-note.gts
+++ b/packages/pretui/pretui-note.gts
@@ -10,13 +10,13 @@
 //   - The note LINKS to its component (`target`), so the relationship is a
 //     real edge in the graph rather than a name match. The component page
 //     finds its own notes by querying for that edge.
-//   - Colour is the Law 2 recipe over one hue, not a hardcoded yellow, so a
-//     sticky re-tints with the season and reads correctly in light or dark.
-//     `--pretui-note-hue` is the knob.
-//   - `status` is deliberately a plain string rather than an enum field: an
-//     agent writes it, and a value this small does not need a field class.
-//     Anything that is not 'addressed' counts as open, so a note created by
-//     hand with no status set still shows up in the queue.
+//   - Color is a tint of `--attention`, not a hardcoded yellow, so a sticky
+//     re-tints with the theme and reads correctly in light or dark.
+//   - `status` is an Open / Addressed enum. Anything that is not
+//     'addressed' counts as open, so a note created with no status set still
+//     shows up in the queue.
+//   - The title is `cardTitle`: `cardInfo.name` when one is set, otherwise
+//     the note's first line, so a note is never "Untitled" in a list.
 import {
   CardDef,
   Component,
@@ -27,7 +27,14 @@ import {
 import type { RealmResourceIdentifier } from '@cardstack/runtime-common';
 import StringField from 'https://cardstack.com/base/string';
 import MarkdownField from 'https://cardstack.com/base/markdown';
+import DateField from 'https://cardstack.com/base/date';
+import enumField from 'https://cardstack.com/base/enum';
+import { FittedCard } from '@cardstack/boxel-ui/components';
+import StickyNoteIcon from '@cardstack/boxel-icons/sticky-note';
 import { on } from '@ember/modifier';
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { Button } from './components/button';
+import { Chip } from './components/chip';
 import { PretUISpec } from './pretui-component';
 
 /** A note is open unless it has been explicitly addressed. */
@@ -51,28 +58,48 @@ export function noteSummary(note: string | undefined): string {
   return plain.length > 72 ? `${plain.slice(0, 71)}…` : plain;
 }
 
+// The note's state as a chip: open is filled with the note's own attention
+// tone, addressed with success.
+const NoteStatus: TemplateOnlyComponent<{
+  Args: { addressed: boolean };
+  Element: HTMLSpanElement;
+}> = <template>
+  <Chip
+    @label={{if @addressed 'Addressed' 'Open'}}
+    @tone={{if @addressed 'success' 'attention'}}
+    data-test-pretui-note-status
+    ...attributes
+  />
+</template>;
+
 export class PretuiNote extends CardDef {
   static displayName = 'Sticky Note';
+  static icon = StickyNoteIcon;
 
   /** what you want changed, in your own words */
   @field note = contains(MarkdownField);
   /** the component this note is stuck to */
   @field target = linksTo(() => PretUISpec);
   /** 'open' (default, and anything unrecognised) or 'addressed' */
-  @field status = contains(StringField);
+  @field status = contains(
+    enumField(StringField, {
+      options: [
+        { value: 'open', label: 'Open' },
+        { value: 'addressed', label: 'Addressed' },
+      ],
+    }),
+  );
   /** what the agent actually did about it — written when the note is closed */
   @field resolution = contains(MarkdownField);
-  /** ISO date the note was left. Stamped at creation by the page that
+  /** the date the note was left. Stamped at creation by the page that
    *  creates it, never read from the clock at render time. */
-  @field noted = contains(StringField);
+  @field noted = contains(DateField);
   /** who left it, when that is worth recording */
   @field author = contains(StringField);
 
-  /** Derived so a note is never "Untitled" in a list, a search result, or the
-   *  assistant's card picker — the note text IS the title. */
-  @field title = contains(StringField, {
+  @field cardTitle = contains(StringField, {
     computeVia: function (this: PretuiNote) {
-      return noteSummary(this.note);
+      return this.cardInfo?.name?.trim() || noteSummary(this.note);
     },
   });
 
@@ -88,137 +115,135 @@ export class PretuiNote extends CardDef {
     }
 
     <template>
-      <article
-        class='note-page'
-        data-addressed={{if this.addressed 'true'}}
-        data-test-pretui-note-page
-      >
-        <header class='note-head'>
-          <span class='note-cap'>Sticky note</span>
-          <span class='note-state'>{{if this.addressed 'addressed' 'open'}}</span>
-          {{#if @model.noted}}
-            <span class='note-when'>{{@model.noted}}</span>
+      <div class='note-isolated'>
+        <article
+          class='note-page'
+          data-addressed={{if this.addressed 'true'}}
+          data-test-pretui-note-page
+        >
+          <header class='note-head'>
+            <span class='note-cap'>Sticky note</span>
+            <NoteStatus @addressed={{this.addressed}} />
+            {{#if @model.noted}}
+              <span class='note-when'><@fields.noted /></span>
+            {{/if}}
+          </header>
+
+          <h1><@fields.cardTitle /></h1>
+          {{#if @model.cardDescription}}
+            <p class='note-summary'><@fields.cardDescription /></p>
           {{/if}}
-        </header>
 
-        <div class='note-body'><@fields.note /></div>
+          <div><@fields.note /></div>
 
-        {{#if @model.target}}
-          <button
-            type='button'
-            class='note-target'
-            {{on 'click' this.openTarget}}
-            data-test-pretui-note-target
-          >
-            On
-            <strong>{{if
-                @model.target.componentName
-                @model.target.componentName
-                'a component'
-              }}</strong>
-          </button>
-        {{/if}}
+          {{#if @model.target}}
+            <Button
+              class='note-target'
+              @tone='neutral'
+              @appearance='outlined'
+              @size='xs'
+              {{on 'click' this.openTarget}}
+              data-test-pretui-note-target
+            >
+              Open
+              <strong>{{if
+                  @model.target.componentName
+                  @model.target.componentName
+                  'a component'
+                }}</strong>
+            </Button>
+          {{/if}}
 
-        {{#if @model.resolution}}
-          <section class='note-fix'>
-            <span class='note-cap'>What got fixed</span>
-            <div class='note-body'><@fields.resolution /></div>
-          </section>
-        {{/if}}
+          {{#if @model.resolution}}
+            <section class='note-fix'>
+              <h2 class='note-cap'>What got fixed</h2>
+              <div><@fields.resolution /></div>
+            </section>
+          {{/if}}
 
-        {{#if @model.author}}
-          <footer class='note-foot'>— {{@model.author}}</footer>
-        {{/if}}
-      </article>
+          {{#if @model.author}}
+            <footer class='note-foot'>— <@fields.author /></footer>
+          {{/if}}
+        </article>
+      </div>
 
       <style scoped>
-        /* Law 2: one hue in, a complete treatment out. The sticky is a tint
-           of --pretui-note-hue over --card, with ink derived from the same
-           hue — so it holds contrast in light AND dark without a branch. */
+        /* the isolated page owns the scroll and the margin; the sticky sits
+           on it as a card */
+        .note-isolated {
+          --note-page-max-w: 40rem;
+
+          height: 100%;
+          overflow-y: auto;
+          padding: var(--boxel-sp-lg);
+        }
+        /* The sticky is a tint of --attention over --card with --foreground
+           text and --attention-ink labels, which hold contrast in light and
+           dark. An addressed note goes to the neutral --muted surface. */
         .note-page {
-          --hue: var(--pretui-note-hue, var(--chart-3));
           display: flex;
           flex-direction: column;
-          gap: var(--space-3, 10px);
-          padding: var(--space-5, 18px);
-          border-radius: var(--radius-surface, 10px);
-          background: color-mix(in oklch, var(--hue) 14%, var(--card));
-          color: color-mix(in oklch, var(--foreground) 16%, var(--hue));
-          /* Law 1: depth is hairline + shadow, never contrast. */
-          box-shadow: var(
-            --pretui-shadow-card,
-            0 0 0 1px var(--border),
-            0 1px 2px rgb(0 0 0 / 0.2),
-            0 2px 6px rgb(0 0 0 / 0.2)
+          gap: var(--boxel-sp-xs);
+          max-inline-size: var(--note-page-max-w);
+          margin-inline: auto;
+          padding: var(--boxel-sp);
+          border-radius: var(--boxel-border-radius);
+          background-color: color-mix(
+            in oklch,
+            var(--attention) 14%,
+            var(--card)
           );
+          color: var(--foreground);
+          box-shadow:
+            0 0 0 1px var(--border),
+            var(--shadow-sm);
         }
         .note-page[data-addressed='true'] {
-          --hue: var(--muted-foreground);
+          background-color: var(--muted);
+        }
+        .note-page[data-addressed='true']
+          :is(.note-cap, .note-when, .note-foot) {
+          color: var(--muted-foreground);
         }
         .note-head {
           display: flex;
           align-items: baseline;
-          gap: var(--space-3, 10px);
+          gap: var(--boxel-sp-xs);
+        }
+        /* the sticky's own labels read in its attention ink; the title and
+           body keep the surface's --foreground */
+        .note-cap,
+        .note-when,
+        .note-foot {
+          color: var(--attention-ink);
         }
         .note-cap {
-          font-size: var(--text-ui-xs, 11px);
-          font-weight: 600;
-          letter-spacing: var(--track-eyebrow, 0.06em);
+          font-family: var(--boxel-eyebrow-font-family);
+          font-size: var(--boxel-eyebrow-font-size);
+          font-weight: var(--boxel-eyebrow-font-weight);
+          line-height: var(--boxel-eyebrow-line-height);
+          letter-spacing: var(--boxel-eyebrow-letter-spacing);
           text-transform: uppercase;
-          color: color-mix(
-            in oklch,
-            var(--foreground) 45%,
-            var(--hue)
-          );
         }
-        .note-state,
         .note-when {
           font-family: var(--font-mono);
-          font-size: var(--text-ui-xs, 11px);
-          color: color-mix(
-            in oklch,
-            var(--foreground) 45%,
-            var(--hue)
-          );
+          font-size: var(--boxel-caption-font-size);
         }
-        .note-body {
-          font-size: var(--text-ui-md, 12.5px);
-          line-height: 1.6;
-          color: var(--foreground);
+        .note-summary {
+          color: var(--muted-foreground);
         }
         .note-target {
           align-self: flex-start;
-          padding: 4px 9px;
-          border: 0;
-          border-radius: var(--radius-control, 7px);
-          background: var(--card);
-          box-shadow: var(
-            --pretui-shadow-control,
-            0 0 0 1px var(--border)
-          );
-          font-size: var(--text-ui-xs, 11px);
-          color: var(--foreground);
-          cursor: pointer;
-        }
-        .note-target:focus-visible {
-          outline: 2px solid var(--ring);
-          outline-offset: 2px;
         }
         .note-fix {
           display: flex;
           flex-direction: column;
-          gap: var(--space-2, 6px);
-          padding-top: var(--space-3, 10px);
-          box-shadow: inset 0 1px 0 0
-            color-mix(in oklch, var(--hue) 30%, transparent);
+          gap: var(--boxel-sp-2xs);
+          padding-block-start: var(--boxel-sp-xs);
+          box-shadow: inset 0 1px 0 0 var(--border);
         }
         .note-foot {
-          font-size: var(--text-ui-xs, 11px);
-          color: color-mix(
-            in oklch,
-            var(--foreground) 45%,
-            var(--hue)
-          );
+          font-size: var(--boxel-caption-font-size);
         }
       </style>
     </template>
@@ -234,39 +259,27 @@ export class PretuiNote extends CardDef {
         data-addressed={{if this.addressed 'true'}}
         data-test-pretui-note-embedded
       >
+        <NoteStatus class='sticky-status' @addressed={{this.addressed}} />
         <div class='sticky-body'><@fields.note /></div>
-        {{#if this.addressed}}
-          <span class='sticky-done'>addressed</span>
-        {{/if}}
       </div>
       <style scoped>
         .sticky {
-          --hue: var(--pretui-note-hue, var(--chart-3));
           display: flex;
           flex-direction: column;
-          gap: var(--space-2, 6px);
-          padding: var(--space-3, 10px);
-          border-radius: var(--radius-surface, 10px);
-          background: color-mix(in oklch, var(--hue) 14%, var(--card));
-          box-shadow: var(
-            --pretui-shadow-card,
-            0 0 0 1px var(--border),
-            0 1px 2px rgb(0 0 0 / 0.2)
+          gap: var(--boxel-sp-2xs);
+          padding: var(--boxel-sp-xs);
+          background-color: color-mix(
+            in oklch,
+            var(--attention) 14%,
+            var(--card)
           );
-          font-size: var(--text-ui-md, 12.5px);
-          line-height: 1.5;
           color: var(--foreground);
         }
         .sticky[data-addressed='true'] {
-          --hue: var(--muted-foreground);
-          color: var(--muted-foreground);
+          background-color: var(--muted);
         }
-        .sticky-done {
-          font-family: var(--font-mono);
-          font-size: var(--text-ui-xs, 11px);
-          letter-spacing: var(--track-eyebrow, 0.06em);
-          text-transform: uppercase;
-          color: var(--muted-foreground);
+        .sticky-status {
+          align-self: flex-start;
         }
       </style>
     </template>
@@ -277,56 +290,45 @@ export class PretuiNote extends CardDef {
       return isAddressed(this.args.model.status);
     }
     <template>
-      <div
+      <FittedCard
         class='nfit'
+        @titleTag='h3'
+        @imageUrl={{@model.cardThumbnailURL}}
         data-addressed={{if this.addressed 'true'}}
         data-test-pretui-note-fitted
       >
-        <span class='nfit-dot'></span>
-        {{! the computed title is the note's first line, already flattened out
-            of markdown — the raw field would show `#`/backtick furniture }}
-        <span class='nfit-title'>{{if @model.title @model.title 'Sticky note'}}</span>
-        <span class='nfit-on'>{{if
-            @model.target.componentName
-            @model.target.componentName
-            ''
-          }}</span>
-      </div>
+        <:badgeRow><NoteStatus @addressed={{this.addressed}} /></:badgeRow>
+        <:title><@fields.cardTitle /></:title>
+        <:subtitle>
+          {{#if @model.cardDescription}}
+            <@fields.cardDescription />
+          {{else if @model.target.componentName}}
+            On
+            {{@model.target.componentName}}
+          {{/if}}
+        </:subtitle>
+        <:footer>
+          {{#if @model.author}}<span><@fields.author /></span>{{/if}}
+          {{#if @model.noted}}<@fields.noted />{{/if}}
+        </:footer>
+      </FittedCard>
       <style scoped>
+        /* FittedCard's fade knob doubles as the surface color, so a
+           thumbnail fades into the same tint the card is painted with */
         .nfit {
-          --hue: var(--pretui-note-hue, var(--chart-3));
-          display: flex;
-          align-items: center;
-          gap: var(--space-2, 6px);
-          width: 100%;
-          height: 100%;
-          padding: var(--space-3, 10px);
-          background: color-mix(in oklch, var(--hue) 14%, var(--card));
-          font-size: var(--text-ui-md, 12.5px);
-          color: var(--foreground);
-          overflow: hidden;
+          --fc-image-fade-color: color-mix(
+            in oklch,
+            var(--attention) 14%,
+            var(--card)
+          );
+
+          background-color: var(--fc-image-fade-color);
+          color: var(--card-foreground);
         }
         .nfit[data-addressed='true'] {
-          --hue: var(--muted-foreground);
-        }
-        .nfit-dot {
-          flex: none;
-          width: 7px;
-          height: 7px;
-          border-radius: 999px;
-          background: var(--hue);
-        }
-        .nfit-title {
-          font-weight: 600;
-          white-space: nowrap;
-          overflow: hidden;
-          text-overflow: ellipsis;
-        }
-        .nfit-on {
-          font-family: var(--font-mono);
-          font-size: var(--text-ui-xs, 11px);
-          color: var(--muted-foreground);
-          white-space: nowrap;
+          --fc-image-fade-color: var(--muted);
+
+          color: var(--foreground);
         }
       </style>
     </template>
diff --git a/packages/pretui/pretui-note.test.gts b/packages/pretui/pretui-note.test.gts
index 141ad9988c0..7b097171137 100644
--- a/packages/pretui/pretui-note.test.gts
+++ b/packages/pretui/pretui-note.test.gts
@@ -22,7 +22,11 @@ module('Pretui | PretuiNote', function (hooks) {
       target: { id: targetId, componentName: 'Button' },
     };
     let fields = { note: NoteField };
-    await render(<template><Isolated @model={{model}} @fields={{fields}} @viewCard={{viewCard}} /></template>);
+    await render(
+      <template>
+        <Isolated @model={{model}} @fields={{fields}} @viewCard={{viewCard}} />
+      </template>,
+    );
     await click('[data-test-pretui-note-target]');
     assert.deepEqual(viewed, [targetId]);
   });

From 16cbb16df77506c65e45f5ecda49b803263e6a59 Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Wed, 7 Oct 2026 18:08:25 -0400
Subject: [PATCH 11/30] Fix the UI review findings: keep catalog chips' size
 and outline, paint Table cells, use the eyebrow role, head the Spec panels,
 and correct the docs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/components/chip.gts           |  13 +-
 packages/pretui/components/chip.md            |   4 +-
 .../pretui/components/freestyle-usage.gts     |   5 +-
 packages/pretui/components/freestyle-usage.md |   8 +-
 packages/pretui/components/status-chip.md     |   4 +-
 packages/pretui/components/table.gts          |  10 +-
 packages/pretui/components/table.md           |   2 +-
 packages/pretui/components/theme-frame.md     |   2 +-
 packages/pretui/components/token.md           |   2 +
 packages/pretui/components/usage-argument.gts |  14 +-
 packages/pretui/components/usage-string.md    |   2 +-
 packages/pretui/example-gallery.gts           |   2 +-
 packages/pretui/pretui-component.gts          | 121 +++++++++++++-----
 13 files changed, 127 insertions(+), 62 deletions(-)

diff --git a/packages/pretui/components/chip.gts b/packages/pretui/components/chip.gts
index 693fab0c958..15c7f9aa2c6 100644
--- a/packages/pretui/components/chip.gts
+++ b/packages/pretui/components/chip.gts
@@ -56,7 +56,8 @@ export class Chip extends Component<ChipSignature> {
           height: var(--pretui-chip-height);
           padding: 0 var(--boxel-sp-2xs);
           border-radius: var(--boxel-border-radius-xs);
-          font-size: var(--boxel-font-size-2xs);
+          /* --text-ui-xs is the legacy size knob catalog chips still set */
+          font-size: var(--pretui-chip-font-size, var(--boxel-font-size-2xs));
           font-weight: 500;
           letter-spacing: var(--boxel-lsp-xs);
           white-space: nowrap;
@@ -72,6 +73,16 @@ export class Chip extends Component<ChipSignature> {
             var(--foreground) var(--pretui-ink-mix, 100%),
             var(--pretui-chip-hue)
           );
+          /* the hue hairline legacy chips were drawn with: any
+             --pretui-chip-mix above 0% shows it at full strength, and the
+             default 0% leaves it transparent */
+          box-shadow: 0 0 0 1px
+            color-mix(
+              in oklch,
+              color-mix(in oklch, var(--pretui-chip-hue) 45%, var(--border))
+                min(calc(var(--pretui-chip-mix, 0%) * 100), 100%),
+              transparent
+            );
         }
         /* a toned chip is outlined on --card: its -ink draws the text and the
            ring (the fill hue misses 3:1 as a ring), the dot takes the tone */
diff --git a/packages/pretui/components/chip.md b/packages/pretui/components/chip.md
index eb1c6c88786..bef4aa7aded 100644
--- a/packages/pretui/components/chip.md
+++ b/packages/pretui/components/chip.md
@@ -36,11 +36,11 @@ That is the right answer for a static chip, and it means the accessibility quest
 
 ## Theming
 
-`--muted` / `--foreground` (a neutral pill and its text), `--card` with each tone's `--x-ink` (text and ring) and `--x` (dot) for a toned chip, `--pretui-chip-hue` (the dot, defaulting to `--muted-foreground`, or the tone on a toned chip), `--boxel-border-radius-xs`, `--boxel-font-size-2xs`, `--boxel-lsp-xs`, and the `--boxel-sp-*` spacing scale. `--pretui-chip-height` and `--pretui-chip-dot-size` set the pill height and dot size.
+`--muted` / `--foreground` (a neutral pill and its text), `--card` with each tone's `--x-ink` (text and ring) and `--x` (dot) for a toned chip, `--pretui-chip-hue` (the dot, defaulting to `--muted-foreground`, or the tone on a toned chip), `--boxel-border-radius-xs`, `--boxel-font-size-2xs`, `--boxel-lsp-xs`, and the `--boxel-sp-*` spacing scale. `--pretui-chip-height`, `--pretui-chip-dot-size` and `--pretui-chip-font-size` set the pill height, dot size and text size.
 
 A theme restyles every chip through `--muted` and `--foreground`, and the dot colors through the `--chart-*` tokens. Dark mode needs nothing extra: the theme's dark `--muted` / `--foreground` pair applies.
 
-`--pretui-chip-mix` and `--pretui-ink-mix` are legacy knobs that tint a neutral chip's surface and text toward `--pretui-chip-hue`; they are kept for callers that still set them, and new code uses `@tone`.
+`--pretui-chip-mix` and `--pretui-ink-mix` are legacy knobs that tint a neutral chip's surface and text toward `--pretui-chip-hue`, and any `--pretui-chip-mix` above 0% also draws the hue hairline those chips were designed with. `--text-ui-xs` is the legacy text-size knob, read when `--pretui-chip-font-size` is unset. All three are kept for callers that still set them; new code uses `@tone` and `--pretui-chip-font-size`.
 
 The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
 
diff --git a/packages/pretui/components/freestyle-usage.gts b/packages/pretui/components/freestyle-usage.gts
index 07e67424d12..de5b1aed921 100644
--- a/packages/pretui/components/freestyle-usage.gts
+++ b/packages/pretui/components/freestyle-usage.gts
@@ -51,7 +51,7 @@ export interface FreestyleUsageSignature {
 export const FreestyleUsage: TemplateOnlyComponent<FreestyleUsageSignature> =
   <template>
     <div class='pretui-usage' data-test-pretui-usage ...attributes>
-      {{! identity lives in the page header (breadcrumb) — no h2 here; one
+      {{! the component's name lives in the page header (breadcrumb); one
           compact description line, then straight to the artboard }}
       {{#if (has-block 'description')}}
         <p
@@ -282,8 +282,5 @@ export const FreestyleUsage: TemplateOnlyComponent<FreestyleUsageSignature> =
       .wb-cap {
         margin-block-end: 0;
       }
-      .pretui-usage-api {
-        min-width: 0;
-      }
     </style>
   </template>;
diff --git a/packages/pretui/components/freestyle-usage.md b/packages/pretui/components/freestyle-usage.md
index 9875b4a3cc5..560695990a4 100644
--- a/packages/pretui/components/freestyle-usage.md
+++ b/packages/pretui/components/freestyle-usage.md
@@ -24,7 +24,7 @@ Where the Pretui port differs, and each is a deliberate delta:
 - **The machinery wears the kit.** **Select**, **Input**, **Switch** and **Slider** are the knob controls; **Table** renders the API docs; **Viewport** frames every example. So the documentation surface dogfoods the components it documents — a broken Select breaks its own usage page, which is a useful forcing function Storybook's React-based panel does not have.
 - **The dual-lens `<:api>`** (above). Storybook derives its controls table from types; freestyle makes you author knobs; this makes you author once and renders both.
 - **No ember-freestyle service.** The upstream keeps a global service for section registration; this is component-local, which suits a realm where a page is a card.
-- **Plain `<pre>` for `@source`.** No syntax highlighter — Law 9 forbids vendoring one, and the trade is stated rather than hidden.
+- **Plain `<code>` for `@source`.** No syntax highlighter — Law 9 forbids vendoring one, and the trade is stated rather than hidden.
 - **Labeled controls**, where upstream's are bare.
 
 Where it is behind Storybook, honestly: no addons, no interaction testing, no accessibility panel, no visual regression, and no auto-generated argTypes.
@@ -38,12 +38,12 @@ Gaps worth knowing, because a documentation surface is read by exactly the peopl
 - **Only part of the page has heading structure.** Properties, API and CSS Variables are headed by `h2`s, so heading navigation reaches the knobs and the tables, and Properties is an `<aside>`. The description and the example have no heading, and no region carries an `aria-label`, so a screen-reader user cannot jump to "the example", and landmark navigation finds an unnamed complementary region.
 - **`@name` is not necessarily a heading**, and if it is, its level is fixed — the kit-wide problem (**Panel**, **Toolbar**, **EmptyState**, **Stat**, **FittedCard** all share it).
 - **The knobs and the API table describe the same arguments and are not linked.** A user reading a row in the docs table has no route to the control that changes it.
-- **The `<pre>` source block** needs `tabindex="0"` if it scrolls, or a keyboard user cannot reach the end of a long line (**WCAG 2.1.1**), and it has no language annotation.
+- **The `<code>` source strip** needs `tabindex="0"` if it scrolls, or a keyboard user cannot reach the end of a long line (**WCAG 2.1.1**), and it has no language annotation.
 - **Changing a knob re-renders the example silently.** A `role="status"` region would make the cause-and-effect available; without it, a screen-reader user changing a Select has no confirmation that anything happened.
 - **The example region contains arbitrary live components**, so the page's overall accessibility is whatever is being demonstrated — including deliberately-broken states. That is unavoidable and worth stating: a usage page is not a claim about the component's accessibility.
 
 ## Theming
 
-Composes **Viewport**, **Table**, **Select**, **Input**, **Switch**, **Slider**, **SegmentedControl**, **CopyButton** and **Popover**, so it consumes their token sets rather than defining many of its own. Page structure uses `--card`, `--inset`, `--border`, `--foreground`, `--muted-foreground` and the type scale; the property list and API table pick up **Label**'s eyebrow voice.
+Composes **Viewport**, **Table**, **Select**, **Input**, **Switch**, **Slider**, **SegmentedControl**, **CopyButton** and **Popover**, so it consumes their token sets rather than defining many of its own. Page structure uses `--card` with `--card-foreground`, `--border`, `--muted-foreground`, `--boxel-border-radius` and the `--boxel-sp-*` scale; the section titles take the eyebrow role (`--boxel-eyebrow-*`).
 
-The whole page renders inside the theme island, so a season change re-dresses both the documentation chrome _and_ the example — which is the point, and is what **ThemeFrame** exists to drive.
+The whole page renders inside the theme island, so a theme change re-dresses both the documentation chrome _and_ the example — which is the point, and is what **ThemeFrame** exists to drive.
diff --git a/packages/pretui/components/status-chip.md b/packages/pretui/components/status-chip.md
index 0c33a55ce6f..adf903bf7dd 100644
--- a/packages/pretui/components/status-chip.md
+++ b/packages/pretui/components/status-chip.md
@@ -14,7 +14,7 @@ Three args, and the last two you should rarely reach for. A toned StatusChip is
 
 **The hue is a hash, and the hash is the point.** `statusHue()` runs a 32-bit polynomial rolling hash (`h * 31 + charCode`, unsigned) over the string and takes `h % 5` to index `--chart-1` … `--chart-5`. Deterministic, dependency-free, and — the property that matters — **stable across cards, realms and sessions**. No registry, no config, no design review to add a status.
 
-The corollary worth stating plainly: **the hue carries no semantics.** "Failed" is not red because it means failure; it is whatever colour its characters hash to. Five buckets also means collisions are common — with six statuses, two will share a colour. If your states have meaning that must be conveyed by colour (error/warning/success), **this is the wrong component** — use **Chip** with an explicit semantic hue, or **Alert**.
+The corollary worth stating plainly: **the hue carries no semantics.** "Failed" is not red because it means failure; it is whatever colour its characters hash to. Five buckets also means collisions are common — with six statuses, two will share a colour. If your states have meaning that must be conveyed by colour (error/warning/success), **the hash is the wrong tool** — pass a `@tone` (StatusChip takes one for a fixed status like `live`, **Chip** for anything else), or use **Alert**.
 
 ## Prior art
 
@@ -26,7 +26,7 @@ Pretui's bet is different: in a system where cards are authored quickly and a st
 
 Where that bet is better than the alternatives: zero configuration, zero drift, and it works for values the system has never seen. Where it is worse, and it is worth being blunt: **five buckets is a small palette**, collisions are frequent and invisible, and the colour will occasionally be actively misleading — a hash that paints "Cancelled" green is not a bug you can fix without the `@hue` escape. Neither Web Awesome nor Spectrum has that failure mode.
 
-The pragmatic guidance: use StatusChip for open-ended categorical fields, and **Chip** with a deliberate hue for anything where the colour is load-bearing.
+The pragmatic guidance: use StatusChip for open-ended categorical fields, and a `@tone` for anything where the colour is load-bearing.
 
 ## Accessibility
 
diff --git a/packages/pretui/components/table.gts b/packages/pretui/components/table.gts
index 6ff142e9809..3343e36b843 100644
--- a/packages/pretui/components/table.gts
+++ b/packages/pretui/components/table.gts
@@ -135,13 +135,15 @@ export const Table: TemplateOnlyComponent<TableSignature> = <template>
       .pretui-table :deep(tbody th) {
         text-align: start;
       }
-      /* zebra and hover paint the row, beneath its cells, so a caller's
-         own cell background still shows */
-      .pretui-table :deep(tbody tr:nth-child(even)) {
+      /* on the cells, so a caller that repaints a cell replaces the stripe
+         or hover instead of stacking a second one over the row's */
+      .pretui-table :deep(tbody tr:nth-child(even) td),
+      .pretui-table :deep(tbody tr:nth-child(even) th) {
         background-color: var(--stripe);
       }
       @media (hover: hover) {
-        .pretui-table :deep(tbody tr:hover) {
+        .pretui-table :deep(tbody tr:hover td),
+        .pretui-table :deep(tbody tr:hover th) {
           background-color: var(--hover);
         }
       }
diff --git a/packages/pretui/components/table.md b/packages/pretui/components/table.md
index 21f2e628580..e85f26f68f5 100644
--- a/packages/pretui/components/table.md
+++ b/packages/pretui/components/table.md
@@ -20,7 +20,7 @@ Element: HTMLDivElement
 
 **`@label` and `@labelledBy` name the `<table>`, which deliberately differs from DataTable.** DataTable's `@label` names its scroll region (a `role='region'` box with a tab stop) and sits alongside its caption: the caption names the table, the label names the region. Table has no such region — its wrapper is a plain `<div>` — so the only thing left to name is the `<table>`, and a caption already does that. Hence `@label` and `@labelledBy` here are the caption's stand-ins rather than a second name, and are dropped when a caption renders.
 
-The one non-obvious thing: **the yielded cells are styled partly through `:deep()`.** The component renders `<thead>` and `<tbody>` itself, so the inherited properties sit on those two elements and flow into your cells: the mono header voice, its ink and `nowrap` on `thead`, and top alignment on `tbody`. What the browser's `th` rule overrides (weight, alignment) and what doesn't inherit (padding, height, backgrounds, row rules, the sticky position) has to reach into content the component did not render, so `.pretui-table :deep(thead th)`, `:deep(td)`, `:deep(tbody th)`, `:deep(tbody tr:nth-child(even))`, `:deep(tbody tr:hover)` and `:deep(tbody tr:last-child td)` (with its `th` twin, which drops the last row rule where the frame already draws the edge) do that work. Zebra and hover paint the row, beneath its cells, so a caller's own cell background still shows. This is a legitimate, narrow use of the escape hatch — the alternative would be a `<Table.Row>`/`<Table.Cell>` component pair, which buys type safety at the cost of the "just write a table" affordance the component exists to provide.
+The one non-obvious thing: **the yielded cells are styled partly through `:deep()`.** The component renders `<thead>` and `<tbody>` itself, so the inherited properties sit on those two elements and flow into your cells: the mono header voice, its ink and `nowrap` on `thead`, and top alignment on `tbody`. What the browser's `th` rule overrides (weight, alignment) and what doesn't inherit (padding, height, backgrounds, row rules, the sticky position) has to reach into content the component did not render, so `.pretui-table :deep(thead th)`, `:deep(td)`, `:deep(tbody th)`, `:deep(tbody tr:nth-child(even) td)`, `:deep(tbody tr:hover td)` and `:deep(tbody tr:last-child td)` (each with its `th` twin; the last one drops the last row rule where the frame already draws the edge) do that work. Zebra and hover paint the cells, so a caller that repaints a cell replaces them rather than tinting over them. This is a legitimate, narrow use of the escape hatch — the alternative would be a `<Table.Row>`/`<Table.Cell>` component pair, which buys type safety at the cost of the "just write a table" affordance the component exists to provide.
 
 **The header band is scoped to `thead`.** Only the column headers in `<:head>` get the sticky mono band; the header voice is set on `thead`, so it never reaches the body. A row header — `<th scope='row'>` in `<:body>` — wears the body-cell rules instead: the cell padding, the row rule, zebra and hover, top alignment and start alignment, keeping the browser's bold `th` weight. So a matrix with row headers needs no override to undo the band.
 
diff --git a/packages/pretui/components/theme-frame.md b/packages/pretui/components/theme-frame.md
index 73af2148718..ae616f2a5a4 100644
--- a/packages/pretui/components/theme-frame.md
+++ b/packages/pretui/components/theme-frame.md
@@ -21,7 +21,7 @@ It is a tool, not a product control — a real application's theme setting belon
 
 **The frame owns the switching state**: the mode and the selected theme id live here, starting light like ThemeDashboard. The Boxel chrome around the frame has fixed colors, so the switch previews dark mode rather than following the reader's system setting. What it does not own is _persistence_ — nothing is written to storage, so a host that wants the choice to survive a reload stores it itself.
 
-**`@context` is the switch between one theme and all of them.** Without it the frame dresses its content in `@theme` and offers only the mode switch and the theme's name; with it, the frame queries the realm for every Theme instance and a **Select** replaces the name.
+**`@context` is the switch between one theme and all of them.** Without it the frame dresses its content in `@theme` and offers only the mode switch and the theme's name; with it, the frame queries the realm for every Theme instance, and when it finds more than one, a **Select** replaces the name.
 
 **`@bar={{false}}`** stops the frame drawing its own bar when the page seats the yielded controls in its own header.
 
diff --git a/packages/pretui/components/token.md b/packages/pretui/components/token.md
index 48b53e3db90..6c7ffe2e847 100644
--- a/packages/pretui/components/token.md
+++ b/packages/pretui/components/token.md
@@ -59,3 +59,5 @@ Notes and gaps:
 `--card` (the surface) with `--card-foreground` (the text) and `--border` (the ring), plus `--boxel-border-radius-xs`, `--boxel-sp-2xs` and `--font-mono`. `--pretui-token-hue` sets the text color, on the Token (through `@hue`, a class or `style`) or on any ancestor; pass an ink such as `--primary-ink` or `--muted-foreground`, not a pale fill hue. `--pretui-token-font-size` sets an exact size; unset, the default is `--boxel-font-size-2xs`, and `@size` takes the house scale (`--pretui-size-*`).
 
 The default line height matches Chip's 18px, so a Token and a Chip side by side line up.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
diff --git a/packages/pretui/components/usage-argument.gts b/packages/pretui/components/usage-argument.gts
index 4806a4425d5..c79b2c8a435 100644
--- a/packages/pretui/components/usage-argument.gts
+++ b/packages/pretui/components/usage-argument.gts
@@ -56,12 +56,14 @@ export class UsageArgument extends Component<UsageArgumentSignature> {
             >*</span>{{/if}}
         </td>
         <td class='pretui-usage-arg-type'>{{this.typeLabel}}</td>
-        <td class='pretui-usage-arg-description'>{{@description}}</td>
+        <td><span
+            class='pretui-usage-arg-description-text'
+          >{{@description}}</span></td>
         <td class='pretui-usage-arg-default'>
           {{#if this.shouldRenderDefaultValue}}
             {{this.defaultText}}
           {{else}}
-            <span class='u-none'>—</span>
+            —
           {{/if}}
         </td>
       </tr>
@@ -90,8 +92,9 @@ export class UsageArgument extends Component<UsageArgumentSignature> {
         width: 1%;
         text-transform: lowercase;
       }
-      .pretui-usage-arg-description {
-        color: var(--foreground);
+      /* on a span: table layout ignores max-width on a cell */
+      .pretui-usage-arg-description-text {
+        display: block;
         max-width: var(--pretui-usage-arg-description-max-w);
       }
       .pretui-usage-arg-default {
@@ -102,9 +105,6 @@ export class UsageArgument extends Component<UsageArgumentSignature> {
         white-space: nowrap;
         width: 1%;
       }
-      .u-none {
-        color: var(--muted-foreground);
-      }
     </style>
   </template>
 }
diff --git a/packages/pretui/components/usage-string.md b/packages/pretui/components/usage-string.md
index 116cf38f838..607e6234a5f 100644
--- a/packages/pretui/components/usage-string.md
+++ b/packages/pretui/components/usage-string.md
@@ -34,7 +34,7 @@ No pattern of its own; it renders one of two kit controls plus a table row.
 
 Gaps:
 
-- **The knob's label is the property-row rail, not a `<label for>`.** Verify the label and the control are actually associated — a property list of unlabelled Inputs and Selects is the most likely failure here, and neither **Input** nor **Select** generates its own name. Both accept `@controlId`, so the fix is available.
+- **The knob's visible label is the property-row rail, not a `<label for>`.** The control takes the argument name as its accessible name (`@label` on the Select, `aria-label` on the Input), so it is named, but clicking the rail does not focus it.
 - **`@required` must reach the accessible name**, not only render an asterisk — the fix **FormField** already made in the forms territory.
 - **Changing a knob re-renders the example silently.** No live region announces the effect, so a screen-reader user changing `@size` from `md` to `lg` gets no confirmation that anything happened. This belongs to **FreestyleUsage** but is felt here.
 - **Free-text mode has no format guidance.** A string argument expecting a CSS length or an ISO date offers a bare Input with no hint (**WCAG 3.3.2**), and `@description` lives in the _other_ lens — so the docs table has the explanation and the knob does not.
diff --git a/packages/pretui/example-gallery.gts b/packages/pretui/example-gallery.gts
index 2ba6f4c807e..5886f5d0cb4 100644
--- a/packages/pretui/example-gallery.gts
+++ b/packages/pretui/example-gallery.gts
@@ -69,7 +69,7 @@ export class ExampleGallery extends Component<{
         display: grid;
         grid-template-columns: repeat(
           auto-fill,
-          minmax(var(--_exg-tile-min-w), 1fr)
+          minmax(min(var(--_exg-tile-min-w), 100%), 1fr)
         );
         gap: var(--boxel-sp-sm);
         align-items: stretch;
diff --git a/packages/pretui/pretui-component.gts b/packages/pretui/pretui-component.gts
index c865ceaf5aa..7bbcbb9aa3b 100644
--- a/packages/pretui/pretui-component.gts
+++ b/packages/pretui/pretui-component.gts
@@ -25,6 +25,7 @@ import GlimmerComponent from '@glimmer/component';
 import { guidFor } from '@ember/object/internals';
 import { tracked } from '@glimmer/tracking';
 import { on } from '@ember/modifier';
+import { modifier } from 'ember-modifier';
 import { fn } from '@ember/helper';
 import type { Query, RealmResourceIdentifier } from '@cardstack/runtime-common';
 import { ThemeFrame } from './components/theme-frame';
@@ -104,14 +105,36 @@ interface WriteupFoldSignature {
 
 class WriteupFold extends GlimmerComponent<WriteupFoldSignature> {
   @tracked open = false;
+  @tracked overflows = false;
   regionId = `${guidFor(this)}-writeup`;
   toggle = () => (this.open = !this.open);
+  get showToggle(): boolean {
+    return this.open || this.overflows;
+  }
+  // The toggle and its fade only matter when the closed region clips the
+  // prose; measured while closed, so opening keeps "Show less".
+  measureOverflow = modifier((region: HTMLElement) => {
+    let prose = region.firstElementChild;
+    let check = () => {
+      if (!this.open && prose) {
+        this.overflows = prose.scrollHeight > region.clientHeight;
+      }
+    };
+    let observer = new ResizeObserver(check);
+    observer.observe(region);
+    if (prose) observer.observe(prose);
+    return () => observer.disconnect();
+  });
 
   <template>
     <div class='wb-fold' data-open={{if this.open 'true'}} ...attributes>
       {{! the write-up's prose only — the panel owns the padding, so the
           file's own embedded chrome and surface stay out }}
-      <div id={{this.regionId}} class='wb-fold-region'>
+      <div
+        id={{this.regionId}}
+        class='wb-fold-region'
+        {{this.measureOverflow}}
+      >
         <div class='wb-fold-prose'>
           <MarkdownPreview
             @model={{@writeup}}
@@ -120,17 +143,19 @@ class WriteupFold extends GlimmerComponent<WriteupFoldSignature> {
           />
         </div>
       </div>
-      <div class='wb-fold-more'>
-        <Button
-          @tone='neutral'
-          @appearance='outlined'
-          @size='xs'
-          aria-expanded={{if this.open 'true' 'false'}}
-          aria-controls={{this.regionId}}
-          {{on 'click' this.toggle}}
-          data-test-pretui-writeup-toggle
-        >{{if this.open 'Show less' 'Show more'}}</Button>
-      </div>
+      {{#if this.showToggle}}
+        <div class='wb-fold-more'>
+          <Button
+            @tone='neutral'
+            @appearance='outlined'
+            @size='xs'
+            aria-expanded={{if this.open 'true' 'false'}}
+            aria-controls={{this.regionId}}
+            {{on 'click' this.toggle}}
+            data-test-pretui-writeup-toggle
+          >{{if this.open 'Show less' 'Show more'}}</Button>
+        </div>
+      {{/if}}
     </div>
     <style scoped>
       /* closed, the preview fills whatever height the fold is given, never
@@ -251,9 +276,11 @@ class NoteComposer extends GlimmerComponent<NoteComposerSignature> {
         min-width: var(--note-compose-min-w);
       }
       .note-compose-cap {
-        font-size: var(--boxel-font-size-2xs);
-        font-weight: 600;
-        letter-spacing: 0.06em;
+        font-family: var(--boxel-eyebrow-font-family);
+        font-size: var(--boxel-eyebrow-font-size);
+        font-weight: var(--boxel-eyebrow-font-weight);
+        line-height: var(--boxel-eyebrow-line-height);
+        letter-spacing: var(--boxel-eyebrow-letter-spacing);
         text-transform: uppercase;
         color: var(--muted-foreground);
       }
@@ -365,6 +392,8 @@ export class PretUISpec extends Spec {
 
   // each format is cast: Spec's format classes carry getters these views do not use
   static isolated = class Isolated extends Component<typeof PretUISpec> {
+    writeupHeadingId = `${guidFor(this)}-writeup-heading`;
+    provenanceHeadingId = `${guidFor(this)}-provenance-heading`;
     get demoLoad() {
       let m = this.args.model;
       return m.componentName
@@ -700,9 +729,15 @@ export class PretUISpec extends Spec {
           <ExampleGallery @specs={{this.examples}} />
           <div class='wb-below'>
             {{#if @model.writeup}}
-              <section class='wb-panel wb-writeup-panel' aria-label='Write-up'>
+              <section
+                class='wb-panel wb-writeup-panel'
+                aria-labelledby={{this.writeupHeadingId}}
+              >
                 <div class='wb-panel-h'>
-                  <span class='wb-cap'>Write-up</span>
+                  <h2
+                    id={{this.writeupHeadingId}}
+                    class='wb-cap'
+                  >Write-up</h2>
                 </div>
                 <WriteupFold
                   class='wb-writeup-fold'
@@ -710,9 +745,15 @@ export class PretUISpec extends Spec {
                 />
               </section>
             {{/if}}
-            <section class='wb-panel wb-provenance' aria-label='Provenance'>
+            <section
+              class='wb-panel wb-provenance'
+              aria-labelledby={{this.provenanceHeadingId}}
+            >
               <div class='wb-panel-h'>
-                <span class='wb-cap'>Provenance</span>
+                <h2
+                  id={{this.provenanceHeadingId}}
+                  class='wb-cap'
+                >Provenance</h2>
               </div>
               <StepList
                 class='wb-pipe'
@@ -983,9 +1024,12 @@ export class PretUISpec extends Spec {
         /* THE caps treatment — panel and group headers only (type spec:
            one caps style, everything else sentence case) */
         .wb-cap {
-          font-size: var(--boxel-font-size-2xs);
-          font-weight: 600;
-          letter-spacing: 0.06em;
+          margin: 0;
+          font-family: var(--boxel-eyebrow-font-family);
+          font-size: var(--boxel-eyebrow-font-size);
+          font-weight: var(--boxel-eyebrow-font-weight);
+          line-height: var(--boxel-eyebrow-line-height);
+          letter-spacing: var(--boxel-eyebrow-letter-spacing);
           text-transform: uppercase;
           color: var(--muted-foreground);
         }
@@ -1157,14 +1201,14 @@ export class PretUISpec extends Spec {
           text-overflow: ellipsis;
         }
         .fit-star {
-          color: var(--accent-ink);
+          color: var(--warning-ink);
         }
         .fit-sub {
           display: flex;
           gap: var(--boxel-sp-xs);
           font-family: var(--font-mono);
-          font-size: var(--boxel-font-size-2xs);
-          letter-spacing: 0.06em;
+          font-size: var(--boxel-eyebrow-font-size);
+          letter-spacing: var(--boxel-eyebrow-letter-spacing);
           text-transform: uppercase;
           color: var(--muted-foreground);
         }
@@ -1266,8 +1310,8 @@ export class PretUISpec extends Spec {
         }
         .territory {
           font-family: var(--font-mono);
-          font-size: var(--boxel-font-size-2xs);
-          letter-spacing: 0.08em;
+          font-size: var(--boxel-eyebrow-font-size);
+          letter-spacing: var(--boxel-eyebrow-letter-spacing);
           text-transform: uppercase;
           color: var(--muted-foreground);
         }
@@ -1339,7 +1383,12 @@ export class PretUISpec extends Spec {
         <fieldset class='wb-group'>
           <legend>Write-up</legend>
           <div class='wb-fields'>
-            <label class='wb-wide'>Linked file <@fields.writeup /></label>
+            {{! a div, not a label: the editor's first control is Remove,
+                which a label would activate on any click }}
+            <div class='wb-wide'>
+              <span class='wb-cap'>Linked file</span>
+              <@fields.writeup />
+            </div>
           </div>
         </fieldset>
       </div>
@@ -1359,9 +1408,11 @@ export class PretUISpec extends Spec {
           min-width: 0;
         }
         .wb-group > legend {
-          font-size: var(--boxel-font-size-2xs);
-          font-weight: 600;
-          letter-spacing: 0.08em;
+          font-family: var(--boxel-eyebrow-font-family);
+          font-size: var(--boxel-eyebrow-font-size);
+          font-weight: var(--boxel-eyebrow-font-weight);
+          line-height: var(--boxel-eyebrow-line-height);
+          letter-spacing: var(--boxel-eyebrow-letter-spacing);
           text-transform: uppercase;
           color: var(--muted-foreground);
           padding-inline: var(--boxel-sp-2xs);
@@ -1378,9 +1429,11 @@ export class PretUISpec extends Spec {
         .wb-fields > div {
           display: grid;
           gap: var(--boxel-sp-2xs);
-          font-size: var(--boxel-font-size-2xs);
-          font-weight: 600;
-          letter-spacing: 0.04em;
+          font-family: var(--boxel-eyebrow-font-family);
+          font-size: var(--boxel-eyebrow-font-size);
+          font-weight: var(--boxel-eyebrow-font-weight);
+          line-height: var(--boxel-eyebrow-line-height);
+          letter-spacing: var(--boxel-eyebrow-letter-spacing);
           text-transform: uppercase;
           color: var(--muted-foreground);
           min-width: 0;

From 64263561b40cce12b4c89df48655195d12934a7d Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Thu, 8 Oct 2026 15:24:46 -0400
Subject: [PATCH 12/30] Put Autocomplete on the theme contract: ink edges and
 match text, ladder sizes, Button for Clear, and readonly when disabled

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/components/autocomplete.gts | 229 ++++++++++----------
 packages/pretui/components/autocomplete.md  |   7 +-
 packages/pretui/controls-entry.test.gts     |  13 ++
 3 files changed, 134 insertions(+), 115 deletions(-)

diff --git a/packages/pretui/components/autocomplete.gts b/packages/pretui/components/autocomplete.gts
index 3a24a1f768a..fa78beaefd6 100644
--- a/packages/pretui/components/autocomplete.gts
+++ b/packages/pretui/components/autocomplete.gts
@@ -4,7 +4,10 @@ import { tracked } from '@glimmer/tracking';
 import { fn } from '@ember/helper';
 import { on } from '@ember/modifier';
 import { guidFor } from '@ember/object/internals';
+import XIcon from '@cardstack/boxel-icons/x';
 import { OwnedTimers, listen, ownsTimers } from '../focus';
+import { Button } from './button';
+import { VisuallyHidden } from './visually-hidden';
 import { PRETUI_TONES, emit, firstDefined, resolveSize, resolveTone } from '../pretui-primitives';
 import type {
   ControlAliasArgs,
@@ -394,8 +397,16 @@ export class Autocomplete extends Component<AutocompleteSignature> {
   get emptyText(): string {
     return this.args.emptyText ?? 'No matches';
   }
+  // a disabled field shows no Clear, since Clear can't act on it
   get clearable(): boolean {
-    return (this.args.clearable ?? false) && this.value.length > 0;
+    return (
+      (this.args.clearable ?? false) && !this.inert && this.value.length > 0
+    );
+  }
+  // Disabled stays focusable (aria-disabled, not the native attribute), so
+  // readonly is what stops the browser editing the text.
+  get blocksTyping(): boolean {
+    return this.inert || this.readonly;
   }
   get clearLabel(): string {
     return 'Clear ' + this.fieldLabel;
@@ -701,15 +712,16 @@ export class Autocomplete extends Component<AutocompleteSignature> {
       data-busy={{if this.busy 'true'}}
       data-invalid={{if this.invalid 'true'}}
       data-disabled={{if this.inert 'true'}}
-      data-test-pretui-autocomplete
       ...attributes
       {{ownsTimers this.timers}}
       {{listen 'focusout' this.handleFocusOut}}
       {{listen 'mouseover' this.handleHover}}
       {{listen 'mousedown' this.handlePress}}
+      data-test-pretui-autocomplete
     >
       {{#if this.ownsLabel}}
-        <label class='pretui-ac-sr' for={{this.inputId}}>{{this.fieldLabel}}</label>
+        <label for={{this.inputId}}><VisuallyHidden
+          >{{this.fieldLabel}}</VisuallyHidden></label>
       {{/if}}
 
       <div class='pretui-ac-field'>
@@ -729,23 +741,25 @@ export class Autocomplete extends Component<AutocompleteSignature> {
           aria-disabled={{if this.inert 'true'}}
           aria-busy={{if this.busy 'true'}}
           placeholder={{@placeholder}}
-          readonly={{this.readonly}}
+          readonly={{this.blocksTyping}}
           value={{this.value}}
-          data-test-pretui-autocomplete-input
           {{on 'input' this.handleInput}}
           {{on 'focus' this.handleFieldFocus}}
           {{on 'keydown' this.handleKeyDown}}
+          data-test-pretui-autocomplete-input
         />
         {{#if this.busy}}
           <span class='pretui-ac-spin' aria-hidden='true'></span>
         {{else if this.clearable}}
-          <button
-            type='button'
+          <Button
             class='pretui-ac-clear'
+            @tone='neutral'
+            @appearance='plain'
+            @size='xs'
             aria-label={{this.clearLabel}}
-            data-test-pretui-autocomplete-clear
             {{on 'click' this.clear}}
-          ><span class='pretui-ac-cross' aria-hidden='true'></span></button>
+            data-test-pretui-autocomplete-clear
+          ><XIcon width='12' height='12' aria-hidden='true' /></Button>
         {{/if}}
       </div>
 
@@ -794,8 +808,8 @@ export class Autocomplete extends Component<AutocompleteSignature> {
                   aria-label={{row.label}}
                   aria-selected={{if row.active 'true' 'false'}}
                   aria-disabled={{if row.disabled 'true'}}
-                  data-test-pretui-autocomplete-option={{row.value}}
                   {{on 'click' (fn this.chooseRow row)}}
+                  data-test-pretui-autocomplete-option={{row.value}}
                 ></span>
               </li>
             {{/each}}
@@ -814,11 +828,10 @@ export class Autocomplete extends Component<AutocompleteSignature> {
         </ul>
       {{/if}}
 
-      <span
-        class='pretui-ac-sr'
+      <VisuallyHidden
         role='status'
         data-test-pretui-autocomplete-status
-      >{{this.suggestionStatus}}</span>
+      >{{this.suggestionStatus}}</VisuallyHidden>
     </div>
     <style scoped>
       @layer PretComponent {
@@ -826,43 +839,58 @@ export class Autocomplete extends Component<AutocompleteSignature> {
           position: relative;
           display: block;
           min-width: 0;
-          font-size: var(--pretui-size-m, var(--text-ui-md, 0.78rem));
+          font-size: var(--pretui-size-m, var(--boxel-font-size-xs));
         }
+        /* the ladder has no step under 11px, so xs and s share it */
         .pretui-ac[data-size='xs'] {
-          font-size: var(--pretui-size-xs, var(--text-ui-xs, 0.66rem));
+          font-size: var(--pretui-size-xs, var(--boxel-font-size-2xs));
         }
         .pretui-ac[data-size='s'] {
-          font-size: var(--pretui-size-s, var(--text-ui-sm, 0.72rem));
+          font-size: var(--pretui-size-s, var(--boxel-font-size-2xs));
         }
         .pretui-ac[data-size='l'] {
-          font-size: var(--pretui-size-l, var(--text-ui-lg, 0.875rem));
+          font-size: var(--pretui-size-l, var(--boxel-font-size-sm));
         }
         .pretui-ac[data-size='xl'] {
-          font-size: var(--pretui-size-xl, var(--text-ui-xl, 1rem));
+          font-size: var(--pretui-size-xl, var(--boxel-font-size));
+        }
+        /* tone sets custom properties only: the fill hue for tints, its -ink
+           for text and lines, and the default field's edge (--input when
+           neutral, the -ink otherwise, so a tone shows in both schemes) */
+        .pretui-ac {
+          --pretui-ac-edge: var(--pretui-tone-ink);
         }
-        /* tone sets custom properties only; the recipes below read them, so a
-           season retints the field without a rule being touched */
         .pretui-ac[data-tone='neutral'] {
           --pretui-tone: var(--foreground);
+          --pretui-tone-ink: var(--foreground);
+          --pretui-ac-edge: var(--input);
         }
         .pretui-ac[data-tone='primary'] {
           --pretui-tone: var(--primary);
+          --pretui-tone-ink: var(--primary-ink);
         }
         .pretui-ac[data-tone='info'] {
-          --pretui-tone: var(--pretui-info, var(--boxel-blue));
+          --pretui-tone: var(--info);
+          --pretui-tone-ink: var(--info-ink);
         }
         .pretui-ac[data-tone='success'] {
-          --pretui-tone: var(--success, var(--boxel-success));
+          --pretui-tone: var(--success);
+          --pretui-tone-ink: var(--success-ink);
         }
         .pretui-ac[data-tone='warning'] {
-          --pretui-tone: var(--warning, var(--boxel-warning));
+          --pretui-tone: var(--warning);
+          --pretui-tone-ink: var(--warning-ink);
         }
         .pretui-ac[data-tone='danger'] {
           --pretui-tone: var(--destructive);
+          --pretui-tone-ink: var(--destructive-ink);
         }
         .pretui-ac[data-tone='attention'] {
-          --pretui-tone: var(--pretui-attention, var(--boxel-fuschia));
+          --pretui-tone: var(--attention);
+          --pretui-tone-ink: var(--attention-ink);
         }
+        /* the edge is one variable: appearances and states set it, and only
+           this rule draws it, so no selector has to outrank another */
         .pretui-ac-field {
           position: relative;
           display: flex;
@@ -871,36 +899,58 @@ export class Autocomplete extends Component<AutocompleteSignature> {
           min-width: 0;
           min-height: var(--pretui-ac-h, 2.24em);
           padding-inline: 0.5em;
-          border-radius: var(--radius);
+          border-radius: var(--boxel-border-radius);
+          box-shadow: 0 0 0 1px var(--pretui-ac-edge);
+        }
+        /* edges are drawn in the tone's -ink: the fill hue misses the 3:1 a
+           field boundary needs */
+        .pretui-ac[data-appearance='outlined'],
+        .pretui-ac[data-appearance='accent'] {
+          --pretui-ac-edge: var(--pretui-tone-ink);
+        }
+        .pretui-ac[data-appearance='filled'],
+        .pretui-ac[data-appearance='plain'] {
+          --pretui-ac-edge: transparent;
         }
         .pretui-ac[data-appearance='filled-outlined'] .pretui-ac-field {
-          background: color-mix(in oklch, var(--pretui-tone) 6%, var(--field, var(--boxel-light)));
-          box-shadow: 0 0 0 1px var(--input);
+          background-color: color-mix(
+            in oklch,
+            var(--pretui-tone) 6%,
+            var(--field)
+          );
+          color: var(--foreground);
         }
         .pretui-ac[data-appearance='outlined'] .pretui-ac-field {
-          background: var(--card);
-          box-shadow: 0 0 0 1px color-mix(in oklch, var(--pretui-tone) 45%, var(--border));
+          background-color: var(--card);
+          color: var(--card-foreground);
         }
         .pretui-ac[data-appearance='filled'] .pretui-ac-field {
-          background: color-mix(in oklch, var(--pretui-tone) 15%, var(--card));
+          background-color: color-mix(
+            in oklch,
+            var(--pretui-tone) 15%,
+            var(--card)
+          );
+          color: var(--card-foreground);
         }
         .pretui-ac[data-appearance='plain'] .pretui-ac-field {
-          background: transparent;
+          background-color: transparent;
         }
         .pretui-ac[data-appearance='accent'] .pretui-ac-field {
-          background: var(--field, var(--boxel-light));
-          box-shadow: 0 0 0 1px var(--pretui-tone);
+          background-color: var(--field);
+          color: var(--foreground);
         }
-        .pretui-ac-field:hover {
-          box-shadow: 0 0 0 1px var(--line-strong, var(--boxel-400));
+        /* hover strengthens a neutral field's gray edge; a toned or inked
+           edge is already strong */
+        .pretui-ac[data-tone='neutral']:not([data-appearance='outlined'], [data-appearance='accent'], [data-invalid='true'])
+          .pretui-ac-field:hover {
+          --pretui-ac-edge: var(--border-strong);
         }
         .pretui-ac[data-invalid='true'] .pretui-ac-field {
-          box-shadow: 0 0 0 1px var(--destructive);
+          --pretui-ac-edge: var(--destructive-ink);
         }
-        /* focus wins over both hover and the invalid ring — a reader must
-           always be able to see where they are */
-        .pretui-ac-field:focus-within,
-        .pretui-ac[data-invalid='true'] .pretui-ac-field:focus-within {
+        /* focus draws the box-shadow itself, so it wins over hover and the
+           invalid edge: a reader must always see where they are */
+        .pretui-ac-field:focus-within {
           box-shadow: 0 0 0 2px var(--ring);
         }
         .pretui-ac[data-disabled='true'] {
@@ -911,60 +961,22 @@ export class Autocomplete extends Component<AutocompleteSignature> {
           min-width: 0;
           height: 2em;
           border: 0;
-          background: transparent;
-          color: var(--foreground);
-          font: inherit;
-          letter-spacing: var(--track-ui, 0.01em);
+          background-color: transparent;
+          color: inherit;
+          font-family: inherit;
+          font-size: inherit;
+          font-weight: inherit;
           outline: none;
         }
         .pretui-ac-input::placeholder {
-          color: var(--ink-3, var(--boxel-400));
+          color: var(--muted-foreground);
         }
+        /* a square 1.5rem target: Button's xs height, with no inline padding */
         .pretui-ac-clear {
+          --pretui-button-px: 0;
+          --pretui-button-min-w: 1.5rem;
+
           flex: none;
-          display: inline-flex;
-          align-items: center;
-          justify-content: center;
-          width: 1.4em;
-          height: 1.4em;
-          padding: 0;
-          border: 0;
-          border-radius: var(--radius-sm, 5px);
-          background: transparent;
-          color: var(--muted-foreground);
-          cursor: pointer;
-        }
-        .pretui-ac-clear:hover {
-          background: var(--hover, rgb(0 0 0 / 0.05));
-          color: var(--foreground);
-        }
-        .pretui-ac-clear:focus-visible {
-          outline: 2px solid var(--ring);
-          outline-offset: -1px;
-        }
-        /* Drawn from two borders rather than an svg, so the field stays legal
-           inside any role a caller wraps it in. */
-        .pretui-ac-cross {
-          position: relative;
-          width: 0.6em;
-          height: 0.6em;
-        }
-        .pretui-ac-cross::before,
-        .pretui-ac-cross::after {
-          content: '';
-          position: absolute;
-          inset-block-start: 0.26em;
-          inset-inline-start: 0;
-          width: 0.6em;
-          height: 1.2px;
-          border-radius: 1px;
-          background: currentColor;
-        }
-        .pretui-ac-cross::before {
-          transform: rotate(45deg);
-        }
-        .pretui-ac-cross::after {
-          transform: rotate(-45deg);
         }
         @keyframes pretui-ac-spin {
           to {
@@ -977,32 +989,34 @@ export class Autocomplete extends Component<AutocompleteSignature> {
           height: 1.04em;
           border-radius: 50%;
           border: 1.5px solid color-mix(in oklch, currentColor 25%, transparent);
-          border-top-color: var(--pretui-tone, currentColor);
+          border-top-color: var(--pretui-tone-ink);
           animation: pretui-ac-spin 0.7s linear infinite;
         }
         /* The layer renders IN PLACE: a portaled surface cannot
-           inherit the season's tokens, which is the whole theming contract. */
+           inherit the theme's tokens, which is the whole theming contract. */
         .pretui-ac-list {
           position: absolute;
-          z-index: 20;
+          z-index: var(--pretui-z-dropdown, 60);
           inset-inline: 0;
-          inset-block-start: calc(100% + 4px);
+          inset-block-start: calc(100% + var(--boxel-sp-4xs));
           margin: 0;
           padding: 0.25em;
           max-height: 16em;
           overflow-y: auto;
           list-style: none;
-          border-radius: var(--radius);
-          background: var(--popover);
-          box-shadow: 0 0 0 1px var(--border),
-            0 6px 18px var(--shadow-ink-mid, rgb(0 0 0 / 0.08));
+          border-radius: var(--boxel-border-radius);
+          background-color: var(--popover);
+          color: var(--popover-foreground);
+          box-shadow:
+            0 0 0 1px var(--border),
+            var(--shadow-md);
           animation: pretui-ac-drop var(--pretui-dur-snap, 180ms)
             var(--pretui-ease-snap, ease) both;
         }
         @keyframes pretui-ac-drop {
           from {
             opacity: 0;
-            transform: translateY(-3px);
+            transform: translateY(-0.1875rem);
           }
         }
         .pretui-ac-row {
@@ -1012,11 +1026,11 @@ export class Autocomplete extends Component<AutocompleteSignature> {
           gap: 0.5em;
           min-width: 0;
           padding: 0.34em 0.5em;
-          border-radius: var(--radius-sm, 6px);
+          border-radius: var(--boxel-border-radius-sm);
           cursor: pointer;
         }
         .pretui-ac-row[data-active='true'] {
-          background: var(--hover, var(--boxel-100));
+          background-color: var(--hover);
         }
         .pretui-ac-face {
           position: relative;
@@ -1048,15 +1062,15 @@ export class Autocomplete extends Component<AutocompleteSignature> {
           overflow: hidden;
           text-overflow: ellipsis;
           white-space: nowrap;
-          color: var(--foreground);
         }
         .pretui-ac-hit {
           font-weight: 600;
-          color: var(--pretui-tone, var(--primary));
+          /* the tone's -ink: the fill hue misses 4.5:1 as text */
+          color: var(--pretui-tone-ink);
         }
         .pretui-ac-meta {
           flex: none;
-          font-size: 0.86em;
+          font-size: var(--boxel-font-size-2xs);
           font-variant-numeric: tabular-nums;
           color: var(--muted-foreground);
         }
@@ -1077,20 +1091,11 @@ export class Autocomplete extends Component<AutocompleteSignature> {
         }
         .pretui-ac-none-text {
           font-weight: 500;
-          color: var(--foreground);
         }
         .pretui-ac-none-hint {
-          font-size: 0.86em;
+          font-size: var(--boxel-font-size-2xs);
           color: var(--muted-foreground);
         }
-        .pretui-ac-sr {
-          position: absolute;
-          width: 1px;
-          height: 1px;
-          overflow: hidden;
-          clip-path: inset(50%);
-          white-space: nowrap;
-        }
         @media (pointer: coarse) {
           .pretui-ac-row {
             padding-block: 0.6em;
diff --git a/packages/pretui/components/autocomplete.md b/packages/pretui/components/autocomplete.md
index c3cbd9edc34..35a654fa664 100644
--- a/packages/pretui/components/autocomplete.md
+++ b/packages/pretui/components/autocomplete.md
@@ -32,7 +32,7 @@ That last clause is the whole difference from **Combobox**: an autocomplete's va
 <:empty> — replaces the built-in empty line
 ```
 
-**`@onCommit` is the callback that distinguishes typing from meaning it.** It fires on Enter, a click or a blur, and it tells you *which* happened: a suggestion object when one was chosen, `undefined` when the reader meant their own text.
+**`@onCommit` is the callback that distinguishes typing from meaning it.** It fires on Enter, a click or a blur, and it tells you _which_ happened: a suggestion object when one was chosen, `undefined` when the reader meant their own text.
 
 **`@enterCommits` defaults to `'deliberate'`, and that is the interesting decision.** When the highlight and the typed text disagree, Enter takes the typed text unless the reader deliberately moved to the highlight. An automatic highlight does **not** win Enter — so `@autoHighlight` is a visual aid rather than a trap that silently replaces what someone typed.
 
@@ -51,6 +51,7 @@ Where it is thinner: no multi-select or token mode — that is **TokenInput** 
 ## Accessibility
 
 - **Rows are rendered inside an `aria-hidden` face, and the option's accessible name is computed rather than scraped.** That is what makes `<:item>` safe: any markup is legal in the block because none of it reaches the accessibility tree.
+- **`@disabled` keeps the field focusable.** It sets `aria-disabled` and `readonly` rather than the native `disabled`, so a reader can still reach the field and hear that it's unavailable, while the text can't be edited. The Clear button is hidden.
 - **`@busy` retains focus.** A field that disables itself while fetching suggestions throws the reader to the document mid-word.
 - **The field is always named** — through `@label` as an `sr-only` label, or through a wrapper's `@controlId`.
 - **`@minChars` suppresses the layer silently.** A reader who types one character and gets nothing is not told why; if the threshold is high, say so in `@placeholder` or in help text.
@@ -59,8 +60,8 @@ Where it is thinner: no multi-select or token mode — that is **TokenInput** 
 
 ## Theming
 
-Tone, appearance and size resolve through the kit's shared recipe system, so the field matches every other control in a form at the same size.
+Tone, appearance and size resolve through the kit's shared recipe system, so the field matches every other control in a form at the same size. A tone sets two properties: `--pretui-tone`, the fill (`--primary`, `--info`, `--success`, `--warning`, `--destructive`, `--attention`) for tints, and `--pretui-tone-ink`, its `-ink`, for rings, the busy arc and the matched text, since a fill misses the contrast a line or text needs. The field reads `--field` or `--card` with its foreground; its edge is `--input` when neutral (`--border-strong` on hover) and the tone's `-ink` otherwise, `--destructive-ink` when invalid, `--ring` for focus and `--muted-foreground` for the placeholder. Sizes come from `--pretui-size-*`, falling back to `--boxel-font-size-2xs` (xs and s), `-xs` (m, as on Select), `-sm` (l) and `--boxel-font-size` (xl).
 
-The suggestion layer rides the kit's overlay tokens rather than defining its own surface, which is what keeps an autocomplete's dropdown at the same elevation and radius as a **Select**'s or a **Combobox**'s in the same season — three components that would look like three different products if each owned its own popover styling.
+The suggestion layer is a `--popover` surface with `--popover-foreground`, `--shadow-md`, `--boxel-border-radius` and the kit's `dropdown` stacking tier, the same elevation and radius as a **Select**'s or a **Combobox**'s, so three components don't look like three different products. The clear button is a plain neutral **Button** with a boxel-icons `x`.
 
 The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
diff --git a/packages/pretui/controls-entry.test.gts b/packages/pretui/controls-entry.test.gts
index eb179bfc02f..3dffc025a99 100644
--- a/packages/pretui/controls-entry.test.gts
+++ b/packages/pretui/controls-entry.test.gts
@@ -240,6 +240,18 @@ module('controls-entry | Toggle', function (hooks) {
     assert.strictEqual(button.getAttribute('title'), 'Pin this row');
   });
 
+  test('a disabled field with a value shows no Clear', async function (assert) {
+    await render(<template>
+      <Autocomplete
+        @items={{ITEMS}}
+        @defaultValue='Berlin'
+        @clearable={{true}}
+        @disabled={{true}}
+      />
+    </template>);
+    assert.strictEqual(one('[data-test-pretui-autocomplete-clear]'), null);
+  });
+
   test('the treatment is reflected as data attributes', async function (assert) {
     await render(<template>
       <Toggle @tone='destructive' @size='lg' @pressed={{true}}>X</Toggle>
@@ -598,6 +610,7 @@ module('controls-entry | Autocomplete', function (hooks) {
     let input = one(FIELD) as HTMLInputElement;
     assert.strictEqual(input.getAttribute('aria-disabled'), 'true');
     assert.false(input.disabled, 'aria-disabled, never the native attribute');
+    assert.true(input.readOnly, 'readonly, so the browser cannot edit the text');
     await focus(input);
     assert.strictEqual(input.getAttribute('aria-expanded'), 'false');
     assert.strictEqual(

From 231b112d00336fffd3df76dab5bf55927552464f Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Thu, 8 Oct 2026 15:24:48 -0400
Subject: [PATCH 13/30] Bring SegmentedControl and SlidingHighlight onto the
 contract, with Button's corner, an inset focus ring, and docs that match the
 radiogroup

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../pretui/components/segmented-control.gts   | 120 +++++++++---------
 .../pretui/components/segmented-control.md    |  38 ++----
 .../pretui/components/sliding-highlight.gts   |  23 ++--
 .../pretui/components/sliding-highlight.md    |  14 +-
 4 files changed, 95 insertions(+), 100 deletions(-)

diff --git a/packages/pretui/components/segmented-control.gts b/packages/pretui/components/segmented-control.gts
index 022a231cb70..8ed34873a2d 100644
--- a/packages/pretui/components/segmented-control.gts
+++ b/packages/pretui/components/segmented-control.gts
@@ -1,5 +1,5 @@
-// Pretui — SegmentedControl: compact view switcher. The active card is
-// motion-core's SlidingHighlight, not the segment's own background.
+// Pretui — SegmentedControl: compact view switcher. The active card is a
+// SlidingHighlight pill, not the segment's own background.
 import Component from '@glimmer/component';
 import { tracked } from '@glimmer/tracking';
 import { on } from '@ember/modifier';
@@ -32,25 +32,14 @@ export interface SegmentedControlSignature {
   Element: HTMLDivElement;
 }
 
-// The active segment's card face is not painted by the segment: it is ONE
-// <SlidingHighlight @variant='pill' /> that travels between segments, driven
-// by motion-core's slidingHighlight modifier on the rail. Adopting the shared
-// primitive rather than keeping a local copy means the measuring code, the
-// first-paint suppression and the reduced-motion fallback live in exactly one
-// place for Segmented, Tabs and anything that adopts it next. The modifier
-// reads the same data-state='active' the styling already used, so nothing
-// here had to hand over its DOM or thread an active index through.
+// The active segment's card face is one <SlidingHighlight @variant='pill' />
+// that slides between segments, driven by the slidingHighlight modifier on
+// the rail; it reads each label's data-state='active'.
 //
-// **A radiogroup, not a tablist.** A segmented control swaps a *value*, not
-// a panel, so it is radios; a tablist's children must be tabs. Tabs, three components down this file, is the one that swaps a
-// panel. It is now what it always was: a single-choice value picker, built on
-// the same native `<input type='radio'>` foundation `RadioGroup` uses, which
-// hands over the entire APG radio contract — one tab stop for the group,
-// arrows to move and select, checked state exposed, form participation — with
-// no roving-tabindex code and no keyboard handler of our own. Nothing about
-// how it LOOKS changed: the radio is visually hidden, the `<label>` wears the
-// old `.pretui-seg-item` dress and keeps `data-state='active'` so
-// SlidingHighlight measures exactly what it measured before.
+// A radiogroup, not a tablist: a segmented control picks a value, not a
+// panel. Native radios sharing a name give the APG radio contract (one tab
+// stop, arrows move and select, checked state, form participation) with no
+// keyboard code here; each radio is visually hidden and its label is the face.
 export class SegmentedControl extends Component<SegmentedControlSignature> {
   @tracked internal =
     this.args.defaultValue ??
@@ -62,7 +51,7 @@ export class SegmentedControl extends Component<SegmentedControlSignature> {
   get value() {
     return this.args.value ?? this.internal;
   }
-  pick = (option: SegmentOption, event: Event) => {
+  pick = (option: SegmentOption) => {
     if (this.args.value === undefined) {
       this.internal = option.value;
     }
@@ -70,10 +59,11 @@ export class SegmentedControl extends Component<SegmentedControlSignature> {
     // controlled: the browser already moved the radio; move it back unless the
     // owner took the new value
     if (this.args.value !== undefined && this.args.value !== option.value) {
-      let group = (event.target as HTMLElement).closest('.pretui-seg');
-      group?.querySelectorAll<HTMLInputElement>('.pretui-seg-input').forEach((radio) => {
+      for (let radio of document.getElementsByName(
+        this.name,
+      ) as NodeListOf<HTMLInputElement>) {
         radio.checked = radio.value === this.args.value;
-      });
+      }
     }
   };
   isActive = (option: SegmentOption) => this.value === option.value;
@@ -82,9 +72,9 @@ export class SegmentedControl extends Component<SegmentedControlSignature> {
       class='pretui-seg'
       role='radiogroup'
       aria-label={{@label}}
-      data-test-pretui-segmented
       ...attributes
       {{slidingHighlight}}
+      data-test-pretui-segmented
     >
       <SlidingHighlight @variant='pill' />
       {{#each this.options as |option|}}
@@ -112,42 +102,54 @@ export class SegmentedControl extends Component<SegmentedControlSignature> {
     <style scoped>
       @layer PretComponent {
         .pretui-seg {
+          /* the rail's gap, padding and radius offset move together, so the
+             pill's corner stays concentric with the rail's */
+          --pretui-seg-inset: var(--boxel-sp-6xs);
+          /* the active label's weight; the hidden copy below must match it */
+          --pretui-seg-active-weight: 600;
+          /* Button's corner, shared by the segments and the pill; the rail
+             adds the inset so the pill's corner stays concentric */
+          --pretui-seg-radius: calc(var(--radius) - 2px);
+          --pretui-highlight-radius: var(--pretui-seg-radius);
+
           position: relative;
           display: inline-flex;
-          gap: 2px;
-          padding: 2px;
-          background: var(--inset, var(--boxel-100));
-          border-radius: calc(var(--radius) + 2px);
-          box-shadow: var(--pretui-shadow-hairline, 0 0 0 1px var(--border));
+          gap: var(--pretui-seg-inset);
+          padding: var(--pretui-seg-inset);
+          background-color: var(--inset);
+          color: var(--foreground);
+          border-radius: calc(var(--pretui-seg-radius) + var(--pretui-seg-inset));
+          box-shadow: 0 0 0 1px var(--border);
+        }
+        .pretui-seg:has(.pretui-seg-input:disabled) {
+          opacity: 0.5;
         }
         .pretui-seg-item {
-          /* positioned + z-index so the label paints above the travelling
-             highlight, which is a sibling rather than this button's own
-             background. `raised` is the kit scale's in-component tier
-             (pretui-css.gts) — it never competes outside this box. */
+          /* above the pill, which is a sibling, not the label's background;
+             raised is the kit's in-component stacking tier */
           position: relative;
           z-index: var(--pretui-z-raised, 1);
           display: inline-flex;
           align-items: center;
-          height: 24px;
-          padding: 0 11px;
-          border: 0;
-          background: none;
-          border-radius: var(--radius);
-          font-family: inherit;
-          font-size: var(--text-ui, 12px);
-          font-weight: 500;
-          letter-spacing: inherit;
+          height: 1.5rem;
+          padding: 0 var(--boxel-sp-sm);
+          border-radius: var(--pretui-seg-radius);
+          font-size: var(--boxel-ui-label-font-size);
+          font-weight: var(--boxel-ui-label-font-weight);
+          line-height: var(--boxel-ui-label-line-height);
+          letter-spacing: var(--boxel-ui-label-letter-spacing);
           color: var(--muted-foreground);
           cursor: pointer;
           white-space: nowrap;
-          /* the label crosses to ink over the same beat the pill travels, so
-             the two halves of the state change read as one move */
-          transition: color 150ms var(--pretui-ease-snap, ease);
+          /* the ink shift keeps the pill's timing, so the two read as one move */
+          transition: color 180ms cubic-bezier(0.23, 1, 0.32, 1);
+        }
+        .pretui-seg-item:has(.pretui-seg-input:disabled) {
+          cursor: default;
         }
         /* the radio carries the semantics and the keyboard; the label carries
-           the look. Kept 1px and in flow rather than display:none so it stays
-           focusable and so the focus ring below has something to sit on. */
+           the look. Kept 1px rather than display:none so it stays focusable
+           and the focus ring below has something to follow. */
         .pretui-seg-input {
           position: absolute;
           width: 1px;
@@ -156,16 +158,15 @@ export class SegmentedControl extends Component<SegmentedControlSignature> {
           opacity: 0;
           pointer-events: none;
         }
+        /* inset: the rail's padding and gap are thinner than an outside ring */
         .pretui-seg-item:has(.pretui-seg-input:focus-visible) {
           outline: 2px solid var(--ring);
-          outline-offset: 1px;
+          outline-offset: -2px;
         }
+        /* the label sits on the pill's --card face */
         .pretui-seg-item[data-state='active'] {
-          /* the card face and control shadow now belong to the shared
-             SlidingHighlight in its pill cut — identical treatment, one
-             element, and it travels */
-          color: var(--foreground);
-          font-weight: 600;
+          color: var(--card-foreground);
+          font-weight: var(--pretui-seg-active-weight);
         }
         /* a hidden bold copy under the label holds every segment at its bold
            width, so selecting one never shifts its neighbors or the pill */
@@ -177,13 +178,18 @@ export class SegmentedControl extends Component<SegmentedControlSignature> {
           height: 0;
           overflow: hidden;
           visibility: hidden;
-          font-weight: 600;
+          font-weight: var(--pretui-seg-active-weight);
         }
         /* coarse pointers get a real hit target without moving the fine one */
         @media (any-pointer: coarse) {
           .pretui-seg-item {
-            min-height: 34px;
-            padding: 0 14px;
+            min-height: 2.125rem;
+            padding: 0 var(--boxel-sp);
+          }
+        }
+        @media (prefers-reduced-motion: reduce) {
+          .pretui-seg-item {
+            transition: none;
           }
         }
       }
diff --git a/packages/pretui/components/segmented-control.md b/packages/pretui/components/segmented-control.md
index 1a6e9805da4..4439e46d658 100644
--- a/packages/pretui/components/segmented-control.md
+++ b/packages/pretui/components/segmented-control.md
@@ -5,47 +5,35 @@ A compact row of mutually exclusive options, all visible, with a pill that slide
 ## The contract
 
 ```
-@options: { value, label }[]   (required)
-@value?, @defaultValue?, @onValueChange?(value: string)
+@options?: { value, label }[]   (or @items, the same list)
+@value?, @defaultValue?, @onValueChange?(value: string)   (or @onChange)
+@label?       — the group's accessible name
 @disabled?    — disables every segment
 ```
 
-Hybrid controlled/uncontrolled: `@value ?? @internal`, initialised from `@defaultValue ?? options[0].value`. Unlike RadioGroup there is no empty state — a segmented control always has a selection, which is the semantic difference from a set of toggle buttons.
+Hybrid controlled/uncontrolled: `@value ?? @internal`, initialized from `@defaultValue ?? options[0].value`. Unlike RadioGroup there is no empty state — a segmented control always has a selection, which is the semantic difference from a set of toggle buttons.
 
-**The selected segment's face is not painted by the segment.** It is one `<SlidingHighlight @variant='pill' />` that travels, driven by the `slidingHighlight` modifier (`components/sliding-highlight.gts`) on the rail. The modifier reads the `data-state='active'` attribute the styling already used, so the control did not have to hand over its DOM or thread an active index through. This is the kit's Law 5 second canonical mechanism, and adopting the shared primitive rather than keeping a local copy means the measuring code, first-paint suppression and reduced-motion fallback exist once for SegmentedControl, Tabs and whatever adopts it next.
+**The selected segment's face is not painted by the segment.** It is one `<SlidingHighlight @variant='pill' />` that slides between segments, driven by the `slidingHighlight` modifier (`components/sliding-highlight.gts`) on the rail, which reads each label's `data-state='active'`. The measuring code, first-paint suppression and reduced-motion fallback live once in that primitive, for SegmentedControl, Tabs and whatever adopts it next.
 
 ## Prior art
 
-**Apple HIG** is the origin: a segmented control is a value picker, and HIG is explicit that segments should be similar in width and content type, and that segmented controls are for _selecting_ rather than _acting_. **React Spectrum** does not ship one; the closest is `ToggleButtonGroup` with `selectionMode="single"`. **Radix** likewise has no segmented control — `ToggleGroup` with `type="single"` is the analogue, and it exposes `rovingFocus` and `loop`. **shadcn** implements it as `Tabs` styled as a pill strip, which is exactly the mistake described below.
+**Apple HIG** is the origin: a segmented control is a value picker, and HIG is explicit that segments should be similar in width and content type, and that segmented controls are for _selecting_ rather than _acting_. **React Spectrum** does not ship one; the closest is `ToggleButtonGroup` with `selectionMode="single"`. **Radix** likewise has no segmented control — `ToggleGroup` with `type="single"` is the analogue, and it exposes `rovingFocus` and `loop`. **shadcn** implements it as `Tabs` styled as a pill strip, which gives a value picker tab semantics: a tablist must control panels, and this controls a value.
 
 Pretui's improvement is the shared traveling highlight. shadcn's Tabs-as-segmented and most in-house versions cross-fade a background on the active item; getting the pill to _travel_ means writing measuring code, and here it is a component plus a modifier reused across the kit.
 
 ## Accessibility
 
-This is the component's weak point, and it is worth being blunt: **the roles are wrong.**
+**A radiogroup of native radios.** The rail is `role="radiogroup"`, named by `@label`; pass it whenever no visible heading names the control. Each segment is a visually hidden `<input type="radio">` sharing one `name`, with its `<label>` as the visible face, so the browser supplies the APG radio contract: the group is one tab stop, arrow keys move and select, the checked state is exposed, and the value takes part in a form. There is no keyboard code of our own.
 
-The rail carries `role="tablist"`, but its children are plain `<button>`s with **no `role="tab"` and no `aria-selected`** — only a `data-state` attribute for styling. A `tablist` whose children are not `tab`s is an invalid ARIA structure; assistive tech is told "tab list, 3 items" and then finds three ordinary buttons, none of which reports selection. A screen-reader user cannot tell which segment is active at all.
-
-Compounding it, `role="tablist"` is the wrong pattern even if the children were fixed: nothing here controls a tab panel. The APG guidance is direct — do not use `tablist` unless it actually swaps panels.
-
-The correct shape is one of two:
-
-- **Radio group** (recommended, because this is a value choice): `role="radiogroup"` with an accessible name on the container, `role="radio"` + `aria-checked` on each segment, roving tabindex so the group is one tab stop, and Left/Right/Up/Down moving _and_ selecting with wrapping.
-- **Toolbar**: `role="toolbar"`, roving tabindex, arrows move focus only and activation is separate — appropriate if segments were actions, which they are not.
-
-Other gaps, secondary to the above:
-
-- **No arrow-key navigation** and **no roving tabindex** — each segment is its own tab stop.
-- **No accessible name** on the group.
-- **No disabled support** on individual options, unlike RadioGroup.
-- No visible focus ring is defined; the control relies on the UA outline over a custom face.
-
-**RadioGroup in this same file gets all of this right for free** by using native `<input type="radio">` with a shared `name`. Rebuilding SegmentedControl's semantics on the same foundation — native radios, visually hidden, with the labels as the faces — would close every gap above without touching the sliding highlight. That is the fix, and it is not a large one.
+- **Focus** draws a 2px `--ring` outline inside the label of the focused radio (`:has(:focus-visible)`), inset because the rail's padding is thinner than an outside ring.
+- **Disabled** dims the whole rail; there is no per-option disabled, unlike **RadioGroup**.
+- **The selected label is bold**, and a hidden bold copy of each label (`visibility: hidden`, so it never reaches the accessible name) reserves that width, so selection never shifts the segments.
+- **A controlled `@value` that rejects a change** puts the radio back; focus stays on the radio the reader moved to.
 
 ## Theming
 
-Rail and segments consume `--muted-foreground` and `--foreground` for inactive/active ink and `--text-ui-md` for type; the pill itself is **SlidingHighlight**'s, so its fill, radius and shadow are that component's tokens. The 2px inter-segment gap and the rail's `inline-flex` metrics are fixed.
+The rail is an `--inset` surface with `--foreground`, edged in `--border`. Labels are set in the ui-label role (`--boxel-ui-label-*`) in `--muted-foreground`; the selected one takes `--card-foreground`, since it sits on the pill's `--card` face, at weight 600 (`--pretui-seg-active-weight`). The pill itself is **SlidingHighlight**'s: `--card` with a `--border-strong` edge and `--shadow-sm`. `--pretui-seg-radius` (Button's corner, `--radius` less 2px) rounds the segments and the pill, and `--pretui-seg-inset` (`--boxel-sp-6xs`) sets the rail's gap, its padding and the radius it adds on top, which keeps the pill's corner concentric with the rail's.
 
-Because active state is carried by the traveling pill plus an ink shift, a season that makes the pill low-contrast against the rail leaves the control reading as four equal buttons. Check the pill fill against the rail background, not against the page.
+Because the selection is carried by the pill, the ink shift and the weight, a theme whose `--card` and `--inset` are close leaves the pill's edge doing the work. Check the pill against the rail background, not against the page.
 
 The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
diff --git a/packages/pretui/components/sliding-highlight.gts b/packages/pretui/components/sliding-highlight.gts
index a9f29504dc2..b46a86b554a 100644
--- a/packages/pretui/components/sliding-highlight.gts
+++ b/packages/pretui/components/sliding-highlight.gts
@@ -1,4 +1,4 @@
-// Pretui — SlidingHighlight: the travelling selection indicator and the modifier that measures it.
+// Pretui — SlidingHighlight: the traveling selection indicator and the modifier that measures it.
 import Component from '@glimmer/component';
 import { htmlSafe } from '@ember/template';
 import { modifier } from 'ember-modifier';
@@ -138,7 +138,7 @@ export interface SlidingHighlightSignature {
 }
 
 /**
- * The travelling indicator. Render it inside a container carrying
+ * The traveling indicator. Render it inside a container carrying
  * `{{slidingHighlight}}`; it needs no arguments to work. Its block is a slot
  * for callers who want to paint the indicator themselves (a gradient, a
  * texture) while keeping the travel.
@@ -151,7 +151,7 @@ export class SlidingHighlight extends Component<SlidingHighlightSignature> {
     let bits: string[] = [];
     if (this.args.duration !== undefined) {
       bits.push(
-        `--pretui-highlight-duration: ${seconds(this.args.duration, 0.22)}`,
+        `--pretui-highlight-duration: ${seconds(this.args.duration, 0.18)}`,
       );
     }
     {
@@ -174,8 +174,8 @@ export class SlidingHighlight extends Component<SlidingHighlightSignature> {
       data-variant={{this.variant}}
       style={{this.style}}
       aria-hidden='true'
-      data-test-pretui-sliding-highlight
       ...attributes
+      data-test-pretui-sliding-highlight
     >{{yield}}</span>
     <style scoped>
       @layer PretComponent {
@@ -195,15 +195,14 @@ export class SlidingHighlight extends Component<SlidingHighlightSignature> {
           z-index: 0;
           transition-property: transform, width, height, opacity;
           /* --init is present only for the first measurement (see the
-             modifier); the chain then falls through to the caller's duration,
-             then to the kit's snap default. */
+             modifier); the chain then falls through to the caller's duration */
           transition-duration: var(
             --pretui-highlight-init,
-            var(--pretui-highlight-duration, var(--pretui-dur-snap, 180ms))
+            var(--pretui-highlight-duration, 180ms)
           );
           transition-timing-function: var(
             --pretui-highlight-ease,
-            var(--pretui-ease-snap, cubic-bezier(0.23, 1, 0.32, 1))
+            cubic-bezier(0.23, 1, 0.32, 1)
           );
         }
         /* a strong edge, so the pill reads even when its track blends into
@@ -215,19 +214,21 @@ export class SlidingHighlight extends Component<SlidingHighlightSignature> {
             var(--shadow-sm);
         }
         .pretui-highlight[data-variant='soft'] {
-          background: color-mix(
+          background-color: color-mix(
             in oklch,
             var(--primary) 14%,
             var(--card)
           );
         }
+        /* a line is drawn in the -ink, which holds 3:1 on the surface; the
+           --primary fill does not */
         .pretui-highlight[data-variant='outline'] {
-          box-shadow: 0 0 0 1px var(--primary);
+          box-shadow: 0 0 0 1px var(--primary-ink);
         }
         .pretui-highlight[data-variant='underline'] {
           height: var(--pretui-highlight-thickness, 2px);
           border-radius: var(--pretui-highlight-radius, 1px);
-          background: var(--primary);
+          background-color: var(--primary-ink);
           /* ride the bottom edge of the active item's box */
           transform: translate(
             var(--pretui-highlight-x, 0px),
diff --git a/packages/pretui/components/sliding-highlight.md b/packages/pretui/components/sliding-highlight.md
index d27fb982be3..82cfd14fa78 100644
--- a/packages/pretui/components/sliding-highlight.md
+++ b/packages/pretui/components/sliding-highlight.md
@@ -1,6 +1,6 @@
 ## What it is
 
-The travelling selection indicator: one element that moves and resizes to sit under whichever item is active. **Law 5's second canonical mechanism**, and it is shared — **Tabs**, **SegmentedControl** and **Select** all use this exact component rather than each painting their own active state. Use it whenever a set of peers has one active member and the selection should _travel_ rather than cross-fade. If the active state is a static fill, plain CSS is enough.
+The traveling selection indicator: one element that moves and resizes to sit under whichever item is active. **Law 5's second canonical mechanism**, and it is shared — **Tabs** and **SegmentedControl** both use this exact component rather than each painting their own active state. Use it whenever a set of peers has one active member and the selection should _travel_ rather than cross-fade. If the active state is a static fill, plain CSS is enough.
 
 ## The contract
 
@@ -12,7 +12,7 @@ The travelling selection indicator: one element that moves and resizes to sit un
 <:default>   — paint the indicator yourself while keeping the travel
 ```
 
-**Two parts, and the split is the design.** The modifier measures; the component paints. The modifier publishes `--pretui-highlight-x/y/w/h/on` on the container, and the indicator is an absolutely-positioned element that reads them. So the measuring code exists **once** for the whole kit, and any component that wants a travelling indicator adds a modifier and an element rather than a measurement implementation.
+**Two parts, and the split is the design.** The modifier measures; the component paints. The modifier publishes `--pretui-highlight-x/y/w/h/on` on the container, and the indicator is an absolutely-positioned element that reads them. So the measuring code exists **once** for the whole kit, and any component that wants a traveling indicator adds a modifier and an element rather than a measurement implementation.
 
 **It needs no arguments to work.** The default selector finds the active descendant; pass a custom one (`':scope > [aria-selected="true"]'`) when the container also holds selectable content the default would reach.
 
@@ -38,21 +38,21 @@ Where a second copy still exists: **TableOfContents** has a local vertical imple
 
 **No roles, no states, no keyboard — and that is correct.** The indicator is decoration; the selection it tracks is expressed by whatever the container marks as active (`aria-selected` on a tab, `aria-checked` on a radio, `data-state` on a segment).
 
-The important consequence, and it is a real one: **this component makes selection _look_ well-communicated while contributing nothing to how it is _announced_.** Two of its three consumers have exactly that problem — **SegmentedControl** carries `role="tablist"` over children with no `role="tab"` and no `aria-selected`, and **FilterChips** does the same with `aria-pressed`. In both, the travelling pill is the only clear selection signal, and it is invisible to assistive tech. Fixing those components' roles is the work; this component cannot help.
+The important consequence, and it is a real one: **this component makes selection _look_ well-communicated while contributing nothing to how it is _announced_.** Each consumer exposes the selection itself: **Tabs** with `aria-selected`, **SegmentedControl** with native checked radios. A new consumer must do the same; the pill alone is invisible to assistive tech.
 
 Other notes:
 
 - **First-paint suppression** exists (the `first` flag), so the indicator does not animate from `0,0` on mount — it appears in place. Without that, every tab strip would slide in from the top-left corner on load.
-- **A reduced-motion fallback is described as living in this primitive.** Verify it: the travel is a `transition` on the indicator's position, and `prefers-reduced-motion: reduce` should collapse it to an instant move rather than removing the indicator. This is the right place for that guard and the reason consumers should not roll their own.
+- **Reduced motion** sets `transition-property: none`, so the indicator moves to its new place instantly instead of disappearing. The guard lives here so consumers don't roll their own.
 - **`--pretui-highlight-on: 0`** hides the indicator when nothing is active, so an empty state does not leave a stray bar.
 - The indicator is absolutely positioned inside the container and does not affect layout, so it cannot push content or trap focus.
 
 ## Theming
 
-`--pretui-highlight-duration` (default 0.22s), `--pretui-highlight-thickness`, `--pretui-highlight-radius` (defaults to the control radius, or 1px under `underline`), plus the four variants' fills — `pill` is a raised card face, `soft` an accent tint, `outline` a hairline, `underline` a bar.
+`--pretui-highlight-duration` (default 0.18s), `--pretui-highlight-ease` (default `cubic-bezier(0.23, 1, 0.32, 1)`), `--pretui-highlight-thickness`, `--pretui-highlight-radius` (defaults to the control radius, or 1px under `underline`), plus the four variants: `pill` is a `--card` face with a 1px `--border-strong` edge and `--shadow-sm`, `soft` a `--primary` tint over `--card`, `outline` a 1px `--primary-ink` line, `underline` a `--primary-ink` bar. Lines use the `-ink` because the `--primary` fill misses 3:1 as a line.
 
-The published measurement properties (`--pretui-highlight-x/y/w/h/on`) are read-only outputs; a season should not set them.
+The published measurement properties (`--pretui-highlight-x/y/w/h/on`) are read-only outputs; a theme or caller should not set them.
 
-Because `pill` is a raised card face, it depends on `--card` and the kit's shadow tokens reading distinctly against whatever rail it sits on — a season that makes the rail and the card the same colour leaves a pill visible only by its shadow, which is the most common way this primitive is undermined.
+Because `pill` is a card face, it depends on `--card`, its `--border-strong` edge and `--shadow-sm` reading distinctly against whatever rail it sits on. A theme that makes the rail and the card the same color leaves the pill visible only by its edge and shadow.
 
 The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

From 7b1d78a016e5ff9257a62063afb8dd29d7db283f Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Thu, 8 Oct 2026 15:24:50 -0400
Subject: [PATCH 14/30] Name the usage page's panels from their headings,
 scroll its source in a keyboard region, and give Table cells their ink and
 line height

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../pretui/components/freestyle-usage.gts     | 47 ++++++++++++++-----
 packages/pretui/components/freestyle-usage.md | 10 ++--
 packages/pretui/components/table.gts          | 11 ++++-
 packages/pretui/components/table.md           |  9 ++--
 4 files changed, 53 insertions(+), 24 deletions(-)

diff --git a/packages/pretui/components/freestyle-usage.gts b/packages/pretui/components/freestyle-usage.gts
index de5b1aed921..ae4ad5479ec 100644
--- a/packages/pretui/components/freestyle-usage.gts
+++ b/packages/pretui/components/freestyle-usage.gts
@@ -1,6 +1,6 @@
 // Pretui — FreestyleUsage: a component's usage page — example, knobs and API table.
 import type { TemplateOnlyComponent } from '@ember/component/template-only';
-import { hash } from '@ember/helper';
+import { hash, uniqueId } from '@ember/helper';
 import { Table } from './table';
 import { CopyButton } from './copy-button';
 import { UsageAction } from './usage-action';
@@ -13,7 +13,7 @@ import { UsageNumber } from './usage-number';
 import { UsageObject } from './usage-object';
 import { UsageString } from './usage-string';
 import { UsageYield } from './usage-yield';
-import { Viewport } from './viewport';
+import { Viewport, type ViewportSignature } from './viewport';
 
 // ── FreestyleUsage (the page) ────────────────────────────────────────────
 export interface FreestyleUsageSignature {
@@ -22,7 +22,7 @@ export interface FreestyleUsageSignature {
     description?: string;
     slug?: string;
     source?: string;
-    viewportMode?: 'fill' | 'narrow' | 'wide' | 'inline' | 'grid';
+    viewportMode?: ViewportSignature['Args']['defaultMode'];
   };
   Blocks: {
     description: [];
@@ -50,6 +50,7 @@ export interface FreestyleUsageSignature {
 
 export const FreestyleUsage: TemplateOnlyComponent<FreestyleUsageSignature> =
   <template>
+    {{#let (uniqueId) (uniqueId) (uniqueId) as |propsId apiId cssId|}}
     <div class='pretui-usage' data-test-pretui-usage ...attributes>
       {{! the component's name lives in the page header (breadcrumb); one
           compact description line, then straight to the artboard }}
@@ -73,10 +74,19 @@ export const FreestyleUsage: TemplateOnlyComponent<FreestyleUsageSignature> =
             </Viewport>
             {{#if @source}}
               <div class='wb-codestrip' data-test-pretui-usage-source>
-                <code
-                  class='wb-code'
-                  data-test-pretui-usage-source-code
-                >{{@source}}</code>
+                {{! the code scrolls, not the strip, so Copy stays in view; a
+                    scroller needs a tab stop and a name for keyboard users }}
+                <div
+                  class='wb-code-scroll'
+                  tabindex='0'
+                  role='region'
+                  aria-label='Usage source'
+                >
+                  <code
+                    class='wb-code'
+                    data-test-pretui-usage-source-code
+                  >{{@source}}</code>
+                </div>
                 <CopyButton
                   @text={{@source}}
                   @label='Copy usage'
@@ -89,9 +99,11 @@ export const FreestyleUsage: TemplateOnlyComponent<FreestyleUsageSignature> =
         {{#if (has-block 'api')}}
           <aside
             class='pretui-usage-props wb-panel'
+            aria-labelledby={{propsId}}
             data-test-pretui-usage-props
           >
             <h2
+              id={{propsId}}
               class='pretui-usage-section-title'
               data-test-pretui-usage-section-title
             >Properties</h2>
@@ -123,11 +135,12 @@ export const FreestyleUsage: TemplateOnlyComponent<FreestyleUsageSignature> =
         <div class='pretui-usage-api wb-panel' data-test-pretui-usage-api>
           <div class='wb-panel-h'>
             <h2
+              id={{apiId}}
               class='pretui-usage-section-title wb-cap'
               data-test-pretui-usage-section-title
             >API</h2>
           </div>
-          <Table @framed={{false}}>
+          <Table @framed={{false}} @labelledBy={{apiId}}>
             <:head>
               <tr>
                 <th>Argument</th>
@@ -160,11 +173,12 @@ export const FreestyleUsage: TemplateOnlyComponent<FreestyleUsageSignature> =
         <div class='pretui-usage-api wb-panel' data-test-pretui-usage-css-vars>
           <div class='wb-panel-h'>
             <h2
+              id={{cssId}}
               class='pretui-usage-section-title wb-cap'
               data-test-pretui-usage-section-title
             >CSS Variables</h2>
           </div>
-          <Table @framed={{false}}>
+          <Table @framed={{false}} @labelledBy={{cssId}}>
             <:head>
               <tr>
                 <th>Variable</th>
@@ -183,9 +197,10 @@ export const FreestyleUsage: TemplateOnlyComponent<FreestyleUsageSignature> =
         </div>
       {{/if}}
     </div>
+    {{/let}}
     <style scoped>
       .pretui-usage {
-        --pretui-usage-props-w: 22rem;
+        --pretui-usage-props-w: 26rem;
         --pretui-usage-panel-h: 2.25rem;
         --pretui-usage-description-max-w: 64rem;
 
@@ -197,6 +212,7 @@ export const FreestyleUsage: TemplateOnlyComponent<FreestyleUsageSignature> =
       }
       .pretui-usage-description {
         max-inline-size: var(--pretui-usage-description-max-w);
+        line-height: var(--boxel-line-height-md);
         color: var(--muted-foreground);
       }
       /* the Properties rail wraps under the preview when the preview would
@@ -248,16 +264,23 @@ export const FreestyleUsage: TemplateOnlyComponent<FreestyleUsageSignature> =
         display: flex;
         align-items: center;
         gap: var(--boxel-sp-sm);
-        padding: var(--boxel-sp-2xs) var(--boxel-sp-sm);
+        padding-inline: var(--boxel-sp-sm);
         box-shadow: inset 0 1px 0 var(--border);
+      }
+      /* the block padding lives here, not on the strip, so an overlay
+         scrollbar draws in it rather than over the one line of code */
+      .wb-code-scroll {
+        flex: 1;
+        min-width: 0;
+        padding-block: var(--boxel-sp-xs);
         overflow-x: auto;
+        scrollbar-width: thin;
       }
       .wb-code {
         font-family: var(--font-mono);
         font-size: var(--boxel-font-size-xs);
         color: var(--muted-foreground);
         white-space: pre;
-        flex: 1;
       }
       .wb-codestrip > :last-child {
         flex: none;
diff --git a/packages/pretui/components/freestyle-usage.md b/packages/pretui/components/freestyle-usage.md
index 560695990a4..37bee179771 100644
--- a/packages/pretui/components/freestyle-usage.md
+++ b/packages/pretui/components/freestyle-usage.md
@@ -1,6 +1,6 @@
 ## What it is
 
-The usage page: a component's example, its interactive knobs, its API table and its source, in one frame. Use it to document a component. Every page in the Pretui catalogue is one of these. If you only need the artboard frame, **Viewport**; if you need the theme switcher, **ThemeFrame**.
+The usage page: a component's example, its interactive knobs, its API table and its source, in one frame. Use it to document a component. Every page in the Pret UI catalog is one of these. If you only need the artboard frame, **Viewport**; if you need the theme switcher, **ThemeFrame**.
 
 ## The contract
 
@@ -35,15 +35,15 @@ No pattern governs it; it is a page composed of the kit's own components, and it
 
 Gaps worth knowing, because a documentation surface is read by exactly the people who care about these:
 
-- **Only part of the page has heading structure.** Properties, API and CSS Variables are headed by `h2`s, so heading navigation reaches the knobs and the tables, and Properties is an `<aside>`. The description and the example have no heading, and no region carries an `aria-label`, so a screen-reader user cannot jump to "the example", and landmark navigation finds an unnamed complementary region.
-- **`@name` is not necessarily a heading**, and if it is, its level is fixed — the kit-wide problem (**Panel**, **Toolbar**, **EmptyState**, **Stat**, **FittedCard** all share it).
+- **Only part of the page has heading structure.** Properties, API and CSS Variables are headed by `h2`s, so heading navigation reaches the knobs and the tables; Properties is an `<aside>` named "Properties", and each table carries its heading as its name. The description and the example have no heading or region, so a screen-reader user cannot jump to "the example".
+- **`@name` is not a heading here.** It only labels the Viewport's artboard; the page's heading is the Spec's `h1`, and the section titles are `h2`s under it.
 - **The knobs and the API table describe the same arguments and are not linked.** A user reading a row in the docs table has no route to the control that changes it.
-- **The `<code>` source strip** needs `tabindex="0"` if it scrolls, or a keyboard user cannot reach the end of a long line (**WCAG 2.1.1**), and it has no language annotation.
+- **The `<code>` source has no language annotation.** It scrolls inside a named region ("Usage source") with a tab stop, so a keyboard user can reach the end of a long line, and the Copy button stays in view beside it.
 - **Changing a knob re-renders the example silently.** A `role="status"` region would make the cause-and-effect available; without it, a screen-reader user changing a Select has no confirmation that anything happened.
 - **The example region contains arbitrary live components**, so the page's overall accessibility is whatever is being demonstrated — including deliberately-broken states. That is unavoidable and worth stating: a usage page is not a claim about the component's accessibility.
 
 ## Theming
 
-Composes **Viewport**, **Table**, **Select**, **Input**, **Switch**, **Slider**, **SegmentedControl**, **CopyButton** and **Popover**, so it consumes their token sets rather than defining many of its own. Page structure uses `--card` with `--card-foreground`, `--border`, `--muted-foreground`, `--boxel-border-radius` and the `--boxel-sp-*` scale; the section titles take the eyebrow role (`--boxel-eyebrow-*`).
+Composes **Viewport**, **Table**, **Select**, **Input**, **Switch**, **Slider**, **SegmentedControl**, **CopyButton** and **Popover**, so it consumes their token sets rather than defining many of its own. Page structure uses `--card` with `--card-foreground`, `--border`, `--muted-foreground`, `--boxel-border-radius` and the `--boxel-sp-*` scale; the section titles take the eyebrow role (`--boxel-eyebrow-*`), and the source is set in `--font-mono` at `--boxel-font-size-xs`. The Properties panel and the two tables are named by their `h2`s.
 
 The whole page renders inside the theme island, so a theme change re-dresses both the documentation chrome _and_ the example — which is the point, and is what **ThemeFrame** exists to drive.
diff --git a/packages/pretui/components/table.gts b/packages/pretui/components/table.gts
index 3343e36b843..6d8f8d03fc2 100644
--- a/packages/pretui/components/table.gts
+++ b/packages/pretui/components/table.gts
@@ -64,7 +64,11 @@ export const Table: TemplateOnlyComponent<TableSignature> = <template>
          vertically. A caller bounds it with --pretui-table-max-height; unset,
          the wrapper grows with its rows and the header scrolls away with them. */
       .pretui-tablewrap {
+        --pretui-table-head-height: 1.875rem;
+
         overflow: auto;
+        /* a focused cell scrolls clear of the sticky header */
+        scroll-padding-block-start: var(--pretui-table-head-height);
         min-width: 0;
         max-width: 100%;
         max-height: var(--pretui-table-max-height, none);
@@ -78,7 +82,6 @@ export const Table: TemplateOnlyComponent<TableSignature> = <template>
         box-shadow: none;
       }
       .pretui-table {
-        --pretui-table-head-height: 1.875rem;
         width: 100%;
         border-collapse: collapse;
         font-size: var(--boxel-font-size-xs);
@@ -100,10 +103,11 @@ export const Table: TemplateOnlyComponent<TableSignature> = <template>
         letter-spacing: var(--boxel-ui-label-letter-spacing);
         text-transform: uppercase;
         white-space: nowrap;
-        color: var(--foreground);
       }
+      /* cells wrap, so the body line height clears the 1.4 floor */
       .pretui-table tbody {
         vertical-align: top;
+        line-height: var(--boxel-line-height-md);
       }
       /* :deep() only for what the browser's th rule overrides and for what
          doesn't inherit. */
@@ -116,6 +120,7 @@ export const Table: TemplateOnlyComponent<TableSignature> = <template>
         text-align: start;
         font-weight: var(--boxel-ui-label-font-weight);
         background-color: var(--inset);
+        color: var(--foreground);
         box-shadow: inset 0 -1px 0 var(--border-strong);
       }
       .pretui-table :deep(td),
@@ -140,11 +145,13 @@ export const Table: TemplateOnlyComponent<TableSignature> = <template>
       .pretui-table :deep(tbody tr:nth-child(even) td),
       .pretui-table :deep(tbody tr:nth-child(even) th) {
         background-color: var(--stripe);
+        color: var(--foreground);
       }
       @media (hover: hover) {
         .pretui-table :deep(tbody tr:hover td),
         .pretui-table :deep(tbody tr:hover th) {
           background-color: var(--hover);
+          color: var(--foreground);
         }
       }
     }
diff --git a/packages/pretui/components/table.md b/packages/pretui/components/table.md
index e85f26f68f5..c339debc58a 100644
--- a/packages/pretui/components/table.md
+++ b/packages/pretui/components/table.md
@@ -49,20 +49,19 @@ Governing pattern: APG **Table**, whose keyboard interaction section reads "Not
 
 Component-level gaps:
 
-- **The scroll container has no `tabindex="0"`.** `overflow-x: auto` on a wide table means a keyboard-only user cannot scroll it without tabbing through cells, which fails WCAG **2.1.1** for a table of static text. One attribute fixes it, and it would fix DataGrid too.
-- **Sticky headers with no `scroll-margin`** can obscure a focused cell in a vertically scrolled table (WCAG **2.4.11 Focus Not Obscured**).
+- **The scroll container has no `tabindex="0"`.** `overflow: auto` on a wide table means a keyboard-only user cannot scroll it without tabbing through cells, which fails WCAG **2.1.1** for a table of static text. One attribute fixes it, and it would fix DataGrid too.
 - `vertical-align: top` on the body (inherited by every cell) is a good default for mixed-height content and worth knowing about before you fight it.
 
 ## Theming
 
 Everything comes from the boxel theme contract:
 
-- **Surfaces and ink:** `--card` with `--card-foreground` (the wrapper, which cells inherit), `--inset` with `--foreground` (the header band), `--muted-foreground` (the caption), `--stripe` (zebra), `--hover` (row hover, on devices that hover).
-- **Rules and edge:** `--border` (row rules and the outer hairline), `--border-strong` (header underline), `--radius`.
+- **Surfaces and ink:** `--card` with `--card-foreground` (the wrapper, which cells inherit), `--inset` with `--foreground` (the header band), `--muted-foreground` (the caption), `--stripe` (zebra) and `--hover` (row hover, on devices that hover), each with `--foreground`.
+- **Rules and edge:** `--border` (row rules and the outer hairline), `--border-strong` (header underline), `--boxel-border-radius` (the frame's corner).
 - **Type:** `--boxel-font-size-xs` (the table), the caption role (`--boxel-caption-font-size`, `-font-weight`, `-line-height`, `-letter-spacing`), the label role for the header band (`--boxel-ui-label-font-size`, `-font-weight`, `-letter-spacing`), and `--font-mono` for its family.
 - **Spacing:** `--boxel-sp-2xs` (block padding of the caption and cells) and `--boxel-sp-xs` (inline padding of the caption, header and cells, so their text shares one start edge).
 
-The header band's height is `--pretui-table-head-height` (1.875rem), declared on `.pretui-table`. **The header only sticks inside a wrapper that scrolls vertically.** `overflow: auto` makes the wrapper the header's scroll container, and with no height limit it never scrolls, so the header leaves with the rows. Set `--pretui-table-max-height` on the table (or an ancestor) to bound the wrapper, for example `--pretui-table-max-height: 24rem`; the rows then scroll under a header that stays put. Unset, it is `none` and the table is as tall as its rows. `--stripe` must be distinguishable from both `--card` and `--hover`, or zebra and hover collapse into each other.
+The header band's height is `--pretui-table-head-height` (1.875rem), declared on the wrapper so a caller can set it; the wrapper also reads it as `scroll-padding-block-start`, so a focused cell scrolls clear of the sticky header. Body cells take a 1.4 line height (`--boxel-line-height-md`), since they wrap. **The header only sticks inside a wrapper that scrolls vertically.** `overflow: auto` makes the wrapper the header's scroll container, and with no height limit it never scrolls, so the header leaves with the rows. Set `--pretui-table-max-height` on the table (or an ancestor) to bound the wrapper, for example `--pretui-table-max-height: 24rem`; the rows then scroll under a header that stays put. Unset, it is `none` and the table is as tall as its rows. `--stripe` must be distinguishable from both `--card` and `--hover`, or zebra and hover collapse into each other.
 
 The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
 

From ddc009df45df6bf07d5572eedf452bdd28c2ca91 Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Thu, 8 Oct 2026 15:24:52 -0400
Subject: [PATCH 15/30] Paint ThemeFrame's island with --background, fill the
 frame, and name its controls

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/components/theme-frame.gts | 16 +++++++++++++---
 packages/pretui/components/theme-frame.md  |  4 ++++
 2 files changed, 17 insertions(+), 3 deletions(-)

diff --git a/packages/pretui/components/theme-frame.gts b/packages/pretui/components/theme-frame.gts
index 79675107acc..9236fd15ede 100644
--- a/packages/pretui/components/theme-frame.gts
+++ b/packages/pretui/components/theme-frame.gts
@@ -69,7 +69,13 @@ interface ThemeControlsSignature {
 }
 
 const ThemeControls: TemplateOnlyComponent<ThemeControlsSignature> = <template>
-  <span class='pretui-theme-controls' data-test-pretui-theme-bar ...attributes>
+  <span
+    class='pretui-theme-controls'
+    role='group'
+    aria-label='Theme preview'
+    data-test-pretui-theme-bar
+    ...attributes
+  >
     <Switch
       @isEnabled={{@frame.isDarkMode}}
       @onChange={{@frame.toggleDarkMode}}
@@ -230,7 +236,11 @@ export class ThemeFrame extends Component<ThemeFrameSignature> {
     </div>
     <style scoped>
       @layer PretComponent {
+        /* a column, so the surface grows to fill the frame: a percentage
+           min-height can't, since the frame's own height isn't definite */
         .pretui-theme-frame {
+          display: flex;
+          flex-direction: column;
           min-height: 100%;
         }
         /* the scoped theme channel only carries custom properties, so the
@@ -245,8 +255,8 @@ export class ThemeFrame extends Component<ThemeFrameSignature> {
            applies its own background, foreground and font, or the card's show
            through */
         .pretui-theme-surface {
-          min-height: 100%;
-          background-color: var(--canvas);
+          flex: 1 0 auto;
+          background-color: var(--background);
           color: var(--foreground);
           font-family: var(--font-sans);
         }
diff --git a/packages/pretui/components/theme-frame.md b/packages/pretui/components/theme-frame.md
index ae616f2a5a4..5da19a73c60 100644
--- a/packages/pretui/components/theme-frame.md
+++ b/packages/pretui/components/theme-frame.md
@@ -42,3 +42,7 @@ Where it is thinner: no persistence, no per-component theme override, and no way
 The frame applies a theme rather than being themed by one — it establishes the token scope its subtree renders in, using boxel-ui's own theme helpers rather than hand-rolling the scoping.
 
 Its own controls take the active theme's tokens, so the switch and select restyle with the theme they switch to.
+
+The island paints its own surface, `--background` with `--foreground` in `--font-sans`, because its tokens flip below the card's own surface and the card's would otherwise show through. It grows to fill the frame. The controls are a group named "Theme preview"; the theme's name, when shown, is `--muted-foreground`.
+
+The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

From 58b6b9316f24c37bae3622ffc3f2788900411317 Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Thu, 8 Oct 2026 15:24:54 -0400
Subject: [PATCH 16/30] Use the caption size and a shared gutter on the Spec
 page, show a loading state, and keep the edit view's caps on its captions

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/pretui-component.gts | 115 +++++++++++++++------------
 1 file changed, 66 insertions(+), 49 deletions(-)

diff --git a/packages/pretui/pretui-component.gts b/packages/pretui/pretui-component.gts
index 7bbcbb9aa3b..89a6357cbb3 100644
--- a/packages/pretui/pretui-component.gts
+++ b/packages/pretui/pretui-component.gts
@@ -30,6 +30,7 @@ import { fn } from '@ember/helper';
 import type { Query, RealmResourceIdentifier } from '@cardstack/runtime-common';
 import { ThemeFrame } from './components/theme-frame';
 import { EmptyState } from './components/empty-state';
+import { LoadingState } from './components/loading-state';
 import { StatusChip } from './components/status-chip';
 import { Chip } from './components/chip';
 import { Token } from './components/token';
@@ -130,11 +131,7 @@ class WriteupFold extends GlimmerComponent<WriteupFoldSignature> {
     <div class='wb-fold' data-open={{if this.open 'true'}} ...attributes>
       {{! the write-up's prose only — the panel owns the padding, so the
           file's own embedded chrome and surface stay out }}
-      <div
-        id={{this.regionId}}
-        class='wb-fold-region'
-        {{this.measureOverflow}}
-      >
+      <div id={{this.regionId}} class='wb-fold-region' {{this.measureOverflow}}>
         <div class='wb-fold-prose'>
           <MarkdownPreview
             @model={{@writeup}}
@@ -702,7 +699,9 @@ export class PretUISpec extends Spec {
             {{#if this.demo}}
               <this.demo />
             {{else if this.isDemoLoading}}
-              <section class='panel' aria-busy='true'></section>
+              <section class='panel' aria-busy='true'>
+                <LoadingState @label='Loading the usage page' />
+              </section>
             {{else if this.isDemoExcluded}}
               <section class='panel'>
                 {{#if this.isHost}}
@@ -734,10 +733,7 @@ export class PretUISpec extends Spec {
                 aria-labelledby={{this.writeupHeadingId}}
               >
                 <div class='wb-panel-h'>
-                  <h2
-                    id={{this.writeupHeadingId}}
-                    class='wb-cap'
-                  >Write-up</h2>
+                  <h2 id={{this.writeupHeadingId}} class='wb-cap'>Write-up</h2>
                 </div>
                 <WriteupFold
                   class='wb-writeup-fold'
@@ -814,9 +810,12 @@ export class PretUISpec extends Spec {
           --wb-provenance-max-w: 30rem;
           --wb-krow-label-w: 6.875rem;
           --wb-dot-size: 0.5rem;
+          /* the page's inline padding, which the topbar cancels and restores
+             to run edge to edge */
+          --wb-page-gutter: var(--boxel-sp-lg);
 
           min-height: 100%;
-          padding: 0 var(--boxel-sp-lg) var(--boxel-sp-2xl);
+          padding: 0 var(--wb-page-gutter) var(--boxel-sp-2xl);
           display: grid;
           gap: var(--boxel-sp);
           align-content: start;
@@ -834,7 +833,7 @@ export class PretUISpec extends Spec {
           gap: var(--boxel-sp-xs);
         }
         /* the component's icon beside its title: a --background tile with a
-           hairline ring on the page's --canvas, not a raised button */
+           hairline ring, not a raised button */
         .wb-title-frame {
           --icon-color: currentColor;
           --icon-bg: none;
@@ -859,8 +858,8 @@ export class PretUISpec extends Spec {
           align-items: center;
           gap: var(--boxel-sp-sm);
           min-height: var(--wb-topbar-h);
-          margin: 0 calc(-1 * var(--boxel-sp-lg));
-          padding: var(--boxel-sp-2xs) var(--boxel-sp-lg);
+          margin: 0 calc(-1 * var(--wb-page-gutter));
+          padding: var(--boxel-sp-2xs) var(--wb-page-gutter);
           background-color: var(--card);
           color: var(--card-foreground);
           box-shadow: inset 0 -1px 0 var(--border);
@@ -878,7 +877,7 @@ export class PretUISpec extends Spec {
           padding: var(--boxel-sp-5xs) var(--boxel-sp-3xs);
         }
         .wb-here {
-          color: var(--foreground);
+          color: var(--card-foreground);
           font-weight: 600;
         }
         .wb-badges {
@@ -938,7 +937,7 @@ export class PretUISpec extends Spec {
           box-shadow:
             0 0 0 1px var(--border),
             var(--shadow-sm);
-          font-size: var(--boxel-font-size-xs);
+          font-size: var(--boxel-caption-font-size);
           line-height: 1.5;
         }
         .note:focus-visible {
@@ -1024,7 +1023,6 @@ export class PretUISpec extends Spec {
         /* THE caps treatment — panel and group headers only (type spec:
            one caps style, everything else sentence case) */
         .wb-cap {
-          margin: 0;
           font-family: var(--boxel-eyebrow-font-family);
           font-size: var(--boxel-eyebrow-font-size);
           font-weight: var(--boxel-eyebrow-font-weight);
@@ -1087,7 +1085,7 @@ export class PretUISpec extends Spec {
         }
         .brief {
           max-width: 78ch;
-          font-size: var(--boxel-font-size-xs);
+          font-size: var(--boxel-caption-font-size);
           line-height: 1.5;
           color: var(--muted-foreground);
         }
@@ -1256,9 +1254,9 @@ export class PretUISpec extends Spec {
             -webkit-box-orient: vertical;
             -webkit-line-clamp: 3;
             overflow: hidden;
-            font-size: var(--boxel-font-size-xs);
+            font-size: var(--boxel-caption-font-size);
             color: var(--muted-foreground);
-            line-height: 1.45;
+            line-height: 1.5;
             white-space: normal;
           }
         }
@@ -1327,21 +1325,28 @@ export class PretUISpec extends Spec {
         <fieldset class='wb-group'>
           <legend>Identity</legend>
           <div class='wb-fields'>
-            <label>Name <@fields.componentName /></label>
-            <label>Icon <@fields.icon /></label>
-            <label class='wb-wide'>Brief <@fields.brief /></label>
+            <label><span class='wb-cap'>Name</span>
+              <@fields.componentName /></label>
+            <label><span class='wb-cap'>Icon</span> <@fields.icon /></label>
+            <label class='wb-wide'><span class='wb-cap'>Brief</span>
+              <@fields.brief /></label>
           </div>
         </fieldset>
 
         <fieldset class='wb-group'>
           <legend>Taxonomy</legend>
           <div class='wb-fields'>
-            <label>Category <@fields.category /></label>
-            <label>Tier <@fields.tier /></label>
-            <label>Ownership <@fields.ownership /></label>
-            <label>Implementation <@fields.implementationStatus /></label>
-            <label>Adoption <@fields.adoptionStatus /></label>
-            <label>Introduced in <@fields.introducedVersion /></label>
+            <label><span class='wb-cap'>Category</span>
+              <@fields.category /></label>
+            <label><span class='wb-cap'>Tier</span> <@fields.tier /></label>
+            <label><span class='wb-cap'>Ownership</span>
+              <@fields.ownership /></label>
+            <label><span class='wb-cap'>Implementation</span>
+              <@fields.implementationStatus /></label>
+            <label><span class='wb-cap'>Adoption</span>
+              <@fields.adoptionStatus /></label>
+            <label><span class='wb-cap'>Introduced in</span>
+              <@fields.introducedVersion /></label>
             <div class='wb-wide'>
               <span class='wb-cap'>Tags</span>
               <@fields.tags />
@@ -1352,31 +1357,42 @@ export class PretUISpec extends Spec {
         <fieldset class='wb-group'>
           <legend>Provenance</legend>
           <div class='wb-fields'>
-            <label>Source <@fields.source /></label>
-            <label>Lineage <@fields.lineage /></label>
-            <label>Version <@fields.version /></label>
-            <label>Builds on <@fields.buildsOn /></label>
-            <label class='wb-wide'>References <@fields.refs /></label>
+            <label><span class='wb-cap'>Source</span> <@fields.source /></label>
+            <label><span class='wb-cap'>Lineage</span>
+              <@fields.lineage /></label>
+            <label><span class='wb-cap'>Version</span>
+              <@fields.version /></label>
+            <label><span class='wb-cap'>Builds on</span>
+              <@fields.buildsOn /></label>
+            <label class='wb-wide'><span class='wb-cap'>References</span>
+              <@fields.refs /></label>
           </div>
         </fieldset>
 
         <fieldset class='wb-group'>
           <legend>Signals</legend>
           <div class='wb-fields'>
-            <label>Demand (1-5) <@fields.demand /></label>
-            <label class='wb-flag'><@fields.featured /> Featured</label>
-            <label class='wb-flag'><@fields.isNew /> New</label>
-            <label class='wb-flag'><@fields.hasDesign /> Has design</label>
-            <label class='wb-flag'><@fields.hasExamples /> Has examples</label>
-            <label class='wb-flag'><@fields.liveInUse /> Live in use</label>
+            <label><span class='wb-cap'>Demand (1-5)</span>
+              <@fields.demand /></label>
+            <label class='wb-flag'><@fields.featured />
+              <span class='wb-cap'>Featured</span></label>
+            <label class='wb-flag'><@fields.isNew />
+              <span class='wb-cap'>New</span></label>
+            <label class='wb-flag'><@fields.hasDesign />
+              <span class='wb-cap'>Has design</span></label>
+            <label class='wb-flag'><@fields.hasExamples />
+              <span class='wb-cap'>Has examples</span></label>
+            <label class='wb-flag'><@fields.liveInUse />
+              <span class='wb-cap'>Live in use</span></label>
           </div>
         </fieldset>
 
         <fieldset class='wb-group'>
           <legend>Legacy axes</legend>
           <div class='wb-fields'>
-            <label>Territory <@fields.territory /></label>
-            <label>Stage <@fields.stage /></label>
+            <label><span class='wb-cap'>Territory</span>
+              <@fields.territory /></label>
+            <label><span class='wb-cap'>Stage</span> <@fields.stage /></label>
           </div>
         </fieldset>
 
@@ -1429,13 +1445,6 @@ export class PretUISpec extends Spec {
         .wb-fields > div {
           display: grid;
           gap: var(--boxel-sp-2xs);
-          font-family: var(--boxel-eyebrow-font-family);
-          font-size: var(--boxel-eyebrow-font-size);
-          font-weight: var(--boxel-eyebrow-font-weight);
-          line-height: var(--boxel-eyebrow-line-height);
-          letter-spacing: var(--boxel-eyebrow-letter-spacing);
-          text-transform: uppercase;
-          color: var(--muted-foreground);
           min-width: 0;
         }
         .wb-wide {
@@ -1445,8 +1454,16 @@ export class PretUISpec extends Spec {
           grid-template-columns: auto 1fr;
           align-items: center;
         }
+        /* the caption only, so the caps style stays off the editor beside it */
         .wb-cap {
           display: block;
+          font-family: var(--boxel-eyebrow-font-family);
+          font-size: var(--boxel-eyebrow-font-size);
+          font-weight: var(--boxel-eyebrow-font-weight);
+          line-height: var(--boxel-eyebrow-line-height);
+          letter-spacing: var(--boxel-eyebrow-letter-spacing);
+          text-transform: uppercase;
+          color: var(--muted-foreground);
         }
       </style>
     </template>

From 59f21b71ffee1a5816678d8ce660dd03cd8227fa Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Thu, 8 Oct 2026 15:24:55 -0400
Subject: [PATCH 17/30] Keep Chip's legacy text-size fallback for catalog
 chips, and correct StatusChip's docs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/components/chip.gts       |  5 ++++-
 packages/pretui/components/status-chip.md | 20 ++++++++++----------
 2 files changed, 14 insertions(+), 11 deletions(-)

diff --git a/packages/pretui/components/chip.gts b/packages/pretui/components/chip.gts
index 15c7f9aa2c6..83b1877c22d 100644
--- a/packages/pretui/components/chip.gts
+++ b/packages/pretui/components/chip.gts
@@ -57,7 +57,10 @@ export class Chip extends Component<ChipSignature> {
           padding: 0 var(--boxel-sp-2xs);
           border-radius: var(--boxel-border-radius-xs);
           /* --text-ui-xs is the legacy size knob catalog chips still set */
-          font-size: var(--pretui-chip-font-size, var(--boxel-font-size-2xs));
+          font-size: var(
+            --pretui-chip-font-size,
+            var(--text-ui-xs, var(--boxel-font-size-2xs))
+          );
           font-weight: 500;
           letter-spacing: var(--boxel-lsp-xs);
           white-space: nowrap;
diff --git a/packages/pretui/components/status-chip.md b/packages/pretui/components/status-chip.md
index adf903bf7dd..e4934753b93 100644
--- a/packages/pretui/components/status-chip.md
+++ b/packages/pretui/components/status-chip.md
@@ -1,6 +1,6 @@
 ## What it is
 
-A **Chip** whose colour is derived from the value rather than chosen. Pass `@value='In Review'` and you get a chip whose hue is a stable hash of that string — the same status is the same colour on every card, in every list, in every realm, without anyone maintaining a status-to-colour map. Use it for any enumerable state field. If you want to choose the colour, use **Chip** directly (or pass `@hue` here — the escape exists, but it is meant to be the exception). If the value filters a list, **FilterChips**. If it is a machine value, **Token**.
+A **Chip** whose color is derived from the value rather than chosen. Pass `@value='In Review'` and you get a chip whose hue is a stable hash of that string — the same status is the same color on every card, in every list, in every realm, without anyone maintaining a status-to-color map. Use it for any enumerable state field. If you want to choose the color, use **Chip** directly (or pass `@hue` here — the escape exists, but it is meant to be the exception). If the value filters a list, **FilterChips**. If it is a machine value, **Token**.
 
 ## The contract
 
@@ -10,23 +10,23 @@ A **Chip** whose colour is derived from the value rather than chosen. Pass `@val
 @tone?           — Chip's tone (default neutral)
 ```
 
-Three args, and the last two you should rarely reach for. A toned StatusChip is outlined in that tone and its dot takes the tone, so `@tone` is for a status whose meaning is fixed, like `live`; the hash hue stays on a neutral chip.
+Three args, and the last two you should rarely reach for. A toned StatusChip is outlined in that tone and its dot takes the tone unless `@hue` is passed, so `@tone` is for a status whose meaning is fixed, like `live`; the hash hue stays on a neutral chip.
 
 **The hue is a hash, and the hash is the point.** `statusHue()` runs a 32-bit polynomial rolling hash (`h * 31 + charCode`, unsigned) over the string and takes `h % 5` to index `--chart-1` … `--chart-5`. Deterministic, dependency-free, and — the property that matters — **stable across cards, realms and sessions**. No registry, no config, no design review to add a status.
 
-The corollary worth stating plainly: **the hue carries no semantics.** "Failed" is not red because it means failure; it is whatever colour its characters hash to. Five buckets also means collisions are common — with six statuses, two will share a colour. If your states have meaning that must be conveyed by colour (error/warning/success), **the hash is the wrong tool** — pass a `@tone` (StatusChip takes one for a fixed status like `live`, **Chip** for anything else), or use **Alert**.
+The corollary worth stating plainly: **the hue carries no semantics.** "Failed" is not red because it means failure; it is whatever color its characters hash to. Five buckets also means collisions are common — with six statuses, two will share a color. If your states have meaning that must be conveyed by color (error/warning/success), **the hash is the wrong tool** — pass a `@tone` (StatusChip takes one for a fixed status like `live`, **Chip** for anything else), or use **Alert**.
 
 ## Prior art
 
 Nobody else does this, which is either the interesting part or the suspicious part depending on your view.
 
-**Web Awesome `wa-tag`**, **shadcn `Badge`** and **React Spectrum `Badge`** all take a `variant` from a closed semantic enum, and every product using them maintains a `statusColors` map somewhere. **Linear**, **GitHub** and **Jira** all store the colour on the status entity — the colour is data, chosen by a human, persisted alongside the label.
+**Web Awesome `wa-tag`**, **shadcn `Badge`** and **React Spectrum `Badge`** all take a `variant` from a closed semantic enum, and every product using them maintains a `statusColors` map somewhere. **Linear**, **GitHub** and **Jira** all store the color on the status entity — the color is data, chosen by a human, persisted alongside the label.
 
-Pretui's bet is different: in a system where cards are authored quickly and a status field's values are whatever an author typed, there is no entity to hang a colour on and no one to choose it. A stable hash gives _consistency_ for free, which is the property that actually makes a list scannable — you learn "green-ish means In Review" within a page, and it stays true everywhere.
+Pretui's bet is different: in a system where cards are authored quickly and a status field's values are whatever an author typed, there is no entity to hang a color on and no one to choose it. A stable hash gives _consistency_ for free, which is the property that actually makes a list scannable — you learn "green-ish means In Review" within a page, and it stays true everywhere.
 
-Where that bet is better than the alternatives: zero configuration, zero drift, and it works for values the system has never seen. Where it is worse, and it is worth being blunt: **five buckets is a small palette**, collisions are frequent and invisible, and the colour will occasionally be actively misleading — a hash that paints "Cancelled" green is not a bug you can fix without the `@hue` escape. Neither Web Awesome nor Spectrum has that failure mode.
+Where that bet is better than the alternatives: zero configuration, zero drift, and it works for values the system has never seen. Where it is worse, and it is worth being blunt: **five buckets is a small palette**, collisions are frequent and invisible, and the color will occasionally be actively misleading — a hash that paints "Cancelled" green is not a bug you can fix without the `@hue` escape. Neither Web Awesome nor Spectrum has that failure mode.
 
-The pragmatic guidance: use StatusChip for open-ended categorical fields, and a `@tone` for anything where the colour is load-bearing.
+The pragmatic guidance: use StatusChip for open-ended categorical fields, and a `@tone` for anything where the color is load-bearing.
 
 ## Accessibility
 
@@ -34,8 +34,8 @@ No APG pattern; it is text with a background and carries no role — correct.
 
 Everything **Chip** says applies, and one thing more, which is the important one:
 
-- **Colour conveys nothing here, and that is a feature.** Because the hue is a hash, it is _not_ meaningful, so a user who cannot perceive it loses nothing that the label does not already carry. That makes StatusChip trivially **WCAG 1.4.1** compliant in a way that a semantic-colour chip is not — the label is always the message.
-- **Contrast does not depend on the hue.** The text is Chip's `--foreground` on `--muted` (or a tone's `-ink` on `--card`), at **11px, weight 500**; the hash hue only colors the dot, so no `--chart-*` value can make the label illegible.
+- **Color conveys nothing here, and that is a feature.** Because the hue is a hash, it is _not_ meaningful, so a user who cannot perceive it loses nothing that the label does not already carry. That makes StatusChip trivially **WCAG 1.4.1** compliant in a way that a semantic-color chip is not — the label is always the message.
+- **Contrast does not depend on the hue** (with Chip's legacy mix knobs unset). The text is Chip's `--foreground` on `--muted` (or a tone's `-ink` on `--card`), at **11px, weight 500**; the hash hue only colors the dot, so no `--chart-*` value can make the label illegible.
 - **The dot inherits from Chip and is on by default**, giving each hue a saturated anchor. Since the hues are arbitrary, the dot is doing less work here than it does on a semantic Chip — but it still helps distinguish adjacent chips whose fills are close.
 - **The chip has no relationship to the field it describes.** "In Review" announced next to a record name is loose text; put it in a **KeyValue** row or a **FormField** static block if the property name matters.
 - **No `aria-label` and no title.** The value is the visible text and the accessible text, which is right.
@@ -43,6 +43,6 @@ Everything **Chip** says applies, and one thing more, which is the important one
 
 ## Theming
 
-Inherits **Chip**'s entire token set; `--pretui-chip-hue` is set here from the hash.
+Inherits **Chip**'s entire token set; `--pretui-chip-hue` is set here from the hash on a neutral chip, or from `@hue`.
 
 The theme's `--chart-1` through `--chart-5` color the dots, and this component is the reason those five need to work as a _set_: they appear side by side in a list, assigned arbitrarily, so they must be mutually distinguishable as small dots on `--muted`.

From 91cc4d2830469ee4717ed49edfaaa46798f5848a Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Thu, 8 Oct 2026 15:44:26 -0400
Subject: [PATCH 18/30] Give Toast's message a contrast-safe ink and the
 title's size, and correct the Toast and Snackbar docs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/components/snackbar.md     |  4 ++--
 packages/pretui/components/toast.gts       | 12 +++++++++---
 packages/pretui/components/toast.md        | 10 +++++-----
 packages/pretui/components/toast.usage.gts |  3 ++-
 4 files changed, 18 insertions(+), 11 deletions(-)

diff --git a/packages/pretui/components/snackbar.md b/packages/pretui/components/snackbar.md
index 7a9b355c993..b70ed0e9f6d 100644
--- a/packages/pretui/components/snackbar.md
+++ b/packages/pretui/components/snackbar.md
@@ -18,11 +18,11 @@ Identical to Toast. Lifetime, placement and tone are not args here: they live on
 
 ## Accessibility
 
-Governing pattern: APG **Alert**. Toast hardcodes `role="status"` on the card and is its own live region, created with its content already in it, so a card that mounts complete is announced unreliably; there is no close control and no Escape handling. Render it inside a host that owns the region, the politeness and the dismiss — Toaster does all three — and keep `role="status"` on the region rather than the card.
+Governing pattern: APG **Alert**. Toast hardcodes `role="status"` on the card and is its own live region, created with its content already in it, so a card that mounts complete is announced unreliably; there is no close control and no Escape handling. Render it inside a host that owns the region, the politeness and the dismiss, and pass `role={{null}}` so the card isn't a second region. **Toaster** owns all three but draws its own item, so it is the alternative to Snackbar, not a place to put one.
 
 ## Theming
 
-`--popover` (surface), `--pretui-shadow-raised`, `--border`, `--foreground` (title), `--muted-foreground` (message), `--text-ui-md`. The 10px radius, padding, gap and 360px max width are fixed. A season must keep `--popover` distinct from the page background, since the only other separation is a shadow.
+Same as **Toast**; see its Theming.
 
 ## React ecosystem
 
diff --git a/packages/pretui/components/toast.gts b/packages/pretui/components/toast.gts
index 1d238dc4b24..c31d7deda04 100644
--- a/packages/pretui/components/toast.gts
+++ b/packages/pretui/components/toast.gts
@@ -15,7 +15,7 @@ export interface ToastSignature {
 }
 
 export const Toast: TemplateOnlyComponent<ToastSignature> = <template>
-  <div class='pretui-toast' role='status' data-test-pretui-toast ...attributes>
+  <div class='pretui-toast' role='status' ...attributes data-test-pretui-toast>
     {{#if (has-block 'icon')}}{{yield to='icon'}}{{/if}}
     <div class='pretui-toast-body'>
       <div class='pretui-toast-title'>{{@title}}</div>
@@ -58,9 +58,15 @@ export const Toast: TemplateOnlyComponent<ToastSignature> = <template>
       .pretui-toast-title {
         font-weight: 600;
       }
+      /* a softer ink than the title: --muted-foreground isn't a guaranteed
+         pair on --popover (4.2:1 in dark), a mix of the surface's own ink is */
       .pretui-toast-msg {
-        color: var(--muted-foreground);
-        font-size: var(--boxel-caption-font-size);
+        color: color-mix(
+          in oklch,
+          var(--popover-foreground) 75%,
+          var(--popover)
+        );
+        line-height: 1.4;
       }
       .pretui-toast-action {
         margin-inline-start: var(--boxel-sp-xs);
diff --git a/packages/pretui/components/toast.md b/packages/pretui/components/toast.md
index 8ad6ab1dd16..03962c7b897 100644
--- a/packages/pretui/components/toast.md
+++ b/packages/pretui/components/toast.md
@@ -6,7 +6,7 @@ A small raised card announcing that something just happened — saved, copied, f
 
 ```
 @title: string   (required)
-@message?
+@message?    (or @description, the Sonner / shadcn / Mantine name)
 <:icon>  <:action>
 ```
 
@@ -14,7 +14,7 @@ That is all. There is no `duration`, no `placement`, no `variant`, no close butt
 
 **The omissions are the design.** A toast stack is a host concern: it needs a single top-layer region, an ordering policy, a pause-on-hover rule, and one shared live region — and none of that belongs to a component that a card might render three of. Pretui ships the card here and the stack as **Toaster**, which draws its own item so the clock, roles and controls are one implementation. The upside is that a Toast composes into anything; the downside is that using it correctly requires you to build the parts that are hard.
 
-`width: max-content` with a 22.5rem cap (`--pretui-toast-max-w`) means a toast is as wide as its content and no wider, which is what makes a stack of them read as a column of distinct messages rather than a wall.
+`width: max-content` with a 22.5rem cap (`--pretui-toast-max-w`, set on the Toast itself) means a toast is as wide as its content and no wider, which is what makes a stack of them read as a column of distinct messages rather than a wall.
 
 ## Prior art
 
@@ -39,13 +39,13 @@ Governing pattern: APG **Alert** for the announcement, plus the live-region rule
 - **`<:icon>` content is not `aria-hidden` by the component**, so a decorative icon that emits a `<title>` will be read before the title text.
 - The title and message are plain text with no heading semantics — correct for a transient card.
 
-Practical guidance: render Toast inside a host-owned region that carries the live semantics, keep `role="status"` on the region rather than the card, and give anything actionable a persistent home as well.
+Practical guidance: **Toaster** does not render Toast; it draws its own item with its own live region, so don't put a Toast in Toaster's `<:toast>` block, which would nest one status region in another. In a host region of your own that carries the live semantics, pass `role={{null}}` so the card isn't a second region, and give anything actionable a persistent home as well.
 
 ## Theming
 
-`--popover` / `--popover-foreground` (surface and title), `--muted-foreground` (message), `--border` and `--shadow-md` (edge and lift), `--boxel-border-radius`, the `--boxel-sp-*` spacing scale, and `--boxel-font-size-xs` / `--boxel-caption-font-size` (title and message). `--pretui-toast-max-w` sets the width cap.
+`--popover` / `--popover-foreground` (surface and title), a 75% mix of `--popover-foreground` into `--popover` (message, so it holds contrast in both schemes), `--border` and `--shadow-md` (edge and lift), `--boxel-border-radius`, the `--boxel-sp-*` spacing scale, and `--boxel-font-size-xs` (title and message). `--pretui-toast-max-w` sets the width cap.
 
-Because the surface is `--popover` rather than `--card`, a toast matches **Menu** and **Popover** rather than **Panel** — the "floating above" vocabulary. A season must keep `--popover` distinct from the page background, since the only other separation is a shadow, and shadows disappear on dark surfaces.
+Because the surface is `--popover` rather than `--card`, a toast matches **Menu** and **Popover** rather than **Panel** — the "floating above" vocabulary. The edge is a 1px `--border` ring plus `--shadow-md`. A theme should keep `--popover` distinct from `--background`, since shadows fade on dark surfaces; the default light theme doesn't, so there the ring carries the edge.
 
 The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
 
diff --git a/packages/pretui/components/toast.usage.gts b/packages/pretui/components/toast.usage.gts
index f2e13910397..e986073a07e 100644
--- a/packages/pretui/components/toast.usage.gts
+++ b/packages/pretui/components/toast.usage.gts
@@ -8,7 +8,8 @@ import { Toast } from './toast';
 const ToastUsage: TemplateOnlyComponent = <template>
     <FreestyleUsage @name='Toast' @description='A brief in-flow status receipt. Positioning and lifetime belong to its host; title, message and action remain ordinary content.' @source='<Toast @title="Lot saved" @message="B-103 is ready for review">…</Toast>'>
       <:example><Toast @title='Lot saved' @message='B-103 is ready for review'><:icon><CheckIcon width='14' height='14' aria-hidden='true' /></:icon><:action><Button @tone='neutral' @appearance='plain'>Review</Button></:action></Toast></:example>
-      <:api as |Args|><Args.String @name='title' @value='Lot saved' /><Args.String @name='message' @value='B-103 is ready for review' /><Args.Yield @name='icon' /><Args.Yield @name='action' /></:api>
+      <:api as |Args|><Args.String @name='title' @value='Lot saved' /><Args.String @name='message' @value='B-103 is ready for review' /><Args.String @name='description' @description='Alias for message, the name Sonner, shadcn and Mantine use.' /><Args.Yield @name='icon' /><Args.Yield @name='action' /></:api>
+      <:cssVars as |Css|><Css.Basic @name='pretui-toast-max-w' @type='dimension' @description='The width cap; set it on the Toast itself.' @defaultValue='22.5rem' /></:cssVars>
     </FreestyleUsage>
   </template>;
 

From 109a8ae427627a34fb5f26c47b903335ab4a6f6b Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Thu, 8 Oct 2026 15:44:28 -0400
Subject: [PATCH 19/30] Put Token's sizes on the ladder with one growing line
 height, and tidy its docs and usage page

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/components/token.gts       | 19 +++++++++----------
 packages/pretui/components/token.md        |  8 ++++----
 packages/pretui/components/token.usage.gts |  5 +----
 3 files changed, 14 insertions(+), 18 deletions(-)

diff --git a/packages/pretui/components/token.gts b/packages/pretui/components/token.gts
index dfaa0943844..b8e183b57fc 100644
--- a/packages/pretui/components/token.gts
+++ b/packages/pretui/components/token.gts
@@ -157,7 +157,8 @@ export class Token extends Component<TokenSignature> {
           vertical-align: baseline;
           font-family: var(--font-mono);
           font-size: var(--pretui-token-font-size, var(--boxel-font-size-2xs));
-          line-height: 1.125rem;
+          /* 18px, matching Chip, until the text needs more */
+          line-height: max(1.125rem, 1.5em);
           padding: 0 var(--boxel-sp-2xs);
           border-radius: var(--boxel-border-radius-xs);
           background-color: var(--card);
@@ -166,24 +167,22 @@ export class Token extends Component<TokenSignature> {
           white-space: nowrap;
           font-variant-numeric: tabular-nums;
         }
-        /* size scale — the same steps as Button's @size */
+        /* size scale, the same steps as Autocomplete's; the ladder has no
+           step under 11px, so xs and s share it */
         .pretui-token[data-size='xs'] {
-          font-size: var(--pretui-size-xs, var(--text-ui-xs, 0.66rem));
+          font-size: var(--pretui-size-xs, var(--boxel-font-size-2xs));
         }
         .pretui-token[data-size='s'] {
-          font-size: var(--pretui-size-s, var(--text-ui-sm, 0.72rem));
+          font-size: var(--pretui-size-s, var(--boxel-font-size-2xs));
         }
         .pretui-token[data-size='m'] {
-          font-size: var(--pretui-size-m, var(--text-ui-md, 0.78rem));
-          line-height: 1.5;
+          font-size: var(--pretui-size-m, var(--boxel-font-size-xs));
         }
         .pretui-token[data-size='l'] {
-          font-size: var(--pretui-size-l, var(--text-ui-lg, 0.875rem));
-          line-height: 1.5;
+          font-size: var(--pretui-size-l, var(--boxel-font-size-sm));
         }
         .pretui-token[data-size='xl'] {
-          font-size: var(--pretui-size-xl, var(--text-ui-xl, 1rem));
-          line-height: 1.5;
+          font-size: var(--pretui-size-xl, var(--boxel-font-size));
         }
         .pretui-token[data-wrap] {
           white-space: normal;
diff --git a/packages/pretui/components/token.md b/packages/pretui/components/token.md
index 6c7ffe2e847..28dcaad6370 100644
--- a/packages/pretui/components/token.md
+++ b/packages/pretui/components/token.md
@@ -12,7 +12,7 @@ Element: HTMLElement (a <code>)
 
 **It renders `<code>`**, which is the correct element and is what makes it a Token rather than a styled span.
 
-**`@size`** takes the house scale `xs | s | m | l | xl` (and the `sm` / `md` / `lg` / `small` / `medium` / `large` aliases), the same steps and the same `--pretui-size-*` → `--text-ui-*` tokens as **Button**'s `@size`. Like Button's, it sets the font-size only; the padding, radius and margins stay as they are. It lands as `data-size` on the element. Without `@size`, or with `@size='default'` (as on Button, the component's own default), the size is `--boxel-font-size-2xs`; `--pretui-token-font-size` pins it to an exact value instead, such as `var(--boxel-font-size-xs)`. `@size` wins over that property.
+**`@size`** takes the house scale `xs | s | m | l | xl` (and the `sm` / `md` / `lg` / `small` / `medium` / `large` aliases), read from `--pretui-size-*`, falling back to the ladder: `--boxel-font-size-2xs` (xs and s), `-xs` (m), `-sm` (l) and `--boxel-font-size` (xl). It sets the font-size; the line box stays 18px until the text needs more (`max(1.125rem, 1.5em)`), and the padding, radius and margins stay as they are. It lands as `data-size` on the element. Without `@size`, or with `@size='default'` (as on Button, the component's own default), the size is `--boxel-font-size-2xs`; `--pretui-token-font-size` pins it to an exact value instead, such as `var(--boxel-font-size-xs)`. `@size` wins over that property.
 
 **`@hue` and a caller's `style` work together.** Glimmer lets a caller's `style` attribute replace a component's own, so `@hue` is also written as a single `--pretui-token-hue` property on top of whatever style the element ends up with, and written again if the caller's style changes later. The caller's own declarations are kept, and so is a property another modifier on the element sets, such as boxel-ui's `setCssVar`. If the caller's style sets `--pretui-token-hue` as well, `@hue` wins, and the hue the caller's style last set comes back when `@hue` is cleared, including when the caller rewrote its style to `@hue`'s own value. One rewrite is not told apart from another modifier's write: a caller style that sets the hue exactly as `@hue` wrote it and changes some other declaration (dropping a property another modifier set counts). Its hue is not taken as the caller's, so clearing `@hue` brings back the caller's earlier hue, or none. `@size` and `@wrap` are data attributes, so a caller's style cannot remove them.
 
@@ -20,7 +20,7 @@ Element: HTMLElement (a <code>)
 
 Two details worth knowing, both about how it behaves in context:
 
-**`margin-inline: 0.35ch`.** A mono pill dropped into proportional prose sits too tight against its neighbours because the pill's padding is inside the box. A third of a character on each side restores the word rhythm — and because it is `ch`, it scales with the surrounding type.
+**`margin-inline: 0.35ch`.** A mono pill dropped into proportional prose sits too tight against its neighbors because the pill's padding is inside the box. A third of a character on each side restores the word rhythm — and because it is `ch`, it scales with the surrounding type.
 
 **`:where(td, dd) > .pretui-token { margin-inline: 0 }`.** As a direct child of a table cell or a definition-list value, the margins go away so the pill aligns flush with the cell edge. The `:where()` keeps specificity at zero so a call site can override without a fight. This is a small thing that makes tables of ids look right without anyone thinking about it.
 
@@ -34,7 +34,7 @@ Nobody ships this as a component. **shadcn**, **Radix**, **Web Awesome** and **R
 
 So the comparison is against "a global `code { }` rule", and the improvements are specific:
 
-- **It is a component, so a season can retune every machine value in the product at once** rather than hunting for a global rule that some card overrode.
+- **It is a component, so a theme can retune every machine value in the product at once** rather than hunting for a global rule that some card overrode.
 - **`@hue` makes it tintable per instance**, which is what lets **FieldError**'s rule-id provenance, an error trace and a normal id look related but distinguishable.
 - **The context-aware margins** (above) — a global `code` rule cannot know it is in a table cell without the same `:where()` trick, and almost none do it.
 - **The size is a fixed small step** (`--boxel-font-size-2xs` by default), so the mono value sits at about the optical size of body text rather than the visually larger result you get from matching point sizes.
@@ -51,7 +51,7 @@ Notes and gaps:
 - **Long or opaque values are hostile to speech.** A UUID or a hash announced character by character is unusable, and announced as a word is meaningless. If a Token holds something a screen-reader user might need to transcribe, pair it with a **CopyButton** — that is the accessible affordance, not the text.
 - **`white-space: nowrap`** is the default, so a long value overflows its container rather than wrapping, which can push a card horizontally and fail **WCAG 1.4.10 Reflow** at 320px. This is the most likely practical problem: paths and URLs are exactly what people put in Tokens. Set `@wrap` wherever the value can be long.
 - **Contrast.** By default the text is `--card-foreground` on `--card`, the theme's own guaranteed pair. A `@hue` replaces the text color, so pass an ink (`--primary-ink`, `--muted-foreground`), not a pale fill hue, and check it at the size it is used (11px by default, smaller at `@size='xs'`).
-- **The hue carries no meaning** and there is no non-colour channel, so do not use `@hue` to encode state — use two components, or add text.
+- **The hue carries no meaning** and there is no non-color channel, so do not use `@hue` to encode state — use two components, or add text.
 - Nothing is focusable, correctly.
 
 ## Theming
diff --git a/packages/pretui/components/token.usage.gts b/packages/pretui/components/token.usage.gts
index 3f1da613f65..6737a15b4d0 100644
--- a/packages/pretui/components/token.usage.gts
+++ b/packages/pretui/components/token.usage.gts
@@ -20,7 +20,6 @@ const HUES = [
 ];
 
 class TokenUsage extends Component {
-  values = ['records@2.4.0', 'LOT-B-103', 'ctse/pretui'];
   @tracked value = 'records@2.4.0';
   @tracked size = BODY_SIZE;
   @tracked hue = DEFAULT_HUE;
@@ -68,7 +67,6 @@ class TokenUsage extends Component {
           <Token @value='ctse/pretui' />.</p>
       </:example>
       <:api as |Args|>
-        <Args.Object @name='sample values' @value={{this.values}} />
         <Args.String
           @name='value'
           @value={{this.value}}
@@ -79,7 +77,7 @@ class TokenUsage extends Component {
           @value={{this.size}}
           @options={{SIZES}}
           @defaultValue={{BODY_SIZE}}
-          @description='House scale xs|s|m|l|xl, the same steps as Button; sets the font-size only. Omitted, the size is --boxel-font-size-2xs, or --pretui-token-font-size when that is set (Pretui addition).'
+          @description='House scale xs|s|m|l|xl, the same steps as Button; sets the font-size, with the line box growing past 18px. Omitted, the size is --boxel-font-size-2xs, or --pretui-token-font-size when that is set (Pretui addition).'
           @onInput={{this.setSize}}
         />
         <Args.String
@@ -120,7 +118,6 @@ class TokenUsage extends Component {
     <style scoped>
       .foundation-prose {
         margin: 0;
-        color: var(--foreground);
       }
     </style>
   </template>

From fe7b1cc1a8aa6afc1af7da5e9a34e6a871d88c26 Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Thu, 8 Oct 2026 15:44:30 -0400
Subject: [PATCH 20/30] Make Viewport's width controls, stage settings and
 canvas behave in every mode, scroll the mode picker when narrow, and rewrite
 its docs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/components/viewport.gts | 65 +++++++++++++++++--------
 packages/pretui/components/viewport.md  | 33 +++++++------
 2 files changed, 63 insertions(+), 35 deletions(-)

diff --git a/packages/pretui/components/viewport.gts b/packages/pretui/components/viewport.gts
index 0122255f1ed..e352a42b16f 100644
--- a/packages/pretui/components/viewport.gts
+++ b/packages/pretui/components/viewport.gts
@@ -88,12 +88,14 @@ export class Viewport extends Component<ViewportSignature> {
     this.mode = v;
     this.customWidth = 0;
   };
+  // A free width belongs to Fill, so every preset click afterwards is a real
+  // change that resets it; snapped to the slider's 5px step so the slider
+  // can land on a dragged width.
   setWidth = (v: number) => {
-    this.customWidth = Math.round(Math.min(1600, Math.max(240, v)));
-    if (!this.isFramed) {
-      this.mode = 'fill';
-    }
+    this.customWidth = Math.round(Math.min(1600, Math.max(240, v)) / 5) * 5;
+    this.mode = 'fill';
   };
+  formatWidth = (v: number) => `${v} pixels`;
   setSurface = (v: string) => (this.surface = v);
   setGutter = (v: boolean) => (this.gutter = v);
   get isFramed() {
@@ -131,6 +133,7 @@ export class Viewport extends Component<ViewportSignature> {
     // user-select: none for the duration in case a selection was already
     // under way when the drag started.
     let down = (e: PointerEvent) => {
+      if (e.button !== 0) return;
       active = true;
       startX = e.clientX;
       startW = artboard?.getBoundingClientRect().width ?? 0;
@@ -161,9 +164,10 @@ export class Viewport extends Component<ViewportSignature> {
     };
   });
   <template>
-    <div class='pretui-viewport' data-test-pretui-viewport ...attributes>
+    <div class='pretui-viewport' ...attributes data-test-pretui-viewport>
       <div class='pretui-viewport-bar'>
         <SegmentedControl
+          class='pretui-viewport-modes'
           @label='Viewport mode'
           @options={{VIEWPORT_MODES}}
           @value={{this.mode}}
@@ -176,12 +180,14 @@ export class Viewport extends Component<ViewportSignature> {
               @options={{this.surfaces}}
               @value={{this.surface}}
               @onValueChange={{this.setSurface}}
+              @disabled={{isInline this.mode}}
             />
           </div>
           <label class='pretui-viewport-gutter'>
             <Switch
               @checked={{this.gutter}}
               @onCheckedChange={{this.setGutter}}
+              @disabled={{isInline this.mode}}
               data-test-pretui-viewport-gutter
             />
             <span>Padding</span>
@@ -194,13 +200,19 @@ export class Viewport extends Component<ViewportSignature> {
             @max={{1600}}
             @step={{5}}
             @label='Artboard width'
+            @formatValue={{this.formatWidth}}
             @onValueChange={{this.setWidth}}
           />
           <span class='pretui-viewport-readout'>{{this.widthLabel}}</span>
         </div>
       </div>
+      {{! wide artboards pan inside the canvas, so it takes a tab stop and a
+          name for keyboard users }}
       <div
         class='pretui-viewport-canvas'
+        tabindex='0'
+        role='region'
+        aria-label='Artboard canvas'
         data-mode={{this.mode}}
         data-width={{this.widthLabel}}
       >
@@ -266,6 +278,7 @@ export class Viewport extends Component<ViewportSignature> {
               <div
                 class='pretui-viewport-cell'
                 data-surface={{this.surface}}
+                data-gutter={{if this.gutter 'true' 'false'}}
                 data-test-pretui-viewport-specimen
               >{{yield}}</div>
             {{/each}}
@@ -320,6 +333,13 @@ export class Viewport extends Component<ViewportSignature> {
           padding: var(--boxel-sp-2xs) var(--boxel-sp-sm);
           box-shadow: inset 0 -1px 0 var(--border);
         }
+        /* seven segments outgrow a phone-width panel; the control scrolls on
+           its own rather than pushing the page sideways */
+        .pretui-viewport-modes {
+          max-width: 100%;
+          overflow-x: auto;
+          scrollbar-width: none;
+        }
         .pretui-viewport-width {
           display: flex;
           align-items: center;
@@ -346,14 +366,15 @@ export class Viewport extends Component<ViewportSignature> {
         }
         .pretui-viewport-surface {
           width: var(--pretui-viewport-surface-w);
-          font-size: var(--boxel-font-size-xs);
         }
         .pretui-viewport-gutter {
           display: inline-flex;
           align-items: center;
           gap: var(--boxel-sp-2xs);
-          font-size: var(--boxel-font-size-xs);
-          font-weight: 500;
+          font-size: var(--boxel-ui-label-font-size);
+          font-weight: var(--boxel-ui-label-font-weight);
+          line-height: var(--boxel-ui-label-line-height);
+          letter-spacing: var(--boxel-ui-label-letter-spacing);
           color: var(--muted-foreground);
           white-space: nowrap;
           cursor: pointer;
@@ -391,12 +412,14 @@ export class Viewport extends Component<ViewportSignature> {
           inset-inline-start: 0;
           font-family: var(--font-mono);
           font-size: var(--boxel-font-size-2xs);
-          letter-spacing: 0.02em;
+          letter-spacing: var(--boxel-lsp-sm);
           color: var(--primary-ink);
           white-space: nowrap;
         }
-        .pretui-artboard-body {
-          /* R2: a neutral stage — normal block flow, no centering opinion */
+        /* a neutral stage, normal block flow with no centering opinion; grid
+           cells share its surfaces */
+        .pretui-artboard-body,
+        .pretui-viewport-cell {
           min-height: var(--pretui-artboard-min-h);
           border-radius: var(--boxel-border-radius-sm);
           box-shadow: 0 0 0 1px var(--border);
@@ -404,23 +427,28 @@ export class Viewport extends Component<ViewportSignature> {
         .pretui-artboard-body[data-gutter='true'] {
           padding: var(--boxel-sp);
         }
-        .pretui-artboard-body[data-surface='background'] {
+        .pretui-artboard-body[data-surface='background'],
+        .pretui-viewport-cell[data-surface='background'] {
           /* a veil of the page color over the dot floor, so the stage reads as
              an area while the specimen still sits on the page background */
           background-color: var(--pretui-viewport-veil);
         }
-        .pretui-artboard-body[data-surface='card'] {
+        .pretui-artboard-body[data-surface='card'],
+        .pretui-viewport-cell[data-surface='card'] {
           background-color: var(--card);
+          color: var(--card-foreground);
           box-shadow:
             0 0 0 1px var(--border),
             var(--shadow-sm);
         }
-        .pretui-artboard-body[data-surface='sidebar'] {
+        .pretui-artboard-body[data-surface='sidebar'],
+        .pretui-viewport-cell[data-surface='sidebar'] {
           background-color: var(--sidebar);
           color: var(--sidebar-foreground);
           box-shadow: 0 0 0 1px var(--sidebar-border);
         }
-        .pretui-artboard-body[data-surface='inset'] {
+        .pretui-artboard-body[data-surface='inset'],
+        .pretui-viewport-cell[data-surface='inset'] {
           background-color: var(--inset);
           box-shadow: inset 0 0 0 1px var(--border);
         }
@@ -480,12 +508,11 @@ export class Viewport extends Component<ViewportSignature> {
           justify-content: center;
           gap: var(--boxel-sp-xs);
           flex-wrap: wrap;
-          background-color: var(--background);
-          border-radius: var(--boxel-border-radius-sm);
-          box-shadow: 0 0 0 1px var(--border);
-          padding: var(--boxel-sp-sm);
           min-height: var(--pretui-viewport-cell-min-h);
         }
+        .pretui-viewport-cell[data-gutter='true'] {
+          padding: var(--boxel-sp-sm);
+        }
       }
     </style>
   </template>
diff --git a/packages/pretui/components/viewport.md b/packages/pretui/components/viewport.md
index 1f08db8f487..425466a660e 100644
--- a/packages/pretui/components/viewport.md
+++ b/packages/pretui/components/viewport.md
@@ -1,24 +1,27 @@
 ## What it is
 
-The artboard: a framed stage that renders its content at a chosen device width, with a caption stating the real width. Use it around any example that needs to be seen at a size other than the page's — every **FreestyleUsage** example sits in one. If you just need a bounded box, plain CSS is enough; Viewport is for _comparing_ a component across widths.
+The artboard: a framed stage that renders its content at a chosen device width, with a caption stating its width. Use it around any example that needs to be seen at a size other than the page's — every **FreestyleUsage** example sits in one. If you just need a bounded box, plain CSS is enough; Viewport is for _comparing_ a component across widths.
 
 ## The contract
 
 ```
-@defaultMode? 'fill' | 'phone' | 'tablet' | 'desktop' | 'bp' | 'inline' | 'grid' | 'narrow' | 'wide'
+@defaultMode? 'fill' | 'phone' | 'tablet' | 'desktop' | 'bp' | 'inline' | 'grid'
+              ('narrow' and 'wide' are kept as aliases for 'phone' and 'desktop')
 @label?   — the specimen's name, captioning a dragged width as "Name · <width>"; presets are captioned by mode
 <:default>
 ```
 
 **True widths that pan rather than clamp.** A `phone` artboard is genuinely 320px wide and the stage scrolls horizontally to show it, rather than scaling the content down or clamping to the available space. That is the difference between an artboard and a resized div: a clamped preview lies about what the component does at that width, and a scaled one lies about its type size.
 
-**`bp` is a 3-up mode** — three breakpoints side by side, which is how you actually check a responsive component.
+**`bp` is a 3-up mode** — three breakpoints side by side, which is how you actually check a responsive component. **`inline`** sets the specimen inside a line of running text, to judge it mid-paragraph. **`grid`** repeats it in six cells, for density.
 
-**The caption is live**: `"Phone · 320px"` for a preset and `"Name · 412px"` once you drag, updating as the drag handle moves. An artboard whose label does not track its real width is worse than no label, because it invites you to trust it.
+**The stage** takes one of four surfaces (Background, a translucent veil of the page color; Card; Sidebar; Inset) and an optional Padding. Both apply to the framed modes and the grid cells; Inline sits in prose, so the two controls are disabled there.
 
-**The drag handle uses pointer capture, not document listeners.** Same discipline as **Popover**'s backdrop and **SplitPanes**' handle: the element's lifetime is the interaction's lifetime, so there is nothing to leak and nothing to remove on teardown.
+**The caption is live**: `"Phone · 320px"` for a preset, `"Fill · 100%"` for the full width, and `"Name · 412px"` once you drag or use the width slider, updating as it moves. A dragged width belongs to Fill, so clicking a preset afterwards always resets it. An artboard whose label does not track its real width is worse than no label, because it invites you to trust it.
 
-State is reflected as `data-*`, so a season or a test can read the current mode.
+**The drag handle uses pointer capture, not document listeners.** Same discipline as **Popover**'s backdrop and **SplitPanes**' handle: the listeners live on the handle, so teardown only unbinds them and clears the resize flag. Only the primary button starts a drag.
+
+State is reflected as `data-*`, so a theme or a test can read the current mode.
 
 ## Prior art
 
@@ -37,19 +40,17 @@ Where it is thinner: no device chrome, no orientation toggle, no zoom, and no de
 
 No pattern governs it; it is a tool, and the criteria are WCAG **2.1.1 Keyboard**, **2.5.7 Dragging Movements** and **1.4.10 Reflow**.
 
-Gaps, and the first two are the ones that matter for a tool:
-
-- **The drag handle needs a keyboard path.** A width control operated only by dragging is a **WCAG 2.1.1** failure and, separately, a **2.5.7 Dragging Movements** failure — 2.5.7 specifically requires a single-pointer alternative, which keyboard support does _not_ satisfy. The mode presets are the pointer alternative for the common cases, so 2.5.7 is arguably met; arrow keys on a focused handle would close 2.1.1. Verify whether the handle is focusable at all.
-- **The handle should be `role="separator"` with `aria-valuenow`/`min`/`max` and an accessible name** — the same contract **SplitPanes**' divider needs, and the same one to check.
-- **The live caption is not a live region**, so a screen-reader user dragging (or arrowing) the handle gets no width feedback. Since the caption exists and is already updating, wrapping it in `role="status"` is nearly free — though it would then chatter during a drag, so `aria-valuenow` on the handle is the better channel.
-- **The panning stage needs `tabindex="0"`** if it scrolls horizontally, or a keyboard-only user cannot pan a `desktop` artboard inside a narrow page.
-- **Mode presets are presumably a SegmentedControl**, which in this kit carries `role="tablist"` over children with no `role="tab"` — see that component's note. The mode choice may be announced as an unstructured group of buttons.
-- **The framed content is arbitrary**, so anything inside keeps its own tab order — which means tabbing through a 3-up view traverses three copies of the same component. That is expected for a tool and worth knowing.
+- **The width slider is the keyboard path.** The drag handle is a redundant pointer target, hidden from assistive tech and not focusable; the **Slider** beside it sets the same width with the arrow keys (5px steps), Page Up/Down and Home/End, and announces it as "N pixels". The presets and a click on the slider track are the single-pointer alternatives 2.5.7 asks for.
+- **The canvas is a named region with a tab stop** ("Artboard canvas"), so a keyboard user can pan a `desktop` or 3-up artboard that is wider than the page.
+- **The mode picker is a SegmentedControl** (a radiogroup named "Viewport mode"). In a panel narrower than its seven segments it scrolls on its own instead of widening the page.
+- **In Fill, 3-up, Inline and Grid the slider reads its 240px minimum**, since those modes have no single fixed width to report.
+- **The live caption is not a live region**, so dragging gives a screen-reader user no width feedback; the slider's announced value is the channel.
+- **The framed content is arbitrary**, so anything inside keeps its own tab order: tabbing through a 3-up view traverses three copies of the component, and Grid six. That is expected for a tool and worth knowing.
 
 ## Theming
 
-Stage surfaces (`--background`, `--card`, `--inset`, and `--sidebar` / `--sidebar-foreground` / `--sidebar-border`), `--border` for frames and the canvas dots, `--shadow-sm` on the card surface, `--border-strong` for the resize grip, `--primary-ink` for the artboard caption and the hovered grip, `--muted-foreground` for the width readout and the Padding label, a translucent `--background` veil over the dot floor on the Background surface, and **SegmentedControl**'s tokens for the mode picker.
+Stage surfaces (`--background`, `--card`, `--inset`, and `--sidebar` / `--sidebar-foreground` / `--sidebar-border`), `--border` for frames and the canvas dots, `--shadow-sm` on the card surface, `--border-strong` for the resize grip, `--primary-ink` for the artboard caption and the hovered grip, `--muted-foreground` for the width readout and the Padding label, a translucent `--background` veil over the dot floor on the Background surface, and and the tokens of the **SegmentedControl**, **Select**, **Switch** and **Slider** in the toolbar.
 
-**The stage is deliberately neutral** with explicit surface and gutter settings, because an artboard that shares the page's background makes the framed component's own surface invisible. A season must keep the stage distinguishable from `--card` — otherwise every example appears to float in nothing, which is exactly the illusion an artboard exists to prevent.
+**The stage is deliberately neutral** with explicit surface and padding settings, because an artboard that shares the page's background makes the framed component's own surface invisible. A theme must keep the stage distinguishable from `--card` — otherwise every example appears to float in nothing, which is exactly the illusion an artboard exists to prevent.
 
 The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.

From 13ab133e7e9a5eae6b0749e96314271378dbcfe5 Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Thu, 8 Oct 2026 15:44:32 -0400
Subject: [PATCH 21/30] Label each property knob with its row, announce
 required arguments, head API rows by name, and correct the usage docs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/components/table.gts          |  5 ++-
 packages/pretui/components/usage-argument.gts | 19 +++++-----
 packages/pretui/components/usage-argument.md  | 16 ++++-----
 .../pretui/components/usage-argument.test.gts |  7 ++--
 .../components/usage-css-variable.test.gts    |  2 +-
 packages/pretui/components/usage-number.gts   | 23 +++++++++---
 packages/pretui/components/usage-number.md    | 14 ++++----
 packages/pretui/components/usage-object.gts   | 21 -----------
 packages/pretui/components/usage-object.md    | 16 ++++-----
 .../pretui/components/usage-object.test.gts   |  6 ++--
 packages/pretui/components/usage-string.gts   | 16 +++++++--
 packages/pretui/components/usage-string.md    |  8 ++---
 packages/pretui/freestyle-controls.test.gts   | 15 ++++++--
 packages/pretui/internal/freestyle.gts        | 36 +++++++++++++++----
 14 files changed, 116 insertions(+), 88 deletions(-)

diff --git a/packages/pretui/components/table.gts b/packages/pretui/components/table.gts
index 6d8f8d03fc2..9ae8b53afc3 100644
--- a/packages/pretui/components/table.gts
+++ b/packages/pretui/components/table.gts
@@ -134,9 +134,8 @@ export const Table: TemplateOnlyComponent<TableSignature> = <template>
       .pretui-table :deep(tbody tr:last-child th) {
         box-shadow: none;
       }
-      /* Kept off td: at this specificity it would beat a caller's own td
-         alignment in the same layer, such as UsageArgument's right-aligned
-         Default column. */
+      /* Kept off td: at this specificity it would beat a layered caller's
+         own cell alignment, such as a right-aligned number column. */
       .pretui-table :deep(tbody th) {
         text-align: start;
       }
diff --git a/packages/pretui/components/usage-argument.gts b/packages/pretui/components/usage-argument.gts
index c79b2c8a435..6b8086ecb82 100644
--- a/packages/pretui/components/usage-argument.gts
+++ b/packages/pretui/components/usage-argument.gts
@@ -1,6 +1,7 @@
 // Pretui — UsageArgument: one documented argument row (doc lens: table row; prop lens: nothing).
 import Component from '@glimmer/component';
-import { isPresent } from '../internal/freestyle';
+import { VisuallyHidden } from './visually-hidden';
+import { isPresent, readOnlyText } from '../internal/freestyle';
 import type { ArgsMode } from '../internal/freestyle';
 
 // ── Freestyle::Usage::Argument (doc lens: table row; prop lens: nothing) ──
@@ -31,7 +32,7 @@ export class UsageArgument extends Component<UsageArgumentSignature> {
     return isPresent(this.args.defaultValue);
   }
   get defaultText() {
-    return String(this.args.defaultValue);
+    return readOnlyText(this.args.defaultValue);
   }
   // yields print as {{name}}, css vars bare (names carry --), args as @name
   get sigilPre() {
@@ -45,16 +46,17 @@ export class UsageArgument extends Component<UsageArgumentSignature> {
   <template>
     {{#if this.isDoc}}
       <tr class='pretui-usage-arg' data-test-pretui-usage-arg>
-        <td class='pretui-usage-arg-name'>
+        {{! the name heads the row, so each cell is announced with it }}
+        <th scope='row' class='pretui-usage-arg-name'>
           <span class='u-sig'>{{this.sigilPre}}</span>{{#if
             @name
           }}{{@name}}{{/if}}<span class='u-sig'>{{this.sigilPost}}</span>
           {{#if @required}}<span
               class='u-req'
-              title='Required'
+              aria-hidden='true'
               data-test-pretui-usage-arg-required
-            >*</span>{{/if}}
-        </td>
+            >*</span><VisuallyHidden>(required)</VisuallyHidden>{{/if}}
+        </th>
         <td class='pretui-usage-arg-type'>{{this.typeLabel}}</td>
         <td><span
             class='pretui-usage-arg-description-text'
@@ -74,7 +76,7 @@ export class UsageArgument extends Component<UsageArgumentSignature> {
       }
       .pretui-usage-arg-name {
         font-family: var(--font-mono);
-        font-size: var(--boxel-font-size-xs);
+        font-weight: inherit;
         white-space: nowrap;
         width: 1%;
       }
@@ -86,11 +88,9 @@ export class UsageArgument extends Component<UsageArgumentSignature> {
       }
       .pretui-usage-arg-type {
         font-family: var(--font-mono);
-        font-size: var(--boxel-font-size-xs);
         color: var(--muted-foreground);
         white-space: nowrap;
         width: 1%;
-        text-transform: lowercase;
       }
       /* on a span: table layout ignores max-width on a cell */
       .pretui-usage-arg-description-text {
@@ -99,7 +99,6 @@ export class UsageArgument extends Component<UsageArgumentSignature> {
       }
       .pretui-usage-arg-default {
         font-family: var(--font-mono);
-        font-size: var(--boxel-font-size-xs);
         color: var(--muted-foreground);
         text-align: end;
         white-space: nowrap;
diff --git a/packages/pretui/components/usage-argument.md b/packages/pretui/components/usage-argument.md
index 4a583673a45..8ba7c06c5f1 100644
--- a/packages/pretui/components/usage-argument.md
+++ b/packages/pretui/components/usage-argument.md
@@ -7,8 +7,8 @@ The base argument row of a **FreestyleUsage** page — `Args.Base` in the yielde
 ```
 @mode? 'doc' | 'prop'   (default 'doc')
 @name?, @type?, @typeLabel?, @description?, @defaultValue?
-@required?, @optional?, @hideControls?
-<:default>
+@required?, @hideControls?
+@optional?   — accepted for ember-freestyle parity; it renders nothing
 ```
 
 **`@mode` is the lens, and it is the architecture of the whole family.** A usage page authors its `<:api>` block **once**; `FreestyleUsage` renders it twice — as a right-hand **property list** (`prop`) and as an **API table** (`doc`) below. Every Usage component therefore knows both presentations. **`UsageArgument` renders a table row in `doc` and nothing at all in `prop`**, because there is no control to show. That asymmetry is what makes the dual-lens trick work: components with knobs appear in both, components without appear only in the docs.
@@ -33,16 +33,12 @@ No pattern governs it; it is a table row in one lens and nothing in the other.
 
 Gaps, and most belong to the page rather than the row:
 
-- **The `doc` lens renders into `Table`**, so it inherits that component's contract — real `<th>`/`<td>` markup, and everything **Table**'s note says: no `scope`, no caption, no `aria-sort`, all supplied by the caller. Here the caller is **FreestyleUsage**, so the API table's header semantics are its responsibility to get right.
-- **The required marker** (`@required` / `@optional`) must reach the accessible name of the row, not just render an asterisk. **FormField** in this kit made exactly that fix — a visually-hidden "(required)" inside the label — and a docs table has the same obligation.
-- **The sigil is decorative typography carrying meaning.** `{{name}}` versus `@name` versus a bare token name is a real distinction, conveyed by punctuation that screen readers announce inconsistently (or spell out). The `@type` value is presumably in its own column, which mitigates it.
+- **The name heads its row** (`<th scope="row">`), so each Type, Description and Default cell is announced with the argument it describes. The table itself is named by its section heading in **FreestyleUsage**.
+- **The required marker** is a visual asterisk hidden from assistive tech, with a visually hidden "(required)" beside it, the same fix **FormField** made.
+- **The sigil is decorative typography carrying meaning.** `{{name}}` versus `@name` versus a bare token name is a real distinction, conveyed by punctuation that screen readers announce inconsistently (or spell out). The type is in the Type column, which mitigates it.
 - **`@description` is prose in a table cell**, so it is announced only when the reader traverses to that cell — which is correct for a table and means the description is not part of the argument's name.
 - **The `prop` lens renders nothing**, so an argument documented with `Base` is invisible in the property list. That is intended; it does mean a reader working from the knobs alone will not know the argument exists.
 
 ## Theming
 
-**Table**'s tokens for the row (`--card`, `--border`, `--stripe`, `--hover`, the mono eyebrow header voice) plus **Token**'s treatment for the type and default value, and `--muted-foreground` for the description.
-
-Nothing of its own. The type and default cells should use the mono voice — machine values as jewelry, Law 3 — so a reader can distinguish `'md'` the default from _md_ the prose.
-
-The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+**Table**'s tokens for the row (`--card` with `--card-foreground`, `--border`, `--stripe`, `--hover`, the label role in the header). The name, type and default cells are set in `--font-mono`, with the type, default and sigils in `--muted-foreground`, so a reader can tell `'md'` the default from _md_ the prose; the asterisk is `--destructive-ink`. The description takes the row's ink and stops at `--pretui-usage-arg-description-max-w` (32.5rem), a local measure.
diff --git a/packages/pretui/components/usage-argument.test.gts b/packages/pretui/components/usage-argument.test.gts
index fb702854f2f..49e1ce5f6d6 100644
--- a/packages/pretui/components/usage-argument.test.gts
+++ b/packages/pretui/components/usage-argument.test.gts
@@ -9,7 +9,7 @@ import { setupCardTest } from '@cardstack/host/tests/helpers';
 import { UsageArgument } from './usage-argument';
 
 function cellTexts(): string[] {
-  return Array.from(document.querySelectorAll('[data-test-pretui-usage-arg] td')).map((td) => td.textContent?.replace(/\s+/g, ' ').trim() ?? '');
+  return Array.from(document.querySelectorAll('[data-test-pretui-usage-arg] :is(th, td)')).map((td) => td.textContent?.replace(/\s+/g, ' ').trim() ?? '');
 }
 
 module('Pretui | components/usage-argument', function (hooks) {
@@ -18,13 +18,14 @@ module('Pretui | components/usage-argument', function (hooks) {
   test('doc mode is one API-table row: sigil + name, type, description, default', async function (assert) {
     await render(<template><table><tbody><UsageArgument @name='variant' @type='String' @description='Visual weight' @defaultValue='primary' /></tbody></table></template>);
     assert.deepEqual(cellTexts(), ['@variant', 'String', 'Visual weight', 'primary']);
+    assert.strictEqual(document.querySelector('[data-test-pretui-usage-arg] th')?.getAttribute('scope'), 'row', 'the name heads its row');
     assert.strictEqual(document.querySelector('[data-test-pretui-usage-arg-required]'), null);
   });
 
   test('a missing default reads as a dash, required adds the asterisk, and typeLabel overrides type', async function (assert) {
     await render(<template><table><tbody><UsageArgument @name='items' @type='Array' @typeLabel='Item[]' @required={{true}} /></tbody></table></template>);
-    assert.deepEqual(cellTexts(), ['@items *', 'Item[]', '', '—']);
-    assert.strictEqual(document.querySelector('[data-test-pretui-usage-arg-required]')?.getAttribute('title'), 'Required');
+    assert.deepEqual(cellTexts(), ['@items * (required)', 'Item[]', '', '—']);
+    assert.strictEqual(document.querySelector('[data-test-pretui-usage-arg-required]')?.getAttribute('aria-hidden'), 'true', 'the asterisk is visual; "(required)" is the text a screen reader hears');
     await render(<template><table><tbody><UsageArgument @name='count' @type='Number' @defaultValue={{0}} /></tbody></table></template>);
     assert.strictEqual(cellTexts()[3], '0', 'zero is a real default, not a missing one');
   });
diff --git a/packages/pretui/components/usage-css-variable.test.gts b/packages/pretui/components/usage-css-variable.test.gts
index c4894fcfdd1..fa0659b6b94 100644
--- a/packages/pretui/components/usage-css-variable.test.gts
+++ b/packages/pretui/components/usage-css-variable.test.gts
@@ -13,7 +13,7 @@ module('Pretui | components/usage-css-variable', function (hooks) {
 
   test('doc mode is an API row typed CSS with no sigil', async function (assert) {
     await render(<template><table><tbody><UsageCssVariable @name='--pretui-gap' @description='Grid gutter' @defaultValue='8px' /></tbody></table></template>);
-    let cells = Array.from(document.querySelectorAll('[data-test-pretui-usage-arg] td')).map((td) => td.textContent?.replace(/\s+/g, ' ').trim());
+    let cells = Array.from(document.querySelectorAll('[data-test-pretui-usage-arg] :is(th, td)')).map((td) => td.textContent?.replace(/\s+/g, ' ').trim());
     assert.deepEqual(cells, ['--pretui-gap', 'CSS', 'Grid gutter', '8px']);
   });
 
diff --git a/packages/pretui/components/usage-number.gts b/packages/pretui/components/usage-number.gts
index b39ff4a71a1..beed6c5b058 100644
--- a/packages/pretui/components/usage-number.gts
+++ b/packages/pretui/components/usage-number.gts
@@ -1,5 +1,6 @@
 // Pretui — UsageNumber: a number argument with its knob.
 import Component from '@glimmer/component';
+import { guidFor } from '@ember/object/internals';
 import { Input } from './input';
 import { Slider } from './slider';
 import { UsageArgument } from './usage-argument';
@@ -44,6 +45,13 @@ export class UsageNumber extends Component<UsageNumberSignature> {
   get textValue() {
     return this.args.value == null ? undefined : String(this.args.value);
   }
+  controlId = `${guidFor(this)}-control`;
+  // the rail labels the text field; Slider names itself with @label
+  get labelFor() {
+    return this.hasControl && !this.shouldRenderRangeInput
+      ? this.controlId
+      : undefined;
+  }
   onSlide = (v: number) => {
     this.args.onInput?.(v);
   };
@@ -53,10 +61,14 @@ export class UsageNumber extends Component<UsageNumberSignature> {
   <template>
     {{#if this.isProp}}
       {{#unless @hideControls}}
-        <PropRow @label={{@name}} @required={{@required}}>
+        <PropRow
+          @label={{@name}}
+          @required={{@required}}
+          @controlId={{this.labelFor}}
+        >
           {{#if this.hasControl}}
             {{#if this.shouldRenderRangeInput}}
-              <span class='numrange'>
+              <div class='numrange'>
                 <Slider
                   @value={{this.numValue}}
                   @min={{@min}}
@@ -66,13 +78,16 @@ export class UsageNumber extends Component<UsageNumberSignature> {
                   @onValueChange={{this.onSlide}}
                 />
                 <span class='numrange-readout'>{{@value}}</span>
-              </span>
+              </div>
             {{else}}
               <Input
                 @type='number'
                 @value={{this.textValue}}
                 @onInput={{this.onText}}
-                aria-label={{@name}}
+                @controlId={{this.controlId}}
+                min={{@min}}
+                max={{@max}}
+                step={{@step}}
               />
             {{/if}}
           {{else}}
diff --git a/packages/pretui/components/usage-number.md b/packages/pretui/components/usage-number.md
index 4d79d29b660..fb224472643 100644
--- a/packages/pretui/components/usage-number.md
+++ b/packages/pretui/components/usage-number.md
@@ -34,17 +34,15 @@ No pattern of its own; it renders a **Slider** or an **Input** plus a table row,
 
 Gaps, and two are inherited and consequential in this context:
 
-- **Slider's `aria-label` defaults to the literal `'Slider'`** and it accepts no `@controlId`, so **Field**-style `<label for>` wiring is not available to it at all. A property list of numeric knobs can therefore end up as several controls all announced "Slider". This is an API hole in **Slider** that shows up first here.
-- **Slider sets no `aria-valuetext`**, so a knob announces "8" where "8 pixels" is meant — and a usage page is precisely where the unit matters, because the reader is learning what the argument does.
-- **Slider styles only `::-webkit-slider-thumb`**, so in Firefox the thumb falls back to the UA default. On a documentation page that is visible on every numeric knob.
+- **The number field is labeled by the rail.** Without bounds the knob is an **Input**, and the property row's label is its `<label for>`, so clicking the name focuses the field; `@min`, `@max` and `@step` reach the field too.
+- **The slider names itself.** With both bounds it is a **Slider**, which takes no `@controlId`, so it is named by `@label` (the argument name) and the rail stays plain text.
+- **No unit is announced.** Slider supports `@formatValue` for `aria-valuetext`, but UsageNumber has no unit argument to pass, so a knob announces "8" where "8 pixels" is meant.
 - **Changing a knob re-renders the example silently** — no live region, no confirmation.
-- **`@required` must reach the accessible name** in the docs lens rather than only rendering an asterisk.
+- **`@required`** adds a visually hidden "(required)" beside the asterisk, in the property row and the doc row.
 - **`null` versus `0`** is not distinguishable in the control's announcement; an unset numeric argument and one explicitly set to zero read the same.
 
 ## Theming
 
-**Slider**'s tokens (`--primary` for the filled track, `--line-strong` for the remainder and the thumb hairline, `--card` for the thumb, `--shadow-ink-mid`, `--font-mono` and `--ink-3` for tick labels) or **Input**'s, plus **Table**'s for the doc row and the property rail's label voice.
+**Slider**'s or **Input**'s tokens for the control, **Table**'s for the doc row, and the property rail's mono label in `--muted-foreground`. The readout beside a slider is mono at a fixed minimum width (`--numrange-readout-min-w`), so the slider doesn't shift as the value changes.
 
-Nothing of its own. Check Slider's thumb against `--line-strong` per season — a property list shows sliders at several positions at once, and a thumb that disappears at either end of the track makes the knob unreadable exactly where the bounds are being demonstrated.
-
-The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+A property list shows sliders at several positions at once, so a thumb that disappears at either end of the track makes the knob unreadable exactly where the bounds are being demonstrated; check the thumb against the track in both schemes.
diff --git a/packages/pretui/components/usage-object.gts b/packages/pretui/components/usage-object.gts
index 24dc9efb9c3..6967861b5da 100644
--- a/packages/pretui/components/usage-object.gts
+++ b/packages/pretui/components/usage-object.gts
@@ -5,13 +5,6 @@ import { UsageArgument } from './usage-argument';
 import { PropRow } from '../internal/freestyle';
 import type { ArgsMode } from '../internal/freestyle';
 
-function stringify(v: unknown): string {
-  try {
-    return JSON.stringify(v, null, 2) ?? String(v);
-  } catch {
-    return String(v);
-  }
-}
 // ── Freestyle::Usage::Object (read-only) ─────────────────────────────────
 export interface UsageObjectSignature {
   Args: {
@@ -31,23 +24,10 @@ export class UsageObject extends Component<UsageObjectSignature> {
   get isProp() {
     return this.args.mode === 'prop';
   }
-  get json() {
-    return stringify(this.args.value);
-  }
   <template>
     {{#if this.isProp}}
       {{#unless @hideControls}}
         <PropRow @label={{@name}} @required={{@required}}>
-          {{!-- Adopted 2026-08-13: this was a plain <pre> of the stringified
-                value. JsonTree gives every Args.Object knob in the gallery
-                collapsible nodes, type badges, copy-path and keyboard
-                navigation — and an empty state instead of the literal text
-                "undefined" for the call sites that pass no @value.
-                The json getter is kept: it is the only caller of stringify.
-                NOTE the long-form comment delimiters. A short {{! }} comment
-                ends at its first closing pair, so a mustache inside one
-                escapes into the template and orphans the next closing tag —
-                local parse accepts it; the realm transpiler does not. --}}
           <JsonTree
             @value={{@value}}
             @label={{@name}}
@@ -72,7 +52,6 @@ export class UsageObject extends Component<UsageObjectSignature> {
       .jsonviewer {
         --pretui-json-max-height: 7.5rem;
         --pretui-json-indent: var(--boxel-sp-sm);
-        --pretui-json-row-height: 1.25rem;
       }
     </style>
   </template>
diff --git a/packages/pretui/components/usage-object.md b/packages/pretui/components/usage-object.md
index c8d87f98901..4d7bde1d34a 100644
--- a/packages/pretui/components/usage-object.md
+++ b/packages/pretui/components/usage-object.md
@@ -12,7 +12,7 @@ The object argument row of a **FreestyleUsage** page — `Args.Object`. Docs len
 
 **Note what is absent: there is no input callback.** Every other typed knob in the family round-trips a value; this one **displays** and does not edit. That is the honest boundary — a generic structured editor is a component in its own right, and inventing a half one inside a documentation row would produce a knob that can corrupt the example it is demonstrating.
 
-**`@value` is `unknown`**, the widest type in the family, and the component leans on `JsonTree` to render it. The module's `stringify` helper wraps `JSON.stringify` in a `try`/`catch` falling back to `String(v)`, so a circular structure or a value with a throwing `toJSON` degrades to something printable rather than breaking the page.
+**`@value` is `unknown`**, the widest type in the family, and goes straight to `JsonTree`, which takes plain JSON-safe data. A circular structure is not handled.
 
 **`@mode` is the lens.** The `<:api>` block is authored once and rendered twice — property list (`prop`) and API table (`doc`).
 
@@ -24,9 +24,9 @@ This is where **the kit's most common array argument lands**: an options list of
 
 **Storybook's `object` control** is the analogue and it _does_ edit — a JSON textarea that parses on change, plus a tree view. That is more capability and it is genuinely useful for exploring a data-driven component; it is also the control most likely to leave a story in a broken state after a typo, which is presumably why the port stopped short.
 
-Where the Pretui version is better: **a real tree view rather than a blob of JSON text.** `JsonTree` gives collapsible nodes, so a reader inspecting a fifty-row options array sees its shape rather than scrolling a wall. Storybook's editing textarea makes you read the raw serialisation.
+Where the Pretui version is better: **a real tree view rather than a blob of JSON text.** `JsonTree` gives collapsible nodes, so a reader inspecting a fifty-row options array sees its shape rather than scrolling a wall. Storybook's editing textarea makes you read the raw serialization.
 
-Where it is behind: no editing (above), no copy affordance on the tree (**CopyButton** is right there in the same file, used for `@source`), and no path display — a reader who wants to know how to reach a nested value has to count.
+Where it is behind: no editing (above). `JsonTree` rows do copy their path and value from the keyboard (Ctrl/Cmd+Shift+C and Ctrl/Cmd+C).
 
 ## Accessibility
 
@@ -34,17 +34,15 @@ No pattern of its own; it renders a JSON tree plus a table row.
 
 The tree is where the accessibility questions are, and they are worth checking rather than assuming, because JSON viewers are routinely built as nested `<div>`s with click handlers:
 
-- **A collapsible tree should be the APG Tree View pattern** — `role="tree"`, `role="treeitem"`, `aria-expanded` on branches (and **absent**, not `false`, on leaves), `aria-level`/`aria-posinset`/`aria-setsize`, a roving tabindex so the tree is one tab stop, and Right/Left/Up/Down/Home/End. **Tree** in this kit implements exactly that and would be the natural composition; whether `JsonTree` does is the first thing to verify.
+- **A collapsible tree should be the APG Tree View pattern** — `role="tree"`, `role="treeitem"`, `aria-expanded` on branches (and **absent**, not `false`, on leaves), `aria-level`/`aria-posinset`/`aria-setsize`, a roving tabindex so the tree is one tab stop, and Right/Left/Up/Down/Home/End. `JsonTree` implements it: `role="tree"` and `treeitem`, `aria-level`/`aria-posinset`/`aria-setsize`, `aria-expanded` on branches and a roving tabindex.
 - **If it is not a tree, it is at minimum a set of disclosure buttons**, each needing `aria-expanded` and a name that says what expands.
 - **A large object is a lot of announced text.** Deep JSON read linearly is close to unusable; the collapsed-by-default state is the accessibility feature, and expanding should be the user's choice.
 - **Punctuation-heavy content** — braces, brackets, quotes, colons — is announced inconsistently and often verbosely. A tree with structural nesting instead of visible punctuation reads far better.
-- **`@required` must reach the accessible name** in the docs lens rather than only rendering an asterisk.
+- **`@required`** adds a visually hidden "(required)" beside the asterisk, in the property row and the doc row.
 - **Nothing is editable**, so there is no invalid state to announce — which is one genuine upside of the read-only decision.
 
 ## Theming
 
-`JsonTree`'s tokens for the tree (mono voice, key and value inks, the disclosure affordance), **Table**'s for the doc row, plus the property rail's label voice and **Token**'s treatment for the default value.
+`JsonTree`'s tokens for the tree (mono voice, key and value inks, the disclosure affordance), **Table**'s for the doc row, and the property rail's mono label. The knob caps the tree at 7.5rem tall and sets its indent to `--boxel-sp-sm`; rows keep JsonTree's own height.
 
-Nothing of its own. The key/value ink distinction is the thing to check per season: a JSON tree is read by scanning for keys, and if `--foreground` and `--muted-foreground` converge, the structure flattens into an undifferentiated block of mono text.
-
-The styles sit in `@layer PretComponent`, so a caller's unlayered CSS overrides them without a more specific selector.
+The key/value ink distinction is the thing to check in each theme: a JSON tree is read by scanning for keys, and if `--foreground` and `--muted-foreground` converge, the structure flattens into an undifferentiated block of mono text.
diff --git a/packages/pretui/components/usage-object.test.gts b/packages/pretui/components/usage-object.test.gts
index 8b33131829e..fd7752b7408 100644
--- a/packages/pretui/components/usage-object.test.gts
+++ b/packages/pretui/components/usage-object.test.gts
@@ -13,14 +13,14 @@ module('Pretui | components/usage-object', function (hooks) {
 
   test('doc mode is an API row typed Object', async function (assert) {
     await render(<template><table><tbody><UsageObject @name='item' @description='The record' @required={{true}} /></tbody></table></template>);
-    let cells = Array.from(document.querySelectorAll('[data-test-pretui-usage-arg] td')).map((td) => td.textContent?.replace(/\s+/g, ' ').trim());
-    assert.deepEqual(cells, ['@item *', 'Object', 'The record', '—']);
+    let cells = Array.from(document.querySelectorAll('[data-test-pretui-usage-arg] :is(th, td)')).map((td) => td.textContent?.replace(/\s+/g, ' ').trim());
+    assert.deepEqual(cells, ['@item * (required)', 'Object', 'The record', '—']);
   });
 
   test('prop mode shows the value as a labelled JSON tree, or nothing when controls are hidden', async function (assert) {
     const VALUE = { id: 7, tags: ['a', 'b'] };
     await render(<template><UsageObject @mode='prop' @name='item' @value={{VALUE}} @required={{true}} /></template>);
-    assert.strictEqual(document.querySelector('[data-test-pretui-prop-row-label]')?.textContent?.replace(/\s+/g, ' ').trim(), 'item *');
+    assert.strictEqual(document.querySelector('[data-test-pretui-prop-row-label]')?.textContent?.replace(/\s+/g, ' ').trim(), 'item * (required)');
     let tree = document.querySelector('[data-test-pretui-prop-row] [data-test-pretui-json-tree]') as HTMLElement;
     assert.ok(tree, 'a JsonTree, not a <pre> of stringified JSON');
     assert.true(tree.textContent?.includes('tags'));
diff --git a/packages/pretui/components/usage-string.gts b/packages/pretui/components/usage-string.gts
index 229ba572878..a686ba94764 100644
--- a/packages/pretui/components/usage-string.gts
+++ b/packages/pretui/components/usage-string.gts
@@ -1,5 +1,6 @@
 // Pretui — UsageString: a string argument with its knob.
 import Component from '@glimmer/component';
+import { guidFor } from '@ember/object/internals';
 import { Input } from './input';
 import { Select } from './select';
 import { UsageArgument } from './usage-argument';
@@ -39,26 +40,35 @@ export class UsageString extends Component<UsageStringSignature> {
   get readOnlyValue() {
     return readOnlyText(this.args.value ?? this.args.defaultValue);
   }
+  controlId = `${guidFor(this)}-control`;
+  // the rail labels the control when there is one
+  get labelFor() {
+    return this.hasControl ? this.controlId : undefined;
+  }
   callOnInput = (v: string) => {
     this.args.onInput?.(v);
   };
   <template>
     {{#if this.isProp}}
       {{#unless @hideControls}}
-        <PropRow @label={{@name}} @required={{@required}}>
+        <PropRow
+          @label={{@name}}
+          @required={{@required}}
+          @controlId={{this.labelFor}}
+        >
           {{#if this.hasControl}}
             {{#if @options}}
               <Select
                 @options={{this.selectOptions}}
                 @value={{this.valueStr}}
                 @onValueChange={{this.callOnInput}}
-                @label={{@name}}
+                @controlId={{this.controlId}}
               />
             {{else}}
               <Input
                 @value={{this.valueStr}}
                 @onInput={{this.callOnInput}}
-                aria-label={{@name}}
+                @controlId={{this.controlId}}
               />
             {{/if}}
           {{else}}
diff --git a/packages/pretui/components/usage-string.md b/packages/pretui/components/usage-string.md
index 607e6234a5f..5cb90478b0c 100644
--- a/packages/pretui/components/usage-string.md
+++ b/packages/pretui/components/usage-string.md
@@ -34,8 +34,8 @@ No pattern of its own; it renders one of two kit controls plus a table row.
 
 Gaps:
 
-- **The knob's visible label is the property-row rail, not a `<label for>`.** The control takes the argument name as its accessible name (`@label` on the Select, `aria-label` on the Input), so it is named, but clicking the rail does not focus it.
-- **`@required` must reach the accessible name**, not only render an asterisk — the fix **FormField** already made in the forms territory.
+- **The rail is the control's `<label for>`**, so the visible argument name is the control's accessible name, and clicking it focuses the Input. The Select's trigger takes the same label through `aria-labelledby`.
+- **`@required`** adds a visually hidden "(required)" beside the asterisk, so it is part of the label, the same fix **FormField** made.
 - **Changing a knob re-renders the example silently.** No live region announces the effect, so a screen-reader user changing `@size` from `md` to `lg` gets no confirmation that anything happened. This belongs to **FreestyleUsage** but is felt here.
 - **Free-text mode has no format guidance.** A string argument expecting a CSS length or an ISO date offers a bare Input with no hint (**WCAG 3.3.2**), and `@description` lives in the _other_ lens — so the docs table has the explanation and the knob does not.
 - **The two lenses are not linked.** A reader in the property list has no route to the row documenting the same argument.
@@ -43,6 +43,4 @@ Gaps:
 
 ## Theming
 
-**Select** and **Input** token sets for the control, **Table**'s for the doc row, plus the property rail's label voice (`--muted-foreground`, the mono eyebrow treatment) and **Token**'s for the type and default value.
-
-Nothing of its own. Because the property list is dense and its labels are small, a season should verify the rail's ink against `--card` at the eyebrow size — this is a surface read closely by people comparing values, and it is one of the smallest text sizes in the kit.
+**Select** and **Input** token sets for the control, **Table**'s for the doc row, and the property rail's label: mono at `--boxel-font-size-xs` in `--muted-foreground`, which measures 6.9:1 on `--card` in light and 5.6:1 in dark.
diff --git a/packages/pretui/freestyle-controls.test.gts b/packages/pretui/freestyle-controls.test.gts
index 8b93f6cfe3e..07072251cca 100644
--- a/packages/pretui/freestyle-controls.test.gts
+++ b/packages/pretui/freestyle-controls.test.gts
@@ -22,6 +22,17 @@ class Sink {
   takeArray = (value: string[]) => (this.arrayValue = value);
 }
 
+// the control a property row's visible label points at, so the test also
+// proves the rail names its control
+function controlLabelled(name: string): HTMLElement {
+  let label = Array.from(
+    document.querySelectorAll<HTMLElement>('[data-test-pretui-prop-row-label]'),
+  ).find((element) => element.textContent?.trim() === name);
+  let target = label?.getAttribute('for');
+  if (!target) throw new Error(`no <label for> names the ${name} control`);
+  return document.getElementById(target) as HTMLElement;
+}
+
 module('Pretui | freestyle property controls', function (hooks) {
   setupCardTest(hooks);
 
@@ -101,9 +112,9 @@ module('Pretui | freestyle property controls', function (hooks) {
         />
       </template>);
 
-      await fillIn('[aria-label="label"]', 'New lot');
+      await fillIn(controlLabelled('label'), 'New lot');
       await click('[aria-label="enabled"]');
-      await fillIn('[aria-label="count"]', '8');
+      await fillIn(controlLabelled('count'), '8');
       await fillIn('[aria-label="tags"]', 'green, spring');
 
       assert.strictEqual(sink.stringValue, 'New lot');
diff --git a/packages/pretui/internal/freestyle.gts b/packages/pretui/internal/freestyle.gts
index 6fa7feddbdb..cc98478bb25 100644
--- a/packages/pretui/internal/freestyle.gts
+++ b/packages/pretui/internal/freestyle.gts
@@ -10,6 +10,7 @@
 // verbatim-freestyle. Deliberate deltas: no ember-freestyle service, plain
 // <pre> for @source, labeled controls.
 import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { VisuallyHidden } from '../components/visually-hidden';
 
 export function isPresent(v: unknown): boolean {
   return v !== undefined && v !== null && v !== '';
@@ -23,18 +24,41 @@ export function readOnlyText(v: unknown): string {
 export type ArgsMode = 'doc' | 'prop';
 // ── Property-list row (the prop lens) ────────────────────────────────────
 interface PropRowSignature {
-  Args: { label?: string; required?: boolean };
+  Args: {
+    label?: string;
+    required?: boolean;
+    /** id of the row's control: the rail becomes its <label for>, so the
+     * visible text names the control and a click on it focuses it */
+    controlId?: string;
+  };
   Blocks: { default: [] };
   Element: HTMLDivElement;
 }
 
 export const PropRow: TemplateOnlyComponent<PropRowSignature> = <template>
   <div class='proprow' data-test-pretui-prop-row ...attributes>
-    <span class='proprow-label' data-test-pretui-prop-row-label>
-      {{@label}}
-      {{#if @required}}<span class='proprow-req'>*</span>{{/if}}
-    </span>
-    <span class='proprow-control'>{{yield}}</span>
+    {{#if @controlId}}
+      <label
+        class='proprow-label'
+        for={{@controlId}}
+        data-test-pretui-prop-row-label
+      >
+        {{@label}}
+        {{#if @required}}<span
+            class='proprow-req'
+            aria-hidden='true'
+          >*</span><VisuallyHidden>(required)</VisuallyHidden>{{/if}}
+      </label>
+    {{else}}
+      <span class='proprow-label' data-test-pretui-prop-row-label>
+        {{@label}}
+        {{#if @required}}<span
+            class='proprow-req'
+            aria-hidden='true'
+          >*</span><VisuallyHidden>(required)</VisuallyHidden>{{/if}}
+      </span>
+    {{/if}}
+    <div class='proprow-control'>{{yield}}</div>
   </div>
   <style scoped>
     /* workbench inspector row: label rail left, control right */

From 16efbb9d1aa215170cfe7e1e40f0911a32d95c61 Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Thu, 8 Oct 2026 16:10:51 -0400
Subject: [PATCH 22/30] Fix the Spec edit view's flag labels, wrap long names,
 label the note composer, warm the note tint in dark, and list the gallery's
 examples

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/example-gallery.gts  |  21 ++-
 packages/pretui/pretui-component.gts | 258 ++++++++++++++++++---------
 packages/pretui/pretui-css.gts       |  65 +++----
 packages/pretui/pretui-note.gts      |  80 +++++++--
 4 files changed, 281 insertions(+), 143 deletions(-)

diff --git a/packages/pretui/example-gallery.gts b/packages/pretui/example-gallery.gts
index 5886f5d0cb4..ae5e6b62aeb 100644
--- a/packages/pretui/example-gallery.gts
+++ b/packages/pretui/example-gallery.gts
@@ -20,21 +20,21 @@ export class ExampleGallery extends Component<{
           <h2 class='exg-cap'>Examples</h2>
           <span class='exg-count'>{{this.countLabel}}</span>
         </header>
-        <div class='exg-grid'>
+        <ul class='exg-grid'>
           {{#each this.specs as |spec|}}
-            <div class='exg-card'>
+            <li class='exg-card'>
               <div class='exg-demo'>
                 <spec.component />
               </div>
               <div class='exg-meta'>
-                <span class='exg-title'>{{spec.title}}</span>
+                <h3 class='exg-title'>{{spec.title}}</h3>
                 {{#if spec.note}}<span
                     class='exg-note'
                   >{{spec.note}}</span>{{/if}}
               </div>
-            </div>
+            </li>
           {{/each}}
-        </div>
+        </ul>
       </section>
     {{/if}}
     <style scoped>
@@ -66,6 +66,9 @@ export class ExampleGallery extends Component<{
         color: var(--muted-foreground);
       }
       .exg-grid {
+        margin: 0;
+        padding: 0;
+        list-style: none;
         display: grid;
         grid-template-columns: repeat(
           auto-fill,
@@ -100,18 +103,26 @@ export class ExampleGallery extends Component<{
         overflow: hidden;
       }
       .exg-meta {
+        min-width: 0;
         display: grid;
         gap: var(--boxel-sp-6xs);
         padding-block-start: var(--boxel-sp-xs);
         box-shadow: inset 0 1px 0 var(--border);
       }
+      /* an h3 for navigation, set in the caption role */
       .exg-title {
+        font-family: var(--boxel-caption-font-family);
         font-size: var(--boxel-caption-font-size);
         font-weight: var(--boxel-caption-font-weight);
+        line-height: var(--boxel-caption-line-height);
+        letter-spacing: var(--boxel-caption-letter-spacing);
+        overflow-wrap: break-word;
       }
       .exg-note {
         font-size: var(--boxel-caption-font-size);
+        line-height: 1.5;
         color: var(--muted-foreground);
+        overflow-wrap: break-word;
       }
     </style>
   </template>
diff --git a/packages/pretui/pretui-component.gts b/packages/pretui/pretui-component.gts
index 89a6357cbb3..3859842283d 100644
--- a/packages/pretui/pretui-component.gts
+++ b/packages/pretui/pretui-component.gts
@@ -27,6 +27,7 @@ import { tracked } from '@glimmer/tracking';
 import { on } from '@ember/modifier';
 import { modifier } from 'ember-modifier';
 import { fn } from '@ember/helper';
+import StarIcon from '@cardstack/boxel-icons/star';
 import type { Query, RealmResourceIdentifier } from '@cardstack/runtime-common';
 import { ThemeFrame } from './components/theme-frame';
 import { EmptyState } from './components/empty-state';
@@ -156,10 +157,10 @@ class WriteupFold extends GlimmerComponent<WriteupFoldSignature> {
     </div>
     <style scoped>
       /* closed, the preview fills whatever height the fold is given, never
-         less than --wb-fold-preview-h; open, it grows to the content */
+         less than --_wb-fold-preview-h; open, it grows to the content */
       .wb-fold {
-        --wb-fold-preview-h: 14rem;
-        --wb-fold-fade-h: 2rem;
+        --_wb-fold-preview-h: 14rem;
+        --_wb-fold-fade-h: 2rem;
 
         position: relative;
         display: flex;
@@ -167,7 +168,7 @@ class WriteupFold extends GlimmerComponent<WriteupFoldSignature> {
       }
       .wb-fold-region {
         flex: 1 1 0;
-        min-block-size: var(--wb-fold-preview-h);
+        min-block-size: var(--_wb-fold-preview-h);
         overflow: hidden;
         /* the open state changes the flex basis and grow, not height, so those
            are what animate; interpolate-size lets the basis reach auto */
@@ -196,7 +197,7 @@ class WriteupFold extends GlimmerComponent<WriteupFoldSignature> {
         position: absolute;
         inset-inline: 0;
         inset-block-end: 0;
-        padding: var(--wb-fold-fade-h) var(--boxel-sp-sm) var(--boxel-sp-xs);
+        padding: var(--_wb-fold-fade-h) var(--boxel-sp-sm) var(--boxel-sp-xs);
         background-image: linear-gradient(transparent, var(--card) 70%);
       }
       .wb-fold[data-open='true'] .wb-fold-more {
@@ -230,6 +231,8 @@ interface NoteComposerSignature {
 
 class NoteComposer extends GlimmerComponent<NoteComposerSignature> {
   @tracked draft = '';
+  fieldId = `${guidFor(this)}-note`;
+  hintId = `${guidFor(this)}-hint`;
   setDraft = (v: string) => (this.draft = v);
   get draftEmpty(): boolean {
     return this.draft.trim().length === 0;
@@ -242,18 +245,20 @@ class NoteComposer extends GlimmerComponent<NoteComposerSignature> {
   };
   <template>
     <div class='note-compose' data-test-pretui-note-compose ...attributes>
-      <span class='note-compose-cap'>Note on
-        {{if @componentName @componentName 'this component'}}</span>
+      <label class='note-compose-cap' for={{this.fieldId}}>Note on
+        {{if @componentName @componentName 'this component'}}</label>
       <Textarea
         class='note-compose-field'
+        @controlId={{this.fieldId}}
         @value={{this.draft}}
         @onInput={{this.setDraft}}
         @placeholder='What should change? Markdown welcome.'
-        aria-label='Note text'
+        aria-describedby={{this.hintId}}
         data-test-pretui-note-draft
       />
       <div class='note-compose-foot'>
-        <span class='note-compose-hint'>Picked up by the next triage pass.</span>
+        <span class='note-compose-hint' id={{this.hintId}}>Picked up by the next
+          triage pass.</span>
         <Button
           @tone='primary'
           @size='s'
@@ -265,12 +270,17 @@ class NoteComposer extends GlimmerComponent<NoteComposerSignature> {
     </div>
     <style scoped>
       .note-compose {
-        --note-compose-min-w: 17.5rem;
+        /* the composer sits on --popover, where --muted-foreground isn't a
+           guaranteed pair (4.2:1 in dark); a softer mix of its own ink is */
+        --_note-compose-dim: color-mix(
+          in oklch,
+          var(--popover-foreground) 75%,
+          var(--popover)
+        );
 
         display: flex;
         flex-direction: column;
         gap: var(--boxel-sp-2xs);
-        min-width: var(--note-compose-min-w);
       }
       .note-compose-cap {
         font-family: var(--boxel-eyebrow-font-family);
@@ -279,7 +289,6 @@ class NoteComposer extends GlimmerComponent<NoteComposerSignature> {
         line-height: var(--boxel-eyebrow-line-height);
         letter-spacing: var(--boxel-eyebrow-letter-spacing);
         text-transform: uppercase;
-        color: var(--muted-foreground);
       }
       .note-compose-field {
         width: 100%;
@@ -290,9 +299,12 @@ class NoteComposer extends GlimmerComponent<NoteComposerSignature> {
         justify-content: space-between;
         gap: var(--boxel-sp-xs);
       }
+      .note-compose-cap,
+      .note-compose-hint {
+        color: var(--_note-compose-dim);
+      }
       .note-compose-hint {
         font-size: var(--boxel-font-size-2xs);
-        color: var(--muted-foreground);
       }
     </style>
   </template>
@@ -401,6 +413,11 @@ export class PretUISpec extends Spec {
       // eslint-disable-next-line @typescript-eslint/no-explicit-any
       return this.demoLoad?.value as any;
     }
+    // the brief stands in for a missing usage page; hidden while one loads,
+    // so it doesn't show and then vanish
+    get showBrief() {
+      return Boolean(this.args.model.brief) && !this.demo && !this.isDemoLoading;
+    }
     get examples() {
       let name = this.args.model.componentName;
       return name ? examplesLoadFor(name).value : undefined;
@@ -584,9 +601,9 @@ export class PretUISpec extends Spec {
         <article class='page' data-demo-policy={{this.demoPolicy}}>
           <header class='wb-topbar'>
             <div class='wb-crumb' data-test-pretui-spec-crumb>
-              <span class='wb-crumb-root'>Pret UI</span>
+              <span>Pret UI</span>
               <span aria-hidden='true'>/</span>
-              <span class='wb-crumb-dim'>{{if
+              <span>{{if
                   @model.category
                   @model.category
                   (if @model.territory @model.territory 'components')
@@ -607,10 +624,11 @@ export class PretUISpec extends Spec {
                 @tone={{stageTone @model.stage}}
               />
               {{#if @model.isNew}}<Chip @label='New' @tone='attention' />{{/if}}
-              {{#if @model.featured}}<Chip @tone='warning' @dot={{false}}><span
+              {{#if @model.featured}}<Chip @tone='warning' @dot={{false}}><StarIcon
+                    width='12'
+                    height='12'
                     aria-hidden='true'
-                  >★</span><VisuallyHidden
-                  >Featured</VisuallyHidden></Chip>{{/if}}
+                  /><VisuallyHidden>Featured</VisuallyHidden></Chip>{{/if}}
             </div>
             <div class='wb-grow'></div>
             <ThemeControls />
@@ -641,6 +659,7 @@ export class PretUISpec extends Spec {
                         @appearance='outlined'
                         @size='xs'
                         aria-expanded={{if open 'true' 'false'}}
+                        aria-haspopup='dialog'
                         {{on 'click' toggle}}
                         data-test-pretui-note-add
                       >Add note</Button>
@@ -688,18 +707,20 @@ export class PretUISpec extends Spec {
                 </span>
               {{/if}}
             {{/let}}
-            {{if @model.componentName @model.componentName 'Component'}}
+            <span class='wb-title-text'>{{if
+                @model.componentName
+                @model.componentName
+                'Component'
+              }}</span>
           </h1>
-          {{#unless this.demo}}
-            {{#if @model.brief}}
-              <p class='brief'>{{@model.brief}}</p>
-            {{/if}}
-          {{/unless}}
+          {{#if this.showBrief}}
+            <p class='brief'>{{@model.brief}}</p>
+          {{/if}}
           <div class='wb-work'>
             {{#if this.demo}}
               <this.demo />
             {{else if this.isDemoLoading}}
-              <section class='panel' aria-busy='true'>
+              <section class='panel'>
                 <LoadingState @label='Loading the usage page' />
               </section>
             {{else if this.isDemoExcluded}}
@@ -799,23 +820,24 @@ export class PretUISpec extends Spec {
           overscroll-behavior: none;
         }
         .page {
-          --wb-topbar-h: 2.75rem;
-          --wb-panel-h: 2.25rem;
-          --wb-title-frame-size: 3rem;
-          --wb-notes-w: 17.5rem;
-          --wb-writeup-min-w: 48rem;
+          --_wb-topbar-h: 2.75rem;
+          --_wb-panel-h: 2.25rem;
+          --_wb-title-frame-size: 3rem;
+          --_wb-notes-w: 17.5rem;
+          --_wb-notes-max-h: 20rem;
+          --_wb-writeup-min-w: 48rem;
           /* StepList's track turns vertical at 24rem; with the panel's
              padding, provenance needs 26rem to keep it horizontal */
-          --wb-provenance-min-w: 26rem;
-          --wb-provenance-max-w: 30rem;
-          --wb-krow-label-w: 6.875rem;
-          --wb-dot-size: 0.5rem;
+          --_wb-provenance-min-w: 26rem;
+          --_wb-provenance-max-w: 30rem;
+          --_wb-krow-label-w: 6.875rem;
+          --_wb-dot-size: 0.5rem;
           /* the page's inline padding, which the topbar cancels and restores
              to run edge to edge */
-          --wb-page-gutter: var(--boxel-sp-lg);
+          --_wb-page-gutter: var(--boxel-sp-lg);
 
           min-height: 100%;
-          padding: 0 var(--wb-page-gutter) var(--boxel-sp-2xl);
+          padding: 0 var(--_wb-page-gutter) var(--boxel-sp-2xl);
           display: grid;
           gap: var(--boxel-sp);
           align-content: start;
@@ -834,14 +856,20 @@ export class PretUISpec extends Spec {
         }
         /* the component's icon beside its title: a --background tile with a
            hairline ring, not a raised button */
+        /* the name shrinks and breaks, so a long one can't push the page
+           sideways at narrow widths */
+        .wb-title-text {
+          min-width: 0;
+          overflow-wrap: break-word;
+        }
         .wb-title-frame {
           --icon-color: currentColor;
           --icon-bg: none;
 
           display: grid;
           place-items: center;
-          width: var(--wb-title-frame-size);
-          height: var(--wb-title-frame-size);
+          width: var(--_wb-title-frame-size);
+          height: var(--_wb-title-frame-size);
           flex: none;
           border-radius: var(--boxel-border-radius-sm);
           box-shadow: inset 0 0 0 1px var(--border);
@@ -857,9 +885,9 @@ export class PretUISpec extends Spec {
           display: flex;
           align-items: center;
           gap: var(--boxel-sp-sm);
-          min-height: var(--wb-topbar-h);
-          margin: 0 calc(-1 * var(--wb-page-gutter));
-          padding: var(--boxel-sp-2xs) var(--wb-page-gutter);
+          min-height: var(--_wb-topbar-h);
+          margin: 0 calc(-1 * var(--_wb-page-gutter));
+          padding: var(--boxel-sp-2xs) var(--_wb-page-gutter);
           background-color: var(--card);
           color: var(--card-foreground);
           box-shadow: inset 0 -1px 0 var(--border);
@@ -867,16 +895,16 @@ export class PretUISpec extends Spec {
         }
         .wb-crumb {
           display: flex;
+          flex-wrap: wrap;
           align-items: center;
           gap: var(--boxel-sp-xs);
           font-size: var(--boxel-font-size-xs);
           color: var(--muted-foreground);
           min-width: 0;
         }
-        .wb-crumb-root {
-          padding: var(--boxel-sp-5xs) var(--boxel-sp-3xs);
-        }
         .wb-here {
+          min-width: 0;
+          overflow-wrap: break-word;
           color: var(--card-foreground);
           font-weight: 600;
         }
@@ -903,7 +931,7 @@ export class PretUISpec extends Spec {
           flex-direction: column;
           align-items: flex-end;
           gap: var(--boxel-sp-2xs);
-          width: min(var(--wb-notes-w), 100%);
+          width: min(var(--_wb-notes-w), 100%);
           min-width: 0;
         }
         /* a note wants room to write: Popover reads its width knob on the
@@ -911,13 +939,17 @@ export class PretUISpec extends Spec {
         .note-popover {
           --pretui-popover-width: 20rem;
         }
+        /* a long run of notes scrolls instead of pushing the page down; the
+           padding keeps the notes' focus rings inside the scroller */
         .notes-list {
           display: flex;
           flex-direction: column;
           gap: var(--boxel-sp-2xs);
           width: 100%;
+          max-block-size: var(--_wb-notes-max-h);
+          overflow-y: auto;
           margin: 0;
-          padding: 0;
+          padding: var(--boxel-sp-3xs);
           list-style: none;
         }
         .note {
@@ -926,17 +958,17 @@ export class PretUISpec extends Spec {
           width: 100%;
           text-align: start;
           padding: var(--boxel-sp-xs);
-          border: 0;
+          /* a real border, so the clickable edge survives forced colors */
+          border: 1px solid var(--border);
           border-radius: var(--boxel-border-radius);
+          /* oklab, so the tint stays warm over a cool dark card */
           background-color: color-mix(
-            in oklch,
+            in oklab,
             var(--attention) 14%,
             var(--card)
           );
           color: var(--card-foreground);
-          box-shadow:
-            0 0 0 1px var(--border),
-            var(--shadow-sm);
+          box-shadow: var(--shadow-sm);
           font-size: var(--boxel-caption-font-size);
           line-height: 1.5;
         }
@@ -945,9 +977,7 @@ export class PretUISpec extends Spec {
           outline-offset: 2px;
         }
         .note:hover {
-          box-shadow:
-            0 0 0 1px var(--border),
-            var(--shadow-md);
+          box-shadow: var(--shadow-md);
         }
         /* Clamp long notes: the rail is a pointer to the note card, not the
            note card. Clicking opens the whole thing. */
@@ -982,7 +1012,7 @@ export class PretUISpec extends Spec {
           align-items: stretch;
         }
         .wb-below > .wb-writeup-panel {
-          flex: 1 1 var(--wb-writeup-min-w);
+          flex: 1 1 var(--_wb-writeup-min-w);
           display: flex;
           flex-direction: column;
         }
@@ -991,7 +1021,7 @@ export class PretUISpec extends Spec {
         }
 
         .wb-below > .wb-provenance {
-          flex: 1 1 var(--wb-provenance-min-w);
+          flex: 1 1 var(--_wb-provenance-min-w);
           align-self: start;
         }
         /* capped only while it shares the row: 75rem is the write-up's 48rem
@@ -1001,7 +1031,7 @@ export class PretUISpec extends Spec {
            transpiler. */
         @container (width >= 75rem) {
           .wb-below > .wb-writeup-panel ~ .wb-provenance {
-            max-inline-size: var(--wb-provenance-max-w);
+            max-inline-size: var(--_wb-provenance-max-w);
           }
         }
         .wb-panel {
@@ -1016,7 +1046,7 @@ export class PretUISpec extends Spec {
           display: flex;
           align-items: center;
           gap: var(--boxel-sp-xs);
-          min-height: var(--wb-panel-h);
+          min-height: var(--_wb-panel-h);
           padding: var(--boxel-sp-xs) var(--boxel-sp-sm);
           box-shadow: inset 0 -1px 0 var(--border);
         }
@@ -1043,14 +1073,14 @@ export class PretUISpec extends Spec {
         }
         .wb-krow {
           display: grid;
-          grid-template-columns: var(--wb-krow-label-w) minmax(0, 1fr);
+          grid-template-columns: var(--_wb-krow-label-w) minmax(0, 1fr);
           gap: var(--boxel-sp-sm);
           padding: var(--boxel-sp-2xs) var(--boxel-sp-sm);
           align-items: baseline;
         }
         .wb-krow dt {
-          font-size: var(--boxel-font-size-xs);
-          font-weight: 500;
+          font-size: var(--boxel-ui-label-font-size);
+          font-weight: var(--boxel-ui-label-font-weight);
           color: var(--muted-foreground);
         }
         .wb-dots {
@@ -1060,8 +1090,8 @@ export class PretUISpec extends Spec {
           vertical-align: middle;
         }
         .wb-dot {
-          width: var(--wb-dot-size);
-          height: var(--wb-dot-size);
+          width: var(--_wb-dot-size);
+          height: var(--_wb-dot-size);
           border-radius: 50%;
           box-shadow: inset 0 0 0 1px currentColor;
         }
@@ -1071,6 +1101,7 @@ export class PretUISpec extends Spec {
         .wb-krow dd {
           margin: 0;
           font-size: var(--boxel-font-size-xs);
+          line-height: 1.5;
           overflow-wrap: break-word;
         }
         .panel {
@@ -1110,7 +1141,7 @@ export class PretUISpec extends Spec {
           <div class='mono'>
             {{#let (iconFor @model.icon) as |FitIcon|}}
               {{#if FitIcon}}
-                <FitIcon width='60%' height='60%' role='presentation' />
+                <FitIcon width='18' height='18' role='presentation' />
               {{else}}
                 {{this.monogram}}
               {{/if}}
@@ -1119,19 +1150,20 @@ export class PretUISpec extends Spec {
           <div class='fit-body'>
             <div class='fit-name'>
               {{@model.componentName}}
-              {{#if @model.featured}}<span class='fit-star'><span
+              {{#if @model.featured}}<span class='fit-star'><StarIcon
+                    width='12'
+                    height='12'
                     aria-hidden='true'
-                  >★</span><VisuallyHidden
-                  >Featured</VisuallyHidden></span>{{/if}}
+                  /><VisuallyHidden>Featured</VisuallyHidden></span>{{/if}}
             </div>
             <div class='fit-sub'>
-              <span class='fit-terr'>{{if
+              <span>{{if
                   @model.category
                   @model.category
                   @model.territory
                 }}</span>
               {{#if @model.liveInUse}}
-                <span class='fit-ver'>{{@model.version}}</span>
+                <span>{{if @model.version @model.version '0.0.0'}}</span>
               {{/if}}
             </div>
             <div class='fit-extra'>
@@ -1268,7 +1300,11 @@ export class PretUISpec extends Spec {
     <template>
       <div class='tile'>
         <div class='tile-head'>
-          <span class='tile-name'>{{@model.componentName}}</span>
+          <span class='tile-name'>{{if
+              @model.componentName
+              @model.componentName
+              'Component'
+            }}</span>
           <StatusChip
             @value={{stageLabel @model.stage}}
             @tone={{stageTone @model.stage}}
@@ -1280,7 +1316,7 @@ export class PretUISpec extends Spec {
               @model.category
               @model.territory
             }}</span>
-          <Token @value={{if @model.source @model.source 'design-v1'}} />
+          {{#if @model.source}}<Token @value={{@model.source}} />{{/if}}
         </div>
       </div>
       <style scoped>
@@ -1297,6 +1333,8 @@ export class PretUISpec extends Spec {
           gap: var(--boxel-sp-xs);
         }
         .tile-name {
+          min-width: 0;
+          overflow-wrap: break-word;
           font-weight: 600;
           font-size: var(--boxel-font-size-xs);
         }
@@ -1320,6 +1358,8 @@ export class PretUISpec extends Spec {
   // Hand-written: Spec's own edit template throws without a resolved ref, and
   // the default field editor surfaces ten inherited fields this card never sets.
   static edit = class Edit extends Component<typeof PretUISpec> {
+    // ids for the captions that name editors a <label> can't wrap
+    captionId = (key: string) => `${guidFor(this)}-${key}`;
     <template>
       <div class='wb-edit'>
         <fieldset class='wb-group'>
@@ -1347,8 +1387,12 @@ export class PretUISpec extends Spec {
               <@fields.adoptionStatus /></label>
             <label><span class='wb-cap'>Introduced in</span>
               <@fields.introducedVersion /></label>
-            <div class='wb-wide'>
-              <span class='wb-cap'>Tags</span>
+            <div
+              class='wb-wide'
+              role='group'
+              aria-labelledby={{this.captionId 'tags'}}
+            >
+              <span id={{this.captionId 'tags'}} class='wb-cap'>Tags</span>
               <@fields.tags />
             </div>
           </div>
@@ -1369,21 +1413,54 @@ export class PretUISpec extends Spec {
           </div>
         </fieldset>
 
+        {{! editors a <label> can't wrap (yes/no radios, the tag list, the
+            linked file with its Remove button) sit in a named group instead:
+            a wrapping label would activate their first control on any click }}
         <fieldset class='wb-group'>
           <legend>Signals</legend>
           <div class='wb-fields'>
             <label><span class='wb-cap'>Demand (1-5)</span>
               <@fields.demand /></label>
-            <label class='wb-flag'><@fields.featured />
-              <span class='wb-cap'>Featured</span></label>
-            <label class='wb-flag'><@fields.isNew />
-              <span class='wb-cap'>New</span></label>
-            <label class='wb-flag'><@fields.hasDesign />
-              <span class='wb-cap'>Has design</span></label>
-            <label class='wb-flag'><@fields.hasExamples />
-              <span class='wb-cap'>Has examples</span></label>
-            <label class='wb-flag'><@fields.liveInUse />
-              <span class='wb-cap'>Live in use</span></label>
+            <div
+              class='wb-flag'
+              role='group'
+              aria-labelledby={{this.captionId 'featured'}}
+            ><@fields.featured /><span
+                id={{this.captionId 'featured'}}
+                class='wb-cap'
+              >Featured</span></div>
+            <div
+              class='wb-flag'
+              role='group'
+              aria-labelledby={{this.captionId 'isNew'}}
+            ><@fields.isNew /><span
+                id={{this.captionId 'isNew'}}
+                class='wb-cap'
+              >New</span></div>
+            <div
+              class='wb-flag'
+              role='group'
+              aria-labelledby={{this.captionId 'hasDesign'}}
+            ><@fields.hasDesign /><span
+                id={{this.captionId 'hasDesign'}}
+                class='wb-cap'
+              >Has design</span></div>
+            <div
+              class='wb-flag'
+              role='group'
+              aria-labelledby={{this.captionId 'hasExamples'}}
+            ><@fields.hasExamples /><span
+                id={{this.captionId 'hasExamples'}}
+                class='wb-cap'
+              >Has examples</span></div>
+            <div
+              class='wb-flag'
+              role='group'
+              aria-labelledby={{this.captionId 'liveInUse'}}
+            ><@fields.liveInUse /><span
+                id={{this.captionId 'liveInUse'}}
+                class='wb-cap'
+              >Live in use</span></div>
           </div>
         </fieldset>
 
@@ -1399,10 +1476,13 @@ export class PretUISpec extends Spec {
         <fieldset class='wb-group'>
           <legend>Write-up</legend>
           <div class='wb-fields'>
-            {{! a div, not a label: the editor's first control is Remove,
-                which a label would activate on any click }}
-            <div class='wb-wide'>
-              <span class='wb-cap'>Linked file</span>
+            <div
+              class='wb-wide'
+              role='group'
+              aria-labelledby={{this.captionId 'writeup'}}
+            >
+              <span id={{this.captionId 'writeup'}} class='wb-cap'>Linked
+                file</span>
               <@fields.writeup />
             </div>
           </div>
@@ -1410,7 +1490,7 @@ export class PretUISpec extends Spec {
       </div>
       <style scoped>
         .wb-edit {
-          --wb-field-min-w: 12.5rem;
+          --_wb-field-min-w: 12.5rem;
 
           display: grid;
           gap: var(--boxel-sp);
@@ -1437,7 +1517,7 @@ export class PretUISpec extends Spec {
           display: grid;
           grid-template-columns: repeat(
             auto-fit,
-            minmax(min(var(--wb-field-min-w), 100%), 1fr)
+            minmax(min(var(--_wb-field-min-w), 100%), 1fr)
           );
           gap: var(--boxel-sp-xs) var(--boxel-sp-sm);
         }
diff --git a/packages/pretui/pretui-css.gts b/packages/pretui/pretui-css.gts
index 8ab3b32e263..405b8613569 100644
--- a/packages/pretui/pretui-css.gts
+++ b/packages/pretui/pretui-css.gts
@@ -8,13 +8,13 @@
 // 1. `cssValue` — the guard for caller-supplied strings that reach CSS
 // ─────────────────────────────────────────────────────────────────────────
 //
-// Law 2 routes a hue through nearly every component, and a hue arrives as a
+// A hue is routed through nearly every component, and it arrives as a
 // caller string. Interpolating that string into an inline style and handing
 // it to `htmlSafe` lets `red; background: url(https://evil/x)` inject
 // arbitrary declarations — `htmlSafe` means "I have already made this safe",
 // and nothing had.
 //
-// The guard is an ALLOWLIST, not a sanitiser: it validates and returns the
+// The guard is an ALLOWLIST, not a sanitizer: it validates and returns the
 // value unchanged, or returns `undefined` for anything it does not fully
 // understand. It never strips-and-continues, because strip-and-continue is
 // how a value that looked harmless after cleaning turns out not to be.
@@ -28,10 +28,10 @@
 // 2. `--pretui-z-*` — the stacking scale
 // ─────────────────────────────────────────────────────────────────────────
 //
-// Seven components in the kit float above the page — Popup, Popover, Dialog,
-// Drawer, Tooltip, Menu, Toast — and before this scale each picked its own
-// integer, so they could not be ordered among themselves, and a host
-// application could not slot its own chrome between them.
+// The kit's floating surfaces (Popup, and Popover through it; Dialog,
+// Drawer, Tooltip, Menu and the other dropdowns; Toaster) take their tier
+// from one scale, so they order among themselves and a host can slot its own
+// chrome between them.
 //
 // The order, and why it is this order:
 //
@@ -51,9 +51,13 @@
 //                floating surface. Always one step BELOW the surface it
 //                dismisses and above everything the surface covers — a scrim
 //                that outranks its own panel eats the panel's clicks.
-//   dropdown 60  Menu, Select's listbox, Combobox, CommandPalette. Anchored
-//                to a trigger, dismissed by an outside click, and always
-//                subordinate to a panel that may contain it.
+//   dropdown 60  Menu (MenuPanel), MultiSelect, TreeSelect, Cascader,
+//                NavigationMenu, Mentions, EmojiPicker and Autocomplete.
+//                Anchored to a trigger, dismissed by an outside click, and
+//                always subordinate to a panel that may contain it. Select and
+//                Combobox render boxel-ui's listbox, which takes boxel-ui's
+//                own layer (above toast), and CommandPalette is a modal
+//                <dialog> in the top layer.
 //   overlay 70   Popup and Popover — a deliberate floating panel. Above
 //                dropdown because a Popover can contain a Select, and the
 //                containing panel must never paint under its own content.
@@ -64,23 +68,27 @@
 //   dialog  90   Dialog and Drawer. FALLBACK ONLY: both use native
 //                `<dialog>` + `showModal()`, which promotes them to the top
 //                layer, above every z-index on the page regardless of value.
-//                The token exists so a non-modal or polyfilled variant lands
-//                in the right place, and so the intended rank is written
-//                down rather than implied by the platform.
+//                Nothing reads this token; it records the intended rank
+//                rather than leaving it implied by the platform.
 //   toast   100  the last word. A toast reports something that just happened
 //                and must stay readable over whatever is open, including a
 //                modal — so it is the only tier deliberately above `dialog`.
-//                Toaster's fixed region takes it; a bare Toast is in flow and
-//                takes no tier, so whatever positions one owns its z-index.
+//                Toaster's fixed region and SkipLink take it; a bare Toast is
+//                in flow and takes no tier, so whatever positions one owns
+//                its z-index.
 //
 // The numbers are gapped so a host can interleave its own chrome (a global
 // nav at 65, an assistant panel at 85) without editing Pretui.
 //
-// **Consumption rule.** Every component writes
-// `z-index: var(--pretui-z-<tier>, <the number above>)`. The literal fallback
-// is not optional and is not a guess — it is this table, restated, so a
-// season that has never defined these tokens renders in exactly the same
-// order. A season redefines a token to move a whole tier at once.
+// **Consumption rule.** A component that stacks against OTHER components
+// writes `z-index: var(--pretui-z-<tier>, <the number above>)`. The literal
+// fallback is not optional and is not a guess — it is this table, restated,
+// so a host that has never defined these tokens renders in exactly the same
+// order; a host redefines a token to move a whole tier at once. Layering
+// inside one component's own box (a 1, 2 or 3) is the `raised` role and
+// stays literal. Exceptions that still pick their own number: PageScaffold's
+// skip link (20) and sticky masthead (10), FloatButton (--pretui-float-z, 20)
+// and Backdrop (--pretui-backdrop-z, 50).
 
 import { htmlSafe } from '@ember/template';
 
@@ -121,7 +129,7 @@ const ALLOWED_FUNCTIONS = new Set([
   'clamp',
   'round',
   'abs',
-  // colour
+  // color
   'rgb',
   'rgba',
   'hsl',
@@ -133,8 +141,7 @@ const ALLOWED_FUNCTIONS = new Set([
   'oklch',
   'color',
   'color-mix',
-  // gradients — added 2026-08-13 after the colour work measured the gap.
-  // Their ARGUMENTS are still validated by the same character and function
+  // gradients. Their ARGUMENTS are still validated by the same character and function
   // allowlist, so admitting the names widens nothing: `url()` and `attr()`
   // remain rejected wherever they appear, at any nesting depth.
   'linear-gradient',
@@ -160,12 +167,9 @@ const CALL = /([A-Za-z][A-Za-z0-9-]*)?\(/g;
 /** Anything starting `#` up to the next separator. */
 const HEXISH = /#[^\s,()]*/g;
 
-/** Longer than any legitimate colour, length or gradient stop list. */
-// 256 was chosen for hand-authored values and was wrong for GENERATED ones: a
-// 32-step channel track measures 1069 chars and a 20-step track 629, so an
-// 8-stop gradient already exceeded the old cap and was silently dropped. The
-// cap exists to bound the parser's work, not to police intent — 4096 keeps
-// that bound while admitting every gradient the kit actually emits.
+/** Longer than any legitimate color, length or gradient stop list. */
+// Bounds the parser's work; generated gradient tracks run past 1000
+// characters (a 32-step channel track is 1069), so the cap sits well above.
 const MAX_VALUE_LENGTH = 4096;
 
 /** Deeper than `color-mix(in oklch, var(--a, oklch(…)) 40%, var(--b))`. */
@@ -228,7 +232,7 @@ export function cssValue(raw: unknown): string | undefined {
     }
     call = CALL.exec(value);
   }
-  // Every `#` introduces a well-formed hex colour.
+  // Every `#` introduces a well-formed hex color.
   HEXISH.lastIndex = 0;
   let hex = HEXISH.exec(value);
   while (hex !== null) {
@@ -254,7 +258,6 @@ const NUMERIC = /^-?(?:\d+\.?\d*|\.\d+)$/;
  * falls through to whatever the stylesheet's own fallback is — the caller
  * loses their override, never the component's rendering.
  */
-
 export function cssDeclaration(
   property: string,
   raw: unknown,
@@ -365,7 +368,7 @@ export function zVarName(layer: PretuiZLayer): string {
 }
 
 /**
- * The scale as CSS custom properties, for a season or host stylesheet that
+ * The scale as CSS custom properties, for a host stylesheet that
  * wants to declare them explicitly. Declaring them changes nothing on its
  * own — every consumer already falls back to these exact numbers — but it
  * gives one place to shift a whole tier.
diff --git a/packages/pretui/pretui-note.gts b/packages/pretui/pretui-note.gts
index fea1a8c9159..896ebfe0c5d 100644
--- a/packages/pretui/pretui-note.gts
+++ b/packages/pretui/pretui-note.gts
@@ -10,8 +10,9 @@
 //   - The note LINKS to its component (`target`), so the relationship is a
 //     real edge in the graph rather than a name match. The component page
 //     finds its own notes by querying for that edge.
-//   - Color is a tint of `--attention`, not a hardcoded yellow, so a sticky
-//     re-tints with the theme and reads correctly in light or dark.
+//   - Color is a tint of `--attention` over `--card`, not a hardcoded yellow,
+//     so a sticky re-tints with the theme; it is mixed in oklab, which keeps
+//     the tint warm over a cool dark card where oklch would turn it violet.
 //   - `status` is an Open / Addressed enum. Anything that is not
 //     'addressed' counts as open, so a note created with no status set still
 //     shows up in the queue.
@@ -58,8 +59,8 @@ export function noteSummary(note: string | undefined): string {
   return plain.length > 72 ? `${plain.slice(0, 71)}…` : plain;
 }
 
-// The note's state as a chip: open is filled with the note's own attention
-// tone, addressed with success.
+// The note's state as a chip: open in the attention tone, addressed in
+// success.
 const NoteStatus: TemplateOnlyComponent<{
   Args: { addressed: boolean };
   Element: HTMLSpanElement;
@@ -72,6 +73,19 @@ const NoteStatus: TemplateOnlyComponent<{
   />
 </template>;
 
+// The title is the note's first line unless cardInfo.name is set, so the
+// body only adds something when there is a name or more than that line.
+function bodyAddsToTitle(note: string | undefined, name: string | undefined) {
+  let text = note?.trim();
+  if (!text) return false;
+  if (name?.trim()) return true;
+  let lines = text
+    .split('\n')
+    .map((line) => line.trim())
+    .filter((line) => line.length > 0);
+  return lines.length > 1 || noteSummary(text).endsWith('…');
+}
+
 export class PretuiNote extends CardDef {
   static displayName = 'Sticky Note';
   static icon = StickyNoteIcon;
@@ -113,6 +127,12 @@ export class PretuiNote extends CardDef {
     get addressed() {
       return isAddressed(this.args.model.status);
     }
+    get showBody() {
+      return bodyAddsToTitle(
+        this.args.model.note,
+        this.args.model.cardInfo?.name,
+      );
+    }
 
     <template>
       <div class='note-isolated'>
@@ -134,7 +154,9 @@ export class PretuiNote extends CardDef {
             <p class='note-summary'><@fields.cardDescription /></p>
           {{/if}}
 
-          <div><@fields.note /></div>
+          {{#if this.showBody}}
+            <div><@fields.note /></div>
+          {{/if}}
 
           {{#if @model.target}}
             <Button
@@ -171,35 +193,38 @@ export class PretuiNote extends CardDef {
         /* the isolated page owns the scroll and the margin; the sticky sits
            on it as a card */
         .note-isolated {
-          --note-page-max-w: 40rem;
+          --_note-page-max-w: 40rem;
 
           height: 100%;
           overflow-y: auto;
           padding: var(--boxel-sp-lg);
         }
-        /* The sticky is a tint of --attention over --card with --foreground
-           text and --attention-ink labels, which hold contrast in light and
-           dark. An addressed note goes to the neutral --muted surface. */
+        /* The sticky is a tint of --attention over --card with
+           --card-foreground text and --attention-ink labels, which hold
+           contrast in light and dark. An addressed note goes to the neutral
+           --muted surface with --foreground. */
         .note-page {
           display: flex;
           flex-direction: column;
           gap: var(--boxel-sp-xs);
-          max-inline-size: var(--note-page-max-w);
+          max-inline-size: var(--_note-page-max-w);
+          overflow-wrap: break-word;
           margin-inline: auto;
           padding: var(--boxel-sp);
           border-radius: var(--boxel-border-radius);
           background-color: color-mix(
-            in oklch,
+            in oklab,
             var(--attention) 14%,
             var(--card)
           );
-          color: var(--foreground);
+          color: var(--card-foreground);
           box-shadow:
             0 0 0 1px var(--border),
             var(--shadow-sm);
         }
         .note-page[data-addressed='true'] {
           background-color: var(--muted);
+          color: var(--foreground);
         }
         .note-page[data-addressed='true']
           :is(.note-cap, .note-when, .note-foot) {
@@ -253,6 +278,12 @@ export class PretuiNote extends CardDef {
     get addressed() {
       return isAddressed(this.args.model.status);
     }
+    get showBody() {
+      return bodyAddsToTitle(
+        this.args.model.note,
+        this.args.model.cardInfo?.name,
+      );
+    }
     <template>
       <div
         class='sticky'
@@ -260,7 +291,10 @@ export class PretuiNote extends CardDef {
         data-test-pretui-note-embedded
       >
         <NoteStatus class='sticky-status' @addressed={{this.addressed}} />
-        <div class='sticky-body'><@fields.note /></div>
+        <h3 class='sticky-title'><@fields.cardTitle /></h3>
+        {{#if this.showBody}}
+          <div class='sticky-body'><@fields.note /></div>
+        {{/if}}
       </div>
       <style scoped>
         .sticky {
@@ -268,19 +302,28 @@ export class PretuiNote extends CardDef {
           flex-direction: column;
           gap: var(--boxel-sp-2xs);
           padding: var(--boxel-sp-xs);
+          overflow-wrap: break-word;
           background-color: color-mix(
-            in oklch,
+            in oklab,
             var(--attention) 14%,
             var(--card)
           );
-          color: var(--foreground);
+          color: var(--card-foreground);
         }
         .sticky[data-addressed='true'] {
           background-color: var(--muted);
+          color: var(--foreground);
         }
         .sticky-status {
           align-self: flex-start;
         }
+        /* a long note shows its first lines; the isolated view has the rest */
+        .sticky-body {
+          display: -webkit-box;
+          -webkit-box-orient: vertical;
+          -webkit-line-clamp: 4;
+          overflow: hidden;
+        }
       </style>
     </template>
   };
@@ -297,7 +340,9 @@ export class PretuiNote extends CardDef {
         data-addressed={{if this.addressed 'true'}}
         data-test-pretui-note-fitted
       >
-        <:badgeRow><NoteStatus @addressed={{this.addressed}} /></:badgeRow>
+        {{! badgeRight stays at the sizes where FittedCard hides the badge
+            row, so open and addressed never differ by fill alone }}
+        <:badgeRight><NoteStatus @addressed={{this.addressed}} /></:badgeRight>
         <:title><@fields.cardTitle /></:title>
         <:subtitle>
           {{#if @model.cardDescription}}
@@ -317,13 +362,12 @@ export class PretuiNote extends CardDef {
            thumbnail fades into the same tint the card is painted with */
         .nfit {
           --fc-image-fade-color: color-mix(
-            in oklch,
+            in oklab,
             var(--attention) 14%,
             var(--card)
           );
 
           background-color: var(--fc-image-fade-color);
-          color: var(--card-foreground);
         }
         .nfit[data-addressed='true'] {
           --fc-image-fade-color: var(--muted);

From 80fe6dc71f2b0417574ad99a5bdb04451c72e526 Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Thu, 8 Oct 2026 16:10:53 -0400
Subject: [PATCH 23/30] Link the array and CSS-variable knobs to their row
 labels, and describe the freestyle helpers accurately

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/components/usage-array.gts    | 14 +++++++++++--
 .../pretui/components/usage-css-variable.gts  |  6 ++++--
 .../components/usage-css-variable.test.gts    |  3 ++-
 packages/pretui/freestyle-controls.test.gts   |  2 +-
 packages/pretui/internal/freestyle.gts        | 20 ++++++-------------
 5 files changed, 25 insertions(+), 20 deletions(-)

diff --git a/packages/pretui/components/usage-array.gts b/packages/pretui/components/usage-array.gts
index 8e419546654..e4ea0077850 100644
--- a/packages/pretui/components/usage-array.gts
+++ b/packages/pretui/components/usage-array.gts
@@ -1,5 +1,6 @@
 // Pretui — UsageArray: an array argument with its knob.
 import Component from '@glimmer/component';
+import { guidFor } from '@ember/object/internals';
 import { Input } from './input';
 import { UsageArgument } from './usage-argument';
 import { PropReadOnly, PropRow, readOnlyText } from '../internal/freestyle';
@@ -34,6 +35,11 @@ export class UsageArray extends Component<UsageArraySignature> {
   get readOnlyValue() {
     return readOnlyText(this.args.value ?? this.args.defaultValue);
   }
+  controlId = `${guidFor(this)}-control`;
+  // the rail labels the control when there is one
+  get labelFor() {
+    return this.hasControl ? this.controlId : undefined;
+  }
   callOnInput = (raw: string) => {
     this.args.onInput?.(
       raw
@@ -45,12 +51,16 @@ export class UsageArray extends Component<UsageArraySignature> {
   <template>
     {{#if this.isProp}}
       {{#unless @hideControls}}
-        <PropRow @label={{@name}} @required={{@required}}>
+        <PropRow
+          @label={{@name}}
+          @required={{@required}}
+          @controlId={{this.labelFor}}
+        >
           {{#if this.hasControl}}
             <Input
               @value={{this.text}}
               @onInput={{this.callOnInput}}
-              aria-label={{@name}}
+              @controlId={{this.controlId}}
             />
           {{else}}
             <PropReadOnly @value={{this.readOnlyValue}} />
diff --git a/packages/pretui/components/usage-css-variable.gts b/packages/pretui/components/usage-css-variable.gts
index 37c8b6d655a..58b9791c7ee 100644
--- a/packages/pretui/components/usage-css-variable.gts
+++ b/packages/pretui/components/usage-css-variable.gts
@@ -1,5 +1,6 @@
 // Pretui — UsageCssVariable: a documented CSS custom property.
 import Component from '@glimmer/component';
+import { guidFor } from '@ember/object/internals';
 import { Input } from './input';
 import { UsageArgument } from './usage-argument';
 import { PropRow } from '../internal/freestyle';
@@ -28,17 +29,18 @@ export class UsageCssVariable extends Component<UsageCssVariableSignature> {
   get hasControl() {
     return this.args.onInput !== undefined;
   }
+  controlId = `${guidFor(this)}-control`;
   callOnInput = (v: string) => {
     this.args.onInput?.(v);
   };
   <template>
     {{#if this.isProp}}
       {{#if this.hasControl}}
-        <PropRow @label={{@name}}>
+        <PropRow @label={{@name}} @controlId={{this.controlId}}>
           <Input
             @value={{this.valueStr}}
             @onInput={{this.callOnInput}}
-            aria-label={{@name}}
+            @controlId={{this.controlId}}
           />
         </PropRow>
       {{/if}}
diff --git a/packages/pretui/components/usage-css-variable.test.gts b/packages/pretui/components/usage-css-variable.test.gts
index fa0659b6b94..95f081886a0 100644
--- a/packages/pretui/components/usage-css-variable.test.gts
+++ b/packages/pretui/components/usage-css-variable.test.gts
@@ -23,7 +23,8 @@ module('Pretui | components/usage-css-variable', function (hooks) {
     await render(<template><UsageCssVariable @mode='prop' @name='--pretui-gap' @value='8px' @onInput={{onInput}} /></template>);
     assert.strictEqual(document.querySelector('[data-test-pretui-prop-row-label]')?.textContent?.trim(), '--pretui-gap');
     let input = document.querySelector('[data-test-pretui-prop-row] input') as HTMLInputElement;
-    assert.strictEqual(input.getAttribute('aria-label'), '--pretui-gap');
+    let label = document.querySelector('[data-test-pretui-prop-row-label]');
+    assert.strictEqual(label?.getAttribute('for'), input.id, 'the rail is the field\'s label');
     assert.strictEqual(input.value, '8px');
     await fillIn(input, '12px');
     assert.deepEqual(seen, ['12px']);
diff --git a/packages/pretui/freestyle-controls.test.gts b/packages/pretui/freestyle-controls.test.gts
index 07072251cca..85b460ab8b2 100644
--- a/packages/pretui/freestyle-controls.test.gts
+++ b/packages/pretui/freestyle-controls.test.gts
@@ -115,7 +115,7 @@ module('Pretui | freestyle property controls', function (hooks) {
       await fillIn(controlLabelled('label'), 'New lot');
       await click('[aria-label="enabled"]');
       await fillIn(controlLabelled('count'), '8');
-      await fillIn('[aria-label="tags"]', 'green, spring');
+      await fillIn(controlLabelled('tags'), 'green, spring');
 
       assert.strictEqual(sink.stringValue, 'New lot');
       assert.strictEqual(sink.boolValue, true);
diff --git a/packages/pretui/internal/freestyle.gts b/packages/pretui/internal/freestyle.gts
index cc98478bb25..68a296d339f 100644
--- a/packages/pretui/internal/freestyle.gts
+++ b/packages/pretui/internal/freestyle.gts
@@ -1,14 +1,7 @@
-// Pretui — shared by the usage-page machinery: ember-freestyle, ported (verbatim-reuse directive) and dogfooded:
-// same invocation surface as addon/components/freestyle/usage (<:example>,
-// <:api as |Args|> with Args.String/Bool/Number/Array/Object/Component/
-// Action/Yield/Base, <:cssVars as |Css|>), but the machinery wears the kit —
-// Select/Input/Switch/Slider as knob controls, Table for the API docs, and
-// the Viewport frame around every example. Layout evolution (Chris): the
-// interactive knobs render as a right-hand PROPERTY LIST while the API table
-// below documents types/descriptions/defaults — the same <:api> block is
-// yielded twice through two lenses (prop / doc), so usage pages stay
-// verbatim-freestyle. Deliberate deltas: no ember-freestyle service, plain
-// <pre> for @source, labeled controls.
+// Pretui — shared pieces of the usage pages (components/freestyle-usage.gts
+// and the usage-* argument components): PropRow, one row of the property
+// list; PropReadOnly, a knob's value when it has no control; the
+// isPresent/readOnlyText helpers; and the ArgsMode/UsagePresetSignature types.
 import type { TemplateOnlyComponent } from '@ember/component/template-only';
 import { VisuallyHidden } from '../components/visually-hidden';
 
@@ -63,10 +56,10 @@ export const PropRow: TemplateOnlyComponent<PropRowSignature> = <template>
   <style scoped>
     /* workbench inspector row: label rail left, control right */
     .proprow {
-      --proprow-label-w: 8rem;
+      --_proprow-label-w: 8rem;
 
       display: grid;
-      grid-template-columns: var(--proprow-label-w) minmax(0, 1fr);
+      grid-template-columns: var(--_proprow-label-w) minmax(0, 1fr);
       gap: var(--boxel-sp-xs);
       align-items: center;
       padding-block: var(--boxel-sp-3xs);
@@ -100,7 +93,6 @@ export const PropReadOnly: TemplateOnlyComponent<PropReadOnlySignature> =
     <style scoped>
       .proprow-readonly {
         display: block;
-        min-width: 0;
         overflow-wrap: break-word;
         color: var(--muted-foreground);
         font-family: var(--font-mono);

From 64c2af88b02bbc2d6b2fb97f33e22a7f4a26a148 Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Thu, 8 Oct 2026 16:10:54 -0400
Subject: [PATCH 24/30] Put ...attributes last on Autocomplete,
 SegmentedControl, SlidingHighlight, Toast and Viewport

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/components/autocomplete.gts      | 2 +-
 packages/pretui/components/segmented-control.gts | 2 +-
 packages/pretui/components/sliding-highlight.gts | 2 +-
 packages/pretui/components/toast.gts             | 2 +-
 packages/pretui/components/viewport.gts          | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/pretui/components/autocomplete.gts b/packages/pretui/components/autocomplete.gts
index fa78beaefd6..8d9527ee90a 100644
--- a/packages/pretui/components/autocomplete.gts
+++ b/packages/pretui/components/autocomplete.gts
@@ -712,12 +712,12 @@ export class Autocomplete extends Component<AutocompleteSignature> {
       data-busy={{if this.busy 'true'}}
       data-invalid={{if this.invalid 'true'}}
       data-disabled={{if this.inert 'true'}}
-      ...attributes
       {{ownsTimers this.timers}}
       {{listen 'focusout' this.handleFocusOut}}
       {{listen 'mouseover' this.handleHover}}
       {{listen 'mousedown' this.handlePress}}
       data-test-pretui-autocomplete
+      ...attributes
     >
       {{#if this.ownsLabel}}
         <label for={{this.inputId}}><VisuallyHidden
diff --git a/packages/pretui/components/segmented-control.gts b/packages/pretui/components/segmented-control.gts
index 8ed34873a2d..99d01a7d5a2 100644
--- a/packages/pretui/components/segmented-control.gts
+++ b/packages/pretui/components/segmented-control.gts
@@ -72,9 +72,9 @@ export class SegmentedControl extends Component<SegmentedControlSignature> {
       class='pretui-seg'
       role='radiogroup'
       aria-label={{@label}}
-      ...attributes
       {{slidingHighlight}}
       data-test-pretui-segmented
+      ...attributes
     >
       <SlidingHighlight @variant='pill' />
       {{#each this.options as |option|}}
diff --git a/packages/pretui/components/sliding-highlight.gts b/packages/pretui/components/sliding-highlight.gts
index b46a86b554a..76a304929a5 100644
--- a/packages/pretui/components/sliding-highlight.gts
+++ b/packages/pretui/components/sliding-highlight.gts
@@ -174,8 +174,8 @@ export class SlidingHighlight extends Component<SlidingHighlightSignature> {
       data-variant={{this.variant}}
       style={{this.style}}
       aria-hidden='true'
-      ...attributes
       data-test-pretui-sliding-highlight
+      ...attributes
     >{{yield}}</span>
     <style scoped>
       @layer PretComponent {
diff --git a/packages/pretui/components/toast.gts b/packages/pretui/components/toast.gts
index c31d7deda04..37d5c047108 100644
--- a/packages/pretui/components/toast.gts
+++ b/packages/pretui/components/toast.gts
@@ -15,7 +15,7 @@ export interface ToastSignature {
 }
 
 export const Toast: TemplateOnlyComponent<ToastSignature> = <template>
-  <div class='pretui-toast' role='status' ...attributes data-test-pretui-toast>
+  <div class='pretui-toast' role='status' data-test-pretui-toast ...attributes>
     {{#if (has-block 'icon')}}{{yield to='icon'}}{{/if}}
     <div class='pretui-toast-body'>
       <div class='pretui-toast-title'>{{@title}}</div>
diff --git a/packages/pretui/components/viewport.gts b/packages/pretui/components/viewport.gts
index e352a42b16f..e47f81d6b6d 100644
--- a/packages/pretui/components/viewport.gts
+++ b/packages/pretui/components/viewport.gts
@@ -164,7 +164,7 @@ export class Viewport extends Component<ViewportSignature> {
     };
   });
   <template>
-    <div class='pretui-viewport' ...attributes data-test-pretui-viewport>
+    <div class='pretui-viewport' data-test-pretui-viewport ...attributes>
       <div class='pretui-viewport-bar'>
         <SegmentedControl
           class='pretui-viewport-modes'

From 0de567836b1f1eda73997649749c16cbc0ef90a5 Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Thu, 8 Oct 2026 17:06:56 -0400
Subject: [PATCH 25/30] Caption a dragged Viewport width by its mode, and drop
 the specimen label it no longer needs

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/components/freestyle-usage.gts |  2 +-
 packages/pretui/components/freestyle-usage.md  |  2 +-
 packages/pretui/components/viewport.gts        | 13 ++++---------
 packages/pretui/components/viewport.md         |  3 +--
 packages/pretui/viewport.test.gts              |  6 +++---
 5 files changed, 10 insertions(+), 16 deletions(-)

diff --git a/packages/pretui/components/freestyle-usage.gts b/packages/pretui/components/freestyle-usage.gts
index ae4ad5479ec..71a6d550b13 100644
--- a/packages/pretui/components/freestyle-usage.gts
+++ b/packages/pretui/components/freestyle-usage.gts
@@ -69,7 +69,7 @@ export const FreestyleUsage: TemplateOnlyComponent<FreestyleUsageSignature> =
       <div class='pretui-usage-stage'>
         <div class='pretui-usage-preview-col'>
           <div class='wb-panel'>
-            <Viewport @defaultMode={{@viewportMode}} @label={{@name}}>
+            <Viewport @defaultMode={{@viewportMode}}>
               {{yield to='example'}}
             </Viewport>
             {{#if @source}}
diff --git a/packages/pretui/components/freestyle-usage.md b/packages/pretui/components/freestyle-usage.md
index 37bee179771..c7145b7aff9 100644
--- a/packages/pretui/components/freestyle-usage.md
+++ b/packages/pretui/components/freestyle-usage.md
@@ -36,7 +36,7 @@ No pattern governs it; it is a page composed of the kit's own components, and it
 Gaps worth knowing, because a documentation surface is read by exactly the people who care about these:
 
 - **Only part of the page has heading structure.** Properties, API and CSS Variables are headed by `h2`s, so heading navigation reaches the knobs and the tables; Properties is an `<aside>` named "Properties", and each table carries its heading as its name. The description and the example have no heading or region, so a screen-reader user cannot jump to "the example".
-- **`@name` is not a heading here.** It only labels the Viewport's artboard; the page's heading is the Spec's `h1`, and the section titles are `h2`s under it.
+- **`@name` is not rendered.** It is accepted for ember-freestyle parity; the page's heading is the Spec's `h1`, and the section titles are `h2`s under it.
 - **The knobs and the API table describe the same arguments and are not linked.** A user reading a row in the docs table has no route to the control that changes it.
 - **The `<code>` source has no language annotation.** It scrolls inside a named region ("Usage source") with a tab stop, so a keyboard user can reach the end of a long line, and the Copy button stays in view beside it.
 - **Changing a knob re-renders the example silently.** A `role="status"` region would make the cause-and-effect available; without it, a screen-reader user changing a Select has no confirmation that anything happened.
diff --git a/packages/pretui/components/viewport.gts b/packages/pretui/components/viewport.gts
index e47f81d6b6d..b156c6d02b3 100644
--- a/packages/pretui/components/viewport.gts
+++ b/packages/pretui/components/viewport.gts
@@ -67,9 +67,6 @@ export interface ViewportSignature {
       | 'grid'
       | 'narrow'
       | 'wide';
-    // the specimen's name, e.g. the component name: the caption of a
-    // dragged width ("Name · <width>"); presets are captioned by mode
-    label?: string;
   };
   Blocks: { default: [] };
   Element: HTMLDivElement;
@@ -107,13 +104,11 @@ export class Viewport extends Component<ViewportSignature> {
   get widthLabel() {
     return this.artboardWidth ? `${this.artboardWidth}px` : '100%';
   }
-  // a preset (Fill or a device) is named by its mode, like the 3-up
-  // captions; a dragged width names the specimen
+  // named by the selected mode, like the 3-up captions; a dragged width is
+  // Fill, so it reads "Fill · 412px"
   get frameCaption() {
-    let device = this.customWidth
-      ? undefined
-      : VIEWPORT_MODES.find((m) => m.value === this.mode)?.label;
-    return `${device ?? this.args.label ?? 'Specimen'} · ${this.widthLabel}`;
+    let mode = VIEWPORT_MODES.find((m) => m.value === this.mode)?.label;
+    return `${mode} · ${this.widthLabel}`;
   }
   // Drag-to-resize on the artboard edge. Pointer capture keeps every event
   // on the handle — no document listeners (backdrop-close discipline).
diff --git a/packages/pretui/components/viewport.md b/packages/pretui/components/viewport.md
index 425466a660e..591c8692add 100644
--- a/packages/pretui/components/viewport.md
+++ b/packages/pretui/components/viewport.md
@@ -7,7 +7,6 @@ The artboard: a framed stage that renders its content at a chosen device width,
 ```
 @defaultMode? 'fill' | 'phone' | 'tablet' | 'desktop' | 'bp' | 'inline' | 'grid'
               ('narrow' and 'wide' are kept as aliases for 'phone' and 'desktop')
-@label?   — the specimen's name, captioning a dragged width as "Name · <width>"; presets are captioned by mode
 <:default>
 ```
 
@@ -17,7 +16,7 @@ The artboard: a framed stage that renders its content at a chosen device width,
 
 **The stage** takes one of four surfaces (Background, a translucent veil of the page color; Card; Sidebar; Inset) and an optional Padding. Both apply to the framed modes and the grid cells; Inline sits in prose, so the two controls are disabled there.
 
-**The caption is live**: `"Phone · 320px"` for a preset, `"Fill · 100%"` for the full width, and `"Name · 412px"` once you drag or use the width slider, updating as it moves. A dragged width belongs to Fill, so clicking a preset afterwards always resets it. An artboard whose label does not track its real width is worse than no label, because it invites you to trust it.
+**The caption is live**: `"Phone · 320px"` for a preset, `"Fill · 100%"` for the full width, and `"Fill · 412px"` once you drag or use the width slider, updating as it moves. A dragged width belongs to Fill, so clicking a preset afterwards always resets it. An artboard whose label does not track its real width is worse than no label, because it invites you to trust it.
 
 **The drag handle uses pointer capture, not document listeners.** Same discipline as **Popover**'s backdrop and **SplitPanes**' handle: the listeners live on the handle, so teardown only unbinds them and clears the resize flag. Only the primary button starts a drag.
 
diff --git a/packages/pretui/viewport.test.gts b/packages/pretui/viewport.test.gts
index 968224432ac..065a088e08d 100644
--- a/packages/pretui/viewport.test.gts
+++ b/packages/pretui/viewport.test.gts
@@ -23,7 +23,7 @@ module('Pretui | Viewport artboard', function (hooks) {
 
   test('R1: presets set exact widths; R5: caption is honest', async function (assert) {
     await render(<template>
-      <Viewport @label='Probe'><span>content</span></Viewport>
+      <Viewport><span>content</span></Viewport>
     </template>);
 
     assert.strictEqual(
@@ -51,7 +51,7 @@ module('Pretui | Viewport artboard', function (hooks) {
 
   test('R3: 3-up renders all three labeled breakpoints', async function (assert) {
     await render(<template>
-      <Viewport @label='Probe'><span>content</span></Viewport>
+      <Viewport><span>content</span></Viewport>
     </template>);
     await click(segButton('bp'));
     let boards = Array.from(
@@ -72,7 +72,7 @@ module('Pretui | Viewport artboard', function (hooks) {
 
   test('R2/R9: surface and gutter are explicit, reflected settings', async function (assert) {
     await render(<template>
-      <Viewport @label='Probe'><span>content</span></Viewport>
+      <Viewport><span>content</span></Viewport>
     </template>);
     let body = () =>
       document.querySelector('[data-test-pretui-artboard-body]') as HTMLElement;

From 1d4711c40893b2e00429b328043f7761790092de Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Thu, 8 Oct 2026 18:21:17 -0400
Subject: [PATCH 26/30] Fit Viewport, Toast and the Spec page to narrow panels,
 scroll code-mode previews, and wrap long names

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 .../pretui/components/segmented-control.gts   |   3 +-
 .../pretui/components/segmented-control.md    |   2 +-
 packages/pretui/components/step-list.gts      | 168 ++++++++++++++----
 packages/pretui/components/toast.gts          |  12 +-
 packages/pretui/components/viewport.gts       |   8 +-
 5 files changed, 151 insertions(+), 42 deletions(-)

diff --git a/packages/pretui/components/segmented-control.gts b/packages/pretui/components/segmented-control.gts
index 99d01a7d5a2..66498580159 100644
--- a/packages/pretui/components/segmented-control.gts
+++ b/packages/pretui/components/segmented-control.gts
@@ -158,10 +158,9 @@ export class SegmentedControl extends Component<SegmentedControlSignature> {
           opacity: 0;
           pointer-events: none;
         }
-        /* inset: the rail's padding and gap are thinner than an outside ring */
+        /* the radio is visually hidden, so its label shows the focus */
         .pretui-seg-item:has(.pretui-seg-input:focus-visible) {
           outline: 2px solid var(--ring);
-          outline-offset: -2px;
         }
         /* the label sits on the pill's --card face */
         .pretui-seg-item[data-state='active'] {
diff --git a/packages/pretui/components/segmented-control.md b/packages/pretui/components/segmented-control.md
index 4439e46d658..a9c5fdc31f2 100644
--- a/packages/pretui/components/segmented-control.md
+++ b/packages/pretui/components/segmented-control.md
@@ -25,7 +25,7 @@ Pretui's improvement is the shared traveling highlight. shadcn's Tabs-as-segment
 
 **A radiogroup of native radios.** The rail is `role="radiogroup"`, named by `@label`; pass it whenever no visible heading names the control. Each segment is a visually hidden `<input type="radio">` sharing one `name`, with its `<label>` as the visible face, so the browser supplies the APG radio contract: the group is one tab stop, arrow keys move and select, the checked state is exposed, and the value takes part in a form. There is no keyboard code of our own.
 
-- **Focus** draws a 2px `--ring` outline inside the label of the focused radio (`:has(:focus-visible)`), inset because the rail's padding is thinner than an outside ring.
+- **Focus** draws a 2px `--ring` outline on the label of the focused radio (`:has(:focus-visible)`), since the radio itself is visually hidden.
 - **Disabled** dims the whole rail; there is no per-option disabled, unlike **RadioGroup**.
 - **The selected label is bold**, and a hidden bold copy of each label (`visibility: hidden`, so it never reaches the accessible name) reserves that width, so selection never shifts the segments.
 - **A controlled `@value` that rejects a change** puts the radio back; focus stays on the radio the reader moved to.
diff --git a/packages/pretui/components/step-list.gts b/packages/pretui/components/step-list.gts
index c9e43fd45fb..a8d1a1a6d28 100644
--- a/packages/pretui/components/step-list.gts
+++ b/packages/pretui/components/step-list.gts
@@ -257,14 +257,19 @@ export class StepList extends Component<StepListSignature> {
               {{else if step.isError}}
                 <ExclamationMarkIcon width='9' height='9' stroke-width='4' />
               {{else if step.isBlocked}}
-                {{!-- a bar across the marker — "the way through is shut", and
-                    unmistakably not the error exclamation beside it --}}
+                {{! a bar across the marker — "the way through is shut", and
+                    unmistakably not the error exclamation beside it }}
                 <MinusIcon width='9' height='9' stroke-width='4' />
               {{else if step.isRunning}}
-                {{!-- a play triangle — "the machine is working on this one".
+                {{! a play triangle — "the machine is working on this one".
                     Static on purpose: a spinning marker would be motion that
-                    encodes nothing the tone and the state text do not --}}
-                <PlayerPlayIcon width='9' height='9' stroke-width='4' fill='currentColor' />
+                    encodes nothing the tone and the state text do not }}
+                <PlayerPlayIcon
+                  width='9'
+                  height='9'
+                  stroke-width='4'
+                  fill='currentColor'
+                />
               {{else}}
                 {{step.number}}
               {{/if}}
@@ -338,50 +343,137 @@ export class StepList extends Component<StepListSignature> {
            --pretui-step-error-marker-bg (etc.) on any ancestor to re-tone one
            state without touching the rest */
         .pretui-step[data-state='upcoming'] {
-          --pretui-step-tone: var(--pretui-step-upcoming-tone, var(--muted-foreground));
-          --pretui-step-marker-bg: var(--pretui-step-upcoming-marker-bg, var(--inset));
-          --pretui-step-marker-fg: var(--pretui-step-upcoming-marker-fg, var(--muted-foreground));
+          --pretui-step-tone: var(
+            --pretui-step-upcoming-tone,
+            var(--muted-foreground)
+          );
+          --pretui-step-marker-bg: var(
+            --pretui-step-upcoming-marker-bg,
+            var(--inset)
+          );
+          --pretui-step-marker-fg: var(
+            --pretui-step-upcoming-marker-fg,
+            var(--muted-foreground)
+          );
           --pretui-step-ring: var(--pretui-step-upcoming-ring, var(--border));
-          --pretui-step-bar-fill: var(--pretui-step-upcoming-bar, var(--border));
+          --pretui-step-bar-fill: var(
+            --pretui-step-upcoming-bar,
+            var(--border)
+          );
         }
         .pretui-step[data-state='current'] {
-          --pretui-step-tone: var(--pretui-step-current-tone, var(--foreground));
-          --pretui-step-marker-bg: var(--pretui-step-current-marker-bg, var(--primary));
-          --pretui-step-marker-fg: var(--pretui-step-current-marker-fg, var(--primary-foreground));
-          --pretui-step-ring: var(--pretui-step-current-ring, color-mix(in oklch, var(--primary) 70%, var(--border)));
-          --pretui-step-bar-fill: var(--pretui-step-current-bar, var(--primary));
+          --pretui-step-tone: var(
+            --pretui-step-current-tone,
+            var(--foreground)
+          );
+          --pretui-step-marker-bg: var(
+            --pretui-step-current-marker-bg,
+            var(--primary)
+          );
+          --pretui-step-marker-fg: var(
+            --pretui-step-current-marker-fg,
+            var(--primary-foreground)
+          );
+          --pretui-step-ring: var(
+            --pretui-step-current-ring,
+            color-mix(in oklch, var(--primary) 70%, var(--border))
+          );
+          --pretui-step-bar-fill: var(
+            --pretui-step-current-bar,
+            var(--primary)
+          );
         }
         .pretui-step[data-state='complete'] {
-          --pretui-step-tone: var(--pretui-step-complete-tone, var(--muted-foreground));
-          --pretui-step-marker-bg: var(--pretui-step-complete-marker-bg, color-mix(in oklch, var(--success) 15%, var(--card)));
-          --pretui-step-marker-fg: var(--pretui-step-complete-marker-fg, var(--success-ink));
-          --pretui-step-ring: var(--pretui-step-complete-ring, color-mix(in oklch, var(--success) 40%, var(--border)));
-          --pretui-step-bar-fill: var(--pretui-step-complete-bar, var(--success));
+          --pretui-step-tone: var(
+            --pretui-step-complete-tone,
+            var(--muted-foreground)
+          );
+          --pretui-step-marker-bg: var(
+            --pretui-step-complete-marker-bg,
+            color-mix(in oklch, var(--success) 15%, var(--card))
+          );
+          --pretui-step-marker-fg: var(
+            --pretui-step-complete-marker-fg,
+            var(--success-ink)
+          );
+          --pretui-step-ring: var(
+            --pretui-step-complete-ring,
+            color-mix(in oklch, var(--success) 40%, var(--border))
+          );
+          --pretui-step-bar-fill: var(
+            --pretui-step-complete-bar,
+            var(--success)
+          );
         }
         .pretui-step[data-state='error'] {
-          --pretui-step-tone: var(--pretui-step-error-tone, var(--destructive-ink));
-          --pretui-step-marker-bg: var(--pretui-step-error-marker-bg, color-mix(in oklch, var(--destructive) 12%, var(--card)));
-          --pretui-step-marker-fg: var(--pretui-step-error-marker-fg, var(--destructive-ink));
-          --pretui-step-ring: var(--pretui-step-error-ring, color-mix(in oklch, var(--destructive) 45%, var(--border)));
-          --pretui-step-bar-fill: var(--pretui-step-error-bar, var(--destructive));
+          --pretui-step-tone: var(
+            --pretui-step-error-tone,
+            var(--destructive-ink)
+          );
+          --pretui-step-marker-bg: var(
+            --pretui-step-error-marker-bg,
+            color-mix(in oklch, var(--destructive) 12%, var(--card))
+          );
+          --pretui-step-marker-fg: var(
+            --pretui-step-error-marker-fg,
+            var(--destructive-ink)
+          );
+          --pretui-step-ring: var(
+            --pretui-step-error-ring,
+            color-mix(in oklch, var(--destructive) 45%, var(--border))
+          );
+          --pretui-step-bar-fill: var(
+            --pretui-step-error-bar,
+            var(--destructive)
+          );
         }
         /* running now: a light info tint with an info-ink play triangle, so it
            never reads like 'current' (the primary hue filled solid, with a
            number) at a glance */
         .pretui-step[data-state='in-progress'] {
-          --pretui-step-tone: var(--pretui-step-in-progress-tone, var(--foreground));
-          --pretui-step-marker-bg: var(--pretui-step-in-progress-marker-bg, color-mix(in oklch, var(--info) 16%, var(--card)));
-          --pretui-step-marker-fg: var(--pretui-step-in-progress-marker-fg, var(--info-ink));
-          --pretui-step-ring: var(--pretui-step-in-progress-ring, color-mix(in oklch, var(--info) 55%, var(--border)));
-          --pretui-step-bar-fill: var(--pretui-step-in-progress-bar, var(--info));
+          --pretui-step-tone: var(
+            --pretui-step-in-progress-tone,
+            var(--foreground)
+          );
+          --pretui-step-marker-bg: var(
+            --pretui-step-in-progress-marker-bg,
+            color-mix(in oklch, var(--info) 16%, var(--card))
+          );
+          --pretui-step-marker-fg: var(
+            --pretui-step-in-progress-marker-fg,
+            var(--info-ink)
+          );
+          --pretui-step-ring: var(
+            --pretui-step-in-progress-ring,
+            color-mix(in oklch, var(--info) 55%, var(--border))
+          );
+          --pretui-step-bar-fill: var(
+            --pretui-step-in-progress-bar,
+            var(--info)
+          );
         }
         /* cannot proceed: warning tone, not destructive — nothing has failed */
         .pretui-step[data-state='blocked'] {
-          --pretui-step-tone: var(--pretui-step-blocked-tone, var(--foreground));
-          --pretui-step-marker-bg: var(--pretui-step-blocked-marker-bg, color-mix(in oklch, var(--warning) 14%, var(--card)));
-          --pretui-step-marker-fg: var(--pretui-step-blocked-marker-fg, var(--warning-ink));
-          --pretui-step-ring: var(--pretui-step-blocked-ring, color-mix(in oklch, var(--warning) 50%, var(--border)));
-          --pretui-step-bar-fill: var(--pretui-step-blocked-bar, var(--warning));
+          --pretui-step-tone: var(
+            --pretui-step-blocked-tone,
+            var(--foreground)
+          );
+          --pretui-step-marker-bg: var(
+            --pretui-step-blocked-marker-bg,
+            color-mix(in oklch, var(--warning) 14%, var(--card))
+          );
+          --pretui-step-marker-fg: var(
+            --pretui-step-blocked-marker-fg,
+            var(--warning-ink)
+          );
+          --pretui-step-ring: var(
+            --pretui-step-blocked-ring,
+            color-mix(in oklch, var(--warning) 50%, var(--border))
+          );
+          --pretui-step-bar-fill: var(
+            --pretui-step-blocked-bar,
+            var(--warning)
+          );
         }
         .pretui-step-marker {
           display: inline-grid;
@@ -429,7 +521,11 @@ export class StepList extends Component<StepListSignature> {
           background-color: var(--border);
         }
         .pretui-step[data-state='complete'] .pretui-step-connector {
-          background-color: color-mix(in oklch, var(--success) 45%, var(--border));
+          background-color: color-mix(
+            in oklch,
+            var(--success) 45%,
+            var(--border)
+          );
         }
         /* ── track variant ── equal-width bars, caption beneath each. The
            caption keeps the marker glyph, so 'complete' is carried by shape
@@ -505,7 +601,7 @@ export class StepList extends Component<StepListSignature> {
             gap: var(--boxel-sp-2xs);
           }
           .pretui-steplist[data-variant='track'] .pretui-step {
-            grid-template-columns: 0.875rem auto minmax(0, 1fr);
+            grid-template-columns: 2rem auto minmax(0, 1fr);
             grid-template-areas: 'bar marker label';
             gap: var(--boxel-sp-2xs);
           }
diff --git a/packages/pretui/components/toast.gts b/packages/pretui/components/toast.gts
index 37d5c047108..937d25d0611 100644
--- a/packages/pretui/components/toast.gts
+++ b/packages/pretui/components/toast.gts
@@ -16,7 +16,9 @@ export interface ToastSignature {
 
 export const Toast: TemplateOnlyComponent<ToastSignature> = <template>
   <div class='pretui-toast' role='status' data-test-pretui-toast ...attributes>
-    {{#if (has-block 'icon')}}{{yield to='icon'}}{{/if}}
+    {{#if (has-block 'icon')}}<span class='pretui-toast-icon'>{{yield
+          to='icon'
+        }}</span>{{/if}}
     <div class='pretui-toast-body'>
       <div class='pretui-toast-title'>{{@title}}</div>
       {{#if @message}}<div class='pretui-toast-msg'>{{@message}}</div>
@@ -48,7 +50,13 @@ export const Toast: TemplateOnlyComponent<ToastSignature> = <template>
         padding: var(--boxel-sp-2xs) var(--boxel-sp-xs);
         font-size: var(--boxel-font-size-xs);
         width: max-content;
-        max-width: var(--pretui-toast-max-w);
+        /* never wider than its container, so a narrow column wraps it */
+        max-width: min(var(--pretui-toast-max-w), 100%);
+      }
+      /* the icon keeps its size when the message wraps */
+      .pretui-toast-icon {
+        display: inline-flex;
+        flex: none;
       }
       .pretui-toast-body {
         display: grid;
diff --git a/packages/pretui/components/viewport.gts b/packages/pretui/components/viewport.gts
index b156c6d02b3..fbd7557945e 100644
--- a/packages/pretui/components/viewport.gts
+++ b/packages/pretui/components/viewport.gts
@@ -306,7 +306,10 @@ export class Viewport extends Component<ViewportSignature> {
           --pretui-viewport-tile-min-w: 12.5rem;
           --pretui-viewport-cell-min-h: 4rem;
 
+          /* one column that may shrink below its content, so a wide artboard
+             pans inside the canvas instead of widening the whole viewport */
           display: grid;
+          grid-template-columns: minmax(0, 1fr);
           min-width: 0;
         }
         /* While the width handle is being dragged, nothing in the viewport is
@@ -324,6 +327,7 @@ export class Viewport extends Component<ViewportSignature> {
           justify-content: space-between;
           gap: var(--boxel-sp-sm);
           flex-wrap: wrap;
+          min-width: 0;
           min-height: var(--pretui-viewport-bar-min-h);
           padding: var(--boxel-sp-2xs) var(--boxel-sp-sm);
           box-shadow: inset 0 -1px 0 var(--border);
@@ -340,7 +344,7 @@ export class Viewport extends Component<ViewportSignature> {
           align-items: center;
           gap: var(--boxel-sp-xs);
           flex: 1;
-          min-width: var(--pretui-viewport-width-min-w);
+          min-width: min(var(--pretui-viewport-width-min-w), 100%);
           max-width: var(--pretui-viewport-width-max-w);
         }
         .pretui-viewport-width > :first-child {
@@ -356,8 +360,10 @@ export class Viewport extends Component<ViewportSignature> {
         }
         .pretui-viewport-settings {
           display: flex;
+          flex-wrap: wrap;
           align-items: center;
           gap: var(--boxel-sp-sm);
+          min-width: 0;
         }
         .pretui-viewport-surface {
           width: var(--pretui-viewport-surface-w);

From 9dcdf684b3de546600317fe25e67f3aa9921dc36 Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Thu, 8 Oct 2026 18:21:19 -0400
Subject: [PATCH 27/30] Show Spec flags as switches, caption fields in sentence
 case, fill and explain the featured star, and scroll write-up code blocks

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/pretui-component.gts | 166 +++++++++++++++++----------
 1 file changed, 103 insertions(+), 63 deletions(-)

diff --git a/packages/pretui/pretui-component.gts b/packages/pretui/pretui-component.gts
index 3859842283d..2a0ccb88a0e 100644
--- a/packages/pretui/pretui-component.gts
+++ b/packages/pretui/pretui-component.gts
@@ -27,6 +27,7 @@ import { tracked } from '@glimmer/tracking';
 import { on } from '@ember/modifier';
 import { modifier } from 'ember-modifier';
 import { fn } from '@ember/helper';
+import { not } from '@cardstack/boxel-ui/helpers';
 import StarIcon from '@cardstack/boxel-icons/star';
 import type { Query, RealmResourceIdentifier } from '@cardstack/runtime-common';
 import { ThemeFrame } from './components/theme-frame';
@@ -36,6 +37,8 @@ import { StatusChip } from './components/status-chip';
 import { Chip } from './components/chip';
 import { Token } from './components/token';
 import { Button } from './components/button';
+import { Switch } from './components/switch';
+import { Tooltip } from './components/tooltip';
 import { VisuallyHidden } from './components/visually-hidden';
 import { Textarea } from './components/textarea';
 import { StepList } from './components/step-list';
@@ -189,6 +192,12 @@ class WriteupFold extends GlimmerComponent<WriteupFoldSignature> {
 
         padding: var(--boxel-sp-sm);
       }
+      /* highlighted code joins its words with non-breaking spaces, so a long
+         line can't wrap; it scrolls inside its block instead of being
+         clipped by the fold */
+      .wb-fold-prose :deep(pre) {
+        overflow-x: auto;
+      }
       /* closed, the toggle sits over a fade into the panel's surface; open,
          it follows the content */
       .wb-fold-more {
@@ -386,6 +395,8 @@ export class PretUISpec extends Spec {
   // prose citation ('shadcn Button · wa-button'), not Spec's `ref` CodeRef
   @field refs = contains(StringField);
   @field buildsOn = contains(StringField);
+  /** a hand-picked flagship of the kit, the components to look at first;
+   *  shown as a gold star on the Spec page and its fitted card */
   @field featured = contains(BooleanField);
   @field isNew = contains(BooleanField);
   @field hasDesign = contains(BooleanField);
@@ -624,11 +635,16 @@ export class PretUISpec extends Spec {
                 @tone={{stageTone @model.stage}}
               />
               {{#if @model.isNew}}<Chip @label='New' @tone='attention' />{{/if}}
-              {{#if @model.featured}}<Chip @tone='warning' @dot={{false}}><StarIcon
-                    width='12'
-                    height='12'
-                    aria-hidden='true'
-                  /><VisuallyHidden>Featured</VisuallyHidden></Chip>{{/if}}
+              {{#if @model.featured}}
+                <Tooltip @content='Featured: a flagship component' @side='bottom'>
+                  <Chip @tone='warning' @dot={{false}}><StarIcon
+                      class='wb-star'
+                      width='12'
+                      height='12'
+                      aria-hidden='true'
+                    /><VisuallyHidden>Featured: a flagship component</VisuallyHidden></Chip>
+                </Tooltip>
+              {{/if}}
             </div>
             <div class='wb-grow'></div>
             <ThemeControls />
@@ -811,13 +827,13 @@ export class PretUISpec extends Spec {
         </article>
       </ThemeFrame>
       <style scoped>
-        /* the isolated root: exactly the card's height and the one scroller, so
-           the sticky topbar sticks to it and an overscroll can't bounce past
-           the island or carry on into the page behind */
+        /* the isolated root: the card's height and its scroller. No
+           overscroll-behavior: where a host sizes the card to its content
+           (code mode's preview), the frame has nothing to scroll and the
+           wheel has to pass up to the host's scroller */
         .wb-frame {
           height: 100%;
           overflow-y: auto;
-          overscroll-behavior: none;
         }
         .page {
           --_wb-topbar-h: 2.75rem;
@@ -838,7 +854,10 @@ export class PretUISpec extends Spec {
 
           min-height: 100%;
           padding: 0 var(--_wb-page-gutter) var(--boxel-sp-2xl);
+          /* one column that may shrink below its content, so a long name
+             breaks instead of widening the page */
           display: grid;
+          grid-template-columns: minmax(0, 1fr);
           gap: var(--boxel-sp);
           align-content: start;
         }
@@ -917,6 +936,10 @@ export class PretUISpec extends Spec {
         .wb-grow {
           flex: 1;
         }
+        /* the icon set's star is outline-only; filled reads as a flag */
+        .wb-star {
+          fill: currentColor;
+        }
         .wb-work {
           min-width: 0;
         }
@@ -1150,11 +1173,15 @@ export class PretUISpec extends Spec {
           <div class='fit-body'>
             <div class='fit-name'>
               {{@model.componentName}}
-              {{#if @model.featured}}<span class='fit-star'><StarIcon
+              {{#if @model.featured}}<span
+                  class='fit-star'
+                  title='Featured: a flagship component'
+                ><StarIcon
+                    class='wb-star'
                     width='12'
                     height='12'
                     aria-hidden='true'
-                  /><VisuallyHidden>Featured</VisuallyHidden></span>{{/if}}
+                  /><VisuallyHidden>Featured: a flagship component</VisuallyHidden></span>{{/if}}
             </div>
             <div class='fit-sub'>
               <span>{{if
@@ -1233,6 +1260,10 @@ export class PretUISpec extends Spec {
         .fit-star {
           color: var(--warning-ink);
         }
+        /* the icon set's star is outline-only; filled reads as a flag */
+        .wb-star {
+          fill: currentColor;
+        }
         .fit-sub {
           display: flex;
           gap: var(--boxel-sp-xs);
@@ -1360,6 +1391,13 @@ export class PretUISpec extends Spec {
   static edit = class Edit extends Component<typeof PretUISpec> {
     // ids for the captions that name editors a <label> can't wrap
     captionId = (key: string) => `${guidFor(this)}-${key}`;
+    // the yes/no signals are switches that write the field directly
+    setFlag = (
+      key: 'featured' | 'isNew' | 'hasDesign' | 'hasExamples' | 'liveInUse',
+      on: boolean,
+    ) => {
+      this.args.model[key] = on;
+    };
     <template>
       <div class='wb-edit'>
         <fieldset class='wb-group'>
@@ -1413,54 +1451,55 @@ export class PretUISpec extends Spec {
           </div>
         </fieldset>
 
-        {{! editors a <label> can't wrap (yes/no radios, the tag list, the
-            linked file with its Remove button) sit in a named group instead:
-            a wrapping label would activate their first control on any click }}
+        {{! editors a <label> can't wrap (the tag list, the linked file with
+            its Remove button) sit in a named group instead: a wrapping label
+            would activate their first control on any click. The yes/no
+            signals are single switches, so their label does wrap them. }}
         <fieldset class='wb-group'>
           <legend>Signals</legend>
           <div class='wb-fields'>
             <label><span class='wb-cap'>Demand (1-5)</span>
               <@fields.demand /></label>
-            <div
-              class='wb-flag'
-              role='group'
-              aria-labelledby={{this.captionId 'featured'}}
-            ><@fields.featured /><span
-                id={{this.captionId 'featured'}}
-                class='wb-cap'
-              >Featured</span></div>
-            <div
-              class='wb-flag'
-              role='group'
-              aria-labelledby={{this.captionId 'isNew'}}
-            ><@fields.isNew /><span
-                id={{this.captionId 'isNew'}}
-                class='wb-cap'
-              >New</span></div>
-            <div
-              class='wb-flag'
-              role='group'
-              aria-labelledby={{this.captionId 'hasDesign'}}
-            ><@fields.hasDesign /><span
-                id={{this.captionId 'hasDesign'}}
-                class='wb-cap'
-              >Has design</span></div>
-            <div
-              class='wb-flag'
-              role='group'
-              aria-labelledby={{this.captionId 'hasExamples'}}
-            ><@fields.hasExamples /><span
-                id={{this.captionId 'hasExamples'}}
-                class='wb-cap'
-              >Has examples</span></div>
-            <div
-              class='wb-flag'
-              role='group'
-              aria-labelledby={{this.captionId 'liveInUse'}}
-            ><@fields.liveInUse /><span
-                id={{this.captionId 'liveInUse'}}
-                class='wb-cap'
-              >Live in use</span></div>
+            <label class='wb-switch-row'>
+              <Switch
+                @checked={{@model.featured}}
+                @onCheckedChange={{fn this.setFlag 'featured'}}
+                @disabled={{not @canEdit}}
+              />
+              <span class='wb-cap'>Featured</span>
+            </label>
+            <label class='wb-switch-row'>
+              <Switch
+                @checked={{@model.isNew}}
+                @onCheckedChange={{fn this.setFlag 'isNew'}}
+                @disabled={{not @canEdit}}
+              />
+              <span class='wb-cap'>New</span>
+            </label>
+            <label class='wb-switch-row'>
+              <Switch
+                @checked={{@model.hasDesign}}
+                @onCheckedChange={{fn this.setFlag 'hasDesign'}}
+                @disabled={{not @canEdit}}
+              />
+              <span class='wb-cap'>Has design</span>
+            </label>
+            <label class='wb-switch-row'>
+              <Switch
+                @checked={{@model.hasExamples}}
+                @onCheckedChange={{fn this.setFlag 'hasExamples'}}
+                @disabled={{not @canEdit}}
+              />
+              <span class='wb-cap'>Has examples</span>
+            </label>
+            <label class='wb-switch-row'>
+              <Switch
+                @checked={{@model.liveInUse}}
+                @onCheckedChange={{fn this.setFlag 'liveInUse'}}
+                @disabled={{not @canEdit}}
+              />
+              <span class='wb-cap'>Live in use</span>
+            </label>
           </div>
         </fieldset>
 
@@ -1530,19 +1569,20 @@ export class PretUISpec extends Spec {
         .wb-wide {
           grid-column: 1 / -1;
         }
-        .wb-flag {
-          grid-template-columns: auto 1fr;
+        .wb-fields > .wb-switch-row {
+          display: flex;
           align-items: center;
+          gap: var(--boxel-sp-xs);
+          cursor: pointer;
         }
-        /* the caption only, so the caps style stays off the editor beside it */
+        /* field captions are sentence-case labels; the caps style is the
+           group legends' alone */
         .wb-cap {
           display: block;
-          font-family: var(--boxel-eyebrow-font-family);
-          font-size: var(--boxel-eyebrow-font-size);
-          font-weight: var(--boxel-eyebrow-font-weight);
-          line-height: var(--boxel-eyebrow-line-height);
-          letter-spacing: var(--boxel-eyebrow-letter-spacing);
-          text-transform: uppercase;
+          font-size: var(--boxel-ui-label-font-size);
+          font-weight: var(--boxel-ui-label-font-weight);
+          line-height: var(--boxel-ui-label-line-height);
+          letter-spacing: var(--boxel-ui-label-letter-spacing);
           color: var(--muted-foreground);
         }
       </style>

From e397645be94014a75c5c7bb0d8b813ae62fe56aa Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Thu, 8 Oct 2026 18:21:20 -0400
Subject: [PATCH 28/30] Offer the Spec's closed vocabularies (category, tier,
 ownership, adoption, source, demand) as enums

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/pretui-component.gts | 72 +++++++++++++++++++++++++---
 1 file changed, 66 insertions(+), 6 deletions(-)

diff --git a/packages/pretui/pretui-component.gts b/packages/pretui/pretui-component.gts
index 2a0ccb88a0e..7d1c60fd6cc 100644
--- a/packages/pretui/pretui-component.gts
+++ b/packages/pretui/pretui-component.gts
@@ -19,6 +19,7 @@ import { Spec } from 'https://cardstack.com/base/spec';
 import { MarkdownDef } from 'https://cardstack.com/base/markdown-file-def';
 import { MarkdownPreview } from 'https://cardstack.com/base/file-formats/index';
 import StringField from 'https://cardstack.com/base/string';
+import enumField from 'https://cardstack.com/base/enum';
 import BooleanField from 'https://cardstack.com/base/boolean';
 import NumberField from 'https://cardstack.com/base/number';
 import GlimmerComponent from '@glimmer/component';
@@ -366,6 +367,55 @@ function examplesLoadFor(name: string): Loaded<ExampleSpec[]> {
 
 // ── The card ─────────────────────────────────────────────────────────────
 
+// Closed vocabularies for the Spec's classification fields: the edit form
+// offers these as dropdowns. Each list covers every value the catalog's
+// Specs store, so existing instances read unchanged.
+const CATEGORY_OPTIONS = [
+  'Actions',
+  'Agentic',
+  'Authoring Tools',
+  'Containers',
+  'Data Display',
+  'Feedback',
+  'Forms',
+  'Foundations',
+  'Inputs',
+  'Layout',
+  'Media',
+  'Motion & Effects',
+  'Navigation',
+  'Overlays',
+].map((value) => ({ value, label: value }));
+const TIER_OPTIONS = [
+  'Primitive',
+  'Element',
+  'Compound',
+  'Block',
+  'Surface',
+  'Runtime',
+].map((value) => ({ value, label: value }));
+const OWNERSHIP_OPTIONS = [
+  { value: 'pretui', label: 'Pret UI' },
+  { value: 'boxel-ui', label: 'boxel-ui' },
+];
+const ADOPTION_OPTIONS = [
+  { value: 'in-use', label: 'In use' },
+  { value: 'demo-ready', label: 'Demo ready' },
+  { value: 'experimental', label: 'Experimental' },
+];
+const SOURCE_OPTIONS = [
+  { value: 'design-v1', label: 'design-v1' },
+  { value: 'react-ecosystem', label: 'React ecosystem' },
+  { value: 'boxel-ui', label: 'boxel-ui' },
+  { value: 'ember-freestyle', label: 'ember-freestyle' },
+  { value: 'webawesome', label: 'Web Awesome' },
+  { value: 'pretui', label: 'Pret UI' },
+];
+const DEMAND_OPTIONS = [1, 2, 3, 4, 5].map((value) => ({
+  value,
+  label: String(value),
+}));
+
 export class PretUISpec extends Spec {
   static displayName = 'Pret UI Spec';
   static prefersWideFormat = true;
@@ -378,17 +428,25 @@ export class PretUISpec extends Spec {
   // category = the primary user-facing home; tier = compositional
   // complexity; tags = cross-cutting capabilities. Independent axes — never
   // infer one from another.
-  @field category = contains(StringField);
-  @field tier = contains(StringField);
+  @field category = contains(
+    enumField(StringField, { options: CATEGORY_OPTIONS }),
+  );
+  @field tier = contains(enumField(StringField, { options: TIER_OPTIONS }));
   @field tags = containsMany(StringField);
-  @field ownership = contains(StringField);
+  @field ownership = contains(
+    enumField(StringField, { options: OWNERSHIP_OPTIONS }),
+  );
   @field implementationStatus = contains(StringField);
-  @field adoptionStatus = contains(StringField);
+  @field adoptionStatus = contains(
+    enumField(StringField, { options: ADOPTION_OPTIONS }),
+  );
   @field introducedVersion = contains(StringField);
   // ── legacy axes, retained through the migration ──
   @field territory = contains(StringField);
   @field stage = contains(StringField);
-  @field source = contains(StringField);
+  @field source = contains(
+    enumField(StringField, { options: SOURCE_OPTIONS }),
+  );
   @field lineage = contains(StringField);
   @field version = contains(StringField);
   @field brief = contains(StringField);
@@ -404,7 +462,9 @@ export class PretUISpec extends Spec {
   @field liveInUse = contains(BooleanField);
   // cross-library demand signal, 1-5 — how many independent kits converged
   // on this component (sourcing/index.md dupe density)
-  @field demand = contains(NumberField);
+  @field demand = contains(
+    enumField(NumberField, { options: DEMAND_OPTIONS }),
+  );
   // the write-up lives in the sibling <name>.md; the indexer extracts its
   // content into the linked MarkdownDef, so the .md stays the single source.
   // searchable puts that content in the spec's search doc, once.

From be0d301595aefff73d0fc5b90771736141e6abee Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Thu, 8 Oct 2026 19:23:12 -0400
Subject: [PATCH 29/30] Show Spec notes as title and excerpt beside the
 heading, keep the frame's scroll inside it, break titles between words, and
 set key-value values in mono

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/note-text.ts         |  32 ++++
 packages/pretui/pretui-component.gts | 262 +++++++++++++++++----------
 packages/pretui/pretui-note.gts      |  17 +-
 3 files changed, 205 insertions(+), 106 deletions(-)
 create mode 100644 packages/pretui/note-text.ts

diff --git a/packages/pretui/note-text.ts b/packages/pretui/note-text.ts
new file mode 100644
index 00000000000..c70f8b718a7
--- /dev/null
+++ b/packages/pretui/note-text.ts
@@ -0,0 +1,32 @@
+// Pretui — plain-text views of a sticky note's markdown, shared by the note
+// card and the Spec page's notes rail (which can't import the note card: the
+// note links to the Spec, so the import would be a cycle).
+
+// a line's leading markdown furniture: quote, heading and list markers
+const LINE_PREFIX = /^[\s>#*\-+]+/;
+// inline emphasis and code marks
+const INLINE_MARKS = /[`*_]/g;
+
+function plainLines(note: string | undefined): string[] {
+  return (note ?? '')
+    .split('\n')
+    .map((line) =>
+      line.replace(LINE_PREFIX, '').replace(INLINE_MARKS, '').trim(),
+    )
+    .filter((line) => line.length > 0);
+}
+
+/**
+ * First line of a note, flattened to plain text and shortened — the note's
+ * title in card lists, search results, and the assistant's card picker.
+ */
+export function noteSummary(note: string | undefined): string {
+  let first = plainLines(note)[0];
+  if (!first) return 'Sticky note';
+  return first.length > 72 ? `${first.slice(0, 71)}…` : first;
+}
+
+/** Everything after the first line, as one run of plain text ('' if none). */
+export function noteExcerpt(note: string | undefined): string {
+  return plainLines(note).slice(1).join(' ');
+}
diff --git a/packages/pretui/pretui-component.gts b/packages/pretui/pretui-component.gts
index 7d1c60fd6cc..db49a8bd8f7 100644
--- a/packages/pretui/pretui-component.gts
+++ b/packages/pretui/pretui-component.gts
@@ -39,6 +39,7 @@ import { Chip } from './components/chip';
 import { Token } from './components/token';
 import { Button } from './components/button';
 import { Switch } from './components/switch';
+import { noteExcerpt, noteSummary } from './note-text';
 import { Tooltip } from './components/tooltip';
 import { VisuallyHidden } from './components/visually-hidden';
 import { Textarea } from './components/textarea';
@@ -100,6 +101,13 @@ function stageTone(stage: string | undefined): 'success' | undefined {
   return stage === 'live' ? 'success' : undefined;
 }
 
+// A component name split at its camel-case humps ("ApprovalFooter" →
+// "Approval", "Footer"), so a narrow title breaks between words.
+const NAME_HUMP_RE = new RegExp('(?<=[a-z0-9])(?=[A-Z])');
+function nameParts(name: string): string[] {
+  return name.split(NAME_HUMP_RE);
+}
+
 // The write-up shows its first lines under a fade, with a centered toggle
 // over the fade; opening it grows the region to the content's height. Its own
 // component for the same reason as NoteComposer: the open state can't live in
@@ -607,6 +615,13 @@ export class PretUISpec extends Spec {
         (n) => (n.status ?? '').toLowerCase() !== 'addressed',
       );
     }
+    // the rail shows the first few open notes; the rest sit in a disclosure
+    get firstNotes(): NoteLike[] {
+      return this.openNotes.slice(0, 3);
+    }
+    get moreNotes(): NoteLike[] {
+      return this.openNotes.slice(3);
+    }
     get addressedCount(): number {
       return this.notes.length - this.openNotes.length;
     }
@@ -710,85 +725,117 @@ export class PretUISpec extends Spec {
             <ThemeControls />
           </header>
 
-          {{! Sticky notes live top-right, where you left them. Visible by
-            design: an annotation hidden behind a disclosure is an annotation
-            nobody reads. }}
-          {{#if this.showNotes}}
-            <aside
-              class='notes'
-              aria-label='Sticky notes on this component'
-              data-test-pretui-notes
-            >
-              {{! The trigger sits FIRST — directly under the theme control and
-                above the artboard — so leaving a note is a fixed target on
-                every page, not something that moves as notes accumulate. }}
-              <div class='notes-foot'>
-                {{#if this.canAddNote}}
-                  <Popover
-                    class='note-popover'
-                    @placement='bottom-end'
-                    @label='Leave a sticky note'
-                  >
-                    <:trigger as |open toggle|>
-                      <Button
-                        @tone='neutral'
-                        @appearance='outlined'
-                        @size='xs'
-                        aria-expanded={{if open 'true' 'false'}}
-                        aria-haspopup='dialog'
-                        {{on 'click' toggle}}
-                        data-test-pretui-note-add
-                      >Add note</Button>
-                    </:trigger>
-                    <:default as |close|>
-                      <NoteComposer
-                        @componentName={{@model.componentName}}
-                        @onSave={{fn this.saveNote close}}
-                      />
-                    </:default>
-                  </Popover>
+          <div class='wb-head'>
+            <h1 class='wb-title'>
+              {{#let (iconFor @model.icon) as |TitleIcon|}}
+                {{#if TitleIcon}}
+                  <span class='wb-title-frame'>
+                    <TitleIcon width='22' height='22' role='presentation' />
+                  </span>
                 {{/if}}
-                {{#if this.addressedCount}}
-                  <span class='notes-done'>{{this.addressedCount}}
-                    addressed</span>
+              {{/let}}
+              <span class='wb-title-text'>{{#each
+                  (nameParts (if @model.componentName @model.componentName 'Component'))
+                  as |part i|
+                }}{{#if i}}<wbr />{{/if}}{{part}}{{/each}}</span>
+            </h1>
+              {{! Sticky notes sit beside the title, where you left them, and
+                the first few stay visible: an annotation hidden behind a
+                disclosure is an annotation nobody reads. }}
+            {{#if this.showNotes}}
+              <aside
+                class='notes'
+                aria-label='Sticky notes on this component'
+                data-test-pretui-notes
+              >
+                {{! The trigger sits FIRST — directly under the theme control and
+                  above the artboard — so leaving a note is a fixed target on
+                  every page, not something that moves as notes accumulate. }}
+                <div class='notes-foot'>
+                  {{#if this.canAddNote}}
+                    <Popover
+                      class='note-popover'
+                      @placement='bottom-end'
+                      @label='Leave a sticky note'
+                    >
+                      <:trigger as |open toggle|>
+                        <Button
+                          @tone='neutral'
+                          @appearance='outlined'
+                          @size='xs'
+                          aria-expanded={{if open 'true' 'false'}}
+                          aria-haspopup='dialog'
+                          {{on 'click' toggle}}
+                          data-test-pretui-note-add
+                        >Add note</Button>
+                      </:trigger>
+                      <:default as |close|>
+                        <NoteComposer
+                          @componentName={{@model.componentName}}
+                          @onSave={{fn this.saveNote close}}
+                        />
+                      </:default>
+                    </Popover>
+                  {{/if}}
+                  {{#if this.addressedCount}}
+                    <span class='notes-done'>{{this.addressedCount}}
+                      addressed</span>
+                  {{/if}}
+                </div>
+                {{#if this.openNotes}}
+                  <ul class='notes-list'>
+                    {{#each this.firstNotes key='id' as |n|}}
+                      <li>
+                        <button
+                          type='button'
+                          class='note'
+                          {{on 'click' (fn this.openNote n.id)}}
+                          data-test-pretui-note
+                        >
+                          <span class='note-title'>{{noteSummary n.note}}</span>
+                          {{#let (noteExcerpt n.note) as |excerpt|}}
+                            {{#if excerpt}}
+                              <span class='note-excerpt'>{{excerpt}}</span>
+                            {{/if}}
+                          {{/let}}
+                        </button>
+                      </li>
+                    {{/each}}
+                  </ul>
+                  {{#if this.moreNotes.length}}
+                    {{! buttons in a details' content, outside its summary, are
+                        valid; the rule counts details itself as interactive }}
+                    {{! template-lint-disable no-nested-interactive }}
+                    <details class='notes-more' data-test-pretui-notes-more>
+                      <summary>Show
+                        {{this.moreNotes.length}}
+                        more</summary>
+                      <ul class='notes-list'>
+                        {{#each this.moreNotes key='id' as |n|}}
+                          <li>
+                            <button
+                              type='button'
+                              class='note'
+                              {{on 'click' (fn this.openNote n.id)}}
+                              data-test-pretui-note
+                            >
+                              <span class='note-title'>{{noteSummary n.note}}</span>
+                              {{#let (noteExcerpt n.note) as |excerpt|}}
+                                {{#if excerpt}}
+                                  <span class='note-excerpt'>{{excerpt}}</span>
+                                {{/if}}
+                              {{/let}}
+                            </button>
+                          </li>
+                        {{/each}}
+                      </ul>
+                    </details>
+                    {{! template-lint-enable no-nested-interactive }}
+                  {{/if}}
                 {{/if}}
-              </div>
-              {{#if this.openNotes}}
-                <ul class='notes-list'>
-                  {{#each this.openNotes key='id' as |n|}}
-                    <li>
-                      <button
-                        type='button'
-                        class='note'
-                        {{on 'click' (fn this.openNote n.id)}}
-                        data-test-pretui-note
-                      >
-                        <span class='note-text'>{{if
-                            n.note
-                            n.note
-                            'Empty note'
-                          }}</span>
-                      </button>
-                    </li>
-                  {{/each}}
-                </ul>
-              {{/if}}
-            </aside>
-          {{/if}}
-          <h1 class='wb-title'>
-            {{#let (iconFor @model.icon) as |TitleIcon|}}
-              {{#if TitleIcon}}
-                <span class='wb-title-frame'>
-                  <TitleIcon width='22' height='22' role='presentation' />
-                </span>
-              {{/if}}
-            {{/let}}
-            <span class='wb-title-text'>{{if
-                @model.componentName
-                @model.componentName
-                'Component'
-              }}</span>
-          </h1>
+              </aside>
+            {{/if}}
+          </div>
           {{#if this.showBrief}}
             <p class='brief'>{{@model.brief}}</p>
           {{/if}}
@@ -890,8 +937,12 @@ export class PretUISpec extends Spec {
         /* the isolated root: the card's height and its scroller. No
            overscroll-behavior: where a host sizes the card to its content
            (code mode's preview), the frame has nothing to scroll and the
-           wheel has to pass up to the host's scroller */
+           wheel has to pass up to the host's scroller. position: relative
+           keeps absolute descendants (visually hidden text) inside this
+           scroller; otherwise they overflow the card container, which then
+           scrolls past the frame onto its own background */
         .wb-frame {
+          position: relative;
           height: 100%;
           overflow-y: auto;
         }
@@ -1003,18 +1054,25 @@ export class PretUISpec extends Spec {
         .wb-work {
           min-width: 0;
         }
-        /* ── Sticky notes ────────────────────────────────────────────────
-           Pinned to the right edge of the page column, above the title, so
-           an annotation is the first thing you see on a page that has one.
-           justify-self keeps the rail narrow instead of stretching across
-           the grid column. */
+        /* the title and the notes rail share a row; the rail wraps under
+           the title when the row is too narrow for both */
+        .wb-head {
+          display: flex;
+          flex-wrap: wrap;
+          align-items: flex-start;
+          gap: var(--boxel-sp) var(--boxel-sp-lg);
+        }
+        .wb-head > .wb-title {
+          flex: 1 1 18rem;
+          min-width: 0;
+        }
+        /* ── Sticky notes ── */
         .notes {
-          justify-self: end;
+          flex: 0 1 var(--_wb-notes-w);
           display: flex;
           flex-direction: column;
           align-items: flex-end;
           gap: var(--boxel-sp-2xs);
-          width: min(var(--_wb-notes-w), 100%);
           min-width: 0;
         }
         /* a note wants room to write: Popover reads its width knob on the
@@ -1062,16 +1120,37 @@ export class PretUISpec extends Spec {
         .note:hover {
           box-shadow: var(--shadow-md);
         }
-        /* Clamp long notes: the rail is a pointer to the note card, not the
-           note card. Clicking opens the whole thing. */
-        .note-text {
+        .notes-more {
+          width: 100%;
+        }
+        .notes-more > summary {
+          width: fit-content;
+          margin-inline-start: auto;
+          font-size: var(--boxel-ui-label-font-size);
+          font-weight: var(--boxel-ui-label-font-weight);
+          color: var(--muted-foreground);
+          cursor: pointer;
+        }
+        .notes-more[open] > summary {
+          margin-block-end: var(--boxel-sp-2xs);
+        }
+        /* each note reads as a small card: its title, then the start of
+           its body; clicking opens the whole note */
+        .note {
+          display: grid;
+          gap: var(--boxel-sp-6xs);
+        }
+        .note-title {
+          font-weight: 600;
+          overflow-wrap: break-word;
+        }
+        .note-excerpt {
           display: -webkit-box;
-          -webkit-line-clamp: 4;
+          -webkit-line-clamp: 2;
           -webkit-box-orient: vertical;
           overflow: hidden;
-          /* a pasted URL or a long identifier is one "word"; the rail has a
-             fixed width, so break-word wraps it instead of overflowing */
           overflow-wrap: break-word;
+          color: var(--muted-foreground);
         }
         .notes-foot {
           display: flex;
@@ -1183,6 +1262,7 @@ export class PretUISpec extends Spec {
         }
         .wb-krow dd {
           margin: 0;
+          font-family: var(--font-mono);
           font-size: var(--boxel-font-size-xs);
           line-height: 1.5;
           overflow-wrap: break-word;
diff --git a/packages/pretui/pretui-note.gts b/packages/pretui/pretui-note.gts
index 896ebfe0c5d..f7ef36bdac2 100644
--- a/packages/pretui/pretui-note.gts
+++ b/packages/pretui/pretui-note.gts
@@ -37,27 +37,14 @@ import type { TemplateOnlyComponent } from '@ember/component/template-only';
 import { Button } from './components/button';
 import { Chip } from './components/chip';
 import { PretUISpec } from './pretui-component';
+import { noteSummary } from './note-text';
 
 /** A note is open unless it has been explicitly addressed. */
 export function isAddressed(status: string | undefined): boolean {
   return (status ?? '').toLowerCase() === 'addressed';
 }
 
-/**
- * First line of a note, flattened to plain text and shortened — the note's
- * title in card lists, search results, and the assistant's card picker.
- * Notes are markdown, so the leading `#`/`>`/`-`/backtick furniture is
- * stripped rather than shown.
- */
-export function noteSummary(note: string | undefined): string {
-  let first = (note ?? '')
-    .split('\n')
-    .map((line) => line.replace(/^[\s>#*\-+]+/, '').trim())
-    .find((line) => line.length > 0);
-  if (!first) return 'Sticky note';
-  let plain = first.replace(/[`*_]/g, '');
-  return plain.length > 72 ? `${plain.slice(0, 71)}…` : plain;
-}
+export { noteSummary };
 
 // The note's state as a chip: open in the attention tone, addressed in
 // success.

From 19ed0a61e8a117d9a60c87d26be56aabcfb22e8f Mon Sep 17 00:00:00 2001
From: Burcu Noyan <burcunoyan@gmail.com>
Date: Thu, 8 Oct 2026 19:31:13 -0400
Subject: [PATCH 30/30] Space the hidden (required) from the asterisk, and read
 API row names from their th in the usage-page test

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
---
 packages/pretui/components/freestyle-usage.test.gts | 6 +++---
 packages/pretui/components/usage-argument.gts       | 2 +-
 packages/pretui/internal/freestyle.gts              | 4 ++--
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/packages/pretui/components/freestyle-usage.test.gts b/packages/pretui/components/freestyle-usage.test.gts
index a70be0a4a93..75df3db96c4 100644
--- a/packages/pretui/components/freestyle-usage.test.gts
+++ b/packages/pretui/components/freestyle-usage.test.gts
@@ -69,9 +69,9 @@ module('Pretui | components/freestyle-usage', function (hooks) {
     let aside = root().querySelector('[data-test-pretui-usage-props]') as HTMLElement;
     assert.deepEqual(Array.from(aside.querySelectorAll('[data-test-pretui-prop-row-label]')).map((l) => l.textContent?.trim()), ['label', 'disabled', '--pretui-btn-radius'], 'actions and yields have no knob');
     let apiRows = Array.from(root().querySelector('[data-test-pretui-usage-api]')?.querySelectorAll('[data-test-pretui-usage-arg]') ?? []);
-    assert.deepEqual(apiRows.map((r) => r.querySelector('td')?.textContent?.replace(/\s+/g, ' ').trim()), ['@label', '@disabled', '@onClick', '{{default}}']);
-    assert.deepEqual(apiRows.map((r) => r.querySelectorAll('td')[1]?.textContent?.trim()), ['String', 'Bool', 'Action', 'Yield']);
+    assert.deepEqual(apiRows.map((r) => r.querySelector('th')?.textContent?.replace(/\s+/g, ' ').trim()), ['@label', '@disabled', '@onClick', '{{default}}']);
+    assert.deepEqual(apiRows.map((r) => r.querySelector('td')?.textContent?.trim()), ['String', 'Bool', 'Action', 'Yield']);
     let cssRows = Array.from(root().querySelector('[data-test-pretui-usage-css-vars]')?.querySelectorAll('[data-test-pretui-usage-arg]') ?? []);
-    assert.deepEqual(cssRows.map((r) => Array.from(r.querySelectorAll('td')).map((td) => td.textContent?.replace(/\s+/g, ' ').trim())), [['--pretui-btn-radius', 'CSS', '', '6px']]);
+    assert.deepEqual(cssRows.map((r) => Array.from(r.querySelectorAll(':is(th, td)')).map((td) => td.textContent?.replace(/\s+/g, ' ').trim())), [['--pretui-btn-radius', 'CSS', '', '6px']]);
   });
 });
diff --git a/packages/pretui/components/usage-argument.gts b/packages/pretui/components/usage-argument.gts
index 6b8086ecb82..90e06c6db8a 100644
--- a/packages/pretui/components/usage-argument.gts
+++ b/packages/pretui/components/usage-argument.gts
@@ -55,7 +55,7 @@ export class UsageArgument extends Component<UsageArgumentSignature> {
               class='u-req'
               aria-hidden='true'
               data-test-pretui-usage-arg-required
-            >*</span><VisuallyHidden>(required)</VisuallyHidden>{{/if}}
+            >*</span><VisuallyHidden> (required)</VisuallyHidden>{{/if}}
         </th>
         <td class='pretui-usage-arg-type'>{{this.typeLabel}}</td>
         <td><span
diff --git a/packages/pretui/internal/freestyle.gts b/packages/pretui/internal/freestyle.gts
index 68a296d339f..ef43ce99915 100644
--- a/packages/pretui/internal/freestyle.gts
+++ b/packages/pretui/internal/freestyle.gts
@@ -40,7 +40,7 @@ export const PropRow: TemplateOnlyComponent<PropRowSignature> = <template>
         {{#if @required}}<span
             class='proprow-req'
             aria-hidden='true'
-          >*</span><VisuallyHidden>(required)</VisuallyHidden>{{/if}}
+          >*</span><VisuallyHidden> (required)</VisuallyHidden>{{/if}}
       </label>
     {{else}}
       <span class='proprow-label' data-test-pretui-prop-row-label>
@@ -48,7 +48,7 @@ export const PropRow: TemplateOnlyComponent<PropRowSignature> = <template>
         {{#if @required}}<span
             class='proprow-req'
             aria-hidden='true'
-          >*</span><VisuallyHidden>(required)</VisuallyHidden>{{/if}}
+          >*</span><VisuallyHidden> (required)</VisuallyHidden>{{/if}}
       </span>
     {{/if}}
     <div class='proprow-control'>{{yield}}</div>