@ahrowe/ui 0.42.0 → 0.44.0

package/docs/Alert.md

@@ -4,24 +4,24 @@
 
 **Keywords:** warning box
 
-**Import:** `import { Alert, AlertStyleType } from '@ahrowe/ui'`
+**Import:** `import { Alert, ThemeColor } from '@ahrowe/ui'`
 
-**Style variants:** `AlertStyleType.Default` | `AlertStyleType.Info` | `AlertStyleType.Success` | `AlertStyleType.Warn` | `AlertStyleType.Error`
+**Colours:** any `color`: a `ThemeColor` (default `Primary`) or any CSS colour, see [ThemeColor.md](ThemeColor.md). A `ThemeColor` also picks the icon: a bell for `Primary` and `Neutral`, then info, check, warning and cross. Any other colour shows `icon`, or the bell.
 
 ```tsx
-import { Alert, AlertStyleType } from '@ahrowe/ui';
+import { Alert, ThemeColor } from '@ahrowe/ui';
 
-// Default, neutral message
-<Alert>A default, neutral message.</Alert>
+// In the primary colour, the default
+<Alert>Here is what changed since your last visit.</Alert>
 
-// Semantic variants
-<Alert styleType={AlertStyleType.Info}>Here's something worth knowing.</Alert>
-<Alert styleType={AlertStyleType.Success}>Your changes were saved.</Alert>
-<Alert styleType={AlertStyleType.Warn}>Your storage is almost full.</Alert>
-<Alert styleType={AlertStyleType.Error}>Something went wrong. Please try again.</Alert>
+// Semantic colours
+<Alert color={ThemeColor.Info}>Here's something worth knowing.</Alert>
+<Alert color={ThemeColor.Success}>Your changes were saved.</Alert>
+<Alert color={ThemeColor.Warn}>Your storage is almost full.</Alert>
+<Alert color={ThemeColor.Error}>Something went wrong. Please try again.</Alert>
 
 // With a title
-<Alert styleType={AlertStyleType.Warn} title="Storage almost full">
+<Alert color={ThemeColor.Warn} title="Storage almost full">
   You've used 92% of your available space. Free up room or upgrade your plan.
 </Alert>
 
@@ -30,7 +30,7 @@ import { Alert, AlertStyleType } from '@ahrowe/ui';
 const [visible, setVisible] = useState(true);
 {visible && (
   <Alert
-    styleType={AlertStyleType.Info}
+    color={ThemeColor.Info}
     title="New feature available"
     onClose={() => setVisible(false)}
   >
@@ -39,13 +39,13 @@ const [visible, setVisible] = useState(true);
 )}
 
 // Without the leading icon
-<Alert styleType={AlertStyleType.Success} hideIcon>
+<Alert color={ThemeColor.Success} hideIcon>
   A minimal message with no leading icon.
 </Alert>
 
-// Custom icon, overriding the styleType default
+// Custom icon, overriding the colour's own
 import { faRocket } from '@fortawesome/free-solid-svg-icons';
-<Alert styleType={AlertStyleType.Info} icon={faRocket}>
+<Alert color={ThemeColor.Info} icon={faRocket}>
   Shipping a new release tonight.
 </Alert>
 ```
@@ -56,8 +56,8 @@ import { faRocket } from '@fortawesome/free-solid-svg-icons';
 |------|------|-------------|
 | `title` | `ReactNode` | Optional bold heading above the description |
 | `children` | `ReactNode` | The message body |
-| `styleType` | `AlertStyleType` | Colour variant and default icon (default `Default`) |
-| `icon` | `IconDefinition \| ReactElement` | Overrides the default icon for `styleType` — FontAwesome icon or any React element |
+| `color` | `ColorValue` | A `ThemeColor` (default `Primary`) or any CSS colour; a `ThemeColor` also picks the icon |
+| `icon` | `IconDefinition \| ReactElement` | Overrides the colour's icon — FontAwesome icon or any React element |
 | `hideIcon` | `boolean` | Hide the leading icon entirely |
 | `onClose` | `() => void` | Shows a close button and is called when it's clicked. `Alert` doesn't hide itself, so stop rendering it (or update your own state) in the handler |
 
@@ -70,3 +70,13 @@ import { faRocket } from '@fortawesome/free-solid-svg-icons';
 ## Sizing
 
 Every length in an alert is `em`, so the padding, the icon, the close button and the accent bar keep their ratios to the body copy at any base font.
+
+## Migration from `AlertStyleType`
+
+Before 0.43 an Alert's colour was `styleType`, typed `AlertStyleType`. It is now `color`, typed
+`ColorValue`, and `AlertStyleType` is gone, so TypeScript points at every use:
+
+| Before | After |
+|--------|-------|
+| `styleType={AlertStyleType.Default}` | nothing: `Primary` is the default, with the same bell |
+| `styleType={AlertStyleType.Info}` (and `Success`, `Warn`, `Error`) | `color={ThemeColor.Info}` |

