@usefragments/ui 1.0.0

package/src/tokens/_property-registrations.scss

@@ -0,0 +1,218 @@
+// ============================================
+// @usefragments/ui CSS @property Registrations
+// ============================================
+// Registers typed CSS custom properties via @property.
+// Benefits:
+//   1. Animatable color/length tokens (smooth theme transitions)
+//   2. Typed defaults eliminate need for SCSS fallback long-term
+//   3. Inheritance control prevents token leaking
+// Browser support: ~94% (Chrome 85+, Firefox 128+, Safari 15.4+)
+// https://caniuse.com/mdn-css_at-rules_property
+// Usage: @include fui-property-registrations; (before fui-css-variables)
+// ============================================
+
+@use 'variables' as *;
+
+// ============================================
+// Color Tokens
+// ============================================
+
+@mixin register-color($name, $initial) {
+  @property --fui-#{$name} {
+    syntax: '<color>';
+    initial-value: #{$initial};
+    inherits: true;
+  }
+}
+
+// ============================================
+// Length Tokens
+// ============================================
+
+@mixin register-length($name, $initial) {
+  @property --fui-#{$name} {
+    syntax: '<length>';
+    initial-value: #{$initial};
+    inherits: true;
+  }
+}
+
+// ============================================
+// Number Tokens (unitless: weights, line-heights, z-index)
+// ============================================
+
+@mixin register-number($name, $initial) {
+  @property --fui-#{$name} {
+    syntax: '<number>';
+    initial-value: #{$initial};
+    inherits: true;
+  }
+}
+
+// ============================================
+// Main Registration Mixin
+// ============================================
+
+@mixin fui-property-registrations {
+  // ------------------------------------------
+  // Seed Colors — configurable brand/semantic seeds
+  // Runtime derivation via relative color syntax operates in OKLCH space.
+  // ------------------------------------------
+  @include register-color('seed-brand', $fui-color-accent);
+  @include register-color('seed-danger', $fui-color-danger);
+  @include register-color('seed-success', $fui-color-success);
+  @include register-color('seed-warning', $fui-color-warning);
+  @include register-color('seed-info', $fui-color-info);
+
+  // ------------------------------------------
+  // Colors — Accent (animatable for theme transitions)
+  // ------------------------------------------
+  @include register-color('color-accent', $fui-color-accent);
+  @include register-color('color-accent-hover', $fui-color-accent-hover);
+  @include register-color('color-accent-active', $fui-color-accent-active);
+
+  // ------------------------------------------
+  // Colors — Semantic
+  // ------------------------------------------
+  @include register-color('color-danger', $fui-color-danger);
+  @include register-color('color-danger-hover', $fui-color-danger-hover);
+  @include register-color('color-success', $fui-color-success);
+  @include register-color('color-warning', $fui-color-warning);
+  @include register-color('color-info', $fui-color-info);
+
+  // ------------------------------------------
+  // Colors — Semantic Backgrounds
+  // ------------------------------------------
+  @include register-color('color-danger-bg', $fui-color-danger-bg);
+  @include register-color('color-success-bg', $fui-color-success-bg);
+  @include register-color('color-warning-bg', $fui-color-warning-bg);
+  @include register-color('color-info-bg', $fui-color-info-bg);
+
+  // ------------------------------------------
+  // Colors — Semantic Text
+  // ------------------------------------------
+  @include register-color('color-danger-text', $fui-color-danger-text);
+  @include register-color('color-success-text', $fui-color-success-text);
+  @include register-color('color-warning-text', $fui-color-warning-text);
+  @include register-color('color-info-text', $fui-color-info-text);
+
+  // ------------------------------------------
+  // Colors — Surfaces
+  // ------------------------------------------
+  @include register-color('bg-primary', $fui-bg-primary);
+  @include register-color('bg-secondary', $fui-bg-secondary);
+  @include register-color('bg-tertiary', $fui-bg-tertiary);
+  @include register-color('bg-elevated', $fui-bg-elevated);
+  @include register-color('bg-subtle', $fui-bg-subtle);
+  @include register-color('bg-hover', $fui-bg-hover);
+  @include register-color('bg-active', $fui-bg-active);
+  @include register-color('body-bg', $fui-body-bg);
+  @include register-color('main-bg', $fui-main-bg);
+
+  // ------------------------------------------
+  // Colors — Text
+  // ------------------------------------------
+  @include register-color('text-primary', $fui-text-primary);
+  @include register-color('text-secondary', $fui-text-secondary);
+  @include register-color('text-tertiary', $fui-text-tertiary);
+  @include register-color('text-inverse', $fui-text-inverse);
+
+  // ------------------------------------------
+  // Colors — Borders
+  // ------------------------------------------
+  @include register-color('border', $fui-border);
+  @include register-color('border-default', $fui-border-default);
+  @include register-color('border-strong', $fui-border-strong);
+
+  // ------------------------------------------
+  // Colors — Focus
+  // ------------------------------------------
+  @include register-color('focus-ring-color', $fui-focus-ring-color);
+
+  // ------------------------------------------
+  // Colors — Scrollbar
+  // ------------------------------------------
+  @include register-color('scrollbar-track', $fui-scrollbar-track);
+  @include register-color('scrollbar-thumb', $fui-scrollbar-thumb);
+  @include register-color('scrollbar-thumb-hover', $fui-scrollbar-thumb-hover);
+
+  // ------------------------------------------
+  // Spacing — Lengths
+  // ------------------------------------------
+  @include register-length('space-px', $fui-space-px);
+  @include register-length('space-0-5', $fui-space-0-5);
+  @include register-length('space-0-75', $fui-space-0-75);
+  @include register-length('space-1', $fui-space-1);
+  @include register-length('space-2', $fui-space-2);
+  @include register-length('space-3', $fui-space-3);
+  @include register-length('space-4', $fui-space-4);
+  @include register-length('space-5', $fui-space-5);
+  @include register-length('space-6', $fui-space-6);
+  @include register-length('space-8', $fui-space-8);
+  @include register-length('space-10', $fui-space-10);
+  @include register-length('space-12', $fui-space-12);
+
+  // ------------------------------------------
+  // Border Radius — Lengths
+  // ------------------------------------------
+  @include register-length('radius-sm', $fui-radius-sm);
+  @include register-length('radius-md', $fui-radius-md);
+  @include register-length('radius-lg', $fui-radius-lg);
+  @include register-length('radius-xl', $fui-radius-xl);
+  @include register-length('radius-full', $fui-radius-full);
+
+  // ------------------------------------------
+  // Component Heights — Lengths
+  // ------------------------------------------
+  @include register-length('button-height-xs', $fui-button-height-xs);
+  @include register-length('button-height-sm', $fui-button-height-sm);
+  @include register-length('button-height-md', $fui-button-height-md);
+  @include register-length('button-height-lg', $fui-button-height-lg);
+  @include register-length('input-height', $fui-input-height);
+  @include register-length('input-height-sm', $fui-input-height-sm);
+  @include register-length('input-height-lg', $fui-input-height-lg);
+  @include register-length('target-size-min', $fui-target-size-min);
+
+  // ------------------------------------------
+  // Focus Ring — Lengths
+  // ------------------------------------------
+  @include register-length('focus-ring-offset', $fui-focus-ring-offset);
+  @include register-length('focus-ring-width', $fui-focus-ring-width);
+  @include register-length('scrollbar-width', $fui-scrollbar-width);
+
+  // ------------------------------------------
+  // Typography — Numbers (unitless, animatable)
+  // ------------------------------------------
+  @include register-number('font-weight-normal', $fui-font-weight-normal);
+  @include register-number('font-weight-medium', $fui-font-weight-medium);
+  @include register-number('font-weight-semibold', $fui-font-weight-semibold);
+  @include register-number('font-weight-bold', $fui-font-weight-bold);
+  @include register-number('line-height-tight', $fui-line-height-tight);
+  @include register-number('line-height-normal', $fui-line-height-normal);
+  @include register-number('line-height-relaxed', $fui-line-height-relaxed);
+  @include register-number('line-height-display', $fui-line-height-display);
+  @include register-number('line-height-prose', $fui-line-height-prose);
+
+  // ------------------------------------------
+  // Typography — Font Sizes (lengths)
+  // ------------------------------------------
+  @include register-length('font-size-2xs', $fui-font-size-2xs);
+  @include register-length('font-size-xs', $fui-font-size-xs);
+  @include register-length('font-size-sm', $fui-font-size-sm);
+  @include register-length('font-size-base', $fui-font-size-base);
+  @include register-length('font-size-md', $fui-font-size-md);
+  @include register-length('font-size-lg', $fui-font-size-lg);
+  @include register-length('font-size-xl', $fui-font-size-xl);
+  @include register-length('font-size-2xl', $fui-font-size-2xl);
+  @include register-length('font-size-3xl', $fui-font-size-3xl);
+  @include register-length('font-size-4xl', $fui-font-size-4xl);
+
+  // ------------------------------------------
+  // Note: The following tokens are NOT registered because @property
+  // syntax doesn't support their complex types:
+  //   --fui-font-sans, --fui-font-mono (font family lists)
+  //   --fui-shadow-sm/md/lg (shadow lists)
+  //   --fui-transition-fast/normal (shorthand timing)
+  //   --fui-backdrop, --fui-dark-backdrop (rgba — registered above as <color>)
+  // ------------------------------------------
+}

