@carissa-io/theme-default 0.3.7 → 0.3.9

package/DESIGN.md

@@ -362,6 +362,61 @@ The panel slides in over `$transition-duration`; with reduced motion it just app
 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.
+
+## 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`.
+
+## 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.
+
+## 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`.
+
+## 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.
+
+## 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).
+
+## 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).
+
+## 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.
+
+## 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.
+
 ## 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`, `-prose`, `-tabs`, `-accordion`, `-breadcrumb`, `-pagination`, `-stepper`, `-sidebar`, `-navbar`, `-drawer` and `-menu`. `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` and `-async-autocomplete`. `components-email`, `-password`, `-url` and `-textarea`
 are styled through the input.
 
 ## Change a value