@mitcsutt/kiln-ui 0.2.0 → 0.2.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mitcsutt/kiln-ui",
-  "version": "0.2.0",
+  "version": "0.2.2",
   "description": "Kiln: a themeable React design system on Radix primitives, plain CSS and design tokens",
   "keywords": [
     "kiln",

package/skills/custom-theme/SKILL.md

@@ -24,7 +24,7 @@ A Kiln theme is one CSS file. It sets the tokens in the [contract](references/to
 ```tsx
 import { Box, Button, Heading, Inline, Stack, Text, ThemeScope } from '@mitcsutt/kiln-ui'
 
-export default function CustomTheme() {
+export function Usage() {
   return (
     <ThemeScope theme="harbour">
       <Box padding={6}>

package/skills/layout-composition/SKILL.md

@@ -7,18 +7,18 @@ metadata:
   library: "@mitcsutt/kiln-ui"
 sources:
   - mitcsutt/kiln:apps/docs/content/docs/ui/foundations/spacing.mdx
-  - mitcsutt/kiln:apps/docs/content/docs/ui/layout/stack.mdx
-  - mitcsutt/kiln:apps/docs/content/docs/ui/layout/inline.mdx
-  - mitcsutt/kiln:apps/docs/content/docs/ui/layout/grid.mdx
-  - mitcsutt/kiln:apps/docs/content/docs/ui/layout/split.mdx
-  - mitcsutt/kiln:apps/docs/content/docs/ui/layout/section.mdx
-  - mitcsutt/kiln:apps/docs/content/docs/ui/layout/container.mdx
-  - mitcsutt/kiln:apps/docs/content/docs/ui/layout/box.mdx
-  - mitcsutt/kiln:apps/docs/content/docs/ui/layout/app-shell.mdx
-  - mitcsutt/kiln:apps/docs/content/docs/ui/layout/action-bar.mdx
-  - mitcsutt/kiln:apps/docs/content/docs/ui/layout/divider.mdx
-  - mitcsutt/kiln:apps/docs/content/docs/ui/layout/aspect-ratio.mdx
-  - mitcsutt/kiln:apps/docs/content/docs/ui/layout/visually-hidden.mdx
+  - mitcsutt/kiln:packages/ui/src/components/layout/Stack/Stack.tsx
+  - mitcsutt/kiln:packages/ui/src/components/layout/Inline/Inline.tsx
+  - mitcsutt/kiln:packages/ui/src/components/layout/Grid/Grid.tsx
+  - mitcsutt/kiln:packages/ui/src/components/layout/Split/Split.tsx
+  - mitcsutt/kiln:packages/ui/src/components/layout/Section/Section.tsx
+  - mitcsutt/kiln:packages/ui/src/components/layout/Container/Container.tsx
+  - mitcsutt/kiln:packages/ui/src/components/layout/Box/Box.tsx
+  - mitcsutt/kiln:packages/ui/src/components/layout/AppShell/AppShell.tsx
+  - mitcsutt/kiln:packages/ui/src/components/layout/ActionBar/ActionBar.tsx
+  - mitcsutt/kiln:packages/ui/src/components/layout/Divider/Divider.tsx
+  - mitcsutt/kiln:packages/ui/src/components/layout/AspectRatio/AspectRatio.tsx
+  - mitcsutt/kiln:packages/ui/src/components/layout/VisuallyHidden/VisuallyHidden.tsx
   - mitcsutt/kiln:apps/docs/content/docs/ui/patterns/dashboard.mdx
   - mitcsutt/kiln:apps/docs/content/docs/ui/patterns/settings.mdx
   - mitcsutt/kiln:apps/docs/content/docs/ui/patterns/checkout.mdx
@@ -50,7 +50,7 @@ Vary the rhythm. Adjacent sections shouldn't share a `space` step, and a page us
 ```tsx
 import { Button, Inline, Stack, Text, TextField } from '@mitcsutt/kiln-ui'
 
-export default function Density() {
+export function Density() {
   return (
     <Inline gap={7} align="start">
       {(['compact', undefined, 'comfortable'] as const).map((density) => (
@@ -96,7 +96,7 @@ import { Box, Grid, Text } from '@mitcsutt/kiln-ui'
 
 const STOPS = ['Harbour', 'Northpoint', 'Kelso Bay', 'Ferry Lane', 'Old Quay', 'Marram Point']
 
-export default function ResponsiveProps() {
+export function ResponsiveProps() {
   return (
     <Grid columns={{ base: 1, sm: 2, lg: 3 }} gap={{ base: 3, md: 5 }}>
       {STOPS.map((stop) => (
@@ -121,10 +121,12 @@ A column of things with consistent space between them. The layout you'll reach f
 
 `Stack` lays its children out vertically with a gap from the space scale. Most screens are stacks of stacks, so most spacing in a Kiln app is a `gap` prop rather than a margin.
 
+`align` sets the cross-axis alignment (`stretch` by default, so children fill the width). Use `align="start"` when a child like a button should keep its own width.
+
 ```tsx
 import { Button, Heading, Stack, Text } from '@mitcsutt/kiln-ui'
 
-export default function Usage() {
+export function Usage() {
   return (
     <Stack gap={4} align="start">
       <Heading level={3} size="xl">
@@ -137,8 +139,6 @@ export default function Usage() {
 }
 ```
 
-`align` sets the cross-axis alignment (`stretch` by default, so children fill the width). Use `align="start"` when a child like a button should keep its own width.
-
 ### Rules between items
 
 `dividers` draws a hairline between every child, centred in the gap. It's usually better than a card per item: lists, settings rows and timelines read as one document.
@@ -152,7 +152,7 @@ const STOPS = [
   { name: 'Kelso Bay Pier', time: '23:31' },
 ]
 
-export default function Dividers() {
+export function Dividers() {
   return (
     <Stack gap={{ base: 3, md: 4 }} dividers>
       {STOPS.map((stop) => (
@@ -180,8 +180,8 @@ export default function Dividers() {
 | --- | --- | --- | --- |
 | `gap` | `Responsive<Space>` |  | Space between children, as a step on the theme's space scale. Responsive. |
 | `align` | `Responsive<Align>` | `stretch` | Cross-axis alignment. Responsive. Default `stretch`. |
-| `dividers` | `boolean` |  | Draw a hairline rule between children (the rule sits in the middle of the gap). |
-| `as` | `'div' \| 'section' \| 'article' \| 'aside' \| 'header' \| 'footer' \| 'main' \| 'nav' \| 'ul' \| 'ol' \| 'li' \| 'form' \| 'fieldset'` |  | Render as a different element. Lists get `role="list"` semantics preserved. |
+| `dividers` | `boolean` | `false` | Draw a hairline rule between children (the rule sits in the middle of the gap). |
+| `as` | `'div' \| 'section' \| 'article' \| 'aside' \| 'header' \| 'footer' \| 'main' \| 'nav' \| 'ul' \| 'ol' \| 'li' \| 'form' \| 'fieldset'` | `div` | Render as a different element. Lists get `role="list"` semantics preserved. |
 | `hideBelow` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide below this breakpoint (e.g. `md` → hidden on phones, shown from 48em). |
 | `hideAbove` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide from this breakpoint up (e.g. `md` → shown on phones only). |
 
@@ -193,10 +193,12 @@ Things in a row that wrap when they run out of room. Button rows, tag lists, too
 
 `Inline` lays its children out horizontally with a gap, vertically centred, wrapping onto new lines when they don't fit.
 
+`justify` spreads the row (`between` pushes the groups to either end) and takes responsive values, so a header can stack its groups on a phone and spread them from `md` up. `wrap={false}` keeps everything on one line; children then shrink instead. `rowGap` sets the space between wrapped lines when it should differ from `gap`.
+
 ```tsx
 import { Badge, Button, Inline, Text } from '@mitcsutt/kiln-ui'
 
-export default function Usage() {
+export function Usage() {
   return (
     <Inline gap={3} justify={{ base: 'start', md: 'between' }}>
       <Inline gap={2}>
@@ -214,8 +216,6 @@ export default function Usage() {
 }
 ```
 
-`justify` spreads the row (`between` pushes the groups to either end) and takes responsive values, so a header can stack its groups on a phone and spread them from `md` up. `wrap={false}` keeps everything on one line; children then shrink instead. `rowGap` sets the space between wrapped lines when it should differ from `gap`.
-
 ### API
 
 `InlineProps`:
@@ -227,7 +227,7 @@ export default function Usage() {
 | `align` | `Responsive<Align>` | `center` | Cross-axis alignment. Default `center`. Responsive. |
 | `justify` | `Responsive<Justify>` | `start` | Main-axis distribution. Default `start`. Responsive. |
 | `wrap` | `boolean` | `true` | Wrap onto new lines. Default `true`. |
-| `as` | `'div' \| 'header' \| 'footer' \| 'nav' \| 'ul' \| 'ol' \| 'li' \| 'span' \| 'p'` |  |  |
+| `as` | `'div' \| 'header' \| 'footer' \| 'nav' \| 'ul' \| 'ol' \| 'li' \| 'span' \| 'p'` | `div` |  |
 | `hideBelow` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide below this breakpoint (e.g. `md` → hidden on phones, shown from 48em). |
 | `hideAbove` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide from this breakpoint up (e.g. `md` → shown on phones only). |
 
@@ -239,12 +239,14 @@ Two-dimensional layout, either with a column count per breakpoint or as an auto-
 
 `Grid` has two modes. With `columns`, you choose how many equal columns there are, per breakpoint. With `minItemWidth`, the grid fits as many columns as there's room for, each at least that wide, so it adapts to its container without a single breakpoint.
 
+One column on a phone, two from `sm` and four from `lg`.
+
 ```tsx
 import { Box, Grid, Text } from '@mitcsutt/kiln-ui'
 
 const LINES = ['Red', 'Harbour', 'Coastal', 'Night', 'Airport', 'Orbital', 'Market', 'University']
 
-export default function Columns() {
+export function Columns() {
   return (
     <Grid columns={{ base: 1, sm: 2, lg: 4 }} gap={4}>
       {LINES.map((line) => (
@@ -266,7 +268,7 @@ import { Box, Grid, Text } from '@mitcsutt/kiln-ui'
 
 const PIERS = ['North pier', 'South pier', 'Ferry terminal', 'Lifeboat station', 'Fish market']
 
-export default function AutoFill() {
+export function AutoFill() {
   return (
     <Grid minItemWidth="xs" gap={4}>
       {PIERS.map((pier) => (
@@ -286,7 +288,7 @@ export default function AutoFill() {
 ```tsx
 import { Box, Grid, Text } from '@mitcsutt/kiln-ui'
 
-export default function Items() {
+export function Items() {
   return (
     <Grid columns={{ base: 1, md: 3 }} gap={4}>
       <Grid.Item span={{ base: 1, md: 2 }}>
@@ -318,7 +320,7 @@ export default function Items() {
 | `gap` | `Responsive<Space>` |  | Space between cells (both axes). Responsive. |
 | `rowGap` | `Responsive<Space>` |  | Row gap, if different from `gap`. Responsive. |
 | `align` | `Responsive<Align>` | `stretch` | Cell alignment on the block axis. Default `stretch`. Responsive. |
-| `as` | `'div' \| 'section' \| 'ul' \| 'ol' \| 'dl'` |  |  |
+| `as` | `'div' \| 'section' \| 'ul' \| 'ol' \| 'dl'` | `div` |  |
 | `hideBelow` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide below this breakpoint (e.g. `md` → hidden on phones, shown from 48em). |
 | `hideAbove` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide from this breakpoint up (e.g. `md` → shown on phones only). |
 
@@ -348,6 +350,8 @@ An asymmetric two-column layout that stacks on small screens. A heading beside i
 
 `Split` takes exactly two children and puts them side by side in a ratio. Asymmetric splits read as designed; a 50/50 split of a heading and a list rarely does. Below `collapseBelow` (`md` by default) the two stack, first child on top.
 
+A heading and a list of changes in a 5/7 split, stacked on a phone.
+
 ```tsx
 import { Heading, Split, Stack, Text } from '@mitcsutt/kiln-ui'
 
@@ -357,7 +361,7 @@ const CHANGES = [
   'Kelso Bay Pier reopens on 3 November.',
 ]
 
-export default function Usage() {
+export function Usage() {
   return (
     <Split ratio="5/7" gap={{ base: 5, md: 7 }}>
       <Heading level={3} size="2xl">
@@ -380,7 +384,7 @@ export default function Usage() {
 ```tsx
 import { Box, Split, Stack, Text } from '@mitcsutt/kiln-ui'
 
-export default function Ratios() {
+export function Ratios() {
   return (
     <Stack gap={4}>
       {(['1/1', '1/2', '1/3', '5/7'] as const).map((ratio) => (
@@ -410,82 +414,17 @@ export default function Ratios() {
 | `collapseBelow` | `'sm' \| 'md' \| 'lg'` | `md` | Stack the two children vertically below this breakpoint. Default `md`. |
 | `gap` | `Responsive<Space>` |  | Space between the two sides (and between them when stacked). Responsive. |
 | `align` | `Responsive<Align>` | `start` | Block-axis alignment of the two sides. Default `start`. Responsive. |
-| `reverse` | `boolean` |  | Put the second child first *visually* when split. DOM (and stacked) order is unchanged. |
+| `reverse` | `boolean` | `false` | Put the second child first *visually* when split. DOM (and stacked) order is unchanged. |
 | `children` (required) | `[ReactNode, ReactNode]` |  | Exactly two children: the first and second side. |
-| `as` | `'div' \| 'section' \| 'article' \| 'header' \| 'footer'` |  |  |
-
-Also accepts every prop of `HTMLAttributes<HTMLElement>`.
-
-## Section
-
-A full-bleed band of vertical space, with an optional surface and rules. Put a Container inside it for width.
-
-`Section` is how a page gets its rhythm: each band pads itself top and bottom with a step from the space scale, and can paint a surface across the full width. Width is the `Container`'s job, so a section is almost always `Section` then `Container`.
-
-```tsx
-import { Button, Container, Heading, Section, Stack, Text } from '@mitcsutt/kiln-ui'
-
-export default function Usage() {
-  return (
-    <>
-      <Section space={7}>
-        <Container width="text">
-          <Stack gap={3}>
-            <Heading level={3} size="2xl">
-              Ride the coast for less
-            </Heading>
-            <Text tone="muted">An annual pass covers every ferry and bus in the bay.</Text>
-          </Stack>
-        </Container>
-      </Section>
-      <Section space={6} surface="inverse" divider="top">
-        <Container width="text">
-          <Stack gap={4} align="start">
-            <Text>Commuting every day? The pass pays for itself in five weeks.</Text>
-            <Button>Buy an annual pass</Button>
-          </Stack>
-        </Container>
-      </Section>
-    </>
-  )
-}
-```
-
-Vary `space` between neighbours. The scale is non-linear for this reason: a page of `space={8}` everywhere has no rhythm at all.
-
-### Surfaces and bands
-
-`surface` is `canvas`, `surface`, `sunken`, `inverse` or `accent`. On `inverse` and `accent`, the colour roles flip for everything inside, so text, links, focus rings and buttons stay legible with no extra props. `divider` adds a rule at the `top`, `bottom` or `both`.
-
-### API
-
-`SectionProps`:
-
-| Prop | Type | Default | Description |
-| --- | --- | --- | --- |
-| `space` | `Responsive<Space>` | `8` | Block padding (top and bottom), as a step on the space scale. Responsive. Vary it: adjacent sections should not share the same step. Default `8`. |
-| `surface` | `'accent' \| 'surface' \| 'canvas' \| 'sunken' \| 'inverse'` |  | Full-bleed band colour. Omit to stay transparent on the canvas. `inverse` and `accent` re-point the ink, line and focus colours so children stay legible. |
-| `divider` | `'top' \| 'bottom' \| 'both'` |  | A hairline across the full bleed at the top, bottom or both edges. |
-| `as` | `'div' \| 'section' \| 'article' \| 'aside' \| 'header' \| 'footer'` |  |  |
-| `hideBelow` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide below this breakpoint (e.g. `md` → hidden on phones, shown from 48em). |
-| `hideAbove` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide from this breakpoint up (e.g. `md` → shown on phones only). |
+| `as` | `'div' \| 'section' \| 'article' \| 'header' \| 'footer'` | `div` |  |
 
 Also accepts every prop of `HTMLAttributes<HTMLElement>`.
 
-#### Component tokens
-
-Set these in a theme, or on one element, to change this component without touching the rest.
-
-| Token | Default and use |
-| --- | --- |
-| `--section-fill` | / --section-on   (read-only) the band's fill and ink on inverse/accent |
-| `--section-space-default` | block padding when `space` is unset (default var(--space-8)) |
-| `--section-divider-color` | hairline colour for `divider` (default var(--color-line)) |
-
 ## References
 
 Read a reference when its description matches the task:
 
+- [Section](references/section.md): A full-bleed band of vertical space, with an optional surface and rules. Put a Container inside it for width.
 - [Container](references/container.md): Centres content at a readable maximum width, with a fluid gutter outside it.
 - [Box](references/box.md): Padding, a surface and an edge, and nothing else. The escape hatch when no other layout fits.
 - [AppShell](references/app-shell.md): The frame of an app screen. A header, an optional sidebar, the main region, a footer and a phone-only bottom bar.

package/skills/layout-composition/references/action-bar.md

@@ -8,10 +8,12 @@ Source: https://kiln.mitchellsutton.com/docs/ui/layout/action-bar
 
 `ActionBar` is a row of buttons with consistent spacing and alignment: `end` by default, `between` to push a destructive action to the other side, `start` to follow a form's left edge.
 
+`sticky` keeps the bar at the bottom of the viewport while a long form scrolls, so save is always in reach.
+
 ```tsx
 import { ActionBar, Button, Stack, TextField } from '@mitcsutt/kiln-ui'
 
-export default function Usage() {
+export function Usage() {
   return (
     <Stack gap={5}>
       <TextField label="Route name" defaultValue="Morning commute" />
@@ -32,8 +34,6 @@ export default function Usage() {
 }
 ```
 
-`sticky` keeps the bar at the bottom of the viewport while a long form scrolls, so save is always in reach.
-
 ## API
 
 `ActionBarProps`:
@@ -41,7 +41,7 @@ export default function Usage() {
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `align` | `'start' \| 'end' \| 'between'` | `end` | Where the actions sit on the row. Default `end`. |
-| `sticky` | `boolean` |  | Pins the bar to the bottom of its scroll container — a canvas surface above a top hairline, at `--z-sticky`. Use inside a scrolling form/dialog body so the primary action stays reachable. |
+| `sticky` | `boolean` | `false` | Pins the bar to the bottom of its scroll container — a canvas surface above a top hairline, at `--z-sticky`. Use inside a scrolling form/dialog body so the primary action stays reachable. |
 | `gap` | `Responsive<Space>` | `3` | Space between actions. Responsive. Default `3`. |
 | `as` | `'div' \| 'footer'` | `div` | Render as `footer` when the bar is the form's own closing landmark. Default `div`. |
 | `hideBelow` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide below this breakpoint (e.g. `md` → hidden on phones, shown from 48em). |

package/skills/layout-composition/references/app-shell.md

@@ -8,6 +8,8 @@ Source: https://kiln.mitchellsutton.com/docs/ui/layout/app-shell
 
 `AppShell` is the outermost frame of an app: landmarks in the right order, a skip link, a sticky header, and a hand-over between a phone's bottom bar and a desktop's sidebar or header nav. These docs are an `AppShell`.
 
+The window above scrolls; narrow it below `md` and the header links give way to the bottom bar.
+
 ```tsx
 import {
   AppShell,
@@ -32,7 +34,7 @@ const ICONS = [
   <SystemIcon key="a" />,
 ]
 
-export default function Usage() {
+export function Usage() {
   return (
     <AppShell navBreakpoint="md">
       <AppShell.Header>
@@ -86,8 +88,6 @@ export default function Usage() {
 }
 ```
 
-The window above scrolls; narrow it below `md` and the header links give way to the bottom bar.
-
 ## Slots
 
 `AppShell.Header`, `AppShell.Sidebar`, `AppShell.Main`, `AppShell.Footer` and `AppShell.BottomBar` place themselves, so their order in JSX doesn't affect the layout. Keep it the same as the reading order anyway: header, sidebar, main, footer, bottom bar.
@@ -108,7 +108,7 @@ The window above scrolls; narrow it below `md` and the header links give way to
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `skipLinkLabel` | `string` | `"Skip to content"` | Text of the skip link rendered before everything else. Default "Skip to content". |
-| `navBreakpoint` | `'md' \| 'lg'` |  | Where navigation hands over from phone to desktop: from this breakpoint up the `Sidebar` appears and the `BottomBar` is removed, so there is never a width with neither. `md` (48em) or `lg` (64em, default). Pair it with the same value on `BottomNav hideAbove` and header `NavLinks hideBelow`. |
+| `navBreakpoint` | `'md' \| 'lg'` | `lg` | Where navigation hands over from phone to desktop: from this breakpoint up the `Sidebar` appears and the `BottomBar` is removed, so there is never a width with neither. `md` (48em) or `lg` (64em, default). Pair it with the same value on `BottomNav hideAbove` and header `NavLinks hideBelow`. |
 | `mainId` | `string` |  | Id given to `AppShell.Main` (the skip link target). Generated when omitted. |
 
 Also accepts every prop of `HTMLAttributes<HTMLDivElement>`.
@@ -121,6 +121,9 @@ Also accepts every prop of `HTMLAttributes<HTMLDivElement>`.
 
 Also accepts every prop of `HTMLAttributes<HTMLElement>`.
 
+
+Accepts every prop of `HTMLAttributes<HTMLElement>`.
+
 `AppShellSidebarProps`:
 
 | Prop | Type | Default | Description |
@@ -129,6 +132,10 @@ Also accepts every prop of `HTMLAttributes<HTMLElement>`.
 
 Also accepts every prop of `HTMLAttributes<HTMLElement>`.
 
+
+
+
+
 ### Component tokens
 
 Set these in a theme, or on one element, to change this component without touching the rest.

package/skills/layout-composition/references/aspect-ratio.md

@@ -8,6 +8,8 @@ Source: https://kiln.mitchellsutton.com/docs/ui/layout/aspect-ratio
 
 `AspectRatio` holds a ratio as its width changes. Its child (an image, a video, an iframe, an SVG) fills it and is cropped with `object-fit: cover`. It has no edge or radius of its own: wrap it in `Media` or a `Card` for those.
 
+The same chart framed at 16/9, 4/3 and 1/1.
+
 ```tsx
 import { AspectRatio, Grid } from '@mitcsutt/kiln-ui'
 
@@ -25,7 +27,7 @@ function Chart({ label }: { label: string }) {
   )
 }
 
-export default function Usage() {
+export function Usage() {
   return (
     <Grid columns={{ base: 1, sm: 3 }} gap={4}>
       {(['16/9', '4/3', '1/1'] as const).map((ratio) => (

package/skills/layout-composition/references/box.md

@@ -8,10 +8,12 @@ Source: https://kiln.mitchellsutton.com/docs/ui/layout/box
 
 `Box` adds padding, a background surface, a border and a radius to its content. Reach for `Stack`, `Inline` or `Grid` to arrange things, and for `Card` when something is a self-contained object. `Box` is for the wells and frames left over.
 
+`surface="inverse"` flips the colour roles inside, like an inverse `Section`.
+
 ```tsx
 import { Box, Stack, Text } from '@mitcsutt/kiln-ui'
 
-export default function Usage() {
+export function Usage() {
   return (
     <Stack gap={4}>
       <Box padding={{ base: 4, md: 5 }} surface="sunken" radius="surface">
@@ -28,8 +30,6 @@ export default function Usage() {
 }
 ```
 
-`surface="inverse"` flips the colour roles inside, like an inverse `Section`.
-
 ## API
 
 `BoxProps`:
@@ -39,10 +39,10 @@ export default function Usage() {
 | `padding` | `Responsive<Space>` |  | Padding on every side. Responsive. |
 | `paddingX` | `Responsive<Space>` |  | Inline (left/right) padding; overrides `padding` on that axis. Responsive. |
 | `paddingY` | `Responsive<Space>` |  | Block (top/bottom) padding; overrides `padding` on that axis. Responsive. |
-| `surface` | `'none' \| 'surface' \| 'canvas' \| 'sunken' \| 'raised' \| 'inverse'` |  | Background fill. `inverse` also re-points ink and line colours for its children. |
-| `border` | `boolean` |  | Hairline border in `--color-line`. One edge treatment per element — a border *or* a fill. |
-| `radius` | `'none' \| 'surface' \| 'field' \| 'media'` |  | Corner radius, by role. |
-| `as` | `'div' \| 'section' \| 'article' \| 'aside' \| 'header' \| 'footer' \| 'li' \| 'span'` |  |  |
+| `surface` | `'none' \| 'surface' \| 'canvas' \| 'sunken' \| 'raised' \| 'inverse'` | `none` | Background fill. `inverse` also re-points ink and line colours for its children. |
+| `border` | `boolean` | `false` | Hairline border in `--color-line`. One edge treatment per element — a border *or* a fill. |
+| `radius` | `'none' \| 'surface' \| 'field' \| 'media'` | `none` | Corner radius, by role. |
+| `as` | `'div' \| 'section' \| 'article' \| 'aside' \| 'header' \| 'footer' \| 'li' \| 'span'` | `div` |  |
 | `hideBelow` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide below this breakpoint (e.g. `md` → hidden on phones, shown from 48em). |
 | `hideAbove` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide from this breakpoint up (e.g. `md` → shown on phones only). |
 

package/skills/layout-composition/references/checkout.md

@@ -33,7 +33,7 @@ const BASKET = [
 
 const subtotal = BASKET.reduce((sum, item) => sum + item.price, 0)
 
-export default function Checkout() {
+export function Usage() {
   return (
     <Section space={7}>
       <Container width="content">

package/skills/layout-composition/references/container.md

@@ -8,10 +8,22 @@ Source: https://kiln.mitchellsutton.com/docs/ui/layout/container
 
 `Container` sets a maximum width and centres its content. The gutter sits _outside_ the width, so `width="text"` is a true reading measure at any screen size.
 
+| `width`   | Max width | For                                 |
+| --------- | --------- | ----------------------------------- |
+| `narrow`  | 32rem     | sign-in, short forms, confirmations |
+| `text`    | 42rem     | articles and long reading           |
+| `content` | 68rem     | most pages (the default)            |
+| `wide`    | 84rem     | dashboards and wide tables          |
+| `full`    | 100%      | edge to edge, inside the gutter     |
+
+Pass `gutter={false}` when the parent already pads its content.
+
+The `narrow`, `text` and `content` widths, one above the other.
+
 ```tsx
 import { Container, Stack, Text } from '@mitcsutt/kiln-ui'
 
-export default function Usage() {
+export function Usage() {
   return (
     <Stack gap={4}>
       {(['narrow', 'text', 'content'] as const).map((width) => (
@@ -26,25 +38,15 @@ export default function Usage() {
 }
 ```
 
-| `width`   | Max width | For                                 |
-| --------- | --------- | ----------------------------------- |
-| `narrow`  | 32rem     | sign-in, short forms, confirmations |
-| `text`    | 42rem     | articles and long reading           |
-| `content` | 68rem     | most pages (the default)            |
-| `wide`    | 84rem     | dashboards and wide tables          |
-| `full`    | 100%      | edge to edge, inside the gutter     |
-
-Pass `gutter={false}` when the parent already pads its content.
-
 ## API
 
 `ContainerProps`:
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `width` | `'content' \| 'narrow' \| 'text' \| 'wide' \| 'full'` |  | Maximum content width: `narrow` 32rem · `text` 42rem (prose measure) · `content` 68rem (default) · `wide` 84rem · `full` (no maximum). |
+| `width` | `'content' \| 'narrow' \| 'text' \| 'wide' \| 'full'` | `content` | Maximum content width: `narrow` 32rem · `text` 42rem (prose measure) · `content` 68rem (default) · `wide` 84rem · `full` (no maximum). |
 | `gutter` | `boolean` | `true` | Keep the fluid page gutter on either side. Default `true`. |
-| `as` | `'div' \| 'section' \| 'article' \| 'header' \| 'footer' \| 'main' \| 'nav'` |  |  |
+| `as` | `'div' \| 'section' \| 'article' \| 'header' \| 'footer' \| 'main' \| 'nav'` | `div` |  |
 | `hideBelow` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide below this breakpoint (e.g. `md` → hidden on phones, shown from 48em). |
 | `hideAbove` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide from this breakpoint up (e.g. `md` → shown on phones only). |
 

package/skills/layout-composition/references/dashboard.md

@@ -41,7 +41,7 @@ const STATUS = {
   empty: { tone: 'critical', label: 'Empty' },
 } as const
 
-export default function Dashboard() {
+export function Usage() {
   return (
     <Section space={7}>
       <Container width="wide">

package/skills/layout-composition/references/divider.md

@@ -8,10 +8,12 @@ Source: https://kiln.mitchellsutton.com/docs/ui/layout/divider
 
 `Divider` separates groups. For a rule between every item of a list, use `Stack dividers` instead, which spaces the rules for you.
 
+A labelled divider names the group that follows. `spacing` adds space above and below from the space scale, `strong` uses the stronger line colour, and `decorative` hides the rule from assistive technology when it carries no meaning (it's a `separator` otherwise).
+
 ```tsx
 import { Divider, Inline, Stack, Text } from '@mitcsutt/kiln-ui'
 
-export default function Usage() {
+export function Usage() {
   return (
     <Stack gap={4}>
       <Text>Morning departures</Text>
@@ -30,8 +32,6 @@ export default function Usage() {
 }
 ```
 
-A labelled divider names the group that follows. `spacing` adds space above and below from the space scale, `strong` uses the stronger line colour, and `decorative` hides the rule from assistive technology when it carries no meaning (it's a `separator` otherwise).
-
 ## API
 
 `DividerProps`:
@@ -39,11 +39,11 @@ A labelled divider names the group that follows. `spacing` adds space above and
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
 | `orientation` | `'horizontal' \| 'vertical'` | `horizontal` | Default `horizontal`. A vertical rule stretches to its flex/grid row. |
-| `strong` | `boolean` |  | Heavier rule in `--color-line-strong` at `--border-width-strong`. |
+| `strong` | `boolean` | `false` | Heavier rule in `--color-line-strong` at `--border-width-strong`. |
 | `label` | `ReactNode` |  | Text set into a horizontal rule, e.g. "Earlier this week". It also names the separator. |
 | `labelPosition` | `'start' \| 'center'` | `start` | Where the label sits. Default `start` (left-aligned by default); `center` for a lone break. |
 | `spacing` | `0 \| 1 \| 2 \| 3 \| 4 \| 5 \| 6 \| 7 \| 8 \| 9 \| 10 \| 11 \| 12` |  | Margin on both sides of the rule (block axis if horizontal, inline if vertical). |
-| `decorative` | `boolean` |  | Purely visual: hide it from assistive tech. Use when the rule only repeats a boundary that headings or landmarks already convey. |
+| `decorative` | `boolean` | `false` | Purely visual: hide it from assistive tech. Use when the rule only repeats a boundary that headings or landmarks already convey. |
 | `hideBelow` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide below this breakpoint (e.g. `md` → hidden on phones, shown from 48em). |
 | `hideAbove` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide from this breakpoint up (e.g. `md` → shown on phones only). |
 

package/skills/layout-composition/references/section.md

@@ -0,0 +1,69 @@
+<!-- Generated from the Kiln docs by apps/docs/src/skills. Edit the docs pages, then run `pnpm generate:skills`. -->
+
+# Section
+
+> A full-bleed band of vertical space, with an optional surface and rules. Put a Container inside it for width.
+
+Source: https://kiln.mitchellsutton.com/docs/ui/layout/section
+
+`Section` is how a page gets its rhythm: each band pads itself top and bottom with a step from the space scale, and can paint a surface across the full width. Width is the `Container`'s job, so a section is almost always `Section` then `Container`.
+
+Vary `space` between neighbours. The scale is non-linear for this reason: a page of `space={8}` everywhere has no rhythm at all.
+
+```tsx
+import { Button, Container, Heading, Section, Stack, Text } from '@mitcsutt/kiln-ui'
+
+export function Usage() {
+  return (
+    <>
+      <Section space={7}>
+        <Container width="text">
+          <Stack gap={3}>
+            <Heading level={3} size="2xl">
+              Ride the coast for less
+            </Heading>
+            <Text tone="muted">An annual pass covers every ferry and bus in the bay.</Text>
+          </Stack>
+        </Container>
+      </Section>
+      <Section space={6} surface="inverse" divider="top">
+        <Container width="text">
+          <Stack gap={4} align="start">
+            <Text>Commuting every day? The pass pays for itself in five weeks.</Text>
+            <Button>Buy an annual pass</Button>
+          </Stack>
+        </Container>
+      </Section>
+    </>
+  )
+}
+```
+
+## Surfaces and bands
+
+`surface` is `canvas`, `surface`, `sunken`, `inverse` or `accent`. On `inverse` and `accent`, the colour roles flip for everything inside, so text, links, focus rings and buttons stay legible with no extra props. `divider` adds a rule at the `top`, `bottom` or `both`.
+
+## API
+
+`SectionProps`:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `space` | `Responsive<Space>` | `8` | Block padding (top and bottom), as a step on the space scale. Responsive. Vary it: adjacent sections should not share the same step. Default `8`. |
+| `surface` | `'accent' \| 'surface' \| 'canvas' \| 'sunken' \| 'inverse'` |  | Full-bleed band colour. Omit to stay transparent on the canvas. `inverse` and `accent` re-point the ink, line and focus colours so children stay legible. |
+| `divider` | `'top' \| 'bottom' \| 'both'` |  | A hairline across the full bleed at the top, bottom or both edges. |
+| `as` | `'div' \| 'section' \| 'article' \| 'aside' \| 'header' \| 'footer'` | `section` |  |
+| `hideBelow` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide below this breakpoint (e.g. `md` → hidden on phones, shown from 48em). |
+| `hideAbove` | `'sm' \| 'md' \| 'lg' \| 'xl'` |  | Hide from this breakpoint up (e.g. `md` → shown on phones only). |
+
+Also accepts every prop of `HTMLAttributes<HTMLElement>`.
+
+### Component tokens
+
+Set these in a theme, or on one element, to change this component without touching the rest.
+
+| Token | Default and use |
+| --- | --- |
+| `--section-fill` | / --section-on   (read-only) the band's fill and ink on inverse/accent |
+| `--section-space-default` | block padding when `space` is unset (default var(--space-8)) |
+| `--section-divider-color` | hairline colour for `divider` (default var(--color-line)) |

package/skills/layout-composition/references/settings.md

@@ -28,7 +28,7 @@ import {
   TextField,
 } from '@mitcsutt/kiln-ui'
 
-export default function Settings() {
+export function Usage() {
   return (
     <Section space={7}>
       <Container width="content">