@carissa-io/theme-default 0.3.6 → 0.3.8

package/DESIGN.md

@@ -319,6 +319,74 @@ large scale the text and the headings by 0.875 and 1.125). Headings use the type
 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).
 
+## 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.
+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
+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`
+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
+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)
+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`
+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.
+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),
+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
+From [components-drawer](components/components-drawer): `Drawer`, the Modal's box as a panel on an edge of the screen (`start`, `end`, `top`, `bottom`; `sm` 20rem, `md` 28rem, `lg` 40rem). It is `--c-background` with `--c-text` (17.93:1 / 18.16:1), a 1px `--c-muted` border
+(the edge that still reads in dark), square, with the Modal's layered shadow and the same padding (1.5rem by 1.25rem) and close button (`--c-muted`, `--c-text` on hover). The **backdrop** is `rgb(0 0 0 / 0.5)` in both modes, with the shadow the only literal color of the block.
+The panel slides in over `$transition-duration`; with reduced motion it just appears.
+
+## 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.
+
+## 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.
+
+## 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.
+
+## 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.
+
+## 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.
+
+## 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.
+
+## 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.
+
+## 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.
+
 ## Keyboard focus (all controls)
 One rule keeps the controls coherent: **an outlined control thickens its own border from 1px to 2px, black** (text fields,
 select, combobox, date picker, textarea, upload, empty checkbox, off switch, radio, secondary and ghost buttons); **a filled

package/README.md

@@ -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` and `-prose`. `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` and `-code`. `components-email`, `-password`, `-url` and `-textarea`
 are styled through the input.
 
 ## Change a value