@carissa-io/theme-default 0.3.9 → 0.3.11

package/DESIGN.md

@@ -10,7 +10,7 @@ never changes to the components.
 
 ## Principles
 - **Objective clarity:** information is prioritized over decoration.
-- **Mathematical grid:** precise alignment and spacing, square corners.
+- **Mathematical grid:** precise alignment and spacing, square corners. "Square" means the token `$radius: 0`: every component reads that one token (the radio dot is the only round shape, and the date range band stays unrounded so it is unbroken), so the theme is square because the token is 0, and changing the token rounds all of it.
 - **High contrast:** absolute black (`#000`) for primary actions and focus; neutral scales for meta-data.
 
 ## Palette
@@ -18,9 +18,9 @@ never changes to the components.
 | :--- | :--- |
 | Primary | `#000000` |
 | Surface | `#fafafa` / `#f5f5f5` |
-| Border (fields) | `#737373` (hover and focus: `#000`, focus adds a 1px ring) |
+| Border (fields) | `#666666` (hover and focus: `#000`, focus adds a 1px ring) |
 | Text (body) | `#171717` |
-| Text (meta, placeholder) | `#737373` (4.7:1; lighter greys only for disabled states) |
+| Text (meta, placeholder) | `#666666` (5.7:1; lighter greys only for disabled states) |
 
 The same palette is available as Sass tokens (`$black`, `$muted`, `$surface`, `$error`...) in
 [scss/_tokens.scss](scss/_tokens.scss), the machine-readable palette: apps read them (for example to configure Bootstrap)
@@ -35,7 +35,7 @@ Both modes ship in the same package; dark is **opt-in per app** with `data-mode`
 | :--- | :--- | :--- |
 | `background` | `#ffffff` | `#0a0a0a` |
 | `text` | `#171717` | `#f5f5f5` |
-| `muted` | `#737373` | `#a3a3a3` |
+| `muted` | `#666666` | `#a3a3a3` |
 | `surface` | `#f5f5f5` | `#171717` |
 | `surface-active` | `#e5e5e5` | `#262626` |
 | `primary` | `#000000` | `#ffffff` |
@@ -63,8 +63,9 @@ Contrast (WCAG 2.x): text 4.5:1, borders and the focus ring 3:1.
 | Pair | Light | Dark |
 | :--- | :--- | :--- |
 | `text` on `background` | 17.93 | 18.16 |
-| `muted` on `background` (labels, placeholders, field borders) | 4.74 | 7.85 |
-| `muted` on `surface` | 4.35 | 7.11 |
+| `muted` on `background` (labels, placeholders, field borders) | 5.74 | 7.85 |
+| `muted` on `surface` | 5.27 | 7.11 |
+| `muted` on `surface-active` | 4.56 | 6.00 |
 | `on-primary` on `primary` | 21.00 | 21.00 |
 | `error` on `background` | 4.53 | 7.16 |
 | `focus` on `background` | 21.00 | 19.80 |
@@ -76,8 +77,8 @@ Contrast (WCAG 2.x): text 4.5:1, borders and the focus ring 3:1.
 
 The light `error` on `surface` (4.15) is below 4.5 for text, so the Alert never sets text in the status color (only the icon and the accent border, which need 3:1).
 
-`muted` on `surface` in light (4.35) is a known gap that already existed (muted text on the hover surface); the disabled states are exempt from
-WCAG but are listed in the backlog for a contrast review. Known gap in dark: the 0-width listbox option separator keeps the component default
+Every `muted` text pairing passes AA in both modes (a test asserts it): the light muted was `#737373`, which gave 4.35 on `surface` and 3.76 on
+`surface-active`, so it is now `#666666` (5.74 / 5.27 / 4.56). The disabled states are exempt from WCAG but are listed in the backlog for a contrast review. Known gap in dark: the 0-width listbox option separator keeps the component default
 (`#dee2e6`); it draws nothing today.
 
 ## Typography
@@ -114,7 +115,7 @@ Field text is 1rem (16px, which also avoids the zoom-on-focus of mobile browsers
 Three variants from [components-button](components/components-button), all square, 44px tall, with the same uppercase,
 bold, tracked 11px label as the field labels and 200ms color transitions.
 - **Primary:** black background, white text; hover `#262626`, active `#404040`.
-- **Secondary:** white background, 1px `#737373` border; on hover the border turns black and the background becomes `#e5e5e5` (`--c-surface-active`), so the state reads without relying on the border alone.
+- **Secondary:** white background, 1px `#666666` border; on hover the border turns black and the background becomes `#e5e5e5` (`--c-surface-active`), so the state reads without relying on the border alone.
 - **Ghost:** transparent; a `#f5f5f5` surface appears on hover.
 - **Disabled:** `#a3a3a3` text on a `#f5f5f5` surface (primary), or a lighter border (secondary, ghost); no hover.
 - **Focus:** keyboard focus (`:focus-visible`) follows the general rule below: secondary and ghost thicken their border to
@@ -123,7 +124,7 @@ bold, tracked 11px label as the field labels and 200ms color transitions.
 ## Checkbox
 From [components-checkbox](components/components-checkbox): the whole row (box and label) is the click target and is at
 least 44px tall. The label is body text (1rem, `#171717`), not the uppercase field-label style.
-- **Box:** 20px square, square corners, 1px `#737373` border; the border turns black on hover.
+- **Box:** 20px square, square corners, 1px `#666666` border; the border turns black on hover.
 - **Checked:** black background with a white Lucide `check` mark.
 - **Disabled:** `#a3a3a3` label and mark on a `#f5f5f5` box with a `#d4d4d4` border; no hover.
 - **Error:** `#dc3545`, 13px, under the row; the box border turns red too. The built-in error shows after the first
@@ -133,17 +134,17 @@ least 44px tall. The label is body text (1rem, `#171717`), not the uppercase fie
 
 ## Switch
 From [components-switch](components/components-switch), a checkbox with `role="switch"`, same row, label and error.
-- **Track:** 40 x 20px, square, white with a 1px `#737373` border (black on hover); a `#737373` square thumb.
+- **Track:** 40 x 20px, square, white with a 1px `#666666` border (black on hover); a `#666666` square thumb.
 - **On:** black track, white thumb; the thumb slides in 200ms, like the other color transitions.
 - **Disabled:** `#f5f5f5` track with a `#d4d4d4` border and an `#a3a3a3` thumb.
 - **Focus:** an off track thickens its border to 2px; an on (black) track draws a 1px black ring offset by 2px.
 
 ## Radio group
 From [components-radio-group](components/components-radio-group): a fieldset whose legend uses the field-label style
-(11px, bold, uppercase, tracked, `#737373`). Each option row (dot and label) is the click target and is at least 44px
+(11px, bold, uppercase, tracked, `#666666`). Each option row (dot and label) is the click target and is at least 44px
 tall; the label is body text (1rem, `#171717`).
 - **Dot:** 20px circle (the one round shape in the theme: a radio is a circle, so its radius is not the square `$radius`),
-  1px `#737373` border; the border turns black on hover.
+  1px `#666666` border; the border turns black on hover.
 - **Checked:** black border with a 10px black inner dot on white.
 - **Disabled:** `#a3a3a3` label on a `#f5f5f5` dot with a `#d4d4d4` border; no hover. A single option can be disabled too.
 - **Error:** `#dc3545`, 13px, under the options; the dots get a red border. The built-in error shows after the first
@@ -153,7 +154,7 @@ tall; the label is body text (1rem, `#171717`).
 
 ## Textarea
 From [components-textarea](components/components-textarea), which is the input with `multiline`: it uses exactly the
-input's look (notched uppercase label, 1px `#737373` border that turns black on hover and focus, 1px black focus ring,
+input's look (notched uppercase label, 1px `#666666` border that turns black on hover and focus, 1px black focus ring,
 `#dc3545` error). Only the control differs:
 - **Height:** at least 6rem (about three lines of 16px text) and resizable vertically only, so it never breaks the grid;
   `rows` sets the initial height.
@@ -161,9 +162,9 @@ input's look (notched uppercase label, 1px `#737373` border that turns black on
 
 ## Slider
 From [components-slider](components/components-slider), a native range input; the row is at least 44px tall. The label
-uses the field-label style (11px, bold, uppercase, tracked, `#737373`); the optional live value, on the same line at
+uses the field-label style (11px, bold, uppercase, tracked, `#666666`); the optional live value, on the same line at
 the right, is body text (1rem, `#171717`).
-- **Track:** a 2px `#737373` line, square; the part before the thumb is black.
+- **Track:** a 2px `#666666` line, square; the part before the thumb is black.
 - **Thumb:** 20px black square with a 1px white border (so it stays distinct where it crosses the track); `#262626` on
   hover, `#404040` while dragging.
 - **Disabled:** `#a3a3a3` label, thumb and fill on a `#d4d4d4` track; no hover.
@@ -171,7 +172,7 @@ the right, is body text (1rem, `#171717`).
 
 ## Popover
 From [components-popover](components/components-popover), the floating panel behind the select, combobox and date picker:
-white, a 1px `#737373` border, square corners and no shadow (flat, like the rest of the theme), 4px below its anchor.
+white, a 1px `#666666` border, square corners and no shadow (flat, like the rest of the theme), 4px below its anchor.
 It fades in over 200ms and opens above the anchor when there is no room below. It has no padding of its own: the
 content (a list, a calendar) brings its spacing.
 
@@ -181,32 +182,32 @@ least 44px tall, body text (1rem, `#171717`) with 0.75rem of horizontal padding.
 - **Active** (hover or keyboard cursor): `#f5f5f5` surface.
 - **Selected:** bold text with a 2px black bar on the inline-start edge.
 - **Disabled:** `#a3a3a3`, no hover.
-- **Empty:** a `#737373` message with 0.75rem of padding.
+- **Empty:** a `#666666` message with 0.75rem of padding.
 - **Height:** at most 15rem; longer lists scroll.
 
 ## Select
 From [components-select](components/components-select): a custom list, so it looks the same in every browser. The closed
-field is the Input (notched uppercase label, 1px `#737373` border, black on hover and focus, 44px tall); the value reads
-as body text, and the placeholder is `#737373` like the input placeholder. A 16px `#737373` chevron sits on the right
+field is the Input (notched uppercase label, 1px `#666666` border, black on hover and focus, 44px tall); the value reads
+as body text, and the placeholder is `#666666` like the input placeholder. A 16px `#666666` chevron sits on the right
 and turns black; when the list is open it rotates 180 degrees over 200ms and the border stays black. The open panel is
 the Popover and the options are the Listbox, as wide as the field. Errors, required marker and disabled look are the
 Input's.
 
 ## Combobox
 From [components-combobox](components/components-combobox): the Select field with a text input in place of the button, so
