@carissa-io/theme-default 0.3.15 → 0.3.16

package/DESIGN.md

@@ -49,6 +49,8 @@ Both modes ship in the same package; dark is **opt-in per app** with `data-mode`
 | `warning` | `#a16207` | `#fbbf24` |
 | `info` | `#1d4ed8` | `#60a5fa` |
 | `focus` | `#000000` | `#ffffff` |
+| `scrollbar-thumb` | `#737373` | `#737373` |
+| `scrollbar-track` | `#ffffff` | `#0a0a0a` |
 
 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
@@ -74,6 +76,7 @@ Contrast (WCAG 2.x): text 4.5:1, borders and the focus ring 3:1.
 | `info` on `background` / on `surface` | 6.70 / 6.15 | 7.79 / 7.05 |
 | `error` on `surface` | 4.15 | 6.48 |
 | `disabled-text` on `surface` (disabled, exempt) | 2.31 | 3.78 |
+| `scrollbar-thumb` on `scrollbar-track` / on `background` (the same colour) | 4.74 | 4.18 |
 
 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).
 
@@ -81,6 +84,11 @@ Every `muted` text pairing passes AA in both modes (a test asserts it): the ligh
 `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.
 
+## Scrollbars
+Two rules theme every scroll container, and no component carries a scrollbar rule: `scrollbar-color: var(--c-scrollbar-thumb) var(--c-scrollbar-track)` on `:root` (inherited, so every scroller gets it) and `scrollbar-width: thin` on `*`. The thumb is the neutral 500 (`#737373`) in both modes; the track is the page ground, equal to `background` (`#ffffff` / `#0a0a0a`), so the scrollbar is just a thumb on the page and no extra rail is drawn. The thumb passes the 3:1 non-text minimum against the track and the background (4.74 / 4.18, the same pair) and also on `surface` (4.35 / 3.78) and the `surface-active` hover fill (3.76 / 3.19); a test asserts that the track equals the background and the ratio in each mode. Known trade-off: inside a surface-coloured container (the sidebar, a card) the track shows as a strip of the page colour; a theme can override `$scrollbar-track` (and the dark role) with its surface value. The width is `thin` (the `$scrollbar-width` token), which suits the Swiss restraint and still leaves a target the pointer can grab; touch and overlay scrollbars ignore it.
+
+Known limits: `scrollbar-width` is not an inherited property, so a `:root` declaration would thin only the page; it is declared with a universal rule instead, which has zero specificity so it never overrides a component. The rules use the standard properties only, so there is colour and thickness but no rounding, no arrows and no hover state (those need the `::-webkit-scrollbar` pseudo-elements, which the theme deliberately does not use). Support is Chrome 121+, Firefox 64+ and Safari 18.2+; older browsers keep the native bar, which stays usable. A scroller that sets its own `scrollbar-width` keeps it, whatever the order: the carousel hides its bar on purpose (`scrollbar-width: none`, a class selector) and the theme does not undo it.
+
 ## 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`.

package/README.md

@@ -29,7 +29,7 @@ peer dependencies).
 ## 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-success`, `--c-warning`, `--c-info`, `--c-focus`) that every component reads. **Dark is opt-in per app**: without
+`--c-disabled-text`, `--c-disabled-border`, `--c-error`, `--c-success`, `--c-warning`, `--c-info`, `--c-focus`, `--c-scrollbar-thumb`, `--c-scrollbar-track`) 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>`:
@@ -63,6 +63,19 @@ first paint: put this in the `<head>` of the page, before the stylesheet, with t
 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)`.
 
+## Scrollbars
+The theme styles every scroll container with no change in any component: the page, the message list, the table wrapper, the modal and
+drawer bodies, the select, combobox and listbox popups, the sidebar and code blocks. It is two rules: `scrollbar-color: var(--c-scrollbar-thumb)
+var(--c-scrollbar-track)` on `:root` (the property is inherited) and `scrollbar-width: thin` on `*`, because `scrollbar-width` is not inherited and so
+has to be declared on every element. The `*` rule has zero specificity, so any component rule or your own rule wins over it. The colors
+are two palette roles, so they follow `data-mode`; the thickness is the `$scrollbar-width` token.
+
+To change them in your own theme, set `$scrollbar-thumb`, `$scrollbar-track` and `$scrollbar-width` in your `scss/_tokens.scss` (and the
+dark values of the two roles in `scss/_modes.scss`); keep the thumb at 3:1 or more against the track and against the background. The default track is the page background, so inside a surface-coloured container (the sidebar, a card) it shows as a strip of the page colour; a theme that prefers it quieter there sets `$scrollbar-track` to its surface value. An app that
+only needs one scroller to look different overrides the two properties on that element (`scrollbar-color`, `scrollbar-width`); the carousel
+already hides its own bar. Browsers without the standard properties (before Chrome 121, Firefox 64 or Safari 18.2) keep the native bar. See
+[DESIGN.md](DESIGN.md) for the values and limits.
+
 ## 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
@@ -89,6 +102,9 @@ change.
 | `$success` | `#15803d` | success accent and icon (Alert) |
 | `$warning` | `#a16207` | warning accent and icon (Alert) |
 | `$info` | `#1d4ed8` | info accent and icon (Alert) |
