soltana-ui 0.1.0

package/src/styles/base/_accessibility.scss

@@ -0,0 +1,146 @@
+// ---------------------------------------------------------------------------
+// Accessibility System
+// ---------------------------------------------------------------------------
+// Reduced motion, high contrast, focus styles, skip-link, and
+// screen reader utilities. WCAG 2.1 AA compliance foundation.
+// ---------------------------------------------------------------------------
+
+// ---- Reduced Motion ----
+// Disables animations and transitions for users who prefer reduced motion.
+// !important is intentional: accessibility overrides must win over any
+// component-level animation/transition declarations regardless of specificity.
+@media (prefers-reduced-motion: reduce) {
+  *,
+  *::before,
+  *::after {
+    animation-duration: 0.01ms !important;
+    animation-iteration-count: 1 !important;
+    transition-duration: 0.01ms !important;
+    scroll-behavior: auto !important;
+  }
+}
+
+// ---- High Contrast Mode ----
+// Token-level overrides for users who need stronger contrast.
+@media (prefers-contrast: more) {
+  :root {
+    // Semantic border tokens remapped to decorative accent tokens for WCAG AAA compliance.
+    // Borders shift from neutral UI structure to accent-colored decoration for visibility.
+    --border-default: var(--border-decorative-strong);
+    --border-subtle: var(--border-decorative);
+    --border-strong: var(--accent-decorative);
+
+    // Eliminate translucency and decorative overlays
+    --finish-blur: 0px;
+    --finish-saturation: 100%;
+    --finish-opacity: 1;
+    --finish-overlay: none;
+    --finish-sheen: none;
+    --bridge-backdrop-blur: 0px;
+
+    // Enhanced focus ring
+    --focus-ring-width: 3px;
+
+    // Collapse lower hierarchy into secondary
+    --text-muted: var(--text-secondary);
+    --text-tertiary: var(--text-secondary);
+  }
+}
+
+// ---- Focus Ring Tokens ----
+:root {
+  --focus-ring-color: var(--accent-primary);
+  --focus-ring-width: 2px;
+  --focus-ring-offset: 3px;
+  --focus-ring-shadow: 0 0 0 3px var(--state-focus-ring);
+}
+
+// ---- Focus Ring Mixin ----
+@mixin focus-ring-outline($inset: false) {
+  outline: var(--focus-ring-width) solid var(--focus-ring-color);
+
+  @if $inset {
+    outline-offset: calc(-1 * var(--focus-ring-offset));
+  } @else {
+    outline-offset: var(--focus-ring-offset);
+  }
+}
+
+// ---- Disabled State Mixin ----
+@mixin disabled-state {
+  background: var(--state-disabled-bg);
+  cursor: not-allowed;
+  box-shadow: none;
+  backdrop-filter: none;
+}
+
+// ---- Focus Styles ----
+// Consistent focus ring on all interactive elements via tokens.
+:focus-visible {
+  @include focus-ring-outline;
+}
+
+// Generic focus ring utility
+.focus-ring {
+  &:focus-visible {
+    @include focus-ring-outline;
+  }
+}
+
+.focus-ring-inset {
+  &:focus-visible {
+    @include focus-ring-outline($inset: true);
+  }
+}
+
+// ---- Screen Reader Only ----
+@mixin sr-only-styles {
+  position: absolute;
+  width: 1px;
+  height: 1px;
+  padding: 0;
+  margin: -1px;
+  overflow: hidden;
+  clip-path: inset(50%);
+  white-space: nowrap;
+  border-width: 0;
+}
+
+.sr-only {
+  @include sr-only-styles;
+}
+
+// Focusable screen reader only — becomes visible on focus
+.sr-only-focusable {
+  &:not(:focus, :focus-within) {
+    @include sr-only-styles;
+  }
+}
+
+// ---- Skip Navigation Link ----
+.skip-link {
+  position: absolute;
+  top: -100%;
+  left: 50%;
+  transform: translateX(-50%);
+  z-index: var(--z-skip-link);
+  padding: 0.75rem 1.5rem;
+  font-family: var(--font-sans);
+  font-size: var(--text-sm);
+  font-weight: var(--font-semibold);
+  color: var(--text-inverse);
+  background: var(--accent-primary);
+  border-radius: 0 0 var(--radius-md) var(--radius-md);
+  text-decoration: none;
+  transition: top var(--transition-normal) var(--easing-in-out);
+
+  &:focus {
+    top: 0;
+    @include focus-ring-outline;
+  }
+}
+
+// ---- Live Region ----
+.aria-live-region {
+  @include sr-only-styles;
+}

package/src/styles/base/_index.scss

