@skewedaspect/sleekspace-ui 0.2.0-beta.1

package/src/styles/themes/README.md

@@ -0,0 +1,127 @@
+# SleekSpace UI Themes
+
+This directory contains all theme definitions for the design system. Each theme maps foundation color primitives to semantic color roles (kinds).
+
+## Current Themes
+
+- **Greyscale** (`_greyscale.scss`) - Default theme with gray neutral, blue primary, orange accent
+- **Colorful** (`_colorful.scss`) - Vibrant theme with blue neutral, orange primary, blue accent
+
+## Adding a New Theme
+
+To create a new theme:
+
+1. **Create a new theme file** in this directory: `_mytheme.scss`
+
+2. **Define the theme** using the `[data-scheme="mytheme"]` selector:
+
+```scss
+/**
+ * My Theme
+ *
+ * Description of your theme's color personality.
+ */
+
+[data-scheme="mytheme"]
+{
+    /* Neutral Kind - Used for default UI elements */
+    --sk-neutral-base: var(--sk-color-gray-50);
+    --sk-neutral-hover: color-mix(in oklch, var(--sk-neutral-base), var(--sk-color-gray-10) var(--sk-mix-amount-moderate));
+    --sk-neutral-active: color-mix(in oklch, var(--sk-neutral-base), var(--sk-color-gray-10) var(--sk-mix-amount-strong));
+    --sk-neutral-text: oklch(1 0 0);
+    --sk-neutral-text-contrast: var(--sk-color-gray-95);
+
+    /* Primary Kind - Main brand color for primary actions */
+    --sk-primary-base: var(--sk-color-blue-50);
+    --sk-primary-hover: color-mix(in oklch, var(--sk-primary-base), var(--sk-color-gray-10) var(--sk-mix-amount-moderate));
+    --sk-primary-active: color-mix(in oklch, var(--sk-primary-base), var(--sk-color-gray-10) var(--sk-mix-amount-strong));
+    --sk-primary-text: oklch(1 0 0);
+    --sk-primary-text-contrast: var(--sk-color-gray-95);
+
+    /* Accent Kind - Secondary emphasis */
+    --sk-accent-base: var(--sk-color-orange-50);
+    --sk-accent-hover: color-mix(in oklch, var(--sk-accent-base), var(--sk-color-gray-10) var(--sk-mix-amount-moderate));
+    --sk-accent-active: color-mix(in oklch, var(--sk-accent-base), var(--sk-color-gray-10) var(--sk-mix-amount-strong));
+    --sk-accent-text: oklch(1 0 0);
+    --sk-accent-text-contrast: var(--sk-color-gray-95);
+
+    /* Success Kind - Success states and positive actions */
+    --sk-success-base: var(--sk-color-green-50);
+    --sk-success-hover: color-mix(in oklch, var(--sk-success-base), var(--sk-color-gray-10) var(--sk-mix-amount-moderate));
+    --sk-success-active: color-mix(in oklch, var(--sk-success-base), var(--sk-color-gray-10) var(--sk-mix-amount-strong));
+    --sk-success-text: oklch(1 0 0);
+    --sk-success-text-contrast: var(--sk-color-gray-95);
+
+    /* Warning Kind - Warning states and caution */
+    --sk-warning-base: var(--sk-color-yellow-50);
+    --sk-warning-hover: color-mix(in oklch, var(--sk-warning-base), var(--sk-color-gray-10) var(--sk-mix-amount-moderate));
+    --sk-warning-active: color-mix(in oklch, var(--sk-warning-base), var(--sk-color-gray-10) var(--sk-mix-amount-strong));
+    --sk-warning-text: oklch(1 0 0);
+    --sk-warning-text-contrast: var(--sk-color-gray-95);
+
+    /* Danger Kind - Error states and destructive actions */
+    --sk-danger-base: var(--sk-color-red-50);
+    --sk-danger-hover: color-mix(in oklch, var(--sk-danger-base), var(--sk-color-gray-10) var(--sk-mix-amount-moderate));
+    --sk-danger-active: color-mix(in oklch, var(--sk-danger-base), var(--sk-color-gray-10) var(--sk-mix-amount-strong));
+    --sk-danger-text: oklch(1 0 0);
+    --sk-danger-text-contrast: var(--sk-color-gray-95);
+
+    /* Info Kind - Informational content */
+    --sk-info-base: var(--sk-color-cyan-50);
+    --sk-info-hover: color-mix(in oklch, var(--sk-info-base), var(--sk-color-gray-10) var(--sk-mix-amount-moderate));
+    --sk-info-active: color-mix(in oklch, var(--sk-info-base), var(--sk-color-gray-10) var(--sk-mix-amount-strong));
+    --sk-info-text: oklch(1 0 0);
+    --sk-info-text-contrast: var(--sk-color-gray-95);
+}
+```
+
+3. **Import your theme** in `index.scss`:
+
+```scss
+@forward 'greyscale';
+@forward 'colorful';
+@forward 'mytheme';  // Add your theme
+```
+
+4. **Add the TypeScript type** in `src/components/Theme/types.ts`:
+
+```typescript
+export type SkThemeName = 'greyscale' | 'colorful' | 'mytheme';
+```
+
+5. **Use your theme**:
+
+```vue
+<SkTheme theme="mytheme">
+    <YourApp />
+</SkTheme>
+```
+
+## Available Foundation Colors
+
+Each color family has 11 shades (05, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95):
+
+- `--sk-color-gray-XX` - Gray scale
+- `--sk-color-blue-XX` - Neon Blue
+- `--sk-color-red-XX` - Red
+- `--sk-color-orange-XX` - Neon Orange
+- `--sk-color-yellow-XX` - Yellow
+- `--sk-color-green-XX` - Neon Green
+- `--sk-color-mint-XX` - Neon Mint
+- `--sk-color-cyan-XX` - Light Blue/Cyan
+- `--sk-color-purple-XX` - Neon Purple
+- `--sk-color-pink-XX` - Neon Pink
+
+Shade `50` is typically the most vibrant/saturated version of each color.
+
+## Token Structure
+
+Each kind requires 5 tokens:
+
+- **`-base`**: The main color (maps to a foundation color)
+- **`-hover`**: Hover state (derived via `color-mix()`)
+- **`-active`**: Active/pressed state (derived via `color-mix()`)
+- **`-text`**: Text color on colored backgrounds (usually white)
+- **`-text-contrast`**: Alternative text color for special cases
+
+The hover/active states use `color-mix()` to automatically lighten the base color, ensuring consistency across all themes.

