@carissa-io/theme-default 0.1.0 → 0.2.0

package/DESIGN.md

@@ -5,7 +5,7 @@
 This is the design document of the **Carissa Default theme** (`@carissa-io/theme-default`): the decisions behind its
 values. The components are style-agnostic; this theme gives them their look through SCSS variable overrides in
 [scss/index.scss](scss/index.scss), and its palette and shared values (radius, focus ring, transition...) are Sass
-variables at the top of that file. Other themes (tech terminal, brutalist, ...) are their own `theme-<name>` repositories,
+variables in [scss/_tokens.scss](scss/_tokens.scss). Other themes (tech terminal, brutalist, ...) are their own `theme-<name>` repositories,
 never changes to the components.
 
 ## Principles
@@ -22,6 +22,10 @@ never changes to the components.
 | Text (body) | `#171717` |
 | Text (meta, placeholder) | `#737373` (4.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)
+instead of copying the hex values, so a change of value here reaches them with the next release.
+
 ## Typography
 | Variant | Purpose | Style |
 | :--- | :--- | :--- |

package/README.md

@@ -22,9 +22,66 @@ peer dependencies).
    ```scss
    @use '@carissa-io/theme-default/scss';
    ```
-3. **A starting point for a new theme:** copy `scss/index.scss` and change the values. In the Carissa workspace,
+3. **Tokens (Sass variables only, no CSS):** see [Tokens](#tokens).
+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.
 
+## 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
+the values without pulling any rule in. The names are the **public token API**: renaming or removing one is a breaking
+change.
+
+```scss
+@use '@carissa-io/theme-default/scss/tokens' as theme;
+```
+
+| Token | Value | Use |
+| :--- | :--- | :--- |
+| `$black` | `#000` | primary, hover and focus |
+| `$white` | `#fff` | surfaces |
+| `$text` | `#171717` | body text |
+| `$muted` | `#737373` | labels, field borders, placeholders |
+| `$surface` | `#f5f5f5` | hover surface, disabled background |
+| `$surface-active` | `#e5e5e5` | pressed surface, dividers |
+| `$primary-hover` | `#262626` | primary action on hover |
+| `$primary-active` | `#404040` | primary action while pressed |
+| `$disabled-text` | `#a3a3a3` | disabled text and marks |
+| `$disabled-border` | `#d4d4d4` | disabled borders |
+| `$error` | `#dc3545` | error text and borders |
+| `$font-family` | `'Helvetica Neue', Helvetica, Arial, 'Liberation Sans', sans-serif` | type stack |
+| `$radius` | `0` | corner radius |
+| `$min-height` | `2.75rem` | touch target |
+| `$focus-color` | `$black` | focus color |
+| `$focus-width` | `1px` | focus ring width |
+| `$transition-duration` | `0.2s` | color and border transitions |
+| `$label-font-size` | `0.6875rem` | field label size |
+| `$label-font-weight` | `700` | field label weight |
+| `$label-letter-spacing` | `0.1em` | field label tracking |
+| `$arrow-size` | `1rem` | dropdown arrow size |
+| `$arrow-offset` | `0.75rem` | dropdown arrow inset |
+| `$arrow-color` | `$muted` | dropdown arrow color |
+| `$arrow-color-active` | `$black` | dropdown arrow on hover and when open |
+| `$arrow-color-disabled` | `$disabled-text` | dropdown arrow when disabled |
+| `$arrow-transition` | `rotate` and `color`, `$transition-duration` | dropdown arrow motion |
+| `$arrow-rotate-open` | `180deg` | dropdown arrow rotation when open |
+
+**Recommended for apps:** configure Bootstrap from the tokens, so the app and the Carissa components share one palette.
+Needs `sass-embedded` (or `sass`) and a bundler whose Sass importer respects package `exports` (Vite does):
+```scss
+@use '@carissa-io/theme-default/scss/tokens' as theme;
+@use 'bootstrap/scss/bootstrap' with (
+    $primary: theme.$black,
+    $font-family-sans-serif: theme.$font-family,
+    $body-bg: theme.$surface
+);
+```
+Outside a bundler, put `node_modules` on the Sass load path (`sass --load-path=node_modules`).
+
+Every theme repo has its own tokens, with the same names. Switching theme means the same `@use` path with another package
+name (`@carissa-io/theme-<name>/scss/tokens`). A theme that does not define a token must not be used with code that expects
+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`
@@ -32,7 +89,7 @@ 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
-arrow) are Sass variables at the top of `scss/index.scss`; each component has one `@use ... with (...)` block of overrides
+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.
 
 ## Develop

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@carissa-io/theme-default",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "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",
@@ -12,7 +12,8 @@
   "exports": {
     ".": "./dist/index.css",
     "./css": "./dist/index.css",
-    "./scss": "./scss/index.scss"
+    "./scss": "./scss/index.scss",
+    "./scss/tokens": "./scss/_tokens.scss"
   },
   "sideEffects": [
     "*.css"

package/scss/_tokens.scss

@@ -0,0 +1,39 @@
+// Carissa Default theme tokens: the palette and the values shared by every component, as Sass variables only.
+// This file emits no CSS. The variable names below are the PUBLIC TOKEN API: consumers (apps, other tools) may
+// `@use '@carissa-io/theme-default/scss/tokens' as theme;` and read `theme.$black`, `theme.$font-family`...
+// Renaming or removing a token is a breaking change (major release); adding one is a minor release.
+// Every Carissa theme exposes the same names, so switching theme only changes the package name in the `@use`.
+// Neutral scale = Tailwind's neutral palette values, written out as plain colors.
+
+// Palette (Tailwind's neutral scale as plain colors), named by role so a theme is changed in one place.
+$black: #000; // primary, hover and focus
+$white: #fff;
+$text: #171717;
+$muted: #737373; // labels, field borders, placeholders (4.7:1 on white)
+$surface: #f5f5f5; // hover surface, disabled background
+$surface-active: #e5e5e5;
+$primary-hover: #262626;
+$primary-active: #404040;
+$disabled-text: #a3a3a3;
+$disabled-border: #d4d4d4;
+$error: #dc3545;
+
+// Values shared by every component, so the whole theme moves together.
+$font-family: ('Helvetica Neue', Helvetica, Arial, 'Liberation Sans', sans-serif);
+$radius: 0;
+$min-height: 2.75rem; // 44px touch target
+$focus-color: $black;
+$focus-width: 1px;
+$transition-duration: 0.2s;
+$label-font-size: 0.6875rem;
+$label-font-weight: 700;
+$label-letter-spacing: 0.1em;
+
+// The dropdown arrow of Select and Combobox: 16px, muted, black on hover and when open, turns over with the list.
+$arrow-size: 1rem;
+$arrow-offset: 0.75rem;
+$arrow-color: $muted;
+$arrow-color-active: $black;
+$arrow-color-disabled: $disabled-text;
+$arrow-transition: (rotate $transition-duration ease, color $transition-duration ease);
+$arrow-rotate-open: 180deg;

package/scss/index.scss

@@ -1,38 +1,8 @@
 // Carissa Default theme: Swiss minimalism (see DESIGN.md). Only variable overrides, no component code.
 // Neutral scale = Tailwind's neutral palette values, written out as plain colors.
 
-// Palette (Tailwind's neutral scale as plain colors), named by role so a theme is changed in one place.
-$black: #000; // primary, hover and focus
-$white: #fff;
-$text: #171717;
-$muted: #737373; // labels, field borders, placeholders (4.7:1 on white)
-$surface: #f5f5f5; // hover surface, disabled background
-$surface-active: #e5e5e5;
-$primary-hover: #262626;
-$primary-active: #404040;
-$disabled-text: #a3a3a3;
-$disabled-border: #d4d4d4;
-$error: #dc3545;
-
-// Values shared by every component, so the whole theme moves together.
-$font-family: ('Helvetica Neue', Helvetica, Arial, 'Liberation Sans', sans-serif);
-$radius: 0;
-$min-height: 2.75rem; // 44px touch target
-$focus-color: $black;
-$focus-width: 1px;
-$transition-duration: 0.2s;
-$label-font-size: 0.6875rem;
-$label-font-weight: 700;
-$label-letter-spacing: 0.1em;
-
-// The dropdown arrow of Select and Combobox: 16px, muted, black on hover and when open, turns over with the list.
-$arrow-size: 1rem;
-$arrow-offset: 0.75rem;
-$arrow-color: $muted;
-$arrow-color-active: $black;
-$arrow-color-disabled: $disabled-text;
-$arrow-transition: (rotate $transition-duration ease, color $transition-duration ease);
-$arrow-rotate-open: 180deg;
+// The palette and the shared values live in _tokens.scss (the public token API); the blocks below only use them.
+@use 'tokens' as *;
 
 @use '@carissa-io/components-input/scss' as input with (
     // Typography: neutral grotesque stack (no webfont to load), label = bold, uppercase, tracking-widest