@mitcsutt/kiln-ui 0.4.0 → 0.6.0

package/dist/utils/newlines.d.ts

@@ -0,0 +1,2 @@
+/** `text` without its trailing newlines, found by a backward scan rather than a regex. */
+export declare function trimTrailingNewlines(text: string): string;

package/dist/utils/newlines.js

@@ -0,0 +1,10 @@
+//#region src/utils/newlines.ts
+function e(e) {
+	let t = e.length;
+	for (; t > 0 && e[t - 1] === "\n";) t--;
+	return e.slice(0, t);
+}
+//#endregion
+export { e as trimTrailingNewlines };
+
+//# sourceMappingURL=newlines.js.map

package/dist/utils/newlines.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"newlines.js","names":["trimTrailingNewlines","end","text"],"sources":["../../src/utils/newlines.ts"],"sourcesContent":["/** `text` without its trailing newlines, found by a backward scan rather than a regex. */\nexport function trimTrailingNewlines(text: string): string {\n  let end = text.length\n  while (end > 0 && text[end - 1] === '\\n') end--\n  return text.slice(0, end)\n}\n"],"mappings":";AACA,SAAgBA,EAAqB,GAAsB;CACzD,IAAIC,IAAMC,EAAK;CACf,OAAOD,IAAM,KAAKC,EAAKD,IAAM,OAAO,OAAM;CAC1C,OAAOC,EAAK,MAAM,GAAGD,CAAG;AAC1B"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mitcsutt/kiln-ui",
-  "version": "0.4.0",
+  "version": "0.6.0",
   "description": "Kiln: a themeable React design system on Radix primitives, plain CSS and design tokens",
   "keywords": [
     "kiln",
@@ -36,6 +36,10 @@
       "types": "./dist/theme/script.d.ts",
       "default": "./dist/theme/script.js"
     },
+    "./highlight": {
+      "types": "./dist/highlight/index.d.ts",
+      "default": "./dist/highlight/index.js"
+    },
     "./styles.css": "./dist/styles.css",
     "./themes/monograph.css": "./dist/themes/monograph.css",
     "./themes/ledger.css": "./dist/themes/ledger.css",
@@ -72,6 +76,7 @@
     "publint": "^0.3.25",
     "react": "^19.3.0",
     "react-dom": "^19.3.0",
+    "shiki": "^4.5.0",
     "storybook": "^10.6.1",
     "typescript": "~6.0.3",
     "vite": "^8.3.2",