package/src/tokens/_radius.scss

@@ -0,0 +1,107 @@
+// ============================================
+// @usefragments/ui Radius Styles
+// ============================================
+//
+// Defines 5 radius style presets that control corner rounding.
+// Each style maps to sm, md, lg, xl values.
+//
+// ============================================
+
+@use 'sass:map';
+
+// --------------------------------------------
+// Radius Style Definitions
+// --------------------------------------------
+
+// Sharp - No visible rounding (technical, precise)
+$radius-sharp: (
+  sm: 0,
+  md: 0,
+  lg: 0,
+  xl: 0
+);
+
+// Subtle - Minimal rounding (modern minimal)
+$radius-subtle: (
+  sm: 0.125rem,   // 2px
+  md: 0.25rem,    // 4px
+  lg: 0.375rem,   // 6px
+  xl: 0.5rem      // 8px
+);
+
+// Default - Balanced rounding (current values)
+$radius-default: (
+  sm: 0.25rem,    // 3.5px -> 4px
+  md: 0.429rem,   // 6px
+  lg: 0.571rem,   // 8px
+  xl: 0.857rem    // 12px
+);
+
+// Rounded - More prominent rounding (friendly)
+$radius-rounded: (
+  sm: 0.375rem,   // 6px
+  md: 0.5rem,     // 8px
+  lg: 0.75rem,    // 12px
+  xl: 1rem        // 16px
+);
+
+// Pill - Maximum rounding (playful, soft)
+$radius-pill: (
+  sm: 0.5rem,     // 8px
+  md: 0.75rem,    // 12px
+  lg: 1rem,       // 16px
+  xl: 1.5rem      // 24px
+);
+
+// --------------------------------------------
+// Radius Map for Dynamic Access
+// --------------------------------------------
+$radius-styles: (
+  "sharp": $radius-sharp,
+  "subtle": $radius-subtle,
+  "default": $radius-default,
+  "rounded": $radius-rounded,
+  "pill": $radius-pill
+);
+
+// --------------------------------------------
+// Helper Functions
+// --------------------------------------------
+
+/// Get a radius style configuration by name
+/// @param {String} $name - Radius style name (sharp, subtle, default, rounded, pill)
+/// @return {Map} The radius configuration map
+@function get-radius-style($name) {
+  @if not map.has-key($radius-styles, $name) {
+    @warn "Unknown radius style '#{$name}'. Using 'default' as fallback.";
+    @return $radius-default;
+  }
+  @return map.get($radius-styles, $name);
+}
+
+/// Get a specific radius value from a style
+/// @param {Map} $style - A radius style map
+/// @param {String} $size - Size key (sm, md, lg, xl)
+/// @return {Number} The radius value
+@function radius-value($style, $size) {
+  @if not map.has-key($style, $size) {
+    @warn "Unknown radius size '#{$size}'.";
+    @return map.get($style, md);
+  }
+  @return map.get($style, $size);
+}
+
+/// Get radius by style name and size
+/// @param {String} $style-name - Radius style name
+/// @param {String} $size - Size key (sm, md, lg, xl)
+/// @return {Number} The radius value
+@function radius($style-name, $size) {
+  $style: get-radius-style($style-name);
+  @return radius-value($style, $size);
+}
+
+/// Full/circular radius (always the same)
+/// @return {Number} The full radius value
+@function radius-full() {
+  @return 9999px;
+}