package/docs/AnimatedLogo.md

@@ -49,7 +49,7 @@ import { AnimatedLogo } from '@ahrowe/ui';
 | `path` | `string` | SVG path `d` data to draw and fill (default: the AhroweUI mark). Multiple subpaths (several `M` commands in one `d`) are supported. |
 | `viewBox` | `string` | `viewBox` matching `path`'s coordinate space (default: the AhroweUI mark's viewBox) |
 | `size` | `number \| string` | Width/height of the root `svg` (default `96`) |
-| `color` | `string` | Overrides stroke/fill colour (default `var(--primary-color)`) |
+| `color` | `ColorValue` | The stroke and fill: a `ThemeColor` or any CSS colour (default `--primary-color`) |
 | `duration` | `number` | Length of one draw-fill cycle, in seconds (default `4.2`) |
 | `loop` | `boolean` | Repeats the draw-fill-retract cycle forever; `false` plays once and holds filled (default `true`) |
 | `fill` | `boolean` | Fills the interior once drawn; `false` keeps it an outline-only trace (default `true`) |

package/docs/Badge.md

@@ -4,14 +4,14 @@
 
 **Keywords:** pill
 
-**Import:** `import { Badge, BadgeStyleType, BadgePosition } from '@ahrowe/ui'`
+**Import:** `import { Badge, BadgeStyleType, BadgePosition, ThemeColor } from '@ahrowe/ui'`
 
-**Style variants:** `BadgeStyleType.Default` | `BadgeStyleType.Primary` (default) | `BadgeStyleType.Success` | `BadgeStyleType.Info` | `BadgeStyleType.Warn` | `BadgeStyleType.Error`
+**Styles:** `BadgeStyleType.Filled` (default) | `BadgeStyleType.Light` | `BadgeStyleType.Outlined`, in any `color`: a `ThemeColor` (default `Primary`) or any CSS colour, see [ThemeColor.md](ThemeColor.md). A `dot` is always solid.
 
-**Position (when wrapping `children`):** `BadgePosition.TopRight` (default) | `BadgePosition.TopLeft` | `BadgePosition.BottomRight` | `BadgePosition.BottomLeft`
+**Position (when wrapping `children`):** `BadgePosition.TopRight` (default) | `BadgePosition.TopLeft` | `BadgePosition.BottomRight` | `BadgePosition.BottomLeft`. A badge over its `children` sits on the page colour, so `Light`, `Outlined` and a `Neutral` `Filled` look as they do on the page instead of letting the avatar or icon show through.
 
 ```tsx
-import { Badge, BadgeStyleType } from '@ahrowe/ui';
+import { Badge, BadgeStyleType, ThemeColor } from '@ahrowe/ui';
 import { faBell } from '@fortawesome/free-solid-svg-icons';
 import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
 
@@ -25,10 +25,13 @@ import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
 <Badge content="NEW" />
 
 // Plain dot, no text
-<Badge dot styleType={BadgeStyleType.Error} />
+<Badge dot color={ThemeColor.Error} />
+
+// A status label
+<Badge content="Paid" styleType={BadgeStyleType.Light} color={ThemeColor.Success} />
 
 // Overlaying an icon
-<Badge count={12} styleType={BadgeStyleType.Error}>
+<Badge count={12} color={ThemeColor.Error}>
   <FontAwesomeIcon icon={faBell} />
 </Badge>
 
@@ -47,8 +50,22 @@ import { FontAwesomeIcon } from '@fortawesome/react-fontawesome';
 | `content` | `ReactNode` | Custom content overriding the computed `count` text |
 | `dot` | `boolean` | Render as a plain dot with no text |
 | `showZero` | `boolean` | Show the badge when `count` is `0` |
-| `styleType` | `BadgeStyleType` | Colour variant (default `Primary`) |
+| `styleType` | `BadgeStyleType` | `Filled` (default), `Light` or `Outlined`. Ignored by a `dot` |
+| `color` | `ColorValue` | A `ThemeColor` (default `Primary`) or any CSS colour |
 | `position` | `BadgePosition` | Corner the badge attaches to when wrapping `children` (default `TopRight`) |
 | `children` | `ReactNode` | Element the badge overlays. Omit to render the badge inline on its own |
 
 **Slots:** `badge`
+
+## Migration from colour styles
+
+Before 0.43, `BadgeStyleType` was a colour, and `Primary` was filled while the others were a light
+tint. Style and colour are now separate props, so every colour comes in every style. The old
+members are gone and TypeScript points at each:
+
+| Before | After |
+|--------|-------|
+| `styleType={BadgeStyleType.Primary}` | nothing: `Filled` `Primary` is the default |
+| `styleType={BadgeStyleType.Default}` | `styleType={BadgeStyleType.Light} color={ThemeColor.Neutral}` |
+| `styleType={BadgeStyleType.Success}` (and `Info`, `Warn`, `Error`) | `styleType={BadgeStyleType.Light} color={ThemeColor.Success}` |
+| `dot styleType={BadgeStyleType.Error}` | `dot color={ThemeColor.Error}` |

package/docs/Button.md

@@ -1,37 +1,57 @@
 # Button
 
-**When to use:** Primary interactive action trigger. Supports loading state, icon, multiple visual styles and sizes.
+**When to use:** Primary interactive action trigger. Supports loading state, icon, four styles in any colour, and sizes.
 
-**Keywords:** cta, action button
+**Keywords:** cta, action button, ghost, text button, borderless, subtle, variant, danger, destructive, secondary
 
-**Import:** `import { Button, ButtonStyleType, ButtonSize, ButtonType } from '@ahrowe/ui'`
+**Import:** `import { Button, ButtonStyleType, ButtonSize, ButtonType, ThemeColor } from '@ahrowe/ui'`
+
+A button has a **style** (how much it stands out) and a **color**, set independently: any style
+works with any colour. The colours are the library-wide `ThemeColor`s or any CSS colour, see
+[ThemeColor.md](ThemeColor.md).
 
 ```tsx
