@nubisco/ui 1.60.2 → 2.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nubisco/ui",
-  "version": "1.60.2",
+  "version": "2.0.0",
   "description": "Vue 3 UI component library",
   "packageManager": "pnpm@11.0.8",
   "repository": {

package/src/styles/_theme.scss

@@ -3,6 +3,7 @@
 @use 'config';
 @use 'variables/layout';
 @use 'variables/colors';
+@use 'variables/layers';
 @use 'variables/type';
 @use 'variables/grid';
 @use 'variables/animations';
@@ -115,20 +116,20 @@
     // Layer 1: panels, cards, sidebar body
     // Layer 2: nested panels, inspector sections
     // Layer 3: overlays, popovers, modals (highest)
-    --nb-c-layer-0: #{colors.get-color('french-gray', 100)};
-    --nb-c-layer-1: #{colors.get-color('plain-white', 100)};
-    --nb-c-layer-2: #{colors.get-color('french-gray', 100)};
-    --nb-c-layer-3: #{colors.get-color('plain-white', 100)};
+    --nb-c-layer-0: #{layers.level(layers.$light, surface, 0)};
+    --nb-c-layer-1: #{layers.level(layers.$light, surface, 1)};
+    --nb-c-layer-2: #{layers.level(layers.$light, surface, 2)};
+    --nb-c-layer-3: #{layers.level(layers.$light, surface, 3)};
 
-    --nb-c-layer-border-0: #{colors.get-color('french-gray', 250)};
-    --nb-c-layer-border-1: #{colors.get-color('french-gray', 250)};
-    --nb-c-layer-border-2: #{colors.get-color('french-gray', 300)};
-    --nb-c-layer-border-3: #{colors.get-color('french-gray', 200)};
+    --nb-c-layer-border-0: #{layers.level(layers.$light, border, 0)};
+    --nb-c-layer-border-1: #{layers.level(layers.$light, border, 1)};
+    --nb-c-layer-border-2: #{layers.level(layers.$light, border, 2)};
+    --nb-c-layer-border-3: #{layers.level(layers.$light, border, 3)};
 
-    --nb-c-layer-hover-0: #{colors.get-color('french-gray', 200)};
-    --nb-c-layer-hover-1: #{colors.get-color('french-gray', 150)};
-    --nb-c-layer-hover-2: #{colors.get-color('french-gray', 200)};
-    --nb-c-layer-hover-3: #{colors.get-color('french-gray', 150)};
+    --nb-c-layer-hover-0: #{layers.level(layers.$light, hover, 0)};
+    --nb-c-layer-hover-1: #{layers.level(layers.$light, hover, 1)};
+    --nb-c-layer-hover-2: #{layers.level(layers.$light, hover, 2)};
+    --nb-c-layer-hover-3: #{layers.level(layers.$light, hover, 3)};
 
     // Semantic surface tokens — default to layer-1 (most components sit on layer-0)
     --nb-c-surface: var(--nb-c-layer-1);
@@ -193,16 +194,22 @@
     --nb-c-component-plain-border-a11y: var(--nb-c-nouveau-gray-300-a11y);
 
     // Text
-    --nb-c-text: var(--nb-c-plain-black-900);
-    --nb-c-text-a11y: var(--nb-c-plain-black-900-a11y);
-    --nb-c-text-muted: var(--nb-c-nouveau-gray-600);
-    --nb-c-text-muted-a11y: var(--nb-c-nouveau-gray-600-a11y);
-    --nb-c-text-subtle: var(--nb-c-nouveau-gray-500);
-    --nb-c-text-subtle-a11y: var(--nb-c-nouveau-gray-500-a11y);
+    --nb-c-text: #{layers.token(layers.$light, text)};
+    --nb-c-text-a11y: #{colors.color-contrast(
+        layers.token(layers.$light, text)
+      )};
+    --nb-c-text-muted: #{layers.token(layers.$light, text-muted)};
+    --nb-c-text-muted-a11y: #{colors.color-contrast(
+        layers.token(layers.$light, text-muted)
+      )};
+    --nb-c-text-subtle: #{layers.token(layers.$light, text-subtle)};
+    --nb-c-text-subtle-a11y: #{colors.color-contrast(
+        layers.token(layers.$light, text-subtle)
+      )};
 
     // Form field tokens: heights and padding relative to --nb-base-unit (8px)