-the user can type to filter the list. Same Input look (notched uppercase label, 1px `#737373` border, black on hover and
-focus, 44px tall), same 16px `#737373` chevron that turns black and rotates 180 degrees when the list is open. The text
-is body text (`#171717`) and the placeholder `#737373`. A press anywhere in the box focuses the input (the chevron is
+the user can type to filter the list. Same Input look (notched uppercase label, 1px `#666666` border, black on hover and
+focus, 44px tall), same 16px `#666666` chevron that turns black and rotates 180 degrees when the list is open. The text
+is body text (`#171717`) and the placeholder `#666666`. A press anywhere in the box focuses the input (the chevron is
 decorative, not a button); the list opens when typing or with the arrow keys. The panel is the Popover and the options
 the Listbox, as wide as the field; a message such as "No results" uses the Listbox empty style. Errors, required marker
 and disabled look are the Input's.
 
 ## Upload
 From [components-upload](components/components-upload): the Input field turned into a dropzone. The box keeps the
-notched uppercase label and the 1px `#737373` border but dashed, black on hover; while files are dragged over it the
-border is black and the background `#f5f5f5`. The zone is at least 5.5rem tall and centers its content as muted (`#737373`)
+notched uppercase label and the 1px `#666666` border but dashed, black on hover; while files are dragged over it the
+border is black and the background `#f5f5f5`. The zone is at least 5.5rem tall and centers its content as muted (`#666666`)
 body text, and the whole box is the click target. Chosen files are listed below the zone as 44px rows split by a 1px
-`#e5e5e5` line: the name in body text with an ellipsis, and a 44px square remove button (a multiplication sign, `#737373`,
+`#e5e5e5` line: the name in body text with an ellipsis, and a 44px square remove button (a multiplication sign, `#666666`,
 black on hover, 1px black focus ring). The focus ring of the box is the Input's. Errors, required marker and disabled look
 (`#a3a3a3` on `#f5f5f5`) are the Input's.
 
@@ -214,7 +215,7 @@ black on hover, 1px black focus ring). The focus ring of the box is the Input's.
 From [components-calendar](components/components-calendar): a standalone month grid (the date picker shows it inside the
 Popover, which draws the only border). It has no outer border. The header is two 44px navigation buttons (muted
 chevrons that turn black, 1px black focus ring drawn inside) around the month and year in the label style (11px, bold,
-uppercase, `0.1em` tracking, `#737373`); the weekday row uses the same style. Days are 44px squares in body text
+uppercase, `0.1em` tracking, `#666666`); the weekday row uses the same style. Days are 44px squares in body text
 (`#171717`) with square corners and a `#f5f5f5` hover. The selected day is a black square with white text; today is a
 1px black border, drawn inside the square so nothing shifts. Days outside `min..max` are `#a3a3a3` with no hover, and
 the days of the neighbor months are left empty. The keyboard focus ring is 1px black, inset. The grid always shows six
@@ -222,20 +223,20 @@ weeks so the height never changes between months.
 
 ## Date picker
 From [components-date-picker](components/components-date-picker): the Select field with a calendar in the panel. The closed
-field is the Input (notched uppercase label, 1px `#737373` border, black on hover and focus, 44px tall); the chosen date
-reads as body text (for example "Oct 14, 2026") and the placeholder is `#737373`. A 16px `#737373` calendar icon sits on the
+field is the Input (notched uppercase label, 1px `#666666` border, black on hover and focus, 44px tall); the chosen date
+reads as body text (for example "Oct 14, 2026") and the placeholder is `#666666`. A 16px `#666666` calendar icon sits on the
 right and turns black on hover and while open; it does not rotate, and the border stays black while open. The open panel
-is the Popover (1px `#737373` border, no shadow) with 0.5rem of padding around the Calendar, as wide as the calendar
+is the Popover (1px `#666666` border, no shadow) with 0.5rem of padding around the Calendar, as wide as the calendar
 needs, not as the field. Errors, required marker and disabled look are the Input's.
 
 ## Search
 From [components-search](components/components-search): the Input of type search with two inline parts built on the input's
-`start` and `end` slots. The field is the Input's (notched uppercase label, 1px `#737373` border, black on hover and focus,
-44px tall; the keyboard focus rule below applies). A 20px `#737373` magnifier icon sits on the left and turns black while the
-field has the focus. The clear button appears on the right only while there is text: a 16px `#737373` cross in the Input's
+`start` and `end` slots. The field is the Input's (notched uppercase label, 1px `#666666` border, black on hover and focus,
+44px tall; the keyboard focus rule below applies). A 20px `#666666` magnifier icon sits on the left and turns black while the
+field has the focus. The clear button appears on the right only while there is text: a 16px `#666666` cross in the Input's
 44px side-button box that turns black on hover; the browser's own clear button is hidden so the look is the same everywhere.
 Errors, required marker and disabled look are the Input's. The Input and Textarea accept `start` and `end` content (a prefix
-icon, a unit) in the same muted color (`#737373`) with `0.5rem` between the content and the text.
+icon, a unit) in the same muted color (`#666666`) with `0.5rem` between the content and the text.
 
 ## Card
 From [components-card](components/components-card): `Card` with `CardHeader`, `CardBody` and `CardFooter`; the title and description are the Typography
@@ -275,7 +276,7 @@ placements. The look of each toast is the Alert's (see above), so its colors, ro
 only the fade stays. The region is in the page, not in the browser's top layer, so a toast shown while a modal is open sits behind the modal's backdrop.
 
 ## Divider
-From [components-divider](components/components-divider): `Divider`, a 1px line in `--c-muted` (the edge of the cards and fields: 4.74:1 on the background in light, 7.85:1 in dark),
+From [components-divider](components/components-divider): `Divider`, a 1px line in `--c-muted` (the edge of the cards and fields: 5.74:1 on the background in light, 7.85:1 in dark),
 1rem of space around it. With a label the text is the small `--c-muted` text (0.875rem, same contrast) with 0.75rem between it and each line. Horizontal is an `hr`, vertical and labelled
 ones are `role="separator"`.
 
@@ -283,7 +284,7 @@ ones are `role="separator"`.
 From [components-badge](components/components-badge): `Badge` in six variants and two sizes (`md` 0.75rem, `sm` 0.6875rem, bold), square like the rest, plus a `dot`. The variants are **tinted
 like the Alert**: 12% of the role color (`--c-primary`, `--c-success`, `--c-warning`, `--c-error`, `--c-info`) over `--c-background` with `color-mix`, a 1px border at 35% of the same color.
 **The text is always `--c-text`**, never the status color: it is 13.6:1 or more on every tint in both modes (light 13.63 to 15.32, dark 13.63 to 15.87), where the raw light `error` on its own tint would
-fail. Neutral is `--c-surface` with a `--c-muted` border (text 16.44:1). The **dot** carries the role color (`--c-muted` for neutral) and is 3:1 or more as a graphic on its tint in both modes: in light 3.81 (error), 4.21 (warning), 4.27 (success), 5.56 (info), 15.97 (primary) and 4.35 (neutral); in dark 6.25 or more. A dot has no text, so the caller gives it `aria-label`.
+fail. Neutral is `--c-surface` with a `--c-muted` border (text 16.44:1). The **dot** carries the role color (`--c-muted` for neutral) and is 3:1 or more as a graphic on its tint in both modes: in light 3.81 (error), 4.21 (warning), 4.27 (success), 5.56 (info), 15.97 (primary) and 5.27 (neutral); in dark 6.25 or more. A dot has no text, so the caller gives it `aria-label`.
 
 ## Tag
 From [components-tag](components/components-tag): `Tag`, a chip with the same six tints, the same text rule (`--c-text`, same ratios) and square corners as the Badge, bold, 0.875rem (`md`) or 0.75rem (`sm`). A removable tag is
@@ -291,7 +292,7 @@ one tab stop and takes the theme focus ring (1px `--c-focus`, offset 2px). The r
 
 ## Link
 From [components-link](components/components-link): `Link` in `default`, `subtle` and `inline`. The default is `--c-primary` (black in light, white in dark: 21:1 and 19.8:1 on the background), bold, **always underlined**: a black link
-beside near-black text is told apart by the underline alone, so there is no un-underlined default. Hover is `--c-primary-hover`. `subtle` is `--c-muted` (4.74:1 light, 7.85:1 dark), `--c-text` on hover. Focus is the theme ring
+beside near-black text is told apart by the underline alone, so there is no un-underlined default. Hover is `--c-primary-hover`. `subtle` is `--c-muted` (5.74:1 light, 7.85:1 dark), `--c-text` on hover. Focus is the theme ring
 (1px `--c-focus`, offset 2px). Disabled is `--c-disabled-text` at full opacity (exempt from contrast, as the other disabled states).
 
 ## Avatar
@@ -315,42 +316,42 @@ or focus, stays open while the pointer is over it and closes on `Escape`; the bu
 ## Prose
 From [components-prose](components/components-prose): `Prose`, raw HTML content (markdown, a CMS, an article) with the same hierarchy as `Heading` and `Text`. Body text is `--c-text` at 1rem and a 1.6 line height, 65ch wide (small and
 large scale the text and the headings by 0.875 and 1.125). Headings use the type scale tokens: `h1` and `h2` black (900), `h3` to `h6` bold, with the line heights of the typography block. Links are `--c-primary` and always underlined
-(21:1 light, 19.8:1 dark), `--c-primary-hover` on hover (15.13:1 and 15.72:1). The quote edge, the `hr` and the table borders are `--c-muted` (4.74:1 light, 7.85:1 dark, above the 3:1 of a graphic); the quote text and the figure
+(21:1 light, 19.8:1 dark), `--c-primary-hover` on hover (15.13:1 and 15.72:1). The quote edge, the `hr` and the table borders are `--c-muted` (5.74:1 light, 7.85:1 dark, above the 3:1 of a graphic); the quote text and the figure
 caption are `--c-muted` on the page background too. Code, `pre`, `kbd` and the table head sit on `--c-surface` with `--c-text` (16.44:1 in both modes); `kbd` has a `--c-muted` edge. Everything is square (`$radius`), code uses `$font-family-mono`.
-`--c-muted` is not used for text on `--c-surface` (4.35:1 in light).
+`--c-muted` on `--c-surface` is 5.27:1 in light (AA), though the code and table text stay `--c-text`.
 
 ## Tabs
-From [components-tabs](components/components-tabs): `Tabs`, `TabList`, `Tab` and `TabPanel`. A 1px `--c-muted` line runs under the list (4.74:1 light, 7.85:1 dark) and the selected tab has a 2px `--c-primary` indicator on it (21:1 light, 19.8:1 dark, well above the 3:1 of a graphic) with
-bold `--c-text` (17.93:1 / 18.16:1). The other tabs are bold `--c-muted` (4.74:1 / 7.85:1) and turn `--c-text` on a `--c-surface` hover (16.44:1 in both modes); `--c-muted` is never used for text on `--c-surface` (4.35:1 in light), so the hover changes the text too.
+From [components-tabs](components/components-tabs): `Tabs`, `TabList`, `Tab` and `TabPanel`. A 1px `--c-muted` line runs under the list (5.74:1 light, 7.85:1 dark) and the selected tab has a 2px `--c-primary` indicator on it (21:1 light, 19.8:1 dark, well above the 3:1 of a graphic) with
+bold `--c-text` (17.93:1 / 18.16:1). The other tabs are bold `--c-muted` (5.74:1 / 7.85:1) and turn `--c-text` on a `--c-surface` hover (16.44:1 in both modes); `--c-muted` on `--c-surface` is 5.27:1 in light (AA), and the hover still changes the text color too.
 Square, 0.875rem, 1.25rem by 0.625rem of padding. The indicator is a bottom edge (horizontal) or an inline end edge (vertical). Keyboard focus is the theme's 1px `--c-focus` ring, drawn inside the tab so the scrolling list does not clip it.
 
 ## Accordion