-import { Button, ButtonStyleType, ButtonSize } from '@ahrowe/ui';
-import { faSave } from '@fortawesome/free-solid-svg-icons';
+import { Button, ButtonStyleType, ButtonSize, ButtonType, ThemeColor } from '@ahrowe/ui';
+import { faPlus, faSave, faTrash, faXmark } from '@fortawesome/free-solid-svg-icons';
 
-// Primary
-<Button styleType={ButtonStyleType.Primary} onClick={handleSave}>Save</Button>
+// The main action
+<Button styleType={ButtonStyleType.Filled} onClick={handleSave}>Save</Button>
 
-// With icon + loading state
+// Secondary: Outlined is the default style, Primary the default colour
+<Button onClick={handleCancel}>Cancel</Button>
+<Button color={ThemeColor.Neutral} onClick={handleCancel}>Cancel</Button>
+
+// Destructive
+<Button styleType={ButtonStyleType.Filled} color={ThemeColor.Error} onClick={handleDelete}>Delete</Button>
+
+// A trash icon in a table row
 <Button
-  styleType={ButtonStyleType.Primary}
-  icon={faSave}
-  isLoading={isSaving}
-  onClick={handleSave}
->
+  styleType={ButtonStyleType.Plain}
+  color={ThemeColor.Error}
+  size={ButtonSize.Icon}
+  icon={faTrash}
+  aria-label="Delete row"
+  style={{ width: 32, height: 32 }}
+/>
+
+// A close button: Neutral takes the text colour of whatever it sits on
+<Button
+  styleType={ButtonStyleType.Plain}
+  color={ThemeColor.Neutral}
+  size={ButtonSize.Icon}
+  icon={faXmark}
+  aria-label="Close"
+  style={{ width: 32, height: 32 }}
+/>
+
+// With icon + loading state
+<Button styleType={ButtonStyleType.Filled} icon={faSave} isLoading={isSaving} onClick={handleSave}>
   Save
 </Button>
 
-// Delete / danger
-<Button styleType={ButtonStyleType.Delete} onClick={handleDelete}>Delete</Button>
-
 // Small
 <Button size={ButtonSize.Small}>Cancel</Button>
 
-// Icon-only — padding-free and square; give it the box size you want
-<Button size={ButtonSize.Icon} icon={faPlus} aria-label="Add" style={{ width: 44, height: 44 }} />
-
 // Press-and-hold: act on press rather than release
 <Button
   icon={faPlus}
@@ -42,12 +62,13 @@ import { faSave } from '@fortawesome/free-solid-svg-icons';
 />
 
 // Submit button in a form