-    --nb-c-field-bg: var(--nb-c-french-gray-100);
-    --nb-c-field-border: var(--nb-c-french-gray-500);
+    --nb-c-field-bg: #{layers.token(layers.$light, field-bg)};
+    --nb-c-field-border: #{layers.token(layers.$light, field-border)};
     // xs is the compact size for dense surfaces (inspectors, toolbars).
     // Distinctly smaller than sm; pair with a 13px field font. See the
     // "Building an inspector" guide in the docs before reaching for it.
@@ -219,8 +226,8 @@
     --nb-field-label-gap: calc(var(--nb-base-unit) * 0.75);
 
     // Background tiers
-    --nb-c-bg: var(--nb-c-french-gray-100);
-    --nb-c-bg-soft: var(--nb-c-french-gray-200);
+    --nb-c-bg: var(--nb-c-layer-0);
+    --nb-c-bg-soft: var(--nb-c-layer-1);
 
     // Discrete / muted interactive states
     --nb-c-discrete: var(--nb-c-nouveau-gray-200);
@@ -430,20 +437,20 @@
 
     // ── Layer system (dark) ───────────────────────────────────────────────
     // In dark mode, layers get progressively lighter as elevation increases
-    --nb-c-layer-0: #{colors.get-color('nouveau-gray', 900)};
-    --nb-c-layer-1: #{colors.get-color('plain-black', 850)};
-    --nb-c-layer-2: #{colors.get-color('nouveau-gray', 800)};
-    --nb-c-layer-3: #{colors.get-color('nouveau-gray', 750)};
+    --nb-c-layer-0: #{layers.level(layers.$dark, surface, 0)};
+    --nb-c-layer-1: #{layers.level(layers.$dark, surface, 1)};
+    --nb-c-layer-2: #{layers.level(layers.$dark, surface, 2)};
+    --nb-c-layer-3: #{layers.level(layers.$dark, surface, 3)};
 
-    --nb-c-layer-border-0: #{colors.get-color('nouveau-gray', 750)};
-    --nb-c-layer-border-1: #{colors.get-color('nouveau-gray', 700)};
-    --nb-c-layer-border-2: #{colors.get-color('nouveau-gray', 650)};
-    --nb-c-layer-border-3: #{colors.get-color('nouveau-gray', 600)};
+    --nb-c-layer-border-0: #{layers.level(layers.$dark, border, 0)};
+    --nb-c-layer-border-1: #{layers.level(layers.$dark, border, 1)};
+    --nb-c-layer-border-2: #{layers.level(layers.$dark, border, 2)};
+    --nb-c-layer-border-3: #{layers.level(layers.$dark, border, 3)};
 
-    --nb-c-layer-hover-0: #{colors.get-color('nouveau-gray', 800)};
-    --nb-c-layer-hover-1: #{colors.get-color('nouveau-gray', 750)};
-    --nb-c-layer-hover-2: #{colors.get-color('nouveau-gray', 700)};
-    --nb-c-layer-hover-3: #{colors.get-color('nouveau-gray', 650)};
+    --nb-c-layer-hover-0: #{layers.level(layers.$dark, hover, 0)};
+    --nb-c-layer-hover-1: #{layers.level(layers.$dark, hover, 1)};
+    --nb-c-layer-hover-2: #{layers.level(layers.$dark, hover, 2)};
+    --nb-c-layer-hover-3: #{layers.level(layers.$dark, hover, 3)};
 
     // Surface tokens — override to dark values
     --nb-c-surface: var(--nb-c-layer-1);
