@ultimat3/ui 1.0.0

package/src/theme/theme.ts

@@ -0,0 +1,116 @@
+// Theme resolution. One rule: an explicit choice in storage wins, otherwise the
+// OS decides. Every side effect goes through an injected `ThemeEnv`, so this is
+// testable without a DOM and reusable on the server.
+
+import { invalidThemeError, runtimeMissingError } from '../errors';
+import type { Theme } from '../tokens/tokens';
+
+export type { Theme };
+
+export const THEME_STORAGE_KEY = 'ultimate.theme';
+export const THEME_ATTRIBUTE = 'data-theme';
+export const THEME_MEDIA_QUERY = '(prefers-color-scheme: dark)';
+
+/** The host capabilities theme control needs. Injected so tests need no DOM. */
+export interface ThemeEnv {
+  read(): string | null;
+  write(value: string): void;
+  remove(): void;
+  prefersDark(): boolean;
+  apply(theme: Theme): void;
+  /** Subscribe to OS scheme changes. Returns an unsubscribe. */
+  observeOs(listener: () => void): () => void;
+}
+
+export function isTheme(value: unknown): value is Theme {
+  return value === 'light' || value === 'dark';
+}
+
+function assertTheme(value: unknown): asserts value is Theme {
+  if (!isTheme(value)) throw invalidThemeError(value);
+}
+
+/** The user's explicit choice, or null when they have never chosen. */
+export function storedTheme(env: ThemeEnv): Theme | null {
+  const raw = env.read();
+  return isTheme(raw) ? raw : null;
+}
+
+export function osTheme(env: ThemeEnv): Theme {
+  return env.prefersDark() ? 'dark' : 'light';
+}
+
+/** Resolution order: explicit stored choice -> OS preference. */
+export function resolveTheme(env: ThemeEnv): Theme {
+  return storedTheme(env) ?? osTheme(env);
+}
+
+/** Run once on load. Idempotent — safe after the inline head script. */
+export function initTheme(env: ThemeEnv = browserThemeEnv()): Theme {
+  const theme = resolveTheme(env);
+  env.apply(theme);
+  return theme;
+}
+
+/** The user picked a theme. Persist it so it outranks the OS from now on. */
+export function setTheme(theme: Theme, env: ThemeEnv = browserThemeEnv()): Theme {
+  assertTheme(theme);
+  env.write(theme);
+  env.apply(theme);
+  return theme;
+}
+
+/** Forget the explicit choice and follow the OS again. */
+export function clearTheme(env: ThemeEnv = browserThemeEnv()): Theme {
+  env.remove();
+  const theme = osTheme(env);
+  env.apply(theme);
+  return theme;
+}
+
+/** Flip whatever is currently resolved, and record it as an explicit choice. */
+export function toggleTheme(env: ThemeEnv = browserThemeEnv()): Theme {
+  return setTheme(resolveTheme(env) === 'dark' ? 'light' : 'dark', env);
+}
+
+/**
+ * Follow the OS live — but only while the user has made no explicit choice.
+ * Returns an unsubscribe so a component can drop it on cleanup.
+ */
+export function watchOsTheme(env: ThemeEnv = browserThemeEnv()): () => void {
+  return env.observeOs(() => {
+    if (storedTheme(env) === null) env.apply(osTheme(env));
+  });
+}
+
+/** The real browser implementation. Throws off-DOM instead of failing silently. */
+export function browserThemeEnv(): ThemeEnv {
+  if (typeof document === 'undefined' || typeof window === 'undefined') {
+    throw runtimeMissingError(
+      'document/window for theme control',
+      'pass an explicit ThemeEnv: initTheme(myServerThemeEnv)',
+    );
+  }
+  const media = window.matchMedia(THEME_MEDIA_QUERY);
+  return {
+    read: () => safeStorage(() => window.localStorage.getItem(THEME_STORAGE_KEY), null),
+    write: (value) => safeStorage(() => window.localStorage.setItem(THEME_STORAGE_KEY, value)),
+    remove: () => safeStorage(() => window.localStorage.removeItem(THEME_STORAGE_KEY)),
+    prefersDark: () => media.matches,
+    apply: (theme) => document.documentElement.setAttribute(THEME_ATTRIBUTE, theme),
+    observeOs: (listener) => {
+      media.addEventListener('change', listener);
+      return () => media.removeEventListener('change', listener);
+    },
+  };
+}
+
+// Private-mode Safari throws on localStorage access; a theme is never worth a
+// crash, so storage failures degrade to "no stored choice".
+function safeStorage<T>(fn: () => T, fallback?: T): T {
+  try {
+    return fn();
+  } catch {
+    return fallback as T;
+  }
+}