-<Button type={ButtonType.Submit} styleType={ButtonStyleType.Primary}>Submit</Button>
+<Button type={ButtonType.Submit} styleType={ButtonStyleType.Filled}>Submit</Button>
 ```
 
 **Enums:**
 
-- `ButtonStyleType`: `Primary` | `Default` | `Delete`
+- `ButtonStyleType`: `Filled` | `Light` | `Outlined` (default) | `Plain`
+- `ThemeColor`: `Primary` (default) | `Neutral` | `Success` | `Info` | `Warn` | `Error`
 - `ButtonSize`: `Default` | `Small` | `Medium` | `Large` | `Icon`
 - `ButtonType`: `Button` | `Reset` | `Submit`
 
@@ -55,41 +76,42 @@ import { faSave } from '@fortawesome/free-solid-svg-icons';
 
 | Prop | Type | Description |
 |------|------|-------------|
-| `styleType` | `ButtonStyleType` | Visual variant |
+| `styleType` | `ButtonStyleType` | `Filled`: solid fill, for the one main action. `Light`: a tint of the colour behind text in the colour. `Outlined` (default): border and text in the colour. `Plain`: text in the colour, no fill or border, for toolbar, icon and close buttons |
+| `color` | `ColorValue` | A `ThemeColor` (default `Primary`) or any CSS colour. `Neutral` takes the surrounding text colour, with a `--border-color` outline; `Error` is for destructive actions. See [ThemeColor.md](ThemeColor.md) |
 | `size` | `ButtonSize` | Size variant. `Icon` strips all padding, inherits the surrounding text size, and centres a lone icon — set the width/height yourself |
 | `type` | `ButtonType` | HTML button type |
 | `icon` | `IconDefinition \| ReactElement` | FontAwesome icon or any React element, shown before label |
-| `isLoading` | `boolean` | Replaces content with a spinner |
-| `disabled` | `boolean` | |
+| `isLoading` | `boolean` | Replaces content with a [Loader](Loader.md) in the button's text colour. Blocks clicks like `disabled` but keeps full colour |
+| `disabled` | `boolean` | Fades the button to half opacity |
 | `onClick` | `(e: MouseEvent) => void \| Promise<void>` | |
 
 `ButtonProps` extends `React.ButtonHTMLAttributes<HTMLButtonElement>`, so every native `<button>`
 attribute is accepted and forwarded — pointer handlers (`onPointerDown` and friends, for
 press-and-hold controls that act on press rather than release), `onContextMenu`, `tabIndex`,
 `name`, `value`, `form`, `autoFocus`, and the rest. `type` and `onClick` are narrowed: `type`
-takes the `ButtonType` enum, and `onClick` may return a promise.
+takes the `ButtonType` enum, and `onClick` may return a promise. `color` is Button's own prop, not
+the obsolete HTML attribute.
 
-**Theming (default style):** the `Default` style is transparent text-coloured by default. Override it theme-wide (or per button via `style`) without touching `Primary`/`Delete`:
+**Theming:** each colour reads the theme variables listed in [ThemeColor.md](ThemeColor.md). The
+`Filled` `Primary` button also paints `--primary-gradient` when the theme sets one. See
+[ThemeProvider.md](ThemeProvider.md).
 
-- `--button-default-background` — fill (default transparent)
-- `--button-default-color` — text colour (default `var(--text-color)`)
-- `--button-default-border` — full `border` shorthand, e.g. `1px solid var(--border-color)` (default a transparent `1px` border)
+## Custom colours and presets
 
-Every button reserves a transparent `1px` border, so switching `--button-default-border` on never shifts layout or changes button height. See [ThemeProvider.md](ThemeProvider.md).
+`color` takes any CSS colour as well as a `ThemeColor`; the text on a `Filled` button is picked
+for contrast. Presets are a component in your app, and a section or the whole app takes a default
+through `ConfigProvider`. All three are in [ThemeColor.md](ThemeColor.md).
 
 ```tsx
