@mitcsutt/kiln-ui 0.1.0

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

@@ -0,0 +1,134 @@
+<!-- Generated from the Kiln docs by apps/docs/src/skills. Edit the docs pages, then run `pnpm generate:skills`. -->
+
+# Settings
+
+> A settings page with section navigation, labelled fields, grouped switches and a guarded destructive action.
+
+Source: https://kiln.mitchellsutton.com/docs/ui/patterns/settings
+
+Settings pages are long, rarely visited, and read by people looking for one thing. So the sections are named and linked, every control has a visible label and a sentence of description where the effect isn't obvious, and the one destructive action asks before it acts.
+
+```tsx
+import {
+  ActionBar,
+  Button,
+  Container,
+  Dialog,
+  Divider,
+  Fieldset,
+  NavLinks,
+  Section,
+  SectionHeader,
+  SelectField,
+  Split,
+  Stack,
+  SwitchField,
+  Text,
+  TextareaField,
+  TextField,
+} from '@mitcsutt/kiln-ui'
+
+export default function Settings() {
+  return (
+    <Section space={7}>
+      <Container width="content">
+        <Split ratio="1/3" gap={7}>
+          <NavLinks orientation="vertical" label="Settings">
+            <NavLinks.Item href="#profile" active>
+              Profile
+            </NavLinks.Item>
+            <NavLinks.Item href="#notifications">Notifications</NavLinks.Item>
+            <NavLinks.Item href="#account">Account</NavLinks.Item>
+          </NavLinks>
+          <Stack gap={7}>
+            <Stack gap={5} as="section" aria-labelledby="profile">
+              <SectionHeader
+                level={2}
+                size="xl"
+                titleId="profile"
+                title="Profile"
+                description="Shown to the people you share routes with."
+              />
+              <TextField label="Display name" defaultValue="Ines Varga" />
+              <TextareaField
+                label="About"
+                description="A sentence or two. Plain text."
+                defaultValue="Commutes by ferry, weekends on the coast path."
+                showCount
+                maxLength={160}
+              />
+              <SelectField
+                label="Home station"
+                defaultValue="harbour"
+                options={[
+                  { value: 'harbour', label: 'Harbour Square' },
+                  { value: 'northpoint', label: 'Northpoint Library' },
+                  { value: 'kelso', label: 'Kelso Bay Pier' },
+                ]}
+              />
+            </Stack>
+            <Divider />
+            <Fieldset legend="Notifications" description="Sent to ines@example.com.">
+              <Stack gap={4}>
+                <SwitchField label="Weekly ride summary" defaultChecked />
+                <SwitchField
+                  label="Station alerts"
+                  description="When your home station runs low."
+                  defaultChecked
+                />
+                <SwitchField label="Product news" />
+              </Stack>
+            </Fieldset>
+            <Divider />
+            <Stack gap={4} as="section" aria-labelledby="account">
+              <SectionHeader level={2} size="xl" titleId="account" title="Account" />
+              <Text tone="muted">
+                Deleting your account ends any active hire and removes your ride history.
+              </Text>
+              <Dialog>
+                <Dialog.Trigger asChild>
+                  <Button variant="outline" tone="critical">
+                    Delete account
+                  </Button>
+                </Dialog.Trigger>
+                <Dialog.Content
+                  size="sm"
+                  title="Delete your account?"
+                  description="Your 214 rides and saved routes go with it. This can't be undone."
+                >
+                  <Dialog.Footer>
+                    <Dialog.Close asChild>
+                      <Button variant="ghost" tone="neutral">
+                        Keep my account
+                      </Button>
+                    </Dialog.Close>
+                    <Button tone="critical">Delete account</Button>
+                  </Dialog.Footer>
+                </Dialog.Content>
+              </Dialog>
+            </Stack>
+            <ActionBar align="end">
+              <Button variant="ghost" tone="neutral">
+                Discard changes
+              </Button>
+              <Button>Save profile</Button>
+            </ActionBar>
+          </Stack>
+        </Split>
+      </Container>
+    </Section>
+  )
+}
+```
+
+## What it's made of
+
+- **`Split ratio="1/3"`** with vertical **`NavLinks`** for the sections. Below `md` the split stacks, and the links sit above the form.
+- **`TextField`, `TextareaField` and `SelectField`**, the composed fields from [Inputs](https://kiln.mitchellsutton.com/docs/ui/inputs/field): label, description, error and warning wired to the control with no extra markup.
+- **`Fieldset`** groups the notification switches under one legend, so a screen reader announces them as a set.
+- **`Dialog`** confirms the account deletion, saying exactly what will be lost. Its cancel button is the specific "Keep my account", not "Cancel".
+- **`ActionBar align="end"`** holds save and discard together at the end of the form.
+
+## Bound to form state
+
+This page uses plain kiln-ui fields with default values. To validate, track dirty state and submit, bind the same fields with `@mitcsutt/kiln-forms`: it renders through exactly these components, so the page looks the same. See [Account settings](https://kiln.mitchellsutton.com/docs/forms/getting-started/account-settings) for the bound version.

package/skills/layout-composition/references/visually-hidden.md

@@ -0,0 +1,41 @@
+<!-- Generated from the Kiln docs by apps/docs/src/skills. Edit the docs pages, then run `pnpm generate:skills`. -->
+
+# VisuallyHidden
+
+> Content that screen readers announce and sighted readers don't need to see.
+
+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.
+
+```tsx
+import { Inline, Text, VisuallyHidden } from '@mitcsutt/kiln-ui'
+
+export default function Usage() {
+  return (
+    <Inline gap={2}>
+      <Text numeric weight="strong">
+        4.2
+      </Text>
+      <Text tone="muted" aria-hidden="true">
+        ★
+      </Text>
+      <VisuallyHidden>out of 5, from 318 passenger reviews</VisuallyHidden>
+    </Inline>
+  )
+}
+```
+
+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. |
+| `as` | `'div' \| 'span' \| 'label' \| 'a' \| 'h1' \| 'h2' \| 'h3'` | `span` | Default `span`. |
+| `href` | `string` |  | Only for `as="a"`. |
+
+Also accepts every prop of `HTMLAttributes<HTMLElement>`.

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

@@ -0,0 +1,197 @@
+---
+name: setup-and-theming
+description: "Use when installing @mitcsutt/kiln-ui in a React app: loading its stylesheet, wrapping the app in ThemeProvider, choosing Paper or a preset theme (Monograph, Ledger, Fiesta) and a colour mode, setting the theme before first paint with themeScript under SSR or the Next.js App Router, and passing router links through asChild."
+metadata:
+  purpose: Install kiln-ui, load its CSS, and apply a built-in theme and colour mode correctly on the client and the server.
+  type: lifecycle
+  library: "@mitcsutt/kiln-ui"
+sources:
+  - mitcsutt/kiln:apps/docs/content/docs/ui/index.mdx
+  - mitcsutt/kiln:apps/docs/content/docs/ui/themes/paper.mdx
+  - mitcsutt/kiln:apps/docs/content/docs/ui/themes/monograph.mdx
+  - mitcsutt/kiln:apps/docs/content/docs/ui/themes/ledger.mdx
+  - mitcsutt/kiln:apps/docs/content/docs/ui/themes/fiesta.mdx
+---
+
+<!-- Generated from the Kiln docs by apps/docs/src/skills. Edit the docs pages, then run `pnpm generate:skills`. -->
+
+# Set up kiln-ui and pick a theme
+
+Install kiln-ui, load its CSS, and apply a built-in theme and colour mode correctly on the client and the server.
+
+`@mitcsutt/kiln-ui` is one set of React components whose whole look (colour, type, shape, density, depth and motion) comes from a theme applied at the root. Behaviour comes from [Radix](https://www.radix-ui.com/primitives) primitives; the look is plain CSS and design tokens. There's no Tailwind and no CSS-in-JS to configure.
+
+## Install
+
+```sh
+pnpm add @mitcsutt/kiln-ui
+```
+
+React and React DOM 18.3 or 19 are peer dependencies. The only runtime dependency is `radix-ui`.
+
+## Load the stylesheet
+
+Import the stylesheet once, at your app's root, before your own CSS:
+
+```tsx title="src/main.tsx"
+import '@mitcsutt/kiln-ui/styles.css'
+```
+
+`styles.css` holds the fonts, the tokens, a small reset, the default Paper theme and every component's styles. Kiln's global tokens and reset sit in cascade layers (`kiln.reset`, `kiln.tokens`, `kiln.themes`), so your own CSS always wins over them without a specificity fight.
+
+## Wrap the app in a theme
+
+```tsx title="src/App.tsx"
+import { ThemeProvider } from '@mitcsutt/kiln-ui'
+import type { ReactNode } from 'react'
+
+export function App({ children }: { children: ReactNode }) {
+  return <ThemeProvider>{children}</ThemeProvider>
+}
+```
+
+With no `theme`, you get **Paper**, the neutral default. `ThemeProvider` writes `data-theme` and `data-mode` to `<html>`, remembers the reader's light or dark choice, and gives every component below it `useTheme()`. To use a preset, import its stylesheet and name it:
+
+```tsx
+import '@mitcsutt/kiln-ui/styles.css'
+import '@mitcsutt/kiln-ui/themes/monograph.css'
+
+;<ThemeProvider theme="monograph" defaultMode="dark">
+  …
+</ThemeProvider>
+```
+
+Presets are separate files, so an app pays only for the ones it imports. [Themes](references/paper.md) shows all four, and [Theming](https://kiln.mitchellsutton.com/docs/ui/foundations/theming) shows how to write your own.
+
+## Compose a screen
+
+Screens are built from layout primitives and typed props, never utility classes or inline styles: `gap={5}` is a step on the theme's space scale, `width="text"` is a reading measure, `tone="critical"` is an intent.
+
+```tsx
+import { Button, Container, Heading, Inline, Section, Stack, Text } from '@mitcsutt/kiln-ui'
+
+export default function FirstScreen() {
+  return (
+    <Section space={7}>
+      <Container width="text">
+        <Stack gap={5}>
+          <Heading level={1} size="display-sm">
+            Maps for people in a hurry
+          </Heading>
+          <Text size="lg" tone="muted">
+            Every ferry, tram and night bus in the bay, on one timetable that fits in a pocket.
+          </Text>
+          <Inline gap={3}>
+            <Button>Download the timetable</Button>
+            <Button variant="outline" tone="neutral">
+              See the route map
+            </Button>
+          </Inline>
+        </Stack>
+      </Container>
+    </Section>
+  )
+}
+```
+
+If a screen needs CSS beyond a layout wrapper or two, Kiln is probably missing a prop or a component. Read [Layout](https://kiln.mitchellsutton.com/docs/ui/layout/stack) for the primitives that replace most custom CSS.
+
+## Render on the server without a flash
+
+When the page is server-rendered, the stored colour mode is only known in the browser. Put `themeScript` in the document `<head>` so the right theme and mode are set before the first paint. Give it the same theme and `defaultMode` as the provider; a reader's stored choice still wins.
+
+```tsx title="app/layout.tsx"
+import '@mitcsutt/kiln-ui/styles.css'
+import { themeScript } from '@mitcsutt/kiln-ui'
+import { Providers } from './providers'
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en" suppressHydrationWarning>
+      <head>
+        <script dangerouslySetInnerHTML={{ __html: themeScript('paper', 'system') }} />
+      </head>
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  )
+}
+```
+
+`suppressHydrationWarning` on `<html>` is needed because the script changes its attributes before React hydrates.
+
+### With the Next.js App Router
+
+Kiln's components use React state and context, so they render in client components. Put `ThemeProvider` in a file marked `'use client'`, and import Kiln components from client components:
+
+```tsx title="app/providers.tsx"
+'use client'
+
+import { ThemeProvider } from '@mitcsutt/kiln-ui'
+import type { ReactNode } from 'react'
+
+export function Providers({ children }: { children: ReactNode }) {
+  return <ThemeProvider>{children}</ThemeProvider>
+}
+```
+
+Server components can still render those client components and pass them data. These docs are built that way: the pages are server components, and everything they show from Kiln is rendered by client components.
+
+## Links and routers
+
+Anything that navigates takes `asChild`, so your router's link keeps doing the routing while Kiln does the styling:
+
+```tsx
+import NextLink from 'next/link'
+import { Button, Link, NavLinks } from '@mitcsutt/kiln-ui'
+
+;<>
+  <Button asChild>
+    <NextLink href="/work">See the work</NextLink>
+  </Button>
+
+  <NavLinks.Item asChild active={pathname === '/work'}>
+    <NextLink href="/work">Work</NextLink>
+  </NavLinks.Item>
+</>
+```
+
+## What every component promises
+
+- It forwards its ref and spreads native props onto its root, so `id`, `aria-*`, `data-*` and event handlers work as on the element it renders.
+- It works on React 18 and 19, and renders on the server.
+- It's keyboard- and screen-reader-complete. Anything with focus management (menus, dialogs, tabs, selects) is built on Radix.
+- It respects `prefers-reduced-motion`: every duration collapses to almost nothing.
+- It accepts `className` and `style` as an escape hatch, not a workflow.
+
+## Joining class names
+
+`cx` joins class names and skips the falsy ones, for the rare `className` you add to a Kiln component or your own element:
+
+```tsx
+import { cx } from '@mitcsutt/kiln-ui'
+
+;<Card className={cx(styles.route, isSaved && styles.saved)}>…</Card>
+```
+
+```ts
+declare function cx(...classes: (string | false | null | undefined)[]): string
+```
+
+Merges class names, filtering falsy values.
+
+## Next
+
+- [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.
+
+## References
+
+Read a reference when its description matches the task:
+
+- [Paper](references/paper.md): The neutral default. A typeset proof on good uncoated stock, where the ink is the accent.
+- [Monograph](references/monograph.md): A scholarly monograph read under a desk lamp at night. Blue slate, one ember accent, a big serif display. Dark-first.
+- [Ledger](references/ledger.md): An accountant's ruled book. Green-grey paper, bank-note green, accounting red, and figures set like receipt tape.
+- [Fiesta](references/fiesta.md): A screen-printed festival poster. Flat spot inks, hard offsets, condensed signage numerals and springy motion.

package/skills/setup-and-theming/references/fiesta.md

@@ -0,0 +1,32 @@
+<!-- Generated from the Kiln docs by apps/docs/src/skills. Edit the docs pages, then run `pnpm generate:skills`. -->
+
+# Fiesta
+
+> A screen-printed festival poster. Flat spot inks, hard offsets, condensed signage numerals and springy motion.
+
+Source: https://kiln.mitchellsutton.com/docs/ui/themes/fiesta
+
+_A screen-printed festival poster and sticker album._ Screen printing can't do gradients, so neither does Fiesta: flat spot inks on apricot poster stock, everything keylined in aubergine, and a hard misregistered offset where other themes have a soft shadow.
+
+
+## Use it
+
+```tsx
+import '@mitcsutt/kiln-ui/styles.css'
+import '@mitcsutt/kiln-ui/themes/fiesta.css'
+import { ThemeProvider } from '@mitcsutt/kiln-ui'
+
+;<ThemeProvider theme="fiesta" defaultMode="light">
+  …
+</ThemeProvider>
+```
+
+Fiesta's two faces are declared in its own stylesheet, so they cost nothing unless you import it. It's light-first (the daytime show); dark mode is the floodlit night show.
+
+## The idea, applied
+
+- **Colour.** Flat spot inks (coral accent, gold highlight, teal positive) on apricot poster stock, all keylined in aubergine ink. Night mode is a floodlit aubergine. A 6% halftone dot screen on the canvas, and no gradients anywhere.
+- **Type.** Big Shoulders, a condensed signage face, for headings (in capitals), figures and numerals, and Bricolage Grotesque, ink-trapped and a little mischievous, for text. A 1.28 ratio.
+- **Shape.** 2px ink borders, pills for actions and chips, 18px surfaces, round avatars.
+- **Depth.** The misregistered hard offset (`4px 4px 0` in ink), which presses flat (`--active-shift: 2px`) when you press a control.
+- **Motion.** An overshooting spring: things land with a bump.

package/skills/setup-and-theming/references/ledger.md

@@ -0,0 +1,32 @@
+<!-- Generated from the Kiln docs by apps/docs/src/skills. Edit the docs pages, then run `pnpm generate:skills`. -->
+
+# Ledger
+
+> An accountant's ruled book. Green-grey paper, bank-note green, accounting red, and figures set like receipt tape.
+
+Source: https://kiln.mitchellsutton.com/docs/ui/themes/ledger
+
+_An accountant's ruled book._ Quiet, dense and numeric. In Ledger the numbers are the content, so they get their own face: a condensed monospace, always tabular, like receipt tape.
+
+
+## Use it
+
+```tsx
+import '@mitcsutt/kiln-ui/styles.css'
+import '@mitcsutt/kiln-ui/themes/ledger.css'
+import { ThemeProvider } from '@mitcsutt/kiln-ui'
+
+;<ThemeProvider theme="ledger" defaultMode="light">
+  …
+</ThemeProvider>
+```
+
+Ledger is light-first. It suits screens that are mostly tables and totals: invoices, timesheets, stock counts.
+
+## The idea, applied
+
+- **Colour.** Faint green-grey ledger paper, a bank-note green accent, accounting red for negatives and a highlighter-yellow highlight.
+- **Type.** Schibsted Grotesk throughout, and Martian Mono at 80% width for every figure. A 15px base on a 1.2 ratio.
+- **Shape.** 5px radii everywhere, and a compact density of 0.86, so every space step and control is smaller.
+- **Depth.** Hairlines, and a double rule above a table's footer (`--table-foot-rule`), as a ledger totals a column.
+- **Motion.** Brief and flat (`--motion-scale: 0.8`).

package/skills/setup-and-theming/references/monograph.md

@@ -0,0 +1,39 @@
+<!-- Generated from the Kiln docs by apps/docs/src/skills. Edit the docs pages, then run `pnpm generate:skills`. -->
+
+# Monograph
+
+> A scholarly monograph read under a desk lamp at night. Blue slate, one ember accent, a big serif display. Dark-first.
+
+Source: https://kiln.mitchellsutton.com/docs/ui/themes/monograph
+
+_A scholarly monograph read under a desk lamp at night._ Modern nostalgia: blue slate rather than black, a single ember accent that behaves like phosphor, and a serif display set big and tight over a newsroom grotesk.
+
+
+## Use it
+
+Monograph is a preset, so import its stylesheet. It's dark-first, so pair it with `defaultMode="dark"`, and give `themeScript` the same:
+
+```tsx
+import '@mitcsutt/kiln-ui/styles.css'
+import '@mitcsutt/kiln-ui/themes/monograph.css'
+import { ThemeProvider, themeScript } from '@mitcsutt/kiln-ui'
+
+;<html lang="en">
+  <head>
+    <script dangerouslySetInnerHTML={{ __html: themeScript('monograph', 'dark') }} />
+  </head>
+  <body>
+    <ThemeProvider theme="monograph" defaultMode="dark">
+      …
+    </ThemeProvider>
+  </body>
+</html>
+```
+
+## The idea, applied
+
+- **Colour.** Blue-slate neutrals (hue 255, never black). One ember accent (`oklch(0.72 0.15 52)` in dark, `oklch(0.565 0.158 44)` in light) that marks what's live and current, and never decorates. A cool slate highlight.
+- **Type.** Newsreader for display and prose (optical sizes, set big at weight around 430 with −0.035em tracking) and Schibsted Grotesk for text and interface. Martian Mono only for code. A 17px base on a 1.25 ratio.
+- **Shape.** Pill actions, 8px fields, 12px surfaces, rounded-square avatars.
+- **Depth.** Hairlines only. Soft tinted shadows for floating layers.
+- **Motion.** A quint ease-out with no bounce, slightly slow (`--motion-scale: 1.1`).

package/skills/setup-and-theming/references/paper.md

@@ -0,0 +1,35 @@
+<!-- Generated from the Kiln docs by apps/docs/src/skills. Edit the docs pages, then run `pnpm generate:skills`. -->
+
+# Paper
+
+> The neutral default. A typeset proof on good uncoated stock, where the ink is the accent.
+
+Source: https://kiln.mitchellsutton.com/docs/ui/themes/paper
+
+_A typeset proof on good uncoated stock._ Paper is the theme you get when you set none. It's in the base stylesheet, and it's built to sit under any brand without arguing with it: graphite ink on warm-neutral paper, with the ink itself as the accent.
+
+
+## Use it
+
+Paper needs no extra import and no `theme` prop:
+
+```tsx
+import '@mitcsutt/kiln-ui/styles.css'
+import { ThemeProvider } from '@mitcsutt/kiln-ui'
+
+;<ThemeProvider>…</ThemeProvider>
+```
+
+Paper is also declared on the document root at zero specificity, so a preset or a custom theme that leaves a token out falls back to Paper's value rather than to nothing.
+
+## The idea, applied
+
+- **Colour.** Warm-neutral paper (hue 85, chroma no more than 0.008) and graphite ink. The primary action, the current item and live state are solid ink, and links are ink told apart by their underline. The one other hue is the editor's non-photo blue, kept for "you", the selected row and text selection. Tones are the only saturated colour on the page.
+- **Type.** Schibsted Grotesk for everything you scan (text, headings, and display at weight 640 with −0.04em tracking), Newsreader for long reading and for figures, whose tabular punctuation sits tighter, and Martian Mono for code. A 16px base on a 1.25 ratio.
+- **Shape.** Square-shouldered: 6px actions, fields and chips, 8px surfaces, round avatars.
+- **Depth.** Hairlines only. Soft graphite shadows for floating layers.
+- **Motion.** A quart ease-out, brisk, with no bounce.
+
+## All four themes
+
+The same screen in each built-in theme, in the page's current mode: