@eagami/ui 2.2.0 → 2.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eagami/ui",
-  "version": "2.2.0",
+  "version": "2.4.0",
   "description": "Lightweight, accessible Angular UI component library built on CSS custom properties",
   "author": "Michal Wiraszka <michal@eagami.com>",
   "license": "MIT",

package/src/styles/_reset.scss

@@ -22,7 +22,7 @@ body {
   font-size: var(--font-size-md);
   line-height: var(--line-height-normal);
   color: var(--color-text-primary);
-  background-color: var(--color-bg-base);
+  background-color: var(--color-bg-canvas);
   -webkit-font-smoothing: antialiased;
   -moz-osx-font-smoothing: grayscale;
 }

package/src/styles/tokens/_colors.scss

@@ -85,27 +85,47 @@
   --color-text-primary: var(--color-neutral-900);
   --color-text-secondary: var(--color-neutral-600);
   --color-text-tertiary: var(--color-neutral-400);
-  --color-text-disabled: var(--color-neutral-300);
+  --color-text-disabled: var(--color-neutral-400);
   --color-text-inverse: var(--color-neutral-0);
   --color-text-link: var(--color-primary-600);
   --color-text-link-hover: var(--color-primary-800);
 
-  // Background
+  // Two-tier surface model: `bg-canvas` is the page itself; `bg-base` is the
+  // surface of components on the page (inputs, cards, accordion items,
+  // popover panels). In dark mode bg-base lifts above bg-canvas so component
+  // surfaces don't disappear into the page.
+  --color-bg-canvas: var(--color-neutral-0);
   --color-bg-base: var(--color-neutral-0);
   --color-bg-subtle: var(--color-neutral-50);
+  --color-bg-stripe: var(--color-neutral-50);
   --color-bg-muted: var(--color-neutral-100);
   --color-bg-elevated: var(--color-neutral-0);
   --color-bg-overlay: rgba(0, 0, 0, 0.5);
 
-  // Border
+  // Border. `subtle` is for low-contrast dividers (table rows, cell grids)
+  // where a full `default` border would feel heavy. `default` is the everyday
+  // form-component outline; `strong` is for prominent outlines (secondary
+  // buttons, etc.); `focus` is the keyboard-focus ring.
+  --color-border-subtle: var(--color-neutral-200);
   --color-border-default: var(--color-neutral-200);
   --color-border-strong: var(--color-neutral-400);
   --color-border-focus: var(--color-primary-500);
 
-  // Brand semantic
+  // Brand semantic.
+  //
+  // Two roles split intentionally:
+  //  - `--color-brand-default` (and `-hover` / `-active`) is the brand colour
+  //    used as a **surface** — solid background under white text (primary
+  //    button, badge bg). Needs ≥ 4.5:1 vs white text.
+  //  - `--color-brand-text` is the brand colour used as a **foreground** on a
+  //    non-brand surface (selected dropdown row, today marker, sorted column
+  //    header, link, spinner). Needs ≥ 4.5:1 vs `--color-bg-base`. In dark
+  //    mode the foreground role flips to a lighter shade so contrast against
+  //    the dark surface still holds.
   --color-brand-default: var(--color-primary-600);
   --color-brand-hover: var(--color-primary-700);
   --color-brand-active: var(--color-primary-800);
+  --color-brand-text: var(--color-primary-700);
   --color-brand-subtle: var(--color-primary-50);
   --color-brand-muted: var(--color-primary-100);
 