-// Outlined default buttons across the app
-const theme: Theme = {
-  id: 'brand',
-  variables: { '--button-default-border': '1px solid var(--border-color)' },
-};
-
-// Or one-off via style
-<Button style={{ '--button-default-border': '1px solid var(--border-color)' } as React.CSSProperties}>
-  Cancel
-</Button>
+<Button styleType={ButtonStyleType.Filled} color="var(--brand)">Upgrade</Button>
 ```
 
+**States:** hover and press lay a tint of the button's own text colour over the whole button, so
+every style, colour and theme gets them with no variables of their own. The keyboard focus ring
+sits inside the edge, in `--focus-border-color`, or in the text colour on a `Filled` button. The
+ripple is in the text colour too. Every button reserves a `1px` border, so switching style never
+shifts layout or changes its height.
+
 **Slots:** `background` `content` `loadingContainer` `label`
 
 **Sizing in a flex row:** a Button never shrinks below its own content (`min-width: min-content`),
@@ -100,3 +122,39 @@ so an icon is never cut off by a flexible sibling. A multi-word label still wrap
 A Button is sized by its font. `--default-font-size` is the base, and `Small` and `Large` are multiples of it (0.75x and 1.25x), so a theme with a smaller base font gets proportionally smaller controls everywhere. Padding and the icon gap are in `em`, so the whole box grows with the label rather than a large button wearing a default button's padding.
 
 `ButtonSize.Icon` is the exception: it inherits the surrounding text size and has no padding at all, because the caller sets the box.
+
+## Migration from `Primary`, `Default` and `Delete`
+
+Before 0.43, `styleType` set emphasis and colour in one value. `Primary`, `Default` and `Delete` no
+longer exist, so TypeScript points at every place that names them:
+
+| Before | After |
+|--------|-------|
+| `styleType={ButtonStyleType.Primary}` | `styleType={ButtonStyleType.Filled}` |
+| `styleType={ButtonStyleType.Default}` | nothing: `Outlined` is the default |
+| `styleType={ButtonStyleType.Delete}` | `styleType={ButtonStyleType.Filled} color={ThemeColor.Error}` |
+| ActionButtons `submitButtonStyle={ButtonStyleType.Delete}` | `submitButtonColor={ThemeColor.Error}` |
+| SplitButton `styleType={ButtonStyleType.Delete}` | `color={ThemeColor.Error}` (`Filled` is its default) |
+| Card action `styleType: ButtonStyleType.Delete` | `styleType: ButtonStyleType.Filled, color: ThemeColor.Error` |
+| `defaultProps={{ Button: { styleType: ButtonStyleType.Primary } }}` | `defaultProps={{ Button: { styleType: ButtonStyleType.Filled } }}` |
+
+Two things compile unchanged and need a look of their own:
+
+**A Button with no `styleType`.** It was transparent text in `--text-color` unless the theme set
+`--button-default-*`; the built-in `defaultTheme` made it an outline in `--primary-color`, which
+is now the default everywhere. To keep the old look where you want it, use
+`styleType={ButtonStyleType.Plain} color={ThemeColor.Neutral}`.
+
+**`--button-default-background`, `--button-default-color` and `--button-default-border` in a
+theme.** They are gone, and since a theme accepts any variable they still compile and do nothing.
+What they styled is now the default `color`, set once on `AhroweProvider`:
+
+| Theme set | Instead |
+|-----------|---------|
+| `--button-default-color: var(--text-color)` and a `--border-color` border | `defaultProps={{ Button: { color: ThemeColor.Neutral } }}` |
+| another colour | `defaultProps={{ Button: { color: 'var(--your-colour)' } }}` |
+| a fill in `--button-default-background` | also `styleType: ButtonStyleType.Filled`; `ThemeColor.Neutral` fills with a mix of the text colour |
+
+A default prop does not change with the theme. Where each theme had its own default button, give
+each theme a variable of your own, `'--app-button': '…'`, and set
+`defaultProps={{ Button: { color: 'var(--app-button)' } }}` once: the variable follows the theme.

package/docs/ButtonGroup.md

@@ -13,23 +13,23 @@ import { ButtonGroup, ButtonGroupOrientation, Button, ButtonStyleType } from '@a
 
 // Segmented toggle
 <ButtonGroup>
-  <Button styleType={ButtonStyleType.Default}>Day</Button>
-  <Button styleType={ButtonStyleType.Default}>Week</Button>
-  <Button styleType={ButtonStyleType.Default}>Month</Button>
+  <Button styleType={ButtonStyleType.Outlined}>Day</Button>
+  <Button styleType={ButtonStyleType.Outlined}>Week</Button>
+  <Button styleType={ButtonStyleType.Outlined}>Month</Button>
 </ButtonGroup>
 
 // Icon toolbar
 <ButtonGroup>
-  <Button styleType={ButtonStyleType.Default} icon={faBold} aria-label="Bold" />
-  <Button styleType={ButtonStyleType.Default} icon={faItalic} aria-label="Italic" />
-  <Button styleType={ButtonStyleType.Default} icon={faUnderline} aria-label="Underline" />
+  <Button styleType={ButtonStyleType.Outlined} icon={faBold} aria-label="Bold" />
+  <Button styleType={ButtonStyleType.Outlined} icon={faItalic} aria-label="Italic" />
+  <Button styleType={ButtonStyleType.Outlined} icon={faUnderline} aria-label="Underline" />
 </ButtonGroup>
 
 // Vertical
 <ButtonGroup orientation={ButtonGroupOrientation.Vertical}>
-  <Button styleType={ButtonStyleType.Default}>Bold</Button>
-  <Button styleType={ButtonStyleType.Default}>Italic</Button>
-  <Button styleType={ButtonStyleType.Default}>Underline</Button>
+  <Button styleType={ButtonStyleType.Outlined}>Bold</Button>
+  <Button styleType={ButtonStyleType.Outlined}>Italic</Button>
+  <Button styleType={ButtonStyleType.Outlined}>Underline</Button>
 </ButtonGroup>
 
 // With a separator — filled styles (Primary/Delete) have no border of their own to merge,
@@ -37,23 +37,23 @@ import { ButtonGroup, ButtonGroupOrientation, Button, ButtonStyleType } from '@a
 import { Divider, DividerOrientation } from '@ahrowe/ui';
 
 <ButtonGroup>
-  <Button styleType={ButtonStyleType.Primary}>Save</Button>
+  <Button styleType={ButtonStyleType.Filled}>Save</Button>
   <Divider orientation={DividerOrientation.Vertical} />
-  <Button styleType={ButtonStyleType.Primary}>Save & new</Button>
+  <Button styleType={ButtonStyleType.Filled}>Save & new</Button>
 </ButtonGroup>
 
 // Nested groups — a toolbar made of two self-contained sub-groups, spaced apart rather
 // than merged into one continuous strip
 <ButtonGroup>
   <ButtonGroup>
-    <Button styleType={ButtonStyleType.Default} icon={faBold} aria-label="Bold" />
-    <Button styleType={ButtonStyleType.Default} icon={faItalic} aria-label="Italic" />
-    <Button styleType={ButtonStyleType.Default} icon={faUnderline} aria-label="Underline" />
+    <Button styleType={ButtonStyleType.Outlined} icon={faBold} aria-label="Bold" />
+    <Button styleType={ButtonStyleType.Outlined} icon={faItalic} aria-label="Italic" />
+    <Button styleType={ButtonStyleType.Outlined} icon={faUnderline} aria-label="Underline" />
   </ButtonGroup>
   <ButtonGroup>
-    <Button styleType={ButtonStyleType.Default} icon={faAlignLeft} aria-label="Align left" />
-    <Button styleType={ButtonStyleType.Default} icon={faAlignCenter} aria-label="Align center" />
-    <Button styleType={ButtonStyleType.Default} icon={faAlignRight} aria-label="Align right" />
+    <Button styleType={ButtonStyleType.Outlined} icon={faAlignLeft} aria-label="Align left" />
+    <Button styleType={ButtonStyleType.Outlined} icon={faAlignCenter} aria-label="Align center" />
+    <Button styleType={ButtonStyleType.Outlined} icon={faAlignRight} aria-label="Align right" />
   </ButtonGroup>
 </ButtonGroup>
 
@@ -64,7 +64,7 @@ import { Input } from '@ahrowe/ui';
 
 <ButtonGroup>
   <Input placeholder="Search…" value={search} onChange={setSearch} />
-  <Button styleType={ButtonStyleType.Primary} icon={faMagnifyingGlass} aria-label="Search" />
+  <Button styleType={ButtonStyleType.Filled} icon={faMagnifyingGlass} aria-label="Search" />
 </ButtonGroup>
 ```
 

