@cardstack/boxel-cli 0.10.0 → 0.10.1-unstable.0

package/bundled-realms/pretui/components/format-number.usage.gts

@@ -0,0 +1,261 @@
+// Pretui — FormatNumber usage page.
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { FreestyleUsage } from './freestyle-usage';
+import { FormatNumber } from './format-number';
+import { LOCALES, NOTATIONS, NUMBER_STYLES, SPOKEN_MODES } from '../demo-reading-format';
+
+// ── FormatNumber ─────────────────────────────────────────────────────────
+const SIGN_DISPLAYS = ['auto', 'never', 'always', 'exceptZero', 'negative'];
+
+// The accessibility case worth reading: compact notation abbreviates
+// 1,234,567 to 1.2M, and an abbreviation is a LOSS for a screen reader.
+// @spoken='auto' therefore mirrors the full-precision value whenever the
+// visible text is abbreviated, which is what makes compact notation safe
+// to use at all.
+class FormatNumberUsage extends Component {
+  styleOptions = NUMBER_STYLES;
+  notationOptions = NOTATIONS;
+  signOptions = SIGN_DISPLAYS;
+  localeOptions = LOCALES;
+  spokenOptions = SPOKEN_MODES;
+
+  @tracked value = 1234567.891;
+  @tracked style = 'currency';
+  @tracked currency = 'USD';
+  @tracked notation = 'standard';
+  @tracked locale = 'en-US';
+  @tracked signDisplay = 'auto';
+  @tracked maximumFractionDigits: number | null = 2;
+  @tracked token = false;
+  @tracked spoken = 'auto';
+
+  setValue = (v: number | null) => (this.value = v ?? 0);
+  setStyle = (v: string) => (this.style = v);
+  setCurrency = (v: string) => (this.currency = v);
+  setNotation = (v: string) => (this.notation = v);
+  setLocale = (v: string) => (this.locale = v);
+  setSignDisplay = (v: string) => (this.signDisplay = v);
+  setMaxFraction = (v: number | null) => (this.maximumFractionDigits = v);
+  setToken = (v: boolean) => (this.token = v);
+  setSpoken = (v: string) => (this.spoken = v);
+
+  get styleVal() {
+    return this.style as 'decimal' | 'currency' | 'percent' | 'unit';
+  }
+  get notationVal() {
+    return this.notation as
+      | 'standard'
+      | 'compact'
+      | 'scientific'
+      | 'engineering';
+  }
+  get signVal() {
+    return this.signDisplay as
+      | 'auto'
+      | 'never'
+      | 'always'
+      | 'exceptZero'
+      | 'negative';
+  }
+  get spokenVal() {
+    return this.spoken as 'auto' | 'always' | 'off';
+  }
+  get maxFractionVal() {
+    return this.maximumFractionDigits ?? undefined;
+  }
+  get unitVal() {
+    return this.style === 'unit' ? 'kilogram' : undefined;
+  }
+  get usage() {
+    let bits = [`@value={{${this.value}}}`];
+    if (this.style !== 'decimal') bits.push(`@style='${this.style}'`);
+    if (this.style === 'currency') bits.push(`@currency='${this.currency}'`);
+    if (this.style === 'unit') bits.push("@unit='kilogram'");
+    if (this.notation !== 'standard') bits.push(`@notation='${this.notation}'`);
+    if (this.locale !== 'en-US') bits.push(`@locale='${this.locale}'`);
+    if (this.signDisplay !== 'auto')
+      bits.push(`@signDisplay='${this.signDisplay}'`);
+    if (this.token) bits.push('@token={{true}}');
+    return `<FormatNumber ${bits.join(' ')} />`;
+  }
+
+  <template>
+    <FreestyleUsage
+      @name='FormatNumber'
+      @description="Locale-aware numbers, currency, percentages, and units over Intl.NumberFormat, with the whole option surface exposed as separately-settable knobs rather than the two or three most libraries stop at. Every numeral sets tabular-nums so a column of them stays in register (Law 8). Compact notation abbreviates — and abbreviation loses information — so @spoken mirrors the full-precision value to assistive tech whenever the visible text is shortened."
+      @source={{this.usage}}
+    >
+      <:example>
+        <div class='fmt-stack'>
+          <p class='fmt-line'>
+            <em>Silver Peak Trading</em>
+            settled the season at
+            <FormatNumber
+              @value={{this.value}}
+              @style={{this.styleVal}}
+              @currency={{this.currency}}
+              @unit={{this.unitVal}}
+              @notation={{this.notationVal}}
+              @locale={{this.locale}}
+              @signDisplay={{this.signVal}}
+              @maximumFractionDigits={{this.maxFractionVal}}
+              @token={{this.token}}
+              @spoken={{this.spokenVal}}
+            />
+            across all lots.
+          </p>
+
+          <div class='fmt-grid'>
+            {{#each this.notationOptions as |note|}}
+              <div class='fmt-cell'>
+                <span class='fmt-cap'>{{note}}</span>
+                <FormatNumber
+                  @value={{this.value}}
+                  @style={{this.styleVal}}
+                  @currency={{this.currency}}
+                  @unit={{this.unitVal}}
+                  @notation={{note}}
+                  @locale={{this.locale}}
+                  @maximumFractionDigits={{this.maxFractionVal}}
+                />
+              </div>
+            {{/each}}
+          </div>
+        </div>
+      </:example>
+      <:api as |Args|>
+        <Args.Number
+          @name='value'
+          @value={{this.value}}
+          @description='The number. Strings are coerced; anything non-finite renders @placeholder rather than NaN.'
+          @onInput={{this.setValue}}
+        />
+        <Args.String
+          @name='style'
+          @defaultValue='decimal'
+          @value={{this.style}}
+          @options={{this.styleOptions}}
+          @description='decimal, currency, percent (0.42 renders 42%), or unit.'
+          @onInput={{this.setStyle}}
+        />
+        <Args.String
+          @name='currency'
+          @value={{this.currency}}
+          @description='ISO 4217 code, required by style=currency. Without it the style degrades to decimal instead of throwing.'
+          @onInput={{this.setCurrency}}
+        />
+        <Args.String
+          @name='notation'
+          @defaultValue='standard'
+          @value={{this.notation}}
+          @options={{this.notationOptions}}
+          @description='standard, compact (1.2M), scientific, or engineering. Compact is an abbreviation, so it triggers the sr-only full-precision mirror.'
+          @onInput={{this.setNotation}}
+        />
+        <Args.String
+          @name='signDisplay'
+          @defaultValue='auto'
+          @value={{this.signDisplay}}
+          @options={{this.signOptions}}
+          @description='When the sign is shown. exceptZero is the one you want for deltas.'
+          @onInput={{this.setSignDisplay}}
+        />
+        <Args.String
+          @name='locale'
+          @value={{this.locale}}
+          @options={{this.localeOptions}}
+          @description='BCP-47 tag; omit for the runtime default. hi-IN groups in lakhs, de-DE swaps separators, ar-EG changes the digits.'
+          @onInput={{this.setLocale}}
+        />
+        <Args.Number
+          @name='maximumFractionDigits'
+          @value={{this.maximumFractionDigits}}
+          @min={{0}}
+          @max={{6}}
+          @description='Ceiling on fraction digits. Significant-digit knobs win over the fraction-digit ones.'
+          @onInput={{this.setMaxFraction}}
+        />
+        <Args.Bool
+          @name='token'
+          @defaultValue={{false}}
+          @value={{this.token}}
+          @description='Wear the Token dress (Law 3) — for parameter rows and machine contexts.'
+          @onInput={{this.setToken}}
+        />
+        <Args.String
+          @name='spoken'
+          @defaultValue='auto'
+          @value={{this.spoken}}
+          @options={{this.spokenOptions}}
+          @description='sr-only mirror policy. auto mirrors whenever the visible text is abbreviated, so 1.2M does not cost a screen-reader user the real figure.'
+          @onInput={{this.setSpoken}}
+        />
+        <Args.String
+          @name='currencyDisplay, currencySign, unit, unitDisplay, compactDisplay'
+          @description='Wording controls: symbol/narrowSymbol/code/name, accounting negatives, the CLDR unit id, and short/long compact words.'
+        />
+        <Args.String
+          @name='useGrouping, minimumIntegerDigits, minimum/maximumSignificantDigits, numberingSystem'
+          @description='Grouping policy, integer padding, significant-digit bounds, and the digit system.'
+        />
+        <Args.Object
+          @name='options'
+          @description='Escape hatch for any Intl.NumberFormat option not named above. Named knobs win over it.'
+        />
+        <Args.String
+          @name='placeholder'
+          @defaultValue='—'
+          @description='Rendered when the value is missing or non-finite.'
+        />
+      </:api>
+    </FreestyleUsage>
+    <style scoped>
+      .fmt-stack {
+        display: flex;
+        flex-direction: column;
+        gap: var(--space-4, 14px);
+      }
+      .fmt-line {
+        margin: 0;
+        font-size: var(--text-ui-md, 12.5px);
+        line-height: 1.6;
+        color: var(--foreground);
+      }
+      .fmt-line em {
+        font-style: normal;
+        font-weight: 600;
+      }
+      .fmt-cap {
+        font-family: var(--font-mono);
+        font-size: var(--text-ui-xs, 11px);
+        font-weight: 600;
+        letter-spacing: var(--track-eyebrow, 0.06em);
+        text-transform: uppercase;
+        color: var(--muted-foreground);
+      }
+      .fmt-grid {
+        display: grid;
+        grid-template-columns: repeat(auto-fit, minmax(150px, 1fr));
+        gap: var(--space-3, 10px);
+      }
+      .fmt-cell {
+        display: flex;
+        flex-direction: column;
+        gap: var(--space-1, 4px);
+        padding: var(--space-3, 10px);
+        border-radius: var(--radius-surface, 10px);
+        box-shadow: var(
+          --pretui-shadow-hairline,
+          0 0 0 1px var(--border)
+        );
+        font-size: var(--text-ui-md, 12.5px);
+        color: var(--foreground);
+      }
+    </style>
+  </template>
+}
+
+export const DEMOS_FORMAT_NUMBER: Record<string, unknown> = {
+  FormatNumber: FormatNumberUsage,
+};

package/bundled-realms/pretui/components/formatted-value.gts

@@ -0,0 +1,65 @@
+// Pretui — FormattedValue: the visible/spoken pair every formatter renders through.
+import Component from '@glimmer/component';
+import { Token } from './token';
+
+// ── FormattedValue — the shared visible/spoken pair ──────────────────────
+// Exported as its own primitive because all three formatters (and anything
+// else in the kit that abbreviates a value) need the same three things: the
+// visible text, the optional sr-only mirror, and the optional Token dress.
+export interface FormattedValueSignature {
+  Args: {
+    /** the visible, already-formatted text */
+    text?: string;
+    /** full-precision or spelled-out mirror for screen readers; when present the visible text is aria-hidden */
+    spoken?: string;
+    /** wear the Token dress (Law 3) instead of a prose numeral */
+    token?: boolean;
+    /** hue forwarded to Token when @token is set */
+    hue?: string;
+    /** marks the value as absent so the placeholder renders muted */
+    empty?: boolean;
+  };
+  Element: HTMLSpanElement;
+}
+
+export class FormattedValue extends Component<FormattedValueSignature> {
+  get hideVisible(): string | undefined {
+    return this.args.spoken ? 'true' : undefined;
+  }
+  get emptyFlag(): string | undefined {
+    return this.args.empty ? 'true' : undefined;
+  }
+  <template>
+    <span
+      class='pretui-fv'
+      data-empty={{this.emptyFlag}}
+      data-test-pretui-formatted-value
+      ...attributes
+    >
+      <span class='pretui-fv-vis' aria-hidden={{this.hideVisible}}>
+        {{#if @token}}<Token @value={{@text}} @hue={{@hue}} />{{else}}{{@text}}{{/if}}
+      </span>
+      {{#if @spoken}}<span class='pretui-fv-sr'>{{@spoken}}</span>{{/if}}
+    </span>
+    <style scoped>
+      @layer PretComponent {
+        .pretui-fv {
+          font-variant-numeric: tabular-nums;
+        }
+        .pretui-fv[data-empty='true'] {
+          color: var(--muted-foreground);
+        }
+        .pretui-fv-vis {
+          white-space: nowrap;
+        }
+        .pretui-fv-sr {
+          position: absolute;
+          width: 1px;
+          height: 1px;
+          overflow: hidden;
+          clip: rect(0 0 0 0);
+        }
+      }
+    </style>
+  </template>
+}

package/bundled-realms/pretui/components/freestyle-usage.gts

@@ -0,0 +1,311 @@
+// Pretui — FreestyleUsage: a component's usage page — example, knobs and API table.
+import type { TemplateOnlyComponent } from '@ember/component/template-only';
+import { hash, uniqueId } from '@ember/helper';
+import { Table } from './table';
+import { CopyButton } from './copy-button';
+import { UsageAction } from './usage-action';
+import { UsageArgument } from './usage-argument';
+import { UsageArray } from './usage-array';
+import { UsageBool } from './usage-bool';
+import { UsageComponentArg } from './usage-component-arg';
+import { UsageCssVariable } from './usage-css-variable';
+import { UsageNumber } from './usage-number';
+import { UsageObject } from './usage-object';
+import { UsageString } from './usage-string';
+import { UsageYield } from './usage-yield';
+import { Viewport, type ViewportSignature } from './viewport';
+
+// ── FreestyleUsage (the page) ────────────────────────────────────────────
+export interface FreestyleUsageSignature {
+  Args: {
+    name?: string;
+    description?: string;
+    slug?: string;
+    source?: string;
+    viewportMode?: ViewportSignature['Args']['defaultMode'];
+  };
+  Blocks: {
+    description: [];
+    example: [];
+    /* eslint-disable @typescript-eslint/no-explicit-any -- the yielded Args
+       hash is any-typed exactly as in ember-freestyle's own signature */
+    api: [
+      {
+        Action: any;
+        Array: any;
+        Base: any;
+        Bool: any;
+        Component: any;
+        Number: any;
+        Object: any;
+        String: any;
+        Yield: any;
+      },
+    ];
+    cssVars: [{ Basic: any }];
+    /* eslint-enable @typescript-eslint/no-explicit-any */
+  };
+  Element: HTMLDivElement;
+}
+
+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 }}
+      {{#if (has-block 'description')}}
+        <p
+          class='pretui-usage-description'
+          data-test-pretui-usage-description
+        >{{yield to='description'}}</p>
+      {{else if @description}}
+        <p
+          class='pretui-usage-description'
+          data-test-pretui-usage-description
+        >{{@description}}</p>
+      {{/if}}
+
+      <div class='pretui-usage-stage'>
+        <div class='pretui-usage-preview-col'>
+          <div class='wb-panel'>
+            <Viewport @defaultMode={{@viewportMode}}>
+              {{yield to='example'}}
+            </Viewport>
+            {{#if @source}}
+              <div class='wb-codestrip' data-test-pretui-usage-source>
+                {{! 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'
+                  @appearance='plain'
+                  class='wb-copy'
+                />
+              </div>
+            {{/if}}
+          </div>
+        </div>
+        {{#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>
+            {{yield
+              (hash
+                Action=(component UsageAction mode='prop')
+                Array=(component UsageArray mode='prop')
+                Base=(component UsageArgument mode='prop')
+                Bool=(component UsageBool mode='prop')
+                Component=(component UsageComponentArg mode='prop')
+                Number=(component UsageNumber mode='prop')
+                Object=(component UsageObject mode='prop')
+                String=(component UsageString mode='prop')
+                Yield=(component UsageYield mode='prop')
+              )
+              to='api'
+            }}
+            {{#if (has-block 'cssVars')}}
+              {{yield
+                (hash Basic=(component UsageCssVariable mode='prop'))
+                to='cssVars'
+              }}
+            {{/if}}
+          </aside>
+        {{/if}}
+      </div>
+
+      {{#if (has-block 'api')}}
+        <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}} @labelledBy={{apiId}}>
+            <:head>
+              <tr>
+                <th>Argument</th>
+                <th>Type</th>
+                <th>Description</th>
+                <th class='wb-th-right'>Default</th>
+              </tr>
+            </:head>
+            <:body>
+              {{yield
+                (hash
+                  Action=(component UsageAction mode='doc')
+                  Array=(component UsageArray mode='doc')
+                  Base=(component UsageArgument mode='doc')
+                  Bool=(component UsageBool mode='doc')
+                  Component=(component UsageComponentArg mode='doc')
+                  Number=(component UsageNumber mode='doc')
+                  Object=(component UsageObject mode='doc')
+                  String=(component UsageString mode='doc')
+                  Yield=(component UsageYield mode='doc')
+                )
+                to='api'
+              }}
+            </:body>
+          </Table>
+        </div>
+      {{/if}}
+
+      {{#if (has-block 'cssVars')}}
+        <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}} @labelledBy={{cssId}}>
+            <:head>
+              <tr>
+                <th>Variable</th>
+                <th>Type</th>
+                <th>Description</th>
+                <th class='wb-th-right'>Default</th>
+              </tr>
+            </:head>
+            <:body>
+              {{yield
+                (hash Basic=(component UsageCssVariable mode='doc'))
+                to='cssVars'
+              }}
+            </:body>
+          </Table>
+        </div>
+      {{/if}}
+    </div>
+    {{/let}}
+    <style scoped>
+      .pretui-usage {
+        --pretui-usage-props-w: 26rem;
+        --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);
+        line-height: var(--boxel-line-height-md);
+        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-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;
+      }
+      /* by class, since CopyButton's status region follows it as a sibling */
+      .wb-codestrip > .wb-copy {
+        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;
+      }
+    </style>
+  </template>;

package/bundled-realms/pretui/components/freestyle-usage.md

@@ -0,0 +1,49 @@
+## 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 Pret UI catalog is one of these. If you only need the artboard frame, **Viewport**; if you need the theme switcher, **ThemeFrame**.
+
+## The contract
+
+```
+@name?, @description?, @slug?, @source?, @viewportMode?
+<:description>  <:example>
+<:api as |Args|>       — Args.{ String, Bool, Number, Array, Object, Component, Action, Yield, Base }
+<:cssVars as |Css|>    — Css.Basic
+```
+
+**The invocation surface is ember-freestyle's, verbatim.** Same block names, same `Args.*` hash, same `<:cssVars>`. That is the verbatim-reuse directive: a usage page written for ember-freestyle works here unchanged, and a Pretui usage page could be lifted back out.
+
+**The `<:api>` block is yielded twice, through two lenses.** The interactive knobs render as a right-hand **property list** (`mode='prop'`); the API table below documents types, descriptions and defaults (`mode='doc'`). One authored block, two presentations — so a page author never writes the same argument twice and the knobs cannot drift from the docs. That is the layout evolution over upstream, and it is the reason `ArgsMode` exists at all.
+
+## Prior art
+
+**ember-freestyle** is the upstream, and this is a port rather than a reimplementation. Against the wider field: **Storybook** is the reference, with args/argTypes, a controls panel, an autodocs table and a source viewer — structurally the same four regions. **Ladle** and **Histoire** are lighter Storybook shapes.
+
+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 `<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.
+
+## Accessibility
+
+No pattern governs it; it is a page composed of the kit's own components, and it inherits their contracts — including their gaps.
+
+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 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.
+- **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-*`), 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.