@carissa-io/theme-default 0.2.1 → 0.3.0

package/DESIGN.md

@@ -26,19 +26,76 @@ The same palette is available as Sass tokens (`$black`, `$muted`, `$surface`, `$
 [scss/_tokens.scss](scss/_tokens.scss), the machine-readable palette: apps read them (for example to configure Bootstrap)
 instead of copying the hex values, so a change of value here reaches them with the next release.
 
-## Typography
-| Variant | Purpose | Style |
+## Dark mode
+Both modes ship in the same package; dark is **opt-in per app** with `data-mode` on `<html>` (`dark`, `light`, or `auto` to follow
+`prefers-color-scheme`; no attribute is light). The palette is a set of custom properties by role, defined in
+[scss/_modes.scss](scss/_modes.scss); the Sass tokens remain the static light values.
+
+| Role (`--c-...`) | Light | Dark |
+| :--- | :--- | :--- |
+| `background` | `#ffffff` | `#0a0a0a` |
+| `text` | `#171717` | `#f5f5f5` |
+| `muted` | `#737373` | `#a3a3a3` |
+| `surface` | `#f5f5f5` | `#171717` |
+| `surface-active` | `#e5e5e5` | `#262626` |
+| `primary` | `#000000` | `#ffffff` |
+| `on-primary` | `#ffffff` | `#000000` |
+| `primary-hover` | `#262626` | `#e5e5e5` |
+| `primary-active` | `#404040` | `#d4d4d4` |
+| `disabled-text` | `#a3a3a3` | `#737373` |
+| `disabled-border` | `#d4d4d4` | `#404040` |
+| `error` | `#dc3545` | `#f87171` |
+| `focus` | `#000000` | `#ffffff` |
+
+Decisions: dark inverts the contrast of the light theme, it does not invent a new look (near-black ground, the primary action becomes white,
+square corners and the 1px focus ring stay). The ground is `#0a0a0a`, not pure black, so surfaces (`#171717`) can be told apart. Primary and focus
+are pure white as black is in light. The error red is lighter (`#f87171`) because `#dc3545` is too dim on a dark ground.
+
+Contrast (WCAG 2.x): text 4.5:1, borders and the focus ring 3:1.
+
+| Pair | Light | Dark |
 | :--- | :--- | :--- |
-| `h1` | Primary page header | Black (900), tight tracking |
-| `h2` | Section header | Black (900) |
-| `h3` | Sub-section | Bold (700) |
-| `body` | Main content | Regular (400) |
-| `label` | Metadata / tags / field labels | Bold (700), uppercase, widest tracking |
-| `mono` | System data | Technical precision |
+| `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 |
+| `on-primary` on `primary` | 21.00 | 21.00 |
+| `error` on `background` | 4.53 | 7.16 |
+| `focus` on `background` | 21.00 | 19.80 |
+| `disabled-text` on `surface` (disabled, exempt) | 2.31 | 3.78 |
+
+`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
+(`#dee2e6`); it draws nothing today.
+
+## Typography
+Configured through [components-typography](components/components-typography): `Heading` (the element comes from `level`, the look from `size`)
+and `Text`. Neutral grotesque, no margins (spacing belongs to the layout), color from `$text`; only muted text uses `$muted`.
+
+| Style | Size / line height | Weight | Tracking | Purpose |
+| :--- | :--- | :--- | :--- | :--- |
+| `display` | 3.5rem / 1.05 | Black (900) | -0.04em | Hero statements |
+| `h1` | 2.5rem / 1.1 | Black (900) | -0.03em | Primary page header |
+| `h2` | 1.75rem / 1.2 | Black (900) | -0.02em | Section header |
+| `h3` | 1.25rem / 1.3 | Bold (700) | normal | Sub-section |
+| `h4` | 1.125rem / 1.3 | Bold (700) | normal | Group title |
+| `h5` | 1rem / 1.4 | Bold (700) | normal | Minor title |
+| `h6` | 0.875rem / 1.4 | Bold (700) | normal | Smallest title |
+| `lead` | 1.25rem / 1.5 | Regular (400) | normal | Introductory paragraph |
+| `body` | 1rem / 1.5 | Regular (400) | normal | Main content |
+| `small` | 0.875rem / 1.5 | Regular (400) | normal | Secondary content |
+| `caption` | 0.75rem / 1.4 | Regular (400), muted by use | normal | Notes under media or fields |
+| `overline` | 0.6875rem / 1.4 | Bold (700), uppercase | 0.1em | Metadata / tags: the field-label style |
+| `mono` | 0.875rem / 1.5 | Regular (400) | normal | System data, in `$font-family-mono` |
+
+The sizes, weights and the two shared line heights of this table are Sass tokens in [scss/_tokens.scss](scss/_tokens.scss)
+(`$font-size-display` to `$font-size-overline`, `$font-weight-regular|bold|black`, `$line-height-tight|normal`), so the whole hierarchy moves
+from one place. The components' own text uses them where it plays the same role (field and option text is `$font-size-body`, the selected
+option `$font-weight-bold`). One-off values stay literal: the line heights 1.05, 1.1, 1.2 and 1.4, the heading tracking, the 0.8125rem error text.
 
 Font family: a neutral grotesque stack, `Helvetica Neue, Helvetica, Arial, Liberation Sans, sans-serif`, in keeping with