-From [components-accordion](components/components-accordion): `Accordion` and `AccordionItem`. The box and the rules between the items are 1px `--c-muted` (4.74:1 / 7.85:1); each header is a full-width bold `--c-text` button (17.93:1 / 18.16:1) with a `--c-surface` hover (16.44:1) and a chevron
+From [components-accordion](components/components-accordion): `Accordion` and `AccordionItem`. The box and the rules between the items are 1px `--c-muted` (5.74:1 / 7.85:1); each header is a full-width bold `--c-text` button (17.93:1 / 18.16:1) with a `--c-surface` hover (16.44:1) and a chevron
 that follows the text color and turns over when the item opens. 1.25rem of inline padding, 0.875rem of block padding on the header and 1rem on the content, square. Focus is the theme's 1px `--c-focus` ring, inside the header. The chevron is CSS, not an icon.
 
 ## Breadcrumb
-From [components-breadcrumb](components/components-breadcrumb): `Breadcrumb` and `BreadcrumbItem`. Links and separators are `--c-muted` (4.74:1 on the page in light, 7.85:1 in dark), links gain an underline and turn `--c-text` on hover (17.93:1 / 18.16:1), and the current page is bold `--c-text`
+From [components-breadcrumb](components/components-breadcrumb): `Breadcrumb` and `BreadcrumbItem`. Links and separators are `--c-muted` (5.74:1 on the page in light, 7.85:1 in dark), links gain an underline and turn `--c-text` on hover (17.93:1 / 18.16:1), and the current page is bold `--c-text`
 and not a link. 0.875rem text. Focus is the theme's 1px `--c-focus` ring, offset 2px. The separator is generated content, so screen readers do not read it.
 
 ## Pagination
 From [components-pagination](components/components-pagination): `Pagination`. The controls follow the secondary button: `--c-background` with a 1px `--c-muted` border, bold `--c-text` (17.93:1 / 18.16:1), `--c-surface-active` on hover (14.23:1 / 13.88:1),