package/docs/CLAUDE.md

@@ -32,8 +32,13 @@ enums and slot names. Do not infer props from a component's name.
 - **Text a component renders itself** (close buttons, empty messages, page labels) is set with its
   `labels` prop. App-wide defaults for any prop go through `AhroweProvider`'s `defaultProps`
   (ConfigProvider.md).
-- **Variants are enums**, not strings: `ButtonStyleType.Primary`, `ButtonSize.Small`. Each doc lists
+- **Variants are enums**, not strings: `ButtonStyleType.Filled`, `ButtonSize.Small`. Each doc lists
   them under **Enums**.
+- **Colours are one vocabulary.** Every `color` prop takes a `ThemeColor` (`Primary`, `Neutral`,
+  `Success`, `Info`, `Warn`, `Error`) or any CSS colour, and a separate `styleType` sets how much
+  the component stands out, so any style works in any colour (ThemeColor.md). Pick the style by
+  emphasis, the same way everywhere: `Filled` for the one main action of a region (at most one),
+  `Light` for status and selection, `Outlined` for secondary actions, `Plain` for tertiary ones.
 - **`icon` props** take a FontAwesome `IconDefinition` or any React element.
 - **`ref`** is a plain prop, there is no `forwardRef`. It lands on the element you would reach for:
   Input, Textarea, NumberInput and SearchInput hand out their inner `<input>`. Timer, Flip, Tilt,
@@ -44,6 +49,10 @@ enums and slot names. Do not infer props from a component's name.
   or validates a plan. No right-to-left support.
   `prefers-reduced-motion` is honoured. Built for Chrome and Edge 111, Firefox 114, Safari 16.4
   and newer, with no polyfills. The package is 0.x: a minor can break, a patch cannot.
+- **Upgrading.** Every breaking change has a `## Migration from …` section, an old-to-new table,
+  in the doc of the component it changed. When TypeScript reports a name as missing after an
+  update, search the docs for that name. `CHANGELOG.md` beside `docs/` lists every change by
+  version and names the section to read.
 
 ## Components
 
