@usefragments/ui 1.0.0

package/src/styles/globals.scss

@@ -0,0 +1,207 @@
+// ============================================
+// @usefragments/ui Global Styles
+// ============================================
+// Import this file once in your app to set up CSS custom properties
+// for theming, plus base element resets for consistent rendering.
+//
+// Usage in SCSS (recommended):
+//   @use '@usefragments/ui/styles' with (
+//     $fui-brand: #6366f1,
+//     $fui-neutral: "earth",
+//     $fui-radius-style: "rounded"
+//   );
+//
+// Or without customization:
+//   @use '@usefragments/ui/styles';
+//
+// Or as a plain import (no seed customization):
+//   import '@usefragments/ui/styles/globals.scss';
+// ============================================
+
+// --------------------------------------------
+// Configurable Seed Variables
+// --------------------------------------------
+// Consumers set these via @use ... with().
+// Values are forwarded to the seed/token chain below.
+
+$fui-brand: #18181b !default;
+$fui-neutral: "stone" !default;
+$fui-density: "default" !default;
+$fui-radius-style: "default" !default;
+$fui-danger: #ef4444 !default;
+$fui-success: #22c55e !default;
+$fui-warning: #f59e0b !default;
+$fui-info: #3b82f6 !default;
+
+// Configure seeds BEFORE loading variables.
+// Sass module singleton: once configured here, every subsequent
+// @use 'seeds' (in _computed.scss, etc.) gets this instance.
+@use "../tokens/seeds" with (
+  $fui-brand: $fui-brand,
+  $fui-neutral: $fui-neutral,
+  $fui-density: $fui-density,
+  $fui-radius-style: $fui-radius-style,
+  $fui-danger: $fui-danger,
+  $fui-success: $fui-success,
+  $fui-warning: $fui-warning,
+  $fui-info: $fui-info
+);
+
+@use "../tokens/variables" as *;
+@use "../tokens/property-registrations" as prop-reg;
+
+// ============================================
+// Cascade Layer Order Declaration
+// ============================================
+// Establishes the priority order for the cascade.
+// Consumer styles outside any @layer always win over layered styles.
+// Within layers: tokens < base < components (declared first = lowest priority).
+// Browser support: ~97% (Chrome 99+, Firefox 97+, Safari 15.4+)
+@layer fui.tokens, fui.base;
+
+// Output typed @property registrations (must be top-level, can't be in @layer)
+@include prop-reg.fui-property-registrations;
+
+// ============================================
+// Tokens Layer — CSS custom properties & theming
+// ============================================
+
+@layer fui.tokens {
+  @include fui-css-variables;
+}
+
+// ============================================
+// Base Layer — Resets & defaults
+// ============================================
+// Uses :where() for zero-specificity resets where possible.
+// Any consumer selector overrides these without specificity fighting.
+
+@layer fui.base {
+  // Box-Sizing Reset
+  :where(*, *::before, *::after) {
+    box-sizing: border-box;
+  }
+
+  // Base Element Resets
+  // Use real specificity (not :where()) for font-size so it overrides
+  // the browser default 16px. This makes 1rem = 14px throughout.
+  html {
+    font-size: #{$fui-base-font-size};
+    scroll-behavior: smooth;
+  }
+
+  :where(body) {
+    margin: 0;
+    font-size: inherit;
+    font-family: var(
+      --fui-font-sans,
+      Inter,
+      system-ui,
+      -apple-system,
+      BlinkMacSystemFont,
+      "Segoe UI",
+      sans-serif
+    );
+    line-height: var(--fui-line-height-normal, $fui-line-height-normal);
+    background-color: var(--fui-body-bg, #{$fui-body-bg});
+    color: var(--fui-text-primary, #171717);
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+    font-feature-settings:
+      "rlig" 1,
+      "calt" 1;
+  }
+
+  // Global link defaults.
+  // Classed or inline-styled anchors (e.g., those wrapping a <Button>) get the
+  // bare reset — text-decoration: none, color inherited — so consumers style
+  // them without specificity fighting. Naked <a> tags in prose (no className,
+  // no inline style) get the accent color + underline so they look intentional
+  // instead of falling back to the browser's blue/purple defaults.
+  :where(a) {
+    text-decoration: none;
+    color: inherit;
+  }
+
+  :where(a:not([class]):not([style])) {
+    color: var(--fui-color-accent, #{$fui-color-accent});
+    text-decoration: underline;
+    text-underline-offset: 2px;
+    transition: color 0.15s ease;
+
+    &:hover {
+      color: var(--fui-color-accent-hover, #{$fui-color-accent-hover});
+    }
+  }
+
+  ::selection {
+    background-color: var(
+      --fui-selection-bg,
+      color-mix(in srgb, var(--fui-button-primary-base, #0a84ff) 18%, transparent)
+    );
+    color: var(--fui-selection-color, var(--fui-text-primary, #171717));
+  }
+
+  // Scrollbar Styles — transparent by default, visible on hover of the
+  // scrollable element. Mirrors macOS overlay-scrollbar behaviour so
+  // content reads cleanly at rest.
+  ::-webkit-scrollbar {
+    width: 6px;
+    height: 6px;
+  }
+
+  ::-webkit-scrollbar-track {
+    background-color: transparent;
+  }
+
+  ::-webkit-scrollbar-thumb {
+    background-color: transparent;
+    border-radius: 9999px;
+    transition: background-color var(--fui-transition-fast, $fui-transition-fast);
+  }
+
+  // Reveal thumb when the scrollable element (or any ancestor) is hovered.
+  // :hover bubbles up the tree, so hovering a child of a scroll container
+  // still triggers the container's thumb to appear.
+  :where(*:hover)::-webkit-scrollbar-thumb {
+    background-color: var(--fui-text-tertiary, #8a8a8a);
+  }
+
+  ::-webkit-scrollbar-thumb:hover {
+    background-color: var(--fui-text-secondary, #525252);
+  }
+
+  // Firefox scrollbar — hidden at rest, shown on hover.
+  :where(*) {
+    scrollbar-width: thin;
+    scrollbar-color: transparent transparent;
+  }
+
+  :where(*:hover) {
+    scrollbar-color: var(--fui-text-tertiary, #8a8a8a) transparent;
+  }
+
+  // Accessibility: Reduced Motion
+  @media (prefers-reduced-motion: reduce) {
+    :where(*, *::before, *::after) {
+      animation-duration: 0.01ms !important;
+      animation-iteration-count: 1 !important;
+      transition-duration: 0.01ms !important;
+      scroll-behavior: auto !important;
+    }
+  }
+
+  // Accessibility: Focus Visible
+  :where(:focus:not(:focus-visible)) {
+    outline: none;
+  }
+
+  :where(:focus-visible) {
+    outline: 1px solid color-mix(in srgb, var(--fui-focus-ring-color, #18181b) 24%, transparent);
+    outline-offset: var(--fui-focus-ring-offset, 2px);
+    box-shadow:
+      0 0 0 calc(var(--fui-focus-ring-width, 2px) + 1px)
+        color-mix(in srgb, var(--fui-focus-ring-color, #18181b) 10%, transparent),
+      0 10px 24px -16px color-mix(in srgb, var(--fui-focus-ring-color, #18181b) 18%, transparent);
+  }
+}

package/src/tokens/_computed.scss

@@ -0,0 +1,225 @@
+// ============================================
+// @usefragments/ui Computed Tokens
+// ============================================
+//
+// This module imports seed values and derivation functions,
+// then computes all token values. These computed values are
+// used as fallbacks in _variables.scss for backward compatibility.
+//
+// ============================================
+
+@use "sass:map";
+@use "seeds" as seeds;
+@use "palettes" as palettes;
+@use "density" as density;
+@use "radius" as radius;
+@use "derive" as derive;
+
+// --------------------------------------------
+// Resolve Seed Values
+// --------------------------------------------
+
+// Get the selected configurations
+$_palette: palettes.get-palette(seeds.$fui-neutral);
+$_density: density.get-density(seeds.$fui-density);
+$_radius: radius.get-radius-style(seeds.$fui-radius-style);
+
+// Derive spacing from density
+$_spacing: density.derive-spacing($_density);
+
+// --------------------------------------------
+// Computed: Base Configuration
+// --------------------------------------------
+
+$computed-base-font-size: map.get($_density, base-font-size);
+$computed-base-unit: map.get($_density, base-unit);
+
+// --------------------------------------------
+// Computed: Spacing
+// --------------------------------------------
+
+$computed-space-px: map.get($_spacing, px);
+$computed-space-0-5: map.get($_spacing, 0-5);
+$computed-space-0-75: map.get($_spacing, 0-75);
+$computed-space-1: map.get($_spacing, 1);
+$computed-space-2: map.get($_spacing, 2);
+$computed-space-3: map.get($_spacing, 3);
+$computed-space-4: map.get($_spacing, 4);
+$computed-space-5: map.get($_spacing, 5);
+$computed-space-6: map.get($_spacing, 6);
+$computed-space-8: map.get($_spacing, 8);
+$computed-space-10: map.get($_spacing, 10);
+$computed-space-12: map.get($_spacing, 12);
+
+// --------------------------------------------
+// Computed: Border Radius
+// --------------------------------------------
+
+$computed-radius-sm: radius.radius-value($_radius, sm);
+$computed-radius-md: radius.radius-value($_radius, md);
+$computed-radius-lg: radius.radius-value($_radius, lg);
+$computed-radius-xl: radius.radius-value($_radius, xl);
+$computed-radius-full: radius.radius-full();
+
+// --------------------------------------------
+// Computed: Component Heights (from density)
+// --------------------------------------------
+
+$computed-button-height-xs: density.px-to-rem($_density, map.get($_density, button-height-xs));
+$computed-button-height-sm: density.px-to-rem($_density, map.get($_density, button-height-sm));
+$computed-button-height-md: density.px-to-rem($_density, map.get($_density, button-height-md));
+$computed-button-height-lg: density.px-to-rem($_density, map.get($_density, button-height-lg));
+
+$computed-input-height: density.px-to-rem($_density, map.get($_density, input-height));
+$computed-input-height-sm: density.px-to-rem($_density, map.get($_density, input-height-sm));
+$computed-input-height-lg: density.px-to-rem($_density, map.get($_density, input-height-lg));
+
+$computed-touch-sm: density.px-to-rem($_density, map.get($_density, touch-sm));
+$computed-touch-md: density.px-to-rem($_density, map.get($_density, touch-md));
+$computed-touch-lg: density.px-to-rem($_density, map.get($_density, touch-lg));
+
+// Sidebar navigation (from density)
+$computed-sidebar-item-height: density.px-to-rem($_density, map.get($_density, sidebar-item-height));
+
+// --------------------------------------------
+// Computed: Colors - Light Mode
+// --------------------------------------------
+
+// Accent colors (from brand seed)
+$computed-color-accent: seeds.$fui-brand;
+$computed-color-on-accent: derive.contrast-color(seeds.$fui-brand);
+$computed-color-accent-hover: derive.derive-accent-hover(seeds.$fui-brand, false);
+$computed-color-accent-active: derive.derive-accent-active(seeds.$fui-brand, false);
+
+// Semantic colors (from seeds or defaults)
+$computed-color-danger: seeds.$fui-danger;
+$computed-color-danger-hover: derive.derive-semantic-hover(seeds.$fui-danger);
+$computed-color-success: seeds.$fui-success;
+$computed-color-warning: seeds.$fui-warning;
+$computed-color-info: seeds.$fui-info;
+
+// Semantic backgrounds
+$computed-color-danger-bg: derive.derive-semantic-bg(seeds.$fui-danger, false);
+$computed-color-success-bg: derive.derive-semantic-bg(seeds.$fui-success, false);
+$computed-color-warning-bg: derive.derive-semantic-bg(seeds.$fui-warning, false);
+$computed-color-info-bg: derive.derive-semantic-bg(seeds.$fui-info, false);
+
+// Semantic text colors (WCAG AA contrast-safe for text on semantic backgrounds)
+$computed-color-danger-text: derive.derive-semantic-text(seeds.$fui-danger, false);
+$computed-color-success-text: derive.derive-semantic-text(seeds.$fui-success, false);
+$computed-color-warning-text: derive.derive-semantic-text(seeds.$fui-warning, false);
+$computed-color-info-text: derive.derive-semantic-text(seeds.$fui-info, false);
+
+// Surfaces (from neutral palette)
+$_surfaces-light: derive.derive-surfaces($_palette, false, seeds.$fui-neutral);
+$computed-bg-primary: map.get($_surfaces-light, primary);
+$computed-bg-secondary: map.get($_surfaces-light, secondary);
+$computed-bg-tertiary: map.get($_surfaces-light, tertiary);
+$computed-bg-elevated: map.get($_surfaces-light, elevated);
+$computed-bg-subtle: map.get($_surfaces-light, subtle);
+$computed-bg-hover: map.get($_surfaces-light, hover);
+$computed-bg-active: map.get($_surfaces-light, active);
+
+// App/document surfaces
+$_app-surfaces-light: derive.derive-app-surfaces($_palette, false, seeds.$fui-neutral);
+$computed-body-bg: map.get($_app-surfaces-light, body);
+$computed-main-bg: map.get($_app-surfaces-light, main);
+
+// Text (from neutral palette)
+$_text-light: derive.derive-text($_palette, false, seeds.$fui-neutral);
+$computed-text-primary: map.get($_text-light, primary);
+$computed-text-secondary: map.get($_text-light, secondary);
+$computed-text-tertiary: map.get($_text-light, tertiary);
+$computed-text-inverse: map.get($_text-light, inverse);
+
+// Borders (from neutral palette)
+$_borders-light: derive.derive-borders($_palette, false, seeds.$fui-neutral);
+$computed-border: map.get($_borders-light, default);
+$computed-border-default: map.get($_borders-light, default);
+$computed-border-strong: map.get($_borders-light, strong);
+
+// Shadows
+$_shadows-light: derive.derive-shadows(false);
+$computed-shadow-sm: map.get($_shadows-light, sm);
+$computed-shadow-md: map.get($_shadows-light, md);
+$computed-shadow-lg: map.get($_shadows-light, lg);
+
+// Focus ring
+$computed-focus-ring-color: derive.derive-focus-ring(seeds.$fui-brand, false);
+
+// Scrollbar
+$_scrollbar-light: derive.derive-scrollbar($_palette, false);
+$computed-scrollbar-track: map.get($_scrollbar-light, track);
+$computed-scrollbar-thumb: map.get($_scrollbar-light, thumb);
+$computed-scrollbar-thumb-hover: map.get($_scrollbar-light, thumb-hover);
+
+// Backdrop
+$computed-backdrop: derive.derive-backdrop(false);
+
+// --------------------------------------------
+// Computed: Colors - Dark Mode
+// --------------------------------------------
+
+// Accent colors — dark brands lightened for visibility; on-accent handles text contrast
+$computed-dark-color-accent: derive.derive-dark-accent(seeds.$fui-brand);
+$computed-dark-color-on-accent: derive.contrast-color($computed-dark-color-accent);
+$computed-dark-color-accent-hover: derive.derive-accent-hover($computed-dark-color-accent, true);
+$computed-dark-color-accent-active: derive.derive-accent-active($computed-dark-color-accent, true);
+
+// Semantic backgrounds (dark mode)
+$computed-dark-color-danger-bg: derive.derive-semantic-bg(seeds.$fui-danger, true);
+$computed-dark-color-success-bg: derive.derive-semantic-bg(seeds.$fui-success, true);
+$computed-dark-color-warning-bg: derive.derive-semantic-bg(seeds.$fui-warning, true);
+$computed-dark-color-info-bg: derive.derive-semantic-bg(seeds.$fui-info, true);
+
+// Semantic text colors (dark mode, WCAG AA contrast-safe)
+$computed-dark-color-danger-text: derive.derive-semantic-text(seeds.$fui-danger, true);
+$computed-dark-color-success-text: derive.derive-semantic-text(seeds.$fui-success, true);
+$computed-dark-color-warning-text: derive.derive-semantic-text(seeds.$fui-warning, true);
+$computed-dark-color-info-text: derive.derive-semantic-text(seeds.$fui-info, true);
+
+// Surfaces (dark mode)
+$_surfaces-dark: derive.derive-surfaces($_palette, true, seeds.$fui-neutral);
+$computed-dark-bg-primary: map.get($_surfaces-dark, primary);
+$computed-dark-bg-secondary: map.get($_surfaces-dark, secondary);
+$computed-dark-bg-tertiary: map.get($_surfaces-dark, tertiary);
+$computed-dark-bg-elevated: map.get($_surfaces-dark, elevated);
+$computed-dark-bg-subtle: map.get($_surfaces-dark, subtle);
+$computed-dark-bg-hover: map.get($_surfaces-dark, hover);
+$computed-dark-bg-active: map.get($_surfaces-dark, active);
+
+// App/document surfaces (dark mode)
+$_app-surfaces-dark: derive.derive-app-surfaces($_palette, true, seeds.$fui-neutral);
+$computed-dark-body-bg: map.get($_app-surfaces-dark, body);
+$computed-dark-main-bg: map.get($_app-surfaces-dark, main);
+
+// Text (dark mode)
+$_text-dark: derive.derive-text($_palette, true, seeds.$fui-neutral);
+$computed-dark-text-primary: map.get($_text-dark, primary);
+$computed-dark-text-secondary: map.get($_text-dark, secondary);
+$computed-dark-text-tertiary: map.get($_text-dark, tertiary);
+$computed-dark-text-inverse: map.get($_text-dark, inverse);
+
+// Borders (dark mode)
+$_borders-dark: derive.derive-borders($_palette, true, seeds.$fui-neutral);
+$computed-dark-border: map.get($_borders-dark, default);
+$computed-dark-border-default: map.get($_borders-dark, default);
+$computed-dark-border-strong: map.get($_borders-dark, strong);
+
+// Shadows (dark mode)
+$_shadows-dark: derive.derive-shadows(true);
+$computed-dark-shadow-sm: map.get($_shadows-dark, sm);
+$computed-dark-shadow-md: map.get($_shadows-dark, md);
+$computed-dark-shadow-lg: map.get($_shadows-dark, lg);
+
+// Focus ring (dark mode)
+$computed-dark-focus-ring-color: derive.derive-focus-ring(seeds.$fui-brand, true);
+
+// Scrollbar (dark mode)
+$_scrollbar-dark: derive.derive-scrollbar($_palette, true);
+$computed-dark-scrollbar-track: map.get($_scrollbar-dark, track);
+$computed-dark-scrollbar-thumb: map.get($_scrollbar-dark, thumb);
+$computed-dark-scrollbar-thumb-hover: map.get($_scrollbar-dark, thumb-hover);
+
+// Backdrop (dark mode)
+$computed-dark-backdrop: derive.derive-backdrop(true);

package/src/tokens/_density.scss

@@ -0,0 +1,176 @@
+// ============================================
+// @usefragments/ui Density Scales
+// ============================================
+//
+// Defines 3 density presets that control spacing and sizing.
+// Each preset uses a different base unit to scale all spacing.
+//
+// ============================================
+
+@use "sass:math";
+@use "sass:map";
+
+// --------------------------------------------
+// Density Definitions
+// --------------------------------------------
+// Each density includes:
+// - base-unit: The fundamental spacing unit
+// - multipliers: Scale factors for spacing tokens
+
+$density-compact: (
+  base-unit: 6px,
+  base-font-size: 14px,
+  // Button heights (compact, with a 32px interactive floor)
+  button-height-xs: 32px,
+  button-height-sm: 32px,
+  button-height-md: 32px,
+  button-height-lg: 36px,
+  // 6 units
+  // Input height
+  input-height: 32px,
+  input-height-sm: 32px,
+  input-height-lg: 36px,
+  // 6 units
+  // Touch targets
+  touch-sm: 32px,
+  touch-md: 32px,
+  touch-lg: 40px,
+  // Sidebar navigation
+  sidebar-item-height: 32px,
+);
+
+$density-default: (
+  base-unit: 7px,
+  base-font-size: 14px,
+  // Button heights align with field heights at each size
+  button-height-xs: 32px,
+  button-height-sm: 32px,
+  button-height-md: 40px,
+  button-height-lg: 44px,
+  // ~6 units
+  // Input height
+  input-height: 40px,
+  // ~6 units
+  input-height-sm: 32px,
+  // ~4.5 units
+  input-height-lg: 44px,
+  // ~6 units
+  // Touch targets (baseline)
+  touch-sm: 32px,
+  touch-md: 32px,
+  touch-lg: 44px,
+  // WCAG AAA recommended
+  // Sidebar navigation
+  sidebar-item-height: 32px,
+);
+
+$density-relaxed: (
+  base-unit: 8px,
+  base-font-size: 14px,
+  // Button heights align with field heights at each size
+  button-height-xs: 32px,
+  button-height-sm: 32px,
+  button-height-md: 44px,
+  button-height-lg: 48px,
+  // 6 units
+  // Input height
+  input-height: 44px,
+  // ~5.5 units
+  input-height-sm: 32px,
+  // 4 units
+  input-height-lg: 48px,
+  // 6 units
+  // Touch targets (proportional from default, not blown out)
+  touch-sm: 32px,
+  touch-md: 40px,
+  touch-lg: 48px,
+  // +9% from default (unchanged)
+  // Sidebar navigation
+  sidebar-item-height: 36px,
+);
+
+// --------------------------------------------
+// Density Map for Dynamic Access
+// --------------------------------------------
+$densities: (
+  "compact": $density-compact,
+  "default": $density-default,
+  "relaxed": $density-relaxed,
+);
+
+// --------------------------------------------
+// Helper Functions
+// --------------------------------------------
+
+/// Get a density configuration by name
+/// @param {String} $name - Density name (compact, default, relaxed)
+/// @return {Map} The density configuration map
+@function get-density($name) {
+  @if not map.has-key($densities, $name) {
+    @warn "Unknown density '#{$name}'. Using 'default' as fallback.";
+    @return $density-default;
+  }
+  @return map.get($densities, $name);
+}
+
+/// Get a specific value from a density configuration
+/// @param {Map} $density - A density configuration map
+/// @param {String} $key - The key to retrieve
+/// @return {*} The value
+@function density-value($density, $key) {
+  @if not map.has-key($density, $key) {
+    @warn "Unknown density key '#{$key}'.";
+    @return null;
+  }
+  @return map.get($density, $key);
+}
+
+/// Derive spacing scale from base unit
+/// Returns a map with spacing tokens
+/// @param {Map} $density - A density configuration map
+/// @return {Map} Spacing tokens
+@function derive-spacing($density) {
+  $base: map.get($density, base-unit);
+  $font-size: map.get($density, base-font-size);
+
+  // Convert to rem based on font size
+  // 1 unit = base-unit / font-size * 1rem
+  $unit-rem: math.div($base, $font-size) * 1rem;
+
+  @return (
+    // Micro spacing (pixel-precise for tiny alignments)
+    px: 1px,
+    0-5: $unit-rem * 0.3,
+    // ~2px for 7px base
+    0-75: $unit-rem * 0.43,
+
+    // ~3px for 7px base
+    // Standard spacing scale
+    1: $unit-rem,
+    // 1 unit
+    2: $unit-rem * 2,
+    // 2 units
+    3: $unit-rem * 3,
+    // 3 units
+    4: $unit-rem * 4,
+    // 4 units
+    5: $unit-rem * 5,
+    // 5 units
+    6: $unit-rem * 6,
+    // 6 units
+    8: $unit-rem * 8,
+    // 8 units
+    10: $unit-rem * 10,
+    // 10 units
+    12: $unit-rem * 12 // 12 units
+  );
+}
+
+/// Convert pixel value to rem based on density
+/// @param {Map} $density - A density configuration map
+/// @param {Number} $px - Pixel value to convert
+/// @return {Number} Value in rem
+@function px-to-rem($density, $px) {
+  $font-size: map.get($density, base-font-size);
+  @return math.div($px, $font-size) * 1rem;
+}