@@ -454,17 +461,21 @@
     --nb-c-document: #{colors.get-color('plain-white', 50)};
 
     // Text
-    --nb-c-text: #{colors.get-color('plain-white', 150)}; // primary text: ~#d9d9d9
-    --nb-c-text-muted: #{colors.get-color('nouveau-gray', 400)};
-    --nb-c-text-subtle: #{colors.get-color('nouveau-gray', 500)};
+    --nb-c-text: #{layers.token(layers.$dark, text)};
+    --nb-c-text-a11y: #{colors.color-contrast(layers.token(layers.$dark, text))};
+    --nb-c-text-muted: #{layers.token(layers.$dark, text-muted)};
+    --nb-c-text-muted-a11y: #{colors.color-contrast(
+        layers.token(layers.$dark, text-muted)
+      )};
+    --nb-c-text-subtle: #{layers.token(layers.$dark, text-subtle)};
 
     // Background tiers — deepest layer for page background
-    --nb-c-bg: #{colors.get-color('nouveau-gray', 900)}; // page bg: ~#17191c (close to VitePress's #1b1b1f)
-    --nb-c-bg-soft: #{colors.get-color('nouveau-gray', 850)}; // elevated bg: ~#242527
+    --nb-c-bg: var(--nb-c-layer-0);
+    --nb-c-bg-soft: var(--nb-c-layer-1);
 
     // Form fields
-    --nb-c-field-bg: #{colors.get-color('plain-black', 800)}; // input bg: ~#333333
-    --nb-c-field-border: #{colors.get-color('nouveau-gray', 600)};
+    --nb-c-field-bg: #{layers.token(layers.$dark, field-bg)};
+    --nb-c-field-border: #{layers.token(layers.$dark, field-border)};
 
     // Discrete
     --nb-c-discrete: #{colors.get-color('nouveau-gray', 700)};

package/src/styles/variables/_layers.scss