@@ -79,7 +84,13 @@
   },
   "peerDependencies": {
     "react": "^18.3.0 || ^19.0.0",
-    "react-dom": "^18.3.0 || ^19.0.0"
+    "react-dom": "^18.3.0 || ^19.0.0",
+    "shiki": "^4.0.0"
+  },
+  "peerDependenciesMeta": {
+    "shiki": {
+      "optional": true
+    }
   },
   "engines": {
     "node": ">=22.12.0"

package/skills/design-rules/SKILL.md

@@ -79,6 +79,7 @@ Beyond the checks, a theme has a subject, and each colour, face, radius and easi
 - **Asymmetric splits** (`<Split ratio="5/7">`), a hang column for labels, at least one element per page that breaks the column.
 - **Vary section rhythm.** The space scale is non-linear (4 8 12 16 24 32 48 64 96 144…) and adjacent `<Section>`s should not use the same `space`.
 - **Not everything is a card.** Prefer lists, tables, rules and whitespace. A card needs a reason: it's interactive, draggable, or a self-contained object.
+- **A list on a busy canvas gets one sheet, not a card per row.** Where rows would float on a textured or coloured canvas, `List` and `Table` take `surface` (`surface` or `raised`): the whole list sits on one sheet and its rows, fills, rails and rules stay rows inside it.
 - The hero is the subject's most characteristic thing: the open invoices, the release board, today's orders. Not a stat row with a gradient.
 
 ### Components & depth

package/skills/layout-composition/SKILL.md

@@ -18,6 +18,7 @@ sources:
   - 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/ScrollArea/ScrollArea.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
@@ -431,6 +432,7 @@ Read a reference when its description matches the task:
 - [ActionBar](references/action-bar.md): The row of actions at the end of a form or dialog. Cancel, save, continue.
 - [Divider](references/divider.md): A hairline rule between groups of content, optionally labelled, horizontal or vertical.
 - [AspectRatio](references/aspect-ratio.md): A frame that keeps its proportions, for images, video, maps and charts.
+- [ScrollArea](references/scroll-area.md): A scroll container for content wider or taller than the page, such as a bracket, a timeline or a wide board, that keyboard users can reach and scroll.
 - [VisuallyHidden](references/visually-hidden.md): Content that screen readers announce and sighted readers don't need to see.
 - [Dashboard](references/dashboard.md): A week of operations at a glance, built from stats, a table and a list. No tiles, no gradients, no cards that don't need to be cards.
 - [Settings](references/settings.md): A settings page with section navigation, labelled fields, grouped switches and a guarded destructive action.

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

@@ -30,6 +30,25 @@ export function Usage() {
 }
 ```
 
+## Accent panel
+
+`surface="accent"` is a rounded panel in the accent colour, for the one thing on a page that should shout. Text, links and buttons inside it take the accent's own ink.
+
+```tsx
+import { Box, Stack, Text } from '@mitcsutt/kiln-ui'
+
+export function AccentPanel() {
+  return (
+    <Box surface="accent" padding={5} radius="surface">
+      <Stack gap={2}>
+        <Text weight="medium">Ferry tickets go on sale Monday at 09:00</Text>
+        <Text size="sm">Weekend crossings sell out within the hour, so set a reminder.</Text>
+      </Stack>
+    </Box>
+  )
+}
+```
+
 ## API
 
 `BoxProps`:
@@ -39,7 +58,8 @@ 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' \| 'cat-6' \| 'cat-3' \| 'cat-5' \| 'cat-1' \| 'cat-2' \| 'cat-4' \| 'cat-7' \| 'cat-8'` | `none` | Background fill. `inverse` and the categorical `cat-1` to `cat-8` (one person's or team's colour, matching their `Tag`) also re-point ink and line colours for its children. |
+| `surface` | `'none' \| 'accent' \| 'surface' \| 'canvas' \| 'sunken' \| 'raised' \| 'inverse' \| 'cat-6' \| 'cat-3' \| 'cat-5' \| 'cat-1' \| 'cat-2' \| 'cat-4' \| 'cat-7' \| 'cat-8'` | `none` | Background fill. `inverse`, `accent` and the categorical `cat-1` to `cat-8` (one person's or team's colour, matching their `Tag`) also re-point ink, line and accent colours for its children, so they stay legible on the fill. |
+| `adaptTones` | `boolean` | `false` | On an `inverse`, `accent` or categorical fill, re-point the status tones too, so tone text and soft tone fills (a `Stat` delta, a toned `Numeral` or `Text`, a soft `Badge`) stay AA on the fill. On `accent` and categorical fills tone text becomes the fill's ink, so the sign, glyph or label carries the status; on `inverse` each tone keeps its hue. Off by default, so tones keep the page's colours. No effect on other surfaces. |
 | `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` |  |

package/skills/layout-composition/references/scroll-area.md

@@ -0,0 +1,68 @@
+<!-- Generated from the Kiln docs by apps/docs/src/skills. Edit the docs pages, then run `pnpm generate:skills`. -->
+
+# ScrollArea
+
+> A scroll container for content wider or taller than the page, such as a bracket, a timeline or a wide board, that keyboard users can reach and scroll.
+
+Source: https://kiln.mitchellsutton.com/docs/ui/layout/scroll-area
+
+`ScrollArea` lets one wide thing scroll on its own instead of pushing the page sideways. Give it a `label` and it's a named region in the tab order, so someone without a mouse or touch screen can focus it and scroll with the arrow keys. The scrollbar takes the theme's line colour.
+
+A data table doesn't need one: `Table` scrolls sideways itself, and takes the same `label`.
+
+Something wider than the page, such as a knockout bracket, scrolls inside a `ScrollArea` instead of pushing the page sideways. Its `label` makes it a named region that keyboard users can focus and scroll with the arrow keys.
+
+```tsx
+import { Badge, Card, Inline, ScrollArea, Stack, Text } from '@mitcsutt/kiln-ui'
+
+const ROUNDS = [
+  { round: 'Round of 16', ties: ['Kelso Bay 2–1 Old Quay', 'Harbour Square 0–0 Marram Point'] },
+  { round: 'Quarter-finals', ties: ['Kelso Bay 3–2 North Point', 'Harbour Square 1–0 Eastgate'] },
+  { round: 'Semi-finals', ties: ['Kelso Bay 1–1 Harbour Square'] },
+  { round: 'Final', ties: ['Saturday 14:00 at Harbour Park'] },
+]
+
+export function Usage() {
+  return (
+    <ScrollArea label="Knockout rounds">
+      <Inline gap={4} wrap={false}>
+        {ROUNDS.map((r) => (
+          <Card key={r.round}>
+            <Card.Body>
+              <Stack gap={2} align="start">
+                <Text weight="medium">{r.round}</Text>
+                {r.ties.map((tie) => (
+                  <Badge key={tie} variant="outline">
+                    {tie}
+                  </Badge>
+                ))}
+              </Stack>
+            </Card.Body>
+          </Card>
+        ))}
+      </Inline>
+    </ScrollArea>
+  )
+}
+```
+
+## API
+
+`ScrollAreaProps`:
+
+| Prop | Type | Default | Description |
+| --- | --- | --- | --- |
+| `label` | `string` |  | Names the area. With a name (this, or `aria-labelledby`) it becomes a labelled region that keyboard users can focus and scroll with the arrow keys. |
+| `axis` | `'both' \| 'x' \| 'y'` | `x` | Which way it scrolls. On `x` and `both` the content keeps its natural width, so a row of cards scrolls instead of squeezing. `y` and `both` scroll once a parent gives the area a height (a grid row, a pane). Default `x`. |
+| `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<HTMLDivElement>`.
+
+### Component tokens
+
+Set these in a theme, or on one element, to change this component without touching the rest.
+
+| Token | Default and use |
+| --- | --- |
+| `--scroll-area-thumb` | default var(--color-line-strong) — the scrollbar's thumb |

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

@@ -62,7 +62,7 @@ export function CategoricalBand() {
 
 ## Surfaces and bands
 
-`surface` is `canvas`, `surface`, `sunken`, `inverse`, `accent`, or a categorical `cat-1` to `cat-8` (a band in one person's or team's colour, matching their `Tag`). On `inverse`, `accent` and the categorical bands, 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`.
+`surface` is `canvas`, `surface`, `sunken`, `inverse`, `accent`, or a categorical `cat-1` to `cat-8` (a band in one person's or team's colour, matching their `Tag`). On `inverse`, `accent` and the categorical bands, the colour roles flip for everything inside, so text, links, focus rings and buttons stay legible with no extra props. Add `adaptTones` to flip the status tones too. `divider` adds a rule at the `top`, `bottom` or `both`.
 
 ## API
 
@@ -72,6 +72,7 @@ export function CategoricalBand() {
 | --- | --- | --- | --- |
 | `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' \| 'cat-6' \| 'cat-3' \| 'cat-5' \| 'cat-1' \| 'cat-2' \| 'cat-4' \| 'cat-7' \| 'cat-8'` |  | Full-bleed band colour. Omit to stay transparent on the canvas. `inverse`, `accent` and the categorical `cat-1` to `cat-8` re-point the ink, line and focus colours so children stay legible. |
+| `adaptTones` | `boolean` | `false` | On an `inverse`, `accent` or categorical band, re-point the status tones too, so tone text and soft tone fills (a `Stat` delta, a toned `Numeral` or `Text`, a soft `Badge`) stay AA on the band. On `accent` and categorical bands tone text becomes the band's ink, so the sign, glyph or label carries the status; on `inverse` each tone keeps its hue. Off by default, so tones keep the page's colours. No effect on other surfaces. |
 | `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). |

package/skills/setup-and-theming/SKILL.md

@@ -226,6 +226,7 @@ Merges class names, filtering falsy values.
 - [Tokens](https://kiln.mitchellsutton.com/docs/ui/foundations/tokens): the contract every theme fills in.
 - [Theming](https://kiln.mitchellsutton.com/docs/ui/foundations/theming): write a theme of your own.
 - [Button](https://kiln.mitchellsutton.com/docs/ui/actions/button): the reference component.
+- [AI tooling](https://kiln.mitchellsutton.com/docs/tooling/ai): the agent skills that ship with kiln-ui, and how to load them into your coding agent.
 
 ## References