-the International Typographic Style. No webfont is loaded, so a theme never depends on the network. Field text is
-1rem (16px, which also avoids the zoom-on-focus of mobile browsers); labels are 11px.
+the International Typographic Style. No webfont is loaded, so a theme never depends on the network. System data uses the
+`$font-family-mono` token, a system monospace stack (`ui-monospace, SFMono-Regular, Menlo, Consolas, Liberation Mono`).
+Field text is 1rem (16px, which also avoids the zoom-on-focus of mobile browsers); labels are 11px.
 
 ## Buttons
 Three variants from [components-button](components/components-button), all square, 44px tall, with the same uppercase,

package/README.md

@@ -26,6 +26,43 @@ peer dependencies).
 4. **A starting point for a new theme:** copy `scss/index.scss` and `scss/_tokens.scss` and change the values. In the Carissa workspace,
    `scripts/new-theme.sh <name> "<description>"` does this and sets up the repo.
 
+## Color modes
+The theme has a light and a dark palette in one package. The palette is a set of CSS custom properties (`--c-background`, `--c-text`,
+`--c-muted`, `--c-surface`, `--c-surface-active`, `--c-primary`, `--c-on-primary`, `--c-primary-hover`, `--c-primary-active`,
+`--c-disabled-text`, `--c-disabled-border`, `--c-error`, `--c-focus`) that every component reads. **Dark is opt-in per app**: without
+the attribute below the app is light, exactly as before.
+
+An app opts in with one line in the file where it imports the theme (`App/theme.js`), setting the mode on `<html>`:
+
+```js
+import '@carissa-io/theme-default/css'
+
+document.documentElement.dataset.mode = 'auto' // 'auto' | 'dark' | 'light'
+```
+
+| `data-mode` on `<html>` | Result |
+| :--- | :--- |
+| none | light |
+| `light` | light |
+| `dark` | dark |
+| `auto` | light, and dark while the system asks for it (`prefers-color-scheme: dark`) |
+
+`color-scheme` follows the mode, so native controls and scrollbars match. To avoid a flash of the wrong mode, set the attribute before the
+first paint: put this in the `<head>` of the page, before the stylesheet, with the choice the app remembers (here in `localStorage`):
+
+```html
+<script>
+    try {
+        document.documentElement.dataset.mode = localStorage.getItem('mode') || 'auto'
+    } catch {
+        document.documentElement.dataset.mode = 'auto'
+    }
+</script>
+```
+
+The Sass tokens above stay the static **light** values (for Sass consumers); the dark values are in `scss/_modes.scss`. The page background and
+text color are the app's: give `body` `background: var(--c-background); color: var(--c-text)`.
+
 ## Tokens
 The palette and the values shared by every component are Sass variables in `scss/_tokens.scss`, the single source of
 the theme's values (`scss/index.scss` reads them with `@use 'tokens' as *`). The file emits no CSS, so an app can read
@@ -50,6 +87,7 @@ change.
 | `$disabled-border` | `#d4d4d4` | disabled borders |
 | `$error` | `#dc3545` | error text and borders |
 | `$font-family` | `'Helvetica Neue', Helvetica, Arial, 'Liberation Sans', sans-serif` | type stack |
+| `$font-family-mono` | `ui-monospace, 'SFMono-Regular', Menlo, Consolas, 'Liberation Mono', monospace` | monospace stack for system data and code |
 | `$radius` | `0` | corner radius |
 | `$min-height` | `2.75rem` | touch target |
 | `$focus-color` | `$black` | focus color |
@@ -58,6 +96,23 @@ change.
 | `$label-font-size` | `0.6875rem` | field label size |
 | `$label-font-weight` | `700` | field label weight |
 | `$label-letter-spacing` | `0.1em` | field label tracking |
+| `$font-size-display` | `3.5rem` | `Heading` display |
+| `$font-size-h1` | `2.5rem` | `Heading` 1 |
+| `$font-size-h2` | `1.75rem` | `Heading` 2 |
+| `$font-size-h3` | `1.25rem` | `Heading` 3 |
+| `$font-size-h4` | `1.125rem` | `Heading` 4 |
+| `$font-size-h5` | `1rem` | `Heading` 5 |
+| `$font-size-h6` | `0.875rem` | `Heading` 6, `Text` mono |
+| `$font-size-lead` | `1.25rem` | `Text` lead |
+| `$font-size-body` | `1rem` | body text, and the text of every field and option (16px) |
+| `$font-size-small` | `0.875rem` | `Text` small |
+| `$font-size-caption` | `0.75rem` | `Text` caption |
+| `$font-size-overline` | `$label-font-size` | `Text` overline |
+| `$font-weight-regular` | `400` | body text |
+| `$font-weight-bold` | `700` | titles from `h3`, selected option |
+| `$font-weight-black` | `900` | `display`, `h1` and `h2` |
+| `$line-height-tight` | `1.3` | `h3` and `h4` |
+| `$line-height-normal` | `1.5` | running text |
 | `$arrow-size` | `1rem` | dropdown arrow size |
 | `$arrow-offset` | `0.75rem` | dropdown arrow inset |
 | `$arrow-color` | `$muted` | dropdown arrow color |
@@ -84,11 +139,11 @@ 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` and `-search`. `components-email`, `-password`, `-url` and `-textarea`
+`-combobox`, `-upload`, `-calendar`, `-date-picker`, `-search` and `-typography`. `components-email`, `-password`, `-url` and `-textarea`
 are styled through the input.
 
 ## Change a value
-The palette and the values shared by every component (radius, minimum height, focus ring, transition, label style, dropdown
+The palette and the values shared by every component (fonts, radius, minimum height, focus ring, transition, label style, dropdown
 arrow) are the Sass variables of `scss/_tokens.scss` (the [tokens](#tokens)); each component has one `@use ... with (...)` block of overrides
 below. Change the value, run `npm run build`, and update [DESIGN.md](DESIGN.md) if the decision changes.