@mitcsutt/kiln-ui 0.2.1 → 0.2.2

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
@@ -121,6 +121,8 @@ 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'
 
@@ -137,8 +139,6 @@ export 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.
@@ -180,8 +180,8 @@ export 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,6 +193,8 @@ 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'
 
@@ -214,8 +216,6 @@ export 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 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,6 +239,8 @@ 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'
 
@@ -318,7 +320,7 @@ export 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'
 
@@ -410,82 +414,17 @@ export 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'` |  |  |
+| `as` | `'div' \| 'section' \| 'article' \| 'header' \| 'footer'` | `div` |  |
 
 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 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). |
-
-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,6 +8,8 @@ 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'
 
@@ -32,8 +34,6 @@ export 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 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,
@@ -86,8 +88,6 @@ export 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'
 

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

@@ -8,6 +8,8 @@ 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'
 
@@ -28,8 +30,6 @@ export function Usage() {
 }
 ```
 
-`surface="inverse"` flips the colour roles inside, like an inverse `Section`.
-
 ## API
 
 `BoxProps`:
@@ -39,10 +39,10 @@ export 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/container.md

@@ -8,6 +8,18 @@ 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'
 
@@ -26,25 +38,15 @@ export 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/divider.md

@@ -8,6 +8,8 @@ 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'
 
@@ -30,8 +32,6 @@ export 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/visually-hidden.md

@@ -8,6 +8,8 @@ Source: https://kiln.mitchellsutton.com/docs/ui/layout/visually-hidden
 
 `VisuallyHidden` keeps text in the accessibility tree while hiding it from view: the rest of a sentence a glyph implies, a heading the layout already makes obvious, a table caption.
 
+Screen readers announce the rating above as "4.2 out of 5, from 318 passenger reviews". `as` renders it as another element, such as a heading (`as="h2"`). `focusable` makes a hidden link appear when it receives focus, which is how a skip link works.
+
 ```tsx
 import { Inline, Text, VisuallyHidden } from '@mitcsutt/kiln-ui'
 
@@ -26,15 +28,13 @@ export function Usage() {
 }
 ```
 
-Screen readers announce the rating above as "4.2 out of 5, from 318 passenger reviews". `as` renders it as another element, such as a heading (`as="h2"`). `focusable` makes a hidden link appear when it receives focus, which is how a skip link works.
-
 ## API
 
 `VisuallyHiddenProps`:
 
 | Prop | Type | Default | Description |
 | --- | --- | --- | --- |
-| `focusable` | `boolean` |  | Reveal the content while it (or something inside it) has keyboard focus — for skip links and other keyboard-only affordances. |
+| `focusable` | `boolean` | `false` | Reveal the content while it (or something inside it) has keyboard focus — for skip links and other keyboard-only affordances. |
 | `as` | `'div' \| 'span' \| 'label' \| 'a' \| 'h1' \| 'h2' \| 'h3'` | `span` | Default `span`. |
 | `href` | `string` |  | Only for `as="a"`. |