+| `$scrollbar-thumb` | `#737373` | scrollbar thumb |
+| `$scrollbar-track` | `$white` | scrollbar track (the page ground) |
+| `$scrollbar-width` | `thin` | scrollbar thickness |
 | `$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 |

package/dist/index.css

@@ -16,6 +16,8 @@
   --c-warning: #a16207;
   --c-info: #1d4ed8;
   --c-focus: #000;
+  --c-scrollbar-thumb: #737373;
+  --c-scrollbar-track: #fff;
   color-scheme: light;
 }
 
@@ -36,6 +38,8 @@
   --c-warning: #a16207;
   --c-info: #1d4ed8;
   --c-focus: #000;
+  --c-scrollbar-thumb: #737373;
+  --c-scrollbar-track: #fff;
   color-scheme: light;
 }
 
@@ -56,6 +60,8 @@
   --c-warning: #fbbf24;
   --c-info: #60a5fa;
   --c-focus: #fff;
+  --c-scrollbar-thumb: #737373;
+  --c-scrollbar-track: #0a0a0a;
   color-scheme: dark;
 }
 
@@ -77,9 +83,19 @@
     --c-warning: #fbbf24;
     --c-info: #60a5fa;
     --c-focus: #fff;
+    --c-scrollbar-thumb: #737373;
+    --c-scrollbar-track: #0a0a0a;
     color-scheme: dark;
   }
 }
+:root {
+  scrollbar-color: var(--c-scrollbar-thumb) var(--c-scrollbar-track);
+}
+
+* {
+  scrollbar-width: thin;
+}
+
 .c-input {
   display: block;
   font-family: "Helvetica Neue", Helvetica, Arial, "Liberation Sans", sans-serif;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carissa-io/theme-default",
-  "version": "0.3.15",
+  "version": "0.3.16",
   "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",

package/scss/_modes.scss

@@ -1,5 +1,6 @@
 // Carissa Default theme color modes: the light and dark palettes, emitted as CSS custom properties (`--c-<role>`).
-// Loading this partial emits the CSS below (`@use 'modes' as *` in index.scss); `_tokens.scss` stays Sass-only.
+// Loading this partial emits the CSS below (`@use 'modes' as *` in index.scss), including the two scrollbar rules (`:root` and `*`) at the end;
+// `_tokens.scss` stays Sass-only.
 //
 //   no attribute            light (the default)
 //   data-mode="light"       light
@@ -28,6 +29,8 @@ $light: (
     'warning': t.$warning,
     'info': t.$info,
     'focus': t.$focus-color,
+    'scrollbar-thumb': t.$scrollbar-thumb,
+    'scrollbar-track': t.$scrollbar-track,
 );
 
 // Dark: near-black ground, the contrast of the light theme inverted (see DESIGN.md for the ratios).
@@ -48,6 +51,8 @@ $dark: (
     'warning': #fbbf24,
     'info': #60a5fa,
     'focus': #fff,
+    'scrollbar-thumb': #737373,
+    'scrollbar-track': #0a0a0a, // the dark background
 );
 
 // What the component blocks read: `var(--c-<role>)`, one per role.
@@ -67,6 +72,8 @@ $var-success: var(--c-success);
 $var-warning: var(--c-warning);
 $var-info: var(--c-info);
 $var-focus: var(--c-focus);
+$var-scrollbar-thumb: var(--c-scrollbar-thumb);
+$var-scrollbar-track: var(--c-scrollbar-track);
 
 // The dropdown arrow of Select, Combobox and Date picker (the same roles as the `$arrow-*` tokens).
 $var-arrow-color: $var-muted;
@@ -97,3 +104,16 @@ $var-arrow-color-disabled: $var-disabled-text;
         @include palette($dark, dark);
     }
 }
+
+// Scrollbars, in two rules because the two properties differ. `scrollbar-color` is inherited, so one declaration on `:root` reaches every
+// scroll container. `scrollbar-width` is NOT inherited (only the page viewport would get it), so it is declared on every element with the
+// universal selector. `*` has zero specificity (`:where(*)` would be the same; `*` is plain and just as supported), so it never beats a
+// component rule: a scroller that sets its own width (the carousel hides its bar with `scrollbar-width: none`) keeps it, in any order.
+// Standard properties only: colour and thickness, no rounding.
+:root {
+    scrollbar-color: $var-scrollbar-thumb $var-scrollbar-track;
+}
+
+* {
+    scrollbar-width: t.$scrollbar-width;
+}

package/scss/_tokens.scss

@@ -21,6 +21,10 @@ $error: #dc3545;
 $success: #15803d;
 $warning: #a16207;
 $info: #1d4ed8;
+// Scrollbars (every scroll container inherits them from `:root`): a neutral thumb on a track that is the page ground, thin.
+$scrollbar-thumb: #737373; // 4.74:1 on the white track and background (the neutral 500)
+$scrollbar-track: $white; // the light background: the track is the page ground
+$scrollbar-width: thin;
 
 // Values shared by every component, so the whole theme moves together.
 $font-family: ('Helvetica Neue', Helvetica, Arial, 'Liberation Sans', sans-serif);