package/src/styles/themes/_colorful.scss

@@ -0,0 +1,58 @@
+/**
+ * Colorful Theme
+ *
+ * Vibrant theme with blue neutral colors and orange primary.
+ * This swaps the primary/neutral colors from greyscale for a bolder look.
+ */
+
+[data-scheme="colorful"]
+{
+    /* Neutral Kind */
+    --sk-neutral-base: var(--sk-color-blue-70);
+    --sk-neutral-hover: color-mix(in oklch, var(--sk-neutral-base), var(--sk-color-gray-10) var(--sk-mix-amount-moderate));
+    --sk-neutral-active: color-mix(in oklch, var(--sk-neutral-base), var(--sk-color-gray-10) var(--sk-mix-amount-strong));
+    --sk-neutral-text: oklch(1 0 0);
+    --sk-neutral-text-contrast: var(--sk-color-gray-95);
+
+    /* Primary Kind */
+    --sk-primary-base: var(--sk-color-orange-50);
+    --sk-primary-hover: color-mix(in oklch, var(--sk-primary-base), var(--sk-color-gray-10) var(--sk-mix-amount-moderate));
+    --sk-primary-active: color-mix(in oklch, var(--sk-primary-base), var(--sk-color-gray-10) var(--sk-mix-amount-strong));
+    --sk-primary-text: oklch(1 0 0);
+    --sk-primary-text-contrast: var(--sk-color-gray-95);
+
+    /* Accent Kind */
+    --sk-accent-base: var(--sk-color-blue-50);
+    --sk-accent-hover: color-mix(in oklch, var(--sk-accent-base), var(--sk-color-gray-10) var(--sk-mix-amount-moderate));
+    --sk-accent-active: color-mix(in oklch, var(--sk-accent-base), var(--sk-color-gray-10) var(--sk-mix-amount-strong));
+    --sk-accent-text: oklch(1 0 0);
+    --sk-accent-text-contrast: var(--sk-color-gray-95);
+
+    /* Success Kind */
+    --sk-success-base: var(--sk-color-green-50);
+    --sk-success-hover: color-mix(in oklch, var(--sk-success-base), var(--sk-color-gray-10) var(--sk-mix-amount-moderate));
+    --sk-success-active: color-mix(in oklch, var(--sk-success-base), var(--sk-color-gray-10) var(--sk-mix-amount-strong));
+    --sk-success-text: oklch(1 0 0);
+    --sk-success-text-contrast: var(--sk-color-gray-95);
+
+    /* Warning Kind */
+    --sk-warning-base: var(--sk-color-yellow-50);
+    --sk-warning-hover: color-mix(in oklch, var(--sk-warning-base), var(--sk-color-gray-10) var(--sk-mix-amount-moderate));
+    --sk-warning-active: color-mix(in oklch, var(--sk-warning-base), var(--sk-color-gray-10) var(--sk-mix-amount-strong));
+    --sk-warning-text: oklch(1 0 0);
+    --sk-warning-text-contrast: var(--sk-color-gray-95);
+
+    /* Danger Kind */
+    --sk-danger-base: var(--sk-color-red-50);
+    --sk-danger-hover: color-mix(in oklch, var(--sk-danger-base), var(--sk-color-gray-10) var(--sk-mix-amount-moderate));
+    --sk-danger-active: color-mix(in oklch, var(--sk-danger-base), var(--sk-color-gray-10) var(--sk-mix-amount-strong));
+    --sk-danger-text: oklch(1 0 0);
+    --sk-danger-text-contrast: var(--sk-color-gray-95);
+
+    /* Info Kind */
+    --sk-info-base: var(--sk-color-cyan-50);
+    --sk-info-hover: color-mix(in oklch, var(--sk-info-base), var(--sk-color-gray-10) var(--sk-mix-amount-moderate));
+    --sk-info-active: color-mix(in oklch, var(--sk-info-base), var(--sk-color-gray-10) var(--sk-mix-amount-strong));
+    --sk-info-text: oklch(1 0 0);
+    --sk-info-text-contrast: var(--sk-color-gray-95);
+}

