# Keston UI

> The Vue 3 component library for every Keston product (`@thekestongroup/ui`), built on Reka UI and Tailwind CSS v4.

Every page below is Markdown. Component pages include when to use the component, its behaviour and accessibility rules, and its exact TypeScript API from the source. Use the library's components and tokens rather than building new ones.

---

Examples of whole pages built with the library (Vue source):

- [Keston ID pages](https://raw.githubusercontent.com/thekestongroup/ui/main/src/examples/KestonIdPages.stories.ts): Sign-in leading to OAuth consent, two-step code (Vue source)
- [App pages](https://raw.githubusercontent.com/thekestongroup/ui/main/src/examples/AppPages.stories.ts): Whole app pages built from the components (Vue source)
- [School pages](https://raw.githubusercontent.com/thekestongroup/ui/main/src/examples/SchoolPages.stories.ts): Records, reviews, booking, settings (Vue source)
- [Form layout](https://raw.githubusercontent.com/thekestongroup/ui/main/src/examples/FormLayout.stories.ts): A validated form (Vue source)

---

# Getting started

Keston UI is published on npm as `@thekestongroup/ui`. It needs Vue 3.5 or later and Tailwind CSS v4.

## Install

```sh
pnpm add @thekestongroup/ui
```

## Add the theme

In your app's main CSS file, after Tailwind:

```css
@import "tailwindcss";
@import "@thekestongroup/ui/theme.css";
```

`theme.css` adds Keston's colours and font (Lato, served with the library, so no requests to Google). It also tells Tailwind to scan the library's components for the classes they use.

## Use a component

```vue
<script setup lang="ts">
import { ref } from 'vue'
import { Button, Input } from '@thekestongroup/ui'

const name = ref('')
</script>

<template>
  <form class="flex flex-col gap-4">
    <Input v-model="name" label="Full name" />
    <Button type="submit" variant="primary">Save</Button>
  </form>
</template>
```

Every component is typed, so your editor shows its props and what they do.

## Find your way around

- **[Components](https://ui.keston.co/components/button.md)**: one page per component, with a live example, when to use it, its props, and how it behaves for keyboard and screen-reader users.
- **[Storybook](https://ui.keston.co/storybook/)**: every component with controls for each prop, plus whole example pages built from them.
- **[Changelog](https://ui.keston.co/changelog.md)**: what changed in each version.

## Versions

Keston UI follows [semver](https://semver.org). Before 1.0, a minor version (0.3 → 0.4) can include breaking changes, which the [changelog](https://ui.keston.co/changelog.md) points out.

---

# Colours

Keston's colours are Tailwind theme tokens, defined in `theme.css`. Use them by name in classes, e.g. `bg-primary`, `text-red`, `border-black/15`. Avoid raw hex values, so every product stays in step when a colour changes.

## Brand and text

| | Token | Hex | Use for |
|---|---|---|---|
|  | `primary` (`kblue`) | `#023750` | Keston blue: primary buttons, selected items, the brand |
|  | `black` | `#050505` | Text. Use opacity for quieter text: `text-black/65` |
|  | `white` | `#FAFAFA` | Cards, fields, text on dark colours |

## Surfaces

| | Token | Hex | Use for |
|---|---|---|---|
|  | `background` | `#E1E1E1` | The app's frame behind the content: AppShell, Header, Sidebar |
|  | `surface` | `#EBEBEB` | Quiet areas inside content |
|  | `surface-elevated` | `#F2F2F2` | Areas raised above a surface |

## Status

| | Token | Hex | Use for |
|---|---|---|---|
|  | `green` | `#007A16` | Success |
|  | `yellow` | `#F1C70B` | Warnings. Use black text on it |
|  | `red` | `#D2042D` | Errors and destructive actions |
|  | `blue` | `#035483` | Information, e.g. an info Badge or Notification |
|  | `focus` | `#007FC9` | The keyboard focus ring, and nothing else |

## Lines and quieter text

Borders and dividers are black at 15% (`border-black/15`). Secondary text is black at 65% (`text-black/65`), and placeholders at 55%. Using opacity, not extra greys, keeps them right on any of the surfaces above.

---

# Typography

Keston UI uses **Lato** in regular (400) and bold (700), with italics. It's served with the library from `theme.css`, so it works everywhere, including Safari, with no requests to Google.

## Sizes

The components use Tailwind's text sizes:

| Class | Size | Used for |
|---|---|---|
| `text-xs` | 12px | Helper text, field messages, small buttons, captions |
| `text-sm` | 14px | Most interface text: labels, fields, medium buttons, tables |
| `text-base` | 16px | Body text, large buttons, card titles |
| `text-lg` | 18px | Panel titles, e.g. a Slideover's |
| `text-xl` | 20px | Page and sign-in headings |

On touch screens, form fields use 16px text: iPhone zooms the page into any field with smaller text when it's tapped.

## Weight

Use bold (`font-bold`) for headings, names and totals. Everything else is regular. There's no semibold or light: two weights keep the hierarchy clear.

## Writing

- Sentence case everywhere: "Add a student", not "Add A Student".
- Say what something does: "Save changes", not "OK".
- Keep labels short, and put guidance in helper text.

---

# AppShell

> The layout of every Keston app page: the shared Header on top, the app's Sidebar on the left, the page in the middle.

- Import: `import { AppShell } from '@thekestongroup/ui'`
- Group: Layout
- Live example: https://ui.keston.co/storybook/?path=/story/components-layout-appshell--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/AppShell/AppShell.vue

## When to use

- As the root of every app, so all apps share the same header, account menu and responsive behaviour. Each app supplies only its title, sidebar items and pages.

## When not to use

- Sign-in, error or marketing pages that have no navigation.

## Anatomy

| Part | Required | Notes |
|---|---|---|
| skip link | Yes | "Skip to content", visible only when focused. |
| header | Yes | Header: sticky, with menu button and account menu. The menu button opens the mobile menu (narrow) or collapses the sidebar (wide). |
| sidebar | Yes | Sidebar beside the page (wide) or in a left Slideover (narrow). |
| main | Yes | The page. Default slot. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| title | string | — | App name, in the header and as the mobile menu's title. |
| user | HeaderUser | — | Signed-in user, for the account menu. |
| userActions | HeaderUserAction[] | all | Account menu actions. |
| signIn | boolean | true | Show Sign in when signed out. |
| items / sections | SidebarItem[] / SidebarSection[] | [] | Sidebar contents. |
| collapsible | boolean | true | Wide screens: the header's menu button collapses the sidebar. |
| collapsed | boolean (v-model) | false | Sidebar collapsed to icons. |
| menuOpen | boolean (v-model) | false | Mobile menu open. |
| linkComponent | string \| Component | "a" | For sidebar items with `to`. |
| header / sidebar | object | — | Other Header / Sidebar props. |

Events: `account-settings`, `switch-account`, `log-out`, `sign-in`.

## Spacing and layout

- Breakpoint: lg (64rem). Below it the sidebar moves into a Slideover (max width spacing 72).
- The page scrolls, not an inner box: the header sticks at the top, the sidebar sticks below it at full remaining height.
- Page padding is the page's own (e.g. `ui.main: 'p-6'`).

## Behaviour

- Narrow: menu button opens the menu. Choosing an item, or the screen becoming wide, closes it.
- Wide: sidebar collapse state is kept by `v-model:collapsed` (the app can store it).

## Accessibility

- Landmarks: header (banner), nav (inside the sidebar), main.
- Skip link moves focus to main.
- Mobile menu is a dialog titled with the app name.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `AppShell.vue` | — |
| iOS (SwiftUI) | — | NavigationSplitView (iPad), TabView (iPhone). |
| Android (Compose) | — | Scaffold with TopAppBar and NavigationDrawer / Rail. |

## Tokens used

| Token | Used for |
|---|---|
| color background | page background |

## Do / Don't

| Do | Don't |
|---|---|
| Use one AppShell at the root of each app. | Rebuild the header per app. Use slots for app-specific additions. |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// AppShell.vue
/**
 * The layout of a whole app page: the Header across the top, the app's
 * Sidebar down the left, and the page in the middle. Every app uses this, so
 * the header looks and behaves the same everywhere; only the sidebar's items
 * and the page change.
 *
 * - Wide screens (lg and up): the sidebar sits beside the page, and the
 *   header's menu button collapses it to icons and back (unless
 *   `collapsible` is false).
 * - Narrow screens: the sidebar is hidden and the menu button opens it in a
 *   Slideover from the left, whose title bar is the header's height. Choosing
 *   an item, or the screen becoming wide, closes it.
 * - The page itself scrolls (not an inner box), so the header stays at the
 *   top (sticky), the sidebar stays put below it, and mobile browsers can
 *   hide their address bar while scrolling.
 *
 * The account menu (top right) is the Header's: pass `user` and listen for
 * account-settings, switch-account, log-out (and sign-in when signed out).
 *
 * Slots: default (the page), header-leading, header-middle, header-trailing,
 * account, account-menu (passed to Header), sidebar-header and sidebar-footer (passed to Sidebar;
 * sidebar-header is only shown on wide screens, as the Slideover has its own
 * title).
 */
export interface AppShellProps {
  /** Name of the app, shown in the header and as the mobile menu's title. */
  title?: string
  /** The signed-in user, for the account menu. Without it, Sign in is shown. */
  user?: HeaderUser
  /** Which actions the account menu offers. Default all three. */
  userActions?: HeaderUserAction[]
  /** Show Sign in when there is no user. */
  signIn?: boolean
  /** Sidebar items in a single section. */
  items?: SidebarItem[]
  /** Sidebar items in labelled sections. */
  sections?: SidebarProps['sections']
  /** Wide screens: show the header's menu button, which collapses the sidebar to icons. */
  collapsible?: boolean
  /** Component used for sidebar items with `to`, e.g. RouterLink. */
  linkComponent?: SidebarProps['linkComponent']
  /** Other Header props, e.g. `{ ui: { title: '…' } }`. */
  header?: Omit<HeaderProps, 'title' | 'menu' | 'menuOpen' | 'sticky' | 'user' | 'userActions' | 'signIn'>
  /** Other Sidebar props, e.g. `{ label: 'Admissions' }`. */
  sidebar?: Omit<SidebarProps, 'items' | 'sections' | 'collapsible' | 'linkComponent'>
  class?: HTMLAttributes['class']
  /** Extra classes for the parts. */
  ui?: {
    main?: HTMLAttributes['class']
  }
}

const emit = defineEmits<{
  'account-settings': []
  'switch-account': []
  'log-out': []
  'sign-in': []
}>()

defineSlots<{
  default?(): unknown
  'header-leading'?(): unknown
  'header-middle'?(): unknown
  'header-trailing'?(): unknown
  account?(): unknown
  'account-menu'?(props: { close: () => void }): unknown
  'sidebar-header'?(props: { collapsed: boolean }): unknown
  'sidebar-footer'?(props: { collapsed: boolean; mobile: boolean }): unknown
}>()

/** Sidebar collapsed to icons (wide screens). Use v-model:collapsed to keep it, e.g. in localStorage. */
const collapsed = defineModel<boolean>('collapsed', { default: false })

/** Mobile menu open. Optional: use v-model:menu-open to control it. */
const menuOpen = defineModel<boolean>('menuOpen', { default: false })
```

---

# Header

> The bar across the top of every Keston app: menu button, app name, an optional middle area, actions and the account menu. The same in every app; each part can be overridden.

- Import: `import { Header } from '@thekestongroup/ui'`
- Group: Layout
- Live example: https://ui.keston.co/storybook/?path=/story/components-layout-header--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/Header/Header.vue

## When to use

- Once per app, at the top of every page, above the Sidebar and content.

## When not to use

- Headings inside a page or panel (use a heading, or the Slideover's header).

## Anatomy

| Part | Required | Notes |
|---|---|---|
| menu | No | Ghost square Button with a menu icon. Opens the Sidebar on small screens. |
| leading | No | Before the title, e.g. a logo. |
| title | No | App or area name. Bold, truncates. |
| middle | No | Fills the space between title and trailing, e.g. breadcrumbs. |
| trailing | No | Actions before the account menu, e.g. notifications. |
| account | No | Round avatar (picture or initials) opening the account menu; Sign in button when signed out. Slot `account` replaces it. |
| account menu | No | Panel under the avatar: organisation, large avatar, name, email, with a small basic Account settings button under them; then a row of basic buttons, Switch account (left) and Log out (right). Slot `account-menu` adds content above that row. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| title | string | — | App or area name. |
| menu | boolean | false | Show the menu button (emits `menu`). |
| menuOpen | boolean | — | Whether what it opens is open (aria-expanded). |
| menuControls | string | — | Id of what it opens (aria-controls). |
| menuLabel | string | "Menu" | Accessible name of the menu button. |
| user | { name, email?, organisation?, avatar? } | — | Signed-in user. Shows the account menu. |
| userActions | ('account-settings' \| 'switch-account' \| 'log-out')[] | all three | Actions in the account menu (positions are fixed). Each emits an event of the same name. |
| signIn | boolean | true | Show Sign in (emits `sign-in`) when there is no user. |
| sticky | boolean | true | Stay at the top while the page scrolls. |
| ui | { menu, title, middle, trailing } | — | Extra classes per part, e.g. `menu: 'lg:hidden'`. |

## Sizes

| Size | Height | Padding (x / y) | Gap | Icon size | Text style |
|---|---|---|---|---|---|
| — | spacing 12 (48px) | spacing 4 / — | spacing 2 | 16px | title: base, bold |

## States

| State | Appearance | Notes |
|---|---|---|
| Enabled | white, bottom border black 15% | |
| Sticky | as enabled, pinned to the top | z-index above content, below dialogs |

## Behaviour

- Menu button: press emits `menu`; the app opens the Sidebar (in a Slideover) itself.
- Account menu: opens on click / tap / Enter below the avatar, aligned to its right edge (w-72). Focus moves into it; Escape or clicking outside closes it. Choosing an action closes it, then emits the event; the app does the navigation or sign-out.
- The menu button's icon lines up with the header's padding (negative margin), like the × in Slideover.

## Accessibility

- Rendered as `<header>` (banner landmark when at the top level of the page).
- The title is not a heading; each page keeps its own `h1`.
- Icon-only buttons in trailing need an `aria-label`.
- The avatar button is named "Account: {name}", or "{initials}, account: {name}" when it shows initials, so its visible text is part of its name (voice control). Pictures and initials are hidden from assistive tech, as the name is in the label.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `Header.vue` | — |
| iOS (SwiftUI) | — | Navigation bar / toolbar. |
| Android (Compose) | — | TopAppBar. |

## Tokens used

| Token | Used for |
|---|---|
| color white | background |
| color black (15%) | bottom border, account menu divider |
| color primary | avatar initials background |

## Do / Don't

| Do | Don't |
|---|---|
| Keep trailing to a few icon buttons and one primary action. | Put full forms or labelled fields in the header. |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// Header.vue
export interface HeaderUser {
  name: string
  email?: string
  /** Organisation or school the account belongs to, shown at the top of the account menu. */
  organisation?: string
  /** Picture URL. Initials are shown without one. */
  avatar?: string
}

export type HeaderUserAction = 'account-settings' | 'switch-account' | 'log-out'

/**
 * The bar across the top of every Keston app. It is the same in every app:
 * a menu button (to open the Sidebar on small screens), the app's name, an
 * optional middle area, actions, and the signed-in user's account menu on
 * the right (Account settings, Switch account, Log out). Each part can be
 * overridden with a slot.
 *
 * Slots: leading (before the title, e.g. a logo), title, default (the middle,
 * fills the space between title and trailing), trailing (actions before the
 * account menu), account (replaces the account menu, or the Sign in button),
 * account-menu (extra content in the account menu, above Switch account /
 * Log out: `{ close }`).
 */
export interface HeaderProps {
  /** Name of the app or area, shown next to the menu button. */
  title?: string
  /**
   * Show the menu button, which emits `menu` when pressed. Hide it on wide
   * screens with `ui.menu`, e.g. `{ menu: 'lg:hidden' }`.
   */
  menu?: boolean
  /** Whether what the menu button opens is open, for screen readers (aria-expanded). */
  menuOpen?: boolean
  /** Id of what the menu button opens (aria-controls). */
  menuControls?: string
  /** Accessible name of the menu button. */
  menuLabel?: string
  /**
   * The signed-in user. Shows their picture or initials on the right, which
   * opens the account menu. Without it, a Sign in button is shown instead
   * (see `signIn`).
   */
  user?: HeaderUser
  /**
   * Which actions the account menu offers. Each emits an event of the same
   * name. Account settings sits under the user's name; Switch account and Log
   * out share the bottom row (left and right).
   */
  userActions?: HeaderUserAction[]
  /** Show a Sign in button (emits `sign-in`) when there is no `user`. */
  signIn?: boolean
  /**
   * Stay at the top while the page scrolls (on by default). Turn off when the
   * header isn't inside the element that scrolls.
   */
  sticky?: boolean
  class?: HTMLAttributes['class']
  /** Extra classes for the parts. */
  ui?: {
    menu?: HTMLAttributes['class']
    title?: HTMLAttributes['class']
    middle?: HTMLAttributes['class']
    trailing?: HTMLAttributes['class']
    userMenu?: HTMLAttributes['class']
  }
}

const emit = defineEmits<{
  menu: []
  'account-settings': []
  'switch-account': []
  'log-out': []
  'sign-in': []
}>()

defineSlots<{
  leading?(): unknown
  title?(): unknown
  default?(): unknown
  trailing?(): unknown
  account?(): unknown
  'account-menu'?(props: { close: () => void }): unknown
}>()
```

---

# PageHeader

> The top of a page: breadcrumb, title, status, description and the page's main actions.

- Import: `import { PageHeader } from '@thekestongroup/ui'`
- Group: Layout
- Live example: https://ui.keston.co/storybook/?path=/story/components-layout-pageheader--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/PageHeader/PageHeader.vue

## When to use

Every page inside AppShell, as the first thing in the page.

## Anatomy

| Part | Required | Notes |
|---|---|---|
| breadcrumb | No | Shown when there are two or more steps. Pass `sidebarTrail(items)`. |
| title | Yes | The page's `h1`. |
| badge | No | Slot after the title, e.g. a status Badge ("Draft"). |
| description | No | A sentence under the title. |
| actions | No | Slot on the right, e.g. Buttons, an AvatarGroup. Wraps under the title on narrow screens. |
| below | No | Default slot, under everything, e.g. an alert or tabs. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| title | string | — | Required. |
| description | string | — | Slot `description` for links or formatting. |
| breadcrumb | BreadcrumbItem[] | — | Top level first, the current page last. |
| linkComponent | string \| Component | a | For breadcrumb steps with `to`. |
| ui | { title, description, actions } | — | Extra classes per part. |

## Sizes

| Part | Value |
|---|---|
| Title | 24px / 32px, bold, wraps |
| Description | 14px / 20px, black 65%, up to 65 characters wide |
| Breadcrumb to title | 8px |
| Title to description | 4px |
| Title to badge | 8px |
| Title block to actions | 24px across, 12px when wrapped under |
| Between actions | 8px |

## Behaviour

| Situation | Result |
|---|---|
| Narrow screen | Actions wrap under the title |
| Long title | Wraps onto more lines |
| One breadcrumb step | Breadcrumb hidden (the title says it) |

## Accessibility

| Part | Announced as |
|---|---|
| Title | `heading` level 1 |
| Breadcrumb | `navigation` named "Breadcrumb" |
| Container | `header` inside `main`, so not a banner landmark |

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `PageHeader.vue` | — |
| iOS (SwiftUI) | — | `navigationTitle` and toolbar items. |
| Android (Compose) | — | Top app bar title and actions. |

## Tokens used

| Token | Used for |
|---|---|
| color black | title |
| color black (65%) | description |

## Do / Don't

| Do | Don't |
|---|---|
| Put the page's one primary action here | Put several primary buttons side by side |
| Use the badge for the page's status | Put long text in the badge |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// PageHeader.vue
/**
 * The top of a page: where it is (breadcrumb), what it is (the h1 title, with
 * an optional status badge and description), and its main actions on the
 * right. Actions wrap under the title on narrow screens.
 *
 * Slots: badge (after the title, e.g. a Badge), description (instead of the
 * prop, for links or formatting), actions (e.g. Buttons), default (anything
 * under, e.g. an alert or tabs).
 */
export interface PageHeaderProps {
  /** The page's name: its h1. */
  title: string
  /** A sentence under the title. */
  description?: string
  /** Where the page is. Pass `sidebarTrail(items)` to follow a nested Sidebar. */
  breadcrumb?: BreadcrumbItem[]
  /** Component used for breadcrumb steps with `to`, e.g. RouterLink. */
  linkComponent?: string | Component
  class?: HTMLAttributes['class']
  /** Extra classes for the parts. */
  ui?: {
    title?: HTMLAttributes['class']
    description?: HTMLAttributes['class']
    actions?: HTMLAttributes['class']
  }
}

defineSlots<{
  badge?(): unknown
  description?(): unknown
  actions?(): unknown
  default?(): unknown
}>()
```

---

# Avatar

> A person's picture, or their initials on a primary circle, optionally with a profile card on hover.

- Import: `import { Avatar } from '@thekestongroup/ui'`
- Group: Element
- Live example: https://ui.keston.co/storybook/?path=/story/components-element-avatar--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/Avatar/Avatar.vue

## When to use

| Use an Avatar for | Use instead |
|---|---|
| Showing who someone is beside their name, or in place of it | Several people together (AvatarGroup) |
| A quick look at someone's details (`profile`) without leaving the page | Full details (link to their profile page) |

## Anatomy

| Part | Required | Notes |
|---|---|---|
| circle | Yes | Primary fill, white bold initials, or the picture filling it. |
| picture | No | `user.avatar`. Falls back to initials if it fails to load. |
| profile card | No | With `profile`: a popover with organisation, a 48px avatar, name, role and email (a mailto link). |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| user | { name, avatar?, role?, email?, organisation? } | — | Required. Initials come from the first and last words of `name`. |
| size | xs \| sm \| md \| lg \| xl | md | See Sizes. |
| profile | boolean | false | Show the profile card on hover, click, tap or Enter. Makes the avatar a button. |
| decorative | boolean | false | Hidden from screen readers, when the name is already said nearby. |

## Sizes

| Size | Diameter | Initials |
|---|---|---|
| xs | 20px | 12px bold |
| sm | 28px | 12px bold |
| md | 36px | 14px bold |
| lg | 48px | 16px bold |
| xl | 64px | 20px bold |

Profile card: 256px wide; avatar 48px; name 14px bold; role and email 14px, black 65%; organisation 12px bold uppercase, black 65%.

## States

| State | Appearance | Notes |
|---|---|---|
| Picture | Picture, cropped to the circle | |
| No picture / failed | Initials on primary | |
| Focused (profile) | 2px focus ring `#007FC9`, 1px outside | Keyboard only |
| Profile open | Card below, aligned to the start | Opens after 300ms hover, closes 150ms after leaving |

## Behaviour

| Action | Result |
|---|---|
| Hover (profile) | Card opens after 300ms; stays while the pointer is on it |
| Click, tap or Enter (profile) | Card opens; focus stays on the avatar |
| Escape or click outside | Card closes |

## Accessibility

| Case | Announced as |
|---|---|
| No profile | `img` named by the person's name |
| Decorative | Hidden |
| Profile, with initials | Button named "{initials}, {name}" (visible text first, for voice control) |
| Profile, with a picture | Button named "{name}" |

Initials on primary: white on `#023750` is 12.1:1.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `Avatar.vue` | — |
| iOS (SwiftUI) | — | Circle-clipped `AsyncImage` with an initials fallback; profile in a `popover` (iPad) or sheet (iPhone). |
| Android (Compose) | — | Circle-clipped image with an initials fallback; profile in a bottom sheet. |

## Tokens used

| Token | Used for |
|---|---|
| color primary | circle background |
| color white | initials |
| color focus | focus ring |

## Do / Don't

| Do | Don't |
|---|---|
| Use `decorative` when the name is beside it | Leave screen readers hearing the name twice |
| Use `profile` where people want a quick look | Put actions (message, edit) only in the profile card |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// Avatar.vue
export interface AvatarUser {
  name: string
  /** Picture URL. Initials are shown without one, or if it fails to load. */
  avatar?: string
  /** Job or role, e.g. "Head of Year 9". Shown in the profile. */
  role?: string
  email?: string
  /** Organisation or school, shown in the profile. */
  organisation?: string
}

/**
 * A person's picture, or their initials on a primary circle. With `profile`,
 * it becomes a button that shows a small profile card (name, role, email,
 * organisation) on hover, and on click, tap or Enter, so it works on touch
 * screens and from the keyboard.
 *
 * Several people overlapping: use AvatarGroup.
 */
export interface AvatarProps {
  user: AvatarUser
  /** 20 / 28 / 36 / 48 / 64px. */
  size?: 'xs' | 'sm' | 'md' | 'lg' | 'xl'
  /** Show a profile card on hover / press. Makes the avatar a button. */
  profile?: boolean
  /** Hidden from screen readers, when the name is already said nearby (e.g. in a labelled button). */
  decorative?: boolean
  class?: HTMLAttributes['class']
}
```

---

# AvatarGroup

> Several people as overlapping avatars, each with a profile on hover, with the rest as "+N".

- Import: `import { AvatarGroup } from '@thekestongroup/ui'`
- Group: Element
- Live example: https://ui.keston.co/storybook/?path=/story/components-element-avatargroup--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/AvatarGroup/AvatarGroup.vue

## When to use

| Use an AvatarGroup for | Use instead |
|---|---|
| Who's involved: a class's teachers, who can sign off, who's editing | A list people need to read or act on (use a table or list) |

## Anatomy

| Part | Required | Notes |
|---|---|---|
| avatars | Yes | Avatar each (with `profile` by default), overlapping, each with a white ring. |
| counter | No | "+N" circle in surface grey, when there are more than `max`. Opens a list of the rest. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| users | AvatarUser[] | — | Required. |
| size | xs \| sm \| md \| lg \| xl | md | As Avatar. |
| max | number | 4 | Avatars shown before "+N". If only one would be hidden, all are shown ("+1" saves no space). |
| profile | boolean | true | Profile card on each avatar. |
| label | string | "{n} people" | Name of the group for screen readers. |

## Sizes

| Size | Avatar | Overlap | Ring | Counter text |
|---|---|---|---|---|
| xs | 20px | 2px | 1px | 12px |
| sm | 28px | 4px | 2px | 12px |
| md | 36px | 6px | 2px | 12px |
| lg | 48px | 8px | 2px | 14px |
| xl | 64px | 12px | 2px | 16px |

Overlaps are as large as they can be without the ring reaching the initials. "+N" list: 224px wide, up to 288px tall then scrolls; a 20px avatar, name and role per person.

## Behaviour

| Action | Result |
|---|---|
| Hover or focus an avatar | It comes to the front (its ring and focus outline show), and its profile opens |
| Hover, click or Enter on "+N" | A list of everyone not shown |

## Accessibility

| Part | Announced as |
|---|---|
| Group | `group` named by `label` ("7 people") |
| Each avatar | As Avatar with `profile` |
| Counter | Button named "{n} more: {names}" |

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `AvatarGroup.vue` | — |
| iOS (SwiftUI) | — | `HStack(spacing: -overlap)` of avatars; tap opens a sheet listing everyone. |
| Android (Compose) | — | `Row` with negative spacing; tap opens a bottom sheet listing everyone. |

## Tokens used

| Token | Used for |
|---|---|
| color white | rings |
| color surface | counter background |
| color primary | avatars |

## Do / Don't

| Do | Don't |
|---|---|
| Give the group a label that says who they are ("People who can sign off") | Rely on "{n} people" where the context isn't clear |
| Keep `max` small (3–5) | Show twenty overlapping avatars |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// AvatarGroup.vue
/**
 * Several people as overlapping avatars, e.g. a class's teachers or who's
 * been sent a message. Each shows its profile on hover (or press). Past
 * `max`, the rest are a "+N" circle that lists them.
 */
export interface AvatarGroupProps {
  users: AvatarUser[]
  size?: AvatarProps['size']
  /** Avatars shown before "+N". */
  max?: number
  /** Profile card on each avatar. */
  profile?: boolean
  /** Name of the group for screen readers. Default "{n} people". */
  label?: string
  class?: HTMLAttributes['class']
}
```

---

# Badge

> A small label for a status, count or category.

- Import: `import { Badge } from '@thekestongroup/ui'`
- Group: Element
- Live example: https://ui.keston.co/storybook/?path=/story/components-element-badge--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/Badge/Badge.vue

## When to use

- Showing a status ("Paid", "Overdue"), a count (unread messages) or a category ("Year 9") next to the thing it describes.

## When not to use

- Anything people can press (use Button).
- Long messages or explanations (use text, or a callout).

## Anatomy

| Part | Required | Notes |
|---|---|---|
| container | Yes | Pill shape with a 1px border. |
| label | Yes | Short text or a number. |
| leading | No | e.g. an icon. |
| trailing | No | e.g. an icon. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| color | basic \| primary \| red \| green \| blue \| yellow | basic | Colour, by meaning (see Variants). |
| size | sm \| md \| lg | md | |

## Variants

| Color | Use for | Example |
|---|---|---|
| basic | Neutral information, categories, counts | Year 9, 28 students |
| primary | Emphasis | New |
| green | Positive, done | Paid, Enrolled |
| blue | Informational, ongoing | In progress |
| yellow | Needs attention soon | Due soon |
| red | A problem | Overdue |

## Sizes

| Size | Height | Padding (x) | Gap | Icon size | Text style |
|---|---|---|---|---|---|
| sm | spacing 5 (20px) | spacing 1.5 | spacing 1 | 12px | xs, bold |
| md | spacing 6 (24px) | spacing 2 | spacing 1 | 14px | xs, bold |
| lg | spacing 7 (28px) | spacing 2.5 | spacing 1.5 | 16px | sm, bold |

## States

Not interactive: one state only.

## Content guidelines

- One or two words, sentence case ("Due soon", not "DUE SOON").
- Never wraps; keep it short rather than truncating.

## Accessibility

- Plain text (`<span>`), read in place with the surrounding content.
- Colour must not be the only signal: the text says what the colour means.
- White text on every solid colour meets WCAG AA (4.5:1 or more), except yellow, which uses black text (12:1).

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `Badge.vue` | — |
| iOS (SwiftUI) | — | Capsule-shaped Text. |
| Android (Compose) | — | Badge / AssistChip (non-clickable). |

## Tokens used

| Token | Used for |
|---|---|
| color white, black | basic background, text |
| color black (15%) | border |
| color primary, green, blue, yellow, red | solid backgrounds (black text on yellow) |

## Do / Don't

| Do | Don't |
|---|---|
| Pick the colour by meaning. | Use colours for decoration, or make them clickable. |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// Badge.vue
/**
 * A small label for a status, count or category, e.g. "Active", "3", "Year 9".
 * Not interactive: for something people can press, use a Button.
 *
 * Slots: default (the text), leading and trailing (e.g. an icon).
 */
export interface BadgeProps {
  /**
   * Colour, by meaning:
   * - basic: neutral information, e.g. a category or count
   * - primary: emphasis, e.g. "New"
   * - green: positive / done, e.g. "Paid"
   * - blue: informational, e.g. "In progress"
   * - yellow: needs attention, e.g. "Due soon"
   * - red: a problem, e.g. "Overdue"
   *
   * Colour alone doesn't carry meaning for everyone, so the text should say
   * it too.
   */
  color?: 'basic' | 'primary' | 'red' | 'green' | 'blue' | 'yellow'
  size?: 'sm' | 'md' | 'lg'
  class?: HTMLAttributes['class']
}

defineSlots<{
  default?(): unknown
  leading?(): unknown
  trailing?(): unknown
}>()
```

---

# Button

> Starts an action: saving, cancelling, opening a panel, deleting.

- Import: `import { Button } from '@thekestongroup/ui'`
- Group: Element
- Live example: https://ui.keston.co/storybook/?path=/story/components-element-button--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/Button/Button.vue

## When to use

- Any action someone takes on the current page or record: Save, Cancel, Export, Delete.
- Icon-only actions in toolbars and panel headers (`square`, usually `ghost`), e.g. × to close, ☰ to open the menu.

## When not to use

- Going to another page: use a link (or `as-child` with a router link, so it is still a link).
- Choosing between options: use a radio group, select or segmented control.
- Turning a setting on or off: use a switch or checkbox.

## Anatomy

| Part | Required | Notes |
|---|---|---|
| container | Yes | Rounded rectangle with a 1px border (transparent on ghost). |
| leading | No | Icon before the label (slot `leading`). |
| label | Yes, unless `square` | The text (default slot). |
| trailing | No | Icon after the label (slot `trailing`), e.g. → on Next. |
| status | No | Spinner, ✓ or × with optional text, shown in place of the content while `status` isn't idle. |
| focus ring | — | Outline shown on keyboard focus. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| variant | basic \| primary \| ghost \| danger | basic | What the button is for (see Variants). |
| size | sm \| md \| lg | md | See Sizes. |
| square | boolean | false | Icon only: as wide as it is tall. Needs `aria-label`. |
| disabled | boolean | false | Can't be pressed or focused. |
| type | button \| submit \| reset | button | Native button type. |
| status | idle \| loading \| success \| error (v-model) | idle | Progress of the action. Success and error return to idle by themselves. |
| loadingText / successText / errorText | string | — | Text next to the status icon. Icon only if not set. |
| statusDuration | number (ms) | 2000 | How long success / error stay before returning to idle. |
| as / asChild | string \| component / boolean | button / false | Render as another element, e.g. a link. |

## Variants

| Variant | Background | Text | Border | Use for | Example |
|---|---|---|---|---|---|
| basic | white `#FAFAFA` | black `#050505` | black 15% | Most actions | Cancel, Export, Switch account |
| primary | primary `#023750` | white `#FAFAFA` | black 15% | The main action, one per area | Save, Continue |
| ghost | none | black `#050505` | transparent | Low emphasis, toolbars, icon buttons | ×, ☰, avatar |
| danger | red `#D2042D` | white `#FAFAFA` | black 15% | Destructive actions | Delete |

## Sizes

All sizes: 1px border, icons from Lucide at 2px stroke. Corners: 4px for small and medium (matching form fields), 6px for large. Heights are padding + one line of text + border, measured in the browser.

| Size | Height | Padding (y / x) | Gap | Icon size | Square (w × h) | Radius |
|---|---|---|---|---|---|---|
| sm | 26px | 4px / 8px (spacing 1 / 2) | 4px (spacing 1) | 14px | 26 × 26px (spacing 6.5) | 4px (`rounded`) |
| md | 38px | 8px / 16px (spacing 2 / 4) | 8px (spacing 2) | 16px | 38 × 38px (spacing 9.5) | 4px (`rounded`) |
| lg | 50px | 12px / 24px (spacing 3 / 6) | 12px (spacing 3) | 20px | 50 × 50px (spacing 12.5) | 6px (`rounded-md`) |

In a square button the icon is centred, so the space around it is equal on all four sides (5 / 10 / 14px inside the border).

## Typography

Lato (bundled with the library), regular weight, sentence case, no letter spacing. Never wraps.

| Size | Font size | Line height | Weight | Tailwind |
|---|---|---|---|---|
| sm | 12px | 16px | 400 (regular) | `text-xs` |
| md | 14px | 20px | 400 (regular) | `text-sm` |
| lg | 16px | 24px | 400 (regular) | `text-base` |

Status text (loadingText, etc.) uses the same style as the label, with an 8px gap to its icon at every size.

## States

| State | Appearance | Notes |
|---|---|---|
| Enabled | As in Variants. | |
| Hovered | Filled variants: 90% brightness (white `#FAFAFA` → about `#E1E1E1`). Ghost: black 10% fill. | Web / desktop only. 150ms ease-in-out. |
| Pressed | Filled variants: 80% brightness. Ghost: black 15% fill. | |
| Focused | 2px outline in focus `#007FC9`, 1px outside the border. | Keyboard focus only (`:focus-visible`). |
| Disabled | 40% opacity, not-allowed cursor, no hover / press. | |
| Loading | Content fades out; a spinner (icon-sized) and optional text fade in. Cursor shows progress. | Stays focusable; clicks are blocked. |
| Success | Green background, ✓ and optional text, for `statusDuration`. | Any variant. |
| Error | Red background, × and optional text, for `statusDuration`. | Any variant. |

## Spacing and layout

- Buttons in a row: 8px apart (`gap-2`). The main action goes last (right), e.g. Cancel then Save.
- Minimum clear space around a group: 16px (spacing 4).
- Minimum touch target: md is 38px tall. On touch-first screens prefer lg (50px), or give sm / md buttons extra space around them so the tap area reaches 44px.
- Ghost icon buttons at the edge of a bar or panel use a negative margin so their icon lines up with the bar's padding (see Header, Slideover).

## Behaviour

- Keyboard: Tab to focus; Enter or Space presses it.
- Pointer / touch: press on release, as native buttons do.
- Motion: colours change over 150ms (ease-in-out). Returning from success / error takes 300ms, and the width animates over 300ms (ease-out) when the status text changes its size. Icons fade and scale; with reduced motion they only fade and the width doesn't animate.

## Content guidelines

- A verb, or verb + noun: "Save", "Export students". Sentence case.
- One to three words. Don't truncate; shorten the wording instead.
- Status text says what is happening or happened: "Saving…", "Saved", "Couldn't save".

## Accessibility

- Native `<button>` (`type="button"` unless set), so role, focus and keyboard come for free.
- Icon-only buttons need an `aria-label` (e.g. "Close"). If visible text is shown, the label must contain it.
- While busy the button is `aria-disabled` and `aria-busy` (loading) but stays focusable; the status is announced through a live region ("Loading", "Done", "Failed" if no text is set).
- Contrast (text on background): basic 19.5:1, primary 12.1:1, danger 5.3:1, success status 5.3:1, ghost on white 19.5:1 and on background `#E1E1E1` 15.6:1, so all meet WCAG AA. Focus ring vs white: 4.1:1 (non-text minimum is 3:1).

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `Button.vue` | — |
| iOS (SwiftUI) | — | Button with a custom ButtonStyle using the same sizes; system press feedback instead of brightness. |
| Android (Compose) | — | Button / OutlinedButton / TextButton (ghost); 48dp minimum touch target. |

## Tokens used

| Token | Used for |
|---|---|
| font sans (Lato) | label |
| color white `#FAFAFA`, black `#050505` | basic background and text, text on filled variants |
| color black (15%) | border |
| color primary `#023750` | primary background |
| color red `#D2042D` | danger background, error status |
| color green `#007A16` | success status (white text 5.3:1) |
| color focus `#007FC9` | focus ring |
| radius (Tailwind `rounded` / `rounded-md`: 4 / 6px) | corners: small and medium / large |

## Do / Don't

| Do | Don't |
|---|---|
| Use one primary button per area. | Put two primary buttons side by side. |
| Use `status` for actions that take time, so people see progress. | Disable the button while it works; it loses focus. |
| Label icon-only buttons with `aria-label`. | Use an icon-only button where the icon isn't obvious. |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// Button.vue
export type ButtonStatus = 'idle' | 'loading' | 'success' | 'error'

export interface ButtonProps extends PrimitiveProps {
  /**
   * What the button is for:
   * - primary: the main action (one per area), e.g. Save
   * - basic: other actions, e.g. Cancel, Export
   * - ghost: low-emphasis actions, e.g. toolbar and icon buttons, × on panels
   * - danger: destructive actions, e.g. Delete
   */
  variant?: 'basic' | 'primary' | 'ghost' | 'danger'
  size?: 'sm' | 'md' | 'lg'
  /**
   * Icon-only button: as tall as a normal button of the same size and just as
   * wide, so the icon has equal space on every side. Give it an `aria-label`
   * (e.g. "Close"), as there is no text to name it.
   */
  square?: boolean
  disabled?: boolean
  type?: 'button' | 'submit' | 'reset'
  /**
   * Progress of the action this button starts. The parent sets it; use
   * `v-model:status` so the button can return itself to `idle` after showing
   * success or error. Not supported with `asChild`.
   */
  status?: ButtonStatus
  /** Text shown next to the spinner while loading. Icon only if not set. */
  loadingText?: string
  /** Text shown next to the check on success. Icon only if not set. */
  successText?: string
  /** Text shown next to the cross on error. Icon only if not set. */
  errorText?: string
  /** How long success / error is shown before returning to idle, in ms. */
  statusDuration?: number
  class?: HTMLAttributes['class']
}

const emit = defineEmits<{ 'update:status': [status: ButtonStatus] }>()
```

---

# Card

> A white panel that groups related content on a page: a form section, a summary, a stat, a table.

- Import: `import { Card } from '@thekestongroup/ui'`
- Group: Element
- Live example: https://ui.keston.co/storybook/?path=/story/components-element-card--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/Card/Card.vue

## When to use

| Use a Card for | Use instead |
|---|---|
| A section of a page or form, with a heading | Content inside a popover or slideover (they're already panels) |
| A stat or summary beside other content | A whole page's content (put it on the page background) |
| A table, at full width (`padding="none"`) | Something people press as a whole (use a Button or link) |

## Anatomy

| Part | Required | Notes |
|---|---|---|
| container | Yes | White, 1px black 15% border, 8px corners. A size container for its children. |
| title | No | Heading (h2 by default). Names the card as a region. |
| description | No | Grey text under the title. |
| actions | No | Top right, beside the title, e.g. an Edit button. |
| body | Yes | The content (default slot). |
| footer | No | Under a divider, right-aligned, e.g. Cancel / Save. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| title | string | — | Heading and accessible name. |
| description | string | — | Under the title. |
| headingLevel | 2 \| 3 \| 4 | 2 | To fit the page outline. |
| padding | md \| sm \| none | md | See Sizes. |
| as | section \| aside \| article \| div | section with a title, else div | Element to render. |
| ui | { header, body, footer } | — | Extra classes per part. |

## Sizes

| Padding | Inside | Footer padding | Use for |
|---|---|---|---|
| md | 16px; 24px from the sm breakpoint (640px) | 12px / 16px; 16px / 24px from sm | Sections, forms |
| sm | 16px | 12px / 16px | Stats, summaries |
| none | 0 | 12px / 16px | Tables, lists that run to the edges (clipped to the corners) |

| Part | Value |
|---|---|
| Gap between header and content | 16px |
| Gap between title and description | 4px |
| Title | 16px / 24px, bold |
| Description | 14px / 20px, regular, black 65% |
| Corner radius | 8px (`rounded-lg`), larger than controls' 4px, as a container |
| Border | 1px black 15% (also the footer divider) |

## States

Not interactive: one state.

## Layout

| Rule | Value |
|---|---|
| Space between cards | 16px in a grid, 24px stacked in a column |
| Background behind cards | Page background `#E1E1E1` |
| Children's layout | Use container queries (`@sm:`, `@lg:` …), so content lays out by the card's width, not the window's |

## Accessibility

| Part | Announced as |
|---|---|
| Card with a title | `region` (a `<section>`), named by its heading |
| Card without a title | Plain container, not a landmark |
| `as="aside"` | `complementary` landmark, e.g. a summary beside a form |

| Contrast | Ratio |
|---|---|
| Title on white | 19.5:1 |
| Description (black 65%) on white | about 6.5:1 |
| Card border | Decorative: the white on grey also marks the edge |

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `Card.vue` | — |
| iOS (SwiftUI) | — | `GroupBox`, or a grouped `List` section with a header. |
| Android (Compose) | — | `OutlinedCard`. |

## Tokens used

| Token | Used for |
|---|---|
| color white | background |
| color black (15%) | border, footer divider |
| color black (65%) | description |

## Do / Don't

| Do | Don't |
|---|---|
| Give section cards a title, so they're findable as regions | Nest cards inside cards |
| Put a page's main actions at the top of the page | Put the page's only Save in one card's footer when it saves the whole page |
| Use `padding="none"` for tables | Wrap a table in padding and a second border |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// Card.vue
/**
 * A white panel that groups related content on a page: a form section, a
 * summary, a stat, a table. Same border, radius and white as Button, Input
 * and Popover, so everything on the grey page background matches.
 *
 * With a `title` it's a labelled region (a `<section>` named by its heading),
 * so screen reader users can jump between cards. It's also a size container:
 * children can lay out by the card's width with `@sm:` / `@lg:` etc.
 *
 * Slots: default (the content), header (replaces title and description),
 * actions (top right, beside the title, e.g. an Edit button), footer (under a
 * divider, right-aligned, e.g. Cancel / Save).
 */
export interface CardProps {
  /** Heading. Also the card's accessible name. */
  title?: string
  /** Smaller grey text under the title. */
  description?: string
  /** Heading level, to fit the page outline (h1 is the page title). */
  headingLevel?: 2 | 3 | 4
  /**
   * Space inside:
   * - md (default): 16px, 24px from the sm breakpoint. Sections and forms.
   * - sm: 16px. Small cards, e.g. stats in a grid.
   * - none: content touches the edges, e.g. a table.
   */
  padding?: 'none' | 'sm' | 'md'
  /** Element to render. Defaults to section (with a title) or div. */
  as?: 'section' | 'aside' | 'article' | 'div'
  class?: HTMLAttributes['class']
  /** Extra classes for the parts. */
  ui?: {
    header?: HTMLAttributes['class']
    body?: HTMLAttributes['class']
    footer?: HTMLAttributes['class']
  }
}

defineSlots<{
  default?(): unknown
  header?(): unknown
  actions?(): unknown
  footer?(): unknown
}>()
```

---

# Chip

> A small item someone has chosen or entered, e.g. a recipient or a filter, optionally with × to remove it.

- Import: `import { Chip } from '@thekestongroup/ui'`
- Group: Element
- Live example: https://ui.keston.co/storybook/?path=/story/components-element-chip--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/Chip/Chip.vue

## When to use

- Showing chosen items in a row that wraps: Select's chosen options (`multiple`), recipients, applied filters.

## When not to use

- A status, count or category label: use Badge (fully rounded, bold, coloured by meaning).
- An action: use Button.

## Anatomy

| Part | Required | Notes |
|---|---|---|
| container | Yes | 4px corners (as Button and Input), 1px border, light grey fill. |
| leading | No | e.g. an icon. |
| label | Yes | Short text; truncates with … if the chip is narrower than its text. |
| remove | No | × button at the right (`removable`). |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| size | sm \| md | md | See Sizes. |
| removable | boolean | false | Show × (emits `remove`). |
| removeLabel | string | Remove | Accessible name of ×, e.g. "Remove Ben Blissett". |
| removeFocusable | boolean | true | Whether Tab reaches ×. Turn off only when there's another keyboard way to remove it. |
| disabled | boolean | false | 40% opacity; × can't be pressed. |

## Sizes

| Size | Height | Padding (x) | Gap | Icon size | × button | Text style |
|---|---|---|---|---|---|---|
| sm | 20px | 6px (2px right with ×) | 4px | 12px | 16px | 12px / 16px, regular |
| md | 24px | 8px (4px right with ×) | 4px | 14px | 20px | 14px / 20px, regular |

## States

| State | Appearance | Notes |
|---|---|---|
| Enabled | Black 5% fill, black 15% border, black text. | |
| × hovered / pressed | Black 10% / 15% fill behind the ×. | |
| × focused | 2px focus ring `#007FC9`. | Keyboard only. |
| Disabled | 40% opacity. | |

## Spacing and layout

- In a row: 4px apart (`gap-1`), wrapping onto more lines with 4px between them.

## Accessibility

- Plain text, read in place. The × is a native button named by `removeLabel`; always include the item ("Remove Ben Blissett"), not just "Remove".

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `Chip.vue` | — |
| iOS (SwiftUI) | — | Rounded rectangle label with an optional `xmark` button. |
| Android (Compose) | — | `InputChip` with a trailing close icon. |

## Tokens used

| Token | Used for |
|---|---|
| color black (5%) | fill |
| color black (15%) | border |
| color black (10% / 15%) | × hover / pressed |
| color focus | focus ring |

## Do / Don't

| Do | Don't |
|---|---|
| Use chips for things people chose. | Use chips for statuses (use Badge). |
| Name × after the item. | Leave × as just "Remove". |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// Chip.vue
/**
 * A small item someone has chosen or entered, e.g. a recipient or a filter,
 * usually shown in a row that wraps. Unlike Badge (a fully rounded status
 * label), a chip has the same 4px corners as Button and Input, and can have a
 * × to remove it.
 *
 * Slots: default (the text), leading (e.g. an icon).
 */
export interface ChipProps {
  size?: 'sm' | 'md'
  /** Show a × that emits `remove`. */
  removable?: boolean
  /** Accessible name of the ×, e.g. "Remove Ben Blissett". Default "Remove". */
  removeLabel?: string
  /**
   * Let keyboard users Tab to the ×. Off when something else offers a
   * keyboard way to remove it (e.g. Backspace in Select's search box).
   */
  removeFocusable?: boolean
  disabled?: boolean
  class?: HTMLAttributes['class']
}

const emit = defineEmits<{ remove: [] }>()

defineSlots<{
  default?(): unknown
  leading?(): unknown
}>()
```

---

# Divider

> A thin line between groups of content, optionally with a short label in the middle.

- Import: `import { Divider } from '@thekestongroup/ui'`
- Group: Element
- Live example: https://ui.keston.co/storybook/?path=/story/components-element-divider--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/Divider/Divider.vue

## When to use

| Use a Divider for | Use instead |
|---|---|
| Separating groups inside a Card, panel or menu | Separating whole sections of a page (use Cards, or spacing) |
| "or" between two alternative actions | A border that's part of a component (Card, Header, Slideover draw their own) |
| Vertical: between groups of toolbar buttons | |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| orientation | horizontal \| vertical | horizontal | Vertical stretches to the row's height. |
| label | string | — | Short text in the middle (horizontal only). Slot `default` for richer content. |
| decorative | boolean | true | Hidden from screen readers. False: announced as a separator. |

## Sizes

| Part | Value |
|---|---|
| Line | 1px, black 15% (the same as every border) |
| Length | Full width (horizontal) or full height of the row (vertical) |
| Label | 12px / 16px, black 65%, 12px gap to the lines either side |
| Spacing around | None built in: use the parent's `gap`, or margins (e.g. `mx-1 my-2` in a toolbar) |

## Accessibility

| Case | Announced as |
|---|---|
| Decorative (default) | Nothing (`role="none"` / `presentation`) |
| `decorative="false"` | `separator`, with `aria-orientation` (and the label as its name) |

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `Divider.vue` (Reka UI Separator) | — |
| iOS (SwiftUI) | — | `Divider()` |
| Android (Compose) | — | `HorizontalDivider` / `VerticalDivider` |

## Tokens used

| Token | Used for |
|---|---|
| color black (15%) | line |
| color black (65%) | label |

## Do / Don't

| Do | Don't |
|---|---|
| Use spacing first; add a Divider when spacing alone doesn't separate enough | Put a Divider between every item in a list |
| Keep labels to a word or two ("or", "Older") | Use a Divider as a heading |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// Divider.vue
/**
 * A thin line between groups of content, in the same black 15% as every
 * border. Horizontal (between stacked content) or vertical (between items in
 * a row, e.g. toolbar buttons). Optionally with a short label in the middle,
 * e.g. "or".
 *
 * Decorative by default (hidden from screen readers), as the content either
 * side usually has headings. Set `decorative` to false when the split itself
 * carries meaning.
 *
 * Slots: default (the label, instead of the `label` prop).
 */
export interface DividerProps {
  orientation?: 'horizontal' | 'vertical'
  /** Short text in the middle of a horizontal divider, e.g. "or". */
  label?: string
  /** Hidden from screen readers (the default). False: announced as a separator. */
  decorative?: boolean
  class?: HTMLAttributes['class']
}

defineSlots<{ default?(): unknown }>()
```

---

# Spinner

> A small circular loading indicator: spinning while there's no telling how long, or a ring that fills up.

- Import: `import { Spinner } from '@thekestongroup/ui'`
- Group: Element
- Live example: https://ui.keston.co/storybook/?path=/story/components-element-spinner--continuous
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/Spinner/Spinner.vue

## When to use

- Short waits in a small space: inside a Button while saving, next to a field's "Checking…" message, in a card while it loads.
- `lg` with a value: progress you want people to watch, e.g. an upload in an empty state.

## When not to use

- Progress across the width of a page or panel, or steps: use Progress.
- Waits under about a second: show nothing.

## Anatomy

| Part | Required | Notes |
|---|---|---|
| track | Yes | The full ring, in the current text colour at 20% opacity. |
| arc | Yes | Spins, or fills to the value. Current text colour. |
| percentage | No | In the middle, `lg` only, with a value. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| value | number \| null | — | Progress from 0 to `max`. Leave out for a continuous spinner. |
| max | number | 100 | The value that means complete. |
| size | sm \| md \| lg | md | 16px (a button icon) · 24px · 48px. |
| label | string | Loading | What's loading, for screen readers, e.g. "Uploading report". |
| showValue | boolean | false | Show the percentage in the middle (`lg` with a value only). |

## Behaviour

- Takes the surrounding text colour, like an icon: colour it with a text class on it or its parent, e.g. `text-primary`.
- Continuous: spins once a second; with reduced motion it turns slowly, once every two seconds.

## Accessibility

- `role="progressbar"`, named by `label`, with the value when there is one.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `Spinner.vue` | SVG. |
| iOS (SwiftUI) | — | `ProgressView()` (circular), or with a value. |
| Android (Compose) | — | `CircularProgressIndicator`. |

## Tokens used

| Token | Used for |
|---|---|
| currentColor | Track and arc |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// Spinner.vue
/**
 * A circular progress indicator.
 *
 * - No `value` (or `null`): continuous spinner, for waits of unknown length.
 * - `value` from 0 to `max`: a ring that fills as the value goes up.
 *
 * It takes the surrounding text colour, like an icon, so put a text colour
 * class on it or its parent (e.g. `class="text-primary"`).
 */
export interface SpinnerProps {
  /** Progress from 0 to `max`. Leave out (or null) for a continuous spinner. */
  value?: number | null
  /** The value that means complete. */
  max?: number
  /** sm 16px (button icon size) · md 24px · lg 48px */
  size?: 'sm' | 'md' | 'lg'
  /** What is loading, read by screen readers, e.g. "Uploading report". */
  label?: string
  /** Show the percentage in the middle. Only on `lg`, and only with a value. */
  showValue?: boolean
  class?: HTMLAttributes['class']
}
```

---

# Progress

> A thin bar showing how far along something is: a line, segments for steps, or indeterminate.

- Import: `import { Progress } from '@thekestongroup/ui'`
- Group: Element
- Live example: https://ui.keston.co/storybook/?path=/story/components-element-progress--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/Progress/Progress.vue

## When to use

- Line: something with a known size that takes a few seconds or more, e.g. an upload or an import.
- Segments: where someone is in a set of steps, e.g. a multi-step form (Slideover's `steps` uses it).
- Indeterminate: something that takes a while with no way to tell how long, e.g. loading a page of results.

## When not to use

- Under a second: show nothing, or a Spinner in the Button that started it.
- Ticking off named tasks: use Checklist.

## Anatomy

| Part | Required | Notes |
|---|---|---|
| track | Yes | 6px tall, fully rounded, black 10%. |
| fill | Yes | Primary, fully rounded. |
| segments | No | One track per step, 4px apart, filled up to the current step. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| value | number \| null | null | Done so far. Null or left out: indeterminate. |
| max | number | 100 | The total; with `segments`, the number of segments. |
| segments | boolean | false | Split into `max` segments and fill `value` of them. |
| label | string | — | Required. Accessible name, e.g. "Uploading report.pdf". Not shown. |

## Behaviour

- Line and segments ease to a new value over 300ms. Values outside 0–`max` are clamped.
- Indeterminate: a bar 40% wide sweeps from left to right every 1.5s.
- Reduced motion: no easing; indeterminate becomes a full bar that gently pulses.

## Accessibility

- `role="progressbar"` named by `label`, with `aria-valuenow` / `aria-valuemax`.
- Value text: "40%" for a line, "Step 2 of 4" for segments. Indeterminate has no value and is `aria-busy`.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `Progress.vue` | Reka UI Progress. |
| iOS (SwiftUI) | — | `ProgressView(value:total:)` with a custom style; indeterminate as the same sweeping bar. |
| Android (Compose) | — | `LinearProgressIndicator`, determinate or not; segments as a Row of them. |

## Tokens used

| Token | Used for |
|---|---|
| `color-primary` | Fill |
| `animate-progress-indeterminate` | Indeterminate sweep |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// Progress.vue
/**
 * How far along something is, as a thin bar. Three forms:
 * - a line that fills up, e.g. an upload (`value` out of `max`);
 * - segments, one per step, e.g. a multi-step form (`segments`, with `value`
 *   steps filled out of `max`);
 * - indeterminate, when there's no telling how long it'll take (no `value`).
 * Built on Reka UI's Progress, so it's announced as a progress bar.
 */
export interface ProgressProps {
  /** Done so far, out of `max`. Leave it out (or null) for indeterminate. */
  value?: number | null
  /** The total. With `segments`, the number of segments. */
  max?: number
  /** Split the bar into `max` segments and fill `value` of them. */
  segments?: boolean
  /** What's progressing, e.g. "Uploading report.pdf". Its accessible name; not shown. */
  label: string
  class?: HTMLAttributes['class']
}
```

---

# FormField

> The shell around every text-like field: label, helper, the bordered box, and the status message underneath.

- Import: `import { FormField } from '@thekestongroup/ui'`
- Group: Form
- Live example: https://ui.keston.co/storybook/?path=/story/components-form-formfield--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/FormField/FormField.vue

## When to use

- Building a text-like control the library doesn't have yet (e.g. a textarea), so it looks and behaves like Input.

## When not to use

- Anything the library already has: Input, InputNumber, InputDate, Select. They're built on it.
- Checkbox, RadioGroup and Switch: they have no box, but share the same status message.

## Anatomy

| Part | Required | Notes |
|---|---|---|
| label | Yes | 14px, above the box. |
| helper | No | 12px below the label, or behind a `?` (InfoTip) beside it. |
| box | Yes | Like a medium basic Button: 1px black 15% border, 4px corners, 12px / 8px padding. Text 14px, or 16px on touch screens. |
| leading / trailing | No | Slots either side of the control, e.g. icons. |
| control | Yes | Default slot; receives `id`, `labelId`, `describedBy` and `invalid` to put on it. |
| message | No | Status text and icon, sliding open under the box. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| label | string | — | Required. |
| helper | string | — | |
| helperPlacement | below \| icon | below | |
| errorText | string | — | Error state and message. Overrides `status` / `statusText`. |
| status | error \| success \| loading | — | |
| statusText | string | — | |
| disabled | boolean | false | 40% opacity. |

## Behaviour

- Pressing the box's padding or icons focuses the control.
- The focus ring shows on the box when the control has keyboard focus.
- The message opens in 150ms then fades in; it fades out then closes. No motion with reduced motion.
- On touch screens the text is 16px, so iPhone doesn't zoom the page in when a field is tapped. Pinch-zoom is never blocked: people who need larger text rely on it.

## Accessibility

- The `<label>` names the control. Helper and message are linked with `aria-describedby`; the message is announced politely.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `FormField.vue` | — |
| iOS (SwiftUI) | — | A view wrapping the label, control and message. |
| Android (Compose) | — | `supportingText` / `isError` on `OutlinedTextField`. |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// FormField.vue
export type FormFieldStatus = FieldStatus

export interface FormFieldProps {
  /** Visible label. Always set it: it is also the control's accessible name. */
  label: string
  /** Extra guidance about what to enter. */
  helper?: string
  /** Show helper text under the label, or behind a `?` icon next to it. */
  helperPlacement?: 'below' | 'icon'
  /**
   * Error message, e.g. from a Zod / VeeValidate schema. When set (and not
   * empty) the field shows as an error with this text; leave it undefined
   * when the value is valid. Overrides `status` and `statusText`.
   */
  errorText?: string
  /**
   * Colours the field and the status text. `loading` shows a small spinner
   * by the status text while something is checked, e.g. "Checking
   * availability…", and leaves the border as it is.
   */
  status?: FormFieldStatus
  /** Message under the field, e.g. why the value is invalid. */
  statusText?: string
  disabled?: boolean
  class?: HTMLAttributes['class']
}

defineSlots<{
  default(props: { id: string; labelId: string; describedBy?: string; invalid?: true }): unknown
  leading?(): unknown
  trailing?(): unknown
  /**
   * At the end of the label row, e.g. a "Forgot password?" link. It comes
   * after the control in the page, so Tab reaches it after the field.
   */
  'label-trailing'?(): unknown
}>()
```

---

# Input

> A single line of text: a name, an email address, a search.

- Import: `import { Input } from '@thekestongroup/ui'`
- Group: Form
- Live example: https://ui.keston.co/storybook/?path=/story/components-form-input--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/Input/Input.vue

## When to use

- Short free text on one line: names, email addresses, IDs, search terms.

## When not to use

- Several lines of notes: use InputRichText.
- A number someone steps through (a year group, a quantity): use InputNumber.
- A date: use InputDate.
- A password: use InputPassword. A one-time code: use InputCode.
- Choosing from a list: use Select or RadioGroup.

## Anatomy

| Part | Required | Notes |
|---|---|---|
| label | Yes | 14px, above the box. Also the input's accessible name. |
| helper | No | 12px under the label, or behind a `?` (InfoTip) beside it. |
| box | Yes | FormField's box: like a medium basic Button, 38px tall, 4px corners, 12px / 8px padding. |
| leading / trailing | No | Slots either side of the text, e.g. a search or mail icon. Icons are 16px, 70% opacity. |
| input | Yes | 14px text (16px on touch screens). Placeholder black 55%. |
| message | No | Error, success or loading text that slides open under the box. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| modelValue | string | '' | The text. Use `v-model`. |
| label | string | — | Required. |
| helper / helperPlacement | string / below \| icon | — / below | Extra guidance, under the label or behind a `?`. |
| errorText | string | — | Error message, e.g. from a Zod schema. Overrides everything below. |
| status / statusText | error \| success \| loading / string | — | Colours the box and the message; `loading` shows a spinner, e.g. "Checking availability…". |
| minLength | number | — | Shows "Must be at least N characters" once the field has been left. |
| maxLength | number | — | Shows "Must be N characters or fewer" straight away. Typing isn't blocked. |
| disabled | boolean | false | 40% opacity, not editable. |

Attributes such as `type`, `name`, `placeholder` and `autocomplete` go to the `<input>`.

## States

| State | Appearance | Notes |
|---|---|---|
| Enabled | White box, black 15% border. | |
| Focused | Focus ring around the box. | |
| Error | Red border and message. | |
| Success | Green border and message. | |
| Loading | Spinner and message; border unchanged. | |
| Disabled | 40% opacity. | |

## Behaviour

- Pressing anywhere in the box, including its padding and icons, focuses the input.
- "Too short" waits until the field has been left once, so it doesn't complain while someone is still typing. "Too long" shows straight away.
- An error clears as soon as the value becomes valid.

## Content guidelines

- Label: a short noun phrase, e.g. "Email address", not a question.
- Put examples and rules in the helper, not the placeholder: placeholders vanish while typing.

## Accessibility

- The label is a real `<label>` for the input. Helper and message are its description (`aria-describedby`); the message is announced politely.
- Errors set `aria-invalid`.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `Input.vue` | Built on FormField. |
| iOS (SwiftUI) | — | `TextField` with the label above; the right `textContentType` and keyboard. |
| Android (Compose) | — | `OutlinedTextField`-like field with the label above, not floating. |

## Tokens used

| Token | Used for |
|---|---|
| `color-focus` | Focus ring |
| `color-red` / `color-green` | Error / success |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// Input.vue
export type InputStatus = FormFieldStatus

export interface InputProps {
  /** Visible label. Always set it: it is also the input's accessible name. */
  label: string
  /** Extra guidance about what to enter. */
  helper?: string
  /** Show helper text under the label, or behind a `?` icon next to it. */
  helperPlacement?: 'below' | 'icon'
  /**
   * Error message, e.g. from a Zod / VeeValidate schema. When set (and not
   * empty) the field shows as an error with this text; leave it undefined
   * when the value is valid. Overrides `status`, `statusText` and the length
   * check.
   */
  errorText?: string
  /** Colours the field and the status text. Overrides the length check. */
  status?: InputStatus
  /** Message under the field, e.g. why the value is invalid. */
  statusText?: string
  /** Shows an error once the user leaves a field that is too short. */
  minLength?: number
  /** Shows an error as soon as the value is too long. Typing is not blocked. */
  maxLength?: number
  disabled?: boolean
  class?: HTMLAttributes['class']
}

const model = defineModel<string>({ default: '' })
```

---

# InputNumber

> A number with − and + buttons, e.g. a year group, a quantity or an amount.

- Import: `import { InputNumber } from '@thekestongroup/ui'`
- Group: Form
- Live example: https://ui.keston.co/storybook/?path=/story/components-form-inputnumber--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/InputNumber/InputNumber.vue

## When to use

- Numbers people adjust in small steps, or that have a range: year groups, quantities, amounts of money.

## When not to use

- Numbers that are really identifiers (phone numbers, student IDs, postcodes): use Input. They're never added up, and leading zeros matter.
- A one-time code: use InputCode.

## Anatomy

| Part | Required | Notes |
|---|---|---|
| label, helper, message | — | As every field (FormField). |
| box | Yes | FormField's box, laid out as [ − \| value \| + ]. |
| − / + buttons | Yes | 36px square ends of the box, divided from the value by a black 15% line, like a basic Button. |
| value | Yes | Centred, tabular figures, formatted for the locale. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| modelValue | number \| undefined | — | The number; undefined when empty. |
| label | string | — | Required. |
| helper / helperPlacement | string / below \| icon | — / below | As every field. |
| errorText / status / statusText | | — | As every field. |
| min / max | number | — | The range. The − or + button is disabled at either end. |
| step | number | 1 | How much − / + and the arrow keys change the value. |
| formatOptions | Intl.NumberFormatOptions | — | How it's shown, e.g. `{ style: 'currency', currency: 'GBP' }`. |
| locale | string | browser's | Locale for formatting. |
| disabled | boolean | false | 40% opacity, not editable. |

## States

| State | Appearance | Notes |
|---|---|---|
| At min / max | That end's icon at 40% opacity, button disabled. | |
| Focused | Focus ring around the box. | |
| Error / success | Box border and message coloured. | |
| Disabled | 40% opacity. | |

## Behaviour

- Up / Down arrows step by `step`; Page Up / Page Down by more; Home / End jump to `min` / `max`.
- Typed values are kept within `min` and `max` when the field is left.
- The value is formatted when the field is left, e.g. "12.5" becomes "£12.50".

## Accessibility

- A `spinbutton` named by the label. Its value text is the number as shown (e.g. "9" or "£12.50"); without it, VoiceOver reads a value with a range as a percentage.
- The − / + buttons are labelled "Decrease" and "Increase".

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `InputNumber.vue` | Reka UI NumberField. |
| iOS (SwiftUI) | — | `TextField` with a number format and a `Stepper` beside it. |
| Android (Compose) | — | Number `TextField` with − / + icon buttons. |

## Tokens used

| Token | Used for |
|---|---|
| `color-focus` | Focus ring |
| `color-red` / `color-green` | Error / success |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// InputNumber.vue
export interface InputNumberProps {
  /** Visible label. Always set it: it is also the input's accessible name. */
  label: string
  /** Extra guidance about what to enter. */
  helper?: string
  /** Show helper text under the label, or behind a `?` icon next to it. */
  helperPlacement?: 'below' | 'icon'
  /** Error message, e.g. from a Zod schema. Overrides `status` / `statusText`. */
  errorText?: string
  /** Colours the field and the status text. */
  status?: FormFieldStatus
  /** Message under the field. */
  statusText?: string
  /** Lowest allowed value. The − button is disabled when reached. */
  min?: number
  /** Highest allowed value. The + button is disabled when reached. */
  max?: number
  /** How much − / + and the arrow keys change the value. */
  step?: number
  /** How the number is displayed, e.g. `{ style: 'currency', currency: 'GBP' }`. */
  formatOptions?: Intl.NumberFormatOptions
  /** Locale for formatting. Defaults to the browser's. */
  locale?: string
  disabled?: boolean
  class?: HTMLAttributes['class']
}

/** The number, or undefined when the field is empty. */
const model = defineModel<number | undefined>()
```

---

# InputDate

> A date, typed in almost any form ("26/01/2009", "tmrw", "next friday") or picked from a calendar.

- Import: `import { InputDate } from '@thekestongroup/ui'`
- Group: Form
- Live example: https://ui.keston.co/storybook/?path=/story/components-form-inputdate--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/InputDate/InputDate.vue

## When to use

- Any single date: a date of birth, a due date, an incident date.

## When not to use

- A date shown, not chosen: use RelativeTime or the date helpers.
- Browsing a month to pick from: use Calendar on its own.

## Anatomy

| Part | Required | Notes |
|---|---|---|
| label, helper, message | — | As every field (FormField). |
| text box | Yes | Plain text, placeholder in the locale's order, e.g. dd/mm/yyyy. |
| understood date | No | While words are typed, the date they mean in black 55% at the end, e.g. "tmrw" → 13/11/2026. |
| calendar button | Yes | 36px square at the right end, divided by a black 15% line. Opens Calendar in a popover. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| modelValue | string \| undefined | — | The date as `YYYY-MM-DD`; undefined when empty or not understood. |
| label | string | — | Required. |
| helper / helperPlacement | string / below \| icon | — / below | As every field. |
| errorText / status / statusText | | — | As every field. |
| min / max | string (`YYYY-MM-DD`) | — | The allowed range. Dates outside it are kept but explained. |
| locale | string | en-GB | Day / month / year order and the calendar's language. |
| prefer | future \| past \| nearest | future | How dates without a year, month or week are read ("5th march", "tuesday"). Use `past` for things that already happened. |
| disabled | boolean | false | 40% opacity, not editable. |

## Behaviour

- Understands written dates (26/01/2009, 26 jan 2009, 26th of January), relative days (today, tmrw, the day after tomorrow), weekdays (next tuesday, monday week), parts of time (end of the month, eow), holidays (christmas, easter) and adjustments (in 3 days, 2 weeks from now). Times are ignored.
- The value updates as soon as the text is understood. Leaving the field tidies the text to the full date, e.g. 26/01/2009.
- **Enter:** the first press fills in the full date the text means, without submitting the form. Pressing it again submits as usual.
- Text that isn't a date shows "Enter a date like 26/01/2009" once the field is left.
- A date outside `min` / `max` shows "Choose a date from … to …".
- Choosing a day in the calendar sets it and closes the calendar; it opens on the chosen date, or today.

## Accessibility

- The text box is named by the label; helper and message are its description.
- The calendar button is labelled "Open calendar"; the calendar is fully usable with the keyboard (see Calendar).
- The understood date is hidden from screen readers. They hear the full date when the field is left.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `InputDate.vue` | Typed-date parsing in `src/lib/parseDate.ts`; Reka UI DatePicker for the popover. |
| iOS (SwiftUI) | — | `DatePicker` (compact style); no typed phrases. |
| Android (Compose) | — | Text field plus `DatePickerDialog`. |

## Tokens used

| Token | Used for |
|---|---|
| `color-focus` | Focus ring |
| `color-red` / `color-green` | Error / success |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// InputDate.vue
export interface InputDateProps {
  /** Visible label. Always set it: it is also the field's accessible name. */
  label: string
  /** Extra guidance about what to enter. */
  helper?: string
  /** Show helper text under the label, or behind a `?` icon next to it. */
  helperPlacement?: 'below' | 'icon'
  /** Error message, e.g. from a Zod schema. Overrides `status` / `statusText`. */
  errorText?: string
  /** Colours the field and the status text. */
  status?: FormFieldStatus
  /** Message under the field. */
  statusText?: string
  /** Earliest allowed date, as `YYYY-MM-DD`. */
  min?: string
  /** Latest allowed date, as `YYYY-MM-DD`. */
  max?: string
  /** Sets the order of day / month / year and the calendar's language. */
  locale?: string
  /**
   * How typed dates that don't say which year, month or week are read
   * ("5th march", "the 5th", "tuesday", "christmas"): 'future' (default)
   * picks the next one, 'past' the last one, 'nearest' the closest. Use
   * 'past' for things that already happened, e.g. an incident date.
   */
  prefer?: DatePreference
  disabled?: boolean
  class?: HTMLAttributes['class']
}

/** The date as `YYYY-MM-DD`, or undefined when empty or incomplete. */
const model = defineModel<string | undefined>()
```

---

# InputRichText

> Several lines of text with bold, italic and underline, e.g. notes on a student or an application.

- Import: `import { InputRichText } from '@thekestongroup/ui'`
- Group: Form
- Live example: https://ui.keston.co/storybook/?path=/story/components-form-inputrichtext--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/InputRichText/InputRichText.vue

## When to use

- Notes and comments where people want to stress a word or two.

## When not to use

- A single line: use Input.
- Plain text that's processed or exported (an address, a reason code): a plain text field, as formatting would be lost or get in the way.
- Documents with headings, lists or links: not supported on purpose, so notes look the same everywhere.

## Anatomy

| Part | Required | Notes |
|---|---|---|
| label, helper, message | — | As every field (FormField). |
| box | Yes | FormField's box, holding the toolbar and the text area edge to edge. |
| toolbar | Yes | Bold, Italic, Underline: small square ghost Buttons, 6px padding, black 15% line under it. |
| text area | Yes | 12px / 8px padding, 14px text. At least 4 lines (96px); grows to 15 lines (320px), then scrolls. |
| placeholder | No | Black 55%, in the empty text area. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| modelValue | string (HTML) | '' | Only `<p>`, `<br>`, `<strong>`, `<em>`, `<u>`. Empty is `''`. |
| label | string | — | Required. |
| helper / helperPlacement | string / below \| icon | — / below | As every field. |
| errorText / status / statusText | | — | As every field; `loading` suits saving as you type. |
| placeholder | string | — | e.g. "Add a note…". |
| disabled | boolean | false | 40% opacity, not editable. |

## States

| State | Appearance | Notes |
|---|---|---|
| Format on | Black 15% fill behind the button. | Follows the text at the cursor. |
| Focused | Focus ring around the whole box. | |
| Error / success | Box border and message coloured. | |
| Disabled | 40% opacity. | |

## Behaviour

- ⌘B / ⌘I / ⌘U (Ctrl on Windows and Linux) toggle formatting; ⌘Z undoes.
- Pressing a toolbar button keeps focus and the selection in the text.
- Enter starts a new paragraph (8px apart); Shift+Enter a line break.
- Pasted text keeps bold, italic and underline only.

## Accessibility

- The text area is `role="textbox"` with `aria-multiline`, named by the label; helper and message are its description.
- The toolbar is `role="toolbar"` named "Formatting for {label}". Buttons use `aria-pressed` and `aria-keyshortcuts`, with a Tooltip showing the shortcut.
- Pressing the label focuses the text area.

## Security

The value is HTML from the browser. Sanitise it on the server (allow only `p`, `br`, `strong`, `em`, `u`) before storing or showing it anywhere else.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `InputRichText.vue` | Tiptap (ProseMirror) with only these marks. |
| iOS (SwiftUI) | — | `TextEditor` with `AttributedString` (iOS 26), or a `UITextView` wrapper; formatting from the edit menu and ⌘B / ⌘I / ⌘U. |
| Android (Compose) | — | `BasicTextField` with a rich-text state library; same three marks. |

## Tokens used

| Token | Used for |
|---|---|
| `color-focus` | Focus ring |
| `color-red` / `color-green` | Error / success |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// InputRichText.vue
/**
 * Several lines of text with bold, italic and underline, e.g. notes on a
 * student or an application. Only those three: no headings, lists, links or
 * colours, so notes look the same everywhere. Pasted text keeps its bold,
 * italic and underline and loses everything else.
 *
 * The value is HTML using only <p>, <br>, <strong>, <em> and <u>. Sanitise
 * it on the server like any HTML from a browser before showing it elsewhere.
 */
export interface InputRichTextProps {
  /** Visible label. Always set it: it is also the editor's accessible name. */
  label: string
  /** Extra guidance about what to write. */
  helper?: string
  /** Show helper text under the label, or behind a `?` icon next to it. */
  helperPlacement?: 'below' | 'icon'
  /** Error message, e.g. from a Zod schema. Overrides `status` / `statusText`. */
  errorText?: string
  /** Colours the field and the status text, e.g. 'loading' while it saves. */
  status?: FormFieldStatus
  /** Message under the field. */
  statusText?: string
  /** Shown in the empty editor, e.g. "Add a note…". */
  placeholder?: string
  disabled?: boolean
  class?: HTMLAttributes['class']
}

/** The text as HTML; an empty string when there's nothing in it. */
const model = defineModel<string>({ default: '' })
```

---

# InputPassword

> A password field with a Show / Hide button, for signing in and choosing a password.

- Import: `import { InputPassword } from '@thekestongroup/ui'`
- Group: Form
- Live example: https://ui.keston.co/storybook/?path=/story/components-form-inputpassword--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/InputPassword/InputPassword.vue

## When to use

- Signing in, confirming an action with a password, or choosing a new password.

## When not to use

- One-time codes from an authenticator app, email or SMS: they aren't secret once used, and people need to see what they type.
- Recovery codes, API keys and other secrets that are shown once: show them as text with a copy button.
- Anything that isn't a password: use Input.

## Anatomy

| Part | Required | Notes |
|---|---|---|
| label, helper, message | — | As every field (FormField). |
| box | Yes | FormField's box. |
| leading icon | No | e.g. a lock. |
| input | Yes | Dots while hidden, plain text while shown. |
| toggle | Yes | Square end segment, divided by a black 15% line, like InputNumber's + button. Eye while hidden, eye with a slash while shown. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| modelValue | string | '' | The password. |
| label | string | — | Required. |
| helper / helperPlacement | string / below \| icon | — / below | As every field. Put password rules here when choosing one. |
| errorText / status / statusText | | — | As every field. Each overrides the Caps Lock note. |
| disabled | boolean | false | 40% opacity, not editable, toggle disabled. |
| autocomplete (attribute) | string | current-password | Pass `new-password` when choosing a password. |

## States

| State | Appearance | Notes |
|---|---|---|
| Hidden | Dots, eye icon. | Default. |
| Shown | Plain text, eye-with-slash icon. | Toggle is pressed. |
| Caps Lock on | "Caps Lock is on" under the field, no colour. | While focused, from the first key press. |
| Focused | Focus ring around the whole box. | |
| Error / success | Box border and message coloured. | |
| Disabled | 40% opacity. | |

## Behaviour

- Pressing the toggle shows or hides the password and leaves focus and the caret in the input. It is in the tab order after the input.
- The password is hidden again when its form is submitted.
- Spellcheck, autocorrect and autocapitalise are off, so the password isn't sent to a spelling service or changed while shown.
- Caps Lock can only be detected from a key press, so the note appears on the first key and clears when the field loses focus.

## Accessibility

- The input is named by the label; helper and message are its description.
- The toggle is a button named "Show password" with `aria-pressed` and `aria-controls` pointing at the input.
- The Caps Lock note is announced politely, like every field message.

## Security

- Never prefill the value from the server, or log it.
- Don't block paste: it stops people using password managers.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `InputPassword.vue` | — |
| iOS (SwiftUI) | — | `SecureField` swapped with `TextField` by the toggle; `.textContentType(.password / .newPassword)`. No Caps Lock note. |
| Android (Compose) | — | `TextField` with `PasswordVisualTransformation` and a trailing icon button; `KeyboardType.Password`. No Caps Lock note. |

## Tokens used

| Token | Used for |
|---|---|
| `color-focus` | Focus ring |
| `color-red` / `color-green` | Error / success |

## Do / Don't

| Do | Don't |
|---|---|
| Say what's wrong after a failed sign-in without saying which of email or password it was. | Add a second "confirm password" field: the toggle lets people check what they typed. |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// InputPassword.vue
export type InputPasswordStatus = FormFieldStatus

export interface InputPasswordProps {
  /** Visible label. Always set it: it is also the input's accessible name. */
  label: string
  /** Extra guidance, e.g. the password rules when choosing a new one. */
  helper?: string
  /** Show helper text under the label, or behind a `?` icon next to it. */
  helperPlacement?: 'below' | 'icon'
  /**
   * Error message, e.g. from a Zod / VeeValidate schema or "Incorrect
   * password". When set (and not empty) the field shows as an error with this
   * text. Overrides `status`, `statusText` and the Caps Lock note.
   */
  errorText?: string
  /** Colours the field and the status text. */
  status?: InputPasswordStatus
  /** Message under the field. Overrides the Caps Lock note. */
  statusText?: string
  disabled?: boolean
  class?: HTMLAttributes['class']
}

const model = defineModel<string>({ default: '' })
```

---

# InputCode

> A one-time code from an authenticator app, an email or a text message, with one box per character.

- Import: `import { InputCode } from '@thekestongroup/ui'`
- Group: Form
- Live example: https://ui.keston.co/storybook/?path=/story/components-form-inputcode--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/InputCode/InputCode.vue

## When to use

- Two-step sign-in, confirming an email address or phone number, backup codes.

## When not to use

- Passwords and PINs people choose themselves: use InputPassword.
- Long or variable-length values (reference numbers, IDs): use Input.

## Anatomy

| Part | Required | Notes |
|---|---|---|
| label, helper, message | — | As every field. |
| boxes | Yes | One 40×40px box per character, 8px apart; border like FormField's box. 18px tabular figures, centred. A faint dot in empty boxes. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| modelValue | string | '' | The code so far, e.g. "042317". |
| label | string | — | Required. Say where the code comes from. |
| helper / helperPlacement | string / below \| icon | — / below | e.g. where it was sent and when it expires. |
| length | number | 6 | Number of boxes. |
| alphanumeric | boolean | false | Allow letters (upper-cased). Digits only otherwise. |
| errorText / status / statusText | | — | As every field; `loading` while the code is checked. |
| name | string | — | Sends the code with a native form. |
| disabled | boolean | false | 40% opacity, not editable. |

| Event | Payload | When |
|---|---|---|
| complete | string | Every box is filled. |

## States

| State | Appearance | Notes |
|---|---|---|
| Empty | Faint dot in each box. | |
| Focused | Focus ring around the box being typed in. | |
| Checking | Spinner and message below. | Usually disabled while checking. |
| Error / success | Every box's border and the message coloured. | |
| Disabled | 40% opacity. | |

## Behaviour

- Typing fills a box and moves to the next; Backspace clears and moves back; arrow keys move between boxes.
- Pasting a code, or picking the one the phone's keyboard suggests from a message (`autocomplete="one-time-code"`), fills every box.
- Characters that can't be in the code are ignored. Letters are upper-cased.
- When the last box is filled, `complete` fires: check the code then, with no separate button needed (keep one for people who prefer it).
- After a failed check, clear the boxes so the next attempt starts from the first.

## Content guidelines

- Label: where the code is, e.g. "Code from your authenticator app", "Code from your email".
- Helper: where it was sent (partly hidden) and how long it lasts.
- Error: "That code didn't work. Check it and try again." Don't say whether it was wrong or expired.

## Accessibility

- The boxes are a group named by the label. The first box is named by the label too; the others are "Character 2 of 6" and so on.
- Helper and message describe every box; the message is announced politely.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `InputCode.vue` | Reka UI PinInput. |
| iOS (SwiftUI) | — | One hidden `TextField` with `.textContentType(.oneTimeCode)` drawn as boxes, so SMS autofill works. |
| Android (Compose) | — | One `BasicTextField` drawn as boxes; SMS User Consent / Retriever API for autofill. |

## Tokens used

| Token | Used for |
|---|---|
| `color-focus` | Focus ring |
| `color-red` / `color-green` | Error / success |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// InputCode.vue
export type InputCodeStatus = FieldStatus

export interface InputCodeProps {
  /** Visible label, e.g. "Code from your authenticator app". */
  label: string
  /** Extra guidance, e.g. where the code was sent. */
  helper?: string
  /** Show helper text under the label, or behind a `?` icon next to it. */
  helperPlacement?: 'below' | 'icon'
  /** Number of characters. */
  length?: number
  /** Allow letters as well as digits. Codes are digits only by default. */
  alphanumeric?: boolean
  /**
   * Error message, e.g. "That code didn't work". When set (and not empty)
   * every box shows as an error with this text. Overrides `status` and
   * `statusText`.
   */
  errorText?: string
  /** Colours the boxes and the status text; `loading` while the code is checked. */
  status?: InputCodeStatus
  /** Message under the boxes, e.g. "Checking code…". */
  statusText?: string
  /** Form field name, so the code is sent with a native form. */
  name?: string
  disabled?: boolean
  class?: HTMLAttributes['class']
}

/** The code as one string, e.g. "042317". Shorter while it's being typed. */
const model = defineModel<string>({ default: '' })

const emit = defineEmits<{
  /** Every box is filled: a good moment to submit the code. */
  complete: [code: string]
}>()
```

---

# Select

> Choose one or more options from a list that opens below the field.

- Import: `import { Select } from '@thekestongroup/ui'`
- Group: Form
- Live example: https://ui.keston.co/storybook/?path=/story/components-form-select--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/Select/Select.vue

## When to use

| Use Select for | Use instead |
|---|---|
| One of about 4–30 known options: year group, school, subject | 2–3 options that should all be visible: radio buttons |
| Longer lists (about 10 or more): `searchable` | Lists too long to load, or searched on the server: a server-backed search |
| Several options from a list (`multiple`): subjects, recipients | Several from 2–6 options that should all be visible: checkboxes |
| Trees of options (`children`): Classes › Year 8 › 11Y/En2 › student | Navigating or running actions: a menu |

## Modes

Combine freely, e.g. searchable + multiple + nested.

| Mode | Prop | The field is | Web implementation |
|---|---|---|---|
| Single | — | A button showing the chosen option | Reka UI Select |
| Searchable | `searchable` | A text box that filters the list | Reka UI Combobox |
| Multiple | `multiple` | Chips for the chosen options | Either |
| Nested | `children` on options | (as above) | Either |

## Anatomy

| Part | Required | Notes |
|---|---|---|
| label | Yes | Above the field. Also its accessible name. |
| helper | No | Below the label, or behind a `?` icon. |
| field | Yes | Same box as Input: shows the chosen option (or placeholder) and a chevron. When searchable it is a text box. |
| leading | No | The chosen option's icon, or slot `leading`. |
| list | Yes (when open) | Floating panel with the options, styled like Popover. |
| group heading | No | Small bold uppercase heading, with an optional icon; groups are separated by a line. |
| option | Yes | Label (required), with an optional description under it and an optional icon before it, in any combination. A tick marks the chosen one. |
| back row | Nested only | First row inside a nested level: ‹ and the level's name (bold), then a divider. Goes up one level. |
| chosen chips | Multiple only | A small Chip (20px, 4px corners, with the option's icon) per chosen option, in the field, wrapping onto more lines. When searchable each has × to remove it. |
| empty message | Searchable only | "No matches" when a search finds nothing. |
| status message | No | Error or success message under the field, as on Input. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| label | string | — | Required. |
| modelValue | string \| number, or an array of them when `multiple` (v-model) | — | The chosen value; undefined when nothing is chosen. With `multiple`, the chosen values in the order they were chosen ([] when none). |
| multiple | boolean | false | Choose any number of options. |
| options | (string \| { label, value?, description?, icon?, disabled?, children? })[] | [] | Options in one list. A string is both label and value. Only the label and icon show in the field once chosen. `value` defaults to the label. An option with `children` opens them instead of being chosen. |
| groups | { label?, icon?, options }[] | [] | Options under headings, shown after `options`. |
| searchable | boolean | false | Type in the field to filter the options. |
| placeholder | string | Choose… (Search… when searchable) | Shown when nothing is chosen. |
| emptyText | string | No matches | Shown when a search finds nothing. |
| helper / helperPlacement | string / below \| icon | — / below | As on Input. |
| errorText / status / statusText | | | As on Input. |
| name / required | string / boolean | — | For native form submission and validation. |
| disabled | boolean | false | |

## Sizes

One size, matching Input and a md Button.

| Part | Height | Padding (y / x) | Gap | Icon | Text style |
|---|---|---|---|---|---|
| field | 38px (+24px per extra line of chips) | 8px / 12px | 8px | 16px (70% opacity) | 14px / 20px, regular |
| list panel | up to the space available | 4px | 2px between options | — | — |
| scrollbar | — | — | — | — | Thin system scrollbar when the list scrolls. |
| option | 32px with a label only; 48px with a one-line description (+16px per extra line) | 6px / 8px | 8px | 16px, level with the label | label 14px / 20px (bold when chosen); description 12px / 16px, black 65%, wraps |
| chip (multiple) | 20px | — / 6px | 4px between chips | 12px; × 16px | 12px / 16px, regular |
| label to field | — | — | 6px | — | — |
| group heading | 24px | — / 8px | 6px | 14px, black 65% | 12px / 16px, bold, uppercase, black 65% |
| group divider | 1px | 2px above and below | — | — | black 15%; full width of the panel |

| Panel | Value |
|---|---|
| Minimum width | The field's width |
| Maximum width | 320px, or the field's width if wider; longer text wraps |
| Position | 5px below the field; above it if there's no room below |
| Height | Up to the space available on screen, then scrolls |

## Typography

Lato, sentence case, no letter spacing.

| Text | Size / line height | Weight | Colour |
|---|---|---|---|
| Label, chosen option, option label | 14px / 20px | 400 (option label 700 when chosen) | black `#050505` |
| Placeholder | 14px / 20px | 400 | black 55% |
| Back row | 14px / 20px | 700 | black |
| Option description, search path | 12px / 16px | 400 | black 65% |
| Group heading | 12px / 16px | 700, uppercase | black 65% |
| Chip | 12px / 16px | 400 | black |
| Helper, status message | 12px / 16px | 400 | black 65% / red / green |

## States

| State | Appearance | Notes |
|---|---|---|
| Enabled | White field, black 15% border. Placeholder in black 55%. | |
| Focused | 2px focus ring `#007FC9`, 1px outside the border. | |
| Open | Chevron turns over (150ms); list fades in. | |
| Option highlighted | Black 10% fill. | Mouse hover or arrow keys. |
| Option chosen | Bold, with a tick at the right. | |
| Option disabled | 40% opacity, can't be chosen. | |
| Parent option | › at the right instead of ✓. | Nested. |
| Chip | Black 5% fill, black 15% border; × darkens to black 10% on hover. | Multiple. |
| Error / success | Red / green border and message, as on Input. | |
| Disabled | 40% opacity, not-allowed cursor. | |

## Behaviour

### Keyboard

| Key | Closed | Open |
|---|---|---|
| Enter / Space | Opens | Chooses (Space: not when searchable) |
| ↓ / ↑ | Opens | Moves |
| Home / End | — | First / last option |
| Letters | Chooses the next option starting with them, without opening; searchable: opens and filters | Highlights the next option starting with them; searchable: filters |
| → | — | Opens the highlighted parent (searchable: only while nothing is typed) |
| ← | — | Back one level (searchable: only while nothing is typed) |
| Backspace | — | Searchable multiple, empty search box: removes the last chip |
| Escape / Tab | — | Closes |

### Pointer and choosing

| Action | Single | Multiple |
|---|---|---|
| Press the field | Opens the list | Opens the list |
| Press an option | Chooses it, closes, focus back on the field | Ticks or unticks it; the list stays open |
| Press outside | Closes | Closes |
| × on a chip | — | Removes it (searchable only; without search, untick in the list) |
| v-model | The value, or undefined | An array in the order chosen; `[]` when none |

### Searchable

| Action | Result |
|---|---|
| Type | Opens the list; keeps options whose label or description contains the text, ignoring case and accents |
| Groups with no matches | Hidden, with their divider |
| Nothing matches | "No matches" (`emptyText`) |
| Press or focus the field | Selects its text, so typing replaces it |
| Leave the field | Shows the chosen label again, or clears if nothing is chosen |
| Tick (multiple) | The search clears, ready for the next |

### Nested

| Action | Result |
|---|---|
| Choose a parent (›), or → | Shows its children, with a back row (‹ and the level's name, bold) and a divider at the top |
| Choose the back row, or ← | Goes up one level |
| After opening a level | Highlight on its first option |
| After going back | Highlight on the option just left |
| Reopen | Single: starts at the chosen option's level. Multiple: starts at the top |
| Search | Searches every level; each match shows its path ("Classes › Year 8 › 11Y/En2"); the path is searched too |
| Field | Shows only the chosen label, not its path |

### Shared options

The same option in several places (e.g. a student in two classes) must have the same `value`.

| Where | Result |
|---|---|
| Chosen in one place | Ticked everywhere it appears |
| Field (multiple) | One chip |
| Chosen again anywhere | Unticks it, so it can't be added twice |
| Search | One row, listing every place: "Classes › Year 8 › 11Y/En2 · Classes › Year 8 › 8X/Ma1" |

### Motion

| What | Duration | Easing |
|---|---|---|
| List fades in / out | 150ms | ease-in-out |
| Chevron turns over | 150ms | ease-in-out; none with reduced motion |
| Status message opens / closes | 150ms + 150ms text fade | ease-out (as Input) |

## Content guidelines

| Text | Guideline | Example |
|---|---|---|
| Label | Says what is being chosen | "Year group", not "Select year group" |
| Options | Sentence case, in a sensible order (natural, else alphabetical) | Year 7, Year 8, Year 9 |
| Placeholder | A prompt, never an option | "Choose…", "Search…" |

## Accessibility

| Part | Announced as |
|---|---|
| Field | `combobox` named by `<label for>`: a button, or a text input with `aria-autocomplete="list"` when searchable |
| Helper / status message | Linked with `aria-describedby`; errors set `aria-invalid` |
| List | `listbox` of `option`s; groups named by their heading |
| Parent option | "{label}, more options" |
| Back row | "Back from {level}" |
| Chip × | "Remove {label}" |
| While open | The rest of the page is hidden from screen readers and can't be focused |

| Contrast | Ratio |
|---|---|
| Text on white | 19.5:1 |
| Placeholder (black 55%) on white | about 4.5:1 |
| Focus ring on white | 4.1:1 (minimum 3:1) |

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `Select.vue` (Reka UI Select; Combobox when searchable) | — |
| iOS (SwiftUI) | — | `Picker` with `.menu` style inside a labelled row; searchable: a pushed list with `.searchable`. |
| Android (Compose) | — | `ExposedDropdownMenuBox` (read-only; editable when searchable). |

## Tokens used

| Token | Used for |
|---|---|
| color white, black | field and list background, text |
| color black (15%) | borders, group separators |
| color black (10%) | highlighted option, chip × hover |
| color black (5%) | chip fill |
| color focus | focus ring |
| color red / green | error / success border and message |

## Do / Don't

| Do | Don't |
|---|---|
| Keep lists short enough to scan, make them searchable, or nest them (e.g. year › class › student). | Use a select for 2 options (use radios). |
| Give options with icons a label too. | Put actions ("Add new…") among the options. |
| Give every option in a list an icon, or none. Descriptions can vary per option. | Mix options with and without icons: the labels won't line up, and indenting them makes them look nested. |
| Use the same `value` for the same thing in several places. | Give each copy its own value: it will be treated as a different option. |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// Select.vue
export type SelectValueType = string | number

export interface SelectOption {
  /** Required. Shown in the list and, once chosen, in the field. */
  label: string
  /** What v-model is set to when chosen. Defaults to the label. Not used on options with children. */
  value?: SelectValueType
  /** Smaller grey text under the label, in the list only. Searchable lists match it too. */
  description?: string
  /** A Lucide (or any) icon component, shown before the label (and in the field once chosen). */
  icon?: Component
  disabled?: boolean
  /**
   * Nested options. Choosing this option opens them (with a back row to
   * return) instead of choosing it, e.g. Classes › Year 8 › 11Y/En2 › Ben.
   */
  children?: (SelectOption | string)[]
}

export interface SelectGroupOptions {
  /** Heading above the group's options. */
  label?: string
  /** A Lucide (or any) icon component, shown before the heading. */
  icon?: Component
  options: (SelectOption | string)[]
}

/**
 * Choose one option from a list that opens below the field, e.g. a year
 * group or a school. Looks like Input (same label, helper, status message and
 * box).
 *
 * - Default: built on Reka UI's Select. The field is a button; arrow keys,
 *   Home / End and typing the start of an option move through the list, Enter
 *   / Space choose, Escape closes.
 * - `searchable`: built on Reka UI's Combobox. The field is a text box;
 *   typing filters the options (anywhere in the label, ignoring case and
 *   accents), arrow keys move, Enter chooses. When it loses focus it shows
 *   the chosen option again.
 *
 * Options can be plain strings (label and value the same) or objects with a
 * label and, optionally, a description and an icon; they can be grouped under
 * headings, and nested (`children`): choosing an option with children opens
 * them, with a back row at the top. → / ← also go in and back. Searchable
 * lists search every level and show where each match is.
 *
 * Slots: leading (before the value, replacing the chosen option's icon).
 */
export interface SelectProps {
  /** Visible label. Always set it: it is also the field's accessible name. */
  label: string
  /** Options in a single list. Use `groups` for headings. */
  options?: (SelectOption | string)[]
  /** Groups of options, each with an optional heading. Shown after `options`. */
  groups?: SelectGroupOptions[]
  /** Type in the field to filter the options. Use for lists of more than about 10. */
  searchable?: boolean
  /**
   * Choose any number of options. v-model is then an array, the list stays
   * open while ticking, and the chosen options show as chips in the field
   * (with × to remove them when searchable).
   */
  multiple?: boolean
  /** Shown in the field when nothing is chosen. Default "Choose…", or "Search…" when searchable. */
  placeholder?: string
  /** Shown in the list when a search matches nothing. */
  emptyText?: string
  /** Extra guidance about what to choose. */
  helper?: string
  /** Show helper text under the label, or behind a `?` icon next to it. */
  helperPlacement?: 'below' | 'icon'
  /** Error message, e.g. from a Zod schema. Overrides `status` / `statusText`. */
  errorText?: string
  /** Colours the field and the status text. */
  status?: FormFieldStatus
  /** Message under the field. */
  statusText?: string
  /** Form field name: adds a hidden native field so the value is submitted with a form. */
  name?: string
  /** Must be chosen before a form can be submitted. */
  required?: boolean
  disabled?: boolean
  class?: HTMLAttributes['class']
}

defineSlots<{
  leading?(): unknown
}>()

/** The chosen option's value, or undefined when nothing is chosen. */
const model = defineModel<SelectValueType | SelectValueType[] | undefined>()
```

---

# Checkbox

> A yes / no answer that's sent with a form, e.g. "Has a sibling at the school" or agreeing to terms.

- Import: `import { Checkbox } from '@thekestongroup/ui'`
- Group: Form
- Live example: https://ui.keston.co/storybook/?path=/story/components-form-checkbox--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/Checkbox/Checkbox.vue

## When to use

- A single yes / no question in a form, saved with the form's Save or Submit.
- Agreeing to something before continuing.
- "Select all" over a list of other checkboxes (with the indeterminate state).

## When not to use

- A setting that takes effect straight away: use Switch.
- One choice from a few: use RadioGroup. Several choices from a long list: use Select with `multiple`.
- Showing progress people don't tick themselves: use Checklist.

## Anatomy

| Part | Required | Notes |
|---|---|---|
| box | Yes | 16px square, 4px corners, 1px border. Ticked: primary fill, white tick. |
| label | Yes | Beside the box. Pressing it ticks the box too. |
| description | No | Smaller text under the label. |
| message | No | Error text under it all, sliding open like a field's. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| modelValue | boolean \| 'indeterminate' | false | Ticked or not; 'indeterminate' shows a dash. |
| label | string | — | Required. Also the accessible name. |
| description | string | — | |
| errorText | string | — | Shows the error state and message. |
| name / value | string | — / "on" | For native form submission. |
| required | boolean | false | |
| disabled | boolean | false | |

No sizes or variants.

## States

| State | Appearance | Notes |
|---|---|---|
| Unticked | White box, black 55% border. | Darker than a text box's border, so the box meets 3:1 contrast. |
| Hovered | Black border. | Web / desktop only. |
| Ticked | Primary fill and border, white tick. | |
| Indeterminate | Primary fill and border, white dash. | Pressing it ticks it. |
| Focused | 2px focus ring, 2px out. | Keyboard only. |
| Error | Red border, red message with icon. | |
| Disabled | 40% opacity. | |

## Spacing and layout

- Box to label: 8px. Label to description: 2px. The box is 2px down, level with the label's first line (20px).
- Stacked checkboxes: 8px apart. Children of a "select all": indented 24px (box + gap).

## Behaviour

- Space ticks / unticks. Pressing the box or label does the same.
- The whole row is pressable: the box, its label and its description. The description is not part of the accessible name; it stays the description.

## Accessibility

- Native semantics: `role="checkbox"` with `aria-checked` (`mixed` when indeterminate), named by its `<label>`.
- Description and error are linked with `aria-describedby`; errors set `aria-invalid` and are announced.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `Checkbox.vue` | Reka UI `Checkbox`. |
| iOS (SwiftUI) | — | `Toggle` with a checkbox style (iOS has no native checkbox). |
| Android (Compose) | — | `Checkbox` / `TriStateCheckbox` in a row with the label. |

## Tokens used

| Token | Used for |
|---|---|
| `color-primary` | Ticked fill and border |
| `color-red` | Error border and text |
| `color-focus` | Focus ring |

## Do / Don't

| Do | Don't |
|---|---|
| Word the label so ticked means yes ("Send reminders"). | Use negatives ("Don't send reminders"). |
| Use one checkbox per question. | Use two checkboxes for "Yes" and "No": that's a RadioGroup. |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// Checkbox.vue
/**
 * A yes / no answer that's sent with the form, e.g. "Has a sibling at the
 * school" or agreeing to terms. For a setting that takes effect straight
 * away, use Switch; for one choice from a few, use RadioGroup.
 */
export interface CheckboxProps {
  /** Visible label, beside the box. Pressing it ticks the box too. */
  label: string
  /** More detail, in smaller text under the label. */
  description?: string
  /**
   * Error message, e.g. "Agree to the terms to continue". When set (and not
   * empty) the box shows as an error with this text.
   */
  errorText?: string
  /** Name for native form submission. */
  name?: string
  /** Value sent with the form when ticked. Default "on". */
  value?: string
  required?: boolean
  disabled?: boolean
  class?: HTMLAttributes['class']
}

/**
 * Ticked or not. 'indeterminate' shows a dash: for a "select all" box when
 * only some of its items are ticked. Pressing it then ticks it.
 */
const model = defineModel<boolean | 'indeterminate'>({ default: false })
```

---

# RadioGroup

> One choice from a few options that people should see side by side.

- Import: `import { RadioGroup } from '@thekestongroup/ui'`
- Group: Form
- Live example: https://ui.keston.co/storybook/?path=/story/components-form-radiogroup--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/RadioGroup/RadioGroup.vue

## When to use

- Two to five options, when seeing them all helps the choice, e.g. "Mark as leavers" / "Keep on roll".

## When not to use

- More than five options, or a minor choice: use Select.
- A yes / no question: use Checkbox (in a form) or Switch (a setting).

## Anatomy

| Part | Required | Notes |
|---|---|---|
| label | Yes | The question, above the options. The group's accessible name. |
| helper | No | Under the label, or behind a `?` (InfoTip) beside it. |
| option | Yes | A 16px circle, its label and optional description. The chosen one has an 8px primary dot. |
| message | No | Error text under the options. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| modelValue | string \| number | — | The chosen option's value; undefined until one is chosen. |
| label | string | — | Required. |
| options | { label, value, description?, disabled? }[] | — | Required. |
| helper | string | — | |
| helperPlacement | below \| icon | below | As on every field. |
| errorText | string | — | |
| name | string | — | For native form submission. |
| required / disabled | boolean | false | |

Options always stack vertically: no horizontal layout, so labels and descriptions never crowd.

## States

| State | Appearance | Notes |
|---|---|---|
| Not chosen | White circle, black 55% border. | |
| Hovered | Black border. | Web / desktop only. |
| Chosen | Primary border and dot. | |
| Focused | 2px focus ring, 2px out. | Keyboard only. |
| Error | Red borders, red message with icon. | |
| Disabled | 40% opacity: the whole group, or one option. | |

## Spacing and layout

- Label to helper: 2px. Label block to options: 6px. Options: 8px apart. Circle to option label: 8px.

## Behaviour

- Tab moves into the group (to the chosen option, or the first) and out again; the arrow keys move and choose.
- The whole row is pressable: the circle, its label and its description. The description is not part of the accessible name; it stays the description.
- Once chosen, an option can't be unchosen: start with nothing chosen if "none" isn't a valid answer, or add a "None" option.

## Accessibility

- `role="radiogroup"` named by the label (`aria-labelledby`), described by helper and error; `aria-invalid` on error.
- Each option is `role="radio"`, named by its `<label>`, described by its description.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `RadioGroup.vue` | Reka UI `RadioGroup`. |
| iOS (SwiftUI) | — | `Picker` with `.inline` style in a Form. |
| Android (Compose) | — | `RadioButton` rows with `Modifier.selectableGroup()`. |

## Tokens used

| Token | Used for |
|---|---|
| `color-primary` | Chosen border and dot |
| `color-red` | Error |
| `color-focus` | Focus ring |

## Do / Don't

| Do | Don't |
|---|---|
| Keep option labels short, with detail in `description`. | Put a paragraph in the label. |
| Order options logically (most common first, or a natural order). | Order them at random. |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// RadioGroup.vue
/**
 * One choice from a few (two to five) that people should see side by side,
 * e.g. "Mark as leavers" or "Keep on roll". For more options, or when the
 * choice is less important than the space it takes, use Select.
 */
export type RadioValue = string | number

export interface RadioOption {
  label: string
  value: RadioValue
  /** More detail, in smaller text under the label. */
  description?: string
  disabled?: boolean
}

export interface RadioGroupProps {
  /** The question, above the options. Also the group's accessible name. */
  label: string
  options: RadioOption[]
  /** Extra guidance about the choice. */
  helper?: string
  /** Show helper text under the label, or behind a `?` icon next to it. */
  helperPlacement?: 'below' | 'icon'
  /** Error message, e.g. "Choose what happens to Year 13". */
  errorText?: string
  /** Name for native form submission. */
  name?: string
  required?: boolean
  disabled?: boolean
  class?: HTMLAttributes['class']
}

/** The chosen option's value; undefined until one is chosen. */
const model = defineModel<RadioValue | undefined>()
```

---

# Switch

> Turns a setting on or off straight away, with no Save button.

- Import: `import { Switch } from '@thekestongroup/ui'`
- Group: Form
- Live example: https://ui.keston.co/storybook/?path=/story/components-form-switch--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/Switch/Switch.vue

## When to use

- Settings and preferences that apply as soon as they're flipped, e.g. "Email me when an application arrives".

## When not to use

- A yes / no answer saved with a form: use Checkbox. Mixing the two in one form makes people unsure what's saved.

## Anatomy

| Part | Required | Notes |
|---|---|---|
| track | Yes | 36 × 20px, fully rounded. Off: black 45%. On: primary. |
| thumb | Yes | 16px white circle, slides 16px. |
| label | Yes | Beside the switch. Pressing it flips the switch too. |
| description | No | Smaller text under the label. |
| message | No | How saving went: "Saving…", "Saved", or an error. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| modelValue | boolean | false | On or off. |
| label | string | — | Required. |
| description | string | — | |
| errorText | string | — | Overrides `status` / `statusText`. |
| status | error \| success \| loading | — | As the change saves immediately, show how it went. |
| statusText | string | — | |
| name | string | — | |
| disabled | boolean | false | |

## States

| State | Appearance | Notes |
|---|---|---|
| Off | Black 45% track, thumb at the left. | Dark enough to meet 3:1 contrast. |
| On | Primary track, thumb at the right. | |
| Hovered | Off: black 55% track. | Web / desktop only. |
| Focused | 2px focus ring, 2px out. | Keyboard only. |
| Saving | Spinner and "Saving…" under it. | `status="loading"`. |
| Error | Red message; put the switch back if the save failed. | |
| Disabled | 40% opacity. | |

## Spacing and layout

- Switch to label: 8px. The switch sits on the left, like Checkbox, so a column of settings lines up.
- A list of settings: 16px apart.

## Behaviour

- Space or Enter flips it. The thumb slides in 150ms (none with reduced motion).
- The whole row is pressable: the switch, its label and its description. The description is not part of the accessible name; it stays the description.
- Save on change. If saving fails, put the switch back and say so.

## Accessibility

- `role="switch"` with `aria-checked`, named by its `<label>`; description and status linked with `aria-describedby`, status announced politely.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `Switch.vue` | Reka UI `Switch`. |
| iOS (SwiftUI) | — | `Toggle` (switch on the right, as iOS expects). |
| Android (Compose) | — | `Switch` in a row with the label. |

## Tokens used

| Token | Used for |
|---|---|
| `color-primary` | On track |
| `color-white` | Thumb |
| `color-focus` | Focus ring |

## Do / Don't

| Do | Don't |
|---|---|
| Label the setting, not the action ("Weekly summary"). | Write "Turn on weekly summary". |
| Show "Saving…" and confirm. | Leave people wondering whether it saved. |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// Switch.vue
/**
 * Turns a setting on or off straight away, with no Save button, e.g. "Email
 * me when an application arrives". For an answer that's sent with a form,
 * use Checkbox.
 *
 * As the change saves immediately, it can show how that went: `status`
 * 'loading' with "Saving…", then 'success' or 'error'.
 */
export interface SwitchProps {
  /** Visible label, beside the switch. Pressing it flips the switch too. */
  label: string
  /** More detail, in smaller text under the label. */
  description?: string
  /** Error message. Overrides `status` and `statusText`. */
  errorText?: string
  /** Colours the status text: e.g. 'loading' while the change saves. */
  status?: FieldStatus
  /** Message under the switch, e.g. "Saving…" or "Couldn't save. Try again." */
  statusText?: string
  /** Name for native form submission. */
  name?: string
  disabled?: boolean
  class?: HTMLAttributes['class']
}

/** On or off. */
const model = defineModel<boolean>({ default: false })
```

---

# Calendar

> A month of days to choose one from, with the month and year opening grids of months and years.

- Import: `import { Calendar } from '@thekestongroup/ui'`
- Group: Form
- Live example: https://ui.keston.co/storybook/?path=/story/components-form-calendar--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/Calendar/Calendar.vue

## When to use

- On a page where the date is the main thing, e.g. choosing an interview day with that day's details beside it.
- InputDate uses it in its popover; most forms should use InputDate.

## When not to use

- A date field in a form: use InputDate (people can type, and it's compact).
- Dates far from today, like a date of birth: use InputDate; typing is quicker.

## Anatomy

| Part | Required | Notes |
|---|---|---|
| heading | Yes | ‹ previous, month ▾ and year ▾ buttons, › next. |
| day grid | Yes | Weekday names, then 6 weeks of 32px days, starting Monday. |
| month / year grid | — | 3 × 4 grids of 48px-tall cells, shown from the heading. |

No frame: put it in a Card (or a popover, as InputDate does).

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| modelValue | string (`YYYY-MM-DD`) | — | The chosen date. |
| min / max | string (`YYYY-MM-DD`) | — | Days, months and years outside are greyed out. |
| locale | string | en-GB | Names of days and months. |
| initialFocus | boolean | false | Focus the chosen day (or today) when it appears. |
| disabled | boolean | false | |

## States

| State | Appearance | Notes |
|---|---|---|
| Day | Black text; days outside the month 35%. | |
| Hovered | Black 10% fill. | |
| Chosen | Primary fill, white text. | |
| Today | Bold, with a 4px dot underneath. | Also on today's month and year. |
| Unavailable | 25% text. | Outside min / max. |
| Focused | 2px focus ring. | Keyboard only. |

## Behaviour

- Arrow keys move between days, Page Up / Down between months; Enter or Space chooses.
- Opens on the chosen date, else today, else the nearest allowed month.
- Picking a month or year goes back to the days.

## Accessibility

- A grid of buttons with full dates as names; today is `aria-current="date"`.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `Calendar.vue` | Reka UI `Calendar`. |
| iOS (SwiftUI) | — | `DatePicker` with `.graphical` style. |
| Android (Compose) | — | `DatePicker` (Material 3). |

## Tokens used

| Token | Used for |
|---|---|
| `color-primary` | Chosen day, month, year |
| `color-focus` | Focus ring |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// Calendar.vue
/**
 * A month of days to pick one from, with the month and year in the heading
 * opening grids of months and years. InputDate shows it in a popover; on its
 * own it suits a page where the date is the main thing, e.g. choosing an
 * interview day. It has no frame: put it in a Card.
 */
export interface CalendarProps {
  /** Earliest allowed date, as `YYYY-MM-DD`. */
  min?: string
  /** Latest allowed date, as `YYYY-MM-DD`. */
  max?: string
  /** Sets the weekday names, month names and the calendar's language. */
  locale?: string
  /** Move focus to the chosen day (or today) when the calendar appears. */
  initialFocus?: boolean
  disabled?: boolean
  class?: HTMLAttributes['class']
}

/** The date as `YYYY-MM-DD`, or undefined when none is chosen. */
const model = defineModel<string | undefined>()
```

---

# Table

> Rows of data with column headings, which people can sort: applicants, classes, invoices.

- Import: `import { Table } from '@thekestongroup/ui'`
- Group: Data
- Live example: https://ui.keston.co/storybook/?path=/story/components-data-table--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/Table/Table.vue

## When to use

| Use a Table for | Use instead |
|---|---|
| Many records with the same fields, to compare or scan | One record's details (SummaryList) |
| Data people sort or look across by column | A few items with mixed content (a list in a Card) |
| Totals under a list of amounts | A single headline number (StatTile) |

## Anatomy

| Part | Required | Notes |
|---|---|---|
| scroll area | Yes | Scrolls sideways when the columns don't fit; up and down too with a max height. |
| caption | Recommended | Names the table. Hidden unless `showCaption`. |
| header row | Yes | Column headings, black 65%, bold. Sortable ones are buttons with a sort icon. |
| rows | Yes | One per record, with a line between. |
| row header | No | One column (usually the first, e.g. a name) can head its row. Bold. |
| footer | No | Rows in a `<tfoot>`, e.g. totals. Bold, with a line above. |
| empty / loading | No | One centred row when there are no rows. |

No border or background of its own: put it in a `Card` with `padding="none"`.

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| columns | TableColumn[] | — | Required. See Columns. |
| rows | object[] | — | Required. |
| rowKey | string \| (row, index) => key | index | A unique field, so rows stay stable when sorted. |
| caption | string | — | The table's accessible name. |
| showCaption | boolean | false | Show the caption above the table. |
| sort | { key, direction } \| null | null | `v-model:sort`. |
| manualSort | boolean | false | Only report the sort (e.g. to sort on the server); don't re-order rows. |
| size | md \| sm | md | See Sizes. |
| stickyHeader | boolean | false | Keep the headings in view. Give the table a max height. |
| loading | boolean | false | No rows: a spinner. With rows: rows dimmed to 50%. |
| emptyText | string | "Nothing to show." | Slot `empty` for richer content. |
| ui | { table, header, row } | — | Extra classes per part. |

## Columns

| Field | Type | Default | Description |
|---|---|---|---|
| key | string | — | Required. The field shown, and the slot name `cell-{key}`. |
| label | string | — | Required. Heading text. |
| hideLabel | boolean | false | Heading read out but not shown, e.g. an actions column. |
| align | start \| end | start | End for numbers and amounts, so digits line up (they also use tabular figures). |
| sortable | boolean | false | Heading becomes a sort button. |
| sortValue | (row) => value | `row[key]` | What to sort by, e.g. a date's timestamp. |
| rowHeader | boolean | false | Cells are row headings (`<th scope="row">`). One column at most. |
| nowrap | boolean | true | Keep cells on one line. Turn off for long text. |
| class | string | — | Extra classes for the column, e.g. a width. |

## Sizes

| Size | Cell padding | Row height (one line) |
|---|---|---|
| md | 16px sides, 12px top and bottom | 44px |
| sm | 16px sides, 8px top and bottom | 36px |

| Part | Value |
|---|---|
| Text | 14px / 20px; headings bold, black 65%; the sorted heading black |
| Sort icon | 16px, 4px after the label; unsorted black 40% |
| Lines | 1px black 15%, under the header and between rows (not after the last) |
| Empty / loading row | 32px top and bottom, centred, black 65% |

## Sorting

| Action | Result |
|---|---|
| Click a sortable heading | Ascending, then descending, then back to the original order |
| Text | Natural order ("Year 2" before "Year 10"), ignoring case |
| Empty values | Last, whichever direction |
| Ties | Keep their original order |

## States

| State | Appearance |
|---|---|
| Heading hover | Text goes from black 65% to black |
| Heading focused | 2px focus ring `#007FC9`, 1px outside (keyboard only) |
| Scroll area focused | The same ring, 2px inside the edge so a Card's corners don't clip it (only when it scrolls) |
| Loading, no rows | 16px spinner and "Loading…" |
| Loading, with rows | Rows at 50% opacity |

## Accessibility

| Part | Announced as |
|---|---|
| Table | `table`, named by its caption; `aria-busy` while loading |
| Sortable heading | `columnheader` with `aria-sort` (none / ascending / descending), containing a button named by the label |
| Row header cells | `rowheader`, so each cell is read with its row's name |
| Scroll area (when it scrolls) | `region` named by the caption, focusable so the keyboard can scroll it |
| Icon-only cells (e.g. a ⋯ menu) | Name the button with the row, e.g. "More for Amelia Clarke" |

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `Table.vue` | — |
| iOS (SwiftUI) | — | `Table` on iPad and Mac; a `List` of rows on iPhone. |
| Android (Compose) | — | A `LazyColumn` of rows; columns become label / value pairs on phones. |

## Tokens used

| Token | Used for |
|---|---|
| color black | text, sorted heading |
| color black (65%) | headings, empty text |
| color black (40%) | unsorted icon |
| color black (15%) | lines |
| color white | sticky header background |
| color focus | focus rings |

## Do / Don't

| Do | Don't |
|---|---|
| Give every table a caption | Rely on the surrounding heading alone |
| Right-align numbers and amounts | Centre-align columns |
| Make the name column the row header | Make a whole row clickable with no link or button in it |
| Use slots for Badges, links and menus | Put more than one or two actions in a row |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// Table.vue
/**
 * Rows of data with column headings: applicants, classes, invoices.
 *
 * No border or background of its own: put it in a `<Card padding="none">`,
 * which gives the white panel, and the table runs to its edges.
 *
 * Cells show `row[column.key]` as text. For anything else (a Badge, a link,
 * a menu) use the slot `#cell-{key}`, which gets `{ row, value, index }`.
 *
 * Sorting: mark columns `sortable`. The table sorts the rows itself; with
 * `manualSort` it only reports the sort (`v-model:sort`) so you can sort on
 * the server.
 *
 * Slots: cell-{key}, header-{key}, empty, footer (rows for a `<tfoot>`,
 * e.g. totals), caption.
 */
export interface TableProps<Row = Record<string, any>> {
  columns: TableColumn<Row>[]
  rows: Row[]
  /** Unique field on each row, or a function returning one. Used to keep rows stable when sorting. */
  rowKey?: keyof Row & string | ((row: Row, index: number) => string | number)
  /**
   * What the table shows, e.g. "Applications for September 2027". The
   * table's accessible name. Hidden unless `showCaption`.
   */
  caption?: string
  showCaption?: boolean
  /** Shown when there are no rows. */
  emptyText?: string
  /** Show a spinner (no rows yet), or dim the rows (refreshing). */
  loading?: boolean
  /** md (default) 12px above and below each cell, sm 8px for dense tables. */
  size?: 'sm' | 'md'
  /** Keep the header row in view while the table scrolls. Give the table a max height (`class="max-h-96"`). */
  stickyHeader?: boolean
  /** Don't sort the rows: just update `sort`, e.g. to sort on the server. */
  manualSort?: boolean
  class?: HTMLAttributes['class']
  ui?: {
    table?: HTMLAttributes['class']
    header?: HTMLAttributes['class']
    row?: HTMLAttributes['class']
  }
}

const sort = defineModel<TableSort | null>('sort', { default: null })

defineSlots<
  {
    caption?(): unknown
    empty?(): unknown
    footer?(): unknown
  } & {
    [key: `cell-${string}`]: ((props: { row: Row; value: any; index: number }) => unknown) | undefined
  } & {
    [key: `header-${string}`]: ((props: { column: TableColumn<Row> }) => unknown) | undefined
  }
>()

// table.ts
export type SortDirection = 'asc' | 'desc'

export interface TableSort {
  key: string
  direction: SortDirection
}

export interface TableColumn<Row = Record<string, unknown>> {
  /** Field on each row, and the name of the cell slot (`#cell-{key}`). */
  key: string
  /** Header text. */
  label: string
  /**
   * Visually hide the header (it's still read out), e.g. for an actions
   * column. The label is still required.
   */
  hideLabel?: boolean
  /** start (default) or end. Use end for numbers, so the digits line up. */
  align?: 'start' | 'end'
  /** Let people sort by this column. */
  sortable?: boolean
  /** What to sort by, when it isn't `row[key]` (e.g. a date's timestamp). */
  sortValue?: (row: Row) => unknown
  /** The row's heading: its first cell is a `<th scope="row">`. One column at most. */
  rowHeader?: boolean
  /** Keep the text on one line. Default true; turn off for long text. */
  nowrap?: boolean
  /** Extra classes for this column's header and cells, e.g. a width. */
  class?: string
}

/**
 * Sorts a copy of `rows`. Stable, so rows that tie keep their order. Text
 * sorts naturally ("Year 2" before "Year 10") and ignores case; empty values
 * go last in both directions.
 */
export function sortRows<Row>(rows: readonly Row[], columns: readonly TableColumn<Row>[], sort?: TableSort | null): Row[] { … }

/** Clicking a header: ascending, then descending, then back to unsorted. */
export function nextSort(current: TableSort | null | undefined, key: string): TableSort | null { … }
```

---

# StatTile

> One number that matters, in a small Card, with how it's changed.

- Import: `import { StatTile } from '@thekestongroup/ui'`
- Group: Data
- Live example: https://ui.keston.co/storybook/?path=/story/components-data-stattile--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/StatTile/StatTile.vue

## When to use

| Use a StatTile for | Use instead |
|---|---|
| Headline numbers at the top of a dashboard or app page | Several figures inside one card (SummaryList, `compact`) |
| A number with a trend ("+12% on last year") | A number over time (a chart) |

## Anatomy

| Part | Required | Notes |
|---|---|---|
| container | Yes | A Card with `padding="sm"`. |
| icon | No | 16px, before the label. Decorative. |
| label | Yes | What the number is. |
| value | Yes | The number. Shows "—" if missing. |
| change | No | Arrow, the change in bold, then what it's against, coloured by sentiment. |
| description | No | A sentence under the value. |
| footer | No | e.g. a "View all" link. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| label | string | — | Required. |
| value | string \| number | — | Already formatted ("1,204", "96%"). Slot `value` for a unit in smaller text. |
| icon | Component | — | |
| change | string | — | Already formatted, with its sign ("+12%", "−3"). |
| changeLabel | string | — | e.g. "on last year". |
| trend | up \| down \| flat | — | Sets the arrow. |
| sentiment | positive \| negative \| neutral | from trend | Sets the colour. Up is positive and down negative by default; set it when down is good (absences). |
| description | string | — | |

## Sizes

| Part | Value |
|---|---|
| Padding | 16px |
| Label | 14px / 20px, black 65%; icon 16px, 8px gap |
| Value | 24px / 32px, bold, tabular figures |
| Change | 14px; 16px arrow, 2px gap; 8px after the value, wraps under it when narrow |
| Gap between rows | 4px; footer 8px more |

## States

| Sentiment | Colour | Contrast on white |
|---|---|---|
| positive | green `#007A16` | 5.2:1 |
| negative | red `#D2042D` | 5.0:1 |
| neutral | black 65% | 6.5:1 |

## Accessibility

| Part | Announced as |
|---|---|
| Label, value | Text, in reading order (label first) |
| Arrow | Hidden; the direction is read as "Up", "Down" or "No change" before the change |
| Colour | Never the only signal: the sign and the arrow say it too |

## Layout

| Rule | Value |
|---|---|
| In a row | A grid: 1 column on phones, 2–4 as space allows, 16px gap |
| How many | 3–4 per row; more and none stands out |

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `StatTile.vue` | — |
| iOS (SwiftUI) | — | A `GroupBox` with `LabeledContent`; a `Gauge` for percentages. |
| Android (Compose) | — | An `OutlinedCard` with the same parts. |

## Tokens used

| Token | Used for |
|---|---|
| color green | positive change |
| color red | negative change |
| color black (65%) | label, neutral change, description |

## Do / Don't

| Do | Don't |
|---|---|
| Say what the change is against ("on last year") | Show a percentage with no comparison |
| Set `sentiment` when down is good | Let a fall in absences show red |
| Format numbers before passing them | Show "1204.0000" |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// StatTile.vue
/**
 * One number that matters, in a small Card: "Open applications 48".
 * Put several in a grid. Optionally with how it's changed ("+12% on last
 * year") and a short description.
 *
 * Slots: value (e.g. a value with a unit in smaller text), description,
 * footer (e.g. a "View all" link).
 */
export interface StatTileProps {
  /** What the number is, e.g. "Open applications". */
  label: string
  /** The number, already formatted, e.g. "1,204" or "96%". */
  value?: string | number
  /** Icon before the label. Decorative. */
  icon?: Component
  /** How it's changed, already formatted, e.g. "+12%" or "−3". */
  change?: string
  /** What the change is against, e.g. "on last year". Read after the change. */
  changeLabel?: string
  /** Which way it went. Sets the arrow. */
  trend?: 'up' | 'down' | 'flat'
  /**
   * Whether the change is good, which sets the colour: green good, red bad,
   * grey neutral. Defaults to up good, down bad, flat neutral. Set it when
   * down is good, e.g. absences.
   */
  sentiment?: 'positive' | 'negative' | 'neutral'
  /** Grey text under the value. */
  description?: string
  class?: HTMLAttributes['class']
}

defineSlots<{
  value?(): unknown
  description?(): unknown
  footer?(): unknown
}>()
```

---

# SummaryList

> Labelled values: a record's details, figures in a summary, or answers to check before submitting.

- Import: `import { SummaryList } from '@thekestongroup/ui'`
- Group: Data
- Live example: https://ui.keston.co/storybook/?path=/story/components-data-summarylist--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/SummaryList/SummaryList.vue

## When to use

| Use a SummaryList for | Use instead |
|---|---|
| One record's details ("Email: …", "Year group: …") | Many records (Table) |
| Checking answers before submitting, with a Change per row | Editing (form fields) |
| A few figures in a summary card (`compact`) | One headline number (StatTile) |

## Layouts

| Layout | Looks like | Use for |
|---|---|---|
| rows (default) | Label left, value beside it, a line between rows. Label above value when the container is under 384px. | Details, check your answers |
| compact | Label left, value right-aligned and bold, no lines | Figures in a sidebar or summary card |
| stacked | Label above value; 1 column, 2 from 384px, 3 from 672px (container width) | Lots of short facts |

## Anatomy

| Part | Required | Notes |
|---|---|---|
| label | Yes | Black 65%. |
| value | Yes | Text, or the `value` slot (Badge, link). Empty shows "—". |
| description | No | Grey text under the value. |
| action | No | Slot, e.g. a "Change" button, at the end of the row. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| items | { label, value?, description?, emphasis? }[] | — | Required. `emphasis` makes the value bold, e.g. a total. |
| layout | rows \| compact \| stacked | rows | |
| labelWidth | sm \| md \| lg | md | Label column in `rows`: 128 / 192 / 256px. |
| emptyLabel | string | "Not set" | What screen readers hear for an empty value. |

## Sizes

| Part | Value |
|---|---|
| Text | 14px / 20px |
| rows | 12px above and below each row; the first and last flush with the container; 16px between columns; 4px label to value when stacked |
| compact | 8px between rows, 16px between columns |
| stacked | 4px label to value; 16px between rows, 24px between columns |
| Lines (rows) | 1px black 15% |
| Empty value | "—", black 40% |

## Accessibility

| Part | Announced as |
|---|---|
| List | Description list (`<dl>`), each label a term and each value its definition |
| Pairs | Each pair is wrapped together, so they're read together |
| Empty value | "Not set" (the dash is hidden) |
| Change action | Add the row to the button's name, e.g. `Change<span class="sr-only"> email</span>` |

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `SummaryList.vue` | — |
| iOS (SwiftUI) | — | `LabeledContent` rows in a `Form` or `List` section. |
| Android (Compose) | — | `ListItem` with `overlineContent` (label) and `headlineContent` (value). |

## Tokens used

| Token | Used for |
|---|---|
| color black | values |
| color black (65%) | labels, descriptions |
| color black (40%) | empty dash |
| color black (15%) | lines |

## Do / Don't

| Do | Don't |
|---|---|
| Keep labels short and values scannable | Put paragraphs in values |
| Use `compact` for numbers, so they line up on the right | Use `compact` for long text values |
| Say which row a Change button is for | Have several "Change" buttons with the same name |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// SummaryList.vue
/**
 * Labelled values, e.g. a record's details or a summary before you submit:
 * "Email  office@keston.school". A description list (`<dl>`) underneath.
 *
 * Layouts:
 * - rows (default): label on the left, value beside it, a line between rows.
 *   Stacks the label above the value when the container is narrow (under
 *   384px). With an action per row (e.g. Change) for check-your-answers pages.
 * - compact: label left, value right-aligned, no lines. For figures in a
 *   sidebar or summary card ("Moving up a year  1,204").
 * - stacked: label above value, in a grid of up to 3 columns as space
 *   allows. For a lot of short facts.
 *
 * Slots: value (scoped `{ item, index }`, for a Badge, link, etc.), action
 * (scoped, e.g. a Change button).
 */
export interface SummaryListItem {
  label: string
  /** Shown as text. Empty shows "—" (read as "Not set"). Use the value slot for anything richer. */
  value?: string | number | null
  /** Smaller grey text under the value. */
  description?: string
  /** Bold value, e.g. a total. */
  emphasis?: boolean
}

export interface SummaryListProps<Item extends SummaryListItem = SummaryListItem> {
  items: Item[]
  layout?: 'rows' | 'compact' | 'stacked'
  /** Width of the label column in the rows layout. */
  labelWidth?: 'sm' | 'md' | 'lg'
  /** What an empty value is read as. */
  emptyLabel?: string
  class?: HTMLAttributes['class']
}

defineSlots<{
  value?(props: { item: Item; index: number }): unknown
  action?(props: { item: Item; index: number }): unknown
}>()
```

---

# Checklist

> Steps towards something, ticked off as they're done.

- Import: `import { Checklist } from '@thekestongroup/ui'`
- Group: Data
- Live example: https://ui.keston.co/storybook/?path=/story/components-data-checklist--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/Checklist/Checklist.vue

## When to use

- Showing what's left before a form can be submitted, or a setup's progress (e.g. New School Year Setup's summary).

## When not to use

- Things people tick themselves: use Checkbox.
- A sequence people move through page by page: a stepper (not in the library yet).

## Anatomy

| Part | Required | Notes |
|---|---|---|
| item | Yes | An icon and a label. |
| icon | Yes | Done: green circled tick. To do: empty grey circle. 16px. |
| label | Yes | Done: black. To do: black 65%. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| items | { label, done }[] | — | Required. Labels must be unique. |

## Spacing and layout

- Items 8px apart; icon to label 8px. The icon stays level with the first line of a label that wraps.
- Usually in a summary Card beside a form.

## Accessibility

- A `<ul>`; each item adds "(done)" or "(to do)" for screen readers, as the icon is decorative.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `Checklist.vue` | — |
| iOS (SwiftUI) | — | `Label` rows with `checkmark.circle.fill` / `circle`. |
| Android (Compose) | — | Rows with `CheckCircle` / `RadioButtonUnchecked` icons. |

## Tokens used

| Token | Used for |
|---|---|
| `color-green` | Done icon |

## Do / Don't

| Do | Don't |
|---|---|
| Name each step by its part of the page ("Term dates"). | Write instructions ("You need to add term dates"). |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// Checklist.vue
/**
 * Steps towards something, ticked off as they're done: what's left before a
 * form can be submitted, or setting up a new school year. It shows progress;
 * people don't tick it themselves (use Checkbox for that).
 */
export interface ChecklistItem {
  /** What needs doing, e.g. "Term dates". */
  label: string
  done: boolean
}

export interface ChecklistProps {
  items: ChecklistItem[]
  class?: HTMLAttributes['class']
}
```

---

# RelativeTime

> A time as people say it, "3 hours ago", with the exact date and time in a tooltip.

- Import: `import { RelativeTime } from '@thekestongroup/ui'`
- Group: Data
- Live example: https://ui.keston.co/storybook/?path=/story/components-data-relativetime--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/RelativeTime/RelativeTime.vue

## When to use

- Anywhere an app shows when something happened: notifications, "last edited", activity, comments.

## When not to use

- Dates people need exactly, e.g. a due date or a date of birth: show the full date with the date helpers (`formatDate`).
- Someone's age: use Age.

## Anatomy

| Part | Required | Notes |
|---|---|---|
| text | Yes | e.g. "3 hours ago", "yesterday", "in 2 days", in the surrounding text style. |
| tooltip | Yes | The full date and time, e.g. "Wednesday 11 November 2026 at 09:52". |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| date | Date \| string \| number | — | A Date, an ISO string or a timestamp. |
| now | Date | the live time | What "now" is, e.g. for tests or a fixed screenshot. |
| tooltip | (date) => string | full date and time | Tooltip text, e.g. "Edited on {date}". |

## Behaviour

- Keeps itself up to date, every 30 seconds.
- The tooltip shows on hover and on keyboard focus.

## Accessibility

- A `<time>` element with the exact `datetime`, focusable so keyboard users can reach the tooltip.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `RelativeTime.vue` | `Intl.RelativeTimeFormat`. |
| iOS (SwiftUI) | — | `Text(date, style: .relative)` or `RelativeDateTimeFormatter`; exact date in a context menu. |
| Android (Compose) | — | `DateUtils.getRelativeTimeSpanString`. |

## Tokens used

None of its own: it uses the surrounding text style, and Tooltip's.

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// RelativeTime.vue
/**
 * A time as people say it, "3 hours ago", with the exact date and time
 * ("Wednesday 11 November 2026 at 09:52") in a tooltip on hover or focus.
 * Keeps itself up to date (every 30 seconds).
 *
 * Use it wherever an app shows a relative date: notifications, "last
 * edited", activity, comments.
 */
export interface RelativeTimeProps {
  /** A Date, an ISO string, or a timestamp. */
  date: DateInput
  /** What "now" is, e.g. for tests or a fixed screenshot. Default the live time. */
  now?: Date
  /** Tooltip text. Default the full date and time; e.g. "Edited on {date}". */
  tooltip?: (date: Date) => string
  class?: HTMLAttributes['class']
}
```

---

# Age

> Someone's age, "13", with their date of birth and any birthday this week in a tooltip.

- Import: `import { Age } from '@thekestongroup/ui'`
- Group: Data
- Live example: https://ui.keston.co/storybook/?path=/story/components-data-age--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/Age/Age.vue

## When to use

- Showing a person's age, e.g. in a student list or record. The tooltip saves looking up their date of birth.

## When not to use

- When the date of birth itself matters more than the age: show the date with `formatDate`.
- How long ago something happened: use RelativeTime.

## Anatomy

| Part | Required | Notes |
|---|---|---|
| number | Yes | The age, in the surrounding text style, with an optional suffix ("13 years"). |
| tooltip | Yes | "Born 14 March 2013", plus "Birthday today" or "Birthday in 3 days" within a week. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| birthDate | Date \| string \| number | — | Date of birth: a Date, an ISO string ("2013-03-14") or a timestamp. |
| suffix | string | — | Text after the number, e.g. "years". Leave out in an "Age" column. |
| now | Date | today | What "today" is, e.g. for tests. |

## Behaviour

- The age goes up on the birthday itself; people born on 29 February turn a year older on 1 March in other years.
- The tooltip shows on hover and on keyboard focus.

## Accessibility

- Focusable, so keyboard users can reach the tooltip.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `Age.vue` | `age()` and `daysToBirthday()` in `src/lib/dates.ts`. |
| iOS (SwiftUI) | — | `Calendar.dateComponents([.year], …)`; date of birth in a context menu. |
| Android (Compose) | — | `Period.between(…).years`. |

## Tokens used

None of its own: it uses the surrounding text style, and Tooltip's.

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// Age.vue
/**
 * Someone's age, "13", with their date of birth in a tooltip on hover or
 * focus: "Born 14 March 2013", plus "Birthday today" or "Birthday in 3 days"
 * when it's within a week (handy for teachers).
 */
export interface AgeProps {
  /** Date of birth: a Date, an ISO string ("2013-03-14"), or a timestamp. */
  birthDate: DateInput
  /** Text after the number: "years" gives "13 years". Leave out for just "13" (e.g. in an "Age" column). */
  suffix?: string
  /** What "today" is, e.g. for tests. Default the live date. */
  now?: Date
  class?: HTMLAttributes['class']
}
```

---

# Breadcrumb

> Where the current page is: its parents, then the page itself, e.g. School › School Structure › New School Year Setup.

- Import: `import { Breadcrumb } from '@thekestongroup/ui'`
- Group: Navigation
- Live example: https://ui.keston.co/storybook/?path=/story/components-navigation-breadcrumb--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/Breadcrumb/Breadcrumb.vue

## When to use

| Use a Breadcrumb for | Use instead |
|---|---|
| Pages two or more levels deep, e.g. inside a nested Sidebar | Top-level pages: the page title is enough |
| Records inside records, e.g. Students › Year 9 › Ben Blissett | Steps in a process (use a stepper) |

## Anatomy

| Part | Required | Notes |
|---|---|---|
| step (link) | No | An earlier page: a link back (`href`, `to`) or a button (`onSelect`). |
| step (text) | No | An earlier step that isn't a page, e.g. a sidebar group: plain grey text. |
| current page | Yes | The last step: black text, `aria-current="page"`, not a link. |
| separator | — | › between steps. |
| icon | No | Before a step's label. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| items | { label, icon?, href?, to?, onSelect? }[] | — | Required. Top level first; the last is the current page. SidebarItems fit, so `sidebarTrail(items, sections)` can be passed straight in. |
| label | string | Breadcrumb | Name of the navigation landmark. |
| linkComponent | string \| Component | a | Used for steps with `to`, e.g. RouterLink. |

Events: `select` (item, event) when an earlier step is chosen.

## Sizes

| Part | Size | Notes |
|---|---|---|
| Text | 14px / 20px, regular | `text-sm` |
| Icon | 14px | |
| Separator | 14px › in black 40% | |
| Gap | 6px between step and separator; 4px between wrapped lines | |
| Step width | Up to 240px, then cut off with …; full text on hover (`title`) | |

## States

| State | Appearance |
|---|---|
| Link | Black 65% |
| Link hovered | Black, underlined |
| Link focused | 2px focus ring `#007FC9`, 1px outside, 2px corners |
| Text step | Black 65%, no hover |
| Current page | Black |

## Behaviour

| Situation | Result |
|---|---|
| Narrow screen | Steps wrap onto more lines |
| Long step | Cut off with … at 240px |
| Earlier step chosen | Follows its link, or calls `onSelect`; emits `select` |

## Accessibility

| Part | Announced as |
|---|---|
| Container | `navigation` landmark named "Breadcrumb", containing an ordered list |
| Current page | `aria-current="page"` |
| Separators and icons | Hidden from assistive tech |

| Contrast | Ratio |
|---|---|
| Links and text steps (black 65%) on white | about 6.5:1 |
| Separator (black 40%) | Decorative |

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `Breadcrumb.vue` | — |
| iOS (SwiftUI) | — | Use the navigation stack's back button and title instead. |
| Android (Compose) | — | Use the top app bar's up button and title instead. |

## Tokens used

| Token | Used for |
|---|---|
| color black | current page, hovered link |
| color black (65%) | links and text steps |
| color black (40%) | separators |
| color focus | focus ring |

## Do / Don't

| Do | Don't |
|---|---|
| Follow the Sidebar with `sidebarTrail()`, so both agree | Build the trail by hand where it can drift from the Sidebar |
| Keep the current page as the last step, not a link | Link the current page to itself |
| Leave groups that aren't pages as text | Link a group to a page it doesn't have |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// Breadcrumb.vue
export interface BreadcrumbItem {
  label: string
  /** A Lucide (or any) icon component, shown before the label. */
  icon?: Component
  /** Link with a plain <a href>. */
  href?: string
  /** Link through `linkComponent` (e.g. RouterLink), which receives `to`. */
  to?: unknown
  /** Called when the step is chosen (for steps that aren't links). */
  onSelect?: (event: MouseEvent) => void
}

/**
 * Where the current page is: its parents, then the page itself, e.g.
 * School › School Structure › New School Year Setup. Earlier steps with a
 * `href`, `to` or `onSelect` are links back; steps without are plain text
 * (e.g. a group that isn't a page itself). The last step is the current page.
 *
 * SidebarItems fit, so it can follow a nested Sidebar:
 * `<Breadcrumb :items="sidebarTrail(items, sections)" />`.
 */
export interface BreadcrumbProps {
  items: BreadcrumbItem[]
  /** Accessible name of the navigation landmark. */
  label?: string
  /** Component used for steps with `to`, e.g. RouterLink or NuxtLink. */
  linkComponent?: string | Component
  class?: HTMLAttributes['class']
}

const emit = defineEmits<{
  /** A step before the current page was chosen. */
  select: [item: BreadcrumbItem, event: MouseEvent]
}>()
```

---

# Sidebar

> The app's main navigation, down the left of the page, optionally collapsing to icons.

- Import: `import { Sidebar } from '@thekestongroup/ui'`
- Group: Navigation
- Live example: https://ui.keston.co/storybook/?path=/story/components-navigation-sidebar--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/Sidebar/Sidebar.vue

## When to use

- Moving between the main areas of an app.

## When not to use

- Actions on the current page (use Buttons), or navigation within a page (tabs).

## Anatomy

| Part | Required | Notes |
|---|---|---|
| header | No | Top, same height as Header (e.g. logo). |
| body | Yes | Scrolling list of sections. |
| section label | No | Small bold uppercase heading. A divider when collapsed. |
| item | Yes | Icon, label, optional badge. Items with children show › at the right. |
| back row | Nested only | First row inside a nested item: ‹ and its label (bold), then a divider. Goes up one level. |
| footer | No | Bottom, e.g. profile or help. Holds the collapse button. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| items | SidebarItem[] | [] | Items in one unlabelled section. |
| sections | { label?, items }[] | [] | Labelled groups, after `items`. |
| collapsed | boolean (v-model) | false | Narrow, icons only. |
| collapsible | boolean | false | Show the collapse / expand button. |
| label | string | "Main" | Name of the navigation landmark. |
| linkComponent | string \| Component | "a" | Used for items with `to`, e.g. RouterLink. |
| ui | { header, body, footer, item } | — | Extra classes per part. |

SidebarItem: `label`, `icon`, `href` or `to`, `active`, `badge`, `disabled`, `onSelect`, `children` (sub-pages).

Helper: `sidebarTrail(items, sections)` returns the path to the active item (top first), e.g. for a Breadcrumb.

## Sizes

| Size | Width | Item height | Item padding (x) | Gap | Icon size | Text style |
|---|---|---|---|---|---|---|
| Expanded | spacing 64 (256px) | 38px (md Button) | spacing 3 | spacing 3 | 16px | sm |
| Collapsed | spacing 14 (56px) | 38px | centred | — | 16px | labels hidden |

## States

| State | Appearance | Notes |
|---|---|---|
| Enabled | transparent, black text | |
| Hovered | black 10% | Web / desktop only |
| Pressed | black 15% | |
| Active (current page) | primary 10%, primary bold text | aria-current="page" |
| Parent of current page | primary bold text, no fill | Nested: "you are in here" |
| Focused | inset focus ring | Inset so the scrolling body doesn't clip it |
| Disabled | 40% opacity, not-allowed cursor | Links lose their href |

## Behaviour

- Collapse: width animates over 300ms ease-out; none with reduced motion.
- Scrollbar: thin when expanded; hidden when collapsed (the 40px strip can't spare the width), the list still scrolls.

### Nested items

| Action | Result |
|---|---|
| Choose an item with children (›) | Shows its children in place of the list, with a back row at the top. Doesn't navigate or emit `select` |
| Choose the back row | Goes up one level |
| After opening a level | Focus on its first item |
| After going back | Focus on the item just left |
| Current page changes | The list opens at that page's level |
| Collapsed | Back row shows only ‹ (tooltip "Back from {label}"); give sub-pages icons too |
| In the mobile Slideover | Opening and going back keep it open; choosing a page closes it |
- Small screens: the app hides it and shows it inside a Slideover (left) opened from the Header's menu button. Choosing an item should close the Slideover.

## Accessibility

- `<aside>` containing a `<nav>` named by `label`.
- Each labelled section is a list named by its heading.
- Collapsed: labels and badges stay in the DOM for screen readers; the label is also a native tooltip (`title`).
- Nested: items with children are buttons announced as "{label}, more options"; the back row as "Back from {label}".
- Icons are hidden from assistive tech.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `Sidebar.vue` | — |
| iOS (SwiftUI) | — | NavigationSplitView sidebar (iPad), tab bar (iPhone). |
| Android (Compose) | — | NavigationDrawer / NavigationRail. |

## Tokens used

| Token | Used for |
|---|---|
| color white | background |
| color black (15%) | border, dividers |
| color primary (10% / 15%) | active item, active hover |
| color focus | focus ring |

## Do / Don't

| Do | Don't |
|---|---|
| Give every item an icon if it can collapse, sub-pages included. | Nest so deep people lose their place: pair nesting with a Breadcrumb. |
| Use labels that are unique within each level. | Repeat a label at the same level (levels are tracked by label). |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// Sidebar.vue
export interface SidebarItem {
  label: string
  /** A Lucide (or any) icon component. Needed for the item to make sense when collapsed. */
  icon?: Component
  /** Link with a plain <a href>. */
  href?: string
  /** Link through `linkComponent` (e.g. RouterLink), which receives `to`. */
  to?: unknown
  /** The current page. Shown highlighted, and announced as aria-current="page". */
  active?: boolean
  /** A count or short note on the right, e.g. unread messages. */
  badge?: string | number
  /** Colour of the badge (default basic), e.g. red for something overdue. */
  badgeColor?: BadgeProps['color']
  disabled?: boolean
  /** Called when the item is chosen (for items that aren't links, or as well as navigating). */
  onSelect?: (event: MouseEvent) => void
  /**
   * Sub-pages. Choosing this item shows them in place of the list, with a
   * back row (‹ and this item's label) at the top, instead of navigating.
   * e.g. School › School Structure › New School Year Setup.
   */
  children?: SidebarItem[]
}

export interface SidebarSection {
  /** Heading above the section's items. */
  label?: string
  items: SidebarItem[]
}

/**
 * The app's main navigation, down the left of the page. Items can be links
 * (`href`, or `to` with a router link component) or buttons (`onSelect`), and
 * can be grouped into labelled sections, and nested (`children`): choosing
 * an item with children shows them, with a back row to return. Opens at the
 * level of the current page. Can collapse to a narrow strip of icons.
 *
 * For a Breadcrumb that follows it, use `sidebarTrail(items, sections)`.
 *
 * On small screens, put it inside a Slideover (`side="left"`) opened from the
 * Header's menu button. See Examples/App shell.
 *
 * Slots: header (top, e.g. a logo), footer (bottom, e.g. settings or a
 * profile), item (replaces each item's content: `{ item, active, collapsed }`).
 */
export interface SidebarProps {
  /** Items in a single section. Use `sections` for headings. */
  items?: SidebarItem[]
  /** Groups of items, each with an optional heading. Shown after `items`. */
  sections?: SidebarSection[]
  /** Accessible name of the navigation landmark. */
  label?: string
  /** Show the collapse / expand button in the footer. */
  collapsible?: boolean
  /** Component used for items with `to`, e.g. RouterLink or NuxtLink. */
  linkComponent?: string | Component
  class?: HTMLAttributes['class']
  /** Extra classes for the parts. */
  ui?: {
    header?: HTMLAttributes['class']
    body?: HTMLAttributes['class']
    footer?: HTMLAttributes['class']
    item?: HTMLAttributes['class']
  }
}

const emit = defineEmits<{
  /** An item was chosen (not emitted for disabled items). */
  select: [item: SidebarItem, event: MouseEvent]
}>()

defineSlots<{
  header?(props: { collapsed: boolean }): unknown
  footer?(props: { collapsed: boolean }): unknown
  item?(props: { item: SidebarItem; active: boolean; collapsed: boolean }): unknown
}>()

/** Narrow, icons only. Optional: use v-model:collapsed to control it. */
const collapsed = defineModel<boolean>('collapsed', { default: false })

// sidebar.ts
/**
 * The path to the current page (the item marked `active`) through nested
 * items, top level first, e.g. [School, School Structure, New School Year
 * Setup]. Empty when no item is active. Takes the same `items` and
 * `sections` as the Sidebar, so a Breadcrumb can follow it:
 *
 *   <Breadcrumb :items="sidebarTrail(items, sections)" />
 */
export function sidebarTrail(items: SidebarItem[] = [], sections: SidebarSection[] = []): SidebarItem[] { … }
```

---

# Link

> A text link, in the size and colour of the text around it, with an external-page icon when it opens in a new tab.

- Import: `import { Link } from '@thekestongroup/ui'`
- Group: Navigation
- Live example: https://ui.keston.co/storybook/?path=/story/components-navigation-link--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/Link/Link.vue

## When to use

- Going to another page from within text, a footer or a tooltip: "privacy policy", "Forgot password?", "More info".

## When not to use

- Doing something on this page (save, open a panel, sign in): use Button.
- Moving around an app: use Sidebar or Breadcrumb.

## Anatomy

| Part | Required | Notes |
|---|---|---|
| text | Yes | Underlined, 2px below the text. Colour and size come from the surrounding text. |
| new-tab icon | With `newTab`, unless `icon` is off | Lucide external-link, 0.9em, 2px after the text, on the baseline. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| href | string | — | Where it goes. |
| newTab | boolean | false | Open in a new tab, with the icon and "(opens in a new tab)" for screen readers. |
| icon | boolean | true | With `newTab`, show the icon. Turn off where it would clutter; screen readers still hear "(opens in a new tab)". |
| as | string \| component | a | e.g. RouterLink, with `to`. |

## States

| State | Appearance | Notes |
|---|---|---|
| Enabled | Text colour, 1px underline. | |
| Hovered | Black, 2px underline. | Web / desktop only |
| Focused | 2px focus ring, 2px out. | Keyboard only |

## Behaviour

- `newTab` adds `target="_blank"` and `rel="noopener noreferrer"`.
- Open in a new tab for pages outside the current task (policies, help), so people don't lose what they were doing, e.g. a half-finished sign-in.

## Content guidelines

- Say where it goes ("privacy policy", "More info"), never "click here".

## Accessibility

- A native link. With `newTab`, screen readers hear "(opens in a new tab)" after the text; the icon is hidden from them.
- Underlined, so it doesn't rely on colour alone.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `Link.vue` | Reka UI Primitive, so `as` can be a router link. |
| iOS (SwiftUI) | — | `Link` with an underlined `AttributedString`; new-tab links open in Safari (`SFSafariViewController`). |
| Android (Compose) | — | `LinkAnnotation.Url` in text; new-tab links open in a Custom Tab. |

## Tokens used

| Token | Used for |
|---|---|
| `color-black` | Hover |
| `color-focus` | Focus ring |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// Link.vue
/**
 * A text link: underlined, in the colour and size of the text around it, so
 * it fits in a sentence, a footer or a tooltip alike. With `newTab` it opens
 * in a new tab and shows a small external-page icon (and tells screen
 * readers it opens in a new tab).
 *
 * For a router, pass its link component as `as`, e.g.
 * `<Link :as="RouterLink" to="/help">`.
 */
export interface LinkProps {
  href?: string
  /** Open in a new tab, with the external-page icon. Use it for pages outside the current flow (policies, help) so people don't lose their place. */
  newTab?: boolean
  /** With `newTab`, show the external-page icon. Turn it off where it would clutter, e.g. a row of footer links. Screen readers still hear "(opens in a new tab)". */
  icon?: boolean
  /** Element or component to render, e.g. RouterLink. */
  as?: PrimitiveProps['as']
  class?: HTMLAttributes['class']
}
```

---

# Popover

> A small panel that floats next to the thing that opened it, e.g. a menu, a filter or a profile card.

- Import: `import { Popover } from '@thekestongroup/ui'`
- Group: Overlay
- Live example: https://ui.keston.co/storybook/?path=/story/components-overlay-popover--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/Popover/Popover.vue

## When to use

- Extra content or controls tied to one element: a filter form, a short menu, a profile card on hover.

## When not to use

- A word or two of help: use Tooltip, or InfoTip for a `?` beside a label.
- A larger task, or a form with several fields: use Slideover.
- Something people must respond to before continuing: use a dialog.

## Anatomy

| Part | Required | Notes |
|---|---|---|
| trigger | Yes | The element it opens from, usually a Button (default slot). |
| panel | Yes | White, black 15% border, 4px corners, shadow. Fades in and out. Content goes in the content slot. |
| arrow | No | Points at the trigger. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| mode | click \| hover | click | How it opens. See Behaviour. |
| open | boolean | — | Use `v-model:open` to control it. |
| defaultOpen | boolean | false | Open when first shown. |
| content | object | bottom, 8px away | Placement passed to Reka, e.g. `{ side: 'top', align: 'start' }`. |
| arrow | boolean | false | Show the arrow. |
| portal | boolean \| string \| element | true | Render at the end of the page (true), in a given element, or in place (false). |
| dismissible | boolean | true | Close on Escape and clicking outside. If false, emits `close:prevent`. |
| modal | boolean | false | Block the rest of the page while open. |
| openDelay / closeDelay | number (ms) | 0 / 0 | Hover mode only. |

## Behaviour

- **click:** opens and closes on click, tap or Enter. Focus moves into the panel, so it suits interactive content (menus, forms).
- **hover:** opens on mouse hover, and on click or tap, which keeps it open, so it also works on touch screens. Focus stays where it is, so it suits information.
- Escape and clicking outside close it; focus returns to the trigger.
- It flips and shifts to stay on screen.

## Accessibility

- The trigger gets `aria-expanded` and `aria-controls`; the panel is a dialog.
- In hover mode, put links or buttons in the panel only with `portal: false`, so Tab reaches them straight after the trigger.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `Popover.vue` | Reka UI Popover. |
| iOS (SwiftUI) | — | `.popover` (a sheet on iPhone). |
| Android (Compose) | — | `Popup` or `DropdownMenu`. |

## Tokens used

| Token | Used for |
|---|---|
| `color-white` / `color-black` | Panel and border |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// Popover.vue
/**
 * A floating panel attached to a trigger. Built on Reka UI's Popover, which
 * handles positioning, focus, Escape and clicking outside.
 *
 * - mode "click" (default): opens and closes on click / tap / Enter. Focus
 *   moves into the panel, so it suits interactive content (menus, forms).
 * - mode "hover": opens on mouse hover, and also on click / tap, which keeps
 *   it open (so it works on touch screens). Focus stays where it is, so it
 *   suits information, e.g. a field's help text.
 *
 * Slots: default (the trigger, e.g. a Button), content ({ close }), anchor
 * (position against something other than the trigger).
 */
export interface PopoverProps {
  /** How it opens. */
  mode?: 'click' | 'hover'
  /**
   * Where the panel goes and how it behaves, passed to Reka's PopoverContent,
   * e.g. `{ side: 'top', align: 'start' }`. Default
   * `{ side: 'bottom', sideOffset: 8, collisionPadding: 8 }`.
   */
  content?: Omit<PopoverContentProps, 'as' | 'asChild' | 'forceMount'>
  /** Show an arrow pointing at the trigger (or Reka arrow options). */
  arrow?: boolean | Omit<PopoverArrowProps, 'as' | 'asChild'>
  /**
   * Render the panel at the end of the page (true), inside a given element
   * (a selector or element), or in place (false).
   */
  portal?: boolean | string | HTMLElement
  /** Close on Escape and on clicking outside. If false, emits close:prevent instead. */
  dismissible?: boolean
  /** Block interaction with the rest of the page while open. */
  modal?: boolean
  /** Open when first shown. */
  defaultOpen?: boolean
  /** Hover mode: wait this long before opening, in ms. */
  openDelay?: number
  /** Hover mode: wait this long before closing, in ms (at least 100, so the pointer can reach the panel). */
  closeDelay?: number
  /** Extra classes for the panel and the arrow. */
  ui?: { content?: HTMLAttributes['class']; arrow?: HTMLAttributes['class'] }
}

const emit = defineEmits<{ 'close:prevent': [] }>()

defineSlots<{
  default?(): unknown
  content?(props: { close: () => void }): unknown
  anchor?(): unknown
}>()

/** Whether the panel is open. Optional: use v-model:open to control it. */
const openModel = defineModel<boolean | undefined>('open', { default: undefined })
```

---

# Slideover

> A full-height panel that slides in from the side, e.g. to edit a record or fill in a multi-step form without leaving the page.

- Import: `import { Slideover } from '@thekestongroup/ui'`
- Group: Overlay
- Live example: https://ui.keston.co/storybook/?path=/story/components-overlay-slideover--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/Slideover/Slideover.vue

## When to use

- Editing or adding something while keeping the page behind in context: edit a student, add an application.
- Multi-step forms (with `steps`).
- Longer side content: a notification list, a log.

## When not to use

- A small amount of extra content tied to one element: use Popover.
- A whole task that deserves its own address: use a page.

## Anatomy

| Part | Required | Notes |
|---|---|---|
| trigger | No | Default slot, e.g. a Button. Or control it with `v-model:open`. |
| overlay | No | Black 40% over the page. |
| panel | Yes | White, full height, up to 448px wide (full width on small screens). |
| header | Yes | Title (18px), description, × close button; 24px / 16px padding, line under it. |
| progress | With `steps` | A segment per step above the title, and "Step 2 of 4: Contact details" under it. |
| body | Yes | Scrolls on its own. |
| footer | No | Actions, e.g. Cancel / Save. With `steps`, Cancel or Previous and Next or Finish. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| title | string | — | The panel's heading and accessible name. Always set it. |
| description | string | — | Text under the title. |
| side | right \| left \| top \| bottom | right | Edge it slides in from. |
| open | boolean | — | Use `v-model:open` to control it. |
| overlay | boolean | true | Dim the page behind. |
| close | boolean | true | Show the × button. |
| dismissible | boolean | true | Close on Escape and clicking outside. If false, emits `close:prevent`. |
| modal | boolean | true | Block the page behind while open. |
| initialFocus | none \| auto \| close | none | Where focus goes when it opens. See Accessibility. |
| steps | string[] | — | Step names, for a multi-step form. |
| step | number | 0 | Current step, from 0. Use `v-model:step`. Back to 0 each time it opens. |
| validateStep | (step) => boolean \| Promise | — | Checked before Next / Finish; return false to stay. Can be async, e.g. to save. |
| finishLabel | string | Finish | Text of the last step's button. |

| Event | When |
|---|---|
| finish | Finish was pressed on the last step and `validateStep` passed. |
| close:prevent | Closing was attempted while not dismissible. |

## Behaviour

- Slides in over 300ms and out over 200ms; with reduced motion it fades instead.
- The page behind doesn't scroll while it's open.
- **Multi-step forms:** Next checks the step with `validateStep`, then moves on; Previous goes back; the first step shows Cancel. Enter in a text field presses Next / Finish (after InputDate's own first Enter). Each new step starts scrolled to the top.

## Accessibility

- A dialog named by the title and described by the description. Focus is kept inside while it's open, and returns to the trigger on close.
- `initialFocus`: `none` focuses the panel itself, so screen readers read from the top; `auto` focuses the first field (not on touch screens, so the keyboard doesn't pop up); `close` focuses ×.
- **Multi-step forms:** the step is part of the description when it opens. After Enter, focus moves to the next step's first control, which sits in a group named "Step 3 of 4: Contact". After Next or Previous, the step is announced. It's read once each time.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `Slideover.vue` | Reka UI Dialog. |
| iOS (SwiftUI) | — | `.sheet` on iPhone; `.inspector` on iPad and Mac. |
| Android (Compose) | — | `ModalBottomSheet` on phones; a side sheet on large screens. |

## Tokens used

| Token | Used for |
|---|---|
| `color-white` / `color-black` | Panel, overlay, lines |
| `color-primary` | Step segments |
| `animate-slide-in-*` / `animate-slide-out-*` | Sliding in and out |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// Slideover.vue
/**
 * A full-height panel that slides in from the side of the screen, e.g. to edit
 * a record without leaving the page. Built on Reka UI's Dialog: focus is kept
 * inside while open, Escape and clicking the overlay close it, the page behind
 * doesn't scroll, and it is announced as a dialog.
 *
 * Slots: default (the trigger, e.g. a Button), header (replaces title,
 * description and close), title, description, body (the scrolling middle),
 * footer (e.g. Cancel / Save), content (replaces everything inside the panel).
 * Slots that close it get `{ close }`.
 *
 * Multi-step forms: pass `steps` (one name per step) and show the current
 * step's fields in the body slot, which gets `{ step }`. The header shows a
 * segment per step and "Step 2 of 4: Contact details"; the footer gets
 * Cancel / Previous and Next / Finish, unless you fill the footer slot.
 * Enter in a text field presses Next / Finish.
 */
export interface SlideoverProps {
  /** Heading of the panel. Also its accessible name, so always set it (or the title slot). */
  title?: string
  /** Text under the title. */
  description?: string
  /** Edge it slides in from. */
  side?: 'right' | 'left' | 'top' | 'bottom'
  /** Dim the page behind it. */
  overlay?: boolean
  /** Show the × close button in the header. */
  close?: boolean
  /** Close on Escape and on clicking outside. If false, emits close:prevent instead. */
  dismissible?: boolean
  /** Block interaction with the page behind while open. */
  modal?: boolean
  /** Open when first shown. */
  defaultOpen?: boolean
  /**
   * Where focus goes when it opens:
   * - none (default): the panel itself, so screen readers announce the title
   *   and description and read from the top. Tab then moves to the first
   *   control.
   * - auto: an element marked `autofocus`, else the first form field, else
   *   the × button. On touch screens it skips text fields, so the keyboard
   *   doesn't pop up before the panel has been seen.
   * - close: the × button (or the first button, if there's no ×).
   */
  initialFocus?: 'auto' | 'close' | 'none'
  /** Render at the end of the page (true), inside a given element, or in place (false). */
  portal?: boolean | string | HTMLElement
  /** Passed to Reka's DialogContent. */
  content?: Omit<DialogContentProps, 'as' | 'asChild' | 'forceMount'>
  /** Names of the steps, for a multi-step form. Adds the segments, step name and Previous / Next. */
  steps?: string[]
  /**
   * Checks the current step before moving on (Next) or finishing (Finish).
   * Return false to stay, e.g. after showing field errors. Can be async, e.g.
   * to save on the last step; the button shows a spinner meanwhile.
   */
  validateStep?: (step: number) => boolean | Promise<boolean>
  /** Text of the last step's button. */
  finishLabel?: string
  /** Extra classes for the parts. */
  ui?: {
    overlay?: HTMLAttributes['class']
    content?: HTMLAttributes['class']
    header?: HTMLAttributes['class']
    title?: HTMLAttributes['class']
    body?: HTMLAttributes['class']
    footer?: HTMLAttributes['class']
  }
}

const emit = defineEmits<{
  'close:prevent': []
  /** Finish was pressed on the last step and `validateStep` passed. */
  finish: []
}>()

defineSlots<{
  default?(): unknown
  header?(props: { close: () => void }): unknown
  title?(): unknown
  description?(): unknown
  body?(props: { close: () => void; step: number }): unknown
  footer?(props: { close: () => void }): unknown
  content?(props: { close: () => void }): unknown
}>()

/** Whether it is open. Optional: use v-model:open to control it. */
const openModel = defineModel<boolean | undefined>('open', { default: undefined })

/** Current step, from 0. Optional: use v-model:step to control it. Back to 0 each time it opens. */
const step = defineModel<number>('step', { default: 0 })
```

---

# Tooltip

> A short label on hover or keyboard focus: the exact date behind "3 hours ago", a birthday behind an age, what an icon button does.

- Import: `import { Tooltip } from '@thekestongroup/ui'`
- Group: Overlay
- Live example: https://ui.keston.co/storybook/?path=/story/components-overlay-tooltip--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/Tooltip/Tooltip.vue

## When to use

| Use a Tooltip for | Use instead |
|---|---|
| Extra detail people may want, but don't need | Anything people need to do the task (put it on the page) |
| The exact value behind a rounded or relative one ("3 hours ago" → date and time) | Anything interactive (a Popover) |
| Naming an icon button (as well as its `aria-label`) | Long explanations (a Popover, or help text) |

Tooltips don't open on touch screens, so nothing important can live only in one.

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| text | string | — | Slot `content` for anything richer (still no interactive content). |
| side | top \| right \| bottom \| left | top | Flips if there's no room. |
| align | start \| center \| end | center | |
| delay | number (ms) | 400 | Before it shows. Moving to another tooltip within 300ms shows it at once. |
| disabled | boolean | false | |

The trigger (default slot) must be focusable: a Button, a link, or an element with `tabindex="0"`.

## Sizes

| Part | Value |
|---|---|
| Panel | Gray 900, white text, 6px corners, shadow, 1px white 10% ring |
| Text | 12px / 16px, medium |
| Padding | 10px sides, 6px top and bottom |
| Max width | 288px, then wraps |
| Distance from trigger | 8px |

## Behaviour

| Action | Result |
|---|---|
| Hover the trigger | Shows after 400ms; hides when the pointer leaves (it can move onto the tooltip) |
| Keyboard focus | Shows straight away; hides on blur or Escape |
| Touch | Nothing |

## Accessibility

| Part | Announced as |
|---|---|
| Trigger | Its own name, then the tooltip as its description (`aria-describedby`) |
| Tooltip | `tooltip` |

Meets WCAG 1.4.13: it can be dismissed (Escape), hovered, and stays until the pointer or focus leaves.

## The pattern: short value, exact one on hover

Wherever an app shows something rounded or relative, show the exact value in a tooltip.

| Component | Shows | Tooltip |
|---|---|---|
| `RelativeTime` | "3 hours ago" (updates every 30s) | "Wednesday 11 November 2026 at 08:51" |
| `Age` | "13" or "13 years" | "Born 14 March 2013", plus "· Birthday in 3 days" within a week |

Both have a dotted underline (40% of the text colour) to show there's more, and a focus ring for keyboard users. Date-only strings ("2013-03-14") are read as that day, not midnight UTC.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `Tooltip.vue` (Reka UI Tooltip), `RelativeTime.vue`, `Age.vue` | — |
| iOS (SwiftUI) | — | No hover: show the exact value on tap (a `popover`), or in the detail screen. `.help()` on iPad and Mac pointers. |
| Android (Compose) | — | `PlainTooltip` on long-press. |

## Tokens used

| Token | Used for |
|---|---|
| gray 900, white | panel, text |
| color focus | trigger focus ring |

## Do / Don't

| Do | Don't |
|---|---|
| Use RelativeTime for every relative date | Show "3 hours ago" with no way to see when |
| Keep it to a few words | Put buttons or links in a tooltip |
| Make the trigger focusable | Put a tooltip on plain, unfocusable text |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// Tooltip.vue
/**
 * A short label that appears on hover or keyboard focus: the exact date
 * behind "3 hours ago", a birthday behind an age, the name of an icon
 * button.
 *
 * Only for extra, non-essential detail: it doesn't open on touch screens,
 * so anything people need must be on the page too. Nothing interactive
 * inside it (use a Popover).
 *
 * The trigger (default slot) must be focusable, so keyboard users can open
 * it: a Button, a link, or an element with `tabindex="0"`. The tooltip is
 * linked to it with `aria-describedby`, so screen readers read it after the
 * trigger's name.
 *
 * Slots: default (the trigger), content (instead of `text`).
 */
export interface TooltipProps {
  /** The tooltip's text. */
  text?: string
  /** Which side of the trigger. */
  side?: TooltipContentProps['side']
  align?: TooltipContentProps['align']
  /** Wait this long before showing, in ms. Moving to another tooltip soon after shows it at once. */
  delay?: number
  disabled?: boolean
  class?: HTMLAttributes['class']
}

defineSlots<{
  default?(): unknown
  content?(): unknown
}>()
```

---

# InfoTip

> A `?` that explains the thing beside it: a field's label, a table column, a figure.

- Import: `import { InfoTip } from '@thekestongroup/ui'`
- Group: Overlay
- Live example: https://ui.keston.co/storybook/?path=/story/components-overlay-infotip--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/InfoTip/InfoTip.vue

## When to use

- A short explanation most people won't need, beside the label it explains.
- Fields have it built in: `helperPlacement="icon"` on Input, InputNumber, InputDate, Select and RadioGroup.

## When not to use

- Anything people need to complete the task: put it on the page (e.g. helper text below the label).
- Naming an icon button: use Tooltip.
- Anything interactive: use Popover.

## Anatomy

| Part | Required | Notes |
|---|---|---|
| button | Yes | 16px `?` icon with 2px padding, fully rounded. |
| panel | Yes | Popover panel above it, up to 256px wide, 12px text. |

## Properties

| Property | Type | Default | Description |
|---|---|---|---|
| text | string | — | Required. A sentence or two. |
| label | string | — | Required. Accessible name, e.g. "About attendance". |

## States

| State | Appearance | Notes |
|---|---|---|
| Enabled | Black icon. | |
| Hovered / open | Black 10% circle behind it. | |
| Focused | 2px focus ring. | Keyboard only. |

## Behaviour

- Opens on hover, and on click / tap, which keeps it open (so it works on touch). Escape or clicking outside closes it.
- Focus never moves into it, so typing in a nearby field isn't interrupted.

## Accessibility

- A button named by `label`, with `text` as its description, so screen readers hear the explanation without opening it.
- In a field, the field's control is described by the same text, so it's heard there too.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `InfoTip.vue` | Built on Popover (hover mode). |
| iOS (SwiftUI) | — | `questionmark.circle` button showing a `.popover`. |
| Android (Compose) | — | Icon button with a `RichTooltip`. |

## Tokens used

| Token | Used for |
|---|---|
| `color-focus` | Focus ring |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// InfoTip.vue
/**
 * A `?` that explains the thing beside it: a field's label, a table column,
 * a figure. Opens on hover, and on click / tap (which keeps it open, so it
 * works on touch screens). Focus is never moved, so typing in a nearby
 * control isn't interrupted.
 */
export interface InfoTipProps {
  /** The explanation. Keep it to a sentence or two. */
  text: string
  /**
   * The button's accessible name: what it explains, e.g. "About Student ID".
   * Screen readers then hear `text` as its description.
   */
  label: string
  class?: HTMLAttributes['class']
}
```

---

# Notification

> Something people should know about: a toast when it happens, and a list of past ones behind the bell in the Header.

- Import: `import { Notification } from '@thekestongroup/ui'`
- Group: Overlay
- Live example: https://ui.keston.co/storybook/?path=/story/components-overlay-notification--default
- Source: https://github.com/thekestongroup/ui/blob/main/src/components/Notification/Notification.vue

## When to use

| Use a notification for | Use instead |
|---|---|
| Something that happened, especially in the background (an upload finished, a password is expiring) | The result of what someone just did on the page (show it there: a Button's status, a field's error) |
| Something people may want to come back to (it stays in the pane) | A problem that blocks the page (an alert on the page) |
| | A question that needs an answer before continuing (a dialog) |

## Anatomy

| Part | Required | Notes |
|---|---|---|
| icon | Yes | From the type, 16px, in its colour. |
| title | Yes | Short, bold. |
| description | No | A string, or a render function for **bold** text and links. |
| action | No | One small basic Button, e.g. "Change password". Closes the toast or pane. |
| time | Pane only | "4 minutes ago" (RelativeTime: the exact date and time on hover or focus), kept up to date. |
| unread dot | Pane only | 8px primary dot, and a light blue background on the row. |
| × | Yes | Toast: closes it (it stays in the pane). Pane: removes it. |

## Types

| Type | Icon | Colour | Toast stays | Announced |
|---|---|---|---|---|
| info | Info (i) | blue `#035483` | 6 seconds | When the screen reader is idle |
| success | Circle check | green `#007A16` | 6 seconds | When the screen reader is idle |
| warning | Triangle | yellow `#F1C70B`, black outline | 6 seconds | Straight away |
| error | Circle × | red `#D2042D` | Until closed | Straight away |

With an action, every type stays until closed, so people have time to use it, except compact ones (e.g. Undo), which stay 10 seconds. Errors always stay.

## Compact

One line, for quick confirmations: icon, title, the action on the right, then ×.

```ts
notify({ type: 'success', title: 'Student disabled', compact: true, action: { label: 'Undo', onSelect: undo } })
```

| Rule | Value |
|---|---|
| Width | The same as other toasts (384px), only shorter |
| Padding | 20px left (icons line up with full toasts), 6px top and bottom, 6px right beside the × (16px without one) |
| Content | Title only: the description isn't shown in the toast. In the pane it's a normal row. |
| Gaps | 12px icon to title (as in the full toast), 12px title to action |

## Properties

### notify(input, options)

| Field | Type | Default | Description |
|---|---|---|---|
| title | string | — | Required. |
| type | info \| success \| warning \| error | info | |
| description | string \| () => VNode | — | No HTML strings, so nothing in a notification can run as code. |
| action | { label, onSelect?, href? } | — | |
| compact | boolean | false | One-line toast (see Compact). |
| id | string | generated | Notifying with the same id replaces it, e.g. "Uploading…" then "Uploaded". |
| createdAt | Date | now | |
| options.toast | boolean | true | False: only add it to the pane. |
| options.duration | number (ms) | see Types | |

### Components

| Component | Property | Type | Default |
|---|---|---|---|
| Toaster | notifications | the list | the shared `useNotifications()` |
| Toaster | position | bottom-right \| top-right \| bottom-center | bottom-right |
| Toaster | maxHeight | number (px) | 320: older toasts past this collapse into a stack |
| Toaster | limit | number | 10: the most kept at once |
| Toaster | @more | event | "+3 more" was pressed (it also opens the pane) |
| NotificationPane | notifications | the list | the shared `useNotifications()` |
| NotificationPane | label | string | "Notifications" |
| NotificationPane | emptyText | string | "You're all caught up." |
| Notification | appearance | card \| row | card |
| Notification | compact | boolean | false |
| Notification | dismissible, dismissLabel | boolean, string | true, "Dismiss: {title}" |

## Sizes

| Part | Value |
|---|---|
| Toast | 384px wide (full width minus 16px each side on phones), 16px padding (20px on the left), shadow, 4px corners, 8px between toasts, 16px from the edges |
| Pane | 384px wide, as tall as fits under the Header then scrolls; heading row 44px; rows clipped to its 4px corners |
| Pane row | 16px sides, 12px top and bottom, a line between |
| Icon to text | 12px |
| Title / description | 14px / 20px; title bold black, description black 65% (bold parts black) |
| Time | 12px, black 65% |
| Action | Small basic Button, 8px above |
| Unread count | 16px red circle, white bold 12px, "99+" above 99, white ring |

## Behaviour

| Action | Result |
|---|---|
| `notify()` | Added to the top of the pane; a toast slides up from below the screen and the others move up with it (300ms, ease-out; top-right drops in 16px with a fade) |
| More than `maxHeight` of toasts | The older ones shrink into the "+5 more" pill (to 50%, fading out) as newer ones arrive, and grow back out of it when spread out or when there's room again |
| Any toasts not in view, collapsed | A "+5 more" pill (96px wide, 28px tall, 16px corners, 12px bold, white) sits 8px above the stack, counting every toast not in view: in the pill or waiting |
| Spreading out or collapsing | The pill and the "+3 more" row are one button that morphs: its position, width (96px ↔ full), height (28 ↔ 36px), corners (16 ↔ 4px) and text size (12 ↔ 14px) animate together (300ms, ease-out). Spread out, it counts only those waiting, and fades away if none are |
| Tap or click the pill | The toasts spread out (focus moves to the newest, without a focus ring), for touch screens with no hover |
| Hover the toasts, or focus in them (Tab, F8) | They spread out, 8px apart; leaving collapses them again |
| A toast closes | It fades where it is while the others slide to close the gap (300ms, ease-out); one from the pill grows out to fill the space |
| A toast has to wait (newer ones took its place) | It shrinks into "+N more" (the row when spread out, the pill when collapsed) before it goes |
| A waiting toast's turn comes | It grows out of "+N more", rather than sliding in from the edge like a new one |
| More than fit on the screen spread out (its height, less 80px for the Header and edges) | The oldest wait (not shown, timers not started); the ones in view are always the newest, in the order they came in. When spread out, a "+3 more" row (36px, bold, white) after the last toast counts just those waiting |
| "+3 more" pressed | The pane opens with everything in it; focus moves to its heading |
| Pane open (however it was opened) | Toasts showing fade away and waiting ones are dropped (they're all in the pane); new notifications go straight to the pane, with no toast |
| Hover a toast, or leave the window | Its timer pauses |
| Swipe a toast right | It closes |
| F8 | Focus jumps to the toasts |
| Open the pane | Unread ones show a dot |
| Close the pane | All marked read; the count goes |
| × in the pane | Removed; focus moves to the next one's × (or the heading) |
| Clear all | All removed; focus moves to the heading |

## Accessibility

| Part | Announced as |
|---|---|
| Bell | Button "Notifications, 3 unread" |
| Toast | Read out when it appears ("Notification, Warning: Password Expiry, Your password expires in 7 days"), politely or straight away by type |
| Toasts area | `region` "Notifications (F8)" |
| Pane | `region` named by its heading, a list of notifications |
| Each notification | `group` named by its title; the type is read before the title |
| Unread | "Unread," before the time |
| × | "Dismiss: {title}" in the pane, "Close: {title}" on a toast |

Colour is never the only signal: each type has its own icon and is said in words.

## Platform adaptation

| Platform | Implementation | Differences |
|---|---|---|
| Web / desktop (Vue) | `Notification.vue`, `Toaster.vue`, `NotificationPane.vue` (Reka UI Toast and Popover) | — |
| iOS (SwiftUI) | — | System notifications when the app is closed; a banner overlay in the app; the list in a sheet. |
| Android (Compose) | — | `Snackbar` for toasts (one at a time); the list in a bottom sheet or screen. |

## Tokens used

| Token | Used for |
|---|---|
| color blue / green / yellow / red | type icons (yellow fills the warning triangle; black outlines it) |
| color red | unread count |
| color primary | unread dot |
| color blue (5%) | unread row background |
| color black (65%) | description, time |
| color black (15%) | borders, lines |

## Do / Don't

| Do | Don't |
|---|---|
| Write a title that makes sense on its own | Put the important part only in the description |
| Give errors a way forward (an action) | Notify for every small save: show those where they happened |
| Use `id` to update one notification as something progresses | Send several notifications for the same thing |

## API (from the source)

The component's exact props, model, events, slots and types, with their documentation comments.

```ts
// Notification.vue
/**
 * One notification: an icon for its type, a title, a description, an
 * optional action button, and a close ×.
 *
 * - appearance "card" (default): a white panel with a border. On a page, or
 *   as a toast (Toaster adds the shadow).
 * - appearance "row": no border, for lists, e.g. NotificationPane. Shows the
 *   time, and a dot when unread.
 *
 * The description can be formatted with a render function, e.g.
 * `() => ['Your password expires in ', h('b', '7 days'), '.']`, or the
 * default slot.
 */
export interface NotificationProps {
  type?: NotificationType
  title: string
  description?: NotificationInput['description']
  action?: NotificationAction
  /** When it happened. Shown in the row appearance, e.g. "2 hours ago", with the exact time on hover. */
  createdAt?: Date
  /** Row appearance: show the unread dot. */
  unread?: boolean
  appearance?: 'card' | 'row'
  /**
   * Card appearance: one line, for quick confirmations, e.g. "✓ Student
   * disabled [Undo] ×". The title only (no description); the action sits on
   * the right, before the ×.
   */
  compact?: boolean
  /** Show the close ×. */
  dismissible?: boolean
  /** The ×'s accessible name. Default "Dismiss: {title}". */
  dismissLabel?: string
  /** What "now" is for the relative time. Default the live time. */
  now?: Date
  class?: HTMLAttributes['class']
}

const emit = defineEmits<{ dismiss: []; action: [] }>()

defineSlots<{
  default?(): unknown
  actions?(): unknown
}>()

// NotificationPane.vue
/**
 * The bell in the Header, with a count of unread notifications, that opens
 * a panel of past notifications: newest first, each with a × to remove it,
 * and Clear all. Put it in the Header's `trailing` slot (AppShell's
 * `header-trailing`).
 *
 * Opening it shows what's unread (a dot on each); closing it marks them all
 * read.
 */
export interface NotificationPaneProps {
  /** The list to show. Default the shared one from `useNotifications()`. */
  notifications?: Notifications
  /** Panel heading, and the bell's name. */
  label?: string
  /** Shown when there are none. */
  emptyText?: string
  ui?: { content?: HTMLAttributes['class']; trigger?: HTMLAttributes['class'] }
}

const open = defineModel<boolean>('open', { default: false })

// Toaster.vue
/**
 * Shows new notifications as toasts: cards that slide in at the edge of the
 * screen and close by themselves. Put one in the app (e.g. beside AppShell),
 * then call `notify()` from anywhere:
 *
 *   const { notify } = useNotifications()
 *   notify({ type: 'success', title: 'Saved' })
 *
 * New toasts slide in from the bottom (top for top-right) and push the
 * others along smoothly. Toasts that don't fit in `maxHeight` collapse into
 * a "+5 more" pill on top of the stack saying how many aren't in view (they
 * shrink into it, and grow out of it again); hovering the toasts, tapping the pill, or
 * keyboard focus in them (F8), spreads them all out.
 *
 * If there are more than fit on the screen spread out, the oldest wait, and
 * a "+3 more"
 * row at the end opens NotificationPane, which has them all.
 *
 * Built on Reka UI's Toast: screen readers hear each one (errors and
 * warnings straight away, others when they're idle), timers pause while the
 * pointer is over them or the window isn't focused, and they swipe away.
 *
 * Closing a toast leaves the notification in the list (NotificationPane).
 */
export interface ToasterProps {
  /** The list to show. Default the shared one from `useNotifications()`. */
  notifications?: Notifications
  /** Where they appear. top-right sits under the 48px Header. */
  position?: 'bottom-right' | 'top-right' | 'bottom-center'
  /**
   * How tall the toasts can be, spread out, before older ones collapse into
   * a stack (in px). The newest always shows in full.
   */
  maxHeight?: number
  /** The most toasts kept at once; older ones beyond this wait until one closes. */
  limit?: number
  class?: HTMLAttributes['class']
}

const emit = defineEmits<{ more: [] }>()

// notifications.ts
export type NotificationType = 'info' | 'success' | 'warning' | 'error'

export interface NotificationAction {
  label: string
  /** Run when pressed. The toast closes afterwards (the notification stays in the pane). */
  onSelect?: () => void
  /** Make the action a link instead. */
  href?: string
}

export interface NotificationInput {
  /** Generated if left out. Notifying with an id that's already there replaces it. */
  id?: string
  /** Colour and icon. Default info. */
  type?: NotificationType
  title: string
  /**
   * Text under the title. A string, or a render function for formatting,
   * e.g. `() => ['Your password expires in ', h('b', '7 days'), '.']`.
   * (No HTML strings: they'd let anything that reaches a notification run
   * as code.)
   */
  description?: string | (() => VNodeChild)
  action?: NotificationAction
  /**
   * A one-line toast: icon, title, action, × (e.g. "✓ Student disabled
   * [Undo]"). For quick confirmations; the description isn't shown in the
   * toast. In the pane it's a normal row.
   */
  compact?: boolean
  /** When it happened. Default now. */
  createdAt?: Date
  read?: boolean
}

export interface NotificationItem extends NotificationInput {
  id: string
  type: NotificationType
  createdAt: Date
  read: boolean
}

export interface ToastOptions {
  /** Pop up a toast as well as adding it to the history. Default true. */
  toast?: boolean
  /**
   * How long the toast stays, in ms. Default 6000; until closed for errors,
   * and for toasts with an action (people need time to use it); compact ones
   * with an action (Undo) stay 10 seconds.
   */
  duration?: number
}

export interface ShownToast {
  id: string
  duration: number
  item: NotificationItem
}

/** Default toast length: long enough to read; forever when there's something to do. */
export function toastDuration(item: Pick<NotificationItem, 'type' | 'action' | 'compact'>, duration?: number) { … }

/**
 * A list of notifications (newest first), and the ones currently showing as
 * toasts. Pass `items` to NotificationPane and `toasts` to Toaster, or call
 * `useNotifications()` for one shared list for the whole app.
 */
export function createNotifications(initial: NotificationInput[] = []) { … }

export type Notifications = ReturnType<typeof createNotifications>

/** One shared notification list for the whole app. */
export function useNotifications(): Notifications { … }
```