@skewedaspect/sleekspace-ui 0.2.0-beta.1

package/src/styles/tokens/_semantic-surfaces.scss

@@ -0,0 +1,36 @@
+/**
+ * Semantic Tokens - Surfaces
+ *
+ * Background and text colors for surfaces and general use.
+ * These provide a consistent color system independent of component kinds.
+ */
+
+:root
+{
+    /* ===================================================================
+     * Background Colors
+     * For page backgrounds, card surfaces, etc.
+     * =================================================================== */
+
+    --sk-surface-base:    var(--sk-color-gray-90);   /* Main background */
+    --sk-surface-raised:  var(--sk-color-gray-95);   /* Elevated surfaces (cards, panels) */
+    --sk-surface-overlay: var(--sk-color-gray-80);   /* Overlays (modals, dropdowns) */
+
+    /* ===================================================================
+     * Text Colors
+     * For body text, secondary text, disabled text, etc.
+     * =================================================================== */
+
+    --sk-text-primary:   oklch(1 0 0);             /* Primary body text */
+    --sk-text-secondary: var(--sk-color-gray-30);  /* Secondary/muted text */
+    --sk-text-tertiary:  var(--sk-color-gray-50);  /* Tertiary/placeholder text */
+    --sk-text-disabled:  var(--sk-color-gray-60);  /* Disabled text */
+
+    /* ===================================================================
+     * Border Colors
+     * For borders, dividers, etc.
+     * =================================================================== */
+
+    --sk-border-normal: var(--sk-color-gray-70);  /* Standard borders */
+    --sk-border-subtle: var(--sk-color-gray-80);  /* Subtle borders/dividers */
+}

package/src/styles/tokens/index.scss

@@ -0,0 +1,38 @@
+/**
+ * Design Tokens - Main Entry
+ *
+ * This file imports all design token categories in the correct order.
+ * Foundation tokens must be loaded before semantic tokens,
+ * and semantic tokens must be loaded before component tokens.
+ *
+ * Token Hierarchy:
+ *   Foundation → Semantic → Component
+ *
+ * @see DESIGN_TOKENS_PROPOSAL.md for complete documentation
+ */
+
+/* ===================================================================
+ * Foundation Tokens
+ * Global primitives that all other tokens derive from
+ * =================================================================== */
+
+@use 'foundation-colors';
+@use 'foundation-space';
+@use 'foundation-radius';
+@use 'foundation-borders';
+@use 'foundation-shadows';
+@use 'foundation-glow';
+@use 'foundation-transitions';
+@use 'foundation-typography';
+@use 'foundation-scrollbar';
+
+/* ===================================================================
+ * Semantic Tokens
+ * Contextual meanings that reference foundation tokens
+ * =================================================================== */
+
+@use 'semantic-colors';
+@use 'semantic-color-kinds';
+@use 'semantic-surfaces';
+@use 'semantic-interactive';
+@use 'semantic-scrollbar';

package/src/styles/tokens.scss