@@ -154,29 +174,45 @@
 // ---------------------------------------------------------------------------
 @mixin dark-color-tokens {
   --color-text-primary: var(--color-neutral-50);
-  --color-text-secondary: var(--color-neutral-400);
+  --color-text-secondary: var(--color-neutral-300);
   --color-text-tertiary: var(--color-neutral-500);
-  --color-text-disabled: var(--color-neutral-700);
+  --color-text-disabled: var(--color-neutral-500);
   --color-text-inverse: var(--color-neutral-900);
   --color-text-link: var(--color-primary-300);
   --color-text-link-hover: var(--color-primary-100);
 
-  // Dark-mode background hierarchy steps from darkest (page) to lightest (hover),
-  // since elevation in dark mode is conveyed by surface lightness rather than shadow:
-  //   bg-base (950) → bg-subtle (900) → bg-elevated (800) → bg-muted (700)
-  // bg-muted sits *above* bg-elevated so hover states inside elevated surfaces
-  // (dropdowns on a card, menu items in a drawer) still read as a step up.
-  --color-bg-base: var(--color-neutral-950);
-  --color-bg-subtle: var(--color-neutral-900);
-  --color-bg-elevated: var(--color-neutral-800);
-  --color-bg-muted: var(--color-neutral-700);
-
-  --color-border-default: var(--color-neutral-700);
-  --color-border-strong: var(--color-neutral-500);
-
-  --color-brand-default: var(--color-primary-400);
-  --color-brand-hover: var(--color-primary-300);
-  --color-brand-active: var(--color-primary-200);
+  // Dark-mode surface hierarchy. Canvas is the page itself (deepest).
+  // bg-base lifts above it so component surfaces (inputs, cards, accordion
+  // items, popover panels) read above the page instead of disappearing into
+  // it. Subtle / elevated / muted continue the lift for striped rows, floating
+  // surfaces, and hover states.
+  --color-bg-canvas: var(--color-neutral-950);
+  --color-bg-base: var(--color-neutral-800);
+  --color-bg-subtle: var(--color-neutral-700);
+  --color-bg-stripe: var(--color-neutral-900);
+  --color-bg-elevated: var(--color-neutral-700);
+  --color-bg-muted: var(--color-neutral-600);
+
+  // Borders sit clear of every bg-* shade so they stay visible on any surface.
+  // `subtle` mixes between neutral-700 and -800 so it's distinct from the
+  // card surface (neutral-700) while staying close to cell bgs (-800/-900).
+  // `default` is the form-component outline; anything darker collides with
+  // bg-subtle / bg-elevated (both neutral-700) and disappears.
+  --color-border-subtle: color-mix(
+    in srgb,
+    var(--color-neutral-700),
+    var(--color-neutral-800)
+  );
+  --color-border-default: var(--color-neutral-400);
+  --color-border-strong: var(--color-neutral-300);
+
+  // Brand surface roles step one shade lighter than light mode so the button
+  // clears WCAG 1.4.11 (3:1) against the near-black canvas while still
+  // carrying its white label above 4.5:1.
+  --color-brand-default: var(--color-primary-500);
+  --color-brand-hover: var(--color-primary-600);
+  --color-brand-active: var(--color-primary-700);
+  --color-brand-text: var(--color-primary-300);
   --color-brand-subtle: rgba(75, 145, 195, 0.1);
   --color-brand-muted: rgba(75, 145, 195, 0.2);
 

package/src/styles/tokens/_elevation.scss

@@ -15,6 +15,23 @@
   --shadow-2xl: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
   --shadow-inner: inset 0 2px 4px 0 rgba(0, 0, 0, 0.05);
 
+  // Bevel — paired inset highlight (top) + inset shadow (bottom) for surfaces
+  // that should read as raised/3D (chips, ring rims, keyboard keys, mechanical
+  // toggles). Compose with `--shadow-*` for an ambient drop:
+  //   `box-shadow: var(--shadow-bevel), var(--shadow-sm);`
+  --shadow-bevel:
+    inset 0 1px 1px rgba(255, 255, 255, 0.85), inset 0 -1px 1.5px rgba(0, 0, 0, 0.25);
+  --shadow-bevel-strong:
+    inset 0 1.5px 2px rgba(255, 255, 255, 0.9), inset 0 -2px 3px rgba(0, 0, 0, 0.3);
+
+  // Well — paired inset shadow (top) + inset highlight (bottom) for surfaces
+  // that should read as recessed/sunken (cavity in a ring, depressed switch,
+  // inset panel). Inverse lighting of `--shadow-bevel`.
+  --shadow-well:
+    inset 0 1px 1.5px rgba(0, 0, 0, 0.3), inset 0 -1px 0.5px rgba(255, 255, 255, 0.5);
+  --shadow-well-strong:
+    inset 0 2px 3px rgba(0, 0, 0, 0.4), inset 0 -1.5px 1px rgba(255, 255, 255, 0.55);
+
   // Focus ring — used for keyboard accessibility across all interactive elements
   --shadow-focus-ring: 0 0 0 3px rgba(59, 130, 246, 0.45);
   --shadow-focus-ring-error: 0 0 0 3px var(--color-error-200);
@@ -55,6 +72,18 @@
   --shadow-xl:
     0 12px 18px -4px rgba(255, 255, 255, 0.05), 0 5px 8px -4px rgba(255, 255, 255, 0.03);
   --shadow-2xl: 0 16px 28px -8px rgba(255, 255, 255, 0.06);
+
+  // Bevel / well: against a dark surface a bright white highlight reads as a
+  // halo. Drop the highlight alpha and crank the shadow alpha so the relief
+  // still reads as 3D on the lifted bg-base (neutral-800) without glowing.
+  --shadow-bevel:
+    inset 0 1px 1px rgba(255, 255, 255, 0.18), inset 0 -1px 1.5px rgba(0, 0, 0, 0.6);
+  --shadow-bevel-strong:
+    inset 0 1.5px 2px rgba(255, 255, 255, 0.22), inset 0 -2px 3px rgba(0, 0, 0, 0.7);
+  --shadow-well:
+    inset 0 1px 1.5px rgba(0, 0, 0, 0.55), inset 0 -1px 0.5px rgba(255, 255, 255, 0.08);
+  --shadow-well-strong:
+    inset 0 2px 3px rgba(0, 0, 0, 0.7), inset 0 -1.5px 1px rgba(255, 255, 255, 0.12);
 }
 
 @media (prefers-color-scheme: dark) {

package/src/styles/tokens/_typography.scss

@@ -81,6 +81,17 @@
   --text-h4-weight: var(--font-weight-semibold);
   --text-h4-lh: var(--line-height-snug);
 
+  // Section heading — page-level subsection title (e.g. an `<h2>` under an
+  // `<h1>` page title on a docs or marketing page). Same size/weight/lh as
+  // `--text-h4-*` but routes through the brand family so the heading reads
+  // as part of the brand wordmark rather than the body type. The only
+  // composite that pins a font-family; consumers who want to recolour or
+  // resize without re-specifying the family can still override per-piece.
+  --text-section-heading-size: var(--font-size-xl);
+  --text-section-heading-weight: var(--font-weight-semibold);
+  --text-section-heading-lh: var(--line-height-snug);
+  --text-section-heading-family: var(--font-family-brand);
+
   // Body
   --text-body-lg-size: var(--font-size-lg);
   --text-body-lg-weight: var(--font-weight-regular);
@@ -107,10 +118,16 @@
   --text-label-sm-weight: var(--font-weight-medium);
   --text-label-sm-lh: var(--line-height-tight);
 
-  // Helper / caption — used for field-level hint and error messages. Sits
-  // between `--font-size-xs` (12px) and `--font-size-sm` (14px) at 13px so
-  // it stays visually subordinate to the field's label without dropping into
-  // the "barely readable" zone that 12px hits on dense forms.
+  // Helper / caption — small subordinate text that sits visually below the
+  // primary content of a component. Sits between `--font-size-xs` (12px) and
+  // `--font-size-sm` (14px) at 13px so it stays subordinate without dropping
+  // into the "barely readable" zone that 12px hits.
+  //
+  // Primary role: field-level hint and error messages on form-like components
+  // (see STANDARD below). Secondary role: short subordinate metadata text
+  // inside a component, e.g. `<ea-file-uploader>`'s constraints disclosure
+  // ("PNG or JPG up to 5MB") and per-file size label ("245 KB"). For any
+  // role bigger than these, reach for a body-* composite instead.
   //
   // STANDARD — every form-like component (anything exposing `errorMsg` and/or
   // `hint`) must render its messages identically. Mirror `<ea-input>` exactly: