@nubisco/ui 5.7.0 → 5.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nubisco/ui",
-  "version": "5.7.0",
+  "version": "5.8.0",
   "description": "Vue 3 UI component library",
   "packageManager": "pnpm@12.3.4+sha512.961aa41fb077da3a04a441d9f8e15ebc0c96da8ef710b2eb67bf9ee7cb0610eabd48f1fd85f51cffe73846785fa0f87c56a3a872a1d893f8446741b5cce45457",
   "repository": {

package/src/styles/_accent.scss

@@ -0,0 +1,75 @@
+/// Tokens derived from `--nb-c-primary`.
+///
+/// ## Why these cannot be plain aliases at `:root`
+///
+/// A custom property is substituted at computed-value time **on the element
+/// that declares it**. `--nb-c-focus-ring: var(--nb-c-primary)` written at
+/// `:root` therefore freezes to `:root`'s primary, and every descendant
+/// inherits that frozen literal. Re-pointing `--nb-c-primary` further down the
+/// tree, which is exactly what a named theme does, does not reach it.
+///
+/// Measured in Chrome against a document whose `:root` primary was the default
+/// and whose themed scope set its own:
+///
+/// ```text
+///                         :root      inside [data-nb-theme]
+/// --nb-c-primary          #5c35c4    #5b48c9   follows
+/// --nb-c-focus-ring       #5c35c4    #5c35c4   does not
+/// --nb-c-primary-subtle   #5c35c4…   #5c35c4…  does not
+/// ```
+///
+/// So any scope that re-points the primary has to re-emit these alongside it.
+/// They live here, as mixins, so the formulas exist once: `_theme.scss` calls
+/// them for the default theme and `_theme-api.scss` calls them for every named
+/// theme. Two copies would agree today and drift the first time one is edited.
+///
+/// @group @nubisco/theme-api
+
+/// The pale wash of the accent, for an edge drawn ON a primary fill.
+///
+/// @param {Number} $weight - how much accent the mix carries. The light half
+///   uses 39% and the dark half 50%, because the dark primary is already a
+///   lighter step of the ramp and needs less white to land on the same wash.
+@mixin subtle($weight) {
+  --nb-c-primary-subtle: color-mix(
+    in srgb,
+    var(--nb-c-primary) #{$weight},
+    var(--nb-c-white)
+  );
+}
+
+/// The focus ring, used by every interactive control via `:focus-visible`.
+@mixin focus-ring {
+  --nb-c-focus-ring: var(--nb-c-primary);
+}
+
+/// The shell chrome that carries the accent.
+///
+/// The sidebar is a near-black tint of the accent rather than a raw palette
+/// tint, so re-pointing the primary re-tints the rail with it. That is
+/// deliberate: it is what makes the shell follow a product's identity instead
+/// of the vendor's.
+@mixin shell {
+  --nb-shell-sidebar-bg: color-mix(
+    in srgb,
+    var(--nb-c-primary) 20%,
+    var(--nb-c-black)
+  );
+  --nb-shell-sidebar-link-active-bg: color-mix(
+    in srgb,
+    var(--nb-c-primary) 25%,
+    transparent
+  );
+  // Light tint of --nb-c-primary: keeps the accent on-brand and rebrandable
+  // while staying legible (~6:1) on the dark rail, where --nb-c-primary itself
+  // is too dark (~2.5:1).
+  --nb-shell-sidebar-link-active-color: color-mix(
+    in srgb,
+    var(--nb-c-primary) 60%,
+    var(--nb-c-white)
+  );
+  // The grab-line on the inspector's resize handle. A token, not a literal
+  // brand hex: a white-label product should never have to name the vendor's
+  // ramp to restyle the frame.
+  --nb-shell-inspector-resize-color: var(--nb-c-primary);
+}

package/src/styles/_theme-api.scss

@@ -52,7 +52,9 @@
 @use 'sass:map';
 @use 'sass:meta';
 @use 'sass:string';
+@use 'accent' as accent;
 @use 'logic' as logic;
+@use 'variables/categories' as categories;
 
 /// The tints every palette colour is expanded into, matching the library's own
 /// ramp exactly.
@@ -84,7 +86,23 @@ $a11y-roles:
 /// are generated by one implementation rather than by two that agree today.
 @mixin _palette($palette) {
   @each $name, $base in $palette {
-    $shades: logic.make-shades($base);
+    /*
+     * A palette entry is either one colour or a `(light, dark)` pair.
+     *
+     * With one colour, `make-shades` anchors it at its own lightness step and
+     * generates the rest. With two, it anchors BOTH at their own steps and
+     * interpolates between them, which is what an accent needs: a category's
+     * light and dark values are picked independently for contrast, and neither
+     * is a step of the other's ramp. Anchoring only the light one and hoping
+     * the dark half lands nearby does not hold, measured: the four category
+     * pairs anchor at 700/400, 500/200, 700/400 and 500/300.
+     */
+    $shades: null;
+    @if meta.type-of($base) == list {
+      $shades: logic.make-shades(list.nth($base, 1), list.nth($base, 2));
+    } @else {
+      $shades: logic.make-shades($base);
+    }
     @each $tint in $tints {
       $value: map.get($shades, $tint);
       --nb-c-#{$name}-#{$tint}: #{$value};
@@ -191,3 +209,103 @@ $a11y-roles:
   }
   @return true;
 }
+
+/// The ramp steps a theme can point at, as emitted by `_palette`.
+$_min-step: 100;
+$_max-step: 900;
+
+/// Keeps a derived step inside the range the ramp actually emits.
+@function _step($level, $offset) {
+  $v: $level + $offset;
+  @if $v < $_min-step {
+    @return $_min-step;
+  }
+  @if $v > $_max-step {
+    @return $_max-step;
+  }
+  @return $v;
+}
+
+/// Themes an app from its audience category.
+///
+/// This is the one call an app makes. It takes the category the product
+/// belongs to, resolves that to an accent pair, and wires it through the same
+/// `theme()` machinery a hand-written theme uses.
+///
+/// ```scss
+/// @use '@nubisco/ui/styles/theme-api' as nb;
+///
+/// @include nb.app-theme('acta', $category: 'engineers');
+/// ```
+///
+/// An app with an identity of its own overrides the accent and keeps the
+/// category, which still drives anything that groups products by audience:
+///
+/// ```scss
+/// @include nb.app-theme('doodloop',
+///   $category: 'creatives',
+///   $accent: (#0b7285, #41d6e0)
+/// );
+/// ```
+///
+/// ## What it emits
+///
+/// The accent becomes a full ramp named `accent`, anchored at both ends, and
+/// `primary` / `primary-hover` / `primary-active` point at steps of it: the
+/// anchor step, then two steps away from the surface, darker in light mode and
+/// lighter in dark. Each carries its `-a11y` foreground. Everything derived
+/// from the primary is re-emitted in the same scope, because a `var()` alias
+/// written at `:root` would not follow (see `_accent.scss`).
+///
+/// `--nb-c-category` carries the audience colour separately from the accent.
+/// For most apps they are the same value; for one that overrode its accent
+/// they are not, and a surface that groups products by audience wants the
+/// category, not the app's own colour.
+///
+/// @param {String} $id - the app's identifier, chosen by the app. The library
+///   keeps no registry of these: it never needs to know which products exist.
+/// @param {String} $category - one of `creatives`, `engineers`, `home`, `fun`
+/// @param {List} $accent - an optional `(light, dark)` override
+@mixin app-theme($id, $category, $accent: null) {
+  $category-pair: categories.category($category);
+  $pair: $category-pair;
+  @if $accent != null {
+    $pair: categories.accent-pair($accent);
+  }
+
+  $light-hex: list.nth($pair, 1);
+  $dark-hex: list.nth($pair, 2);
+  $light-level: logic.color-level($light-hex);
+  $dark-level: logic.color-level($dark-hex);
+
+  @include theme(
+    $id,
+    $palette: (accent: $pair),
+    $light: (
+      primary: 'accent-#{$light-level}',
+      primary-hover: 'accent-#{_step($light-level, 50)}',
+      primary-active: 'accent-#{_step($light-level, 100)}',
+      category: list.nth($category-pair, 1)
+    ),
+    $dark: (
+      primary: 'accent-#{$dark-level}',
+      primary-hover: 'accent-#{_step($dark-level, -50)}',
+      primary-active: 'accent-#{_step($dark-level, -100)}',
+      category: list.nth($category-pair, 2)
+    )
+  );
+
+  // The primary-derived tokens, re-emitted in the theme's own scopes. Without
+  // these the app gets its accent on buttons and the vendor's purple on focus
+  // rings and the whole shell.
+  [data-nb-theme='#{$id}'] {
+    @include accent.subtle(39%);
+    @include accent.focus-ring;
+    @include accent.shell;
+  }
+
+  .dark[data-nb-theme='#{$id}'],
+  .dark [data-nb-theme='#{$id}'] {
+    @include accent.subtle(50%);
+  }
+}

package/src/styles/_theme.scss

@@ -1,5 +1,6 @@
 @use 'sass:color';
 @use 'sass:map';
+@use 'accent';
 @use 'config';
 @use 'variables/layout';
 @use 'variables/colors';
@@ -158,11 +159,7 @@
     // hover border visibly moves. The dark theme repeats the mix at 50%
     // because its --nb-c-primary is already a lighter step of the same ramp
     // and needs less white to land on the same wash (dE2000 0.00 there).
-    --nb-c-primary-subtle: color-mix(
-      in srgb,
-      var(--nb-c-primary) 39%,
-      var(--nb-c-white)
-    );
+    @include accent.subtle(39%);
 
     --nb-c-secondary: var(--nb-c-plain-black-700);
     --nb-c-secondary-a11y: var(--nb-c-plain-black-700-a11y);
@@ -375,7 +372,7 @@
     --nb-c-component-discrete-text: var(--nb-c-nouveau-gray-700);
 
     // Focus ring — used by all interactive controls via :focus-visible
-    --nb-c-focus-ring: var(--nb-c-primary);
+    @include accent.focus-ring;
 
     // ── Scrim / overlay ───────────────────────────────────────────────────
     // The dim laid over the page by anything that takes over the viewport:
@@ -588,11 +585,7 @@
     // Dark chrome derived from the brand: a near-black tint of --nb-c-primary so
     // rebranding the primary colour re-tints the sidebar too (semantic, not a
     // raw palette tint).
-    --nb-shell-sidebar-bg: color-mix(
-      in srgb,
-      var(--nb-c-primary) 20%,
-      var(--nb-c-black)
-    );
+    @include accent.shell;
     --nb-shell-sidebar-width: calc(var(--nb-base-unit) * 7); // 56px
     // The verbose variant's rail width. A token rather than a literal inside
     // Shell.vue's variant rule, so a product with long navigation labels can
@@ -613,19 +606,6 @@
       var(--nb-c-white) 90%,
       transparent
     );
-    --nb-shell-sidebar-link-active-bg: color-mix(
-      in srgb,
-      var(--nb-c-primary) 25%,
-      transparent
-    );
-    // Light tint of --nb-c-primary: keeps the accent on-brand and rebrandable
-    // while staying legible (~6:1) on the dark rail, where --nb-c-primary itself
-    // is too dark (~2.5:1).
-    --nb-shell-sidebar-link-active-color: color-mix(
-      in srgb,
-      var(--nb-c-primary) 60%,
-      var(--nb-c-white)
-    );
     --nb-shell-topbar-height: calc(var(--nb-base-unit) * 6.25); // 50px
 
     // Shell chrome. Every rule that paints the frame reads one of these, so a
@@ -672,10 +652,6 @@
     --nb-shell-inspector-max-width: max(calc(var(--nb-base-unit) * 36), 50vw);
     --nb-shell-inspector-border: 1px solid var(--nb-c-border);
     --nb-shell-inspector-bg: var(--nb-c-surface);
-    // The grab-line on the inspector's resize handle. A token, not a literal
-    // brand hex: a white-label product should never have to name the vendor's
-    // ramp to restyle the frame.
-    --nb-shell-inspector-resize-color: var(--nb-c-primary);
     // The dimmer behind the navigation drawer at collapsed widths. Black at
     // 45% reads on both themes because it darkens whatever is under it rather
     // than painting a colour of its own.
@@ -707,11 +683,7 @@
     --nb-c-primary: #{colors.get-color('grape-hyacinth', 400)};
     // Same wash, re-mixed: the dark --nb-c-primary is a 400, so it takes less
     // white than the light 500 does to reach the tint this token used to alias.
-    --nb-c-primary-subtle: color-mix(
-      in srgb,
-      var(--nb-c-primary) 50%,
-      var(--nb-c-white)
-    );
+    @include accent.subtle(50%);
     --nb-c-primary-a11y: #{colors.color-contrast(
         colors.get-color('grape-hyacinth', 400)
       )};

