themelia-ui 3.0.0 → 3.2.0

package/.agents/skills/themelia-ui/references/migration.md

@@ -3,6 +3,154 @@
 What changes between versions, what to do when you upgrade, and which changes a stable major
 allows.
 
+## Upgrading to 3.2
+
+3.2 adds consumer diagnostics, complete reference workflows and optional `scopeKey` support
+for asynchronous combobox lookups, alongside responsive grid, dialog and navigation fixes.
+Applications already on 3.1 need no new codemod replacements. Applications upgrading from
+3.0 or earlier must also follow [Upgrading to 3.1](#upgrading-to-31).
+
+After updating the package, refresh the installed consumer skill with the
+[packaged installer](verification.md#offline-diagnosis-and-skill-freshness). Review any
+local edits before replacing them, then run the read-only diagnostics and your application's
+type, build and interaction checks. The [structural guide](structure-and-spacing.md),
+[blocks guide](blocks.md) and [complete workflows](reference-workflows.md) describe the
+public composition contracts.
+
+For lookups whose results depend on a workspace, tenant or similar context, pass a stable
+`scopeKey` that changes with that context. The lookup aborts and invalidates old responses;
+the application still owns clearing a selection or query that is no longer valid. See the
+[scoped resource selection workflow](reference-workflows.md).
+
+## Upgrading to 3.1
+
+3.1 renames and removes public API as well as adding to it. Upgrade deliberately, not
+through a caret range: pin `themelia-ui` to `~3.0.0` until you have run the codemod and fixed
+what TypeScript reports.
+
+**Blocks are published under `blocks/`.** The tier the documentation, the component index
+and the finder call Blocks now has subpaths that say so:
+
+| was | is |
+| --- | --- |
+| `themelia-ui/patterns/analytics` | `themelia-ui/blocks/analytics` |
+| `themelia-ui/patterns/onboarding` | `themelia-ui/blocks/onboarding` |
+| `themelia-ui/patterns/timelines` | `themelia-ui/blocks/timelines` |
+| `themelia-ui/admin/patterns/access` | `themelia-ui/blocks/admin/access` |
+| `themelia-ui/admin/patterns/commerce` | `themelia-ui/blocks/admin/commerce` |
+
+Module stylesheet subpaths are removed. Importing a component in a bundled app brings its CSS.
+
+**Components bring their own CSS.** In a bundled app, importing a component now brings its
+stylesheet, once, and a module you never import brings none. To upgrade:
+
+1. Run the codemod over each directory that holds application code: `src/`, and `app/` or
+   `.storybook/` where you have them.
+   It removes JavaScript imports of `themelia-ui/style.css` and of module stylesheets, which would
+   now load the CSS twice.
+2. The codemod removes obsolete module CSS `@import`s. Review any remaining stylesheet
+   references it reports. With Tailwind, keep `@import "tailwindcss"` and the bridge, and drop
+   `@import "themelia-ui/style.css"` or `@import "themelia-ui/core.css"` from the Tailwind entry.
+3. If the application renders on the server with Vite (Astro, React Router, TanStack Start, Vike),
+   list `themelia-ui`, and any installed package that imports it, in `ssr.noExternal`; Astro
+   renders the kit unstyled without it. See
+   [Server rendering with Vite](installation.md#server-rendering-with-vite).
+4. If your bundler config sets its own resolve conditions, keep `module` in them.
+5. Pages that link stylesheets without a bundler link `style.css`.
+
+**Fill style is `appearance`.** `tone` is colour, `appearance` is fill and `variant` is
+structure, on every component. TypeScript reports each rename:
+
+| was | is |
+| --- | --- |
+| `buttonStyle` on a Button, a Button-like component or an action definition | `appearance` |
+| `ButtonStyle`, `ActionButtonStyle` | `ButtonAppearance`, `ActionAppearance` |
+| `defaults: { button: { buttonStyle } }` | `defaults: { button: { appearance } }` |
+| `variant` on `Badge`, `Toggle` and `SidebarMenuButton` | `appearance` |
+| `BadgeVariant` | `BadgeAppearance` |
+| `badgeVariants({ tone, variant })` on your own element | `<Badge tone appearance render={<a … />}>` |
+| `badgeVariant` on a metadata badge value | `badgeAppearance` |
+| `confirmStyle` on an overlay or an action modality | `confirmAppearance` |
+
+Button renders `data-appearance` instead of `data-style`, and Toggle `data-appearance`
+instead of `data-variant`: update CSS that selects either.
+
+**Two steps for every size.** A size, padding or gap prop offers `default` and `sm`. `md` is
+`default`, which is also what leaving the prop out gives you; a step larger than the default
+is gone. The gaps map like this:
+
+| was | is |
+| --- | --- |
+| `gap="2xs"`, `"xs"`, `"sm"`, `"md"` | `gap="sm"` (8px) |
+| `gap="lg"`, `"xl"`, `"2xl"` | `gap="default"` (16px), or no `gap` |
+| no `gap` on a `Stack` or `Split` (8px) | 16px; write `gap="sm"` to keep 8px |
+
+Widths take `default`, `sm`, `full`, `none` or a CSS length such as `"48rem"`, and a free
+string no longer type-checks. `Slider` and `SliderField` lose `size`, `InputGroupButton`
+takes `iconOnly` instead of its icon sizes, and an action modality's `size`, which nothing
+read, is gone.
+
+**`density` belongs to the provider.** `MetadataList density="compact"` becomes
+`size="sm"`, `MediaLibrary density="compact"` becomes `size="sm"`, `ActivityFeed density`
+becomes `variant`, and `AiTask density="expanded"` becomes `defaultExpanded`. CSS that
+selects `[data-row-density]`, `[data-media-density]` or `[data-activity-density]` selects
+`[data-size]` or `[data-variant]`.
+
+`Text` drops `size="xxs"` and `weight="regular"`: write `xs` and `normal`.
+
+**The theme is one level.** It is about eighty variables, declared once at `:root`, each
+colour a `light-dark(light, dark)` pair. For a theme of your own:
+
+- Declare it on `:root` alone. The selector list 3.0 asked for (`:root, [data-ui-scope],
+  [data-density], [data-theme], .light, .dark`) is not needed: component styles inherit the
+  root defaults. Explicit regional overrides and density presets replace their corresponding
+  inherited values; set a preset-specific spacing override on that preset.
+- Write a dark value into the colour's pair, `--primary: light-dark(#2563eb, #60a5fa)`, rather
+  than a `.dark { … }` block, which colours a dark page but misses a dark region inside a light
+  one.
+- The palette, the alpha steps, the spacing ladder, the control, icon and avatar ladders, the
+  derived role variables and the scale factors are gone. The codemod renames a variable that
+  has a successor and reports the rest:
+
+| was | is |
+| --- | --- |
+| `--space-2xs` to `--space-md` | `--gap-sm` between things, `--padding-sm` for an inset |
+| `--space-lg` to `--space-2xl` | `--gap` between things, `--padding` for an inset |
+| `--surface-px`, `--surface-py`; `--row-px`, `--row-py` | `--padding`; `--padding-sm` |
+| `--control-h`, `--control-h-sm` | `--control-height`, `--control-height-sm` |
+| `--size-icon`, `--size-icon-sm` | `--icon-size`, `--icon-size-sm` |
+| `--primary-10` and every other alpha step | `color-mix(in oklab, var(--primary) var(--tint), transparent)`; a line takes `--tint-strong` |
+| `--accent-50`, `--border-60`, `--muted-50` | `--accent`, `--border`, `--muted` |
+| `--control-border`, `--focus-ring-color`, `--link-color` | `--input`, `--ring`, `--link` |
+| `--shadow-xs`, `--shadow-sm`; `--shadow-md` to `--shadow-2xl`, `--popover-shadow` | `--shadow`; `--shadow-lg` |
+| `--duration-normal`, `--duration-instant`, `--ease-out` | `--duration`, `--duration-fast`, `--ease` |
+| `--leading-*`, `--weight-*`, `--tracking-*` | Text's `lineHeight`, `weight` and `caps` |
+| `--scale`, `--density-scale` | the provider's `scale` and `density` |
+| `--inverse-*` | a nested provider with `colorScheme: "dark"` |
+| `--animate-spin` and the other `--animate-*` | `--keyframes-spin` and the others, which hold the name alone: `animation: var(--keyframes-spin) 1s linear infinite` |
+
+`--text-scale` stays, and Text multiplies each step by it. A component variable you set from
+outside, such as `--content-block-p`, `--overlay-region-p`, `--field-label-width` or
+`--chart-aspect`, is the component's own now: set the theme variable it reads, or style the
+component through `className`. With Tailwind, `p-padding` and `gap-gap-sm` replace `p-md` and
+the other spacing keys, and `rounded` is the container radius.
+
+**A browser floor for `light-dark()`.** Safari 17.5 or newer; Chrome and Edge 125 and Firefox
+121 are unchanged.
+
+Run the codemod from your project over each directory that holds application code, dry
+first; the commands below show `src/`. It rewrites the moved subpaths, removes the
+stylesheet imports components now bring, renames each theme variable that has a successor,
+and reports the rest:
+
+```sh
+node node_modules/themelia-ui/scripts/consumer/codemod.mjs --dry-run src/
+node node_modules/themelia-ui/scripts/consumer/codemod.mjs src/
+```
+
+Every change with its replacement is listed in the
+migration reference (`node_modules/themelia-ui/docs/generated/migration.md`).
+
 ## Upgrading to 3.0
 
 3.0 changes how the package loads, and gives a few props one shape.
@@ -16,6 +164,9 @@ the package as it is. Server rendering and test runners need no configuration fo
 CommonJS code on Node 20.19 or later can `require()` it. Jest still needs the package
 exempted in `transformIgnorePatterns`.
 
+From 3.1, components bring their own CSS again, and server rendering with Vite lists the
+package in `ssr.noExternal`; see [Upgrading to 3.1](#upgrading-to-31).
+
 TypeScript flags the rest:
 
 - `Scope` takes `render` instead of `as`: `<Scope vars={vars} render={<section />}>`.
@@ -201,14 +352,14 @@ Every change is one of:
 - **additive**: a new export, a new optional prop
 - **documentation-only**: no runtime or type change
 - **behaviour-preserving internal**: a refactor whose observable behaviour is identical
-- **deprecation**: the old name still works, and says what replaces it
+- **deprecation**: an old name still works while a replacement is available
 - **breaking**: anything else
 
-## Within a stable major
+## Upgrade policy
 
-An alias introduced during a stable major is deprecated in that major, documented with its
-replacement, and removed only in the next one. It stays for one full stable major unless
-security or correctness makes keeping it unsafe.
+3.1 removes obsolete aliases and adapters without retaining them for another release. Pin the
+installed version until the application is ready to apply the migration guide, type-check and
+build. Breaking changes are recorded before the API snapshot is updated.
 
 ## Import paths
 

package/.agents/skills/themelia-ui/references/provider-and-scoping.md

@@ -1,5 +1,11 @@
 # Provider and scoping
 
+Choose one document density owner, then use UIScope for a deliberately different region.
+Changing density changes spacing; keep primary copy in Text and headings in Heading or their
+component owners. Check the last field/next heading together: CardContent, FormSection and
+Stack can each contribute separation. A portal must stay inside its intended token scope;
+UIPortalHost provides that boundary. Test open popups as well as the page beneath them.
+
 Three components, and the difference between them is what they are allowed to touch.
 
 | | Renders | Reaches | Use for |
@@ -65,43 +71,40 @@ below a slice as well as at it:
 </UIProvider>
 ```
 
-This applies to every record-shaped field: `theme.colors`, `theme.palette`, `theme.vars`,
-`typography.fonts`, `typography.sizes` and `motion.durations`. Below them a record is a flat
-map of token to value, and a value is replaced, not merged.
+This applies to every record-shaped field: `theme.colors`, `theme.vars`, `typography.fonts`,
+`typography.sizes` and `motion.durations`. Below them a record is a flat map of variable to
+value, and a value is replaced, not merged.
 
 That is the configuration components read, and the CSS follows it: each scope writes the
 merged overrides on its element, so inside the nested scope above `--primary` is red and
-`--secondary` is green. Raw inputs (palette steps, radii, fonts, durations and the scale
-factors) inherit through every boundary. Semantic colours and type sizes do not: a `Scope`,
-or any other element on the boundary list, declares them again from the palette. To keep a
-colour across one of those, set it through `theme.palette` or declare it at the boundary
-list; see [Theming](theming.md#setting-a-theme).
+`--secondary` is green. Component styles inherit global tokens rather than redeclaring
+theme defaults. Explicit Scope/UIScope overrides replace inherited values; a density preset
+also resets its spacing and control heights on that region. A value outside that boundary
+does not override its local declaration; see
+[Theming](theming.md#setting-a-theme).
 
 ## Scope — tokens only
 
-Overriding a factor requires a **scope boundary**, not just any element:
+`Scope` sets theme variables on a region, without the config machinery:
 
 ```tsx fragment — shape only, not a program
-<Scope vars={{ "--density-scale": 0.8 }}>
+<Scope vars={{ "--control-height": "2.5rem" }}>
   <Toolbar />
 </Scope>
 ```
 
-`Scope` renders a `div` without layout. `render` picks another element, as on every
-component (`render={<section />}`), and `transparent={false}` gives it a box.
-
-Derived tokens are declared at `:root, [data-ui-scope], [data-density], [data-theme], .light,
-.dark` (see `src/styles/SCOPES.md` (`node_modules/themelia-ui/src/styles/SCOPES.md`)). A plain
-`<div style={{ "--density-scale": 0.8 }}>` sets the variable and nothing reads it: the
-measurements above it already resolved against the old value. `Scope` renders
-`data-ui-scope`, which puts the element on that list and makes every derived token
-re-compute.
+`Scope` renders a `div` without layout. Its `render` prop picks another element
+(`render={<section />}`), and `transparent={false}` gives it a box. Every
+component inside reads the variables it sets, because components compute from the theme where
+they use it; any element with a `style` does the same, and `Scope` only adds the missing
+layout rule and the `data-ui-scope` marker.
 
 ## Portals and scopes
 
-A scope works through CSS custom properties and the `[data-density]` / `[data-theme]`
-attribute selectors, and both inherit down the DOM subtree. A portal renders elsewhere in the
-document, so by default neither follows it:
+A scope uses CSS custom properties; its `data-density` and `data-theme` attributes establish
+spacing and colour-scheme values that inherit through the DOM subtree. The attributes
+themselves are not copied to descendants. A portal renders elsewhere in the document, so
+those inherited values do not follow it by default:
 
 ```tsx fragment — a template with a hole in it
 <UIScope config={{ density: "compact" }}>
@@ -142,7 +145,7 @@ in — a shadow root, or a positioned overlay element it manages itself.
 
 ## Strict Content Security Policy
 
-Some Base UI-backed controls emit a tiny inline style or pre-hydration script for behavior
+Some Base UI-backed controls emit a tiny inline style element or pre-hydration script for behavior
 the component stylesheet cannot express. Put `CSPProvider` at the same application boundary
 as `UIRoot` and pass the request nonce through:
 
@@ -160,7 +163,7 @@ React 19 hoists styles that carry `precedence`. During streaming SSR, configure
 renderer with the same style nonce as the provider; otherwise React omits the attribute and
 warns about the mismatch.
 
-When the policy permits no inline elements at all, suppress Base UI's style elements and
+When the policy forbids inline style elements, suppress Base UI's style elements and
 ship the scrollbar rule in the consuming application's stylesheet:
 
 ```tsx fragment — App comes from the consuming application
@@ -175,7 +178,16 @@ ship the scrollbar rule in the consuming application's stylesheet:
 ```
 
 `disableStyleElements` does not disable kit behavior; it moves those small rules into the
-consuming app. It does not replace the normal `core.css`, module stylesheet, or `style.css` import.
+consuming app. It does not change how the kit's CSS loads.
+
+This option does not remove inline scripts or `style` attributes. A nonce authorizes the
+matching style/script elements; it does not authorize style attributes in server-rendered
+HTML. Providers, responsive structure and popup positioning can use style attributes, so
+a policy that blocks them needs a separate SSR strategy for the adopted components.
+Inspect the rendered HTML and browser CSP reports; `disableStyleElements` alone does not
+establish compatibility with that policy. See the
+[Base UI CSP reference](https://base-ui.com/react/utils/csp-provider#inline-style-attributes)
+for the distinction and available integration strategies.
 
 ## Reading the config
 

package/.agents/skills/themelia-ui/references/reference-workflows.md

@@ -0,0 +1,43 @@
+# Complete reference workflows
+
+These sources use public package imports and fixed local mock operations. Copy the complete
+workflow directory, including relative helpers, then replace its transport and policy with
+your application's. The versioned inventory (`node_modules/themelia-ui/docs/generated/workflows/index.json`) lists every
+file, import and API reference. Its package version must match the installed package.
+
+| Workflow | Owners and application seam | Complete entry source |
+| --- | --- | --- |
+| Record detail | Page owns route heading; sibling Cards own subjects; MetadataList owns facts; app owns record commands | Record detail (`node_modules/themelia-ui/docs/generated/workflows/record-detail/page-layout/record-detail-reference.tsx`) |
+| Server resource index | DataView owns browser presentation; app owns server matching, unknown totals, cursor and page selection | Resource index (`node_modules/themelia-ui/docs/generated/workflows/resource-index/data-view/resource-index-reference.tsx`) |
+| Multi-section form | Card owns surface; flat FormSections retain insets; FieldGroup and FormField own names; app owns validation and completion | Form (`node_modules/themelia-ui/docs/generated/workflows/multi-section-form/form-workflow/multi-section-reference.tsx`) |
+| Scoped resource selection | ResourceCombobox owns lookup; app owns scopeKey and selection validity; Overlay owns task | Selector (`node_modules/themelia-ui/docs/generated/workflows/scoped-resource-selection/combobox/scoped-resource-reference.tsx`) |
+| Nested action flow | Parent owns draft; child owns confirmation; app closes explicitly after successful mutation | Nested action (`node_modules/themelia-ui/docs/generated/workflows/nested-action-flow/action-overlays/nested-action-reference.tsx`) |
+| Workspace navigation | Shell owns geometry; workspace owns disclosure; app owns router and same-app policy | Workspace (`node_modules/themelia-ui/docs/generated/workflows/workspace-navigation/app-shell/workspace-navigation-reference.tsx`) |
+| Media picking | MediaLibraryDialog owns query/picking UI; app commits a separate picker draft on confirmation, pages through footer slots, hydrates saved ids independently, reports unavailable selection and authorizes fetches | Media (`node_modules/themelia-ui/docs/generated/workflows/media-picking/media-library/media-picking-reference.tsx`) |
+| Communications overview | MetricGrid owns quantities; MetadataList owns prose facts; app owns period, delivery state and retry | Communications (`node_modules/themelia-ui/docs/generated/workflows/communications-overview/analytics/communications-reference.tsx`) |
+| Website editor | RichTextEditor owns editing; app retains locale drafts and alt text; RichText sanitizes preview | Website editor (`node_modules/themelia-ui/docs/generated/workflows/website-content-editor/rich-text-editor/website-content-reference.tsx`) |
+
+Forms using plain state need no form peer. The optional forms-rhf adapter connects existing
+React Hook Form state without duplicating it. The resource-index workflow uses features/table and
+needs its table peer; record-detail uses peer-free base/table; analytics and rich editing require the peers listed in their generated
+API pages. The general reference consumer stays free of optional peers; the admin reference
+consumer demonstrates adopted adapters.
+
+Pending, empty, failed refresh, unavailable selection and resolved validation errors are
+different states. These fixtures demonstrate local feedback and retained drafts. They do
+not establish real persistence, permissions, cache invalidation or backend sanitization.
+Exercise the named cases in your app; [record the evidence](verification.md#completion-record)
+and identify conditions you could not inspect.
+
+The inventory's `verification` entries map required cases to behavioral tests or visual
+inspection conditions. They specify coverage to run, not a claim that your application passed.
+`repositoryFile` identifies a maintainer test in the source repository; copy workflow files
+from the inventory's generated source list and adapt the named behaviors to your test runner.
+The browser cases use explicit mock actions; the read-only observer supplies advisory geometry
+findings. Review screenshots and semantics separately in both themes and densities at mobile,
+desktop and wide widths, including long copy and RTL. Build/type checks prove the complete
+sources and public imports; rich-text security tests exercise the sanitization boundary.
+
+When embedding a contained app shell in an existing main landmark, use `contentRender={<div />}`
+so the composition keeps one main. For a shell that owns the application's main, omit that
+override. The reference uses the embedded form because it also appears inside a documentation page.

package/.agents/skills/themelia-ui/references/structure-and-spacing.md

@@ -0,0 +1,147 @@
+# Structure and spacing
+
+Choose the semantic owner first, then arrange its siblings. A Page owns route geometry;
+Card owns an independent subject; ContentBlock owns supporting content; FormSection owns
+an editable region. Stack and Grid arrange those owners without adding a heading, landmark,
+surface or inset. See [Composition](composition.md#decide-the-owners-before-jsx) for names,
+commands and field ownership, and [Blocks](blocks.md) for ready subject arrangements.
+
+## Choose a structural block
+
+| Need | Public owner | What it supplies |
+| --- | --- | --- |
+| Route title, description and commands | `Page` from `layout/page` | Container, page header and body rhythm. It does not create a main landmark or own scrolling. |
+| Page scroll inside a bounded shell | `PageViewport` from `layout/containers` | Scroll region and an inline-size query container. Focusable by default for keyboard scrolling. |
+| Centred width and inline gutter | `Container` from `layout/containers` | Width and gutter only. Page already includes it. |
+| Semantic section with rhythm between groups | `Section` from `layout/containers` | A native section and twice the group gap; supply its heading or accessible name. |
+| Primary work beside a secondary summary | `TwoColumnLayout` from `layout/containers` | Main/aside arrangement, optional full-width header/footer; stacks below `lg`. Aside stays second in the DOM. |
+| One row or column of passive siblings | `Stack` from `base/structure` | Direction, gap, alignment, distribution and optional wrapping. No padding prop. |
+| An explicit column count | `Grid` and `GridCell` from `base/structure` | One to four columns, responsive gaps and cell spans. |
+| As many equal columns as fit | `AdaptiveGrid` from `base/structure` | Auto-fit tracks; `minColumnWidth` is `default` (16rem), `sm` (12rem) or a CSS length. |
+| A fluid main region and a constrained rail | `Split` from `base/structure` | Two direct children: main first, side second. `sideWidth` defaults to 18rem; `collapseBelow` defaults to `md`. |
+| Intentional edge-to-edge content in an inset | `Bleed` from `base/structure` | Negative margins on the selected axis. Match `amount` to the inset it cancels. |
+
+Read the exact structure API (`node_modules/themelia-ui/docs/generated/components/base--structure.md`),
+containers API (`node_modules/themelia-ui/docs/generated/components/layout--containers.md`) and
+page API (`node_modules/themelia-ui/docs/generated/components/layout--page.md`) before adding props. Container's
+`maxWidth` (`sm`, `md`, `lg`, `xl`, `2xl`, `full`) and `gutter` (`none`, `sm`, `md`, `lg`)
+are a different contract from Stack/Grid widths (`default`, `sm`, `full`, `none` or a CSS
+length). Container gutters are zero, one, one-and-a-half or twice `--padding`; they do not
+add spacing tokens. Stack/Grid `maxWidth` caps width without centring it or adding a gutter.
+
+An app shell normally owns the single main landmark and page scroller. Do not add another
+PageViewport around each section. For document scrolling without a bounded shell, Page can
+live in the application's existing main. When embedding a shell inside another main, use
+its documented `contentRender` seam; see [complete workflows](reference-workflows.md).
+
+## Use the two spacing roles
+
+| Role | Public tokens | Typical use |
+| --- | --- | --- |
+| Container inset | `--padding` | Card regions and decorated ContentBlocks |
+| Item inset | `--padding-sm` | Rows, cells and compact items |
+| Between groups | `--gap`, `gap="default"` | Fields, sibling Cards, sections |
+| Within a group | `--gap-sm`, `gap="sm"` | Title/description, icon/label, toolbar controls |
+
+The omitted structure gap is `default`. `gap="none"` removes separation; it is not a third
+spacing step. Insets belong to the child surface and gaps to the parent arrangement. Avoid
+giving both the same separation job. Density changes these lengths together; it does not
+choose smaller text roles. [Theming](theming.md#scale-and-density) explains density, scale
+and typography scale, including overriding a preset's values.
+
+CardContent supplies its inset and a group gap between direct children; it drops its top
+padding after an undivided CardHeader. Card `surface="flat"` removes decoration and retains
+region insets. FormSection is a Card composition, so a flat FormSection inside CardContent
+still adds its own inset. Use `Stack gap="none"` between such sections when their insets
+already supply the intended rhythm; do not assume flat means flush.
+
+ContentBlock is different: its default `surface="plain"` supplies heading/content spacing
+without an inset or frame. Its `bordered`, `muted` and `card` surfaces add an inset.
+`flush` drops that decorated surface's inset for children that own their own padding.
+Neither flat nor flush changes field associations or heading semantics.
+
+```tsx compile
+import { Card } from "themelia-ui/base/cards"
+import { ContentBlock, MetadataList } from "themelia-ui/base/display"
+import { Grid, Stack } from "themelia-ui/base/structure"
+import { Text } from "themelia-ui/base/typography"
+import { Page } from "themelia-ui/layout/page"
+import { TwoColumnLayout } from "themelia-ui/layout/containers"
+
+export function AccountOverview() {
+  return <Page header={{ title: "Account" }} maxWidth="lg">
+    <TwoColumnLayout
+      main={<Stack>
+        <Grid columns={{ base: 1, md: 2 }}>
+          <Card title="Contact" titleLevel={2}>
+            <MetadataList items={[{ id: "email", label: "Email", value: "alex@example.com" }]} />
+          </Card>
+          <Card title="Billing" titleLevel={2}>
+            <MetadataList items={[{ id: "status", label: "Status", value: "Active" }]} />
+          </Card>
+        </Grid>
+        <Card title="Notes" titleLevel={2}>
+          <ContentBlock description="Context for the next account review.">
+            <Text>The customer prefers email updates.</Text>
+          </ContentBlock>
+        </Card>
+      </Stack>}
+      aside={<Card title="Summary" titleLevel={2}><Text>Review due next month.</Text></Card>}
+    />
+  </Page>
+}
+```
+
+The example has one route heading, three independent subjects in the main region and a
+secondary summary. Page supplies the gutter; TwoColumnLayout supplies main/aside separation;
+Stack/Grid separate subjects; each Card supplies its inset. The complete record and form
+workflows add application-owned commands, validation and asynchronous states.
+
+## Know which width drives responsiveness
+
+A responsive structure prop accepts a single value or an object such as
+`gap={{ base: "sm", md: "default" }}`. Values carry forward until another named step replaces
+them; omitted lower steps use the component's defaults. `sm` as a gap value means the small
+gap; `sm` as an object key means a breakpoint.
+
+| Step | Viewport minimum | Grid's nearest query-container minimum |
+| --- | --- | --- |
+| `base` | All widths | All widths |
+| `sm` | 40rem | 24rem |
+| `md` | 48rem | 32rem |
+| `lg` | 64rem | 40rem |
+| `xl` | 80rem | 52rem |
+| `2xl` | 96rem | 64rem |
+
+Grid uses viewport steps when no ancestor establishes inline-size containment. With a query
+container, such as PageViewport or ContentBlock, Grid's columns, gaps, alignment and maximum
+width use the nearest container and the smaller thresholds above. Grid does not create its
+own query container. Stack, Split, Bleed, AdaptiveGrid's responsive gap/alignment and
+GridCell spans use viewport steps. AdaptiveGrid's **column count** always follows available
+width through auto-fit. TwoColumnLayout stacks below the viewport's `lg` step.
+
+Grid defaults to one column and two from `md`; `columns={1}` stays one at every width.
+Use `GridCell span="full"` for a full row at every width. Numeric spans must fit the current
+column count; `span={{ base: 1, md: "full", xl: 2 }}` can switch between numeric and full
+placement. Coordinate responsive spans with the Grid, especially inside a query
+container where their thresholds differ. Prefer AdaptiveGrid when the available panel width
+should decide the count without coordinating breakpoints. Visual side positioning in Split
+or TwoColumnLayout does not change reading or keyboard order.
+
+## Bleed, custom CSS and verification
+
+Bleed's default amount is `none` and its default axis is `inline`. An intentional image
+escape can use `amount="default"` inside an inset of `--padding`, or `sm` inside
+`--padding-sm`. The shipped spacing pairs have matching padding/gap values; a custom theme
+that separates those values must account for the actual inset. Bleed does not create a
+surface or crop media. Check edges and focus visibility in the surrounding surface.
+
+Application-specific geometry can use `className` and CSS over public tokens; use the
+documented props first. Do not target private `--_…` variables or CSS Module hashes. Keep
+copy in Text/Heading and field labels in FormField rather than setting local type styles.
+For product CSS, prefer logical properties so inline start/end follow RTL.
+
+Check a narrow **parent** as well as a narrow viewport, long headings and translated labels,
+both themes and densities, and keyboard access to the scroller. Verify that additional
+surfaces or gaps serve an independent subject. [Consumer verification](verification.md)
+separates compiled examples, interaction evidence and visual inspection.