@jonmilner/ui 0.0.0-stage → 0.1.0

package/dist/docs/Tag.md

@@ -0,0 +1,97 @@
+# Tag
+
+## Purpose
+
+A label that puts content in a category: a topic, a label, a user-made category. A `span` with a `bgMuted` fill and a full radius around a `Text` in the `label` font. It can be read-only, a link, or removable.
+
+## When to use
+
+- Topics or labels on content: "Design", "Release", "Needs review".
+- Categories a user adds and removes, such as the labels on an issue.
+- A category that links to a page listing everything in it (`href`).
+
+## When not to use
+
+- The status of, or a short fact about, a thing: use `Badge`.
+- A filter or choice the user toggles on and off: use `Chip`.
+- A whole-tag action other than a link or removal: compose `Clickable`.
+- A sentence or a message: use `Text`.
+
+## Rules
+
+- `size`: `sm` or `med` (default), the label's `fontSize` step. There are no color variants yet: a Tag is neutral (`fg` on `bgMuted`, a `contrastPairs` pair).
+- Read-only is the default. `href` makes the label a link (a `Clickable` `<a>` around the text, underlined). The tag itself stays a `span`, so a remove button never nests in the link.
+- `onRemove` adds a native `<button>` after the label with an `x` icon. Its name is "Remove <label>" from a string or number label; set `removeLabel` for any other label. Enter and Space activate it; the click calls `onRemove`. Tag handles no keys, so Backspace and Delete do nothing (ADR 0003, 0055).
+- Wrapping: an uncapped label wraps to the width it has, so a tag never overflows a narrow container or a 320px viewport at large text sizes.
+- Truncation: set `maxInlineSize` on the Tag, as the style prop or in `style` (the style prop's steps stop at 56px, so most caps are `style={{ maxInlineSize: "min(10rem, 100%)" }}`; the `100%` keeps a rem cap inside a narrow container at large text sizes). `style.maxWidth` counts too, and `style` wins over the prop, as inline styles do. A responsive prop truncates only with a `base` step and a size step (or `full`) at every breakpoint: `{ med: "xl" }` and `{ base: "xl", med: "fit" }` wrap. The prop's `fit`, `min`, `max` and `auto`, and `style` values `none`, `auto` and `*-content`, follow the content and wrap. A cap set only through `className` wraps instead. The label becomes one line with an ellipsis. While the pointer is over the tag, or focus is inside it, the label shows its whole text, wrapped within the same width. There is no tooltip and no `title`; the DOM always holds the full text, so screen readers read all of it and so does the remove button's name. The tag grows in height when it reveals, so leave room for it in a tight row. A read-only tag takes no focus, so a keyboard user cannot reveal it: cap read-only tags only where the full text is also elsewhere, or make them links.
+- With no children it renders nothing. Display, fill, text color, padding, radius and `minBlockSize` (the remove button's 24px target) are default style props; a consumer's win. `className`, `style` and `ref` go to the root, `className` last.
+- The module has no hooks, so a server component can render it.
+
+## Focus after removal
+
+Tag never moves focus: removing a tag unmounts the button that has it, and the browser drops focus to `body`. The owner of the list puts it back. In order:
+
+1. The next tag's remove button, which now sits at the removed tag's index.
+2. Else the previous tag's remove button.
+3. Else (the list is empty) the list's container or heading, made focusable with `tabIndex={-1}`, or the input that adds tags.
+
+Tell screen reader users the tag is gone, with the owner's live region or by naming the list's new count in the element that takes focus.
+
+## Do
+
+```tsx
+<Inline gap="4" alignItems="center">
+  <Tag href="/topics/design">Design</Tag>
+  <Tag>Release</Tag>
+</Inline>
+```
+
+```tsx
+// The owner removes the tag and moves focus (see the Removable story).
+<Tag onRemove={() => remove(label)}>{label}</Tag>
+```
+
+```tsx
+<Tag style={{ maxInlineSize: "min(10rem, 100%)" }}>{longCategoryName}</Tag>
+```
+
+## Don't
+
+```tsx
+// Tag handles no keys; do not add Backspace or Delete to it.
+<Tag onKeyDown={removeOnDelete}>Design</Tag>
+```
+
+```tsx
+// A tag is not a status. Use Badge.
+<Tag>Failed</Tag>
+```
+
+```tsx
+// A non-text label needs removeLabel, or the button is just "Remove".
+<Tag onRemove={remove}>
+  <b>Design</b>
+</Tag>
+```
+
+## Accessibility
+
+- A read-only tag is plain text in a `span`, no role. A link tag is a link in the tab order. A removable tag adds one button; each button's name says which tag it removes.
+- Nothing essential is only in a tooltip: truncated text is fully in the DOM and shows on hover and focus.
+- The `x` icon is `aria-hidden`; the button's `aria-label` names it. The link and the button each get the shared focus ring and a 24px target.
+- Under forced colors the tag is `CanvasText` on `Canvas` with a `CanvasText` outline, as Badge is.
+
+## Props
+
+Generated from the TypeScript types.
+
+### Tag
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `href` | `string` | no |  |
+| `onRemove` | `(() => void)` | no |  |
+| `removeLabel` | `string` | no |  |
+| `size` | `"med" \| "sm"` | no |  |
+
+Also accepts the style props (see `manifest.json` `styleProps`).

package/dist/docs/Text.md

@@ -0,0 +1,90 @@
+# Text
+
+## Purpose
+
+The base of all visible text, and the primitive every text component builds on. Capsize trims the box to the cap height and the baseline, so the gap around text is the visible space. It takes every Box style prop (`color`, `textAlign`, margins), plus `size`, `font`, `weight`, `leading` and `truncate`.
+
+## When to use
+
+- Body copy, labels, captions, code: any string a user sees.
+- Building a text component (a heading, a label, a badge's text): render `Text` with defaults, as `Heading` does.
+- A run inside a line (`strong`, `em`, `code`): a `Text` rendered as a phrasing element directly inside another `Text` is inline and untrimmed, and inherits the outer font until its own props say otherwise.
+
+## When not to use
+
+- Section and page headings: use `Heading`, which picks the element by level.
+- Layout around text: put Text in a `Box`, `Stack` or `Inline` and set the gap there.
+
+## Rules
+
+- `as` defaults to `p`, so a run inside a paragraph must set an inline element: `as="span"`, `"strong"`, `"em"`, `"code"`, `"time"`. A `p` inside a `p` is invalid HTML and breaks hydration.
+- A run inherits the outer weight, so `<Text as="strong">` is not bold until it sets `weight="bold"` (or `semibold`).
+- A run is inline whatever its `display` prop, and `truncate` gives it no ellipsis; truncate a block Text instead.
+- `display="flex"` or `"grid"` makes the trim pseudo-elements flex or grid items, so `gap` adds space around them; wrap the text in a Box for layout instead. A block element (`p`, `div`, `h2`) or a Text inside a `Box` inside a Text keeps its own trimmed box.
+- `size` takes a `fontSize` step: `xs`, `sm`, `med`, `lg`, `xl`, `2xl`, `3xl`, `4xl`. The top-level default is `med`.
+- `font` takes a font role: `body` (default), `heading`, `display`, `label`, `mono`. The brand maps roles to fonts.
+- `weight` takes `regular` (default), `medium`, `semibold` or `bold`.
+- `leading` takes a unitless line height: `sm`, `med` (default) or `lg`. The trim follows it.
+- `color` takes a color role (`fg`, `fgMuted`, `accent`, …), never a raw color. Unset, it inherits.
+- `truncate` keeps one line and cuts it with an ellipsis, without clipping ascenders or descenders. It sets the block margins, so do not combine it with margin props.
+- The trim is two pseudo-elements; do not style `::before` or `::after` on a Text.
+- No native `text-box`; capsize only (ADR 0016).
+
+## Do
+
+```tsx
+<Text size="sm" color="fgMuted">
+  Updated{" "}
+  <Text as="time" dateTime="2026-10-23">
+    today
+  </Text>
+</Text>
+```
+
+```tsx
+<Text as="span" font="label" weight="medium" truncate>
+  {fileName}
+</Text>
+```
+
+## Don't
+
+```tsx
+// Raw colors and `md` do not type-check.
+<Text color="#666" size="md" />
+```
+
+```tsx
+// Text outside Text: untrimmed, in no font role.
+<Box>Saved</Box>
+```
+
+```tsx
+// A heading built from Text loses the level; use Heading.
+<Text as="h2" size="xl" weight="semibold">
+  Settings
+</Text>
+```
+
+## Accessibility
+
+- Text adds no role or ARIA. Pick the element with `as` so the meaning is right: `p`, `label`, `time`, `code`, `strong`.
+- Color alone carries no meaning: `fgMuted` text needs words that say the same.
+- Truncated text is cut for everyone; put the full string somewhere reachable (the page it links to, an accessible name), not only in a tooltip.
+
+## Props
+
+Generated from the TypeScript types.
+
+### Text
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `as` | `ElementType` | no |  |
+| `font` | `"body" \| "display" \| "heading" \| "label" \| "mono"` | no |  |
+| `leading` | `"lg" \| "med" \| "sm"` | no |  |
+| `size` | `"2xl" \| "3xl" \| "4xl" \| "lg" \| "med" \| "sm" \| "xl" \| "xs"` | no |  |
+| `truncate` | `boolean` | no |  |
+| `weight` | `"bold" \| "medium" \| "regular" \| "semibold"` | no |  |
+
+Also accepts every `<p>` attribute (change the element with `as`) and the style props (see `manifest.json` `styleProps`).

package/dist/docs/Toast.md

@@ -0,0 +1,115 @@
+# Toast
+
+## Purpose
+
+Tells the user briefly about the result of an action without interrupting them: "Changes saved", "Message sent", "Couldn't upload the file". Material calls it a snackbar and Atlassian a flag. Built on Base UI's Toast, which owns the queue, the timers and swipe-to-dismiss. The parts add the look: a raised card in a stack at the bottom end corner, an icon per variant, a close button, and a slide-up-and-fade that is a plain fade under reduced motion. A toast never takes focus and moves nothing on the page.
+
+## When to use
+
+- The outcome of something the user just did, when they can carry on without reading it.
+- An action that ran at once and can be undone: offer Undo as the toast's action.
+- A background task finishing or failing (an upload, an export).
+
+## When not to use
+
+- A decision the user must make before the action runs: use `AlertDialog`.
+- A focused task, or anything with fields: use `Dialog`. A toast holds no form fields.
+- An error on one input: use the `Field`'s error message, on the field.
+- A status that stays (draft, synced, 3 unread): use `Badge`.
+- A message that must stay on the page until its cause is fixed (offline, trial ending): an inline alert or banner, which the library does not have yet.
+- Anything the user must read or act on to continue: a toast may close before they reach it.
+
+## Rules
+
+- Wrap the app once in `Toast.Provider`, inside its `ThemeProvider`. Show a toast from any client component under it with `useToast()`: `add(options)` returns the toast's id, `close(id)` dismisses it.
+- `title` is one line on what happened. `description` is one optional sentence more. Both are plain strings.
+- `variant` is `info` (the default), `success` or `error`. Each has its own icon, so the variant never rests on color alone. `success` uses the `accent` icon on `bgRaised` until the library has a success role (#100).
+- `action` takes a `label` and an `onClick`; there is at most one. Choosing it also closes the toast. Nothing essential goes there: Undo is fine when the user could also undo another way; "Retry" on an error is fine because an error stays until it is dismissed.
+- `duration` is how long, in milliseconds, before the toast closes itself; `0` keeps it until the user dismisses it. It defaults to 5000, and to 0 for `error`, so the user always gets time to read an error.
+- Every toast has a close button. `closeLabel` on the provider names it for every toast ("Dismiss" by default) and `regionLabel` names the stack's landmark ("Notifications" by default); translate both there.
+- `limit` on the provider (3 by default) caps how many show at once: the newest. Older ones are hidden until a newer one leaves, so an error that stays until dismissed can be hidden by later toasts. The newest sits at the top, nearest the content.
+- The stack portals into the provider's nearest `ThemeProvider`, so it keeps the brand and mode, and sits on `zIndex` `toast`, above modals. That provider must not clip or stack its content: wrap the app root. `className` and `style` on the provider reach the stack.
+- The index module has no hooks, so a server component can render `Toast.Provider`; `useToast` runs in a client component.
+
+## Do
+
+```tsx
+<ThemeProvider brand={brand}>
+  <Toast.Provider>
+    <App />
+  </Toast.Provider>
+</ThemeProvider>
+```
+
+```tsx
+const toast = useToast();
+
+async function save() {
+  try {
+    await saveProfile();
+    toast.add({ title: "Profile saved", variant: "success" });
+  } catch {
+    toast.add({
+      title: "Couldn't save your profile",
+      description: "Check your connection and try again.",
+      variant: "error",
+      action: { label: "Retry", onClick: save },
+    });
+  }
+}
+```
+
+```tsx
+// The archive ran at once; Undo is a shortcut, the archive view is the other way back.
+toast.add({ title: "Conversation archived", action: { label: "Undo", onClick: unarchive } });
+```
+
+## Don't
+
+```tsx
+// A decision dressed as a toast: it may close before the user decides. Use AlertDialog.
+toast.add({ title: "Delete this project?", action: { label: "Delete", onClick: remove } });
+```
+
+```tsx
+// The only way to finish the task, on a timer.
+toast.add({ title: "Verify your email", action: { label: "Send link", onClick: send } });
+```
+
+```tsx
+// A paragraph: a toast is one line and one sentence. Give it a page or a Dialog.
+toast.add({ title: "Update", description: releaseNotes });
+```
+
+## Accessibility
+
+- The stack is a `region` landmark named by `regionLabel` ("Notifications" by default); F6 moves focus to it, and Shift+Tab from there returns focus where it was. Each toast is a `group` named by its title. Neither the stack (`aria-live="off"`) nor the toasts are live regions; the provider renders two visually hidden ones that exist before any toast, and adds each toast's title and description to one as it arrives: `info` and `success` to a polite `status`, `error` to an assertive `alert`. So each toast is announced once, and an error at once (ADR 0074). Adding a toast never moves focus.
+- A toast hidden by `limit` was announced when it arrived. When a newer one leaves and it shows again, it is not announced a second time; a user who needs it finds it in the stack with F6.
+- An error raised from inside a modal `Dialog` is still announced: the dialog hides the rest of the page from assistive tech, but not the announcer's regions.
+- Inside a modal `Dialog`: F6 still reaches the stack past the dialog's focus trap, so an error's action and close button stay in keyboard reach; Tab past the last toast returns focus to the dialog. Escape in the stack currently closes the dialog too, not only the toast (#145).
+- Reflow (WCAG 1.4.10): a stack taller than the window, as at 320px wide with 200% text, scrolls inside itself with the newest toast on top, so the older ones stay in reach.
+- Resize text (WCAG 1.4.4): when the stack is narrower than 16rem, as at 320px wide with 200% text, the content moves to its own line below the icon and close button, so the button stays inside the card and words wrap whole (ADR 0067).
+- Timing (WCAG 2.2.1, Timing Adjustable): a toast closes on its own only when it is not essential. The timer pauses while the pointer is over the stack, while keyboard focus is in it, and while the window is in the background, so a user who reaches it gets the time they need. An error stays until dismissed by default, and `duration: 0` keeps any toast. The close button dismisses a toast at any time.
+- Dismissing a toast from the keyboard (Enter or Space on its close button, or a screen reader's activation) moves focus to the close button of the toast that takes its place: the next one, else the previous one. Dismissing the last returns focus to where it was before Tab or F6 brought it into the stack, so focus never falls to the page (ADR 0085). Focus after a click or swipe is #149.
+- The close button and the action are native buttons with the shared focus ring and a 24px target. The close button's name is `closeLabel`.
+- Swiping a toast away, down or toward the stack's inline end (right, or left under `dir="rtl"`), is a shortcut; the close button does the same.
+- Under reduced motion a toast only fades. Under forced colors it keeps its border.
+
+## Props
+
+Generated from the TypeScript types.
+
+`Toast` is not a component: render its parts.
+
+### Toast.Provider
+
+| Prop | Type | Required | Description |
+| --- | --- | --- | --- |
+| `children` | `ReactNode` | no |  |
+| `className` | `string` | no |  |
+| `closeLabel` | `string` | no |  |
+| `limit` | `number` | no |  |
+| `regionLabel` | `string` | no |  |
+| `style` | `CSSProperties` | no |  |
+
+Also exports `useToast`.

package/dist/docs/llms.txt

@@ -0,0 +1,33 @@
+# @jonmilner/ui
+
+> React design system. Each component's docs say when to use it, its rules and props.
+
+## Components
+
+- [AlertDialog](AlertDialog.md): Asks the user to confirm a consequential action before it runs: delete a project, discard unsaved changes, sign out every device. Built on Base UI's AlertDialog, which owns the behavior: `role="alertdialog"`, focus moves into the dialog and stays there, the page behind is inert, Esc closes it, and a click outside does not. It wears Dialog's panel at the `sm` width with a title, a description, Cancel and one confirm button, and Cancel takes focus on open.
+- [Badge](Badge.md): A static label that states the status of, or a short fact about, the thing beside it: "Draft", "Failed", "Beta". A `span` with a fill from the color roles around a `Text` in the `label` font. It has no role and is never focusable.
+- [Box](Box.md): The base element every component builds on: one element, chosen with `as`, styled with style props. Style props are the token-backed classes from `@layer atoms`: layout (`display`, flex, `gap`, logical padding, margin and sizing), color roles, `borderRadius`, `boxShadow`, `position`, `zIndex`, `overflow` and `textAlign`.
+- [Button](Button.md): The labelled action: a `<button type="button">` with the house look, or a link styled as one with `as="a"` (or a router's link). Three variants (`primary`, `secondary`, `danger`), three sizes (`sm`, `med`, `lg`, 32, 40 and 48 px high), a `loading` state that keeps its width, and icon slots before and after the label. It is built on `Clickable`, so it has the shared focus ring, the 24px minimum target and `aria-disabled` / `aria-busy` states that block activation while the button stays focusable.
+- [Checkbox](Checkbox.md): A two-state choice, with a third mixed state for a "select all" over a partly selected list. Built on Base UI `Checkbox` (ADR 0003, 0046): a `span` with `role="checkbox"` and `aria-checked`, plus a hidden `<input type="checkbox">` that submits with the form. The span is a 24 by 24 CSS px target (WCAG 2.2) with the shared focus ring; the 16px box inside fills and shows a tick when checked, a dash when mixed. It composes `Field` for its label, description and error (ADR 0026).
+- [Chip](Chip.md): A toggle that filters content or picks an option: "Unread", "Starred", "Medium". A `<button>` with `aria-pressed` on `Clickable`, built on Base UI `Toggle`; `ChipGroup` is a Base UI `ToggleGroup` of chips that share one state. If it changes state when clicked, it's a chip.
+- [Clickable](Clickable.md): The low-level base for everything a user presses: a `<button type="button">` by default, or a link with `as="a"` (or a router's link component). It brings the shared focus ring, a 24 by 24 CSS px minimum target (WCAG 2.2), `disabled` and `busy` states as ARIA attributes, and no look of its own: the button and link chrome is stripped. `Button`, `IconButton` and link components are built on it.
+- [Dialog](Dialog.md): A modal panel over the page for one short task: edit a name, fill a small form, read details that need a decision. Built on Base UI's Dialog, which owns the behavior: focus moves into the dialog and stays there, the page behind is inert and does not scroll, Esc and a click on the backdrop close it, and focus returns to the trigger. The parts add the look: a dimmed backdrop, a raised panel with a title, and a zoom-and-fade that is a plain fade under reduced motion.
+- [Field](Field.md): Wires one form control to its label, description and error: ids, `htmlFor`, `aria-describedby` and `aria-invalid`. It is input-agnostic: the control inside is Base UI's `Field.Control` or a Base UI control (Checkbox, Combobox), and Base UI does the wiring. The parts are `Field` (the root, a flex column), `Field.Label`, `Field.Description` and `Field.Error`. Built on Base UI `Field` (ADR 0003, 0026, 0046); `@base-ui/react` is a peer dependency, so the app's Base UI controls and Field share one copy of its contexts.
+- [Heading](Heading.md): Section and page headings. A `Text` with heading defaults: the `heading` font role, `semibold`, `sm` leading, and balanced line wrapping. The level (`as`) and the look (`size`) are separate, so the outline stays right whatever the design calls for.
+- [Icon](Icon.md): The base for every icon: an `<svg>` on a 24-unit grid that draws its children with round 2-unit strokes in `currentColor`. Generated icons from `@jonmilner/ui/icons` (`ArrowRightIcon`, …) wrap it and take the same props, less `children` and `viewBox`. `size` takes a `fontSize` step, so an icon matches the `Text` beside it; `color` takes a color role.
+- [IconButton](IconButton.md): A compact button whose only visible content is an icon, for an action the icon makes plain: close, edit, refresh. A required `label` names it for assistive technology (`aria-label`); the icon is decorative. It is a `<button type="button">` on `Clickable`, so it has the shared focus ring, the 24px minimum target and `aria-disabled` that blocks activation while the button stays focusable. Two variants from Button's fills (`primary`, `secondary`) and three square sizes at Button's heights (`sm`, `med`, `lg`: 32, 40 and 48 px).
+- [Inline](Inline.md): A horizontal row of children that wraps onto new lines, with even space between them on both axes. `Inline` is a `Box` with `display="flex"`, `flexDirection="row"`, `flexWrap="wrap"` and `alignItems="center"` as default style props, spaced by a required `gap`. Children render as they are: no wrapper per child.
+- [Menu](Menu.md): A list of actions that opens from a button: a row's "Edit, Duplicate, Delete", a toolbar's overflow. Built on Base UI's Menu, which owns the keyboard and focus: arrow keys, Home and End move through the items, typing jumps to a matching item, Esc and an outside click close it, and focus returns to the trigger. The parts add the look: a raised surface with a border and shadow, a highlighted item, a zoom-and-fade that is a plain fade under reduced motion.
+- [MultiSelect](MultiSelect.md): A form field for picking any number of values from a list too long to show at once. A trigger styled as Button's secondary look opens a listbox of options; each selected option shows a check mark, and the trigger summarises the selection as the joined labels, or a count ("3 selected") once the labels would not fit. Built on Base UI's `Select` in multiple mode (ADR 0003), which owns the keyboard and focus: arrow keys, Home and End move through the options, typing jumps to a match, Esc and an outside click close it, and focus returns to the trigger. It composes `Field` for its label, description and error (ADR 0026).
+- [SearchField](SearchField.md): A form field for a search query: an `<input type="search">` (role `searchbox`) with a search icon at its inline start and, while it holds a value, a clear button at its inline end. Escape empties a field that has a value, and the clear button empties it and puts focus back in the input, so a keyboard user never loses their place (ADR 0087). Built on Base UI's `Input` (ADR 0003); it composes `Field` for its label, description and error (ADR 0026). Three sizes at Button's heights (`sm`, `med`, `lg`: 32, 40 and 48 px).
+- [Stack](Stack.md): A vertical column of children with even space between them. `Stack` is a `Box` with `display="flex"` and `flexDirection="column"` as default style props, spaced by a required `gap`. Children render as they are: no wrapper per child.
+- [Tabs](Tabs.md): Switches between views that share one place on the page. The parts are `Tabs` (the root, a flex column; a row when vertical), `Tabs.List` (the `tablist`), `Tabs.Tab` (a `tab` button on `Clickable`) and `Tabs.Panel` (the `tabpanel`). Built on Base UI `Tabs` (ADR 0003, 0046): it owns the selection, one tab stop with arrow-key roving, `aria-selected`, and the ids that tie each tab to its panel. The selected tab shows an accent bar that fades and grows in (ADR 0049).
+- [Tag](Tag.md): A label that puts content in a category: a topic, a label, a user-made category. A `span` with a `bgMuted` fill and a full radius around a `Text` in the `label` font. It can be read-only, a link, or removable.
+- [Text](Text.md): The base of all visible text, and the primitive every text component builds on. Capsize trims the box to the cap height and the baseline, so the gap around text is the visible space. It takes every Box style prop (`color`, `textAlign`, margins), plus `size`, `font`, `weight`, `leading` and `truncate`.
+- [Toast](Toast.md): Tells the user briefly about the result of an action without interrupting them: "Changes saved", "Message sent", "Couldn't upload the file". Material calls it a snackbar and Atlassian a flag. Built on Base UI's Toast, which owns the queue, the timers and swipe-to-dismiss. The parts add the look: a raised card in a stack at the bottom end corner, an icon per variant, a close button, and a slide-up-and-fade that is a plain fade under reduced motion. A toast never takes focus and moves nothing on the page.
+
+## Reference
+
+- [manifest.json](manifest.json): every component, prop, variant, icon and token, as JSON
+- [theming.md](theming.md): themes, brands and tokens
+- [migrations/](migrations/README.md): upgrade notes for breaking releases