package/src/styles/variables/_categories.scss

@@ -0,0 +1,169 @@
+@use 'sass:list';
+@use 'sass:map';
+@use 'sass:meta';
+@use '../logic/a11y' as a11y;
+@use 'layers';
+
+/// The audience categories, and the accent pair each one resolves to.
+///
+/// Nubisco groups its products by audience: creatives, engineers, home, fun.
+/// These are the four accents that grouping resolves to, each a
+/// `(light, dark)` pair.
+///
+/// ## What is deliberately not here
+///
+/// There is no product list. The library holds the four values and nothing
+/// else: it does not know which product belongs to which category, and it must
+/// not. A registry of product ids here would mean cutting a library release
+/// every time a product is added or renamed, and it would invert the
+/// dependency, making the design system know about the things that consume it.
+/// An app names its own category when it themes itself, so a new product needs
+/// no change to this file. The product-to-category map is a portfolio fact and
+/// lives in the workspace standards.
+///
+/// ## Why these exact values
+///
+/// Every value clears WCAG AA (4.5:1) against all four surface layers of the
+/// mode it belongs to. That is a stricter bar than measuring against pure
+/// white and pure black, and it is the one that matters: the library never
+/// renders a pure-white surface. Light accents are measured against the
+/// darkest light layer (`layer-2`, `#e7e8e9`) and dark accents against the
+/// lightest dark layer (`layer-3`, `#3d3e3f`), because those are the worst
+/// cases. `tests/categoryContrast.test.ts` measures the compiled values and
+/// fails if an edit drops one below the bar.
+///
+/// Hover and active are the adjacent steps of the same ramp, darker in light
+/// mode and lighter in dark, so both are strictly further from the surface
+/// than the base. The base is therefore the worst case, and testing it is
+/// enough.
+///
+/// @type Map
+/// @access public
+/// @group @nubisco/colors
+$categories: (
+  creatives: (
+    #846201,
+    #e8c15a,
+  ),
+  engineers: (
+    #5b48c9,
+    #a99dff,
+  ),
+  home: (
+    #086f9e,
+    #5ec1e8,
+  ),
+  fun: (
+    #b83266,
+    #f686ae,
+  ),
+);
+
+/// The `(light, dark)` accent pair for a category.
+///
+/// An unknown name is a build error rather than a silent fallback: a typo that
+/// quietly resolved to the default accent would ship a product in the wrong
+/// colour and nothing would say so.
+///
+/// @param {String} $name - a key of `$categories`
+/// @return {List} the `(light, dark)` pair
+/// @access public
+/// @group @nubisco/colors
+@function category($name) {
+  @if not map.has-key($categories, $name) {
+    @error "Unknown category #{$name}. Expected one of: #{map.keys($categories)}.";
+  }
+  @return map.get($categories, $name);
+}
+
+/// Validates a `(light, dark)` accent pair supplied by an app.
+///
+/// An app with an established identity of its own passes its own pair rather
+/// than taking its category's. This checks the shape so a malformed value
+/// fails at build time instead of emitting nonsense custom properties.
+///
+/// @param {List} $accent - a two-item list of colours
+/// @return {List} the same pair, once validated
+/// @access public
+/// @group @nubisco/colors
+@function accent-pair($accent) {
+  @if meta.type-of($accent) != list or list.length($accent) != 2 {
+    @error "An accent must be a (light, dark) pair of colours, got #{$accent}.";
+  }
+  @each $value in $accent {
+    @if meta.type-of($value) != color {
+      @error "An accent pair must hold colours, got #{$value}.";
+    }
+  }
+  @return $accent;
+}
+
+/// The surfaces an accent is measured against, per mode.
+///
+/// These are the library's own layers, resolved from
+/// `variables/_layers.scss`, not pure white and pure black. That distinction
+/// is the point: an accent verified against a surface the product never
+/// renders has not been verified. The worst case is the darkest light layer
+/// and the lightest dark layer, and both are in here.
+///
+/// @type Map
+/// @access private
+/// @group @nubisco/colors
+/// Read from the layer ramps rather than restated, so a change to the surface
+/// system is measured against automatically instead of silently invalidating
+/// numbers copied out of it.
+$_grounds: (
+  light: (
+    layers.level(layers.$light, surface, 0),
+    layers.level(layers.$light, surface, 1),
+    layers.level(layers.$light, surface, 2),
+    layers.level(layers.$light, surface, 3),
+  ),
+  dark: (
+    layers.level(layers.$dark, surface, 0),
+    layers.level(layers.$dark, surface, 1),
+    layers.level(layers.$dark, surface, 2),
+    layers.level(layers.$dark, surface, 3),
+  ),
+);
+
+/// Fails the build if an accent pair does not clear WCAG AA on every surface.
+///
+/// The library measures the accents it ships, in
+/// `tests/categoryContrast.test.ts`. It cannot measure an accent an app
+/// supplies, because it never sees it. An app that overrides its accent calls
+/// this so its own build holds it to the same bar.
+///
+/// ```scss
+/// @debug nb.assert-accent-contrast((#0b7285, #41d6e0));
+/// ```
+///
+/// @param {List} $accent - a `(light, dark)` pair
+/// @param {Number} $minimum - the ratio to clear, 4.5 by default
+/// @return {String} a summary, so the call reads as an assertion that returns
+/// @access public
+/// @group @nubisco/colors
+@function assert-accent-contrast($accent, $minimum: 4.5) {
+  $pair: accent-pair($accent);
+  $worst: 21;
+
+  @each $mode, $grounds in $_grounds {
+    $value: list.nth($pair, 2);
+    $direction: 'lighter';
+    @if $mode == light {
+      $value: list.nth($pair, 1);
+      $direction: 'darker';
+    }
+    @each $ground in $grounds {
+      $ratio: a11y.contrast-ratio($value, $ground);
+      @if $ratio < $minimum {
+        @error "Accent #{$value} is #{$ratio}:1 on #{$mode} surface #{$ground}, below #{$minimum}:1. Pick a #{$direction} value.";
+      }
+      @if $ratio < $worst {
+        $worst: $ratio;
+      }
+    }
+  }
+
+  @return 'accent clears #{$minimum}:1 on every surface (worst #{$worst}:1)';
+}

package/src/styles/variables/index.scss

@@ -1,5 +1,6 @@
 @forward 'layout';
 @forward 'colors';
+@forward 'categories';
 @forward 'type';
 @forward 'breakpoints';
 @forward 'grid';