package/src/tokens/_seeds.scss

@@ -0,0 +1,83 @@
+@use 'sass:list';
+
+// ============================================
+// @usefragments/ui Design Token Seeds
+// ============================================
+//
+// User-configurable seed tokens for the design system.
+// Configure via @use ... with() on the styles entry point:
+//
+// Example:
+//   @use '@usefragments/ui/styles' with (
+//     $fui-brand: #0066ff,
+//     $fui-neutral: "ice",
+//     $fui-density: "compact",
+//     $fui-radius-style: "rounded"
+//   );
+//
+// ============================================
+
+// --------------------------------------------
+// Core Seeds
+// --------------------------------------------
+
+/// Primary brand color - derives accent colors, focus rings, etc.
+/// @type Color
+$fui-brand: #18181b !default;
+
+/// Neutral palette name for surfaces, text, and borders
+/// Options: "stone" | "mono" | "ice" | "earth" | "sand" | "fire" | "fragments"
+/// @type String
+$fui-neutral: "stone" !default;
+
+/// Density preset controlling spacing scale
+/// Options: "compact" | "default" | "relaxed"
+/// @type String
+$fui-density: "default" !default;
+
+/// Radius style for borders and corners
+/// Options: "sharp" | "subtle" | "default" | "rounded" | "pill"
+/// @type String
+$fui-radius-style: "default" !default;
+
+// --------------------------------------------
+// Seed Validation
+// --------------------------------------------
+// Fail fast at compile time if invalid seed values are provided.
+
+$_valid-neutrals: "stone", "mono", "ice", "earth", "sand", "fire", "fragments";
+@if not list.index($_valid-neutrals, $fui-neutral) {
+  @error "Invalid $fui-neutral: '#{$fui-neutral}'. Must be one of: #{$_valid-neutrals}";
+}
+
+$_valid-densities: "compact", "default", "relaxed";
+@if not list.index($_valid-densities, $fui-density) {
+  @error "Invalid $fui-density: '#{$fui-density}'. Must be one of: #{$_valid-densities}";
+}
+
+$_valid-radii: "sharp", "subtle", "default", "rounded", "pill";
+@if not list.index($_valid-radii, $fui-radius-style) {
+  @error "Invalid $fui-radius-style: '#{$fui-radius-style}'. Must be one of: #{$_valid-radii}";
+}
+
+// --------------------------------------------
+// Semantic Color Overrides (Optional)
+// --------------------------------------------
+// Override these to customize semantic colors.
+// If not overridden, they use sensible defaults.
+
+/// Danger/error color (defaults to red-500)
+/// @type Color
+$fui-danger: #ef4444 !default;
+
+/// Success color (defaults to green-500)
+/// @type Color
+$fui-success: #22c55e !default;
+
+/// Warning color (defaults to amber-500)
+/// @type Color
+$fui-warning: #f59e0b !default;
+
+/// Info color (defaults to blue-500)
+/// @type Color
+$fui-info: #3b82f6 !default;