From 2173c77ce0661fff30f5d523f29931fe21a103b2 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 27 Oct 2026 03:28:07 +0000
Subject: [PATCH 01/10] docs: Show useQuery sorting as a team table that sorts
 by any column

The Sorting & Filtering demo is now a team table: pick a column header to
sort by it (again to reverse), or a segment to show admins or members. One
Query does both on what the store already holds, so nothing refetches. It
plays itself once in view.

The design system gains rule-free tables (value cells end-aligned, a row
band under the pointer), a sortable header button (`sort`, with
`aria-sort` driving its arrow) and a chosen segment for `buttonGroup`
filters (`aria-pressed`). The Scalar demo's table drops its inline styles
and align attributes for these.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y5C5ZC3WYndrqLXmu9F42e
---
 docs/core/api/useQuery.md                     | 261 +++++++++++++-----
 docs/rest/shared/_ScalarDemo.mdx              |  32 +--
 .../Playground/DesignSystem/base.css          |   6 +
 .../Playground/DesignSystem/design-system.css | 140 ++++++++--
 website/src/components/Playground/README.md   |   6 +-
 website/src/fixtures/team.ts                  |  21 ++
 6 files changed, 364 insertions(+), 102 deletions(-)
 create mode 100644 website/src/fixtures/team.ts

diff --git a/docs/core/api/useQuery.md b/docs/core/api/useQuery.md
index 37928931f37f..eca86f477f89 100644
--- a/docs/core/api/useQuery.md
+++ b/docs/core/api/useQuery.md
@@ -10,9 +10,21 @@ import ConditionalDependencies from '../shared/\_conditional_dependencies.mdx';
 import FrameworkPlayground from '@site/src/components/FrameworkPlayground';
 import StackBlitz from '@site/src/components/StackBlitz';
 import { RestEndpoint } from '@data-client/rest';
+import { teamFixtures } from '@site/src/fixtures/team';
 import VoteDemo from '../shared/\_VoteDemo.mdx';
 import VueArgs from '../shared/\_vueArgs.mdx';
 
+export const sortDemo = [
+  // most posts first: the rows reorder, nothing refetches
+  { delay: 1200, click: { selector: 'button.sort', hasText: 'Posts' } },
+  { wait: 1200 },
+  { click: { selector: 'button.sort', hasText: 'Posts' } },
+  { wait: 1800 },
+  { click: { selector: '.buttonGroup button', hasText: 'Admins' } },
+  { wait: 1800 },
+  { click: { selector: 'button.sort', hasText: 'Joined' } },
+];
+
 # useQuery()
 
 Data rendering without the fetch.