package/src/styles/themes/_greyscale.scss

@@ -0,0 +1,58 @@
+/**
+ * Greyscale Theme
+ *
+ * Reference theme with gray neutral colors and blue primary.
+ * This is the default, more subdued theme.
+ */
+
+[data-scheme="greyscale"]
+{
+    /* Neutral Kind */
+    --sk-neutral-base: var(--sk-color-gray-50);
+    --sk-neutral-hover: color-mix(in oklch, var(--sk-neutral-base), var(--sk-color-gray-10) var(--sk-mix-amount-moderate));
+    --sk-neutral-active: color-mix(in oklch, var(--sk-neutral-base), var(--sk-color-gray-10) var(--sk-mix-amount-strong));
+    --sk-neutral-text: oklch(1 0 0);
+    --sk-neutral-text-contrast: var(--sk-color-gray-95);
+
+    /* Primary Kind */
+    --sk-primary-base: var(--sk-color-blue-50);
+    --sk-primary-hover: color-mix(in oklch, var(--sk-primary-base), var(--sk-color-gray-10) var(--sk-mix-amount-moderate));
+    --sk-primary-active: color-mix(in oklch, var(--sk-primary-base), var(--sk-color-gray-10) var(--sk-mix-amount-strong));
+    --sk-primary-text: oklch(1 0 0);
+    --sk-primary-text-contrast: var(--sk-color-gray-95);
+
+    /* Accent Kind */
+    --sk-accent-base: var(--sk-color-orange-50);
+    --sk-accent-hover: color-mix(in oklch, var(--sk-accent-base), var(--sk-color-gray-10) var(--sk-mix-amount-moderate));
+    --sk-accent-active: color-mix(in oklch, var(--sk-accent-base), var(--sk-color-gray-10) var(--sk-mix-amount-strong));
+    --sk-accent-text: oklch(1 0 0);
+    --sk-accent-text-contrast: var(--sk-color-gray-95);
+
+    /* Success Kind */
+    --sk-success-base: var(--sk-color-green-50);
+    --sk-success-hover: color-mix(in oklch, var(--sk-success-base), var(--sk-color-gray-10) var(--sk-mix-amount-moderate));
+    --sk-success-active: color-mix(in oklch, var(--sk-success-base), var(--sk-color-gray-10) var(--sk-mix-amount-strong));
+    --sk-success-text: oklch(1 0 0);
+    --sk-success-text-contrast: var(--sk-color-gray-95);
+
+    /* Warning Kind */
+    --sk-warning-base: var(--sk-color-yellow-50);
+    --sk-warning-hover: color-mix(in oklch, var(--sk-warning-base), var(--sk-color-gray-10) var(--sk-mix-amount-moderate));
+    --sk-warning-active: color-mix(in oklch, var(--sk-warning-base), var(--sk-color-gray-10) var(--sk-mix-amount-strong));
+    --sk-warning-text: oklch(1 0 0);
+    --sk-warning-text-contrast: var(--sk-color-gray-95);
+
+    /* Danger Kind */
+    --sk-danger-base: var(--sk-color-red-50);
+    --sk-danger-hover: color-mix(in oklch, var(--sk-danger-base), var(--sk-color-gray-10) var(--sk-mix-amount-moderate));
+    --sk-danger-active: color-mix(in oklch, var(--sk-danger-base), var(--sk-color-gray-10) var(--sk-mix-amount-strong));
+    --sk-danger-text: oklch(1 0 0);
+    --sk-danger-text-contrast: var(--sk-color-gray-95);
+
+    /* Info Kind */
+    --sk-info-base: var(--sk-color-cyan-50);
+    --sk-info-hover: color-mix(in oklch, var(--sk-info-base), var(--sk-color-gray-10) var(--sk-mix-amount-moderate));
+    --sk-info-active: color-mix(in oklch, var(--sk-info-base), var(--sk-color-gray-10) var(--sk-mix-amount-strong));
+    --sk-info-text: oklch(1 0 0);
+    --sk-info-text-contrast: var(--sk-color-gray-95);
+}