@@ -0,0 +1,142 @@
+@use 'sass:map';
+
+/// Layer ramps.
+///
+/// The four visual depth levels, defined as explicit values rather than derived
+/// from the tint ramp. Depth separation is a measured property: each step has to
+/// clear a perceptual distance from its neighbour, and every text colour has to
+/// clear AAA on every surface it can land on, including hover surfaces. A
+/// lightness-stepped tint chain cannot express that, and it also emitted
+/// fractional `rgb(229.5, ...)` channels.
+///
+/// Verify any change here with `node scripts/audit-contrast.mjs`, which measures
+/// these against the published Carbon Design System token values in
+/// `scripts/fixtures/carbon-tokens.json`.
+///
+/// @group @nubisco/layers
+
+/// Light ramp.
+///
+/// Alternates the way Carbon's light themes do, because a light theme should
+/// stay light as surfaces stack: CIE L* 94.05 ground, 98.22 panel, 91.95 nested
+/// section, 96.14 popover. The deepest surface is still a bright L* 96, so
+/// nesting never turns the page muddy.
+///
+/// Two deliberate improvements on the reference. Carbon's g10 sets layer-02
+/// byte-identical to its background and layer-03 to layer-01, so past one level
+/// of nesting the fill carries no depth information at all. Here all four
+/// surfaces are distinct, worst pair 2.08 dL*. And no surface goes above
+/// L* 98.5: a fill pinned against the L*100 ceiling under dark text is the
+/// light-theme equivalent of a near-black ground, and glare over long sessions
+/// is set by the brightest surface, not the darkest.
+///
+/// Because the fill alternates it cannot carry depth order on its own, so the
+/// borders do: 2.15 / 2.60 / 3.05 / 3.50 against their own surface, escalating
+/// with depth, capped well short of reading as a wireframe.
+///
+/// Hover darkens on every layer, 5.7 to 8.0 dL*, and every hover value sits at
+/// least 1.76 dL* from every surface value, so a hovered row never reads as
+/// another layer's resting state.
+///
+/// @type Map
+$light: (
+  surface: (
+    0: #edeeef,
+    1: #f9fafb,
+    2: #e7e8e9,
+    3: #f3f4f5,
+  ),
+  border: (
+    0: #a3a4a5,
+    1: #9c9d9e,
+    2: #838485,
+    3: #818283,
+  ),
+  hover: (
+    0: #dcddde,
+    1: #e2e3e4,
+    2: #d7d8d9,
+    3: #e1e2e3,
+  ),
+  text: #242526,
+  text-muted: #38393a,
+  text-subtle: #545556,
+  field-bg: #cacbcc,
+  field-border: #646566,
+);
+
+/// Dark ramp.
+///
+/// CIE L* 4.63 / 11.69 / 18.87 / 26.15, adjacent steps 7.06 / 7.18 / 7.27,
+/// non-decreasing so deeper nesting separates more, matching the discipline of
+/// Carbon's g100 ramp rather than our previous flat 6.70 / 5.20 / 5.58.
+///
+/// Hover REVERSES at layer 3: levels 0 to 2 lighten by about 5.1 dL*, level 3
+/// darkens by 5.42. There is no headroom above layer 3, and a hover surface
+/// lighter than it would force muted text toward white, collapsing the gap
+/// between the two text tiers. Carbon does the same thing at the top of its own
+/// g90 ramp (layer-03 #6f6f6f hovers to #5e5e5e). Direction is not the
+/// requirement, magnitude is.
+///
+/// layer-0 sits low deliberately. Raising it drags the whole ramp up, which
+/// raises layer 3, which forces muted text brighter to hold 7:1 there, which
+/// forces primary brighter still to keep the tiers apart, which makes glare
+/// worse rather than better. Halation is set at the top of the ramp, not the
+/// bottom: primary text on the page ground measures 15.96:1 here, against
+/// 17.63:1 for a near-black ground and 18.06:1 for a raised one.
+///
+/// @type Map
+$dark: (
+  surface: (
+    0: #0f1011,
+    1: #1e1f20,
+    2: #2d2e2f,
+    3: #3d3e3f,
+  ),
+  border: (
+    0: #434445,
+    1: #4d4e4f,
+    2: #595a5b,
+    3: #696a6b,
+  ),
+  hover: (
+    0: #1a1b1c,
+    1: #292a2b,
+    2: #38393a,
+    3: #313233,
+  ),
+  text: #eaebec,
+  text-muted: #d0d1d2,
+  text-subtle: #a7a8aa,
+  field-bg: #141516,
+  field-border: #626364,
+);
+
+/// The third text tier, `text-subtle`, is held to WCAG AA (4.5:1) rather than
+/// AAA, on every one of the nine painted surfaces in its theme. AAA is not
+/// reachable for a third tier: muted already sits at 9.43:1 on the darkest light
+/// surface, so a tier lighter than muted and still above 7:1 has almost no room
+/// to exist and would not read as a separate tier. Carbon makes the same call
+/// with its own helper text. Use `text-subtle` only for genuinely non-essential
+/// text, and never for anything a person must read to operate the interface.
+///
+/// Returns one value from a ramp.
+///
+/// @param {Map} $ramp - `$light` or `$dark`
+/// @param {String} $role - surface, border or hover
+/// @param {Number} $level - 0 through 3
+/// @access public
+/// @group @nubisco/layers
+@function level($ramp, $role, $level) {
+  @return map.get(map.get($ramp, $role), $level);
+}
+
+/// Returns a scalar token from a ramp.
+///
+/// @param {Map} $ramp - `$light` or `$dark`
+/// @param {String} $key - text, text-muted, field-bg or field-border
+/// @access public
+/// @group @nubisco/layers
+@function token($ramp, $key) {
+  @return map.get($ramp, $key);
+}