@@ -101,28 +113,25 @@ interface Queryable {
 
 ### Sorting & Filtering
 
-[Query](/rest/api/Query) provides programmatic access to the Reactive Data Client store.
+[Query](/rest/api/Query) sorts and filters what is already in the store, so picking another column
+re-sorts the table without fetching again.
 
-<FrameworkPlayground fixtures={[
-{
-endpoint: new RestEndpoint({path: '/users'}),
-args: [],
-response: [
-{ id: '123', name: 'Jim' },
-{ id: '456', name: 'Jane' },
-{ id: '777', name: 'Albatras', isAdmin: true },
-],
-delay: 150,
-},
-]} row>
+<FrameworkPlayground
+fixtures={teamFixtures}
+row
+defaultTab="sortedUsers"
+autoRun={sortDemo}
+>
 
-```ts title="UserResource" collapsed
+```ts title="resources/User" collapsed
 import { Entity, resource } from '@data-client/rest';
 
 export class User extends Entity {
   id = '';
   name = '';
   isAdmin = false;
+  posts = 0;
+  joined = 0;
 
   static key = 'User';
 }
@@ -132,40 +141,132 @@ export const UserResource = resource({
 });
 ```
 
-:::react
-
-```tsx title="UsersPage" {22}
+```ts title="sortedUsers"
 import { All, Query } from '@data-client/rest';
-import { useQuery, useFetch } from '@data-client/react';
-import { UserResource, User } from './UserResource';
+import { User } from './resources/User';
 
-interface Args {
-  asc: boolean;
-  isAdmin?: boolean;
+export type SortBy = 'name' | 'posts' | 'joined';
+export interface Sort {
+  sortBy: SortBy;
+  desc: boolean;
+}
+interface Args extends Sort {
+  /** admins only (true), members only (false), or everyone */
+  isAdmin: boolean | undefined;
 }
-const sortedUsers = new Query(
+
+export const sortedUsers = new Query(
   new All(User),
-  (entries, { asc, isAdmin }: Args = { asc: false }) => {
-    let sorted = [...entries].sort((a, b) => a.name.localeCompare(b.name));
-    if (isAdmin !== undefined)
-      sorted = sorted.filter(user => user.isAdmin === isAdmin);
-    if (asc) return sorted;
-    return sorted.reverse();
+  (entries, { sortBy, desc, isAdmin }: Args) => {
+    const users = entries
+      .filter(user => isAdmin === undefined || user.isAdmin === isAdmin)
+      .sort((a, b) =>
+        sortBy === 'name' ?
+          a.name.localeCompare(b.name)
+        : a[sortBy] - b[sortBy],
+      );
+    return desc ? users.reverse() : users;
   },
 );
+```
+
+:::react
+
+```tsx title="UsersPage" {15}
+import React from 'react';
+import { useQuery, useSuspense } from '@data-client/react';
+import { UserResource } from './resources/User';
+import { sortedUsers, type Sort, type SortBy } from './sortedUsers';
+
+const filters = { All: undefined, Admins: true, Members: false };
 
 function UsersPage() {
-  useFetch(UserResource.getList);
-  const users = useQuery(sortedUsers, { asc: true });
-  if (!users) return <div>No users in cache yet</div>;
+  useSuspense(UserResource.getList);
+  const [sort, setSort] = React.useState<Sort>({
+    sortBy: 'name',
+    desc: false,
+  });
+  const [isAdmin, setIsAdmin] = React.useState<boolean>();
+  const users = useQuery(sortedUsers, { ...sort, isAdmin }) ?? [];
+  const onSort = (sortBy: SortBy) =>
+    setSort(prev => ({
+      sortBy,
+      desc: prev.sortBy === sortBy && !prev.desc,
+    }));
+
   return (
-    <div>
-      {users.map(user => (
-        <div key={user.pk()}>{user.name}</div>
-      ))}
-    </div>
+    <>
+      <header className="appHeader">
+        <h1 className="appTitle">Team</h1>
+        <div className="buttonGroup">
+          {Object.entries(filters).map(([label, value]) => (
+            <button
+              key={label}
+              aria-pressed={isAdmin === value}
+              onClick={() => setIsAdmin(value)}
+            >
+              {label}
+            </button>
+          ))}
+        </div>
+      </header>
+      <table>
+        <thead>
+          <tr>
+            <SortHeader column="name" sort={sort} onSort={onSort}>
+              Name
+            </SortHeader>
+            <th>Role</th>
+            <SortHeader column="posts" sort={sort} onSort={onSort} numeric>
+              Posts
+            </SortHeader>
+            <SortHeader
+              column="joined"
+              sort={sort}
+              onSort={onSort}
+              numeric
+            >
+              Joined
+            </SortHeader>
+          </tr>
+        </thead>
+        <tbody>
+          {users.map(user => (
+            <tr key={user.pk()}>
+              <td>{user.name}</td>
+              <td className="meta">{user.isAdmin ? 'Admin' : 'Member'}</td>
+              <td className="value">{user.posts}</td>
+              <td className="value">{user.joined}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </>
   );
 }
+
+function SortHeader({ column, sort, onSort, numeric, children }: Props) {
+  const sorted = sort.sortBy === column;
+  return (
+    <th
+      className={numeric ? 'value' : undefined}
+      aria-sort={
+        sorted ? (sort.desc ? 'descending' : 'ascending') : undefined
+      }
+    >
+      <button className="sort" onClick={() => onSort(column)}>
+        {children}
+      </button>
+    </th>
+  );
+}
+interface Props {
+  column: SortBy;
+  sort: Sort;
+  onSort: (column: SortBy) => void;
+  numeric?: boolean;
+  children: React.ReactNode;
+}
 render(<UsersPage />);
 ```
 
@@ -173,38 +274,70 @@ render(<UsersPage />);
 
 :::vue
 
-```html title="UsersPage.vue" {24}
+```html title="UsersPage.vue" {12-15}
 <script setup lang="ts">
-  import { Query, All } from '@data-client/rest';
-  import { useQuery, useFetch } from '@data-client/vue';
-  import { UserResource, User } from './UserResource';
-
-  interface Args {
-    asc: boolean;
-    isAdmin?: boolean;
+  import { ref } from 'vue';
+  import { useQuery, useSuspense } from '@data-client/vue';
+  import { UserResource } from './resources/User';
+  import { sortedUsers, type Sort, type SortBy } from './sortedUsers';
+
+  const filters = { All: undefined, Admins: true, Members: false };
+
+  await useSuspense(UserResource.getList);
+  const sort = ref<Sort>({ sortBy: 'name', desc: false });
+  const isAdmin = ref<boolean>();
+  const users = useQuery(sortedUsers, () => ({
+    ...sort.value,
+    isAdmin: isAdmin.value,
+  }));
+  function onSort(sortBy: SortBy) {
+    const desc = sort.value.sortBy === sortBy && !sort.value.desc;
+    sort.value = { sortBy, desc };
+  }
+  function ariaSort(column: SortBy) {
+    if (sort.value.sortBy !== column) return undefined;
+    return sort.value.desc ? 'descending' : 'ascending';
   }
-  const sortedUsers = new Query(
-    new All(User),
-    (entries, { asc, isAdmin }: Args = { asc: false }) => {
-      let sorted = [...entries].sort((a, b) =>
-        a.name.localeCompare(b.name),
-      );
-      if (isAdmin !== undefined)
-        sorted = sorted.filter(user => user.isAdmin === isAdmin);
-      if (asc) return sorted;
-      return sorted.reverse();
-    },
-  );
-
-  useFetch(UserResource.getList);
-  const users = useQuery(sortedUsers, { asc: true });
 </script>
 
 <template>
-  <div v-if="!users">No users in cache yet</div>
-  <div v-else>
-    <div v-for="user in users" :key="user.pk()">{{ user.name }}</div>
-  </div>
+  <header class="appHeader">
+    <h1 class="appTitle">Team</h1>
+    <div class="buttonGroup">
+      <button
+        v-for="(value, label) in filters"
+        :key="label"
+        :aria-pressed="isAdmin === value"
+        @click="isAdmin = value"
+      >
+        {{ label }}
+      </button>
+    </div>
+  </header>
+  <table>
+    <thead>
+      <tr>
+        <th :aria-sort="ariaSort('name')">
+          <button class="sort" @click="onSort('name')">Name</button>
+        </th>
+        <th>Role</th>
+        <th class="value" :aria-sort="ariaSort('posts')">
+          <button class="sort" @click="onSort('posts')">Posts</button>
+        </th>
+        <th class="value" :aria-sort="ariaSort('joined')">
+          <button class="sort" @click="onSort('joined')">Joined</button>
+        </th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr v-for="user in users" :key="user.pk()">
+        <td>{{ user.name }}</td>
+        <td class="meta">{{ user.isAdmin ? 'Admin' : 'Member' }}</td>
+        <td class="value">{{ user.posts }}</td>
+        <td class="value">{{ user.joined }}</td>
+      </tr>
+    </tbody>
+  </table>
 </template>
 ```
 
diff --git a/docs/rest/shared/_ScalarDemo.mdx b/docs/rest/shared/_ScalarDemo.mdx
index 44c68a0eb7cb..247fe4958e34 100644
--- a/docs/rest/shared/_ScalarDemo.mdx
+++ b/docs/rest/shared/_ScalarDemo.mdx
@@ -50,26 +50,26 @@ import { type Company } from './api/Company';
 
 export default function CompanyGrid({ companies }: { companies: Company[] }) {
   return (
-    <table style={{ marginTop: 8, width: '100%' }}>
+    <table>
       <thead>
         <tr>
-          <th align="left">Name</th>
-          <th align="right">Price</th>
-          <th align="right">% Equity</th>
-          <th align="right">Shares</th>
+          <th>Name</th>
+          <th className="value">Price</th>
+          <th className="value">% Equity</th>
+          <th className="value">Shares</th>
         </tr>
       </thead>
       <tbody>
         {companies.map(c => (
           <tr key={c.pk()}>
             <td>{c.name}</td>
-            <td align="right">${c.price.toFixed(2)}</td>
-            <td align="right">
+            <td className="value">${c.price.toFixed(2)}</td>
+            <td className="value">
               {c.pct_equity === undefined ?
                 <span className="skeleton" />
               : formatPercent(c.pct_equity)}
             </td>
-            <td align="right">
+            <td className="value">
               {c.shares === undefined ?
                 <span className="skeleton" />
               : c.shares.toLocaleString()}
@@ -143,24 +143,24 @@ render(<PortfolioGrid />);
 </script>
 
 <template>
-  <table style="margin-top: 8px; width: 100%">
+  <table>
     <thead>
       <tr>
-        <th align="left">Name</th>
-        <th align="right">Price</th>
-        <th align="right">% Equity</th>
-        <th align="right">Shares</th>
+        <th>Name</th>
+        <th class="value">Price</th>
+        <th class="value">% Equity</th>
+        <th class="value">Shares</th>
       </tr>
     </thead>
     <tbody>
       <tr v-for="c in companies" :key="c.pk()">
         <td>{{ c.name }}</td>
-        <td align="right">${{ c.price.toFixed(2) }}</td>
-        <td align="right">
+        <td class="value">${{ c.price.toFixed(2) }}</td>
+        <td class="value">
           <span v-if="c.pct_equity === undefined" class="skeleton" />
           <template v-else>{{ formatPercent(c.pct_equity) }}</template>
         </td>
-        <td align="right">
+        <td class="value">
           <span v-if="c.shares === undefined" class="skeleton" />
           <template v-else>{{ c.shares.toLocaleString() }}</template>
         </td>
diff --git a/website/src/components/Playground/DesignSystem/base.css b/website/src/components/Playground/DesignSystem/base.css
index 21e5772796a0..3b95d67c7344 100644
--- a/website/src/components/Playground/DesignSystem/base.css
+++ b/website/src/components/Playground/DesignSystem/base.css
@@ -54,6 +54,12 @@
     var(--ds-accent) var(--ds-accent-wash),
     transparent
   );
+  /* a pressed control's (or a chosen segment's) opaque wash */
+  --ds-accent-pressed: color-mix(
+    in srgb,
+    var(--ds-accent) var(--ds-accent-press),
+    var(--ds-surface)
+  );
   --ds-on-accent: #fff;
   /* Infima's own vars, re-pointed so what reads them (the rt-* fields, links,
      the error panel's text) follows this palette in both themes */
diff --git a/website/src/components/Playground/DesignSystem/design-system.css b/website/src/components/Playground/DesignSystem/design-system.css
index 8f3319a63362..3e2277e47b5e 100644
--- a/website/src/components/Playground/DesignSystem/design-system.css
+++ b/website/src/components/Playground/DesignSystem/design-system.css
@@ -52,10 +52,12 @@ div.playground-preview h1:first-child {
   margin-bottom: 0;
 }
 /* A group's label over its rows (a section's "Comments", a board column's
-   name): small, muted and semibold, so weight alone marks the group. A
-   row's own title (a post's h3 in a list) stays a heading */
+   name, a table's column): small, muted and semibold, so weight alone
+   marks the group. A row's own title (a post's h3 in a list) stays a
+   heading */
 .playground-preview section > h3,
-.playground-preview .boardColumn > h4 {
+.playground-preview .boardColumn > h4,
+.playground-preview th {
   margin: 0 0 6px;
   font: 600 var(--ds-text-sm) / 1.4 var(--ifm-font-family-base);
   letter-spacing: 0;
@@ -285,14 +287,10 @@ div.playground-preview h1:first-child {
   color: var(--ds-accent);
 }
 .playground-preview button:where(:not([class])):active {
-  background: color-mix(
-    in srgb,
-    var(--ds-accent) var(--ds-accent-press),
-    var(--ds-surface)
-  );
+  background: var(--ds-accent-pressed);
 }
 .playground-preview
-  button:where(:not([class]), .primary, .upvote):focus-visible {
+  button:where(:not([class]), .primary, .upvote, .sort):focus-visible {
   outline: 2px solid var(--ds-accent);
   outline-offset: 2px;
 }
@@ -459,7 +457,9 @@ div.playground-preview h1:first-child {
 .playground-preview .listItem:has(> .upvote) {
   align-items: flex-start;
 }
-.playground-preview button.upvote::before {
+/* an arrow pointing up: an upvote's, a sorted column's */
+.playground-preview button.upvote::before,
+.playground-preview button.sort::after {
   content: '';
   width: 12px;
   height: 7px;
@@ -475,11 +475,7 @@ div.playground-preview h1:first-child {
 }
 .playground-preview button.upvote:active,
 .playground-preview .stepper > button:active {
-  background: color-mix(
-    in srgb,
-    var(--ds-accent) var(--ds-accent-press),
-    var(--ds-surface)
-  );
+  background: var(--ds-accent-pressed);
   color: var(--ds-accent);
 }
 /* Figures side by side (`dl.stats`, each a div of dt then dd): the number
@@ -755,11 +751,7 @@ div.playground-preview h1:first-child {
 .playground-preview
   .buttonGroup
   > button:not([class], [aria-busy='true']):active {
-  background: color-mix(
-    in srgb,
-    var(--ds-accent) var(--ds-accent-press),
-    var(--ds-surface)
-  );
+  background: var(--ds-accent-pressed);
 }
 /* a busy segment's light runs inside the group's edge (outranking the
    segment's border: 0) */
@@ -770,6 +762,114 @@ div.playground-preview h1:first-child {
 .playground-preview .buttonGroup > button:focus-visible {
   outline-offset: -2px;
 }
+/* a filter's choice (All, Admins): the chosen segment washed in the
+   accent as a pressed one is, in the accent's color */
+.playground-preview .buttonGroup > button[aria-pressed='true']:not([class]) {
+  background: var(--ds-accent-pressed);
+  color: var(--ds-accent);
+}
+/* in an app header, level with the wordmark */
+.playground-preview .appHeader .buttonGroup {
+  margin-top: 0;
+}
+/* A table (a team's members): rows on the sheet with no rules or stripes,
+   set apart by space, their text in line with the app header's; under the
+   pointer a row is a rounded band reaching past its text, as a list's.
+   Headers are a group's label. `value` cells (a count, a year) sit at the
+   column's end. Infima's borders and stripes are dropped */
+.playground-preview table {
+  --ifm-table-stripe-background: transparent;
+  width: calc(100% + 2 * var(--ds-space-3));
+  margin: 0 calc(-1 * var(--ds-space-3)) var(--ds-space-4);
+  border-collapse: separate;
+  border-spacing: 0;
+}
+/* under a control (a picker) it stands a step off */
+.playground-preview * + table {
+  margin-top: var(--ds-space-3);
+}
+.playground-preview :is(thead, tr, th, td) {
+  border: 0;
+}
+.playground-preview td {
+  padding: var(--ds-space-2) var(--ds-space-3);
+  vertical-align: baseline;
+  transition: background-color var(--motion-snappy);
+}
+.playground-preview th {
+  padding: 0 var(--ds-space-3) var(--ds-space-1);
+  text-align: start;
+  /* a sort arrow has no baseline: centered, every label stays level */
+  vertical-align: middle;
+  white-space: nowrap;
+}
+.playground-preview :is(th, td).value {
+  text-align: end;
+}
+@media (hover: hover) {
+  .playground-preview tbody tr:hover > td {
+    background: var(--ds-hover);
+  }
+}
+.playground-preview tbody td:first-child {
+  border-radius: var(--ds-radius-sm) 0 0 var(--ds-radius-sm);
+}
+.playground-preview tbody td:last-child {
+  border-radius: 0 var(--ds-radius-sm) var(--ds-radius-sm) 0;
+}
+/* A sortable column's header (`button.sort` in its `th`, `aria-sort` on
+   the sorted one's): its label, then an arrow that points the way the
+   column runs, in the accent; the sorted column's label takes the text's
+   color. The arrow always holds its place, so a header never shifts; on
+   another column it shows faintly under the pointer. In a `value` column
+   it leads the label, so the label ends where the figures do */
+.playground-preview button.sort {
+  display: inline-flex;
+  align-items: center;
+  gap: 4px;
+  margin: -2px -4px;
+  padding: 2px 4px;
+  border: 0;
+  border-radius: var(--ds-radius-xs);
+  background: none;
+  color: inherit;
+  font: inherit;
+  cursor: pointer;
+  transition: color var(--motion-snappy);
+}
+.playground-preview th.value > button.sort {
+  flex-direction: row-reverse;
+}
+.playground-preview button.sort::after {
+  width: 8px;
+  height: 5px;
+  opacity: 0;
+  transition:
+    opacity var(--motion-snappy),
+    transform var(--motion-snappy);
+}
+.playground-preview button.sort:focus-visible {
+  outline-offset: 0;
+}
+.playground-preview button.sort:active,
+.playground-preview th[aria-sort] > button.sort {
+  color: var(--ds-text);
+}
+@media (hover: hover) {
+  .playground-preview button.sort:hover {
+    color: var(--ds-text);
+  }
+  .playground-preview button.sort:hover::after {
+    opacity: 0.4;
+  }
+}
+.playground-preview th[aria-sort] > button.sort::after {
+  background: var(--ds-accent);
+  opacity: 1;
+}
+.playground-preview th[aria-sort='descending'] > button.sort::after {
+  transform: rotate(180deg);
+}
 /* Actions under rows (a clock's Refresh) stand 16px off the last one */
 .playground-preview .listItem + button {
   margin-top: var(--ds-space-2);
diff --git a/website/src/components/Playground/README.md b/website/src/components/Playground/README.md
index 39cf6df9db28..c6cb7c8601e3 100644
--- a/website/src/components/Playground/README.md
+++ b/website/src/components/Playground/README.md
@@ -235,7 +235,8 @@ controls keep an edge). Before restyling a class, grep `docs/` and
 style to a new component.
 
 Styled elements: `h2` (page title), `button` (`primary` fills one;
-`aria-busy` shows pending), text inputs, `nav`, `fieldset`, `progress`.
+`aria-busy` shows pending), text inputs, `nav`, `fieldset`, `progress`,
+`table`.
 
 | Class                                      | Use for                                                                        |
 | ------------------------------------------ | ------------------------------------------------------------------------------ |
@@ -245,7 +246,7 @@ Styled elements: `h2` (page title), `button` (`primary` fills one;
 | `meta`                                     | secondary text; last in a `listItem`, it sits at the row's end                 |
 | `value`                                    | a row's figure (a price); last in a `listItem`, at the row's end, tabular      |
 | `byline`, `author` (`Avatar` takes `size`) | who wrote something                                                            |
-| `buttonGroup`                              | a row of actions as one segmented control                                      |
+| `buttonGroup`                              | segmented actions or a filter (`aria-pressed` marks its pick)                  |
 | `cancel` (`<CancelButton />`)              | a row's remove button                                                          |
 | `skeleton`                                 | a value still loading; `<Loading />`, the default fallback, draws a page       |
 | `toaster`, `toast`                         | notifications: render `<Toaster />`, call `toast.success()` or `toast.error()` |
@@ -253,6 +254,7 @@ Styled elements: `h2` (page title), `button` (`primary` fills one;
 | `upvote` (a button)                        | an upvote with its count; empty, the arrow alone                               |
 | `stats` (a `dl`)                           | figures side by side, each large over its label; a lone one fills the row      |
 | `stepper` (− `output` +)                   | a quantity's buttons around its count (one button alone: Add); in a row        |
+| `table` (`value` cells), `sort` (a button) | rule-free rows; a `th`'s `button.sort` sorts, `aria-sort` marks the sorted     |
 
 ## Auto-run
 
diff --git a/website/src/fixtures/team.ts b/website/src/fixtures/team.ts
new file mode 100644
index 000000000000..ac9d87a2462c
--- /dev/null
+++ b/website/src/fixtures/team.ts
@@ -0,0 +1,21 @@
+import { RestEndpoint } from '@data-client/rest';
+
+// out of every sort order, so the first one already moves the rows
+const members = [
+  { id: '4', name: 'Maya Chen', isAdmin: true, posts: 412, joined: 2018 },
+  { id: '7', name: 'Leo Fischer', isAdmin: false, posts: 36, joined: 2024 },
+  { id: '2', name: 'Ama Owusu', isAdmin: false, posts: 187, joined: 2020 },
+  { id: '9', name: 'Sofia Reyes', isAdmin: true, posts: 95, joined: 2022 },
+  { id: '3', name: 'Ravi Kumar', isAdmin: false, posts: 268, joined: 2019 },
+  { id: '5', name: 'Hana Sato', isAdmin: false, posts: 71, joined: 2023 },
+  { id: '8', name: 'Elias Berg', isAdmin: true, posts: 153, joined: 2017 },
+];
+
+export const teamFixtures = [
+  {
+    endpoint: new RestEndpoint({ path: '/users' }),
+    args: [],
+    response: members,
+    delay: 150,
+  },
+];

From 13890de9a68db72d53a995d4536f9c1f299b27e3 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 27 Oct 2026 03:30:40 +0000
Subject: [PATCH 02/10] docs: Regenerate skill references for the useQuery
 table demo

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y5C5ZC3WYndrqLXmu9F42e
---
 .../data-client-react/references/useQuery.md  | 141 +++++++++++++++---
 .../data-client-schema/references/Scalar.md   |  16 +-
 .../references/Scalar.vue.md                  |  16 +-
 .../references/_ScalarDemo.md                 |  16 +-
 .../references/_ScalarDemo.vue.md             |  16 +-
 .../data-client-vue/references/useQuery.md    | 120 +++++++++++----
 6 files changed, 242 insertions(+), 83 deletions(-)

diff --git a/.agents/skills/data-client-react/references/useQuery.md b/.agents/skills/data-client-react/references/useQuery.md
index 9dd95fe6f748..1c4ac5cb28ff 100644
--- a/.agents/skills/data-client-react/references/useQuery.md
+++ b/.agents/skills/data-client-react/references/useQuery.md
@@ -189,15 +189,18 @@ interface Queryable {
 
 ### Sorting & Filtering
 
-[Query](https://dataclient.io/rest/api/Query) provides programmatic access to the Reactive Data Client store.
+[Query](https://dataclient.io/rest/api/Query) sorts and filters what is already in the store, so picking another column
+re-sorts the table without fetching again.
 
-```ts title="UserResource"
+```ts title="resources/User"
 import { Entity, resource } from '@data-client/rest';
 
 export class User extends Entity {
   id = '';
   name = '';
   isAdmin = false;
+  posts = 0;
+  joined = 0;
 
   static key = 'User';
 }
@@ -207,38 +210,130 @@ export const UserResource = resource({
 });
 ```
 
-```tsx title="UsersPage" {22}
+```ts title="sortedUsers"
 import { All, Query } from '@data-client/rest';
-import { useQuery, useFetch } from '@data-client/react';
-import { UserResource, User } from './UserResource';
+import { User } from './resources/User';
 
-interface Args {
-  asc: boolean;
-  isAdmin?: boolean;
+export type SortBy = 'name' | 'posts' | 'joined';
+export interface Sort {
+  sortBy: SortBy;
+  desc: boolean;
+}
+interface Args extends Sort {
+  /** admins only (true), members only (false), or everyone */
+  isAdmin: boolean | undefined;
 }
-const sortedUsers = new Query(
+
+export const sortedUsers = new Query(
   new All(User),
-  (entries, { asc, isAdmin }: Args = { asc: false }) => {
-    let sorted = [...entries].sort((a, b) => a.name.localeCompare(b.name));
-    if (isAdmin !== undefined)
-      sorted = sorted.filter(user => user.isAdmin === isAdmin);
-    if (asc) return sorted;
-    return sorted.reverse();
+  (entries, { sortBy, desc, isAdmin }: Args) => {
+    const users = entries
+      .filter(user => isAdmin === undefined || user.isAdmin === isAdmin)
+      .sort((a, b) =>
+        sortBy === 'name' ?
+          a.name.localeCompare(b.name)
+        : a[sortBy] - b[sortBy],
+      );
+    return desc ? users.reverse() : users;
   },
 );
+```
+
+```tsx title="UsersPage" {15}
+import React from 'react';
+import { useQuery, useSuspense } from '@data-client/react';
+import { UserResource } from './resources/User';
+import { sortedUsers, type Sort, type SortBy } from './sortedUsers';
+
+const filters = { All: undefined, Admins: true, Members: false };
 
 function UsersPage() {
-  useFetch(UserResource.getList);
-  const users = useQuery(sortedUsers, { asc: true });
-  if (!users) return <div>No users in cache yet</div>;
+  useSuspense(UserResource.getList);
+  const [sort, setSort] = React.useState<Sort>({
+    sortBy: 'name',
+    desc: false,
+  });
+  const [isAdmin, setIsAdmin] = React.useState<boolean>();
+  const users = useQuery(sortedUsers, { ...sort, isAdmin }) ?? [];
+  const onSort = (sortBy: SortBy) =>
+    setSort(prev => ({
+      sortBy,
+      desc: prev.sortBy === sortBy && !prev.desc,
+    }));
+
   return (
-    <div>
-      {users.map(user => (
-        <div key={user.pk()}>{user.name}</div>
-      ))}
-    </div>
+    <>
+      <header className="appHeader">
+        <h1 className="appTitle">Team</h1>
+        <div className="buttonGroup">
+          {Object.entries(filters).map(([label, value]) => (
+            <button
+              key={label}
+              aria-pressed={isAdmin === value}
+              onClick={() => setIsAdmin(value)}
+            >
+              {label}
+            </button>
+          ))}
+        </div>
+      </header>
+      <table>
+        <thead>
+          <tr>
+            <SortHeader column="name" sort={sort} onSort={onSort}>
+              Name
+            </SortHeader>
+            <th>Role</th>
+            <SortHeader column="posts" sort={sort} onSort={onSort} numeric>
+              Posts
+            </SortHeader>
+            <SortHeader
+              column="joined"
+              sort={sort}
+              onSort={onSort}
+              numeric
+            >
+              Joined
+            </SortHeader>
+          </tr>
+        </thead>
+        <tbody>
+          {users.map(user => (
+            <tr key={user.pk()}>
+              <td>{user.name}</td>
+              <td className="meta">{user.isAdmin ? 'Admin' : 'Member'}</td>
+              <td className="value">{user.posts}</td>
+              <td className="value">{user.joined}</td>
+            </tr>
+          ))}
+        </tbody>
+      </table>
+    </>
   );
 }
+
+function SortHeader({ column, sort, onSort, numeric, children }: Props) {
+  const sorted = sort.sortBy === column;
+  return (
+    <th
+      className={numeric ? 'value' : undefined}
+      aria-sort={
+        sorted ? (sort.desc ? 'descending' : 'ascending') : undefined
+      }
+    >
+      <button className="sort" onClick={() => onSort(column)}>
+        {children}
+      </button>
+    </th>
+  );
+}
+interface Props {
+  column: SortBy;
+  sort: Sort;
+  onSort: (column: SortBy) => void;
+  numeric?: boolean;
+  children: React.ReactNode;
+}
 render(<UsersPage />);
 ```
 
diff --git a/.agents/skills/data-client-schema/references/Scalar.md b/.agents/skills/data-client-schema/references/Scalar.md
index 9bc31ebf755d..8257c3ff82cb 100644
--- a/.agents/skills/data-client-schema/references/Scalar.md
+++ b/.agents/skills/data-client-schema/references/Scalar.md
@@ -69,26 +69,26 @@ import { type Company } from './api/Company';
 
 export default function CompanyGrid({ companies }: { companies: Company[] }) {
   return (
-    <table style={{ marginTop: 8, width: '100%' }}>
+    <table>
       <thead>
         <tr>
-          <th align="left">Name</th>
-          <th align="right">Price</th>
-          <th align="right">% Equity</th>
-          <th align="right">Shares</th>
+          <th>Name</th>
+          <th className="value">Price</th>
+          <th className="value">% Equity</th>
+          <th className="value">Shares</th>
         </tr>
       </thead>
       <tbody>
         {companies.map(c => (
           <tr key={c.pk()}>
             <td>{c.name}</td>
-            <td align="right">${c.price.toFixed(2)}</td>
-            <td align="right">
+            <td className="value">${c.price.toFixed(2)}</td>
+            <td className="value">
               {c.pct_equity === undefined ?
                 <span className="skeleton" />
               : formatPercent(c.pct_equity)}
             </td>
-            <td align="right">
+            <td className="value">
               {c.shares === undefined ?
                 <span className="skeleton" />
               : c.shares.toLocaleString()}
diff --git a/.agents/skills/data-client-schema/references/Scalar.vue.md b/.agents/skills/data-client-schema/references/Scalar.vue.md
index 9b074a3853d4..ada76d888082 100644
--- a/.agents/skills/data-client-schema/references/Scalar.vue.md
+++ b/.agents/skills/data-client-schema/references/Scalar.vue.md
@@ -76,24 +76,24 @@ export const getPortfolioColumns = new RestEndpoint({
 </script>
 
 <template>
-  <table style="margin-top: 8px; width: 100%">
+  <table>
     <thead>
       <tr>
-        <th align="left">Name</th>
-        <th align="right">Price</th>
-        <th align="right">% Equity</th>
-        <th align="right">Shares</th>
+        <th>Name</th>
+        <th class="value">Price</th>
+        <th class="value">% Equity</th>
+        <th class="value">Shares</th>
       </tr>
     </thead>
     <tbody>
       <tr v-for="c in companies" :key="c.pk()">
         <td>{{ c.name }}</td>
-        <td align="right">${{ c.price.toFixed(2) }}</td>
-        <td align="right">
+        <td class="value">${{ c.price.toFixed(2) }}</td>
+        <td class="value">
           <span v-if="c.pct_equity === undefined" class="skeleton" />
           <template v-else>{{ formatPercent(c.pct_equity) }}</template>
         </td>
-        <td align="right">
+        <td class="value">
           <span v-if="c.shares === undefined" class="skeleton" />
           <template v-else>{{ c.shares.toLocaleString() }}</template>
         </td>
diff --git a/.agents/skills/data-client-schema/references/_ScalarDemo.md b/.agents/skills/data-client-schema/references/_ScalarDemo.md
index 359227e6c424..ff4fa60a6683 100644
--- a/.agents/skills/data-client-schema/references/_ScalarDemo.md
+++ b/.agents/skills/data-client-schema/references/_ScalarDemo.md
@@ -45,26 +45,26 @@ import { type Company } from './api/Company';
 
 export default function CompanyGrid({ companies }: { companies: Company[] }) {
   return (
-    <table style={{ marginTop: 8, width: '100%' }}>
+    <table>
       <thead>
         <tr>
-          <th align="left">Name</th>
-          <th align="right">Price</th>
-          <th align="right">% Equity</th>
-          <th align="right">Shares</th>
+          <th>Name</th>
+          <th className="value">Price</th>
+          <th className="value">% Equity</th>
+          <th className="value">Shares</th>
         </tr>
       </thead>
       <tbody>
         {companies.map(c => (
           <tr key={c.pk()}>
             <td>{c.name}</td>
-            <td align="right">${c.price.toFixed(2)}</td>
-            <td align="right">
+            <td className="value">${c.price.toFixed(2)}</td>
+            <td className="value">
               {c.pct_equity === undefined ?
                 <span className="skeleton" />
               : formatPercent(c.pct_equity)}
             </td>
-            <td align="right">
+            <td className="value">
               {c.shares === undefined ?
                 <span className="skeleton" />
               : c.shares.toLocaleString()}
diff --git a/.agents/skills/data-client-schema/references/_ScalarDemo.vue.md b/.agents/skills/data-client-schema/references/_ScalarDemo.vue.md
index f592ac0b0aa4..4eb2c008e753 100644
--- a/.agents/skills/data-client-schema/references/_ScalarDemo.vue.md
+++ b/.agents/skills/data-client-schema/references/_ScalarDemo.vue.md
@@ -52,24 +52,24 @@ export const getPortfolioColumns = new RestEndpoint({
 </script>
 
 <template>
-  <table style="margin-top: 8px; width: 100%">
+  <table>
     <thead>
       <tr>
-        <th align="left">Name</th>
-        <th align="right">Price</th>
-        <th align="right">% Equity</th>
-        <th align="right">Shares</th>
+        <th>Name</th>
+        <th class="value">Price</th>
+        <th class="value">% Equity</th>
+        <th class="value">Shares</th>
       </tr>
     </thead>
     <tbody>
       <tr v-for="c in companies" :key="c.pk()">
         <td>{{ c.name }}</td>
-        <td align="right">${{ c.price.toFixed(2) }}</td>
-        <td align="right">
+        <td class="value">${{ c.price.toFixed(2) }}</td>
+        <td class="value">
           <span v-if="c.pct_equity === undefined" class="skeleton" />
           <template v-else>{{ formatPercent(c.pct_equity) }}</template>
         </td>
-        <td align="right">
+        <td class="value">
           <span v-if="c.shares === undefined" class="skeleton" />
           <template v-else>{{ c.shares.toLocaleString() }}</template>
         </td>
diff --git a/.agents/skills/data-client-vue/references/useQuery.md b/.agents/skills/data-client-vue/references/useQuery.md
index c280db697285..4c1efdb0e62e 100644
--- a/.agents/skills/data-client-vue/references/useQuery.md
+++ b/.agents/skills/data-client-vue/references/useQuery.md
@@ -182,15 +182,18 @@ interface Queryable {
 
 ### Sorting & Filtering
 
-[Query](https://dataclient.io/rest/api/Query) provides programmatic access to the Reactive Data Client store.
+[Query](https://dataclient.io/rest/api/Query) sorts and filters what is already in the store, so picking another column
+re-sorts the table without fetching again.
 
-```ts title="UserResource"
+```ts title="resources/User"
 import { Entity, resource } from '@data-client/rest';
 
 export class User extends Entity {
   id = '';
   name = '';
   isAdmin = false;
+  posts = 0;
+  joined = 0;
 
   static key = 'User';
 }
@@ -200,38 +203,99 @@ export const UserResource = resource({
 });
 ```
 
-```html title="UsersPage.vue" {24}
-<script setup lang="ts">
-  import { Query, All } from '@data-client/rest';
-  import { useQuery, useFetch } from '@data-client/vue';
-  import { UserResource, User } from './UserResource';
+```ts title="sortedUsers"
+import { All, Query } from '@data-client/rest';
+import { User } from './resources/User';
 
-  interface Args {
-    asc: boolean;
-    isAdmin?: boolean;
-  }
-  const sortedUsers = new Query(
-    new All(User),
-    (entries, { asc, isAdmin }: Args = { asc: false }) => {
-      let sorted = [...entries].sort((a, b) =>
-        a.name.localeCompare(b.name),
+export type SortBy = 'name' | 'posts' | 'joined';
+export interface Sort {
+  sortBy: SortBy;
+  desc: boolean;
+}
+interface Args extends Sort {
+  /** admins only (true), members only (false), or everyone */
+  isAdmin: boolean | undefined;
+}
+
+export const sortedUsers = new Query(
+  new All(User),
+  (entries, { sortBy, desc, isAdmin }: Args) => {
+    const users = entries
+      .filter(user => isAdmin === undefined || user.isAdmin === isAdmin)
+      .sort((a, b) =>
+        sortBy === 'name' ?
+          a.name.localeCompare(b.name)
+        : a[sortBy] - b[sortBy],
       );
-      if (isAdmin !== undefined)
-        sorted = sorted.filter(user => user.isAdmin === isAdmin);
-      if (asc) return sorted;
-      return sorted.reverse();
-    },
-  );
+    return desc ? users.reverse() : users;
+  },
+);
+```
 
-  useFetch(UserResource.getList);
-  const users = useQuery(sortedUsers, { asc: true });
+```html title="UsersPage.vue" {12-15}
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { useQuery, useSuspense } from '@data-client/vue';
+  import { UserResource } from './resources/User';
+  import { sortedUsers, type Sort, type SortBy } from './sortedUsers';
+
+  const filters = { All: undefined, Admins: true, Members: false };
+
+  await useSuspense(UserResource.getList);
+  const sort = ref<Sort>({ sortBy: 'name', desc: false });
+  const isAdmin = ref<boolean>();
+  const users = useQuery(sortedUsers, () => ({
+    ...sort.value,
+    isAdmin: isAdmin.value,
+  }));
+  function onSort(sortBy: SortBy) {
+    const desc = sort.value.sortBy === sortBy && !sort.value.desc;
+    sort.value = { sortBy, desc };
+  }
+  function ariaSort(column: SortBy) {
+    if (sort.value.sortBy !== column) return undefined;
+    return sort.value.desc ? 'descending' : 'ascending';
+  }
 </script>
 
 <template>
-  <div v-if="!users">No users in cache yet</div>
-  <div v-else>
-    <div v-for="user in users" :key="user.pk()">{{ user.name }}</div>
-  </div>
+  <header class="appHeader">
+    <h1 class="appTitle">Team</h1>
+    <div class="buttonGroup">
+      <button
+        v-for="(value, label) in filters"
+        :key="label"
+        :aria-pressed="isAdmin === value"
+        @click="isAdmin = value"
+      >
+        {{ label }}
+      </button>
+    </div>
+  </header>
+  <table>
+    <thead>
+      <tr>
+        <th :aria-sort="ariaSort('name')">
+          <button class="sort" @click="onSort('name')">Name</button>
+        </th>
+        <th>Role</th>
+        <th class="value" :aria-sort="ariaSort('posts')">
+          <button class="sort" @click="onSort('posts')">Posts</button>
+        </th>
+        <th class="value" :aria-sort="ariaSort('joined')">
+          <button class="sort" @click="onSort('joined')">Joined</button>
+        </th>
+      </tr>
+    </thead>
+    <tbody>
+      <tr v-for="user in users" :key="user.pk()">
+        <td>{{ user.name }}</td>
+        <td class="meta">{{ user.isAdmin ? 'Admin' : 'Member' }}</td>
+        <td class="value">{{ user.posts }}</td>
+        <td class="value">{{ user.joined }}</td>
+      </tr>
+    </tbody>
+  </table>
 </template>
 ```
 

From feabc36fc8b73a98c3c47035567e56bec050e86d Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 27 Oct 2026 03:34:52 +0000
Subject: [PATCH 03/10] docs: Keep the useQuery demo's Query and useQuery in
 one short page

UsersPage now holds just the Query and the state it reads with useQuery,
so the highlighted line sits beside the schema it uses. The table and
its sortable headers move to UsersTable (which decides how a header
click changes the sort), and the role switch to RoleFilter. Vue follows
the same split.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y5C5ZC3WYndrqLXmu9F42e
---
 .../data-client-react/references/useQuery.md  | 185 +++++-----
 .../data-client-vue/references/useQuery.md    | 150 +++++----
 docs/core/api/useQuery.md                     | 318 +++++++++++-------
 3 files changed, 388 insertions(+), 265 deletions(-)

diff --git a/.agents/skills/data-client-react/references/useQuery.md b/.agents/skills/data-client-react/references/useQuery.md
index 1c4ac5cb28ff..4743a69a236d 100644
--- a/.agents/skills/data-client-react/references/useQuery.md
+++ b/.agents/skills/data-client-react/references/useQuery.md
@@ -210,9 +210,106 @@ export const UserResource = resource({
 });
 ```
 
-```ts title="sortedUsers"
+```tsx title="RoleFilter"
+const roles = { All: undefined, Admins: true, Members: false };
+
+export default function RoleFilter({ isAdmin, onChange }: Props) {
+  return (
+    <div className="buttonGroup" role="group" aria-label="Role">
+      {Object.entries(roles).map(([label, value]) => (
+        <button
+          key={label}
+          aria-pressed={isAdmin === value}
+          onClick={() => onChange(value)}
+        >
+          {label}
+        </button>
+      ))}
+    </div>
+  );
+}
+interface Props {
+  isAdmin: boolean | undefined;
+  onChange: (isAdmin: boolean | undefined) => void;
+}
+```
+
+```tsx title="UsersTable"
+import React from 'react';
+import { type User } from './resources/User';
+import { type Sort, type SortBy } from './UsersPage';
+
+export default function UsersTable({ users, sort, onSort }: Props) {
+  return (
+    <table>
+      <thead>
+        <tr>
+          <SortHeader column="name" sort={sort} onSort={onSort}>
+            Name
+          </SortHeader>
+          <th>Role</th>
+          <SortHeader column="posts" sort={sort} onSort={onSort} numeric>
+            Posts
+          </SortHeader>
+          <SortHeader column="joined" sort={sort} onSort={onSort} numeric>
+            Joined
+          </SortHeader>
+        </tr>
+      </thead>
+      <tbody>
+        {users.map(user => (
+          <tr key={user.pk()}>
+            <td>{user.name}</td>
+            <td className="meta">{user.isAdmin ? 'Admin' : 'Member'}</td>
+            <td className="value">{user.posts}</td>
+            <td className="value">{user.joined}</td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+interface Props {
+  users: User[];
+  sort: Sort;
+  onSort: (sort: Sort) => void;
+}
+
+/** A column's header: sorts by it, and a second click reverses it */
+function SortHeader({ column, sort, onSort, numeric, children }: HeaderProps) {
+  const sorted = sort.sortBy === column;
+  return (
+    <th
+      className={numeric ? 'value' : undefined}
+      aria-sort={
+        sorted ? (sort.desc ? 'descending' : 'ascending') : undefined
+      }
+    >
+      <button
+        className="sort"
+        onClick={() => onSort({ sortBy: column, desc: sorted && !sort.desc })}
+      >
+        {children}
+      </button>
+    </th>
+  );
+}
+interface HeaderProps {
+  column: SortBy;
+  sort: Sort;
+  onSort: (sort: Sort) => void;
+  numeric?: boolean;
+  children: React.ReactNode;
+}
+```
+
+```tsx title="UsersPage" {39}
+import React from 'react';
 import { All, Query } from '@data-client/rest';
-import { User } from './resources/User';
+import { useQuery, useSuspense } from '@data-client/react';
+import { User, UserResource } from './resources/User';
+import RoleFilter from './RoleFilter';
+import UsersTable from './UsersTable';
 
 export type SortBy = 'name' | 'posts' | 'joined';
 export interface Sort {
@@ -224,7 +321,7 @@ interface Args extends Sort {
   isAdmin: boolean | undefined;
 }
 
-export const sortedUsers = new Query(
+const sortedUsers = new Query(
   new All(User),
   (entries, { sortBy, desc, isAdmin }: Args) => {
     const users = entries
@@ -237,15 +334,6 @@ export const sortedUsers = new Query(
     return desc ? users.reverse() : users;
   },
 );
-```
-
-```tsx title="UsersPage" {15}
-import React from 'react';
-import { useQuery, useSuspense } from '@data-client/react';
-import { UserResource } from './resources/User';
-import { sortedUsers, type Sort, type SortBy } from './sortedUsers';
-
-const filters = { All: undefined, Admins: true, Members: false };
 
 function UsersPage() {
   useSuspense(UserResource.getList);
@@ -255,85 +343,16 @@ function UsersPage() {
   });
   const [isAdmin, setIsAdmin] = React.useState<boolean>();
   const users = useQuery(sortedUsers, { ...sort, isAdmin }) ?? [];
-  const onSort = (sortBy: SortBy) =>
-    setSort(prev => ({
-      sortBy,
-      desc: prev.sortBy === sortBy && !prev.desc,
-    }));
-
   return (
     <>
       <header className="appHeader">
         <h1 className="appTitle">Team</h1>
-        <div className="buttonGroup">
-          {Object.entries(filters).map(([label, value]) => (
-            <button
-              key={label}
-              aria-pressed={isAdmin === value}
-              onClick={() => setIsAdmin(value)}
-            >
-              {label}
-            </button>
-          ))}
-        </div>
+        <RoleFilter isAdmin={isAdmin} onChange={setIsAdmin} />
       </header>
-      <table>
-        <thead>
-          <tr>
-            <SortHeader column="name" sort={sort} onSort={onSort}>
-              Name
-            </SortHeader>
-            <th>Role</th>
-            <SortHeader column="posts" sort={sort} onSort={onSort} numeric>
-              Posts
-            </SortHeader>
-            <SortHeader
-              column="joined"
-              sort={sort}
-              onSort={onSort}
-              numeric
-            >
-              Joined
-            </SortHeader>
-          </tr>
-        </thead>
-        <tbody>
-          {users.map(user => (
-            <tr key={user.pk()}>
-              <td>{user.name}</td>
-              <td className="meta">{user.isAdmin ? 'Admin' : 'Member'}</td>
-              <td className="value">{user.posts}</td>
-              <td className="value">{user.joined}</td>
-            </tr>
-          ))}
-        </tbody>
-      </table>
+      <UsersTable users={users} sort={sort} onSort={setSort} />
     </>
   );
 }
-
-function SortHeader({ column, sort, onSort, numeric, children }: Props) {
-  const sorted = sort.sortBy === column;
-  return (
-    <th
-      className={numeric ? 'value' : undefined}
-      aria-sort={
-        sorted ? (sort.desc ? 'descending' : 'ascending') : undefined
-      }
-    >
-      <button className="sort" onClick={() => onSort(column)}>
-        {children}
-      </button>
-    </th>
-  );
-}
-interface Props {
-  column: SortBy;
-  sort: Sort;
-  onSort: (column: SortBy) => void;
-  numeric?: boolean;
-  children: React.ReactNode;
-}
 render(<UsersPage />);
 ```
 
diff --git a/.agents/skills/data-client-vue/references/useQuery.md b/.agents/skills/data-client-vue/references/useQuery.md
index 4c1efdb0e62e..34545e39853d 100644
--- a/.agents/skills/data-client-vue/references/useQuery.md
+++ b/.agents/skills/data-client-vue/references/useQuery.md
@@ -203,87 +203,60 @@ export const UserResource = resource({
 });
 ```
 
-```ts title="sortedUsers"
-import { All, Query } from '@data-client/rest';
-import { User } from './resources/User';
-
-export type SortBy = 'name' | 'posts' | 'joined';
-export interface Sort {
-  sortBy: SortBy;
-  desc: boolean;
-}
-interface Args extends Sort {
-  /** admins only (true), members only (false), or everyone */
-  isAdmin: boolean | undefined;
-}
+```html title="RoleFilter.vue"
+<script setup lang="ts">
+  const roles = { All: undefined, Admins: true, Members: false };
 
-export const sortedUsers = new Query(
-  new All(User),
-  (entries, { sortBy, desc, isAdmin }: Args) => {
-    const users = entries
-      .filter(user => isAdmin === undefined || user.isAdmin === isAdmin)
-      .sort((a, b) =>
-        sortBy === 'name' ?
-          a.name.localeCompare(b.name)
-        : a[sortBy] - b[sortBy],
-      );
-    return desc ? users.reverse() : users;
-  },
-);
+  defineProps<{ isAdmin: boolean | undefined }>();
+  const emit = defineEmits<{ change: [isAdmin: boolean | undefined] }>();
+</script>
+
+<template>
+  <div class="buttonGroup" role="group" aria-label="Role">
+    <button
+      v-for="(value, label) in roles"
+      :key="label"
+      :aria-pressed="isAdmin === value"
+      @click="emit('change', value)"
+    >
+      {{ label }}
+    </button>
+  </div>
+</template>
 ```
 
-```html title="UsersPage.vue" {12-15}
+```html title="UsersTable.vue"
 <script setup lang="ts">
-  import { ref } from 'vue';
-  import { useQuery, useSuspense } from '@data-client/vue';
-  import { UserResource } from './resources/User';
-  import { sortedUsers, type Sort, type SortBy } from './sortedUsers';
+  import { type User } from './resources/User';
+  import { type Sort, type SortBy } from './UsersPage.vue';
 
-  const filters = { All: undefined, Admins: true, Members: false };
+  const props = defineProps<{ users: readonly User[]; sort: Sort }>();
+  const emit = defineEmits<{ sort: [sort: Sort] }>();
 
-  await useSuspense(UserResource.getList);
-  const sort = ref<Sort>({ sortBy: 'name', desc: false });
-  const isAdmin = ref<boolean>();
-  const users = useQuery(sortedUsers, () => ({
-    ...sort.value,
-    isAdmin: isAdmin.value,
-  }));
-  function onSort(sortBy: SortBy) {
-    const desc = sort.value.sortBy === sortBy && !sort.value.desc;
-    sort.value = { sortBy, desc };
-  }
   function ariaSort(column: SortBy) {
-    if (sort.value.sortBy !== column) return undefined;
-    return sort.value.desc ? 'descending' : 'ascending';
+    if (props.sort.sortBy !== column) return undefined;
+    return props.sort.desc ? 'descending' : 'ascending';
+  }
+  // a second click on the sorted column reverses it
+  function sortBy(column: SortBy) {
+    const desc = props.sort.sortBy === column && !props.sort.desc;
+    emit('sort', { sortBy: column, desc });
   }
 </script>
 
 <template>
-  <header class="appHeader">
-    <h1 class="appTitle">Team</h1>
-    <div class="buttonGroup">
-      <button
-        v-for="(value, label) in filters"
-        :key="label"
-        :aria-pressed="isAdmin === value"
-        @click="isAdmin = value"
-      >
-        {{ label }}
-      </button>
-    </div>
-  </header>
   <table>
     <thead>
       <tr>
         <th :aria-sort="ariaSort('name')">
-          <button class="sort" @click="onSort('name')">Name</button>
+          <button class="sort" @click="sortBy('name')">Name</button>
         </th>
         <th>Role</th>
         <th class="value" :aria-sort="ariaSort('posts')">
-          <button class="sort" @click="onSort('posts')">Posts</button>
+          <button class="sort" @click="sortBy('posts')">Posts</button>
         </th>
         <th class="value" :aria-sort="ariaSort('joined')">
-          <button class="sort" @click="onSort('joined')">Joined</button>
+          <button class="sort" @click="sortBy('joined')">Joined</button>
         </th>
       </tr>
     </thead>
@@ -299,6 +272,61 @@ export const sortedUsers = new Query(
 </template>
 ```
 
+```html title="UsersPage.vue" {40-43}
+<script lang="ts">
+  import { All, Query } from '@data-client/rest';
+  import { User } from './resources/User';
+
+  export type SortBy = 'name' | 'posts' | 'joined';
+  export interface Sort {
+    sortBy: SortBy;
+    desc: boolean;
+  }
+  interface Args extends Sort {
+    /** admins only (true), members only (false), or everyone */
+    isAdmin: boolean | undefined;
+  }
+
+  const sortedUsers = new Query(
+    new All(User),
+    (entries, { sortBy, desc, isAdmin }: Args) => {
+      const users = entries
+        .filter(user => isAdmin === undefined || user.isAdmin === isAdmin)
+        .sort((a, b) =>
+          sortBy === 'name' ?
+            a.name.localeCompare(b.name)
+          : a[sortBy] - b[sortBy],
+        );
+      return desc ? users.reverse() : users;
+    },
+  );
+</script>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { useQuery, useSuspense } from '@data-client/vue';
+  import { UserResource } from './resources/User';
+  import RoleFilter from './RoleFilter.vue';
+  import UsersTable from './UsersTable.vue';
+
+  await useSuspense(UserResource.getList);
+  const sort = ref<Sort>({ sortBy: 'name', desc: false });
+  const isAdmin = ref<boolean>();
+  const users = useQuery(sortedUsers, () => ({
+    ...sort.value,
+    isAdmin: isAdmin.value,
+  }));
+</script>
+
+<template>
+  <header class="appHeader">
+    <h1 class="appTitle">Team</h1>
+    <RoleFilter :is-admin="isAdmin" @change="isAdmin = $event" />
+  </header>
+  <UsersTable :users="users ?? []" :sort="sort" @sort="sort = $event" />
+</template>
+```
+
 ### Lazy relationships
 
 [Lazy](https://dataclient.io/rest/api/Lazy) fields keep raw IDs during parent denormalization. Use [`.query`](https://dataclient.io/rest/api/Lazy#query) with `useQuery` to resolve them on demand,
diff --git a/docs/core/api/useQuery.md b/docs/core/api/useQuery.md
index eca86f477f89..16c23c23e2e6 100644
--- a/docs/core/api/useQuery.md
+++ b/docs/core/api/useQuery.md
@@ -119,7 +119,7 @@ re-sorts the table without fetching again.
 <FrameworkPlayground
 fixtures={teamFixtures}
 row
-defaultTab="sortedUsers"
+defaultTab="UsersPage"
 autoRun={sortDemo}
 >
 
@@ -141,9 +141,108 @@ export const UserResource = resource({
 });
 ```
 
-```ts title="sortedUsers"
+:::react
+
+```tsx title="RoleFilter" collapsed
+const roles = { All: undefined, Admins: true, Members: false };
+
+export default function RoleFilter({ isAdmin, onChange }: Props) {
+  return (
+    <div className="buttonGroup" role="group" aria-label="Role">
+      {Object.entries(roles).map(([label, value]) => (
+        <button
+          key={label}
+          aria-pressed={isAdmin === value}
+          onClick={() => onChange(value)}
+        >
+          {label}
+        </button>
+      ))}
+    </div>
+  );
+}
+interface Props {
+  isAdmin: boolean | undefined;
+  onChange: (isAdmin: boolean | undefined) => void;
+}
+```
+
+```tsx title="UsersTable" collapsed
+import React from 'react';
+import { type User } from './resources/User';
+import { type Sort, type SortBy } from './UsersPage';
+
+export default function UsersTable({ users, sort, onSort }: Props) {
+  return (
+    <table>
+      <thead>
+        <tr>
+          <SortHeader column="name" sort={sort} onSort={onSort}>
+            Name
+          </SortHeader>
+          <th>Role</th>
+          <SortHeader column="posts" sort={sort} onSort={onSort} numeric>
+            Posts
+          </SortHeader>
+          <SortHeader column="joined" sort={sort} onSort={onSort} numeric>
+            Joined
+          </SortHeader>
+        </tr>
+      </thead>
+      <tbody>
+        {users.map(user => (
+          <tr key={user.pk()}>
+            <td>{user.name}</td>
+            <td className="meta">{user.isAdmin ? 'Admin' : 'Member'}</td>
+            <td className="value">{user.posts}</td>
+            <td className="value">{user.joined}</td>
+          </tr>
+        ))}
+      </tbody>
+    </table>
+  );
+}
+interface Props {
+  users: User[];
+  sort: Sort;
+  onSort: (sort: Sort) => void;
+}
+
+/** A column's header: sorts by it, and a second click reverses it */
+function SortHeader({ column, sort, onSort, numeric, children }: HeaderProps) {
+  const sorted = sort.sortBy === column;
+  return (
+    <th
+      className={numeric ? 'value' : undefined}
+      aria-sort={
+        sorted ? (sort.desc ? 'descending' : 'ascending') : undefined
+      }
+    >
+      <button
+        className="sort"
+        onClick={() => onSort({ sortBy: column, desc: sorted && !sort.desc })}
+      >
+        {children}
+      </button>
+    </th>
+  );
+}
+interface HeaderProps {
+  column: SortBy;
+  sort: Sort;
+  onSort: (sort: Sort) => void;
+  numeric?: boolean;
+  children: React.ReactNode;
+}
+```
+
+```tsx title="UsersPage" {39}
+import React from 'react';
 import { All, Query } from '@data-client/rest';
-import { User } from './resources/User';
+import { useQuery, useSuspense } from '@data-client/react';
+import { User, UserResource } from './resources/User';
+import RoleFilter from './RoleFilter';
+import UsersTable from './UsersTable';
 
 export type SortBy = 'name' | 'posts' | 'joined';
 export interface Sort {
@@ -155,7 +254,7 @@ interface Args extends Sort {
   isAdmin: boolean | undefined;
 }
 
-export const sortedUsers = new Query(
+const sortedUsers = new Query(
   new All(User),
   (entries, { sortBy, desc, isAdmin }: Args) => {
     const users = entries
@@ -168,17 +267,6 @@ export const sortedUsers = new Query(
     return desc ? users.reverse() : users;
   },
 );
-```
-
-:::react
-
-```tsx title="UsersPage" {15}
-import React from 'react';
-import { useQuery, useSuspense } from '@data-client/react';
-import { UserResource } from './resources/User';
-import { sortedUsers, type Sort, type SortBy } from './sortedUsers';
-
-const filters = { All: undefined, Admins: true, Members: false };
 
 function UsersPage() {
   useSuspense(UserResource.getList);
@@ -188,85 +276,16 @@ function UsersPage() {
   });
   const [isAdmin, setIsAdmin] = React.useState<boolean>();
   const users = useQuery(sortedUsers, { ...sort, isAdmin }) ?? [];
-  const onSort = (sortBy: SortBy) =>
-    setSort(prev => ({
-      sortBy,
-      desc: prev.sortBy === sortBy && !prev.desc,
-    }));
-
   return (
     <>
       <header className="appHeader">
         <h1 className="appTitle">Team</h1>
-        <div className="buttonGroup">
-          {Object.entries(filters).map(([label, value]) => (
-            <button
-              key={label}
-              aria-pressed={isAdmin === value}
-              onClick={() => setIsAdmin(value)}
-            >
-              {label}
-            </button>
-          ))}
-        </div>
+        <RoleFilter isAdmin={isAdmin} onChange={setIsAdmin} />
       </header>
-      <table>
-        <thead>
-          <tr>
-            <SortHeader column="name" sort={sort} onSort={onSort}>
-              Name
-            </SortHeader>
-            <th>Role</th>
-            <SortHeader column="posts" sort={sort} onSort={onSort} numeric>
-              Posts
-            </SortHeader>
-            <SortHeader
-              column="joined"
-              sort={sort}
-              onSort={onSort}
-              numeric
-            >
-              Joined
-            </SortHeader>
-          </tr>
-        </thead>
-        <tbody>
-          {users.map(user => (
-            <tr key={user.pk()}>
-              <td>{user.name}</td>
-              <td className="meta">{user.isAdmin ? 'Admin' : 'Member'}</td>
-              <td className="value">{user.posts}</td>
-              <td className="value">{user.joined}</td>
-            </tr>
-          ))}
-        </tbody>
-      </table>
+      <UsersTable users={users} sort={sort} onSort={setSort} />
     </>
   );
 }
-
-function SortHeader({ column, sort, onSort, numeric, children }: Props) {
-  const sorted = sort.sortBy === column;
-  return (
-    <th
-      className={numeric ? 'value' : undefined}
-      aria-sort={
-        sorted ? (sort.desc ? 'descending' : 'ascending') : undefined
-      }
-    >
-      <button className="sort" onClick={() => onSort(column)}>
-        {children}
-      </button>
-    </th>
-  );
-}
-interface Props {
-  column: SortBy;
-  sort: Sort;
-  onSort: (column: SortBy) => void;
-  numeric?: boolean;
-  children: React.ReactNode;
-}
 render(<UsersPage />);
 ```
 
@@ -274,58 +293,60 @@ render(<UsersPage />);
 
 :::vue
 
-```html title="UsersPage.vue" {12-15}
+```html title="RoleFilter.vue" collapsed
 <script setup lang="ts">
-  import { ref } from 'vue';
-  import { useQuery, useSuspense } from '@data-client/vue';
-  import { UserResource } from './resources/User';
-  import { sortedUsers, type Sort, type SortBy } from './sortedUsers';
+  const roles = { All: undefined, Admins: true, Members: false };
 
-  const filters = { All: undefined, Admins: true, Members: false };
+  defineProps<{ isAdmin: boolean | undefined }>();
+  const emit = defineEmits<{ change: [isAdmin: boolean | undefined] }>();
+</script>
+
+<template>
+  <div class="buttonGroup" role="group" aria-label="Role">
+    <button
+      v-for="(value, label) in roles"
+      :key="label"
+      :aria-pressed="isAdmin === value"
+      @click="emit('change', value)"
+    >
+      {{ label }}
+    </button>
+  </div>
+</template>
+```
+
+```html title="UsersTable.vue" collapsed
+<script setup lang="ts">
+  import { type User } from './resources/User';
+  import { type Sort, type SortBy } from './UsersPage.vue';
+
+  const props = defineProps<{ users: readonly User[]; sort: Sort }>();
+  const emit = defineEmits<{ sort: [sort: Sort] }>();
 
-  await useSuspense(UserResource.getList);
-  const sort = ref<Sort>({ sortBy: 'name', desc: false });
-  const isAdmin = ref<boolean>();
-  const users = useQuery(sortedUsers, () => ({
-    ...sort.value,
-    isAdmin: isAdmin.value,
-  }));
-  function onSort(sortBy: SortBy) {
-    const desc = sort.value.sortBy === sortBy && !sort.value.desc;
-    sort.value = { sortBy, desc };
-  }
   function ariaSort(column: SortBy) {
-    if (sort.value.sortBy !== column) return undefined;
-    return sort.value.desc ? 'descending' : 'ascending';
+    if (props.sort.sortBy !== column) return undefined;
+    return props.sort.desc ? 'descending' : 'ascending';
+  }
+  // a second click on the sorted column reverses it
+  function sortBy(column: SortBy) {
+    const desc = props.sort.sortBy === column && !props.sort.desc;
+    emit('sort', { sortBy: column, desc });
   }
 </script>
 
 <template>
-  <header class="appHeader">
-    <h1 class="appTitle">Team</h1>
-    <div class="buttonGroup">
-      <button
-        v-for="(value, label) in filters"
-        :key="label"
-        :aria-pressed="isAdmin === value"
-        @click="isAdmin = value"
-      >
-        {{ label }}
-      </button>
-    </div>
-  </header>
   <table>
     <thead>
       <tr>
         <th :aria-sort="ariaSort('name')">
-          <button class="sort" @click="onSort('name')">Name</button>
+          <button class="sort" @click="sortBy('name')">Name</button>
         </th>
         <th>Role</th>
         <th class="value" :aria-sort="ariaSort('posts')">
-          <button class="sort" @click="onSort('posts')">Posts</button>
+          <button class="sort" @click="sortBy('posts')">Posts</button>
         </th>
         <th class="value" :aria-sort="ariaSort('joined')">
-          <button class="sort" @click="onSort('joined')">Joined</button>
+          <button class="sort" @click="sortBy('joined')">Joined</button>
         </th>
       </tr>
     </thead>
@@ -341,6 +362,61 @@ render(<UsersPage />);
 </template>
 ```
 
+```html title="UsersPage.vue" {40-43}
+<script lang="ts">
+  import { All, Query } from '@data-client/rest';
+  import { User } from './resources/User';
+
+  export type SortBy = 'name' | 'posts' | 'joined';
+  export interface Sort {
+    sortBy: SortBy;
+    desc: boolean;
+  }
+  interface Args extends Sort {
+    /** admins only (true), members only (false), or everyone */
+    isAdmin: boolean | undefined;
+  }
+
+  const sortedUsers = new Query(
+    new All(User),
+    (entries, { sortBy, desc, isAdmin }: Args) => {
+      const users = entries
+        .filter(user => isAdmin === undefined || user.isAdmin === isAdmin)
+        .sort((a, b) =>
+          sortBy === 'name' ?
+            a.name.localeCompare(b.name)
+          : a[sortBy] - b[sortBy],
+        );
+      return desc ? users.reverse() : users;
+    },
+  );
+</script>
+
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import { useQuery, useSuspense } from '@data-client/vue';
+  import { UserResource } from './resources/User';
+  import RoleFilter from './RoleFilter.vue';
+  import UsersTable from './UsersTable.vue';
+
+  await useSuspense(UserResource.getList);
+  const sort = ref<Sort>({ sortBy: 'name', desc: false });
+  const isAdmin = ref<boolean>();
+  const users = useQuery(sortedUsers, () => ({
+    ...sort.value,
+    isAdmin: isAdmin.value,
+  }));
+</script>
+
+<template>
+  <header class="appHeader">
+    <h1 class="appTitle">Team</h1>
+    <RoleFilter :is-admin="isAdmin" @change="isAdmin = $event" />
+  </header>
+  <UsersTable :users="users ?? []" :sort="sort" @sort="sort = $event" />
+</template>
+```
+
 :::
 
 </FrameworkPlayground>

From 1a4a97097c8819ad38d46dcec232d33001631e64 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 27 Oct 2026 03:38:40 +0000
Subject: [PATCH 04/10] docs: Read the useQuery demo's Query in a UsersTable
 that takes its args

UsersTable now holds the Query and reads it with the sort and role it
gets as props, handing the rows to UsersTableView, which only renders
them. UsersPage keeps the sort and filter state. Vue follows the same
split.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y5C5ZC3WYndrqLXmu9F42e
---
 .../data-client-react/references/useQuery.md  | 33 ++++++---
 .../data-client-vue/references/useQuery.md    | 37 +++++++---
 docs/core/api/useQuery.md                     | 72 +++++++++++++------
 3 files changed, 99 insertions(+), 43 deletions(-)

diff --git a/.agents/skills/data-client-react/references/useQuery.md b/.agents/skills/data-client-react/references/useQuery.md
index 4743a69a236d..10e1b271fbde 100644
--- a/.agents/skills/data-client-react/references/useQuery.md
+++ b/.agents/skills/data-client-react/references/useQuery.md
@@ -234,12 +234,12 @@ interface Props {
 }
 ```
 
-```tsx title="UsersTable"
+```tsx title="UsersTableView"
 import React from 'react';
 import { type User } from './resources/User';
-import { type Sort, type SortBy } from './UsersPage';
+import { type Sort, type SortBy } from './UsersTable';
 
-export default function UsersTable({ users, sort, onSort }: Props) {
+export default function UsersTableView({ users, sort, onSort }: Props) {
   return (
     <table>
       <thead>
@@ -303,13 +303,11 @@ interface HeaderProps {
 }
 ```
 
-```tsx title="UsersPage" {39}
-import React from 'react';
+```tsx title="UsersTable" {32}
 import { All, Query } from '@data-client/rest';
 import { useQuery, useSuspense } from '@data-client/react';
 import { User, UserResource } from './resources/User';
-import RoleFilter from './RoleFilter';
-import UsersTable from './UsersTable';
+import UsersTableView from './UsersTableView';
 
 export type SortBy = 'name' | 'posts' | 'joined';
 export interface Sort {
@@ -335,21 +333,36 @@ const sortedUsers = new Query(
   },
 );
 
-function UsersPage() {
+export default function UsersTable({ sort, isAdmin, onSort }: Props) {
   useSuspense(UserResource.getList);
+  const users = useQuery(sortedUsers, { ...sort, isAdmin }) ?? [];
+  return <UsersTableView users={users} sort={sort} onSort={onSort} />;
+}
+interface Props {
+  sort: Sort;
+  isAdmin: boolean | undefined;
+  onSort: (sort: Sort) => void;
+}
+```
+
+```tsx title="UsersPage"
+import React from 'react';
+import RoleFilter from './RoleFilter';
+import UsersTable, { type Sort } from './UsersTable';
+
+function UsersPage() {
   const [sort, setSort] = React.useState<Sort>({
     sortBy: 'name',
     desc: false,
   });
   const [isAdmin, setIsAdmin] = React.useState<boolean>();
-  const users = useQuery(sortedUsers, { ...sort, isAdmin }) ?? [];
   return (
     <>
       <header className="appHeader">
         <h1 className="appTitle">Team</h1>
         <RoleFilter isAdmin={isAdmin} onChange={setIsAdmin} />
       </header>
-      <UsersTable users={users} sort={sort} onSort={setSort} />
+      <UsersTable sort={sort} isAdmin={isAdmin} onSort={setSort} />
     </>
   );
 }
diff --git a/.agents/skills/data-client-vue/references/useQuery.md b/.agents/skills/data-client-vue/references/useQuery.md
index 34545e39853d..1b907fbc9231 100644
--- a/.agents/skills/data-client-vue/references/useQuery.md
+++ b/.agents/skills/data-client-vue/references/useQuery.md
@@ -225,10 +225,10 @@ export const UserResource = resource({
 </template>
 ```
 
-```html title="UsersTable.vue"
+```html title="UsersTableView.vue"
 <script setup lang="ts">
   import { type User } from './resources/User';
-  import { type Sort, type SortBy } from './UsersPage.vue';
+  import { type Sort, type SortBy } from './UsersTable.vue';
 
   const props = defineProps<{ users: readonly User[]; sort: Sort }>();
   const emit = defineEmits<{ sort: [sort: Sort] }>();
@@ -272,7 +272,7 @@ export const UserResource = resource({
 </template>
 ```
 
-```html title="UsersPage.vue" {40-43}
+```html title="UsersTable.vue" {39}
 <script lang="ts">
   import { All, Query } from '@data-client/rest';
   import { User } from './resources/User';
@@ -303,19 +303,34 @@ export const UserResource = resource({
 </script>
 
 <script setup lang="ts">
-  import { ref } from 'vue';
   import { useQuery, useSuspense } from '@data-client/vue';
   import { UserResource } from './resources/User';
-  import RoleFilter from './RoleFilter.vue';
-  import UsersTable from './UsersTable.vue';
+  import UsersTableView from './UsersTableView.vue';
+
+  const props = defineProps<Args>();
+  defineEmits<{ sort: [sort: Sort] }>();
 
   await useSuspense(UserResource.getList);
+  const users = useQuery(sortedUsers, () => ({ ...props }));
+</script>
+
+<template>
+  <UsersTableView
+    :users="users ?? []"
+    :sort="{ sortBy, desc }"
+    @sort="$emit('sort', $event)"
+  />
+</template>
+```
+
+```html title="UsersPage.vue"
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import RoleFilter from './RoleFilter.vue';
+  import UsersTable, { type Sort } from './UsersTable.vue';
+
   const sort = ref<Sort>({ sortBy: 'name', desc: false });
   const isAdmin = ref<boolean>();
-  const users = useQuery(sortedUsers, () => ({
-    ...sort.value,
-    isAdmin: isAdmin.value,
-  }));
 </script>
 
 <template>
@@ -323,7 +338,7 @@ export const UserResource = resource({
     <h1 class="appTitle">Team</h1>
     <RoleFilter :is-admin="isAdmin" @change="isAdmin = $event" />
   </header>
-  <UsersTable :users="users ?? []" :sort="sort" @sort="sort = $event" />
+  <UsersTable v-bind="sort" :is-admin="isAdmin" @sort="sort = $event" />
 </template>
 ```
 
diff --git a/docs/core/api/useQuery.md b/docs/core/api/useQuery.md
index 16c23c23e2e6..90df0a932e84 100644
--- a/docs/core/api/useQuery.md
+++ b/docs/core/api/useQuery.md
@@ -119,7 +119,7 @@ re-sorts the table without fetching again.
 <FrameworkPlayground
 fixtures={teamFixtures}
 row
-defaultTab="UsersPage"
+defaultTab="UsersTable"
 autoRun={sortDemo}
 >
 
@@ -167,12 +167,12 @@ interface Props {
 }
 ```
 
-```tsx title="UsersTable" collapsed
+```tsx title="UsersTableView" collapsed
 import React from 'react';
 import { type User } from './resources/User';
-import { type Sort, type SortBy } from './UsersPage';
+import { type Sort, type SortBy } from './UsersTable';
 
-export default function UsersTable({ users, sort, onSort }: Props) {
+export default function UsersTableView({ users, sort, onSort }: Props) {
   return (
     <table>
       <thead>
@@ -236,13 +236,11 @@ interface HeaderProps {
 }
 ```
 
-```tsx title="UsersPage" {39}
-import React from 'react';
+```tsx title="UsersTable" {32}
 import { All, Query } from '@data-client/rest';
 import { useQuery, useSuspense } from '@data-client/react';
 import { User, UserResource } from './resources/User';
-import RoleFilter from './RoleFilter';
-import UsersTable from './UsersTable';
+import UsersTableView from './UsersTableView';
 
 export type SortBy = 'name' | 'posts' | 'joined';
 export interface Sort {
@@ -268,21 +266,36 @@ const sortedUsers = new Query(
   },
 );
 
-function UsersPage() {
+export default function UsersTable({ sort, isAdmin, onSort }: Props) {
   useSuspense(UserResource.getList);
+  const users = useQuery(sortedUsers, { ...sort, isAdmin }) ?? [];
+  return <UsersTableView users={users} sort={sort} onSort={onSort} />;
+}
+interface Props {
+  sort: Sort;
+  isAdmin: boolean | undefined;
+  onSort: (sort: Sort) => void;
+}
+```
+
+```tsx title="UsersPage" collapsed
+import React from 'react';
+import RoleFilter from './RoleFilter';
+import UsersTable, { type Sort } from './UsersTable';
+
+function UsersPage() {
   const [sort, setSort] = React.useState<Sort>({
     sortBy: 'name',
     desc: false,
   });
   const [isAdmin, setIsAdmin] = React.useState<boolean>();
-  const users = useQuery(sortedUsers, { ...sort, isAdmin }) ?? [];
   return (
     <>
       <header className="appHeader">
         <h1 className="appTitle">Team</h1>
         <RoleFilter isAdmin={isAdmin} onChange={setIsAdmin} />
       </header>
-      <UsersTable users={users} sort={sort} onSort={setSort} />
+      <UsersTable sort={sort} isAdmin={isAdmin} onSort={setSort} />
     </>
   );
 }
@@ -315,10 +328,10 @@ render(<UsersPage />);
 </template>
 ```
 
-```html title="UsersTable.vue" collapsed
+```html title="UsersTableView.vue" collapsed
 <script setup lang="ts">
   import { type User } from './resources/User';
-  import { type Sort, type SortBy } from './UsersPage.vue';
+  import { type Sort, type SortBy } from './UsersTable.vue';
 
   const props = defineProps<{ users: readonly User[]; sort: Sort }>();
   const emit = defineEmits<{ sort: [sort: Sort] }>();
@@ -362,7 +375,7 @@ render(<UsersPage />);
 </template>
 ```
 
-```html title="UsersPage.vue" {40-43}
+```html title="UsersTable.vue" {39}
 <script lang="ts">
   import { All, Query } from '@data-client/rest';
   import { User } from './resources/User';
@@ -393,19 +406,34 @@ render(<UsersPage />);
 </script>
 
 <script setup lang="ts">
-  import { ref } from 'vue';
   import { useQuery, useSuspense } from '@data-client/vue';
   import { UserResource } from './resources/User';
-  import RoleFilter from './RoleFilter.vue';
-  import UsersTable from './UsersTable.vue';
+  import UsersTableView from './UsersTableView.vue';
+
+  const props = defineProps<Args>();
+  defineEmits<{ sort: [sort: Sort] }>();
 
   await useSuspense(UserResource.getList);
+  const users = useQuery(sortedUsers, () => ({ ...props }));
+</script>
+
+<template>
+  <UsersTableView
+    :users="users ?? []"
+    :sort="{ sortBy, desc }"
+    @sort="$emit('sort', $event)"
+  />
+</template>
+```
+
+```html title="UsersPage.vue" collapsed
+<script setup lang="ts">
+  import { ref } from 'vue';
+  import RoleFilter from './RoleFilter.vue';
+  import UsersTable, { type Sort } from './UsersTable.vue';
+
   const sort = ref<Sort>({ sortBy: 'name', desc: false });
   const isAdmin = ref<boolean>();
-  const users = useQuery(sortedUsers, () => ({
-    ...sort.value,
-    isAdmin: isAdmin.value,
-  }));
 </script>
 
 <template>
@@ -413,7 +441,7 @@ render(<UsersPage />);
     <h1 class="appTitle">Team</h1>
     <RoleFilter :is-admin="isAdmin" @change="isAdmin = $event" />
   </header>
-  <UsersTable :users="users ?? []" :sort="sort" @sort="sort = $event" />
+  <UsersTable v-bind="sort" :is-admin="isAdmin" @sort="sort = $event" />
 </template>
 ```
 

From 217d8cfd6fa4273bdb386f5123806c8e403ce1df Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 27 Oct 2026 03:39:54 +0000
Subject: [PATCH 05/10] docs: Keep the useQuery demo's sort type with the User
 resource

Sort and SortBy move to resources/User, so UsersTableView, UsersTable and
UsersPage all import them from there and no component imports from the
one that renders it. Vue's header click handler is named toggleSort.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y5C5ZC3WYndrqLXmu9F42e
---
 .../data-client-react/references/useQuery.md  | 22 ++++-----
 .../data-client-vue/references/useQuery.md    | 30 +++++++------
 docs/core/api/useQuery.md                     | 45 +++++++++----------
 3 files changed, 49 insertions(+), 48 deletions(-)

diff --git a/.agents/skills/data-client-react/references/useQuery.md b/.agents/skills/data-client-react/references/useQuery.md
index 10e1b271fbde..a037bfffaa01 100644
--- a/.agents/skills/data-client-react/references/useQuery.md
+++ b/.agents/skills/data-client-react/references/useQuery.md
@@ -208,6 +208,13 @@ export const UserResource = resource({
   path: '/users/:id',
   schema: User,
 });
+
+/** A users list's order: by one column, reversed when `desc` */
+export type SortBy = 'name' | 'posts' | 'joined';
+export interface Sort {
+  sortBy: SortBy;
+  desc: boolean;
+}
 ```
 
 ```tsx title="RoleFilter"
@@ -236,8 +243,7 @@ interface Props {
 
 ```tsx title="UsersTableView"
 import React from 'react';
-import { type User } from './resources/User';
-import { type Sort, type SortBy } from './UsersTable';
+import { type Sort, type SortBy, type User } from './resources/User';
 
 export default function UsersTableView({ users, sort, onSort }: Props) {
   return (
@@ -303,17 +309,12 @@ interface HeaderProps {
 }
 ```
 
-```tsx title="UsersTable" {32}
+```tsx title="UsersTable" {27}
 import { All, Query } from '@data-client/rest';
 import { useQuery, useSuspense } from '@data-client/react';
-import { User, UserResource } from './resources/User';
+import { type Sort, User, UserResource } from './resources/User';
 import UsersTableView from './UsersTableView';
 
-export type SortBy = 'name' | 'posts' | 'joined';
-export interface Sort {
-  sortBy: SortBy;
-  desc: boolean;
-}
 interface Args extends Sort {
   /** admins only (true), members only (false), or everyone */
   isAdmin: boolean | undefined;
@@ -348,7 +349,8 @@ interface Props {
 ```tsx title="UsersPage"
 import React from 'react';
 import RoleFilter from './RoleFilter';
-import UsersTable, { type Sort } from './UsersTable';
+import { type Sort } from './resources/User';
+import UsersTable from './UsersTable';
 
 function UsersPage() {
   const [sort, setSort] = React.useState<Sort>({
diff --git a/.agents/skills/data-client-vue/references/useQuery.md b/.agents/skills/data-client-vue/references/useQuery.md
index 1b907fbc9231..181677cda04a 100644
--- a/.agents/skills/data-client-vue/references/useQuery.md
+++ b/.agents/skills/data-client-vue/references/useQuery.md
@@ -201,6 +201,13 @@ export const UserResource = resource({
   path: '/users/:id',
   schema: User,
 });
+
+/** A users list's order: by one column, reversed when `desc` */
+export type SortBy = 'name' | 'posts' | 'joined';
+export interface Sort {
+  sortBy: SortBy;
+  desc: boolean;
+}
 ```
 
 ```html title="RoleFilter.vue"
@@ -227,8 +234,7 @@ export const UserResource = resource({
 
 ```html title="UsersTableView.vue"
 <script setup lang="ts">
-  import { type User } from './resources/User';
-  import { type Sort, type SortBy } from './UsersTable.vue';
+  import { type Sort, type SortBy, type User } from './resources/User';
 
   const props = defineProps<{ users: readonly User[]; sort: Sort }>();
   const emit = defineEmits<{ sort: [sort: Sort] }>();
@@ -238,7 +244,7 @@ export const UserResource = resource({
     return props.sort.desc ? 'descending' : 'ascending';
   }
   // a second click on the sorted column reverses it
-  function sortBy(column: SortBy) {
+  function toggleSort(column: SortBy) {
     const desc = props.sort.sortBy === column && !props.sort.desc;
     emit('sort', { sortBy: column, desc });
   }
@@ -249,14 +255,14 @@ export const UserResource = resource({
     <thead>
       <tr>
         <th :aria-sort="ariaSort('name')">
-          <button class="sort" @click="sortBy('name')">Name</button>
+          <button class="sort" @click="toggleSort('name')">Name</button>
         </th>
         <th>Role</th>
         <th class="value" :aria-sort="ariaSort('posts')">
-          <button class="sort" @click="sortBy('posts')">Posts</button>
+          <button class="sort" @click="toggleSort('posts')">Posts</button>
         </th>
         <th class="value" :aria-sort="ariaSort('joined')">
-          <button class="sort" @click="sortBy('joined')">Joined</button>
+          <button class="sort" @click="toggleSort('joined')">Joined</button>
         </th>
       </tr>
     </thead>
@@ -272,16 +278,11 @@ export const UserResource = resource({
 </template>
 ```
 
-```html title="UsersTable.vue" {39}
+```html title="UsersTable.vue" {34}
 <script lang="ts">
   import { All, Query } from '@data-client/rest';
-  import { User } from './resources/User';
+  import { type Sort, User } from './resources/User';
 
-  export type SortBy = 'name' | 'posts' | 'joined';
-  export interface Sort {
-    sortBy: SortBy;
-    desc: boolean;
-  }
   interface Args extends Sort {
     /** admins only (true), members only (false), or everyone */
     isAdmin: boolean | undefined;
@@ -327,7 +328,8 @@ export const UserResource = resource({
 <script setup lang="ts">
   import { ref } from 'vue';
   import RoleFilter from './RoleFilter.vue';
-  import UsersTable, { type Sort } from './UsersTable.vue';
+  import { type Sort } from './resources/User';
+  import UsersTable from './UsersTable.vue';
 
   const sort = ref<Sort>({ sortBy: 'name', desc: false });
   const isAdmin = ref<boolean>();
diff --git a/docs/core/api/useQuery.md b/docs/core/api/useQuery.md
index 90df0a932e84..276636961410 100644
--- a/docs/core/api/useQuery.md
+++ b/docs/core/api/useQuery.md
@@ -139,6 +139,13 @@ export const UserResource = resource({
   path: '/users/:id',
   schema: User,
 });
+
+/** A users list's order: by one column, reversed when `desc` */
+export type SortBy = 'name' | 'posts' | 'joined';
+export interface Sort {
+  sortBy: SortBy;
+  desc: boolean;
+}
 ```
 
 :::react
@@ -169,8 +176,7 @@ interface Props {
 
 ```tsx title="UsersTableView" collapsed
 import React from 'react';
-import { type User } from './resources/User';
-import { type Sort, type SortBy } from './UsersTable';
+import { type Sort, type SortBy, type User } from './resources/User';
 
 export default function UsersTableView({ users, sort, onSort }: Props) {
   return (
@@ -236,17 +242,12 @@ interface HeaderProps {
 }
 ```
 
-```tsx title="UsersTable" {32}
+```tsx title="UsersTable" {27}
 import { All, Query } from '@data-client/rest';
 import { useQuery, useSuspense } from '@data-client/react';
-import { User, UserResource } from './resources/User';
+import { type Sort, User, UserResource } from './resources/User';
 import UsersTableView from './UsersTableView';
 
-export type SortBy = 'name' | 'posts' | 'joined';
-export interface Sort {
-  sortBy: SortBy;
-  desc: boolean;
-}
 interface Args extends Sort {
   /** admins only (true), members only (false), or everyone */
   isAdmin: boolean | undefined;
@@ -281,7 +282,8 @@ interface Props {
 ```tsx title="UsersPage" collapsed
 import React from 'react';
 import RoleFilter from './RoleFilter';
-import UsersTable, { type Sort } from './UsersTable';
+import { type Sort } from './resources/User';
+import UsersTable from './UsersTable';
 
 function UsersPage() {
   const [sort, setSort] = React.useState<Sort>({
@@ -330,8 +332,7 @@ render(<UsersPage />);
 
 ```html title="UsersTableView.vue" collapsed
 <script setup lang="ts">
-  import { type User } from './resources/User';
-  import { type Sort, type SortBy } from './UsersTable.vue';
+  import { type Sort, type SortBy, type User } from './resources/User';
 
   const props = defineProps<{ users: readonly User[]; sort: Sort }>();
   const emit = defineEmits<{ sort: [sort: Sort] }>();
@@ -341,7 +342,7 @@ render(<UsersPage />);
     return props.sort.desc ? 'descending' : 'ascending';
   }
   // a second click on the sorted column reverses it
-  function sortBy(column: SortBy) {
+  function toggleSort(column: SortBy) {
     const desc = props.sort.sortBy === column && !props.sort.desc;
     emit('sort', { sortBy: column, desc });
   }
@@ -352,14 +353,14 @@ render(<UsersPage />);
     <thead>
       <tr>
         <th :aria-sort="ariaSort('name')">
-          <button class="sort" @click="sortBy('name')">Name</button>
+          <button class="sort" @click="toggleSort('name')">Name</button>
         </th>
         <th>Role</th>
         <th class="value" :aria-sort="ariaSort('posts')">
-          <button class="sort" @click="sortBy('posts')">Posts</button>
+          <button class="sort" @click="toggleSort('posts')">Posts</button>
         </th>
         <th class="value" :aria-sort="ariaSort('joined')">
-          <button class="sort" @click="sortBy('joined')">Joined</button>
+          <button class="sort" @click="toggleSort('joined')">Joined</button>
         </th>
       </tr>
     </thead>
@@ -375,16 +376,11 @@ render(<UsersPage />);
 </template>
 ```
 
-```html title="UsersTable.vue" {39}
+```html title="UsersTable.vue" {34}
 <script lang="ts">
   import { All, Query } from '@data-client/rest';
-  import { User } from './resources/User';
+  import { type Sort, User } from './resources/User';
 
-  export type SortBy = 'name' | 'posts' | 'joined';
-  export interface Sort {
-    sortBy: SortBy;
-    desc: boolean;
-  }
   interface Args extends Sort {
     /** admins only (true), members only (false), or everyone */
     isAdmin: boolean | undefined;
@@ -430,7 +426,8 @@ render(<UsersPage />);
 <script setup lang="ts">
   import { ref } from 'vue';
   import RoleFilter from './RoleFilter.vue';
-  import UsersTable, { type Sort } from './UsersTable.vue';
+  import { type Sort } from './resources/User';
+  import UsersTable from './UsersTable.vue';
 
   const sort = ref<Sort>({ sortBy: 'name', desc: false });
   const isAdmin = ref<boolean>();

From 5702846ffea4a043d0c8c24ff723440cecbdb5ab Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 27 Oct 2026 03:45:37 +0000
Subject: [PATCH 06/10] docs(useQuery): Vue sort demo passes one sort prop,
 like React

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y5C5ZC3WYndrqLXmu9F42e
---
 docs/core/api/useQuery.md | 17 ++++++++---------
 1 file changed, 8 insertions(+), 9 deletions(-)

diff --git a/docs/core/api/useQuery.md b/docs/core/api/useQuery.md
index 276636961410..e1f7379bb5a2 100644
--- a/docs/core/api/useQuery.md
+++ b/docs/core/api/useQuery.md
@@ -376,7 +376,7 @@ render(<UsersPage />);
 </template>
 ```
 
-```html title="UsersTable.vue" {34}
+```html title="UsersTable.vue" {34-37}
 <script lang="ts">
   import { All, Query } from '@data-client/rest';
   import { type Sort, User } from './resources/User';
@@ -406,19 +406,18 @@ render(<UsersPage />);
   import { UserResource } from './resources/User';
   import UsersTableView from './UsersTableView.vue';
 
-  const props = defineProps<Args>();
+  const props = defineProps<{ sort: Sort; isAdmin: boolean | undefined }>();
   defineEmits<{ sort: [sort: Sort] }>();
 
   await useSuspense(UserResource.getList);
-  const users = useQuery(sortedUsers, () => ({ ...props }));
+  const users = useQuery(sortedUsers, () => ({
+    ...props.sort,
+    isAdmin: props.isAdmin,
+  }));
 </script>
 
 <template>
-  <UsersTableView
-    :users="users ?? []"
-    :sort="{ sortBy, desc }"
-    @sort="$emit('sort', $event)"
-  />
+  <UsersTableView :users="users ?? []" :sort="sort" @sort="$emit('sort', $event)" />
 </template>
 ```
 
@@ -438,7 +437,7 @@ render(<UsersPage />);
     <h1 class="appTitle">Team</h1>
     <RoleFilter :is-admin="isAdmin" @change="isAdmin = $event" />
   </header>
-  <UsersTable v-bind="sort" :is-admin="isAdmin" @sort="sort = $event" />
+  <UsersTable :sort="sort" :is-admin="isAdmin" @sort="sort = $event" />
 </template>
 ```
 

From e5c0d570877068f33db0fd2361c6c02ab782ea5c Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 27 Oct 2026 04:06:29 +0000
Subject: [PATCH 07/10] docs(useQuery): team directory table and a segmented
 role filter

Adds design-system elements for the sort demo: a segmented filter whose
pill slides to the chosen choice, role pills, and initials avatars. Tables
lose the row hover (their rows aren't actionable) and value cells get
tabular figures.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y5C5ZC3WYndrqLXmu9F42e
---
 .../data-client-react/references/useQuery.md  |  13 +-
 .../data-client-vue/references/useQuery.md    |  30 +--
 docs/core/api/useQuery.md                     |  28 ++-
 .../Playground/DesignSystem/Avatar.tsx        |  27 ++-
 .../Playground/DesignSystem/design-system.css | 198 +++++++++++++++---
 website/src/components/Playground/README.md   |   8 +-
 .../components/Playground/monaco/typeLibs.ts  |   2 +-
 7 files changed, 244 insertions(+), 62 deletions(-)

diff --git a/.agents/skills/data-client-react/references/useQuery.md b/.agents/skills/data-client-react/references/useQuery.md
index a037bfffaa01..327f12aba574 100644
--- a/.agents/skills/data-client-react/references/useQuery.md
+++ b/.agents/skills/data-client-react/references/useQuery.md
@@ -222,7 +222,7 @@ const roles = { All: undefined, Admins: true, Members: false };
 
 export default function RoleFilter({ isAdmin, onChange }: Props) {
   return (
-    <div className="buttonGroup" role="group" aria-label="Role">
+    <div className="segmented" role="group" aria-label="Role">
       {Object.entries(roles).map(([label, value]) => (
         <button
           key={label}
@@ -265,8 +265,15 @@ export default function UsersTableView({ users, sort, onSort }: Props) {
       <tbody>
         {users.map(user => (
           <tr key={user.pk()}>
-            <td>{user.name}</td>
-            <td className="meta">{user.isAdmin ? 'Admin' : 'Member'}</td>
+            <td>
+              <Avatar name={user.name} />
+              {user.name}
+            </td>
+            <td>
+              <span className={user.isAdmin ? 'pill primary' : 'pill'}>
+                {user.isAdmin ? 'Admin' : 'Member'}
+              </span>
+            </td>
             <td className="value">{user.posts}</td>
             <td className="value">{user.joined}</td>
           </tr>
diff --git a/.agents/skills/data-client-vue/references/useQuery.md b/.agents/skills/data-client-vue/references/useQuery.md
index 181677cda04a..f8771d7134b5 100644
--- a/.agents/skills/data-client-vue/references/useQuery.md
+++ b/.agents/skills/data-client-vue/references/useQuery.md
@@ -219,7 +219,7 @@ export interface Sort {
 </script>
 
 <template>
-  <div class="buttonGroup" role="group" aria-label="Role">
+  <div class="segmented" role="group" aria-label="Role">
     <button
       v-for="(value, label) in roles"
       :key="label"
@@ -268,8 +268,15 @@ export interface Sort {
     </thead>
     <tbody>
       <tr v-for="user in users" :key="user.pk()">
-        <td>{{ user.name }}</td>
-        <td class="meta">{{ user.isAdmin ? 'Admin' : 'Member' }}</td>
+        <td>
+          <Avatar :name="user.name" />
+          {{ user.name }}
+        </td>
+        <td>
+          <span :class="user.isAdmin ? 'pill primary' : 'pill'">
+            {{ user.isAdmin ? 'Admin' : 'Member' }}
+          </span>
+        </td>
         <td class="value">{{ user.posts }}</td>
         <td class="value">{{ user.joined }}</td>
       </tr>
@@ -278,7 +285,7 @@ export interface Sort {
 </template>
 ```
 
-```html title="UsersTable.vue" {34}
+```html title="UsersTable.vue" {34-37}
 <script lang="ts">
   import { All, Query } from '@data-client/rest';
   import { type Sort, User } from './resources/User';
@@ -308,19 +315,18 @@ export interface Sort {
   import { UserResource } from './resources/User';
   import UsersTableView from './UsersTableView.vue';
 
-  const props = defineProps<Args>();
+  const props = defineProps<{ sort: Sort; isAdmin: boolean | undefined }>();
   defineEmits<{ sort: [sort: Sort] }>();
 
   await useSuspense(UserResource.getList);
-  const users = useQuery(sortedUsers, () => ({ ...props }));
+  const users = useQuery(sortedUsers, () => ({
+    ...props.sort,
+    isAdmin: props.isAdmin,
+  }));
 </script>
 
 <template>
-  <UsersTableView
-    :users="users ?? []"
-    :sort="{ sortBy, desc }"
-    @sort="$emit('sort', $event)"
-  />
+  <UsersTableView :users="users ?? []" :sort="sort" @sort="$emit('sort', $event)" />
 </template>
 ```
 
@@ -340,7 +346,7 @@ export interface Sort {
     <h1 class="appTitle">Team</h1>
     <RoleFilter :is-admin="isAdmin" @change="isAdmin = $event" />
   </header>
-  <UsersTable v-bind="sort" :is-admin="isAdmin" @sort="sort = $event" />
+  <UsersTable :sort="sort" :is-admin="isAdmin" @sort="sort = $event" />
 </template>
 ```
 
diff --git a/docs/core/api/useQuery.md b/docs/core/api/useQuery.md
index e1f7379bb5a2..79f6a014762e 100644
--- a/docs/core/api/useQuery.md
+++ b/docs/core/api/useQuery.md
@@ -20,7 +20,7 @@ export const sortDemo = [
   { wait: 1200 },
   { click: { selector: 'button.sort', hasText: 'Posts' } },
   { wait: 1800 },
-  { click: { selector: '.buttonGroup button', hasText: 'Admins' } },
+  { click: { selector: '.segmented button', hasText: 'Admins' } },
   { wait: 1800 },
   { click: { selector: 'button.sort', hasText: 'Joined' } },
 ];
@@ -155,7 +155,7 @@ const roles = { All: undefined, Admins: true, Members: false };
 
 export default function RoleFilter({ isAdmin, onChange }: Props) {
   return (
-    <div className="buttonGroup" role="group" aria-label="Role">
+    <div className="segmented" role="group" aria-label="Role">
       {Object.entries(roles).map(([label, value]) => (
         <button
           key={label}
@@ -198,8 +198,15 @@ export default function UsersTableView({ users, sort, onSort }: Props) {
       <tbody>
         {users.map(user => (
           <tr key={user.pk()}>
-            <td>{user.name}</td>
-            <td className="meta">{user.isAdmin ? 'Admin' : 'Member'}</td>
+            <td>
+              <Avatar name={user.name} />
+              {user.name}
+            </td>
+            <td>
+              <span className={user.isAdmin ? 'pill primary' : 'pill'}>
+                {user.isAdmin ? 'Admin' : 'Member'}
+              </span>
+            </td>
             <td className="value">{user.posts}</td>
             <td className="value">{user.joined}</td>
           </tr>
@@ -317,7 +324,7 @@ render(<UsersPage />);
 </script>
 
 <template>
-  <div class="buttonGroup" role="group" aria-label="Role">
+  <div class="segmented" role="group" aria-label="Role">
     <button
       v-for="(value, label) in roles"
       :key="label"
@@ -366,8 +373,15 @@ render(<UsersPage />);
     </thead>
     <tbody>
       <tr v-for="user in users" :key="user.pk()">
-        <td>{{ user.name }}</td>
-        <td class="meta">{{ user.isAdmin ? 'Admin' : 'Member' }}</td>
+        <td>
+          <Avatar :name="user.name" />
+          {{ user.name }}
+        </td>
+        <td>
+          <span :class="user.isAdmin ? 'pill primary' : 'pill'">
+            {{ user.isAdmin ? 'Admin' : 'Member' }}
+          </span>
+        </td>
         <td class="value">{{ user.posts }}</td>
         <td class="value">{{ user.joined }}</td>
       </tr>
diff --git a/website/src/components/Playground/DesignSystem/Avatar.tsx b/website/src/components/Playground/DesignSystem/Avatar.tsx
index 32c5421c7ad8..a86695f3cdd6 100644
--- a/website/src/components/Playground/DesignSystem/Avatar.tsx
+++ b/website/src/components/Playground/DesignSystem/Avatar.tsx
@@ -1,7 +1,24 @@
 import React from 'react';
 
-/** A round profile picture; 32px, or `size` to match the text beside it (smaller in a byline or a comment) */
-export function Avatar({ src, size = 32 }: { src: string; size?: number }) {
+/** A round profile picture; 32px, or `size` to match the text beside it
+ * (smaller in a byline or a comment). With a `name` and no picture, the
+ * name's initials on a disc (sized by the design system: 32px, 24px in a
+ * table row) */
+export function Avatar({
+  src,
+  name,
+  size = 32,
+}: {
+  src?: string;
+  name?: string;
+  size?: number;
+}) {
+  if (!src)
+    return (
+      <span className="avatar" aria-hidden>
+        {initials(name ?? '')}
+      </span>
+    );
   return (
     <span
       style={{
@@ -21,3 +38,9 @@ export function Avatar({ src, size = 32 }: { src: string; size?: number }) {
     </span>
   );
 }
+
+/** The first letters of a name's first and last words ("Maya Chen" → "MC") */
+function initials(name: string) {
+  const words = name.trim().split(/\s+/);
+  return (words[0]?.[0] ?? '') + (words.length > 1 ? words.at(-1)![0] : '');
+}
diff --git a/website/src/components/Playground/DesignSystem/design-system.css b/website/src/components/Playground/DesignSystem/design-system.css
index 3e2277e47b5e..cd94a4828bfb 100644
--- a/website/src/components/Playground/DesignSystem/design-system.css
+++ b/website/src/components/Playground/DesignSystem/design-system.css
@@ -457,15 +457,17 @@ div.playground-preview h1:first-child {
 .playground-preview .listItem:has(> .upvote) {
   align-items: flex-start;
 }
-/* an arrow pointing up: an upvote's, a sorted column's */
+/* an arrow pointing up: an upvote's, a sorted column's (each sizes its own) */
 .playground-preview button.upvote::before,
 .playground-preview button.sort::after {
   content: '';
-  width: 12px;
-  height: 7px;
   background: currentColor;
   clip-path: polygon(50% 0, 100% 100%, 0 100%);
 }
+.playground-preview button.upvote::before {
+  width: 12px;
+  height: 7px;
+}
 @media (hover: hover) {
   .playground-preview button.upvote:hover,
   .playground-preview .stepper > button:hover {
@@ -702,14 +704,18 @@ div.playground-preview h1:first-child {
 .playground-preview .listItem > :is(.meta, .value):last-child {
   margin-left: auto;
 }
-/* A row's figure (`value`: a watchlist row's price, a NumberFlow or a
-   skeleton holding its place): at the row's end in tabular digits, a step
-   up in weight, so a list of them reads as a column. The row's name is its
-   h4 (a coin's symbol), with a `small` line under it when it has one */
+/* A figure (`value`: a watchlist row's price, a table's count, a NumberFlow
+   or a skeleton holding its place): tabular digits, so a column of them
+   lines up */
+.playground-preview .value {
+  font-variant-numeric: tabular-nums;
+}
+/* in a list row, at the row's end and a step up in weight, so a list of
+   them reads as a column. The row's name is its h4 (a coin's symbol), with
+   a `small` line under it when it has one */
 .playground-preview .listItem > .value {
   flex: none;
   font-weight: 600;
-  font-variant-numeric: tabular-nums;
 }
 .playground-preview .listItem:has(> .value) h4 {
   margin-bottom: 0;
@@ -762,25 +768,106 @@ div.playground-preview h1:first-child {
 .playground-preview .buttonGroup > button:focus-visible {
   outline-offset: -2px;
 }
-/* a filter's choice (All, Admins): the chosen segment washed in the
-   accent as a pressed one is, in the accent's color */
-.playground-preview .buttonGroup > button[aria-pressed='true']:not([class]) {
-  background: var(--ds-accent-pressed);
-  color: var(--ds-accent);
-}
 /* in an app header, level with the wordmark */
 .playground-preview .appHeader .buttonGroup {
   margin-top: 0;
 }
-/* A table (a team's members): rows on the sheet with no rules or stripes,
-   set apart by space, their text in line with the app header's; under the
-   pointer a row is a rounded band reaching past its text, as a list's.
-   Headers are a group's label. `value` cells (a count, a year) sit at the
-   column's end. Infima's borders and stripes are dropped */
+/* A filter's choices (All, Admins, Members) as one segmented control: the
+   words on a track of the well's color, in equal segments, and the chosen
+   one (`aria-pressed`) in the accent on a pill of the sheet that slides
+   to it. The pill is the track's ::before, one segment wide, moved by the
+   chosen segment's index (counted by :has(), up to four segments). In an
+   app header it sits level with the wordmark; on a phone it fits beside it */
+.playground-preview .segmented {
+  --segments: 1;
+  --segment: 0;
+  position: relative;
+  display: grid;
+  grid-auto-flow: column;
+  grid-auto-columns: 1fr;
+  width: fit-content;
+  max-width: 100%;
+  padding: 2px;
+  border-radius: 999px;
+  background: var(--ds-surface-2);
+}
+.playground-preview .segmented:has(> :nth-child(2):last-child) {
+  --segments: 2;
+}
+.playground-preview .segmented:has(> :nth-child(3):last-child) {
+  --segments: 3;
+}
+.playground-preview .segmented:has(> :nth-child(4):last-child) {
+  --segments: 4;
+}
+.playground-preview .segmented:has(> :nth-child(2)[aria-pressed='true']) {
+  --segment: 1;
+}
+.playground-preview .segmented:has(> :nth-child(3)[aria-pressed='true']) {
+  --segment: 2;
+}
+.playground-preview .segmented:has(> :nth-child(4)[aria-pressed='true']) {
+  --segment: 3;
+}
+.playground-preview .segmented::before {
+  content: '';
+  position: absolute;
+  inset: 2px auto 2px 2px;
+  width: calc((100% - 4px) / var(--segments));
+  border-radius: 999px;
+  background: var(--ds-surface);
+  box-shadow:
+    0 1px 2px var(--pg-shadow-edge),
+    0 0 0 1px color-mix(in srgb, var(--ds-text) 6%, transparent);
+  transform: translateX(calc(100% * var(--segment)));
+  transition: transform var(--motion-snappy);
+}
+/* at night the pill is a step up from the track, with no shadow to cast */
+html[data-theme='dark'] .playground-preview .segmented::before {
+  background: color-mix(in srgb, var(--ds-text) 14%, var(--ds-surface-2));
+  box-shadow: none;
+}
+@media (prefers-reduced-motion: reduce) {
+  .playground-preview .segmented::before {
+    transition: none;
+  }
+}
+.playground-preview .segmented > button {
+  position: relative;
+  margin: 0;
+  padding: 4px 12px;
+  border: 0;
+  border-radius: 999px;
+  background: none;
+  color: var(--ds-text-muted);
+  font: 500 var(--ds-text-sm) / 1.4 var(--ifm-font-family-base);
+  cursor: pointer;
+  transition: color var(--motion-snappy);
+}
+.playground-preview .segmented > button[aria-pressed='true'] {
+  color: var(--ds-accent);
+  font-weight: 600;
+}
+@media (hover: hover) {
+  .playground-preview .segmented > button:not([aria-pressed='true']):hover {
+    color: var(--ds-text);
+  }
+}
+.playground-preview .segmented > button:focus-visible {
+  outline: 2px solid var(--ds-accent);
+  outline-offset: -2px;
+}
+/* A table (a team's members): rows on the sheet with no rules, stripes or
+   hover (a row does nothing on a click, like a list row without a control),
+   set apart by space, its first and last columns flush with the app
+   header's text. Headers are a group's label; a sort arrow has no baseline,
+   so they sit at the UA's middle and every label stays level. `value` cells
+   (a count, a year) sit at the column's end. Infima's borders and stripes
+   are dropped */
 .playground-preview table {
   --ifm-table-stripe-background: transparent;
-  width: calc(100% + 2 * var(--ds-space-3));
-  margin: 0 calc(-1 * var(--ds-space-3)) var(--ds-space-4);
+  width: 100%;
+  margin: 0 0 var(--ds-space-4);
   border-collapse: separate;
   border-spacing: 0;
 }
@@ -791,31 +878,74 @@ div.playground-preview h1:first-child {
 .playground-preview :is(thead, tr, th, td) {
   border: 0;
 }
+/* 8px between columns is what keeps a 4-column row on a phone's sheet
+   (a name with its avatar, a role's pill, two figures) */
 .playground-preview td {
-  padding: var(--ds-space-2) var(--ds-space-3);
+  padding: var(--ds-space-2);
   vertical-align: baseline;
-  transition: background-color var(--motion-snappy);
 }
 .playground-preview th {
-  padding: 0 var(--ds-space-3) var(--ds-space-1);
+  padding: 0 var(--ds-space-2) var(--ds-space-1);
   text-align: start;
-  /* a sort arrow has no baseline: centered, every label stays level */
-  vertical-align: middle;
   white-space: nowrap;
 }
+.playground-preview :is(th, td):first-child {
+  padding-left: 0;
+}
+.playground-preview :is(th, td):last-child {
+  padding-right: 0;
+}
 .playground-preview :is(th, td).value {
   text-align: end;
 }
-@media (hover: hover) {
-  .playground-preview tbody tr:hover > td {
-    background: var(--ds-hover);
-  }
+/* A person in a row (a team member): `Avatar` with a `name` draws the
+   name's initials on a disc, 32px on its own and 22px in a table cell,
+   where it leads the name and sits in the text's line, 6px before it */
+.playground-preview .avatar {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  flex: none;
+  width: 32px;
+  height: 32px;
+  border-radius: 50%;
+  background: var(--ds-surface-2);
+  color: var(--ds-text-muted);
+  font-size: 0.75rem;
+  font-weight: 600;
+  letter-spacing: 0.02em;
+  line-height: 1;
+  vertical-align: middle;
 }
-.playground-preview tbody td:first-child {
-  border-radius: var(--ds-radius-sm) 0 0 var(--ds-radius-sm);
+.playground-preview td > .avatar {
+  width: 22px;
+  height: 22px;
+  margin: -3px 6px -3px 0;
+  font-size: 0.625rem;
 }
-.playground-preview tbody td:last-child {
-  border-radius: 0 var(--ds-radius-sm) var(--ds-radius-sm) 0;
+/* the name stays on one line, a step (12px) from what follows it */
+.playground-preview td:has(> .avatar) {
+  padding-right: var(--ds-space-3);
+  white-space: nowrap;
+}
+/* A label on a row (`pill`: a member's role): a small bold word on a disc
+   of the well's color, `primary` washed in the accent (an admin). Its disc
+   reaches past its text, so the word stays in line with its column's
+   header */
+.playground-preview .pill {
+  display: inline-block;
+  margin-inline: -7px;
+  padding: 1px 7px;
+  border-radius: 999px;
+  background: var(--ds-surface-2);
+  color: var(--ds-text-muted);
+  font-size: 0.75rem;
+  font-weight: 600;
+  line-height: 1.5;
+}
+.playground-preview .pill.primary {
+  background: var(--ds-accent-soft);
+  color: var(--ds-accent);
 }
 /* A sortable column's header (`button.sort` in its `th`, `aria-sort` on
    the sorted one's): its label, then an arrow that points the way the
diff --git a/website/src/components/Playground/README.md b/website/src/components/Playground/README.md
index c6cb7c8601e3..519ea2f01b9e 100644
--- a/website/src/components/Playground/README.md
+++ b/website/src/components/Playground/README.md
@@ -245,8 +245,10 @@ Styled elements: `h2` (page title), `button` (`primary` fills one;
 | `list`, `listItem` (`nogap`, `spaced`)     | rows; checkbox rows highlight and fade when done                               |
 | `meta`                                     | secondary text; last in a `listItem`, it sits at the row's end                 |
 | `value`                                    | a row's figure (a price); last in a `listItem`, at the row's end, tabular      |
-| `byline`, `author` (`Avatar` takes `size`) | who wrote something                                                            |
-| `buttonGroup`                              | segmented actions or a filter (`aria-pressed` marks its pick)                  |
+| `byline`, `author` (`Avatar` takes `size`) | who wrote something; `Avatar` with a `name` and no `src` draws its initials    |
+| `pill` (`primary`)                         | a label on a row (a member's role); `primary` washes it in the accent          |
+| `buttonGroup`                              | segmented actions (Fail Soft, Fail Hard)                                       |
+| `segmented`                                | a filter's choices on a track; `aria-pressed` marks the pick, the pill slides  |
 | `cancel` (`<CancelButton />`)              | a row's remove button                                                          |
 | `skeleton`                                 | a value still loading; `<Loading />`, the default fallback, draws a page       |
 | `toaster`, `toast`                         | notifications: render `<Toaster />`, call `toast.success()` or `toast.error()` |
@@ -254,7 +256,7 @@ Styled elements: `h2` (page title), `button` (`primary` fills one;
 | `upvote` (a button)                        | an upvote with its count; empty, the arrow alone                               |
 | `stats` (a `dl`)                           | figures side by side, each large over its label; a lone one fills the row      |
 | `stepper` (− `output` +)                   | a quantity's buttons around its count (one button alone: Add); in a row        |
-| `table` (`value` cells), `sort` (a button) | rule-free rows; a `th`'s `button.sort` sorts, `aria-sort` marks the sorted     |
+| `table` (`value` cells), `sort` (a button) | rule-free rows (no hover); a `th`'s `button.sort` sorts, `aria-sort` marks it  |
 
 ## Auto-run
 
diff --git a/website/src/components/Playground/monaco/typeLibs.ts b/website/src/components/Playground/monaco/typeLibs.ts
index d7f279837081..3b506e1400d0 100644
--- a/website/src/components/Playground/monaco/typeLibs.ts
+++ b/website/src/components/Playground/monaco/typeLibs.ts
@@ -188,7 +188,7 @@ const PREVIEW_SCOPE_DECLARATIONS = `declare function render(component:JSX.Elemen
         declare function uuid(): string;
         declare function CurrentTime(props: {}):JSX.Element;
         declare function CancelButton(props: { onClick?: () => void }):JSX.Element;
-        declare function Avatar(props: { src: string; size?: number }):JSX.Element;
+        declare function Avatar(props: { src?: string; name?: string; size?: number }):JSX.Element;
         declare function Formatted({ downColor, formatter, formatterFn, timeout, transition, transitionLength, upColor, value, stylePrefix, }: NumberProps):JSX.Element
         declare function TextInput(props:Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size'> & { label?: React.ReactNode; loading?: boolean; size?: 'large' | 'medium' | 'small'; }):JSX.Element;
         declare function TextArea(props:React.TextareaHTMLAttributes<HTMLTextAreaElement> & { label?: React.ReactNode;}):JSX.Element;

From a320852de52acc703d34d8e64095f6e5a1b88d50 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 27 Oct 2026 04:11:59 +0000
Subject: [PATCH 08/10] docs(playground): ink text on the chosen segment;
 touch-sized segments

Avatar takes a src or a name (one is required), and the segmented
control's four-choice limit is documented.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y5C5ZC3WYndrqLXmu9F42e
---
 .../Playground/DesignSystem/Avatar.tsx        | 27 ++++++-------
 .../Playground/DesignSystem/design-system.css | 10 ++++-
 website/src/components/Playground/README.md   | 38 +++++++++----------
 .../components/Playground/monaco/typeLibs.ts  |  2 +-
 4 files changed, 39 insertions(+), 38 deletions(-)

diff --git a/website/src/components/Playground/DesignSystem/Avatar.tsx b/website/src/components/Playground/DesignSystem/Avatar.tsx
index a86695f3cdd6..cadab7cd0e54 100644
--- a/website/src/components/Playground/DesignSystem/Avatar.tsx
+++ b/website/src/components/Playground/DesignSystem/Avatar.tsx
@@ -1,24 +1,19 @@
 import React from 'react';
 
 /** A round profile picture; 32px, or `size` to match the text beside it
- * (smaller in a byline or a comment). With a `name` and no picture, the
- * name's initials on a disc (sized by the design system: 32px, 24px in a
- * table row) */
-export function Avatar({
-  src,
-  name,
-  size = 32,
-}: {
-  src?: string;
-  name?: string;
-  size?: number;
-}) {
-  if (!src)
+ * (smaller in a byline or a comment). Given a `name` instead, the name's
+ * initials on a disc (32px, 22px in a table row), hidden from screen readers
+ * since the name is written beside it */
+export function Avatar(
+  props: ({ src: string } | { name: string }) & { size?: number },
+) {
+  if (!('src' in props))
     return (
       <span className="avatar" aria-hidden>
-        {initials(name ?? '')}
+        {initials(props.name)}
       </span>
     );
+  const { src, size = 32 } = props;
   return (
     <span
       style={{
@@ -41,6 +36,6 @@ export function Avatar({
 
 /** The first letters of a name's first and last words ("Maya Chen" → "MC") */
 function initials(name: string) {
-  const words = name.trim().split(/\s+/);
-  return (words[0]?.[0] ?? '') + (words.length > 1 ? words.at(-1)![0] : '');
+  const [first = '', ...rest] = name.trim().split(/\s+/);
+  return (first[0] ?? '') + (rest.at(-1)?.[0] ?? '');
 }
diff --git a/website/src/components/Playground/DesignSystem/design-system.css b/website/src/components/Playground/DesignSystem/design-system.css
index cd94a4828bfb..86c089f143c5 100644
--- a/website/src/components/Playground/DesignSystem/design-system.css
+++ b/website/src/components/Playground/DesignSystem/design-system.css
@@ -774,7 +774,7 @@ div.playground-preview h1:first-child {
 }
 /* A filter's choices (All, Admins, Members) as one segmented control: the
    words on a track of the well's color, in equal segments, and the chosen
-   one (`aria-pressed`) in the accent on a pill of the sheet that slides
+   one (`aria-pressed`) in full ink on a pill of the sheet that slides
    to it. The pill is the track's ::before, one segment wide, moved by the
    chosen segment's index (counted by :has(), up to four segments). In an
    app header it sits level with the wordmark; on a phone it fits beside it */
@@ -845,9 +845,15 @@ html[data-theme='dark'] .playground-preview .segmented::before {
   transition: color var(--motion-snappy);
 }
 .playground-preview .segmented > button[aria-pressed='true'] {
-  color: var(--ds-accent);
+  color: var(--ds-text);
   font-weight: 600;
 }
+/* a fingertip's target on touch screens: 40px with the track */
+@media (pointer: coarse) {
+  .playground-preview .segmented > button {
+    min-height: 36px;
+  }
+}
 @media (hover: hover) {
   .playground-preview .segmented > button:not([aria-pressed='true']):hover {
     color: var(--ds-text);
diff --git a/website/src/components/Playground/README.md b/website/src/components/Playground/README.md
index 519ea2f01b9e..022041087166 100644
--- a/website/src/components/Playground/README.md
+++ b/website/src/components/Playground/README.md
@@ -238,25 +238,25 @@ Styled elements: `h2` (page title), `button` (`primary` fills one;
 `aria-busy` shows pending), text inputs, `nav`, `fieldset`, `progress`,
 `table`.
 
-| Class                                      | Use for                                                                        |
-| ------------------------------------------ | ------------------------------------------------------------------------------ |
-| `appHeader` + `appTitle`                   | the app's top bar and wordmark                                                 |
-| `card`                                     | a group (no box: the sheet is the card)                                        |
-| `list`, `listItem` (`nogap`, `spaced`)     | rows; checkbox rows highlight and fade when done                               |
-| `meta`                                     | secondary text; last in a `listItem`, it sits at the row's end                 |
-| `value`                                    | a row's figure (a price); last in a `listItem`, at the row's end, tabular      |
-| `byline`, `author` (`Avatar` takes `size`) | who wrote something; `Avatar` with a `name` and no `src` draws its initials    |
-| `pill` (`primary`)                         | a label on a row (a member's role); `primary` washes it in the accent          |
-| `buttonGroup`                              | segmented actions (Fail Soft, Fail Hard)                                       |
-| `segmented`                                | a filter's choices on a track; `aria-pressed` marks the pick, the pill slides  |
-| `cancel` (`<CancelButton />`)              | a row's remove button                                                          |
-| `skeleton`                                 | a value still loading; `<Loading />`, the default fallback, draws a page       |
-| `toaster`, `toast`                         | notifications: render `<Toaster />`, call `toast.success()` or `toast.error()` |
-| `boardColumn`                              | a kanban column                                                                |
-| `upvote` (a button)                        | an upvote with its count; empty, the arrow alone                               |
-| `stats` (a `dl`)                           | figures side by side, each large over its label; a lone one fills the row      |
-| `stepper` (− `output` +)                   | a quantity's buttons around its count (one button alone: Add); in a row        |
-| `table` (`value` cells), `sort` (a button) | rule-free rows (no hover); a `th`'s `button.sort` sorts, `aria-sort` marks it  |
+| Class                                      | Use for                                                                         |
+| ------------------------------------------ | ------------------------------------------------------------------------------- |
+| `appHeader` + `appTitle`                   | the app's top bar and wordmark                                                  |
+| `card`                                     | a group (no box: the sheet is the card)                                         |
+| `list`, `listItem` (`nogap`, `spaced`)     | rows; checkbox rows highlight and fade when done                                |
+| `meta`                                     | secondary text; last in a `listItem`, it sits at the row's end                  |
+| `value`                                    | a row's figure (a price); last in a `listItem`, at the row's end, tabular       |
+| `byline`, `author` (`Avatar` takes `size`) | who wrote something; `Avatar` with a `name` and no `src` draws its initials     |
+| `pill` (`primary`)                         | a label on a row (a member's role); `primary` washes it in the accent           |
+| `buttonGroup`                              | segmented actions (Fail Soft, Fail Hard)                                        |
+| `segmented`                                | a filter's 2-4 choices on a track; `aria-pressed` marks the pick, a pill slides |
+| `cancel` (`<CancelButton />`)              | a row's remove button                                                           |
+| `skeleton`                                 | a value still loading; `<Loading />`, the default fallback, draws a page        |
+| `toaster`, `toast`                         | notifications: render `<Toaster />`, call `toast.success()` or `toast.error()`  |
+| `boardColumn`                              | a kanban column                                                                 |
+| `upvote` (a button)                        | an upvote with its count; empty, the arrow alone                                |
+| `stats` (a `dl`)                           | figures side by side, each large over its label; a lone one fills the row       |
+| `stepper` (− `output` +)                   | a quantity's buttons around its count (one button alone: Add); in a row         |
+| `table` (`value` cells), `sort` (a button) | rule-free rows (no hover); a `th`'s `button.sort` sorts, `aria-sort` marks it   |
 
 ## Auto-run
 
diff --git a/website/src/components/Playground/monaco/typeLibs.ts b/website/src/components/Playground/monaco/typeLibs.ts
index 3b506e1400d0..ab128ce69500 100644
--- a/website/src/components/Playground/monaco/typeLibs.ts
+++ b/website/src/components/Playground/monaco/typeLibs.ts
@@ -188,7 +188,7 @@ const PREVIEW_SCOPE_DECLARATIONS = `declare function render(component:JSX.Elemen
         declare function uuid(): string;
         declare function CurrentTime(props: {}):JSX.Element;
         declare function CancelButton(props: { onClick?: () => void }):JSX.Element;
-        declare function Avatar(props: { src?: string; name?: string; size?: number }):JSX.Element;
+        declare function Avatar(props: ({ src: string } | { name: string }) & { size?: number }):JSX.Element;
         declare function Formatted({ downColor, formatter, formatterFn, timeout, transition, transitionLength, upColor, value, stylePrefix, }: NumberProps):JSX.Element
         declare function TextInput(props:Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size'> & { label?: React.ReactNode; loading?: boolean; size?: 'large' | 'medium' | 'small'; }):JSX.Element;
         declare function TextArea(props:React.TextareaHTMLAttributes<HTMLTextAreaElement> & { label?: React.ReactNode;}):JSX.Element;

From c3011e9313c37b2a8641eca933e0156edb56fc77 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 27 Oct 2026 04:17:53 +0000
Subject: [PATCH 09/10] docs(playground): simplify the segmented control and
 Avatar

The pill shares the first segment's grid cell, so it sizes itself without
counting segments; buttons reuse the base control's font and focus ring;
the raised pill's colors are theme tokens. Avatar falls back to initials
whenever it has no src, and touch screens keep the regular filter size.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y5C5ZC3WYndrqLXmu9F42e
---
 .../Playground/DesignSystem/Avatar.tsx        | 19 +++---
 .../Playground/DesignSystem/base.css          |  8 +++
 .../Playground/DesignSystem/design-system.css | 60 +++++--------------
 .../components/Playground/monaco/typeLibs.ts  |  2 +-
 4 files changed, 36 insertions(+), 53 deletions(-)

diff --git a/website/src/components/Playground/DesignSystem/Avatar.tsx b/website/src/components/Playground/DesignSystem/Avatar.tsx
index cadab7cd0e54..61df5eadcdcc 100644
--- a/website/src/components/Playground/DesignSystem/Avatar.tsx
+++ b/website/src/components/Playground/DesignSystem/Avatar.tsx
@@ -1,19 +1,24 @@
 import React from 'react';
 
 /** A round profile picture; 32px, or `size` to match the text beside it
- * (smaller in a byline or a comment). Given a `name` instead, the name's
+ * (smaller in a byline or a comment). Without a `src`, its `name`'s
  * initials on a disc (32px, 22px in a table row), hidden from screen readers
  * since the name is written beside it */
-export function Avatar(
-  props: ({ src: string } | { name: string }) & { size?: number },
-) {
-  if (!('src' in props))
+export function Avatar({
+  src,
+  name = '',
+  size = 32,
+}: {
+  src?: string;
+  name?: string;
+  size?: number;
+}) {
+  if (!src)
     return (
       <span className="avatar" aria-hidden>
-        {initials(props.name)}
+        {initials(name)}
       </span>
     );
-  const { src, size = 32 } = props;
   return (
     <span
       style={{
diff --git a/website/src/components/Playground/DesignSystem/base.css b/website/src/components/Playground/DesignSystem/base.css
index 3b95d67c7344..54314e04d3d4 100644
--- a/website/src/components/Playground/DesignSystem/base.css
+++ b/website/src/components/Playground/DesignSystem/base.css
@@ -61,6 +61,11 @@
     var(--ds-surface)
   );
   --ds-on-accent: #fff;
+  /* a surface raised off a well (a segmented control's pill) */
+  --ds-raised: var(--ds-surface);
+  --ds-raised-shadow:
+    0 1px 2px var(--pg-shadow-edge),
+    0 0 0 1px color-mix(in srgb, var(--ds-text) 6%, transparent);
   /* Infima's own vars, re-pointed so what reads them (the rt-* fields, links,
      the error panel's text) follows this palette in both themes */
   --ifm-color-emphasis-0: var(--ds-surface);
@@ -99,6 +104,9 @@ html[data-theme='dark'] .playground-preview {
   --ds-accent-strong: #7cc1f4;
   --ds-accent-wash: 14%;
   --ds-on-accent: #04121f;
+  /* a step up from the well, with no shadow to cast */
+  --ds-raised: color-mix(in srgb, var(--ds-text) 14%, var(--ds-surface-2));
+  --ds-raised-shadow: none;
   /* fields sit in the well, a step above the panel */
   --ifm-color-emphasis-0: var(--ds-surface-2);
 }
diff --git a/website/src/components/Playground/DesignSystem/design-system.css b/website/src/components/Playground/DesignSystem/design-system.css
index 86c089f143c5..530324923483 100644
--- a/website/src/components/Playground/DesignSystem/design-system.css
+++ b/website/src/components/Playground/DesignSystem/design-system.css
@@ -772,16 +772,13 @@ div.playground-preview h1:first-child {
 .playground-preview .appHeader .buttonGroup {
   margin-top: 0;
 }
-/* A filter's choices (All, Admins, Members) as one segmented control: the
-   words on a track of the well's color, in equal segments, and the chosen
-   one (`aria-pressed`) in full ink on a pill of the sheet that slides
-   to it. The pill is the track's ::before, one segment wide, moved by the
-   chosen segment's index (counted by :has(), up to four segments). In an
-   app header it sits level with the wordmark; on a phone it fits beside it */
+/* A filter's choices (All, Admins, Members) on a track of the well's
+   color, in equal segments; the chosen one (`aria-pressed`) in full ink on a
+   pill that slides to it. The pill shares the first segment's grid cell and
+   moves by the chosen one's index. In an app header it sits level with the
+   wordmark; on a phone it fits beside it */
 .playground-preview .segmented {
-  --segments: 1;
   --segment: 0;
-  position: relative;
   display: grid;
   grid-auto-flow: column;
   grid-auto-columns: 1fr;
@@ -791,15 +788,6 @@ div.playground-preview h1:first-child {
   border-radius: 999px;
   background: var(--ds-surface-2);
 }
-.playground-preview .segmented:has(> :nth-child(2):last-child) {
-  --segments: 2;
-}
-.playground-preview .segmented:has(> :nth-child(3):last-child) {
-  --segments: 3;
-}
-.playground-preview .segmented:has(> :nth-child(4):last-child) {
-  --segments: 4;
-}
 .playground-preview .segmented:has(> :nth-child(2)[aria-pressed='true']) {
   --segment: 1;
 }
@@ -809,30 +797,25 @@ div.playground-preview h1:first-child {
 .playground-preview .segmented:has(> :nth-child(4)[aria-pressed='true']) {
   --segment: 3;
 }
+.playground-preview .segmented::before,
+.playground-preview .segmented > :first-child {
+  grid-area: 1 / 1;
+}
 .playground-preview .segmented::before {
   content: '';
-  position: absolute;
-  inset: 2px auto 2px 2px;
-  width: calc((100% - 4px) / var(--segments));
   border-radius: 999px;
-  background: var(--ds-surface);
-  box-shadow:
-    0 1px 2px var(--pg-shadow-edge),
-    0 0 0 1px color-mix(in srgb, var(--ds-text) 6%, transparent);
+  background: var(--ds-raised);
+  box-shadow: var(--ds-raised-shadow);
   transform: translateX(calc(100% * var(--segment)));
   transition: transform var(--motion-snappy);
 }
-/* at night the pill is a step up from the track, with no shadow to cast */
-html[data-theme='dark'] .playground-preview .segmented::before {
-  background: color-mix(in srgb, var(--ds-text) 14%, var(--ds-surface-2));
-  box-shadow: none;
-}
 @media (prefers-reduced-motion: reduce) {
   .playground-preview .segmented::before {
     transition: none;
   }
 }
 .playground-preview .segmented > button {
+  /* above the pill, which its transform lifts over unpositioned siblings */
   position: relative;
   margin: 0;
   padding: 4px 12px;
@@ -840,36 +823,23 @@ html[data-theme='dark'] .playground-preview .segmented::before {
   border-radius: 999px;
   background: none;
   color: var(--ds-text-muted);
-  font: 500 var(--ds-text-sm) / 1.4 var(--ifm-font-family-base);
-  cursor: pointer;
-  transition: color var(--motion-snappy);
 }
 .playground-preview .segmented > button[aria-pressed='true'] {
   color: var(--ds-text);
   font-weight: 600;
 }
-/* a fingertip's target on touch screens: 40px with the track */
-@media (pointer: coarse) {
-  .playground-preview .segmented > button {
-    min-height: 36px;
-  }
-}
 @media (hover: hover) {
   .playground-preview .segmented > button:not([aria-pressed='true']):hover {
     color: var(--ds-text);
   }
 }
 .playground-preview .segmented > button:focus-visible {
-  outline: 2px solid var(--ds-accent);
   outline-offset: -2px;
 }
 /* A table (a team's members): rows on the sheet with no rules, stripes or
-   hover (a row does nothing on a click, like a list row without a control),
-   set apart by space, its first and last columns flush with the app
-   header's text. Headers are a group's label; a sort arrow has no baseline,
-   so they sit at the UA's middle and every label stays level. `value` cells
-   (a count, a year) sit at the column's end. Infima's borders and stripes
-   are dropped */
+   hover, set apart by space, its first and last columns flush with the app
+   header's text. Headers are a group's label; `value` cells (a count, a
+   year) sit at the column's end. Infima's borders and stripes are dropped */
 .playground-preview table {
   --ifm-table-stripe-background: transparent;
   width: 100%;
diff --git a/website/src/components/Playground/monaco/typeLibs.ts b/website/src/components/Playground/monaco/typeLibs.ts
index ab128ce69500..3b506e1400d0 100644
--- a/website/src/components/Playground/monaco/typeLibs.ts
+++ b/website/src/components/Playground/monaco/typeLibs.ts
@@ -188,7 +188,7 @@ const PREVIEW_SCOPE_DECLARATIONS = `declare function render(component:JSX.Elemen
         declare function uuid(): string;
         declare function CurrentTime(props: {}):JSX.Element;
         declare function CancelButton(props: { onClick?: () => void }):JSX.Element;
-        declare function Avatar(props: ({ src: string } | { name: string }) & { size?: number }):JSX.Element;
+        declare function Avatar(props: { src?: string; name?: string; size?: number }):JSX.Element;
         declare function Formatted({ downColor, formatter, formatterFn, timeout, transition, transitionLength, upColor, value, stylePrefix, }: NumberProps):JSX.Element
         declare function TextInput(props:Omit<React.InputHTMLAttributes<HTMLInputElement>, 'size'> & { label?: React.ReactNode; loading?: boolean; size?: 'large' | 'medium' | 'small'; }):JSX.Element;
         declare function TextArea(props:React.TextareaHTMLAttributes<HTMLTextAreaElement> & { label?: React.ReactNode;}):JSX.Element;

From f57b53b1c3a6f987991b7f7b2caf46d4a66ec63b Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Tue, 27 Oct 2026 04:21:18 +0000
Subject: [PATCH 10/10] docs(playground): note the segmented control's
 four-choice limit

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01Y5C5ZC3WYndrqLXmu9F42e
---
 .../src/components/Playground/DesignSystem/design-system.css  | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/website/src/components/Playground/DesignSystem/design-system.css b/website/src/components/Playground/DesignSystem/design-system.css
index 530324923483..bc3f52e7e519 100644
--- a/website/src/components/Playground/DesignSystem/design-system.css
+++ b/website/src/components/Playground/DesignSystem/design-system.css
@@ -775,8 +775,8 @@ div.playground-preview h1:first-child {
 /* A filter's choices (All, Admins, Members) on a track of the well's
    color, in equal segments; the chosen one (`aria-pressed`) in full ink on a
    pill that slides to it. The pill shares the first segment's grid cell and
-   moves by the chosen one's index. In an app header it sits level with the
-   wordmark; on a phone it fits beside it */
+   moves by the chosen one's index (up to the fourth). In an app header it
+   sits level with the wordmark; on a phone it fits beside it */
 .playground-preview .segmented {
   --segment: 0;
   display: grid;