package/src/styles/themes/index.scss

@@ -0,0 +1,9 @@
+/**
+ * Themes Index
+ *
+ * All theme definitions for the SleekSpace UI design system.
+ * Each theme defines semantic color mappings for the 7 kinds.
+ */
+
+@forward 'greyscale';
+@forward 'colorful';

package/src/styles/tokens/README.md

@@ -0,0 +1,268 @@
+# SleekSpace Design Tokens
+
+This directory contains all design tokens for the SleekSpace UI component library, organized in a three-tier hierarchy.
+
+## Token Hierarchy
+
+```
+Foundation Tokens (global primitives)
+    ↓
+Semantic Tokens (contextual meanings)
+    ↓
+Component Tokens (component-specific)
+```
+
+### Foundation Tokens
+
+Foundation tokens are the lowest-level design primitives. These are global values that all other tokens derive from:
+
+- **Colors** (`_foundation-colors.scss`): Color primitives (10 hues × 11 shades), opacity scale, color mixing percentages
+- **Space** (`_foundation-space.scss`): Spacing scale from 3xs to 4xl with global scale multiplier
+- **Radius** (`_foundation-radius.scss`): Border radius scale and radius factors for calculations
+- **Borders** (`_foundation-borders.scss`): Border widths and styles
+- **Shadows** (`_foundation-shadows.scss`): Elevation shadows for creating depth
+- **Glow** (`_foundation-glow.scss`): Glow effects for neon aesthetic (SleekSpace-specific)
+- **Transitions** (`_foundation-transitions.scss`): Animation timing and easing functions
+- **Typography** (`_foundation-typography.scss`): Font families, sizes, weights, line heights
+
+### Semantic Tokens
+
+Semantic tokens provide contextual meaning by referencing foundation tokens:
+
+- **Colors** (`_semantic-colors.scss`): Kind-based colors (neutral, primary, secondary, success, warning, danger, info) with base/hover/active/text variants for each scheme (greyscale, colorful)
+- **Surfaces** (`_semantic-surfaces.scss`): Background and text colors for surfaces
+- **Interactive** (`_semantic-interactive.scss`): Focus rings and selection states
+
+### Component Tokens
+
+Component-specific tokens are defined inline within component stylesheets. Only create component tokens when:
+1. The value doesn't fit existing foundation/semantic tokens
+2. The behavior is unique to that component
+3. Independent control is needed
+
+## Naming Convention
+
+All tokens follow the pattern: `--sk-{category}-{subcategory}-{variant/size}`
+
+Examples:
+- `--sk-color-blue-50`
+- `--sk-space-md`
+- `--sk-radius-lg`
+- `--sk-transition-fast`
+- `--sk-primary-base`
+- `--sk-primary-hover`
+
+## Adding New Components
+
+When creating a new component, follow these guidelines:
+
+### 1. Use Semantic Tokens for Colors
+
+**Do this:**
+```scss
+.sk-new-component {
+  background-color: var(--sk-primary-base);
+  color: var(--sk-primary-text);
+
+  &:hover {
+    background-color: var(--sk-primary-hover);
+  }
+}
+```
+
+**Not this:**
+```scss
+.sk-new-component {
+  background-color: var(--sk-color-blue-50); // ❌ Don't use color primitives directly
+  color: white; // ❌ Don't use hard-coded values
+}
+```
+
+### 2. Use Foundation Tokens for Spacing/Radius/Borders
+
+**Do this:**
+```scss
+.sk-new-component {
+  padding: var(--sk-space-md);
+  gap: var(--sk-space-sm);
+  border-radius: var(--sk-radius-md);
+  border-width: var(--sk-border-width-thin);
+}
+```
+
+**Not this:**
+```scss
+.sk-new-component {
+  padding: 16px; // ❌ Don't use hard-coded values
+  gap: 12px; // ❌ Use tokens instead
+  border-radius: 8px; // ❌ Use tokens instead
+}
+```
+
+### 3. Use Transition Tokens
+
+**Do this:**
+```scss
+.sk-new-component {
+  transition: var(--sk-transition-fast);
+  // Or more specific:
+  transition:
+    color var(--sk-transition-duration-fast) var(--sk-transition-easing-ease-out),
+    background-color var(--sk-transition-duration-fast) var(--sk-transition-easing-ease-out);
+}
+```
+
+### 4. Use Opacity Tokens
+
+**Do this:**
+```scss
+.sk-new-component {
+  background-color: oklch(from var(--sk-primary-base) l c h / var(--sk-opacity-moderate));
+}
+```
+
+**Not this:**
+```scss
+.sk-new-component {
+  background-color: oklch(from var(--sk-primary-base) l c h / 0.2); // ❌ Use tokens
+}
+```
+
+### 5. Use Glow Tokens for Neon Effects
+
+**Do this:**
+```scss
+.sk-new-component {
+  &.variant-neon:hover {
+    box-shadow:
+      0 0 var(--sk-glow-blur-md) var(--sk-glow-spread-sm)
+      color-mix(
+        in oklch,
+        var(--sk-primary-base),
+        transparent calc(100% - (var(--sk-glow-intensity-moderate) * 100%))
+      );
+  }
+}
+```
+
+## Common Patterns
+
+### Kind-Based Component Styling
+
+Use SCSS mixins to generate styles for each kind:
+
+```scss
+@mixin component-kind($kind) {
+  &.sk-#{$kind} {
+    --component-color-base: var(--sk-#{$kind}-base);
+    --component-text: var(--sk-#{$kind}-text);
+
+    background-color: var(--component-color-base);
+    color: var(--component-text);
+
+    &:hover {
+      background-color: var(--sk-#{$kind}-hover);
+    }
+  }
+}
+
+.sk-new-component {
+  @each $kind in $kinds {
+    @include component-kind($kind);
+  }
+}
+```
+
+### Size-Based Component Styling
+
+```scss
+.sk-new-component {
+  height: 40px; // base size
+  padding: var(--sk-space-md);
+
+  &.sk-sm {
+    height: 32px;
+    padding: var(--sk-space-sm);
+  }
+
+  &.sk-lg {
+    height: 48px;
+    padding: var(--sk-space-lg);
+  }
+}
+```
+
+### Color Derivation with color-mix()
+
+```scss
+// Darken a color
+color-mix(in oklch, var(--sk-primary-base), var(--sk-color-gray-10) var(--sk-mix-amount-moderate))
+
+// Lighten a color
+color-mix(in oklch, var(--sk-primary-base), var(--sk-color-gray-95) var(--sk-mix-amount-light))
+
+// Add transparency
+oklch(from var(--sk-primary-base) l c h / var(--sk-opacity-moderate))
+```
+
+## Global Customization
+
+Users can customize the entire system using scale multipliers:
+
+```css
+:root {
+  --sk-space-scale: 1.2;        /* 20% larger spacing */
+  --sk-radius-scale: 1.5;       /* 50% rounder corners */
+  --sk-font-size-scale: 0.9;    /* 10% smaller text */
+}
+```
+
+## Compatibility Layer
+
+The `_compat-layer.scss` file provides backwards compatibility for old token names. This allows existing components to continue working while we migrate to the new naming conventions.
+
+**TODO**: Remove `_compat-layer.scss` once all components are migrated to new token names.
+
+## Token Files
+
+| File | Purpose | Token Count |
+|------|---------|-------------|
+| `_foundation-colors.scss` | Color primitives, opacity, mixing | ~123 |
+| `_foundation-space.scss` | Spacing scale | 11 |
+| `_foundation-radius.scss` | Border radius scale + factors | 13 |
+| `_foundation-borders.scss` | Border widths + styles | 7 |
+| `_foundation-shadows.scss` | Elevation shadows | 7 |
+| `_foundation-glow.scss` | Glow effects | 9 |
+| `_foundation-transitions.scss` | Animation timing | 11 |
+| `_foundation-typography.scss` | Fonts and sizes | 22 |
+| `_semantic-colors.scss` | Kind-based colors (2 schemes) | 70 |
+| `_semantic-surfaces.scss` | Surface + text colors | 7 |
+| `_semantic-interactive.scss` | Focus + selection | 6 |
+| **Total** | | **~286** |
+
+## Color Schemes
+
+The system supports multiple color schemes via `data-scheme` attribute:
+
+- `greyscale` - Gray neutral with blue primary (reference theme)
+- `colorful` - Blue neutral with orange primary
+
+To add a new scheme, update `_semantic-colors.scss`:
+
+```scss
+[data-scheme="my-new-scheme"] {
+  --sk-neutral-base: var(--sk-color-gray-50);
+  --sk-primary-base: var(--sk-color-purple-50);
+  // ... define all semantic color tokens
+}
+```
+
+## Resources
+
+- **Full Proposal**: See `/DESIGN_TOKENS_PROPOSAL.md` for complete design rationale and implementation plan
+- **Web Awesome Inspiration**: https://webawesome.com/docs/tokens/
+- **OKLCH Color Space**: https://oklch.com/
+
+## Questions?
+
+If you have questions about the token system or need guidance on using tokens in your components, refer to the full proposal document or ask the team.

package/src/styles/tokens/_foundation-borders.scss

@@ -0,0 +1,26 @@
+/**
+ * Foundation Tokens - Borders
+ *
+ * Border widths and styles for component outlines.
+ */
+
+:root
+{
+    /* ===================================================================
+     * Border Widths
+     * =================================================================== */
+
+    --sk-border-width-none:   0;
+    --sk-border-width-thin:   1px;
+    --sk-border-width-normal: 2px;
+    --sk-border-width-thick:  4px;
+    --sk-border-width-heavy:  6px;
+
+    /* ===================================================================
+     * Border Styles
+     * =================================================================== */
+
+    --sk-border-style-solid:  solid;
+    --sk-border-style-dashed: dashed;
+    --sk-border-style-none:   none;
+}