@tailor-platform/app-shell 1.1.1 → 1.3.0

package/skills/app-shell-patterns/references/fundamental/design-system.md

@@ -0,0 +1,355 @@
+# Design System
+
+Authority for **visual-only** decisions — tokens, theme imports, breakpoints intent, `**astw:`** rules, and custom-component conformance. For **React component APIs** (imports, props, JSX composition), pair this file with `**components.md`\*\*; that split avoids duplicating tables and lengthy examples across both docs.
+
+`@tailor-platform/app-shell` (ERP scaffolds target **≥0.36**; bump your app’s pinned version deliberately) ships an opinionated design system via CSS variables and a `theme.css` import. Use it whether you are consuming AppShell components (most cases) or building a custom component to fill a gap.
+
+**The tokens are the rails.** Consistency across customers, apps, and AI runs comes from the token system, not from rules written in prose. A hand-typed `#fff` or `padding: 13px` is not a "small deviation" — it is the mechanism by which consistency dies. Every visual value you reach for must resolve to a token in this file. If a token is missing, add one; never inline.
+
+## 1. Setup
+
+Authoritative app wiring also lives in `**project-setup.md`**; **scaffold `index.css`\*\* currently does:
+
+```css
+@import "tailwindcss";
+@import "tw-animate-css";
+
+@import "@tailor-platform/app-shell/styles";
+@import "@tailor-platform/app-shell/theme.css";
+```
+
+Adjust if your App Shell version documents a different barrel filename, but keep this split:
+
+- `**theme.css**` — design tokens as CSS variables on `:root`.
+- `**styles**` (package export) — bundled component styles AppShell ships for primitives.
+- `**tailwindcss**` — utilities; token-backed classes (`bg-surface-1`, `text-fg-muted`) resolve through the theme.
+
+Older docs referred to `app-shell.css`; prefer the `**styles**` import the template uses.
+
+Tailwind v4 stays CSS-first; minimal `vite` / PostCSS wiring is in `**project-setup.md**`.
+
+## 2. Theming via CSS variables
+
+AppShell controls its theme through CSS variables. Override them in `:root` (global) or a scoped selector (per-section, per-tenant, dark mode) to customize. Any token defined in `theme.css` can be overridden after the import.
+
+```css
+:root {
+  --color-primary: #3b82f6;
+  --color-background: #ffffff;
+}
+
+[data-theme="dark"] {
+  --color-background: #0a0a0a;
+  --color-foreground: #fafafa;
+}
+```
+
+Override at the highest scope where the change applies. Do not duplicate token values across files — change them at the source.
+
+**Dark mode** is supported via `[data-theme="dark"]` on the root element. AppShell primitives respect it automatically. Custom components inherit dark-mode behaviour for free as long as they reference tokens (`bg-surface-1`, `text-fg-default`) and never inline literal colors.
+
+## 3. Component styling with data attributes
+
+AppShell's UI components support data-attribute-based styling, following the [Base UI data attributes](https://base-ui.com/react/handbook/styling#data-attributes) convention. Components expose `data-`\* attributes that reflect their internal state, enabling CSS-only style control without JavaScript:
+
+```css
+/* Style a component based on its state */
+.SwitchThumb[data-checked] {
+  background-color: green;
+}
+
+.MenuItem[data-highlighted] {
+  background-color: var(--color-primary);
+  color: white;
+}
+```
+
+This works with Tailwind as well — **use theme tokens**, not raw Tailwind grays:
+
+```tsx
+<Switch.Thumb className="bg-surface-3 data-[checked]:bg-primary" />
+```
+
+Check each component's API reference (`components.md`) for the data attributes it exposes. Custom components must follow the same convention (see Section 6).
+
+## 4. Tokens
+
+All values below are exposed by `theme.css`. **Use the token, never hand-type the value.** A hex literal or magic px in a PR is a review failure.
+
+### Color
+
+Four families. Pick by **intent**, not by visual taste.
+
+| Family     | Token                    | Use                                 | Tailwind                      |
+| ---------- | ------------------------ | ----------------------------------- | ----------------------------- |
+| Surface    | `--color-surface-1`      | page background                     | `bg-surface-1`                |
+| Surface    | `--color-surface-2`      | card on page                        | `bg-surface-2`                |
+| Surface    | `--color-surface-3`      | nested card on card                 | `bg-surface-3`                |
+| Foreground | `--color-fg-default`     | primary text                        | `text-fg-default`             |
+| Foreground | `--color-fg-muted`       | secondary text, descriptions        | `text-fg-muted`               |
+| Foreground | `--color-fg-subtle`      | tertiary text, captions, timestamps | `text-fg-subtle`              |
+| Brand      | `--color-primary`        | primary buttons, links, focus rings | `bg-primary` / `text-primary` |
+| Brand      | `--color-primary-hover`  | brand hover state                   | `hover:bg-primary-hover`      |
+| Brand      | `--color-primary-active` | brand pressed state                 | `active:bg-primary-active`    |
+| Status     | `--color-danger`         | destructive actions, errors         | `bg-danger` / `text-danger`   |
+| Status     | `--color-warning`        | non-blocking caution                | `bg-warning` / `text-warning` |
+| Status     | `--color-success`        | confirmations, completed states     | `bg-success` / `text-success` |
+| Status     | `--color-info`           | neutral callouts                    | `bg-info` / `text-info`       |
+
+```tsx
+// Good — Button exposes a destructive variant; prefer variants over bolting tokens on className when available
+<div className="bg-surface-1 text-fg-default">…</div>
+<Button variant="destructive">Delete</Button>
+
+// Bad — raw colors bypass the theme
+<div style={{ background: "#fff", color: "#111" }}>…</div>
+```
+
+Never reach for raw color names. If a status doesn't fit, that's a content problem, not a token problem.
+
+### Spacing
+
+Linear scale on a 4px base. Padding, margin, and gap all come from this scale. Tailwind's `p-4`, `gap-2`, `mt-8` resolve to the same tokens.
+
+| Token        | Value | Common use                |
+| ------------ | ----- | ------------------------- |
+| `--space-0`  | 0     | reset                     |
+| `--space-1`  | 4px   | tight icon-text gap       |
+| `--space-2`  | 8px   | inline gap, small padding |
+| `--space-3`  | 12px  | row gap, button padding   |
+| `--space-4`  | 16px  | card padding, default gap |
+| `--space-6`  | 24px  | section gap               |
+| `--space-8`  | 32px  | major section gap         |
+| `--space-12` | 48px  | page section break        |
+| `--space-16` | 64px  | hero spacing              |
+
+```tsx
+// Good — scale step
+<div className="flex gap-3 p-4">…</div>
+
+// Bad — magic value
+<div className="p-[13px]">…</div>
+```
+
+Hand-typing `padding: 13px` is a smell. Round to the nearest scale step; if nothing fits, the layout is wrong, not the scale.
+
+### Typography
+
+Named roles. Each token bundles font-size + line-height + weight. Pick by **role**, not by size. Don't set `font-size` and `line-height` independently.
+
+| Token     | Tailwind       | Use                          |
+| --------- | -------------- | ---------------------------- |
+| `display` | `text-display` | hero / marketing surfaces    |
+| `h1`      | `text-h1`      | page title                   |
+| `h2`      | `text-h2`      | section heading              |
+| `h3`      | `text-h3`      | subsection / card title      |
+| `h4`      | `text-h4`      | nested heading               |
+| `body-lg` | `text-body-lg` | emphasised body              |
+| `body`    | `text-body`    | default body copy            |
+| `body-sm` | `text-body-sm` | dense rows, secondary copy   |
+| `caption` | `text-caption` | timestamps, labels, metadata |
+| `mono`    | `text-mono`    | IDs, code, numbers in tables |
+
+```tsx
+<h2 className="text-h2">Section</h2>
+<p className="text-body text-fg-muted">Description copy</p>
+<span className="text-caption text-fg-subtle">Updated 2h ago</span>
+```
+
+### Radius
+
+Pick by component role. A card is always `md`, regardless of its size on screen.
+
+| Token           | Use                 |
+| --------------- | ------------------- |
+| `--radius-sm`   | inputs, small chips |
+| `--radius-md`   | cards, buttons      |
+| `--radius-lg`   | modals, sheets      |
+| `--radius-xl`   | large surfaces      |
+| `--radius-full` | pills, avatars      |
+
+### Elevation
+
+Higher elevation reads as "more transient" — match the component's lifetime. Never hand-craft a `box-shadow`.
+
+| Token           | Use                      |
+| --------------- | ------------------------ |
+| `--elevation-0` | flat surface             |
+| `--elevation-1` | persistent panel, card   |
+| `--elevation-2` | sticky bar, hovered card |
+| `--elevation-3` | popover, menu            |
+| `--elevation-4` | modal, dialog, sheet     |
+
+### Motion
+
+Duration paired with easing. Match motion to the change's lifetime — short events get short durations.
+
+| Token             | ~Duration | Use                            |
+| ----------------- | --------- | ------------------------------ |
+| `--motion-fast`   | 120ms     | hover, focus, button press     |
+| `--motion-base`   | 200ms     | state changes (toggle, select) |
+| `--motion-slow`   | 320ms     | entrance, dialog open          |
+| `--motion-slower` | 500ms     | full-page transitions          |
+| `--ease-out`      | —         | entrances, reveals             |
+| `--ease-in-out`   | —         | symmetric state changes        |
+
+```css
+.menu-item {
+  transition: background-color var(--motion-fast) var(--ease-out);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .menu-item {
+    transition: none;
+  }
+}
+```
+
+Always wrap motion in `@media (prefers-reduced-motion: reduce)` and collapse to instant or near-instant transitions. AppShell components handle this internally; custom components must do the same.
+
+### Z-index
+
+Never invent a z value. If you need a new layer, add a token; never `z-index: 9999`. Popups and overlays share `50` intentionally — sequencing comes from DOM order, not z escalation.
+
+| Token              | Value | Use                           |
+| ------------------ | ----- | ----------------------------- |
+| `--z-sidebar`      | 10    | persistent sidebar            |
+| `--z-sidebar-rail` | 10    | sidebar collapsed rail        |
+| `--z-popup`        | 50    | menu, tooltip, popover        |
+| `--z-overlay`      | 50    | modal, sheet, dialog backdrop |
+
+### Icon sizes
+
+Pair icon size with the surrounding text scale. Pass via the `size` prop, not raw width/height.
+
+| Token       | Pairs with text       |
+| ----------- | --------------------- |
+| `--icon-sm` | `body-sm`, `caption`  |
+| `--icon-md` | `body`, `body-lg`     |
+| `--icon-lg` | `h3`, `h4`            |
+| `--icon-xl` | `h1`, `h2`, `display` |
+
+```tsx
+<Icon name="check" size="md" />
+```
+
+### Breakpoints
+
+| Token | Width  |
+| ----- | ------ |
+| `sm`  | 640px  |
+| `md`  | 768px  |
+| `lg`  | 1024px |
+| `xl`  | 1280px |
+| `2xl` | 1536px |
+
+**ERP target is `xl`/`2xl` desktop.** Pages should be designed for those widths first; smaller breakpoints exist for graceful degradation, not parity. Don't waste effort on mobile-first composition unless a screen explicitly calls for it. A list page that collapses gracefully at `md` is fine; a list page redesigned for `sm` is over-investment.
+
+Two-column **behavior** (right rail stacks under `**lg`**): respect AppShell defaults — do not force side-by-side grids on narrow viewports. `**Layout`column width table** numbers live in`**components.md` → Layout**; reuse them instead of guessing rem values here.
+
+## 5. The `astw:` prefix
+
+AppShell exposes **layout / sizing / overflow** escapes on some components via props like `containerClassName`, `contentClassName`, `className` on roots. Prefix those utilities with `**astw:`\*\* so they apply to the wrapper AppShell controls.
+
+**Do not duplicate full component trees here.** Typical patterns (full `**DataTable`** composition, `**Sheet`+ footer**,`**Table.Root` + card insets**) live in `**components.md`\*\* with JSX you can copy.
+
+Minimal illustrations — same rules apply to other `*ClassName` hooks:
+
+```tsx
+<Table.Root containerClassName="astw:px-6 astw:max-h-96 astw:overflow-y-auto" />
+<Sheet contentClassName="astw:w-[480px] astw:flex astw:flex-col astw:gap-4" />
+```
+
+Rules:
+
+- `**astw:**` only on AppShell `*ClassName` / root `className` hooks each component exposes. Use **plain** Tailwind (`flex`, `gap-4`, `bg-surface-1`, …) on **your** markup.
+- Stick to **layout** utilities (`flex`, `grid`, `max-h-*`, `min-h-0`, `overflow-*`, widths). Avoid painting over internal AppShell padding or colors via `astw:` — prefer an upstream prop or composition change.
+- Steps like `**astw:p-4`\*\* still resolve through tokens — never arbitrary `astw:p-[13px]`.
+
+## 6. When AppShell doesn't have a component you need
+
+Most ERP screens compose entirely from AppShell primitives. When you hit a gap, work through this decision tree before building anything:
+
+### Decision tree
+
+1. **Can you compose existing AppShell primitives?** A "card with metric and trend arrow" is `Card` + `Stat` + `Icon`, not a new component. Compose first.
+2. **If composition won't work, is the behavior one-off?** Build it locally under `src/components/<name>/` and flag it for the `build-component` skill, which promotes useful customs into AppShell upstream.
+3. **If it's already proven reusable across 2+ apps**, skip local entirely — use the `build-component` skill to add it to AppShell directly.
+
+### Conformance rules (non-negotiable for any custom component)
+
+- **Tokens only.** No hex literals, no magic px values, no hand-rolled shadows. Every visual property maps to a token from Section 4.
+- **Base UI data-attribute pattern for state.** Expose `data-*` attributes that reflect internal state; never style off React props alone. A custom toggle exposes `data-checked`; a custom step indicator exposes `data-active`, `data-completed`, etc.
+- **Compose AppShell primitives inside.** If the custom needs a button, use `Button` — not raw `<button>`. Same for `Input`, `Badge`, `Icon`. The custom's job is composition, not reinvention.
+- **Document with a `README.md`** in the component folder listing: purpose, props, tokens used, and a brief justification for why this can't be composed from existing AppShell primitives.
+- **Match accessibility behavior** of the closest AppShell equivalent — focus management, ARIA roles/attributes, keyboard interactions. Reach for Base UI primitives if the behavior is non-trivial.
+
+Example skeleton for a local custom component:
+
+```tsx
+// src/components/StepIndicator/index.tsx
+import { Icon } from "@tailor-platform/app-shell";
+
+type Props = { steps: string[]; current: number };
+
+export function StepIndicator({ steps, current }: Props) {
+  return (
+    <ol className="flex gap-2">
+      {steps.map((label, i) => (
+        <li
+          key={label}
+          data-active={i === current ? "" : undefined}
+          data-completed={i < current ? "" : undefined}
+          className="
+            flex items-center gap-2 px-3 py-2 rounded-md
+            bg-surface-2 text-fg-muted text-body-sm
+            data-[active]:bg-primary data-[active]:text-fg-default
+            data-[completed]:text-success
+          "
+        >
+          {i < current && <Icon name="check" size="sm" />}
+          {label}
+        </li>
+      ))}
+    </ol>
+  );
+}
+```
+
+Notice: tokens for every value, `data-*` attributes for state, no hex literals, AppShell `Icon` composed inside.
+
+### Promotion path
+
+When a custom component proves reusable across 2+ apps, promote it upstream into AppShell via the `build-component` skill (a separate skill at `~/.claude/skills/build-component/`). The skill handles API design, exports, test coverage, and the upstream PR. Local custom components should be considered staging — not a permanent home.
+
+## 7. Quick reference
+
+### Where to look
+
+| Concern                                             | File                               |
+| --------------------------------------------------- | ---------------------------------- |
+| Component imports, props, JSX composition           | **`components.md`**                |
+| Page / screen layout patterns                       | **`patterns/<type>/<slug>.md`**    |
+| Design tokens, `astw:` rules, custom UI conformance | **this file** (`design-system.md`) |
+
+**`components.md`** holds long JSX compositions (e.g. **`DataTable`**, **card + `Table`**). **Do not copy those trees into this file** — link back here only for tokens and `astw:` policy.
+
+`patterns/` is organised by page type: `patterns/list/`, `patterns/detail/`, `patterns/form/`, `patterns/interaction/`. Pick the slug matching the screen you're building.
+
+### Semantic decisions
+
+| Intent                             | Pick                                                                                                                  |
+| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------- |
+| Destructive action (delete, void)  | Prefer **`Button`** `variant="destructive"`; use danger tokens on custom surfaces; confirm in dialog at elevation `4` |
+| Non-blocking caution               | `bg-warning`                                                                                                          |
+| Confirmation / completed state     | `bg-success`                                                                                                          |
+| Neutral callout                    | `bg-info`                                                                                                             |
+| Persistent panel (sidebar, header) | elevation `1`                                                                                                         |
+| Hovered / sticky surface           | elevation `2`                                                                                                         |
+| Popover / menu / tooltip           | elevation `3`, `--motion-fast`                                                                                        |
+| Modal / sheet / dialog             | elevation `4`, `--motion-slow` entrance                                                                               |
+| Hover / focus transition           | `--motion-fast`                                                                                                       |
+| State change (toggle, select)      | `--motion-base`                                                                                                       |
+| Two-column detail at <1024         | right column collapses below main — do not override                                                                   |
+| Inline ID, code, table number      | `text-mono`                                                                                                           |
+| Timestamp, label, subtle metadata  | `text-caption text-fg-subtle`                                                                                         |