-square, 44px minimum (the theme's touch target). The current page is filled: `--c-on-primary` on `--c-primary`, 21:1 in both modes. The ellipsis is `--c-muted` (4.74:1 / 7.85:1) and previous and next, drawn as CSS chevrons, are disabled
+square, 44px minimum (the theme's touch target). The current page is filled: `--c-on-primary` on `--c-primary`, 21:1 in both modes. The ellipsis is `--c-muted` (5.74:1 / 7.85:1) and previous and next, drawn as CSS chevrons, are disabled
 at the ends (half opacity). Focus is the theme's 1px `--c-focus` ring, offset 2px.
 
 ## Stepper
 From [components-stepper](components/components-stepper): `Stepper` and `Step`. The status is carried by the marker shape and the hidden status text, never by color alone: a done step is a filled `--c-primary` marker with a `--c-on-primary` check (21:1), the current one an outlined 2px
 `--c-primary` marker on `--c-background` with its number in `--c-text` (17.93:1 / 18.16:1), an upcoming one a `--c-surface-active` marker with its number in `--c-text` (14.23:1 / 13.88:1), and an error one a `--c-error` marker with a `--c-on-primary` mark
-(4.53:1 light, 7.59:1 dark) and a `--c-error` title (4.53:1 / 7.16:1). Titles are bold `--c-text`; upcoming titles and the descriptions are `--c-muted` (4.74:1 / 7.85:1). The connectors are 2px `--c-muted` lines (4.74:1 / 7.85:1, above 3:1)
+(4.53:1 light, 7.59:1 dark) and a `--c-error` title (4.53:1 / 7.16:1). Titles are bold `--c-text`; upcoming titles and the descriptions are `--c-muted` (5.74:1 / 7.85:1). The connectors are 2px `--c-muted` lines (5.74:1 / 7.85:1, above 3:1)
 and `--c-primary` once the step is done. Clickable (completed) steps are buttons with the theme's 1px `--c-focus` ring, offset 2px.
 
 ## Sidebar
-From [components-sidebar](components/components-sidebar): `Sidebar` and its parts. A `--c-surface` column (16rem, 4.5rem collapsed) with a 1px `--c-muted` edge (4.74:1 light, 7.85:1 dark). Items are bold `--c-text` (16.44:1 on the surface in both modes), 0.875rem with 0.625rem of block padding, with a `--c-surface-active`
+From [components-sidebar](components/components-sidebar): `Sidebar` and its parts. A `--c-surface` column (16rem, 4.5rem collapsed) with a 1px `--c-muted` edge (5.74:1 light, 7.85:1 dark). Items are bold `--c-text` (16.44:1 on the surface in both modes), 0.875rem with 0.625rem of block padding, with a `--c-surface-active`
 hover (14.23:1 light, 13.88:1 dark). The current page is filled: `--c-on-primary` on `--c-primary`, 21:1 in both modes, so it is told apart by shape and weight of fill, not by hue alone. Section titles use the label style (small, bold, uppercase, tracking) in `--c-text` and not
-`--c-muted`, which is only 4.35:1 on the surface in light. A disabled item is half opacity and not a link. The toggle is a 44px square, `--c-text` on a `--c-surface-active` hover. Square; focus is the theme's 1px `--c-focus` ring, inside the item.
+`--c-muted`, which is 5.27:1 on the surface in light. A disabled item is half opacity and not a link. The toggle is a 44px square, `--c-text` on a `--c-surface-active` hover. Square; focus is the theme's 1px `--c-focus` ring, inside the item.
 When collapsed the labels stay in the accessibility tree.
 
 ## Navbar
-From [components-navbar](components/components-navbar): `Navbar` and its parts. A `--c-background` bar with a 1px `--c-muted` bottom edge. The brand is bold `--c-text` (17.93:1 light, 18.16:1 dark). Items read like the tabs: bold `--c-muted` (4.74:1 / 7.85:1), `--c-text` on a `--c-surface` hover (16.44:1),
+From [components-navbar](components/components-navbar): `Navbar` and its parts. A `--c-background` bar with a 1px `--c-muted` bottom edge. The brand is bold `--c-text` (17.93:1 light, 18.16:1 dark). Items read like the tabs: bold `--c-muted` (5.74:1 / 7.85:1), `--c-text` on a `--c-surface` hover (16.44:1),
 and `--c-text` for the current page (`aria-current="page"`). The content collapses behind a 44px toggle below 48rem (the component's Sass breakpoint, a media query, no JS). Square; focus is the theme's 1px `--c-focus` ring, inside the item.
 
 ## Drawer
@@ -360,62 +361,71 @@ The panel slides in over `$transition-duration`; with reduced motion it just app
 
 ## Menu
 From [components-menu](components/components-menu): `Menu`, `MenuItem`, `MenuSeparator` and `MenuLabel`. The panel is the Popover's (`--c-background`, a 1px `--c-muted` border, flat). Items are `--c-text` with 0.625rem of block and 0.75rem of side padding, and hover and keyboard focus share a `--c-surface-active`
-background (14.23:1 light, 13.88:1 dark) plus the theme's 1px `--c-focus` ring. Labels are small `--c-muted` text (4.74:1 / 7.85:1 on the panel), the separator a 1px `--c-muted` line, a disabled item is half opacity. Square. The trigger is the app's own button, so its look is not part of the theme.
+background (14.23:1 light, 13.88:1 dark) plus the theme's 1px `--c-focus` ring. Labels are small `--c-muted` text (5.74:1 / 7.85:1 on the panel), the separator a 1px `--c-muted` line, a disabled item is half opacity. Square. The trigger is the app's own button, so its look is not part of the theme.
 
 ## Table
 From [components-table](components/components-table): `Table` and its parts. The header is `--c-surface` with bold `--c-text` (16.4:1 light, 16.4:1 dark), the rows are divided by 1px `--c-muted` lines, cells have 1rem by 0.75rem of padding (0.75rem by 0.375rem when dense) at the small size. **Row hover** is `--c-surface-active` (14.2:1 / 13.9:1 for `--c-text`), not `--c-surface`, so it still shows on a striped row (stripes are `--c-surface`). The **selected row** is a 12% tint of `--c-primary` over `--c-background`
-(`color-mix`, light `#e0e0e0`, dark `#272727`), so `--c-text` is 13.6:1 / 13.7:1 on it and the tint follows the mode with no extra role. The **sticky header** background is `--c-surface`, a custom property and therefore opaque in both modes (rows never show through, and dark gets its own value; the component's neutral default is a literal white and must not be used in dark). The caption is `--c-muted` (4.74:1 / 7.85:1 on the background). The sort arrows are CSS glyphs, so the direction is a shape and not only an opacity. Square, the theme's 1px `--c-focus` ring inside the cell and the scroll region.
+(`color-mix`, light `#e0e0e0`, dark `#272727`), so `--c-text` is 13.6:1 / 13.7:1 on it and the tint follows the mode with no extra role. The **sticky header** background is `--c-surface`, a custom property and therefore opaque in both modes (rows never show through, and dark gets its own value; the component's neutral default is a literal white and must not be used in dark). The caption is `--c-muted` (5.74:1 / 7.85:1 on the background). The sort arrows are CSS glyphs, so the direction is a shape and not only an opacity. Square, the theme's 1px `--c-focus` ring inside the cell and the scroll region.
 
 ## List
-From [components-list](components/components-list): `List` and `ListItem`. Rows sit on the page background, divided (or bordered) by 1px `--c-muted` lines, with 1rem by 0.75rem of padding. A link or button row highlights with `--c-surface-active` on hover (`--c-text` 14.2:1 / 13.9:1) and the current item (`aria-current`) takes the same 12% `--c-primary` tint as a selected table row (13.6:1 / 13.7:1). The secondary text is `--c-text` at the small size on purpose: `--c-muted` is 4.74:1 on the background but only 4.35:1 on `--c-surface` and 3.76:1 on `--c-surface-active`, both short of AA for text. Square, the theme's 1px `--c-focus` ring inside the row.
+From [components-list](components/components-list): `List` and `ListItem`. Rows sit on the page background, divided (or bordered) by 1px `--c-muted` lines, with 1rem by 0.75rem of padding. A link or button row highlights with `--c-surface-active` on hover (`--c-text` 14.2:1 / 13.9:1) and the current item (`aria-current`) takes the same 12% `--c-primary` tint as a selected table row (13.6:1 / 13.7:1). The secondary text is `--c-text` at the small size on purpose: `--c-muted` is 5.74:1 on the background but only 5.27:1 on `--c-surface` and 3.76:1 on `--c-surface-active`, both short of AA for text. Square, the theme's 1px `--c-focus` ring inside the row.
 
 ## Description list
-From [components-description-list](components/components-description-list): `DescriptionList`, `DescriptionTerm`, `DescriptionDetail` and `DescriptionItem`. The term is a small bold `--c-muted` label (4.74:1 light, 7.85:1 dark on the background; do not put a description list on `--c-surface` in light, where it is 4.35:1) and the detail is `--c-text`. No fills or borders: the layout (vertical, horizontal, grid) is the only thing it sets, with 2rem between columns and 1rem between pairs.
+From [components-description-list](components/components-description-list): `DescriptionList`, `DescriptionTerm`, `DescriptionDetail` and `DescriptionItem`. The term is a small bold `--c-muted` label (5.74:1 light, 7.85:1 dark on the background; do not put a description list on `--c-surface` in light, where it is 5.27:1) and the detail is `--c-text`. No fills or borders: the layout (vertical, horizontal, grid) is the only thing it sets, with 2rem between columns and 1rem between pairs.
 
 ## Stat
-From [components-stat](components/components-stat): `Stat`. A card-like block on `--c-background` with a 1px `--c-muted` border (the Card's outlined look), square, 1.25rem by 1.5rem of padding. It is not on `--c-surface` because the delta colors are checked against the background: **delta up is `--c-success`** (5.02:1 light, 11.36:1 dark), **delta down is `--c-error`** (4.53:1 light, 7.16:1 dark) and **flat is `--c-muted`** (4.74:1 / 7.85:1). On `--c-surface` the light `--c-error` would be 4.15:1, short of AA. The value is `--c-text` at the h1 size; the label and description are `--c-muted`. Color is never the only signal: the arrow glyph (up, down, flat) and the `delta_label` text for screen readers say the same. Whether "down" is good news (churn, cost) is the app's call: the color only follows the direction.
+From [components-stat](components/components-stat): `Stat`. A card-like block on `--c-background` with a 1px `--c-muted` border (the Card's outlined look), square, 1.25rem by 1.5rem of padding. It is not on `--c-surface` because the delta colors are checked against the background: **delta up is `--c-success`** (5.02:1 light, 11.36:1 dark), **delta down is `--c-error`** (4.53:1 light, 7.16:1 dark) and **flat is `--c-muted`** (5.74:1 / 7.85:1). On `--c-surface` the light `--c-error` would be 4.15:1, short of AA. The value is `--c-text` at the h1 size; the label and description are `--c-muted`. Color is never the only signal: the arrow glyph (up, down, flat) and the `delta_label` text for screen readers say the same. Whether "down" is good news (churn, cost) is the app's call: the color only follows the direction.
 
 ## Empty state
-From [components-empty-state](components/components-empty-state): `EmptyState`. A centred block on the page background, with 3rem by 1.5rem of padding at the default size and 1rem between its parts. The icon is `--c-muted` (4.74:1 light, 7.85:1 dark, above the 3:1 non-text minimum), the title is `--c-text`, bold, at the h3 size (h4 small, h2 large) and the description is `--c-muted` at the body size (4.74:1 / 7.85:1 on the background; on `--c-surface` it would be 4.35:1 in light, short of AA, so do not put an empty state on a surface panel without moving the description to `--c-text`). The actions are the app's own buttons. No fills, borders or radius.
+From [components-empty-state](components/components-empty-state): `EmptyState`. A centred block on the page background, with 3rem by 1.5rem of padding at the default size and 1rem between its parts. The icon is `--c-muted` (5.74:1 light, 7.85:1 dark, above the 3:1 non-text minimum), the title is `--c-text`, bold, at the h3 size (h4 small, h2 large) and the description is `--c-muted` at the body size (5.74:1 / 7.85:1 on the background; on `--c-surface` it would be 5.27:1 in light, short of AA, so do not put an empty state on a surface panel without moving the description to `--c-text`). The actions are the app's own buttons. No fills, borders or radius.
 
 ## Timeline
-From [components-timeline](components/components-timeline): `Timeline` and `TimelineItem`. The connector is a 1px `--c-muted` line. A **default** marker is a `--c-surface-active` dot with a 2px `--c-muted` ring; **success, warning, error and info** are solid dots in `--c-success`, `--c-warning`, `--c-error` and `--c-info` (light 5.02, 4.92, 4.53 and 6.70:1 on the background, dark 11.36, 11.86, 7.16 and 7.79:1: all above the 3:1 non-text minimum); the **current** step is a hollow `--c-primary` ring (21:1 / 19.8:1), a different shape from the dots, and the item carries `aria-current="step"`. An **icon marker** keeps a `--c-background` fill and takes the status as its 2px ring, so the `--c-text` icon is 17.93:1 / 18.16:1 in every status (a colored fill would not give one icon color AA in both modes). The status is also the visually hidden `status_label`, so colour is never the only signal. The title is bold `--c-text`, the time is `--c-muted` at the small size (4.74:1 / 7.85:1 on the background) and the description is `--c-text`. Keep a timeline on `--c-background`. Deviation from the first plan: the default dot is outlined with `--c-muted` instead of being a bare `--c-surface-active` dot, which is 1.2:1 on white.
+From [components-timeline](components/components-timeline): `Timeline` and `TimelineItem`. The connector is a 1px `--c-muted` line. A **default** marker is a `--c-surface-active` dot with a 2px `--c-muted` ring; **success, warning, error and info** are solid dots in `--c-success`, `--c-warning`, `--c-error` and `--c-info` (light 5.02, 4.92, 4.53 and 6.70:1 on the background, dark 11.36, 11.86, 7.16 and 7.79:1: all above the 3:1 non-text minimum); the **current** step is a hollow `--c-primary` ring (21:1 / 19.8:1), a different shape from the dots, and the item carries `aria-current="step"`. An **icon marker** keeps a `--c-background` fill and takes the status as its 2px ring, so the `--c-text` icon is 17.93:1 / 18.16:1 in every status (a colored fill would not give one icon color AA in both modes). The status is also the visually hidden `status_label`, so colour is never the only signal. The title is bold `--c-text`, the time is `--c-muted` at the small size (5.74:1 / 7.85:1 on the background) and the description is `--c-text`. Keep a timeline on `--c-background`. Deviation from the first plan: the default dot is outlined with `--c-muted` instead of being a bare `--c-surface-active` dot, which is 1.2:1 on white.
 
 ## Tree
 From [components-tree](components/components-tree): `Tree` and `TreeItem`. Rows are 0.5rem by 0.75rem on the page background, 1.5rem of indent per level. **Hover** is `--c-surface-active` (`--c-text` 14.23:1 light, 13.88:1 dark); the **selected row** is the same 12% tint of `--c-primary` over `--c-background` as a selected table row (`color-mix`, light `#e0e0e0`, dark `#272727`) with `--c-text` (13.58:1 / 13.70:1), so a selected row still reads when hovered. The **chevron** is the component's CSS border chevron on `.c-tree__toggle` (parents only; right when closed, down when open), colored `--c-muted`: 3.76:1 on the hover and 3.59:1 on the selected tint in light, 6.00:1 and 5.92:1 in dark, above the 3:1 non-text minimum. A disabled item is half opacity (exempt from contrast). Square, the theme's 1px `--c-focus` ring inside the row.
 
 ## Code
-From [components-code](components/components-code): `Code`, `Kbd` and `CodeBlock`. The font is the tokens' monospace stack. **Inline code** is `--c-text` on `--c-surface` (16.44:1 in both modes), square, 0.875em. A **kbd** is a `--c-background` key with a 1px `--c-muted` border and a 1px `--c-muted` bottom edge, text `--c-text` (17.93:1 / 18.16:1). The **block** is `--c-surface` with a 1px `--c-muted` border (4.35:1 light, 7.11:1 dark against the surface, above 3:1) and `--c-text` at the small size; highlighted `children` are the app's to keep AA on `--c-surface`. The **copy button** reads like the secondary button: `--c-background` with a 1px `--c-muted` border, `--c-text` (17.93:1 / 18.16:1) and a `--c-surface-active` hover (`--c-text` 14.23:1 / 13.88:1), square, with the theme's 1px `--c-focus` ring inside it and on the focusable `pre`. The component has no uppercase label variables, so the button keeps the small body text instead of the secondary button's label style.
+From [components-code](components/components-code): `Code`, `Kbd` and `CodeBlock`. The font is the tokens' monospace stack. **Inline code** is `--c-text` on `--c-surface` (16.44:1 in both modes), square, 0.875em. A **kbd** is a `--c-background` key with a 1px `--c-muted` border and a 1px `--c-muted` bottom edge, text `--c-text` (17.93:1 / 18.16:1). The **block** is `--c-surface` with a 1px `--c-muted` border (5.27:1 light, 7.11:1 dark against the surface, above 3:1) and `--c-text` at the small size; highlighted `children` are the app's to keep AA on `--c-surface`. The **copy button** reads like the secondary button: `--c-background` with a 1px `--c-muted` border, `--c-text` (17.93:1 / 18.16:1) and a `--c-surface-active` hover (`--c-text` 14.23:1 / 13.88:1), square, with the theme's 1px `--c-focus` ring inside it and on the focusable `pre`. The component has no uppercase label variables, so the button keeps the small body text instead of the secondary button's label style.
 
 ## Field
-From [components-field](components/components-field): `Field`. The label is `--c-text`, bold, at the small size (17.93:1 light, 18.16:1 dark on the background) and not `--c-muted`, which is only 4.35:1 on `--c-surface` in light. The hint is `--c-muted` at the small size (4.74:1 / 7.85:1 on the background) and stays visible, linked with `aria-describedby`. The error is `--c-error` (4.53:1 / 7.16:1), the same color as the Input's error line, and the required asterisk is `--c-error` too; color is never the only signal because the error is text with `role="alert"`. 0.5rem between label, control, hint and error; the horizontal layout uses a 10rem label column and 1.5rem of gap. Keep a field on `--c-background`.
+From [components-field](components/components-field): `Field`. The label is `--c-text`, bold, at the small size (17.93:1 light, 18.16:1 dark on the background) and not `--c-muted`, which is 5.27:1 on `--c-surface` in light. The hint is `--c-muted` at the small size (5.74:1 / 7.85:1 on the background) and stays visible, linked with `aria-describedby`. The error is `--c-error` (4.53:1 / 7.16:1), the same color as the Input's error line, and the required asterisk is `--c-error` too; color is never the only signal because the error is text with `role="alert"`. 0.5rem between label, control, hint and error; the horizontal layout uses a 10rem label column and 1.5rem of gap. Keep a field on `--c-background`.
 
 ## Number input
-From [components-number-input](components/components-number-input): `NumberInput`. The field is the Input's, so it keeps its notched label, `--c-muted` border (4.74:1 / 7.85:1) and thickened `--c-focus` border. The stepper buttons read like the secondary button inside the box: square, `--c-muted` glyphs (4.74:1 / 7.85:1, above the 3:1 non-text minimum) turning `--c-text` on a `--c-surface-active` hover (14.23:1 / 13.88:1), half opacity at a bound (exempt from contrast). They are out of the tab order (the arrow keys do the same), so the focus ring stays on the field.
+From [components-number-input](components/components-number-input): `NumberInput`. The field is the Input's, so it keeps its notched label, `--c-muted` border (5.74:1 / 7.85:1) and thickened `--c-focus` border. The stepper buttons read like the secondary button inside the box: square, `--c-muted` glyphs (5.74:1 / 7.85:1, above the 3:1 non-text minimum) turning `--c-text` on a `--c-surface-active` hover (14.23:1 / 13.88:1), half opacity at a bound (exempt from contrast). They are out of the tab order (the arrow keys do the same), so the focus ring stays on the field.
 
 ## OTP input
-From [components-otp-input](components/components-otp-input): `OtpInput`. Each box is built like the Input: `--c-background` with a 1px `--c-muted` border (4.74:1 / 7.85:1), `--c-primary` on hover, and the keyboard focus thickens the border to `--c-focus` plus a 1px `--c-focus` shadow (2px in total, 21:1 / 19.8:1), the same rule as every outlined control. An invalid box is `--c-error` (4.53:1 / 7.16:1) with the message under the boxes in `--c-error`; a disabled one is `--c-surface` with `--c-disabled-text` (exempt). The digit is `--c-text` at the h3 size (17.93:1 / 18.16:1). Square, 3rem by 3.5rem (above the 44px touch target), 0.5rem between boxes; the group label is the field label style in `--c-muted`.
+From [components-otp-input](components/components-otp-input): `OtpInput`. Each box is built like the Input: `--c-background` with a 1px `--c-muted` border (5.74:1 / 7.85:1), `--c-primary` on hover, and the keyboard focus thickens the border to `--c-focus` plus a 1px `--c-focus` shadow (2px in total, 21:1 / 19.8:1), the same rule as every outlined control. An invalid box is `--c-error` (4.53:1 / 7.16:1) with the message under the boxes in `--c-error`; a disabled one is `--c-surface` with `--c-disabled-text` (exempt). The digit is `--c-text` at the h3 size (17.93:1 / 18.16:1). Square, 3rem by 3.5rem (above the 44px touch target), 0.5rem between boxes; the group label is the field label style in `--c-muted`.
 
 ## Phone
-From [components-phone](components/components-phone): `Phone`. The field is the Input's. The country select is a native `<select>` in the input's start slot, `--c-text` on a transparent background so the box color shows in both modes (17.93:1 / 18.16:1 on the background), with a 1px `--c-muted` divider before the number (4.74:1 / 7.85:1) and the theme's 1px `--c-focus` outline when it is focused by keyboard; disabled is `--c-disabled-text` (exempt). The open list is drawn by the platform, so it follows `color-scheme` in dark.
+From [components-phone](components/components-phone): `Phone`. The field is the Input's. The country select is a native `<select>` in the input's start slot, `--c-text` on a transparent background so the box color shows in both modes (17.93:1 / 18.16:1 on the background), with a 1px `--c-muted` divider before the number (5.74:1 / 7.85:1) and the theme's 1px `--c-focus` outline when it is focused by keyboard; disabled is `--c-disabled-text` (exempt). The open list is drawn by the platform, so it follows `color-scheme` in dark.
 
 ## Tag input
 From [components-tag-input](components/components-tag-input): `TagInput`. The box is the Input's (square, `--c-muted` border, thickened `--c-focus` border on focus) and the chips are the Tag's, so the tag tints, borders and `--c-text` labels (14.8:1 or more on every tint) are the ones documented in the Tag section; the block only sets 0.375rem between chips and the text field and a 6rem minimum for the text field before it wraps to its own row. The placeholder is `--c-muted` as in the Input. Errors (`duplicate`, `max`, `invalid`) use the Input's `--c-error` line.
 
 ## Time picker
-From [components-time-picker](components/components-time-picker): `TimePicker`. The field is the Input's and the times are the Listbox's inside the Popover, so the `--c-muted` border (4.74:1 / 7.85:1), the thickened `--c-focus` border, the `--c-text` options (17.93:1 / 18.16:1), the `--c-surface` active option and the selected marker are the ones documented for the Select and the Combobox (reused, no new figure). The clock icon is the Select arrow's: 16px, `--c-muted` turning `--c-primary` on hover and when open, and `--c-disabled-text` when disabled (exempt). Open takes the `--c-focus` border; the placeholder is `--c-muted`. Errors (`invalid_time`, `out_of_range`) use the Input's `--c-error` line (4.53:1 / 7.16:1).
+From [components-time-picker](components/components-time-picker): `TimePicker`. The field is the Input's and the times are the Listbox's inside the Popover, so the `--c-muted` border (5.74:1 / 7.85:1), the thickened `--c-focus` border, the `--c-text` options (17.93:1 / 18.16:1), the `--c-surface` active option and the selected marker are the ones documented for the Select and the Combobox (reused, no new figure). The clock icon is the Select arrow's: 16px, `--c-muted` turning `--c-primary` on hover and when open, and `--c-disabled-text` when disabled (exempt). Open takes the `--c-focus` border; the placeholder is `--c-muted`. Errors (`invalid_time`, `out_of_range`) use the Input's `--c-error` line (4.53:1 / 7.16:1).
 
 ## Date range
 From [components-date-range](components/components-date-range): `DateRange`. The trigger is the Date picker's and the days are the Calendar's (44px squares, `--c-text`, `--c-surface` hover), so those figures are reused. The two ends use the Calendar's selected look, `--c-on-primary` on `--c-primary` (21:1 / 19.8:1). The days between them are a `--c-surface-active` band with `--c-text` (14.23:1 / 13.88:1, the same pair as the Menu and Pagination hovers), square so the band is unbroken; it is painted on the cell and on the day, and it relies on the calendar grid keeping `border-spacing: 0` (a test asserts it). The band against the background is only 1.26:1 / 1.31:1, so it is not the only cue: the ends are solid black (or white in dark), and the days carry `aria-selected`. Two months sit side by side with 1rem between them, with 0.5rem of panel padding. Errors (`end_before_start`, `out_of_range`) use the Input's `--c-error` line.
 
 ## Rating
-From [components-rating](components/components-rating): `Rating`. The filled part is `--c-primary` (21:1 / 19.8:1 on the background) and the empty part is `--c-muted` (4.74:1 / 7.85:1), both above the 3:1 minimum for graphics. A filled star is a solid shape and an empty one an outline, so the two never rely on colour alone; their lightness differs by 4.43:1 in light and 2.52:1 in dark (below 3:1 there, which the solid-versus-outline shape makes up for). The preview while hovering is `--c-primary-hover` (15.13:1 in light, 15.72:1 in dark on the background). Stars are 1.75rem apart by 0.25rem, and the keyboard ring is the theme's 1px `--c-focus` outline (21:1 / 19.8:1). The group label is the field label style in `--c-muted`; a disabled rating is at half opacity (exempt).
+From [components-rating](components/components-rating): `Rating`. The filled part is `--c-primary` (21:1 / 19.8:1 on the background) and the empty part is `--c-muted` (5.74:1 / 7.85:1), both above the 3:1 minimum for graphics. A filled star is a solid shape and an empty one an outline, so the two never rely on colour alone; their lightness differs by 4.43:1 in light and 2.52:1 in dark (below 3:1 there, which the solid-versus-outline shape makes up for). The preview while hovering is `--c-primary-hover` (15.13:1 in light, 15.72:1 in dark on the background). Stars are 1.75rem apart by 0.25rem, and the keyboard ring is the theme's 1px `--c-focus` outline (21:1 / 19.8:1). The group label is the field label style in `--c-muted`; a disabled rating is at half opacity (exempt).
 
 ## Color picker
-From [components-color-picker](components/components-color-picker): `ColorPicker`. The field is the Input's with a 1.25rem chip bordered in `--c-muted` (4.74:1 / 7.85:1) next to the hex text in `--c-text`; the panel is the Popover's. The thumbs of the area and of the hue and alpha tracks are a 2px `--c-background` ring over a 1px `--c-text` ring, so one of the two contrasts with any colour under it in both modes (the ring pair is 17.93:1 / 18.16:1 between itself); the keyboard focus draws the theme's 1px `--c-focus` outline offset by 2px around the area or the track (21:1 / 19.8:1). The hue and brightness gradients are the colour data and keep their literal colours; the transparent checkerboard is `--c-surface-active` over `--c-background`. The hex input is built like the Input box: `--c-background`, a 1px `--c-muted` border, `--c-error` when invalid (4.53:1 / 7.16:1), the monospace stack at the small size. Swatches are 1.75rem squares with a `--c-muted` border and a `--c-primary` ring when selected; areas, tracks and chips are square.
+From [components-color-picker](components/components-color-picker): `ColorPicker`. The field is the Input's with a 1.25rem chip bordered in `--c-muted` (5.74:1 / 7.85:1) next to the hex text in `--c-text`; the panel is the Popover's. The thumbs of the area and of the hue and alpha tracks are a 2px `--c-background` ring over a 1px `--c-text` ring, so one of the two contrasts with any colour under it in both modes (the ring pair is 17.93:1 / 18.16:1 between itself); the keyboard focus draws the theme's 1px `--c-focus` outline offset by 2px around the area or the track (21:1 / 19.8:1). The hue and brightness gradients are the colour data and keep their literal colours; the transparent checkerboard is `--c-surface-active` over `--c-background`. The hex input is built like the Input box: `--c-background`, a 1px `--c-muted` border, `--c-error` when invalid (4.53:1 / 7.16:1), the monospace stack at the small size. Swatches are 1.75rem squares with a `--c-muted` border and a `--c-primary` ring when selected; areas, tracks and chips are square.
 
 ## Async autocomplete
-From [components-async-autocomplete](components/components-async-autocomplete): `AsyncAutocomplete`. The field, the panel and the options are the Combobox's (reused figures, no new contrast). While a request is pending the field shows a 16px spinner at the arrow's place: a 2px `--c-primary` arc (21:1 / 19.8:1) over a `--c-surface-active` track, slowed down under `prefers-reduced-motion`. The states are written in the panel: `loading` and `empty` in `--c-muted` (4.74:1 / 7.85:1, the Listbox's empty message color) and `error` in `--c-error` (4.53:1 / 7.16:1 on the background, which is the panel's); the state is also exposed as `aria-busy` and `data-state`, so colour is never the only signal. Open takes the `--c-focus` border.
+From [components-async-autocomplete](components/components-async-autocomplete): `AsyncAutocomplete`. The field, the panel and the options are the Combobox's (reused figures, no new contrast). While a request is pending the field shows a 16px spinner at the arrow's place: a 2px `--c-primary` arc (21:1 / 19.8:1) over a `--c-surface-active` track, slowed down under `prefers-reduced-motion`. The states are written in the panel: `loading` and `empty` in `--c-muted` (5.74:1 / 7.85:1, the Listbox's empty message color) and `error` in `--c-error` (4.53:1 / 7.16:1 on the background, which is the panel's); the state is also exposed as `aria-busy` and `data-state`, so colour is never the only signal. Open takes the `--c-focus` border.
+
+## Section and container
+From [components-section](components/components-section): `Container` and `Section`. Layout only: gutters of 1rem growing to 2rem at 40rem, container widths of 40, 48, 64 and 80rem, and vertical rhythms of 2, 4 and 6rem. The section title is `--c-text` in the h2 style (17.93:1 / 18.16:1 on the background) and the lead paragraph is `--c-muted` at the lead size (5.74:1 / 7.85:1 on the background, 5.27:1 / 7.11:1 on `--c-surface`), so both pass AA on either ground. A section with a title is a landmark named by it.
+
+## Faq
+From [components-faq](components/components-faq): `Faq`. It is the Accordion (the box, the `--c-muted` rules, the `--c-surface` header hover and the 1px `--c-focus` ring documented in the Accordion section), so no new figure for the questions. The answers are `--c-text` (17.93:1 / 18.16:1) at a 1.6 line height and the list is capped at 48rem. The block must stay after the accordion block, because the FAQ stylesheet forwards the accordion's.
+
+## Carousel
+From [components-carousel](components/components-carousel): `Carousel`. The arrows and the pause / play button are the secondary button's: square, 2.75rem, a 1px `--c-muted` border (5.74:1 / 7.85:1 on the background), a `--c-surface-active` hover and a `--c-text` glyph (17.93:1 / 18.16:1; 14.23:1 / 13.88:1 on the hover). The glyphs (corner, bars, triangle) are drawn with borders in `currentColor`, so they follow the mode and need no new colour. Disabled arrows are at half opacity (exempt). The dots are 0.625rem circles in `--c-muted` (5.74:1 / 7.85:1 on the background, 5.27:1 / 7.11:1 on `--c-surface`, above the 3:1 minimum for graphics) and the current one is `--c-primary` (21:1 / 19.8:1) and 1.5rem long. Colour is not the only cue: the current dot is a bar against circles, and it also carries `aria-current`; the lightness gap between the two colours is 3.66:1 in light and 2.52:1 in dark (below 3:1 there, which the shape makes up for). The keyboard ring is the theme's 1px `--c-focus` outline offset by 2px (21:1 / 19.8:1). Transitions run at 0.2s and stop under `prefers-reduced-motion`.
 
 ## Keyboard focus (all controls)
 One rule keeps the controls coherent: **an outlined control thickens its own border from 1px to 2px, black** (text fields,

package/README.md

@@ -78,7 +78,7 @@ change.
 | `$black` | `#000` | primary, hover and focus |
 | `$white` | `#fff` | surfaces |
 | `$text` | `#171717` | body text |
-| `$muted` | `#737373` | labels, field borders, placeholders |
+| `$muted` | `#666666` | labels, field borders, placeholders |
 | `$surface` | `#f5f5f5` | hover surface, disabled background |
 | `$surface-active` | `#e5e5e5` | pressed surface, dividers |
 | `$primary-hover` | `#262626` | primary action on hover |
@@ -142,7 +142,7 @@ it: check the names against the theme's `scss/_tokens.scss` before you switch.
 
 ## What it configures
 `components-input`, `-button`, `-checkbox`, `-switch`, `-radio-group`, `-slider`, `-popover`, `-listbox`, `-select`,
-`-combobox`, `-upload`, `-calendar`, `-date-picker`, `-search`, `-typography`, `-card`, `-alert`, `-spinner`, `-modal`, `-toast`, `-divider`, `-badge`, `-tag`, `-link`, `-avatar`, `-skeleton`, `-progress`, `-tooltip`, `-prose`, `-tabs`, `-accordion`, `-breadcrumb`, `-pagination`, `-stepper`, `-sidebar`, `-navbar`, `-drawer`, `-menu`, `-table`, `-list`, `-description-list`, `-stat`, `-empty-state`, `-timeline`, `-tree`, `-code`, `-field`, `-number-input`, `-otp-input`, `-phone`, `-tag-input`, `-time-picker`, `-date-range`, `-rating`, `-color-picker` and `-async-autocomplete`. `components-email`, `-password`, `-url` and `-textarea`
+`-combobox`, `-upload`, `-calendar`, `-date-picker`, `-search`, `-typography`, `-card`, `-alert`, `-spinner`, `-modal`, `-toast`, `-divider`, `-badge`, `-tag`, `-link`, `-avatar`, `-skeleton`, `-progress`, `-tooltip`, `-prose`, `-tabs`, `-accordion`, `-breadcrumb`, `-pagination`, `-stepper`, `-sidebar`, `-navbar`, `-drawer`, `-menu`, `-table`, `-list`, `-description-list`, `-stat`, `-empty-state`, `-timeline`, `-tree`, `-code`, `-field`, `-number-input`, `-otp-input`, `-phone`, `-tag-input`, `-time-picker`, `-date-range`, `-rating`, `-color-picker`, `-async-autocomplete`, `-section`, `-faq` and `-carousel`. `components-email`, `-password`, `-url` and `-textarea`
 are styled through the input.
 
 ## Change a value

package/dist/index.css

@@ -2,7 +2,7 @@
 :root {
   --c-background: #fff;
   --c-text: #171717;
-  --c-muted: #737373;
+  --c-muted: #666666;
   --c-surface: #f5f5f5;
   --c-surface-active: #e5e5e5;
   --c-primary: #000;
@@ -22,7 +22,7 @@
 :root[data-mode=light] {
   --c-background: #fff;
   --c-text: #171717;
-  --c-muted: #737373;
+  --c-muted: #666666;
   --c-surface: #f5f5f5;
   --c-surface-active: #e5e5e5;
   --c-primary: #000;
@@ -4407,6 +4407,10 @@ ol.c-list {
   outline-offset: -2px;
 }
 
+.c-code-block--has-copy .c-code-block__pre {
+  padding-top: 2.5rem;
+}
+
 .c-code-block__code {
   font-size: inherit;
 }
@@ -5042,3 +5046,222 @@ ol.c-list {
     animation-duration: 2s;
   }
 }
+.c-container {
+  box-sizing: border-box;
+  width: 100%;
+  margin-inline: auto;
+  padding-inline: 1rem;
+}
+@media (min-width: 40rem) {
+  .c-container {
+    padding-inline: 2rem;
+  }
+}
+
+.c-container--sm {
+  max-width: 40rem;
+}
+
+.c-container--md {
+  max-width: 48rem;
+}
+
+.c-container--lg {
+  max-width: 64rem;
+}
+
+.c-container--xl {
+  max-width: 80rem;
+}
+
+.c-container--full {
+  max-width: none;
+}
+
+.c-section {
+  box-sizing: border-box;
+}
+
+.c-section--sm {
+  padding-block: 2rem;
+}
+
+.c-section--md {
+  padding-block: 4rem;
+}
+
+.c-section--lg {
+  padding-block: 6rem;
+}
+
+.c-section__header {
+  display: flex;
+  flex-direction: column;
+  gap: 0.75rem;
+  max-width: 40rem;
+  margin-bottom: 2rem;
+}
+
+.c-section__title {
+  margin: 0;
+  font-size: 1.75rem;
+  font-weight: 900;
+  line-height: 1.2;
+  color: var(--c-text);
+}
+
+.c-section__description {
+  margin: 0;
+  font-size: 1.25rem;
+  line-height: 1.6;
+  color: var(--c-muted);
+}
+
+.c-faq {
+  max-width: 48rem;
+}
+
+.c-faq .c-accordion__content {
+  line-height: 1.6;
+  color: var(--c-text);
+}
+
+.c-carousel {
+  box-sizing: border-box;
+}
+
+.c-carousel__viewport {
+  overflow: hidden;
+}
+
+.c-carousel__track {
+  position: relative;
+  display: flex;
+  gap: 1rem;
+  overflow-x: auto;
+  overscroll-behavior-x: contain;
+  scroll-snap-type: x mandatory;
+  scrollbar-width: none;
+  touch-action: pan-x pan-y pinch-zoom;
+}
+.c-carousel__track::-webkit-scrollbar {
+  display: none;
+}
+
+.c-carousel__slide {
+  box-sizing: border-box;
+  flex: 0 0 calc((100% - 1rem * (var(--c-carousel-per-view, 1) - 1)) / var(--c-carousel-per-view, 1));
+  min-width: 0;
+  scroll-snap-align: start;
+}
+
+.c-carousel__controls {
+  display: flex;
+  gap: 1rem;
+  align-items: center;
+  justify-content: center;
+  margin-top: 1rem;
+}
+
+.c-carousel__arrow,
+.c-carousel__toggle {
+  position: relative;
+  box-sizing: border-box;
+  flex: none;
+  width: 2.75rem;
+  height: 2.75rem;
+  padding: 0;
+  color: var(--c-text);
+  cursor: pointer;
+  background: var(--c-background);
+  border: 1px solid var(--c-muted);
+  border-radius: 0;
+  transition: background-color 0.2s ease-out;
+}
+.c-carousel__arrow:hover:not(:disabled),
+.c-carousel__toggle:hover:not(:disabled) {
+  background: var(--c-surface-active);
+}
+.c-carousel__arrow:focus-visible,
+.c-carousel__toggle:focus-visible {
+  outline: 1px solid var(--c-focus);
+  outline-offset: 2px;
+}
+.c-carousel__arrow:disabled,
+.c-carousel__toggle:disabled {
+  cursor: not-allowed;
+  opacity: 0.5;
+}
+.c-carousel__arrow::before,
+.c-carousel__toggle::before {
+  position: absolute;
+  top: 50%;
+  left: 50%;
+  box-sizing: border-box;
+  content: "";
+}
+
+.c-carousel__arrow::before {
+  width: 0.5rem;
+  height: 0.5rem;
+  border-top: 2px solid currentColor;
+  border-right: 2px solid currentColor;
+}
+
+.c-carousel__arrow--next::before {
+  transform: translate(-65%, -50%) rotate(45deg);
+}
+
+.c-carousel__arrow--prev::before {
+  transform: translate(-35%, -50%) rotate(-135deg);
+}
+
+.c-carousel__toggle--playing::before {
+  width: 0.5rem;
+  height: 0.75rem;
+  border-right: 3px solid currentColor;
+  border-left: 3px solid currentColor;
+  transform: translate(-50%, -50%);
+}
+
+.c-carousel__toggle--paused::before {
+  border-top: 0.375rem solid transparent;
+  border-bottom: 0.375rem solid transparent;
+  border-left: 0.625rem solid currentColor;
+  transform: translate(-35%, -50%);
+}
+
+.c-carousel__dots {
+  display: flex;
+  gap: 0.5rem;
+  align-items: center;
+}
+
+.c-carousel__dot {
+  box-sizing: border-box;
+  width: 0.625rem;
+  height: 0.625rem;
+  padding: 0;
+  cursor: pointer;
+  background: var(--c-muted);
+  border: 0;
+  border-radius: 0;
+  transition: width 0.2s ease-out, background-color 0.2s ease-out;
+}
+.c-carousel__dot:focus-visible {
+  outline: 1px solid var(--c-focus);
+  outline-offset: 2px;
+}
+
+.c-carousel__dot--current {
+  width: 1.5rem;
+  background: var(--c-primary);
+}
+
+@media (prefers-reduced-motion: reduce) {
+  .c-carousel__arrow,
+  .c-carousel__toggle,
+  .c-carousel__dot {
+    transition: none;
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carissa-io/theme-default",
-  "version": "0.3.9",
+  "version": "0.3.11",
   "description": "Carissa UI: the default theme (Swiss minimalism) as SCSS variable overrides of the Carissa components, with a compiled CSS build",
   "type": "module",
   "style": "dist/index.css",
@@ -93,7 +93,10 @@
     "@carissa-io/components-date-range": "^0.1.0",
     "@carissa-io/components-rating": "^0.1.0",
     "@carissa-io/components-color-picker": "^0.1.0",
-    "@carissa-io/components-async-autocomplete": "^0.1.0"
+    "@carissa-io/components-async-autocomplete": "^0.1.0",
+    "@carissa-io/components-section": "^0.1.0",
+    "@carissa-io/components-faq": "^0.1.0",
+    "@carissa-io/components-carousel": "^0.1.0"
   },
   "peerDependenciesMeta": {
     "@carissa-io/components-input": {
@@ -275,6 +278,15 @@
     },
     "@carissa-io/components-async-autocomplete": {
       "optional": true
+    },
+    "@carissa-io/components-section": {
+      "optional": true
+    },
+    "@carissa-io/components-faq": {
+      "optional": true
+    },
+    "@carissa-io/components-carousel": {
+      "optional": true
     }
   },
   "devDependencies": {
@@ -287,6 +299,7 @@
     "@carissa-io/components-button": "^0.1.1",
     "@carissa-io/components-calendar": "^0.1.1",
     "@carissa-io/components-card": "^0.1.0",
+    "@carissa-io/components-carousel": "^0.1.0",
     "@carissa-io/components-checkbox": "^0.1.1",
     "@carissa-io/components-code": "^0.1.0",
     "@carissa-io/components-color-picker": "^0.1.0",
@@ -297,6 +310,7 @@
     "@carissa-io/components-divider": "^0.1.0",
     "@carissa-io/components-drawer": "^0.1.0",
     "@carissa-io/components-empty-state": "^0.1.0",
+    "@carissa-io/components-faq": "^0.1.0",
     "@carissa-io/components-field": "^0.1.0",
     "@carissa-io/components-input": "^0.2.1",
     "@carissa-io/components-link": "^0.1.0",
@@ -315,6 +329,7 @@
     "@carissa-io/components-radio-group": "^0.1.1",
     "@carissa-io/components-rating": "^0.1.0",
     "@carissa-io/components-search": "^0.1.1",
+    "@carissa-io/components-section": "^0.1.0",
     "@carissa-io/components-select": "^0.1.1",
     "@carissa-io/components-sidebar": "^0.1.0",
     "@carissa-io/components-skeleton": "^0.1.0",

package/scss/_tokens.scss

@@ -9,7 +9,7 @@
 $black: #000; // primary, hover and focus
 $white: #fff;
 $text: #171717;
-$muted: #737373; // labels, field borders, placeholders (4.7:1 on white)
+$muted: #666666; // labels, field borders, placeholders (5.7:1 on white)
 $surface: #f5f5f5; // hover surface, disabled background
 $surface-active: #e5e5e5;
 $primary-hover: #262626;

package/scss/index.scss

@@ -78,7 +78,7 @@
     $c-button-primary-background-disabled: $var-surface,
     $c-button-primary-border-color-disabled: $var-surface,
 
-    // Secondary: 1px #737373 border, black on hover
+    // Secondary: 1px #666666 border, black on hover
     $c-button-secondary-color: $var-text,
     $c-button-secondary-background: $var-background,
     $c-button-secondary-border-color: $var-muted,
@@ -125,7 +125,7 @@
     $c-checkbox-gap: 0.75rem,
     $c-checkbox-transition: (color $transition-duration ease, background-color $transition-duration ease, border-color $transition-duration ease, opacity $transition-duration ease),
 
-    // Box: 20px square, 1px #737373 border, black on hover
+    // Box: 20px square, 1px #666666 border, black on hover
     $c-checkbox-box-size: 1.25rem,
     $c-checkbox-border-color: $var-muted,
     $c-checkbox-border-color-hover: $var-primary,
@@ -155,7 +155,7 @@
 );
 
 @use '@carissa-io/components-switch/scss' as switch with (
-    // Track: square, 40 x 20px, white with a 1px #737373 border; black when on
+    // Track: square, 40 x 20px, white with a 1px #666666 border; black when on
     $c-switch-track-width: 2.5rem,
     $c-switch-track-height: 1.25rem,
     $c-switch-track-radius: $radius,
@@ -168,7 +168,7 @@
     $c-switch-track-background-disabled: $var-surface,
     $c-switch-track-border-color-disabled: $var-disabled-border,
 
-    // Thumb: square, #737373 when off, white when on
+    // Thumb: square, #666666 when off, white when on
     $c-switch-thumb-size: 0.875rem,
     $c-switch-thumb-offset: 0.125rem,
     $c-switch-thumb-radius: $radius,
@@ -203,7 +203,7 @@
     $c-radio-group-dot-gap: 0.75rem,
     $c-radio-group-transition: (color $transition-duration ease, background-color $transition-duration ease, border-color $transition-duration ease, background-size $transition-duration ease),
 
-    // Dot: 20px circle (a radio is round, so the radius stays 50%), 1px #737373 border, black on hover
+    // Dot: 20px circle (a radio is round, so the radius stays 50%), 1px #666666 border, black on hover
     $c-radio-group-dot-size: 1.25rem,
     $c-radio-group-border-color: $var-muted,
     $c-radio-group-border-color-hover: $var-primary,
@@ -246,7 +246,7 @@
     $c-slider-min-height: $min-height,
     $c-slider-transition: (background-color $transition-duration ease, border-color $transition-duration ease),
 
-    // Track: 2px #737373 line with a black fill
+    // Track: 2px #666666 line with a black fill
     $c-slider-track-height: 2px,
     $c-slider-track-color: $var-muted,
     $c-slider-track-fill-color: $var-primary,
@@ -274,7 +274,7 @@
 );
 
 @use '@carissa-io/components-popover/scss' as popover with (
-    // Panel: white, 1px #737373 border, square, flat (no shadow), 4px below the anchor
+    // Panel: white, 1px #666666 border, square, flat (no shadow), 4px below the anchor
     $c-popover-background: $var-background,
     $c-popover-color: $var-text,
     $c-popover-border-width: 1px,
@@ -356,7 +356,7 @@
 // Upload: the Input field with a dashed box as the dropzone. Its index forwards the input styles, already loaded and
 // configured above, so it must come after them.
 @use '@carissa-io/components-upload/scss' as upload with (
-    // Box: dashed 1px #737373 (the input border), black on hover and while files are dragged over it
+    // Box: dashed 1px #666666 (the input border), black on hover and while files are dragged over it
     $c-upload-border-style: dashed,
     $c-upload-transition: (border-color $transition-duration ease, background-color $transition-duration ease, box-shadow $transition-duration ease, color $transition-duration ease),
     $c-upload-dragging-border-color: $var-primary,
@@ -788,7 +788,7 @@
 );
 
 // Link: --c-primary (black in light, white in dark) with an underline, because a black link on black text is told apart
-// by the underline alone; --c-primary-hover on hover. Subtle is --c-muted (4.7:1 on the background) and turns --c-text.
+// by the underline alone; --c-primary-hover on hover. Subtle is --c-muted (5.7:1 on the background) and turns --c-text.
 // Disabled is --c-disabled-text at full opacity. The focus ring is the theme's 1px ring, offset 2px.
 @use '@carissa-io/components-link/scss' as link with (
     $c-link-color: $var-primary,
@@ -939,7 +939,7 @@
 );
 
 // Tabs: a --c-muted underline under the list and a 2px --c-primary indicator under the selected tab. Tabs read --c-muted
-// (4.7:1 on the background, 7.9:1 in dark), turn --c-text on a --c-surface hover and the selected one is --c-text and bold.
+// (5.7:1 on the background, 7.9:1 in dark), turn --c-text on a --c-surface hover and the selected one is --c-text and bold.
 // Square, bold, the theme's 1px focus ring inside the tab. No other block forwards it.
 @use '@carissa-io/components-tabs/scss' as tabs with (
     $c-tabs-list-border-width: 1px,
@@ -985,7 +985,7 @@
     $c-accordion-transition-duration: $transition-duration
 );
 
-// Breadcrumb: links and separators in --c-muted (4.7:1 on the background), the current page in --c-text and bold. Links turn
+// Breadcrumb: links and separators in --c-muted (5.7:1 on the background), the current page in --c-text and bold. Links turn
 // --c-text and underline on hover. The theme's 1px focus ring, offset 2px.
 @use '@carissa-io/components-breadcrumb/scss' as breadcrumb with (
     $c-breadcrumb-font-size: $font-size-small,
@@ -1062,7 +1062,7 @@
 
 // Sidebar: a --c-surface column with a 1px --c-muted edge. Items are --c-text (16.4:1 on the surface) with a --c-surface-active
 // hover (14.2:1); the current page is filled --c-primary with --c-on-primary (21:1), a shape and not only a hue. Section titles
-// are the small uppercase label style in --c-text, because --c-muted on --c-surface is only 4.35:1 in light. Square, the
+// are the small uppercase label style in --c-text, because --c-muted on --c-surface is 5.27:1 in light (it passes, the label stays text for emphasis). Square, the
 // theme's 1px focus ring inside the item. No other block forwards it.
 @use '@carissa-io/components-sidebar/scss' as sidebar with (
     $c-sidebar-width: 16rem,
@@ -1098,7 +1098,7 @@
     $c-sidebar-transition-duration: $transition-duration
 );
 
-// Navbar: a --c-background bar with a 1px --c-muted bottom edge. Items read like the tabs: bold --c-muted (4.7:1 on the
+// Navbar: a --c-background bar with a 1px --c-muted bottom edge. Items read like the tabs: bold --c-muted (5.7:1 on the
 // background), --c-text on a --c-surface hover, and --c-text for the current page. The breakpoint is the Sass default (48rem).
 // Square, 44px toggle, the theme's 1px focus ring inside the item. No other block forwards it.
 @use '@carissa-io/components-navbar/scss' as navbar with (
@@ -1155,7 +1155,7 @@
 );
 
 // Menu: the panel is the Popover's (--c-background, 1px --c-muted border, flat). Items are --c-text with a --c-surface-active
-// hover and keyboard focus (14.2:1) and the theme's 1px focus ring; labels are small --c-muted text (4.7:1 on the panel) and
+// hover and keyboard focus (14.2:1) and the theme's 1px focus ring; labels are small --c-muted text (5.7:1 on the panel) and
 // the separator a 1px --c-muted line. Square. Its index forwards the popover styles, already loaded and configured above:
 // this block goes after the Popover one.
 @use '@carissa-io/components-menu/scss' as menu with (
@@ -1204,7 +1204,7 @@
 );
 
 // List: rows on the page background, divided by 1px --c-muted lines. The secondary text is --c-text at the small size, not
-// --c-muted, because the row sits on --c-surface-active when hovered and --c-muted is only 3.8:1 there (4.35:1 on --c-surface).
+// --c-muted, because the row sits on --c-surface-active when hovered and --c-muted is 4.56:1 there (5.27:1 on --c-surface), so the text color keeps the hover clearly readable.
 // Hover is --c-surface-active; the current item is the same 12% --c-primary tint as a selected table row. Square, the theme's
 // 1px focus ring inside the row.
 @use '@carissa-io/components-list/scss' as list with (
@@ -1229,7 +1229,7 @@
     $c-list-transition-duration: $transition-duration
 );
 
-// Description list: the term is a small bold --c-muted label (4.7:1 on the background, so use it on --c-background, where
+// Description list: the term is a small bold --c-muted label (5.7:1 on the background, so use it on --c-background, where
 // --c-muted is not enough on --c-surface) and the detail is --c-text. No fills or borders.
 @use '@carissa-io/components-description-list/scss' as description-list with (
     $c-description-list-gap-x: 2rem,
@@ -1245,7 +1245,7 @@
 
 // Stat: a card-like block on the page background with a 1px --c-muted border (the Card's outlined look), not on --c-surface:
 // the delta colors are checked against --c-background, where --c-success is 5:1 and --c-error 4.5:1 in light (4.15:1 for
-// --c-error on --c-surface). The label and the description are --c-muted (4.7:1), the value is --c-text. The delta is
+// --c-error on --c-surface). The label and the description are --c-muted (5.7:1), the value is --c-text. The delta is
 // success when up, error when down and muted when flat; the arrow and the screen-reader text say the same, so color is never
 // the only signal. In dark the status colors are lighter (7.1:1 and above on the background).
 @use '@carissa-io/components-stat/scss' as stat with (
@@ -1271,9 +1271,9 @@
     $c-stat-delta-flat-color: $var-muted
 );
 
-// Empty state: a centred block on the page background. The icon is --c-muted (4.7:1 light, 7.9:1 dark, above the 3:1 non-text
-// minimum), the title --c-text at the h3 size and bold, the description --c-muted (4.7:1 on the background, so keep it off
-// --c-surface, where light is 4.35:1). The actions are the app's buttons. Square, nothing else to set.
+// Empty state: a centred block on the page background. The icon is --c-muted (5.7:1 light, 7.9:1 dark, above the 3:1 non-text
+// minimum), the title --c-text at the h3 size and bold, the description --c-muted (5.7:1 on the background, so keep it off
+// --c-surface, where light is 5.27:1). The actions are the app's buttons. Square, nothing else to set.
 @use '@carissa-io/components-empty-state/scss' as empty-state with (
     $c-empty-state-padding: 3rem 1.5rem,
     $c-empty-state-padding-sm: 1.5rem 1rem,
@@ -1299,7 +1299,7 @@
 // success, warning, error and info are solid dots in their status color (4.5:1 or more against the background in light, 7:1 in
 // dark, above the 3:1 non-text minimum); the current step is a hollow --c-primary ring. An icon marker keeps a --c-background
 // fill and takes the status as its ring, so the --c-text icon is 17.9:1 / 18.2:1 in every status. The status text is the
-// hidden status_label, the time is --c-muted (4.7:1 / 7.9:1 on the background) and the title --c-text, bold. Color is never the
+// hidden status_label, the time is --c-muted (5.7:1 / 7.9:1 on the background) and the title --c-text, bold. Color is never the
 // only signal.
 @use '@carissa-io/components-timeline/scss' as timeline with (
     $c-timeline-gap: 1.5rem,
@@ -1391,8 +1391,8 @@
 );
 
 // Field: the label, hint and error around a control with no label of its own (radio group, slider, custom control). The label is
-// --c-text (17.93:1 / 18.16:1 on the background) in the label size and weight, not --c-muted, which is 4.35:1 on --c-surface in
-// light. The hint is --c-muted (4.74:1 / 7.85:1 on the background) and the error is --c-error (4.53:1 / 7.16:1), the same
+// --c-text (17.93:1 / 18.16:1 on the background) in the label size and weight, not --c-muted, which is 5.27:1 on --c-surface in
+// light. The hint is --c-muted (5.74:1 / 7.85:1 on the background) and the error is --c-error (4.53:1 / 7.16:1), the same
 // color as the Input's error line, with the component's required asterisk. Keep a field on --c-background.
 @use '@carissa-io/components-field/scss' as field with (
     $c-field-font-family: $font-family,
@@ -1412,7 +1412,7 @@
 );
 
 // Number input: the field is the Input's (configured at the top; this module forwards it). The steppers read like the
-// secondary button inside the box: --c-muted glyphs (4.74:1 / 7.85:1, above the 3:1 non-text minimum) turning --c-text on a
+// secondary button inside the box: --c-muted glyphs (5.74:1 / 7.85:1, above the 3:1 non-text minimum) turning --c-text on a
 // --c-surface-active hover (--c-text 14.23:1 / 13.88:1), square, half opacity at a bound.
 @use '@carissa-io/components-number-input/scss' as number-input with (
     $c-number-input-stepper-size: 1.5rem,
@@ -1427,7 +1427,7 @@
     $c-number-input-text-align: start
 );
 
-// OTP input: one box per character, built like the Input box: --c-background with a 1px --c-muted border (4.74:1 / 7.85:1),
+// OTP input: one box per character, built like the Input box: --c-background with a 1px --c-muted border (5.74:1 / 7.85:1),
 // --c-primary on hover, and the keyboard focus thickens the border to the theme's black ring (--c-focus, 21:1 / 19.8:1). An
 // invalid box is --c-error (4.53:1 / 7.16:1) and the message under the boxes is --c-error too; a disabled one is --c-surface
 // with --c-disabled-text (exempt from contrast). The digit is --c-text (17.93:1 / 18.16:1). Square, 3rem by 3.5rem.
@@ -1520,7 +1520,7 @@
     $c-date-range-open-border-color: $var-focus
 );
 
-// Rating: the stars are --c-primary (21:1 / 19.8:1 on the background) over --c-muted ones (4.74:1 / 7.85:1), so the filled
+// Rating: the stars are --c-primary (21:1 / 19.8:1 on the background) over --c-muted ones (5.74:1 / 7.85:1), so the filled
 // and the empty part differ by shape (a solid star against an outline one) and by lightness (4.43:1 / 2.52:1 between them),
 // never by hue alone; the preview while hovering is --c-primary-hover (15.13:1 in light). The keyboard ring is the theme's --c-focus. The label is the field label style in --c-muted.
 @use '@carissa-io/components-rating/scss' as rating with (
@@ -1582,7 +1582,7 @@
 
 // Async autocomplete: the Combobox's field (a text input over the Listbox in the Popover, configured above) with a spinner
 // while a request is pending (--c-primary arc over a --c-surface-active track) and one message in the panel per state:
-// loading and empty in --c-muted (4.74:1 / 7.85:1, the Listbox's empty message color) and an error in --c-error (4.53:1 / 7.16:1).
+// loading and empty in --c-muted (5.74:1 / 7.85:1, the Listbox's empty message color) and an error in --c-error (4.53:1 / 7.16:1).
 @use '@carissa-io/components-async-autocomplete/scss' as async-autocomplete with (
     $c-async-autocomplete-color: $var-text,
     $c-async-autocomplete-min-height: 1.5em,
@@ -1597,3 +1597,58 @@
     $c-async-autocomplete-empty-color: $var-muted,
     $c-async-autocomplete-error-color: $var-error
 );
+
+// Section and container: layout only. Gutters of 1rem growing to 2rem and the three vertical rhythms are plain lengths; the
+// section title is --c-text (17.93:1 / 18.16:1) in the theme's h2 style and the lead paragraph is --c-muted (5.74:1 / 7.85:1).
+@use '@carissa-io/components-section/scss' as section with (
+    $c-container-gutter: 1rem,
+    $c-container-gutter-wide: 2rem,
+    $c-section-spacing-sm: 2rem,
+    $c-section-spacing-md: 4rem,
+    $c-section-spacing-lg: 6rem,
+    $c-section-header-gap: 0.75rem,
+    $c-section-header-margin-bottom: 2rem,
+    $c-section-title-font-size: $font-size-h2,
+    $c-section-title-font-weight: $font-weight-black,
+    $c-section-title-line-height: 1.2,
+    $c-section-title-color: $var-text,
+    $c-section-description-font-size: $font-size-lead,
+    $c-section-description-line-height: 1.6,
+    $c-section-description-color: $var-muted
+);
+
+// FAQ: the accordion block above does the look (its stylesheet is forwarded by the faq one, so keep this block after it); the
+// answers are --c-text (17.93:1 / 18.16:1) at a 1.6 line height and the list is capped at a readable measure.
+@use '@carissa-io/components-faq/scss' as faq with (
+    $c-faq-max-width: 48rem,
+    $c-faq-answer-color: $var-text,
+    $c-faq-answer-line-height: 1.6
+);
+
+// Carousel: the arrows and the pause / play button are the secondary button (--c-muted border, --c-text glyph at 17.93:1 / 18.16:1, a
+// --c-surface-active hover), square like every control of the theme. Inactive dots are --c-muted and the
+// current one is --c-primary and longer (1.5rem against 0.625rem), so position is not told by colour alone. The ring is the
+// theme's --c-focus.
+@use '@carissa-io/components-carousel/scss' as carousel with (
+    $c-carousel-gap: 1rem,
+    $c-carousel-transition-duration: $transition-duration,
+    $c-carousel-controls-gap: 1rem,
+    $c-carousel-controls-margin-top: 1rem,
+    $c-carousel-button-size: $min-height,
+    $c-carousel-button-radius: $radius,
+    $c-carousel-button-border-width: 1px,
+    $c-carousel-button-border-color: $var-muted,
+    $c-carousel-button-color: $var-text,
+    $c-carousel-button-background: $var-background,
+    $c-carousel-button-background-hover: $var-surface-active,
+    $c-carousel-button-disabled-opacity: 0.5,
+    $c-carousel-icon-size: 0.5rem,
+    $c-carousel-icon-thickness: 2px,
+    $c-carousel-dot-size: 0.625rem,
+    $c-carousel-dot-size-current: 1.5rem,
+    $c-carousel-dot-gap: 0.5rem,
+    $c-carousel-dot-color: $var-muted,
+    $c-carousel-dot-color-current: $var-primary,
+    $c-carousel-focus-outline: $focus-width solid $var-focus,
+    $c-carousel-focus-outline-offset: 2px
+);