@@ -0,0 +1,268 @@
+//----------------------------------------------------------------------------------------------------------------------
+// SleekSpace UI - Tokens Only
+//----------------------------------------------------------------------------------------------------------------------
+// This file provides ONLY CSS custom properties (design tokens) without any component styles.
+// Perfect for Tailwind CSS users who want to use SleekSpace tokens with Tailwind utilities.
+//
+// Usage with Tailwind v4:
+//
+// @import "tailwindcss";
+// @import "@skewedaspect/sleekspace-ui/tokens.css";
+//
+// Then use in your templates:
+//   <div class="bg-sk-primary text-sk-primary-text">SleekSpace + Tailwind!</div>
+//   <div class="bg-sk-purple-50 text-white">Neon purple</div>
+//
+// Or with arbitrary values:
+//   <div class="bg-[var(--sk-primary-base)]">Direct CSS variable</div>
+//----------------------------------------------------------------------------------------------------------------------
+
+@use "tokens/index" as tokens-module;
+
+//----------------------------------------------------------------------------------------------------------------------
+// Tailwind v4 Theme Integration
+//----------------------------------------------------------------------------------------------------------------------
+// Map SleekSpace CSS variables to Tailwind's @theme system for standard utilities
+//----------------------------------------------------------------------------------------------------------------------
+
+@theme inline {
+  /* Semantic Colors (theme-aware - change based on SkTheme) */
+  /* Each semantic color gets a full shade range using oklch lightness modifications */
+
+  /* Neutral */
+  --color-sk-neutral: var(--sk-neutral-base);
+  --color-sk-neutral-text: var(--sk-neutral-text);
+  --color-sk-neutral-5: oklch(from var(--sk-neutral-base) 0.95 c h);
+  --color-sk-neutral-10: oklch(from var(--sk-neutral-base) 0.90 c h);
+  --color-sk-neutral-20: oklch(from var(--sk-neutral-base) 0.85 c h);
+  --color-sk-neutral-30: oklch(from var(--sk-neutral-base) 0.80 c h);
+  --color-sk-neutral-40: oklch(from var(--sk-neutral-base) 0.75 c h);
+  --color-sk-neutral-50: var(--sk-neutral-base);
+  --color-sk-neutral-60: oklch(from var(--sk-neutral-base) calc(l * 0.85) c h);
+  --color-sk-neutral-70: oklch(from var(--sk-neutral-base) calc(l * 0.70) c h);
+  --color-sk-neutral-80: oklch(from var(--sk-neutral-base) calc(l * 0.55) c h);
+  --color-sk-neutral-90: oklch(from var(--sk-neutral-base) calc(l * 0.40) c h);
+  --color-sk-neutral-95: oklch(from var(--sk-neutral-base) calc(l * 0.25) c h);
+
+  /* Primary */
+  --color-sk-primary: var(--sk-primary-base);
+  --color-sk-primary-text: var(--sk-primary-text);
+  --color-sk-primary-5: oklch(from var(--sk-primary-base) 0.95 c h);
+  --color-sk-primary-10: oklch(from var(--sk-primary-base) 0.90 c h);
+  --color-sk-primary-20: oklch(from var(--sk-primary-base) 0.85 c h);
+  --color-sk-primary-30: oklch(from var(--sk-primary-base) 0.80 c h);
+  --color-sk-primary-40: oklch(from var(--sk-primary-base) 0.75 c h);
+  --color-sk-primary-50: var(--sk-primary-base);
+  --color-sk-primary-60: oklch(from var(--sk-primary-base) calc(l * 0.85) c h);
+  --color-sk-primary-70: oklch(from var(--sk-primary-base) calc(l * 0.70) c h);
+  --color-sk-primary-80: oklch(from var(--sk-primary-base) calc(l * 0.55) c h);
+  --color-sk-primary-90: oklch(from var(--sk-primary-base) calc(l * 0.40) c h);
+  --color-sk-primary-95: oklch(from var(--sk-primary-base) calc(l * 0.25) c h);
+
+  /* Accent */
+  --color-sk-accent: var(--sk-accent-base);
+  --color-sk-accent-text: var(--sk-accent-text);
+  --color-sk-accent-5: oklch(from var(--sk-accent-base) 0.95 c h);
+  --color-sk-accent-10: oklch(from var(--sk-accent-base) 0.90 c h);
+  --color-sk-accent-20: oklch(from var(--sk-accent-base) 0.85 c h);
+  --color-sk-accent-30: oklch(from var(--sk-accent-base) 0.80 c h);
+  --color-sk-accent-40: oklch(from var(--sk-accent-base) 0.75 c h);
+  --color-sk-accent-50: var(--sk-accent-base);
+  --color-sk-accent-60: oklch(from var(--sk-accent-base) calc(l * 0.85) c h);
+  --color-sk-accent-70: oklch(from var(--sk-accent-base) calc(l * 0.70) c h);
+  --color-sk-accent-80: oklch(from var(--sk-accent-base) calc(l * 0.55) c h);
+  --color-sk-accent-90: oklch(from var(--sk-accent-base) calc(l * 0.40) c h);
+  --color-sk-accent-95: oklch(from var(--sk-accent-base) calc(l * 0.25) c h);
+
+  /* Info */
+  --color-sk-info: var(--sk-info-base);
+  --color-sk-info-text: var(--sk-info-text);
+  --color-sk-info-5: oklch(from var(--sk-info-base) 0.95 c h);
+  --color-sk-info-10: oklch(from var(--sk-info-base) 0.90 c h);
+  --color-sk-info-20: oklch(from var(--sk-info-base) 0.85 c h);
+  --color-sk-info-30: oklch(from var(--sk-info-base) 0.80 c h);
+  --color-sk-info-40: oklch(from var(--sk-info-base) 0.75 c h);
+  --color-sk-info-50: var(--sk-info-base);
+  --color-sk-info-60: oklch(from var(--sk-info-base) calc(l * 0.85) c h);
+  --color-sk-info-70: oklch(from var(--sk-info-base) calc(l * 0.70) c h);
+  --color-sk-info-80: oklch(from var(--sk-info-base) calc(l * 0.55) c h);
+  --color-sk-info-90: oklch(from var(--sk-info-base) calc(l * 0.40) c h);
+  --color-sk-info-95: oklch(from var(--sk-info-base) calc(l * 0.25) c h);
+
+  /* Success */
+  --color-sk-success: var(--sk-success-base);
+  --color-sk-success-text: var(--sk-success-text);
+  --color-sk-success-5: oklch(from var(--sk-success-base) 0.95 c h);
+  --color-sk-success-10: oklch(from var(--sk-success-base) 0.90 c h);
+  --color-sk-success-20: oklch(from var(--sk-success-base) 0.85 c h);
+  --color-sk-success-30: oklch(from var(--sk-success-base) 0.80 c h);
+  --color-sk-success-40: oklch(from var(--sk-success-base) 0.75 c h);
+  --color-sk-success-50: var(--sk-success-base);
+  --color-sk-success-60: oklch(from var(--sk-success-base) calc(l * 0.85) c h);
+  --color-sk-success-70: oklch(from var(--sk-success-base) calc(l * 0.70) c h);
+  --color-sk-success-80: oklch(from var(--sk-success-base) calc(l * 0.55) c h);
+  --color-sk-success-90: oklch(from var(--sk-success-base) calc(l * 0.40) c h);
+  --color-sk-success-95: oklch(from var(--sk-success-base) calc(l * 0.25) c h);
+
+  /* Warning */
+  --color-sk-warning: var(--sk-warning-base);
+  --color-sk-warning-text: var(--sk-warning-text);
+  --color-sk-warning-5: oklch(from var(--sk-warning-base) 0.95 c h);
+  --color-sk-warning-10: oklch(from var(--sk-warning-base) 0.90 c h);
+  --color-sk-warning-20: oklch(from var(--sk-warning-base) 0.85 c h);
+  --color-sk-warning-30: oklch(from var(--sk-warning-base) 0.80 c h);
+  --color-sk-warning-40: oklch(from var(--sk-warning-base) 0.75 c h);
+  --color-sk-warning-50: var(--sk-warning-base);
+  --color-sk-warning-60: oklch(from var(--sk-warning-base) calc(l * 0.85) c h);
+  --color-sk-warning-70: oklch(from var(--sk-warning-base) calc(l * 0.70) c h);
+  --color-sk-warning-80: oklch(from var(--sk-warning-base) calc(l * 0.55) c h);
+  --color-sk-warning-90: oklch(from var(--sk-warning-base) calc(l * 0.40) c h);
+  --color-sk-warning-95: oklch(from var(--sk-warning-base) calc(l * 0.25) c h);
+
+  /* Danger */
+  --color-sk-danger: var(--sk-danger-base);
+  --color-sk-danger-text: var(--sk-danger-text);
+  --color-sk-danger-5: oklch(from var(--sk-danger-base) 0.95 c h);
+  --color-sk-danger-10: oklch(from var(--sk-danger-base) 0.90 c h);
+  --color-sk-danger-20: oklch(from var(--sk-danger-base) 0.85 c h);
+  --color-sk-danger-30: oklch(from var(--sk-danger-base) 0.80 c h);
+  --color-sk-danger-40: oklch(from var(--sk-danger-base) 0.75 c h);
+  --color-sk-danger-50: var(--sk-danger-base);
+  --color-sk-danger-60: oklch(from var(--sk-danger-base) calc(l * 0.85) c h);
+  --color-sk-danger-70: oklch(from var(--sk-danger-base) calc(l * 0.70) c h);
+  --color-sk-danger-80: oklch(from var(--sk-danger-base) calc(l * 0.55) c h);
+  --color-sk-danger-90: oklch(from var(--sk-danger-base) calc(l * 0.40) c h);
+  --color-sk-danger-95: oklch(from var(--sk-danger-base) calc(l * 0.25) c h);
+
+  /* Color Palette - Gray */
+  --color-sk-gray-5: var(--sk-color-gray-05);
+  --color-sk-gray-10: var(--sk-color-gray-10);
+  --color-sk-gray-20: var(--sk-color-gray-20);
+  --color-sk-gray-30: var(--sk-color-gray-30);
+  --color-sk-gray-40: var(--sk-color-gray-40);
+  --color-sk-gray-50: var(--sk-color-gray-50);
+  --color-sk-gray-60: var(--sk-color-gray-60);
+  --color-sk-gray-70: var(--sk-color-gray-70);
+  --color-sk-gray-80: var(--sk-color-gray-80);
+  --color-sk-gray-90: var(--sk-color-gray-90);
+  --color-sk-gray-95: var(--sk-color-gray-95);
+
+  /* Color Palette - Blue */
+  --color-sk-blue-5: var(--sk-color-blue-05);
+  --color-sk-blue-10: var(--sk-color-blue-10);
+  --color-sk-blue-20: var(--sk-color-blue-20);
+  --color-sk-blue-30: var(--sk-color-blue-30);
+  --color-sk-blue-40: var(--sk-color-blue-40);
+  --color-sk-blue-50: var(--sk-color-blue-50);
+  --color-sk-blue-60: var(--sk-color-blue-60);
+  --color-sk-blue-70: var(--sk-color-blue-70);
+  --color-sk-blue-80: var(--sk-color-blue-80);
+  --color-sk-blue-90: var(--sk-color-blue-90);
+  --color-sk-blue-95: var(--sk-color-blue-95);
+
+  /* Color Palette - Red */
+  --color-sk-red-5: var(--sk-color-red-05);
+  --color-sk-red-10: var(--sk-color-red-10);
+  --color-sk-red-20: var(--sk-color-red-20);
+  --color-sk-red-30: var(--sk-color-red-30);
+  --color-sk-red-40: var(--sk-color-red-40);
+  --color-sk-red-50: var(--sk-color-red-50);
+  --color-sk-red-60: var(--sk-color-red-60);
+  --color-sk-red-70: var(--sk-color-red-70);
+  --color-sk-red-80: var(--sk-color-red-80);
+  --color-sk-red-90: var(--sk-color-red-90);
+  --color-sk-red-95: var(--sk-color-red-95);
+
+  /* Color Palette - Orange */
+  --color-sk-orange-5: var(--sk-color-orange-05);
+  --color-sk-orange-10: var(--sk-color-orange-10);
+  --color-sk-orange-20: var(--sk-color-orange-20);
+  --color-sk-orange-30: var(--sk-color-orange-30);
+  --color-sk-orange-40: var(--sk-color-orange-40);
+  --color-sk-orange-50: var(--sk-color-orange-50);
+  --color-sk-orange-60: var(--sk-color-orange-60);
+  --color-sk-orange-70: var(--sk-color-orange-70);
+  --color-sk-orange-80: var(--sk-color-orange-80);
+  --color-sk-orange-90: var(--sk-color-orange-90);
+  --color-sk-orange-95: var(--sk-color-orange-95);
+
+  /* Color Palette - Yellow */
+  --color-sk-yellow-5: var(--sk-color-yellow-05);
+  --color-sk-yellow-10: var(--sk-color-yellow-10);
+  --color-sk-yellow-20: var(--sk-color-yellow-20);
+  --color-sk-yellow-30: var(--sk-color-yellow-30);
+  --color-sk-yellow-40: var(--sk-color-yellow-40);
+  --color-sk-yellow-50: var(--sk-color-yellow-50);
+  --color-sk-yellow-60: var(--sk-color-yellow-60);
+  --color-sk-yellow-70: var(--sk-color-yellow-70);
+  --color-sk-yellow-80: var(--sk-color-yellow-80);
+  --color-sk-yellow-90: var(--sk-color-yellow-90);
+  --color-sk-yellow-95: var(--sk-color-yellow-95);
+
+  /* Color Palette - Green */
+  --color-sk-green-5: var(--sk-color-green-05);
+  --color-sk-green-10: var(--sk-color-green-10);
+  --color-sk-green-20: var(--sk-color-green-20);
+  --color-sk-green-30: var(--sk-color-green-30);
+  --color-sk-green-40: var(--sk-color-green-40);
+  --color-sk-green-50: var(--sk-color-green-50);
+  --color-sk-green-60: var(--sk-color-green-60);
+  --color-sk-green-70: var(--sk-color-green-70);
+  --color-sk-green-80: var(--sk-color-green-80);
+  --color-sk-green-90: var(--sk-color-green-90);
+  --color-sk-green-95: var(--sk-color-green-95);
+
+  /* Color Palette - Mint */
+  --color-sk-mint-5: var(--sk-color-mint-05);
+  --color-sk-mint-10: var(--sk-color-mint-10);
+  --color-sk-mint-20: var(--sk-color-mint-20);
+  --color-sk-mint-30: var(--sk-color-mint-30);
+  --color-sk-mint-40: var(--sk-color-mint-40);
+  --color-sk-mint-50: var(--sk-color-mint-50);
+  --color-sk-mint-60: var(--sk-color-mint-60);
+  --color-sk-mint-70: var(--sk-color-mint-70);
+  --color-sk-mint-80: var(--sk-color-mint-80);
+  --color-sk-mint-90: var(--sk-color-mint-90);
+  --color-sk-mint-95: var(--sk-color-mint-95);
+
+  /* Color Palette - Cyan */
+  --color-sk-cyan-5: var(--sk-color-cyan-05);
+  --color-sk-cyan-10: var(--sk-color-cyan-10);
+  --color-sk-cyan-20: var(--sk-color-cyan-20);
+  --color-sk-cyan-30: var(--sk-color-cyan-30);
+  --color-sk-cyan-40: var(--sk-color-cyan-40);
+  --color-sk-cyan-50: var(--sk-color-cyan-50);
+  --color-sk-cyan-60: var(--sk-color-cyan-60);
+  --color-sk-cyan-70: var(--sk-color-cyan-70);
+  --color-sk-cyan-80: var(--sk-color-cyan-80);
+  --color-sk-cyan-90: var(--sk-color-cyan-90);
+  --color-sk-cyan-95: var(--sk-color-cyan-95);
+
+  /* Color Palette - Purple */
+  --color-sk-purple-5: var(--sk-color-purple-05);
+  --color-sk-purple-10: var(--sk-color-purple-10);
+  --color-sk-purple-20: var(--sk-color-purple-20);
+  --color-sk-purple-30: var(--sk-color-purple-30);
+  --color-sk-purple-40: var(--sk-color-purple-40);
+  --color-sk-purple-50: var(--sk-color-purple-50);
+  --color-sk-purple-60: var(--sk-color-purple-60);
+  --color-sk-purple-70: var(--sk-color-purple-70);
+  --color-sk-purple-80: var(--sk-color-purple-80);
+  --color-sk-purple-90: var(--sk-color-purple-90);
+  --color-sk-purple-95: var(--sk-color-purple-95);
+
+  /* Color Palette - Pink */
+  --color-sk-pink-5: var(--sk-color-pink-05);
+  --color-sk-pink-10: var(--sk-color-pink-10);
+  --color-sk-pink-20: var(--sk-color-pink-20);
+  --color-sk-pink-30: var(--sk-color-pink-30);
+  --color-sk-pink-40: var(--sk-color-pink-40);
+  --color-sk-pink-50: var(--sk-color-pink-50);
+  --color-sk-pink-60: var(--sk-color-pink-60);
+  --color-sk-pink-70: var(--sk-color-pink-70);
+  --color-sk-pink-80: var(--sk-color-pink-80);
+  --color-sk-pink-90: var(--sk-color-pink-90);
+  --color-sk-pink-95: var(--sk-color-pink-95);
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/styles/utilities/_index.scss

@@ -0,0 +1,9 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Utilities
+//----------------------------------------------------------------------------------------------------------------------
+// Utility classes for rapid development and common styling patterns
+//----------------------------------------------------------------------------------------------------------------------
+
+@forward 'typography';
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/styles/utilities/_typography.scss

@@ -0,0 +1,121 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Typography Utilities
+// Provides styling for inline code, keyboard shortcuts, and other text elements
+//----------------------------------------------------------------------------------------------------------------------
+
+@use '../theme/variables' as *;
+
+//----------------------------------------------------------------------------------------------------------------------
+// Code and Kbd Base Styles (NO beveled corners - using rounded corners instead)
+//----------------------------------------------------------------------------------------------------------------------
+
+code,
+kbd
+{
+    font-family: var(--sk-font-family-mono);
+    padding: 0.125rem 0.375rem;
+    border-radius: 0.25rem;
+    font-size: 0.875em;
+    line-height: 1;
+
+    // Default neutral styling
+    color: white;
+    background: color-mix(in oklch, var(--sk-neutral-base), black 50%);
+}
+
+kbd
+{
+    // Slightly different style for keyboard keys
+    font-weight: 600;
+    padding: 0.25rem 0.5rem;
+    border: 1px dashed color-mix(in oklch, var(--sk-neutral-base), black 50%);
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+// Code/Kbd Color Kinds
+//----------------------------------------------------------------------------------------------------------------------
+
+@each $kind in $kinds
+{
+    code.sk-#{ "" + $kind },
+    kbd.sk-#{ "" + $kind }
+    {
+        color: var(--sk-#{ $kind }-base);
+        background: color-mix(in oklch, var(--sk-#{ $kind }-base), black 70%);
+    }
+
+    kbd.sk-#{ "" + $kind }
+    {
+        border-color: color-mix(in oklch, var(--sk-#{ $kind }-base), black 50%);
+    }
+}
+
+// Special case for neutral - use white text and lighter background
+code.sk-neutral,
+kbd.sk-neutral
+{
+    color: white;
+    background: color-mix(in oklch, var(--sk-neutral-base), black 50%);
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+// Text Color Utilities
+//----------------------------------------------------------------------------------------------------------------------
+
+@each $kind in $kinds
+{
+    .text-#{ "" + $kind }
+    {
+        color: var(--sk-#{ $kind }-base) !important;
+    }
+
+    .text-#{ "" + $kind }-subtle
+    {
+        color: color-mix(in oklch, var(--sk-#{ $kind }-base), transparent 50%) !important;
+    }
+}
+
+//----------------------------------------------------------------------------------------------------------------------
+// Header Utilities
+//----------------------------------------------------------------------------------------------------------------------
+
+.h1,
+.h2,
+.h3,
+.h4,
+.h5,
+.h6
+{
+    margin-top: 0;
+    margin-bottom: 0.5rem;
+    font-weight: 600;
+    line-height: 1.2;
+}
+
+.h1 { font-size: 2.5rem; }
+.h2 { font-size: 2rem; }
+.h3 { font-size: 1.75rem; }
+.h4 { font-size: 1.5rem; }
+.h5 { font-size: 1.25rem; }
+.h6 { font-size: 1rem; }
+
+//----------------------------------------------------------------------------------------------------------------------
+// Header Underline Utilities
+//----------------------------------------------------------------------------------------------------------------------
+
+@each $kind in $kinds
+{
+    .underline-#{ "" + $kind }
+    {
+        border-bottom: 2px solid var(--sk-#{ $kind }-base);
+        padding-bottom: 0.5rem;
+    }
+
+    .underline-#{ "" + $kind }-subtle
+    {
+        border-bottom: 2px solid color-mix(in oklch, var(--sk-#{ $kind }-base), transparent 50%);
+        padding-bottom: 0.5rem;
+    }
+}
+
+//----------------------------------------------------------------------------------------------------------------------

package/src/types.ts

@@ -0,0 +1,50 @@
+//----------------------------------------------------------------------------------------------------------------------
+// Common Types
+//----------------------------------------------------------------------------------------------------------------------
+
+// Common component sizes
+export type ComponentSize = 'xs' | 'sm' | 'md' | 'lg' | 'xl';
+
+// Semantic kinds (themeable, colors with meaning)
+export type SemanticKind = 'neutral' | 'primary' | 'accent' | 'danger' | 'info' | 'success' | 'warning';
+
+// Color kinds (non-themeable, direct palette access)
+export type ColorKind = 'boulder' | 'neon-blue' | 'light-blue' | 'neon-orange' | 'neon-purple' | 'neon-green'
+    | 'neon-mint' | 'neon-pink' | 'yellow' | 'red';
+
+// All component kinds (semantic + color)
+export type ComponentKind = SemanticKind | ColorKind;
+
+// Common button/interactive variants
+export type ComponentVariant = 'solid' | 'outline' | 'subtle' | 'ghost' | 'link';
+
+//----------------------------------------------------------------------------------------------------------------------
+
+/**
+ * Custom color props interface for components.
+ * Allows overriding component colors with any valid CSS color value.
+ */
+export interface ComponentCustomColors
+{
+    /**
+     * Base color for the component.
+     * Accepts any valid CSS color value including:
+     * - Hex colors: "#8B5CF6"
+     * - OKLCH colors: "oklch(0.7 0.25 300)"
+     * - RGB/HSL: "rgb(139, 92, 246)", "hsl(258, 90%, 66%)"
+     * - CSS variables: "var(--color-neon-green-200)"
+     * - Named colors: "rebeccapurple"
+     *
+     * When provided, this overrides the color from the `kind` prop.
+     */
+    baseColor ?: string;
+
+    /**
+     * Text/foreground color for the component.
+     * If not provided, automatically calculated for optimal contrast with the base color.
+     * Accepts the same CSS color formats as baseColor.
+     */
+    textColor ?: string;
+}
+
+//----------------------------------------------------------------------------------------------------------------------