package/src/tokens/_breakpoints.scss

@@ -0,0 +1,10 @@
+// Viewport breakpoints. Prefer container queries; reach for these only when the
+// layout genuinely depends on the viewport (app shell, sticky bars).
+
+$breakpoints: (
+  sm: 480px,
+  md: 768px,
+  lg: 1024px,
+  xl: 1280px,
+  2xl: 1536px,
+);

package/src/tokens/_colors.scss

@@ -0,0 +1,95 @@
+// Canonical colour token source. Semantic roles only, stored as space-separated
+// RGB channels so `rgb(var(--color-x) / 0.5)` composites without a second token.
+// `tokens.ts` mirrors these values; `x verify` fails if the two drift.
+
+$light: (
+  bg: 253 246 240,
+  bg-soft: 245 237 230,
+  surface: 250 245 241,
+  surface-raised: 255 255 255,
+  fg: 38 34 31,
+  fg-strong: 17 15 13,
+  fg-muted: 110 102 94,
+  line: 224 216 208,
+  scrim: 17 15 13,
+  accent: 34 122 197,
+  accent-strong: 21 92 152,
+  accent-fg: 255 255 255,
+  success: 22 128 84,
+  success-soft: 222 244 232,
+  success-fg: 255 255 255,
+  warning: 176 106 8,
+  warning-soft: 253 240 213,
+  warning-fg: 255 255 255,
+  danger: 190 42 42,
+  danger-soft: 253 227 227,
+  danger-fg: 255 255 255,
+  info: 34 122 197,
+  info-soft: 224 239 252,
+  info-fg: 255 255 255,
+);
+
+$dark: (
+  bg: 18 18 20,
+  bg-soft: 28 28 32,
+  surface: 34 34 39,
+  surface-raised: 44 44 50,
+  fg: 228 226 222,
+  fg-strong: 248 247 245,
+  fg-muted: 150 146 140,
+  line: 54 54 60,
+  scrim: 0 0 0,
+  accent: 96 170 240,
+  accent-strong: 130 190 248,
+  accent-fg: 16 20 26,
+  success: 74 190 130,
+  success-soft: 22 46 34,
+  success-fg: 12 26 18,
+  warning: 226 170 66,
+  warning-soft: 52 42 20,
+  warning-fg: 28 20 6,
+  danger: 240 110 110,
+  danger-soft: 56 26 26,
+  danger-fg: 30 12 12,
+  info: 96 170 240,
+  info-soft: 22 38 56,
+  info-fg: 12 20 30,
+);
+
+/// Emit one theme's channels as custom properties.
+@mixin channels($map) {
+  @each $role, $channels in $map {
+    --color-#{$role}: #{$channels};
+  }
+}
+
+/// Light in `:root`, dark behind the media query, and BOTH mirrored under
+/// `html[data-theme]` so an explicit user choice always beats the OS.
+@mixin emit {
+  :root {
+    color-scheme: light;
+    @include channels($light);
+  }
+
+  @media (prefers-color-scheme: dark) {
+    :root {
+      color-scheme: dark;
+      @include channels($dark);
+    }
+  }
+
+  html[data-theme='dark'] {
+    color-scheme: dark;
+    @include channels($dark);
+  }
+
+  html[data-theme='light'] {
+    color-scheme: light;
+    @include channels($light);
+  }
+}
+
+/// `rgb()` wrapper so components never touch the raw channel list.
+@function role($name, $alpha: 1) {
+  @return rgb(var(--color-#{$name}) / #{$alpha});
+}

package/src/tokens/_index.scss

@@ -0,0 +1,13 @@
+// Single entry point for authors: `@use '../tokens' as t;` then `t.role('bg')`,
+// `t.space(4)`, `@include t.focus-ring`. Forwards maps, functions, and mixins —
+// emits no CSS. Global custom properties come from `theme.scss`.
+
+@forward 'breakpoints';
+@forward 'colors' hide emit, channels;
+@forward 'motion' hide emit;
+@forward 'radius' hide emit;
+@forward 'shadow' hide emit, levels;
+@forward 'space' hide emit;
+@forward 'typography' hide emit;
+@forward 'z' hide emit;
+@forward 'mixins';

package/src/tokens/_mixins.scss

@@ -0,0 +1,186 @@
+// Shared authoring primitives. Component modules `@use '../tokens' as t;` and
+// compose from here — nothing in a component stylesheet hardcodes a colour,
+// a physical direction, or a breakpoint value.
+
+@use 'sass:list';
+@use 'sass:map';
+@use 'breakpoints';
+@use 'colors';
+@use 'motion';
+@use 'radius';
+
+/// Keyboard-only focus, drawn from the accent role so it themes automatically.
+@mixin focus-ring($role: 'accent', $width: 2px, $offset: 2px) {
+  &:focus-visible {
+    outline: $width solid colors.role($role);
+    outline-offset: $offset;
+  }
+
+  &:focus:not(:focus-visible) {
+    outline: none;
+  }
+}
+
+/// Removed from the visual flow, still announced by screen readers.
+@mixin visually-hidden {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  margin: -1px;
+  padding: 0;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border: 0;
+}
+
+@mixin truncate {
+  overflow: hidden;
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+@mixin line-clamp($lines: 2) {
+  display: -webkit-box;
+  -webkit-box-orient: vertical;
+  -webkit-line-clamp: $lines;
+  overflow: hidden;
+}
+
+/// Style by the component's own width, not the viewport — the portable default.
+@mixin container-query($name, $min) {
+  @container #{$name} (min-width: #{$min}) {
+    @content;
+  }
+}
+
+/// Declare the element a query container. Pair with `container-query`.
+@mixin container($name) {
+  container-type: inline-size;
+  container-name: $name;
+}
+
+/// Viewport breakpoint, min-width only. Named rungs, never a raw px value.
+@mixin respond-to($bp) {
+  @if not map.has-key(breakpoints.$breakpoints, $bp) {
+    @error 'X_TOKEN_UNKNOWN: breakpoint "#{$bp}" is not in $breakpoints. fix: add it to src/tokens/_breakpoints.scss';
+  }
+
+  @media (min-width: map.get(breakpoints.$breakpoints, $bp)) {
+    @content;
+  }
+}
+
+// --- Logical properties ------------------------------------------------------
+// RTL comes free: authors never write `left`/`right`/`margin-left`, so there is
+// no mirrored stylesheet and no `[dir='rtl']` override anywhere in the package.
+
+@mixin margin-inline($start, $end: $start) {
+  margin-inline-start: $start;
+  margin-inline-end: $end;
+}
+
+@mixin margin-block($start, $end: $start) {
+  margin-block-start: $start;
+  margin-block-end: $end;
+}
+
+@mixin padding-inline($start, $end: $start) {
+  padding-inline-start: $start;
+  padding-inline-end: $end;
+}
+
+@mixin padding-block($start, $end: $start) {
+  padding-block-start: $start;
+  padding-block-end: $end;
+}
+
+@mixin inset-inline($start, $end: $start) {
+  inset-inline-start: $start;
+  inset-inline-end: $end;
+}
+
+@mixin inset-block($start, $end: $start) {
+  inset-block-start: $start;
+  inset-block-end: $end;
+}
+
+@mixin border-inline-start($width: 1px, $role: 'line') {
+  border-inline-start: $width solid colors.role($role);
+}
+
+// --- Composites --------------------------------------------------------------
+
+/// Transition any number of properties on the shared duration + easing.
+@mixin transition($props...) {
+  $list: ();
+  @each $prop in $props {
+    $list: list.append($list, #{$prop} motion.duration(base) motion.easing(out), comma);
+  }
+  transition: $list;
+}
+
+/// Card/sheet/popover background pair. `raised` adds the deeper elevation.
+@mixin surface($level: 'surface', $elevation: 'sm') {
+  background: colors.role($level);
+  border: 1px solid colors.role('line');
+  border-radius: radius.radius(lg);
+  box-shadow: var(--shadow-#{$elevation});
+}
+
+/// Both scrollbar engines, plus no scroll chaining to the page.
+@mixin custom-scrollbar($thumb: 'line', $track: 'bg-soft') {
+  overscroll-behavior: contain;
+  scrollbar-width: thin;
+  scrollbar-color: colors.role($thumb) colors.role($track);
+
+  &::-webkit-scrollbar {
+    width: 10px;
+    height: 10px;
+  }
+
+  &::-webkit-scrollbar-track {
+    background: colors.role($track);
+  }
+
+  &::-webkit-scrollbar-thumb {
+    border: 2px solid transparent;
+    border-radius: radius.radius(pill);
+    background: colors.role($thumb);
+    background-clip: content-box;
+  }
+}
+
+/// Shared shape for every text-ish form control so Input/Textarea/Select match.
+@mixin control {
+  @include focus-ring;
+  @include transition(border-color, box-shadow, background);
+  inline-size: 100%;
+  padding-block: var(--space-2);
+  padding-inline: var(--space-3);
+  border: 1px solid colors.role('line');
+  border-radius: radius.radius(md);
+  background: colors.role('surface-raised');
+  color: colors.role('fg');
+  font: inherit;
+  font-size: var(--text-md);
+
+  &::placeholder {
+    color: colors.role('fg-muted');
+  }
+
+  &:hover:not(:disabled, [aria-disabled='true']) {
+    border-color: colors.role('accent', 0.5);
+  }
+
+  &:disabled,
+  &[aria-disabled='true'] {
+    background: colors.role('bg-soft');
+    color: colors.role('fg-muted');
+    cursor: not-allowed;
+  }
+
+  &[aria-invalid='true'] {
+    border-color: colors.role('danger');
+  }
+}

package/src/tokens/_motion.scss

@@ -0,0 +1,36 @@
+// Durations + easings. Every animated rule ships behind the global
+// `prefers-reduced-motion` guard in `reset.scss`.
+
+$duration: (
+  instant: 0ms,
+  fast: 120ms,
+  base: 220ms,
+  slow: 400ms,
+  slower: 640ms,
+);
+
+$easing: (
+  out: cubic-bezier(0.16, 1, 0.3, 1),
+  in: cubic-bezier(0.5, 0, 0.75, 0),
+  in-out: cubic-bezier(0.65, 0, 0.35, 1),
+  spring: cubic-bezier(0.34, 1.56, 0.64, 1),
+);
+
+@mixin emit {
+  :root {
+    @each $name, $value in $duration {
+      --duration-#{$name}: #{$value};
+    }
+    @each $name, $value in $easing {
+      --easing-#{$name}: #{$value};
+    }
+  }
+}
+
+@function duration($name) {
+  @return var(--duration-#{$name});
+}
+
+@function easing($name) {
+  @return var(--easing-#{$name});
+}

package/src/tokens/_radius.scss

@@ -0,0 +1,23 @@
+// Corner radii. `pill` for chips and switches, `full` for avatars.
+
+$radius: (
+  none: 0,
+  sm: 0.25rem,
+  md: 0.5rem,
+  lg: 0.75rem,
+  xl: 1rem,
+  pill: 999px,
+  full: 50%,
+);
+
+@mixin emit {
+  :root {
+    @each $name, $value in $radius {
+      --radius-#{$name}: #{$value};
+    }
+  }
+}
+
+@function radius($name) {
+  @return var(--radius-#{$name});
+}

package/src/tokens/_shadow.scss

@@ -0,0 +1,49 @@
+// Elevation. Shadows are themed: a light-theme shadow (dark ink, low alpha)
+// is invisible on a dark surface, so dark gets its own deeper, higher-alpha set.
+// Single-layer values on purpose — one string per rung keeps the TS mirror exact.
+
+$shadow-light: (
+  xs: 0 1px 2px rgb(17 15 13 / 0.06),
+  sm: 0 2px 6px rgb(17 15 13 / 0.08),
+  md: 0 4px 14px rgb(17 15 13 / 0.1),
+  lg: 0 12px 32px rgb(17 15 13 / 0.14),
+  xl: 0 24px 56px rgb(17 15 13 / 0.18),
+);
+
+$shadow-dark: (
+  xs: 0 1px 2px rgb(0 0 0 / 0.4),
+  sm: 0 2px 8px rgb(0 0 0 / 0.48),
+  md: 0 6px 20px rgb(0 0 0 / 0.56),
+  lg: 0 16px 40px rgb(0 0 0 / 0.64),
+  xl: 0 28px 64px rgb(0 0 0 / 0.72),
+);
+
+@mixin levels($map) {
+  @each $name, $value in $map {
+    --shadow-#{$name}: #{$value};
+  }
+}
+
+@mixin emit {
+  :root {
+    @include levels($shadow-light);
+  }
+
+  @media (prefers-color-scheme: dark) {
+    :root {
+      @include levels($shadow-dark);
+    }
+  }
+
+  html[data-theme='dark'] {
+    @include levels($shadow-dark);
+  }
+
+  html[data-theme='light'] {
+    @include levels($shadow-light);
+  }
+}
+
+@function shadow($name) {
+  @return var(--shadow-#{$name});
+}

package/src/tokens/_space.scss

@@ -0,0 +1,28 @@
+// Spacing scale on a 4px base. Applied through logical properties only
+// (see `_mixins.scss`) so RTL needs no mirrored stylesheet.
+
+$space: (
+  0: 0,
+  1: 0.25rem,
+  2: 0.5rem,
+  3: 0.75rem,
+  4: 1rem,
+  5: 1.25rem,
+  6: 1.5rem,
+  8: 2rem,
+  10: 2.5rem,
+  12: 3rem,
+  16: 4rem,
+);
+
+@mixin emit {
+  :root {
+    @each $step, $value in $space {
+      --space-#{$step}: #{$value};
+    }
+  }
+}
+
+@function space($step) {
+  @return var(--space-#{$step});
+}

package/src/tokens/_typography.scss

@@ -0,0 +1,83 @@
+// Fluid type scale. Every step is a `clamp()` so there is no breakpoint step
+// change and no `font-size` media query anywhere in the design system.
+
+$font-family: (
+  sans: (
+    system-ui,
+    -apple-system,
+    'Segoe UI',
+    Roboto,
+    'Helvetica Neue',
+    sans-serif,
+  ),
+  mono: (
+    ui-monospace,
+    'SFMono-Regular',
+    'JetBrains Mono',
+    Menlo,
+    Consolas,
+    monospace,
+  ),
+);
+
+$font-size: (
+  xs: clamp(0.75rem, 0.73rem + 0.1vw, 0.8125rem),
+  sm: clamp(0.875rem, 0.85rem + 0.15vw, 0.9375rem),
+  md: clamp(1rem, 0.96rem + 0.2vw, 1.0625rem),
+  lg: clamp(1.125rem, 1.05rem + 0.35vw, 1.25rem),
+  xl: clamp(1.375rem, 1.2rem + 0.7vw, 1.75rem),
+  2xl: clamp(1.75rem, 1.4rem + 1.4vw, 2.5rem),
+  3xl: clamp(2.25rem, 1.6rem + 2.6vw, 3.5rem),
+);
+
+$font-weight: (
+  normal: 400,
+  medium: 500,
+  semibold: 600,
+  bold: 700,
+);
+
+$line-height: (
+  tight: 1.2,
+  snug: 1.35,
+  normal: 1.55,
+  loose: 1.75,
+);
+
+$letter-spacing: (
+  tight: -0.015em,
+  normal: 0,
+  wide: 0.04em,
+);
+
+@mixin emit {
+  :root {
+    @each $name, $stack in $font-family {
+      --font-#{$name}: #{$stack};
+    }
+    @each $name, $value in $font-size {
+      --text-#{$name}: #{$value};
+    }
+    @each $name, $value in $font-weight {
+      --weight-#{$name}: #{$value};
+    }
+    @each $name, $value in $line-height {
+      --leading-#{$name}: #{$value};
+    }
+    @each $name, $value in $letter-spacing {
+      --tracking-#{$name}: #{$value};
+    }
+  }
+}
+
+@function text($name) {
+  @return var(--text-#{$name});
+}
+
+@function weight($name) {
+  @return var(--weight-#{$name});
+}
+
+@function leading($name) {
+  @return var(--leading-#{$name});
+}

package/src/tokens/_z.scss

@@ -0,0 +1,27 @@
+// Named z-index ladder. A magic number in a component is a review failure —
+// add a rung here instead.
+
+$z: (
+  base: 0,
+  raised: 10,
+  sticky: 100,
+  dropdown: 200,
+  drawer: 300,
+  dialog: 400,
+  popover: 500,
+  tooltip: 600,
+  toast: 700,
+  skip-nav: 800,
+);
+
+@mixin emit {
+  :root {
+    @each $name, $value in $z {
+      --z-#{$name}: #{$value};
+    }
+  }
+}
+
+@function z($name) {
+  @return var(--z-#{$name});
+}