@@ -51,24 +60,24 @@ enums and slot names. Do not infer props from a component's name.
 
 | Doc | Exports | When to use |
 |-----|---------|-------------|
-| Accordion.md | Accordion | Collapsible sections for progressive disclosure — FAQs, settings panels, long-form content that users expand on demand |
+| Accordion.md | Accordion, AccordionStyleType, ThemeColor | Collapsible sections for progressive disclosure — FAQs, settings panels, long-form content that users expand on demand |
 | ActionButtons.md | ActionButtons | Standardised Submit / Cancel button pair for forms, dialogs, and drawer footers |
-| ActionIcon.md | ActionIcon | Clickable icon button without a label — toolbar actions, table row actions, icon-only controls |
+| ActionIcon.md | ActionIcon | Clickable icon button without a label — toolbar actions, table row actions, close buttons, icon-only controls |
 | AhroweProvider.md | AhroweProvider | The one wrapper an app needs, at its root: it applies the theme, sets default props for every component, shows toasts and renders the element that Modal, Tooltip, Popover, Menu and Toast portal into |
-| Alert.md | Alert, AlertStyleType | A persistent inline status message, used for form-level errors, page/section banners, empty-config warnings, and "here's what changed" notices |
+| Alert.md | Alert, ThemeColor | A persistent inline status message, used for form-level errors, page/section banners, empty-config warnings, and "here's what changed" notices |
 | AnimatedLogo.md | AnimatedLogo | A self-drawing SVG mark for splash/loading screens, empty states, or anywhere a brand or icon mark should feel alive rather than static |
 | AnimatedText.md | AnimatedText, AnimatedTextVariant, AnimatedTextUnit | Decorative text entrance or emphasis effect, for hero headlines, empty-state messages, "premium"/"new" callouts, loading/decoding states |
 | Avatar.md | Avatar, AvatarGroup | User or entity image — profile pictures, comment authors, member lists |
-| Badge.md | Badge, BadgeStyleType, BadgePosition | Small count or status indicator — unread counts, notification dots, "new" markers |
+| Badge.md | Badge, BadgeStyleType, BadgePosition, ThemeColor | Small count or status indicator — unread counts, notification dots, "new" markers |
 | BodyEnd.md | BodyEnd | Renders children through a React portal, to the end of the app |
 | Breadcrumb.md | Breadcrumb | A trail showing the current page's position within a hierarchy, with links back to each ancestor, such as a file browser path, a category/subcategory drill-down, or a multi-level settings page |
-| Button.md | Button, ButtonStyleType, ButtonSize, ButtonType | Primary interactive action trigger |
+| Button.md | Button, ButtonStyleType, ButtonSize, ButtonType, ThemeColor | Primary interactive action trigger |
 | ButtonGroup.md | ButtonGroup, ButtonGroupOrientation | Joins a row (or column) of buttons into a single seamless control, merging their borders and rounding only the outer corners |
-| Calendar.md | Calendar, CalendarView | Showing and editing your own events over time, in month, week, day and agenda views: bookings, shifts, appointments, a team schedule |
-| Card.md | Card, CardStyleType, CardHeader, CardMedia, CardContent, CardActions | Surface container for grouping related content — list items, profile cards, dashboard tiles, product listings |
+| Calendar.md | Calendar, CalendarView | Showing and editing your own events over time, in month, week, day and agenda views: bookings, shifts, appointments |
+| Card.md | Card, CardStyleType, CardHeader, CardMedia, CardContent, CardActions, ThemeColor | Surface container for grouping related content — list items, profile cards, dashboard tiles, product listings |
 | Carousel.md | Carousel | A slide track for stepping through a set of items one at a time, with arrows, dots, and drag/swipe support, plus optional autoplay |
 | Checkbox.md | Checkbox | Boolean toggle input — settings, multi-select lists, accept terms, feature flags |
-| Chip.md | Chip, ChipContainer, ChipStyleType | Compact tag, label, or filter token — selected items, applied filters, category badges, user avatars with remove |
+| Chip.md | Chip, ChipContainer, ChipStyleType, ThemeColor | Compact tag, label, or filter token — selected items, applied filters, category badges, user avatars with remove |
 | ColorPicker.md | ColorPicker | Hex colour selection — theme editors, annotation tools, customisation panels |
 | CommandPalette.md | CommandPalette | A search-first dialog for running any command or jumping anywhere in the app from the keyboard, usually opened with ⌘K / Ctrl+K |
 | ConfigProvider.md | ConfigProvider | Set global **default props** for library components once, near the root of your app, instead of repeating the same prop on every instance |