@@ -0,0 +1,12 @@
+// ---------------------------------------------------------------------------
+// Base Index
+// ---------------------------------------------------------------------------
+// Foundation styles: relief system, typography, and accessibility.
+// ---------------------------------------------------------------------------
+
+@forward 'relief-system';
+@forward 'transitions';
+@forward 'typography';
+@forward 'accessibility';
+@forward 'register';
+@forward 'scrollbar';

package/src/styles/base/_register.scss

@@ -0,0 +1,84 @@
+// ---------------------------------------------------------------------------
+// Tier Registration Mixins
+// ---------------------------------------------------------------------------
+// Emit dual-selector blocks (data-attribute + utility class) for custom tier
+// values from a single @content block.
+// ---------------------------------------------------------------------------
+
+// Theme: [data-theme] + .theme-* selectors (and optionally :root).
+@mixin register-theme($name, $include-root: false) {
+  @if $include-root {
+    :root,
+    [data-theme='#{$name}'],
+    .theme-#{$name} {
+      @content;
+    }
+  } @else {
+    [data-theme='#{$name}'],
+    .theme-#{$name} {
+      @content;
+    }
+  }
+}
+
+// Relief: [data-relief] + .relief-* selectors.
+@mixin register-relief($name) {
+  [data-relief='#{$name}'],
+  .relief-#{$name} {
+    @content;
+  }
+}
+
+// Finish: [data-finish] + .finish-* selectors.
+@mixin register-finish($name) {
+  [data-finish='#{$name}'],
+  .finish-#{$name} {
+    @content;
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Shared Property Mixins
+// ---------------------------------------------------------------------------
+
+@mixin relief-container($shadow: var(--relief-shadow)) {
+  border: 1px solid var(--relief-border);
+  box-shadow: $shadow;
+}
+
+// Applies background with tier composition: consumes --relief-bg (set by active
+// relief tier) with fallback to --surface-1. Finish properties (opacity, blur,
+// overlay, sheen) are applied additively.
+@mixin finish-surface($bg: var(--relief-bg, var(--surface-1)), $gradient: null) {
+  background-color: color-mix(
+    in srgb,
+    #{$bg} calc(var(--relief-opacity, 1) * var(--finish-opacity, 1) * 100%),
+    transparent
+  );
+  @if $gradient {
+    background-image:
+      var(--finish-sheen, none),
+      var(--finish-overlay, none),
+      #{$gradient};
+  } @else {
+    background-image: var(--finish-sheen, none), var(--finish-overlay, none);
+  }
+  backdrop-filter: blur(var(--finish-blur, 0)) saturate(var(--finish-saturation, 100%));
+}
+
+@mixin mask($image, $size: null, $repeat: null, $position: null) {
+  -webkit-mask-image: $image;
+  mask-image: $image;
+  @if $size {
+    -webkit-mask-size: $size;
+    mask-size: $size;
+  }
+  @if $repeat {
+    -webkit-mask-repeat: $repeat;
+    mask-repeat: $repeat;
+  }
+  @if $position {
+    -webkit-mask-position: $position;
+    mask-position: $position;
+  }
+}

package/src/styles/base/_relief-system.scss

@@ -0,0 +1,53 @@
+// ---------------------------------------------------------------------------
+// Relief Bridge Tokens
+// ---------------------------------------------------------------------------
+// Shared defaults via var() indirection — resolve per-element at substitution
+// time, so per-element .theme-* overrides work correctly.
+// Per-theme overrides (--surface-deep, --neu-shadow, --neu-light) live in
+// theme files.
+// Bridge tokens defined here:
+//   --relief-surface-flat, --relief-surface-raised, --relief-surface-deep,
+//   --relief-border-default, --relief-opacity, --glass-opacity, --relief-accent,
+//   --relief-bg, --relief-shadow, --relief-shadow-sm, --relief-shadow-lg,
+//   --relief-shadow-inset, --relief-shadow-inset-sm, --relief-shadow-inset-lg,
+//   --relief-border, --mesh-color-1, --mesh-color-2, --mesh-color-3,
+//   --channel-sheen-color, --channel-tint-color, --bridge-backdrop-blur
+// ---------------------------------------------------------------------------
+
+:root {
+  --relief-surface-flat: var(--surface-1);
+  --relief-surface-raised: var(--surface-2);
+  --relief-surface-deep: var(--surface-deep);
+  --relief-border-default: var(--border-default);
+  --relief-opacity: 1;
+  --glass-opacity: 0.5;
+
+  // Relief property defaults — overridden by each relief selector
+  --relief-bg: var(--relief-surface-flat);
+  --relief-shadow: none;
+  --relief-shadow-sm: none;
+  --relief-shadow-lg: none;
+  --relief-shadow-inset: none;
+  --relief-shadow-inset-sm: none;
+  --relief-shadow-inset-lg: none;
+  --relief-border: var(--relief-border-default);
+
+  // Mesh gradient colors — overridden per-theme for contrast against surfaces
+  --mesh-color-1: var(--accent-primary);
+  --mesh-color-2: var(--accent-secondary);
+  --mesh-color-3: var(--accent-decorative);
+
+  // Relief accent — allows relief-scoped components to reference the active accent
+  --relief-accent: var(--accent-primary);
+
+  // Channel tokens — three-layer indirection pattern:
+  // 1. Themes define channel color values (--highlight-color, --shadow-color)
+  // 2. Relief-system provides fallback defaults via var() references
+  // 3. Finishes consume these tokens for visual effects (tinted overlay, glossy sheen)
+  // This indirection enables per-theme channel tuning while maintaining finish reusability.
+  --channel-sheen-color: var(--highlight-color);
+  --channel-tint-color: var(--shadow-color);
+
+  // Bridge token for backdrop blur — set by finish tier, consumed by relief tier
+  --bridge-backdrop-blur: 0px;
+}

package/src/styles/base/_scrollbar.scss

@@ -0,0 +1,40 @@
+// ---------------------------------------------------------------------------
+// Scrollbar Styling
+// ---------------------------------------------------------------------------
+// Themed scrollbars consuming --scrollbar-thumb and --scrollbar-track tokens
+// from the component-tokens mixin. Uses the standard scrollbar-color
+// property with a WebKit fallback for broader engine coverage.
+// ---------------------------------------------------------------------------
+
+// Standard (Firefox, Chrome 121+)
+// Applied to * so every scrollable container inherits themed scrollbars
+// without requiring per-element opt-in.
+* {
+  scrollbar-color: var(--scrollbar-thumb) var(--scrollbar-track);
+  scrollbar-width: thin;
+}
+
+// WebKit fallback (older Chrome/Safari/Edge)
+::-webkit-scrollbar {
+  width: 8px;
+  height: 8px;
+}
+
+::-webkit-scrollbar-track {
+  background: var(--scrollbar-track);
+}
+
+::-webkit-scrollbar-thumb {
+  background: var(--scrollbar-thumb);
+  border-radius: 4px;
+
+  &:hover {
+    // Falls back to a computed mix when no --scrollbar-thumb-hover token is
+    // provided by the active theme. Themes can override this token to control
+    // the hover intensity explicitly.
+    background: var(
+      --scrollbar-thumb-hover,
+      color-mix(in srgb, var(--text-primary) 20%, transparent)
+    );
+  }
+}

package/src/styles/base/_transitions.scss

@@ -0,0 +1,75 @@
+// ---------------------------------------------------------------------------
+// Transition Mixins
+// ---------------------------------------------------------------------------
+// Standardized transition patterns for interactive components.
+// ---------------------------------------------------------------------------
+
+@mixin transition-interactive($duration: var(--transition-slow)) {
+  transition:
+    background-color $duration var(--easing-in-out),
+    color $duration var(--easing-in-out),
+    border-color $duration var(--easing-in-out),
+    box-shadow $duration var(--easing-in-out),
+    transform var(--transition-normal) var(--easing-in-out);
+}
+
+@mixin transition-depth($duration: var(--transition-slow)) {
+  transition:
+    box-shadow $duration var(--easing-in-out),
+    transform $duration var(--easing-in-out);
+}
+
+@mixin transition-feedback($duration: var(--transition-slow)) {
+  transition:
+    background-color $duration var(--easing-in-out),
+    box-shadow $duration var(--easing-in-out);
+}
+
+@mixin transition-property($prop, $duration: var(--transition-normal)) {
+  transition: $prop $duration var(--easing-in-out);
+}
+
+@mixin hover-state($guard: true) {
+  @if $guard {
+    &:hover:not(:disabled) {
+      background-color: var(--state-hover);
+      @content;
+    }
+  } @else {
+    &:hover {
+      background-color: var(--state-hover);
+      @content;
+    }
+  }
+}
+
+@mixin accent-gradient(
+  $from: var(--accent-primary),
+  $to: var(--accent-decorative),
+  $angle: 145deg
+) {
+  background: linear-gradient($angle, $from, $to);
+}
+
+@mixin hover-lift($distance: -1px) {
+  transform: translateY($distance);
+}
+
+@mixin edge-radius($radius: var(--radius-lg), $child: null) {
+  @if $child {
+    &:first-child #{$child} {
+      border-radius: #{$radius} 0 0 #{$radius};
+    }
+    &:last-child #{$child} {
+      border-radius: 0 #{$radius} #{$radius} 0;
+    }
+  } @else {
+    &:first-child {
+      border-radius: #{$radius} 0 0 #{$radius};
+    }
+
+    &:last-child {
+      border-radius: 0 #{$radius} #{$radius} 0;
+    }
+  }
+}