package/skills/app-shell-patterns/references/fundamental/graphql.md

@@ -0,0 +1,205 @@
+# GraphQL Conventions
+
+Type-safe GraphQL via `gql.tada`. The frontend never hand-writes types — generated bindings come from `pnpm generate` (step 2 of the workflow) reading the deployed backend schema.
+
+## Setup
+
+Every GraphQL-aware module imports from the local `@/graphql` barrel:
+
+```ts
+import { graphql, type FragmentOf, readFragment } from "@/graphql";
+```
+
+`@/graphql` is generated. Don't import `gql` from `urql` or `gql.tada` directly — go through the barrel so types stay coherent.
+
+The urql client is wired in `App.tsx` (see [project-setup.md](project-setup.md)). Pages don't construct their own client.
+
+## Built-in operations vs custom resolvers
+
+The Tailor Platform auto-generates per-entity queries when the resolver doc opts in via `gqlOperations: "query"`:
+
+- `<entity>(id: ID!)` — get one
+- `<entities>` — list, returned as a connection (`edges { node { ... } }`, plus `pageInfo`)
+
+Mutations are always custom — they come from resolver docs (Tier 3) and live in `backend/src/resolvers/`. The generated types appear in `@/graphql` after `pnpm generate`.
+
+## Fragment collocation
+
+**Each component owns its fragment.** The parent page imports the fragment and composes it into the page query. This is the single most important GraphQL convention in this skill.
+
+```tsx
+// components/order-summary.tsx
+import { graphql, type FragmentOf, readFragment } from "@/graphql";
+
+export const OrderSummaryFragment = graphql(`
+  fragment OrderSummary on Order {
+    id
+    number
+    status
+    total
+  }
+`);
+
+export const OrderSummary = ({ order }: { order: FragmentOf<typeof OrderSummaryFragment> }) => {
+  const data = readFragment(OrderSummaryFragment, order);
+  return (
+    <div>
+      {data.number} — {data.status}
+    </div>
+  );
+};
+```
+
+```tsx
+// pages/orders/[id]/page.tsx
+import { graphql } from "@/graphql";
+import { OrderSummary, OrderSummaryFragment } from "@/components/order-summary";
+
+const OrderQuery = graphql(
+  `
+    query Order($id: ID!) {
+      order(id: $id) {
+        ...OrderSummary
+      }
+    }
+  `,
+  [OrderSummaryFragment],
+);
+```
+
+Rules:
+
+- Each component file exports `<Name>Fragment` alongside the component.
+- The component's prop type is `FragmentOf<typeof <Name>Fragment>`. Always call `readFragment(<Name>Fragment, prop)` once to read it.
+- The parent's query lists the fragment in the second `graphql(...)` argument (the dependency array). Forgetting the dep array works at runtime but loses type narrowing.
+- Don't pass raw fields between components — pass the fragment value. This keeps types and queries in lockstep.
+
+## Connection pattern (lists)
+
+Built-in `<entities>` queries return a connection. Use `edges { node { ... } }`:
+
+```tsx
+const OrdersQuery = graphql(
+  `
+    query Orders($first: Int, $after: String) {
+      orders(first: $first, after: $after) {
+        edges {
+          node {
+            ...OrderSummary
+          }
+        }
+        pageInfo {
+          hasNextPage
+          endCursor
+        }
+      }
+    }
+  `,
+  [OrderSummaryFragment],
+);
+
+const [{ data }] = useQuery({ query: OrdersQuery, variables: { first: 25 } });
+const orders = data?.orders.edges.map((e) => e.node) ?? [];
+```
+
+For `pnpm gql-tada:check` to pass, always destructure with optional chaining and provide a fallback (`?? []`).
+
+### Wiring to `DataTable` (sort, filters, pagination)
+
+For **standard list pages**, do not hand-roll only `first` / `after`. Compose AppShell **`DataTable`** + **`useCollectionVariables`** + **`useDataTable`**: derive query variables from `variables.pagination`, `variables.query`, `variables.order`, map `edges` / `pageInfo` / `total` into `useDataTable`’s `data`. See **`patterns/list/dense-scan.md`** and **`components.md` → DataTable**.
+
+When `@tailor-platform/app-shell-sdk-plugin` codegen is enabled, pass generated **`tableMetadata`** into **`useCollectionVariables`** so `variables.query` / `variables.order` are typed against your Tailor GraphQL inputs (upstream **data-table.md** Typed query variables).
+
+## Mutations and cache invalidation
+
+Mutations from custom resolvers appear in `@/graphql` after `pnpm generate`:
+
+```tsx
+import { useMutation } from "urql";
+import { graphql } from "@/graphql";
+import { useToast } from "@tailor-platform/app-shell";
+
+const CreateOrderMutation = graphql(`
+  mutation CreateOrder($input: CreateOrderInput!) {
+    createOrder(input: $input) {
+      id
+      number
+    }
+  }
+`);
+
+function CreateOrderButton() {
+  const toast = useToast();
+  const [{ fetching }, createOrder] = useMutation(CreateOrderMutation);
+
+  const handleSubmit = async (input: CreateOrderInput) => {
+    const result = await createOrder({ input });
+    if (result.error) {
+      toast.error(`Failed to create order: ${result.error.message}`);
+      return;
+    }
+    toast.success(`Order ${result.data!.createOrder.number} created`);
+  };
+  // ...
+}
+```
+
+### `additionalTypenames`
+
+When a mutation creates/updates/deletes an entity that another query already has cached, urql won't know to refetch unless you pass `additionalTypenames`. Use it on **both** the query and the mutation when they share a typename:
+
+```tsx
+// Query side — declares it cares about the Order typename
+const [{ data }] = useQuery({
+  query: OrdersQuery,
+  variables: { first: 25 },
+  context: { additionalTypenames: ["Order"] },
+});
+
+// Mutation side — declares it produces Order writes
+const [, createOrder] = useMutation(CreateOrderMutation);
+await createOrder(
+  { input },
+  { additionalTypenames: ["Order"] }, // triggers refetch of any query subscribed to 'Order'
+);
+```
+
+Skip `additionalTypenames` only when the mutation's return type already includes the affected entity _and_ every cached query for it touched the same `id` — urql will then refresh by id. When in doubt, add it.
+
+### Optimistic updates
+
+Use sparingly — only for actions that:
+
+1. Are reversible (rollback is cheap on error)
+2. The user expects to feel instant (toggling a flag, reordering a list)
+
+Prefer plain pending-state UI (button spinner) for everything else. See `interaction/toast.md` and `interaction/confirm.md` for feedback patterns.
+
+## Page conventions
+
+Every page component:
+
+1. Is the **default export** of `page.tsx` (or `index.tsx` depending on routing convention — match siblings in `src/pages/`).
+2. Sets `appShellPageProps` with at least `meta.title`:
+
+   ```tsx
+   export default function OrdersListPage() {
+     /* ... */
+   }
+   OrdersListPage.appShellPageProps = {
+     meta: { title: "Orders" },
+   };
+   ```
+
+3. Uses `appShellPageProps.guards` for permission gates and `appShellPageProps.loader` for route loaders. See [project-setup.md](project-setup.md).
+
+## Quick reference
+
+| Concern                                        | Answer                                                                                                        |
+| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------- |
+| Where do generated types come from?            | `@/graphql` barrel, populated by `pnpm generate`                                                              |
+| How do I add a field to a card?                | Add it to the component's fragment, not the page query                                                        |
+| Why isn't my list refreshing after a mutation? | Add `additionalTypenames: ['<Type>']` on both query and mutation                                              |
+| Connection vs array?                           | Always connection (`edges { node }`) for built-in `<entities>` queries; check the schema for custom resolvers |
+| Pagination / sort / toolbar filters together?  | `useCollectionVariables` + `DataTable`; see § **Wiring to `DataTable`** above                                 |
+| Where's the urql client configured?            | `App.tsx` — see `project-setup.md`                                                                            |