@@ -94,7 +103,8 @@ enums and slot names. Do not infer props from a component's name.
 | InteractableDiv.md | InteractableDiv | Accessible `<div>` that behaves like a button — click and keyboard (Enter/Space) events, with proper ARIA semantics |
 | KanbanBoard.md | KanbanBoard, KanbanColumn | Drag-and-drop board with columns — task management, workflow stages, status boards (e.g. Todo / In Progress / Done) |
 | KlipyPicker.md | KlipyPicker | GIF picker backed by the Klipy API — chat reactions, message composers, content authoring tools |
-| Loading.md | SpinnerLoading | A loading indicator for async operations: page loads, data fetching, or covering a region while it refreshes |
+| Loader.md | Loader, LoaderType, ThemeColor | A loading indicator for something in progress with no known end: a fetch, a save, a connection |
+| LoadingOverlay.md | LoadingOverlay, Loader, LoaderType | Covering content while it reloads: a table refreshing, a form saving, a panel fetching its next page |
 | Menu.md | Menu, menuHotkeys | A list of actions hanging off a trigger — a row's "more" button, a toolbar overflow, a context menu on a card |
 | Modal.md | Modal | Full overlay dialog — forms, detail views, confirmations, wizards that need to block the rest of the UI |
 | MultiSelect.md | MultiSelect | Pick several options from a list |
@@ -115,7 +125,7 @@ enums and slot names. Do not infer props from a component's name.
 | ScrollbarProvider.md | ScrollbarProvider | Applies custom scrollbar styling to a scrollable region — use to keep scrollbar appearance consistent with the theme |
 | SearchInput.md | SearchInput | Search field with built-in debouncing and an optional result count line — list filters, search-as-you-type pages |
 | SectionHeader.md | SectionHeader, SectionHeaderSize | A reusable heading block for the top of a page, panel, card, or any section — a title with an optional subtitle, a leading icon or thumbnail, and a trailing actions area |
-| Skeleton.md | Skeleton, SkeletonVariant, SkeletonAnimation | Content-shaped loading placeholder, shown while real content is being fetched — more polished than a spinner for content-heavy pages (lists, cards, profile headers) |
+| Skeleton.md | Skeleton, SkeletonVariant, SkeletonAnimation | Content-shaped loading placeholder, shown while real content is being fetched — more polished than a Loader for content-heavy pages (lists, cards, profile headers) |
 | Slider.md | Slider | Let the user pick a number from a continuous or stepped range by dragging a thumb: volume, brightness, price ranges, zoom, quality presets |
 | SplitButton.md | SplitButton | A primary action button with a small attached dropdown for closely related secondary actions, e.g. "Save ▾" opening "Save as draft" / "Save and close" |
 | Stepper.md | Stepper | Step progress indicator for multi-step forms, onboarding flows, and checkout wizards |
@@ -123,12 +133,13 @@ enums and slot names. Do not infer props from a component's name.
 | Switch.md | Switch | Sliding boolean toggle — settings panels, feature flags, preference lists |
 | TabHeader.md | TabHeader | A horizontal row of tabs to switch between sibling views or sections — settings panels, dashboards, detail pages |
 | Textarea.md | Textarea | Multiline text input — comments, descriptions, notes, code snippets, long-form content |
+| ThemeColor.md | ThemeColor | The `color` prop of every component that takes one: the theme's named colours, or any CSS colour of your own |
 | ThemeProvider.md | ThemeProvider | Applies a theme to its subtree, injecting its CSS custom properties as inline styles so every component inside can use them |
 | Tilt.md | Tilt, TiltGroup | Wrap content that should tilt toward the cursor in 3D |
 | TimeInput.md | TimeInput | Time-of-day selection — appointment times, opening hours, shift starts, reminders |
-| Timeline.md | Timeline, TimelineAlignment, TimelineItemStatus | A vertical list of dated events, connected by a line, for audit logs, activity feeds, order status history, and deploy logs |
+| Timeline.md | Timeline, TimelineAlignment, ThemeColor | A vertical list of dated events, connected by a line, for audit logs, activity feeds, order status history, and deploy logs |
 | Timer.md | Timer | A countdown timer with a depleting ring, add/remove-time and pause/cancel controls, and an imperative ref API |
-| Toast.md | showToast | Non-blocking notifications — save confirmations, error alerts, info messages, warnings |
+| Toast.md | showToast, ThemeColor | Non-blocking notifications — save confirmations, error alerts, info messages, warnings |
 | Tooltip.md | Tooltip | Contextual help, info icons, field explanations, error pointers |
 | Tree.md | Tree, flattenTree | A hierarchical list the user can expand, collapse and pick from: categories, nested locations, folder structures, org charts |
 | VirtualList.md | VirtualList | Efficiently render large lists or tables — thousands of rows rendered with a virtualised scroll window so only visible rows are in the DOM |