@skewedaspect/sleekspace-ui 0.4.0 → 0.5.1

package/docs/guides/theming.md

@@ -42,9 +42,29 @@ const { currentTheme, setTheme } = useTheme();
 </template>
 ```
 
+## SkPage as Theme Provider
+
+If your app already uses `SkPage`, you can skip the `SkTheme` wrapper and pass a `theme` prop directly:
+
+```vue
+<template>
+  <SkPage theme="colorful" fixed-header>
+    <template #header>
+      <SkNavBar kind="primary">
+        <template #brand>My App</template>
+      </SkNavBar>
+    </template>
+
+    <SkPanel kind="accent">Fully themed — no SkTheme wrapper needed.</SkPanel>
+  </SkPage>
+</template>
+```
+
+This establishes the same theme context that `SkTheme` does (including portal component support). The `useTheme` composable works identically inside a themed `SkPage`.
+
 ## How It Works
 
-SkTheme sets a `data-scheme` attribute on its wrapper element. CSS rules scoped to each scheme override semantic token values:
+SkTheme (or SkPage with a `theme` prop) sets a `data-scheme` attribute on its wrapper element. This cascades the correct text color (`--sk-text-primary`) to all descendants. SkPage also sets the page background (`--sk-surface-base`). CSS rules scoped to each scheme override semantic token values:
 
 ```css
 [data-scheme="greyscale"] {
@@ -60,30 +80,274 @@ All components reference these semantic tokens, so switching the scheme instantl
 
 ## Creating Custom Themes
 
-Define a custom theme by providing CSS custom property overrides on a new `data-scheme` value:
+Themes are pure CSS. You define a `[data-scheme="name"]` block with 35 custom properties (7 semantic kinds × 5 tokens each) and you're done. No library modifications, no build steps — just a stylesheet.
+
+> See the [SkTheme component page](/components/theme) for live demos of custom themes compared side-by-side with the built-in ones.
+
+### Token Structure
+
+Each of the 7 semantic kinds requires 5 tokens:
+
+| Token | Purpose |
+|-------|---------|
+| `--sk-{kind}-base` | Main background color |
+| `--sk-{kind}-hover` | Hover state background |
+| `--sk-{kind}-active` | Active/pressed state background |
+| `--sk-{kind}-text` | Text color on the base background |
+| `--sk-{kind}-text-contrast` | Alternative text for subtle/ghost variants |
+
+The 7 kinds are: `neutral`, `primary`, `accent`, `success`, `warning`, `danger`, `info`.
+
+### Surface Tokens (Optional)
+
+Themes can also override the page surface tokens. These have sensible defaults (dark gray background, white text) so you only need to override them if your theme wants a different page feel:
+
+| Token | Default | Purpose |
+|-------|---------|---------|
+| `--sk-surface-base` | `--sk-color-gray-90` | Page/app background |
+| `--sk-surface-raised` | `--sk-color-gray-95` | Elevated surfaces (cards, panels) |
+| `--sk-surface-overlay` | `--sk-color-gray-80` | Overlays (modals, dropdowns) |
+| `--sk-text-primary` | white | Primary body text |
+
+`SkPage` applies `--sk-surface-base` as its background automatically. If you use `SkTheme` without `SkPage`, set your body background to `var(--sk-surface-base)` for the dark page feel.
+
+### Deriving Hover and Active States
+
+You don't need to hand-pick hover/active colors. The `color-mix()` function lightens the base color automatically, which is how the built-in themes do it:
 
 ```css
+--sk-primary-hover: color-mix(
+  in oklch,
+  var(--sk-primary-base),
+  var(--sk-color-gray-10) var(--sk-mix-amount-moderate)  /* 15% lighter */
+);
+--sk-primary-active: color-mix(
+  in oklch,
+  var(--sk-primary-base),
+  var(--sk-color-gray-10) var(--sk-mix-amount-strong)    /* 20% lighter */
+);
+```
+
+This pattern references the `--sk-color-gray-10` foundation token (a light gray) and mixes it in at either 15% (`moderate`) or 20% (`strong`). You can also use hardcoded OKLCH values if you prefer full control.
+
+### Complete Example: "Ocean" Theme
+
+Here's a full theme definition using OKLCH values. This theme uses deep blues for neutral elements, teal for primary, coral for accent, and keeps the standard semantic colors for success/warning/danger/info:
+
+```css
+/* ocean-theme.css — import this after SleekSpace UI styles */
+
 [data-scheme="ocean"] {
-  --sk-primary-base: oklch(0.55 0.15 230);
+  /* Neutral — deep slate blue */
+  --sk-neutral-base: oklch(0.35 0.04 250);
+  --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: oklch(0.15 0.02 250);
+
+  /* Primary — bright teal */
+  --sk-primary-base: oklch(0.72 0.15 195);
+  --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-hover: oklch(0.45 0.15 230);
+  --sk-primary-text-contrast: oklch(0.15 0.02 195);
 
-  --sk-accent-base: oklch(0.6 0.2 180);
+  /* Accent — warm coral */
+  --sk-accent-base: oklch(0.68 0.18 25);
+  --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-hover: oklch(0.5 0.2 180);
+  --sk-accent-text-contrast: oklch(0.15 0.02 25);
 
-  /* Define all 7 semantic kinds: neutral, primary, accent, info, success, warning, danger */
+  /* Success — emerald green */
+  --sk-success-base: oklch(0.70 0.18 155);
+  --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: oklch(0.15 0.02 155);
+
+  /* Warning — amber */
+  --sk-warning-base: oklch(0.85 0.16 85);
+  --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: oklch(0.15 0.02 85);
+
+  /* Danger — crimson red */
+  --sk-danger-base: oklch(0.60 0.22 25);
+  --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: oklch(0.15 0.02 25);
+
+  /* Info — sky blue */
+  --sk-info-base: oklch(0.75 0.12 230);
+  --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: oklch(0.15 0.02 230);
 }
 ```
 
-Then use it with the theme component:
+### Complete Example: "Cyberpunk" Theme
+
+Neon pink primary, electric cyan accent, deep violet neutrals, and screaming neon green for success. High chroma across the board.
+
+```css
+/* cyberpunk-theme.css */
+
+[data-scheme="cyberpunk"] {
+  /* Neutral — deep violet */
+  --sk-neutral-base: oklch(0.25 0.08 300);
+  --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: oklch(0.12 0.04 300);
+
+  /* Primary — hot pink */
+  --sk-primary-base: oklch(0.65 0.27 355);
+  --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: oklch(0.12 0.04 355);
+
+  /* Accent — electric cyan */
+  --sk-accent-base: oklch(0.78 0.15 195);
+  --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: oklch(0.12 0.04 195);
+
+  /* Success — neon green */
+  --sk-success-base: oklch(0.82 0.25 145);
+  --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: oklch(0.12 0.04 145);
+
+  /* Warning — electric yellow */
+  --sk-warning-base: oklch(0.90 0.18 100);
+  --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: oklch(0.12 0.04 100);
+
+  /* Danger — hot red */
+  --sk-danger-base: oklch(0.62 0.25 30);
+  --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: oklch(0.12 0.04 30);
+
+  /* Info — neon purple */
+  --sk-info-base: oklch(0.60 0.25 305);
+  --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: oklch(0.12 0.04 305);
+}
+```
+
+### Using a Custom Theme
+
+Apply it with `SkTheme` or `SkPage`:
 
 ```vue
+<!-- With SkTheme -->
 <SkTheme theme="ocean">
   <YourContent />
 </SkTheme>
+
+<!-- Or directly on SkPage -->
+<SkPage theme="ocean" fixed-header>
+  <template #header>...</template>
+  <YourContent />
+</SkPage>
+```
+
+> **TypeScript note:** To get type-safe autocomplete for custom theme names, augment the `SkThemeNameMap` interface:
+>
+> ```ts
+> declare module '@skewedaspect/sleekspace-ui' {
+>     interface SkThemeNameMap {
+>         ocean : true;
+>     }
+> }
+> ```
+>
+> This registers `'ocean'` as a valid `SkThemeName` throughout your project.
+
+### Using Foundation Colors
+
+Instead of raw OKLCH values, you can reference the built-in foundation color palette. Each color family has 11 shades (05 through 95, where 50 is the most saturated):
+
+```css
+[data-scheme="mytheme"] {
+  /* Reference foundation palette variables */
+  --sk-primary-base: var(--sk-color-purple-50);
+  --sk-accent-base: var(--sk-color-pink-50);
+  --sk-neutral-base: var(--sk-color-gray-60);
+
+  /* hover/active states auto-derived the same way */
+  --sk-primary-hover: color-mix(in oklch, var(--sk-primary-base), var(--sk-color-gray-10) var(--sk-mix-amount-moderate));
+  /* ... */
+}
+```
+
+Available foundation color families: `gray`, `blue`, `red`, `orange`, `yellow`, `green`, `mint`, `cyan`, `purple`, `pink`.
+
+### Quick Reference: Minimal Theme
+
+If you just want to remap which colors go where, copy this template and change the `-base` values. The `color-mix()` lines can be copied verbatim — they derive from the base automatically:
+
+```css
+[data-scheme="mytheme"] {
+  --sk-neutral-base: /* your color */;
+  --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);
+
+  --sk-primary-base: /* your color */;
+  --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);
+
+  --sk-accent-base: /* your color */;
+  --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);
+
+  --sk-success-base: /* your color */;
+  --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);
+
+  --sk-warning-base: /* your color */;
+  --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);
+
+  --sk-danger-base: /* your color */;
+  --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);
+
+  --sk-info-base: /* your color */;
+  --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);
+}
 ```
 
+Only the 7 `-base` values need to change. Everything else is boilerplate that can be copied as-is.
+
 ## Semantic Kinds
 
 All themed components accept a `kind` prop with these values:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skewedaspect/sleekspace-ui",
-  "version": "0.4.0",
+  "version": "0.5.1",
   "description": "A Vue 3 component library with a cyberpunk aesthetic, featuring OKLCH colors, beveled corners, and a powerful design token system",
   "type": "module",
   "main": "dist/sleekspace-ui.umd.js",
@@ -49,10 +49,10 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "git+https://gitlab.com/skewedaspect/sleekspace-ui.git",
+    "url": "git+https://gitlab.com/skewed-aspect/sleekspace-ui.git",
     "directory": "packages/sleekspace-ui"
   },
-  "bugs": "https://gitlab.com/skewedaspect/sleekspace-ui/-/issues",
+  "bugs": "https://gitlab.com/skewed-aspect/sleekspace-ui/-/issues",
   "homepage": "https://sleekspace.skewedaspect.com",
   "peerDependencies": {
     "vue": "^3.3.0"

package/src/components/Page/SkPage.vue

@@ -1,5 +1,5 @@
 <template>
-    <div :class="classes" :style="customStyles">
+    <div :class="classes" :style="customStyles" :data-scheme="theme">
         <header v-if="$slots.header" class="sk-page-header">
             <slot name="header" />
         </header>
@@ -62,11 +62,15 @@
      *                width below the sidebar and content areas.
      */
 
-    import { computed } from 'vue';
+    import { computed, provide, watch } from 'vue';
 
     // Types
+    import type { SkThemeName } from '../Theme/types';
     import type { SkPageSidebarPosition } from './types';
 
+    // Composables
+    import { provideTheme } from '../Theme/useTheme';
+
     //------------------------------------------------------------------------------------------------------------------
 
     export interface SkPageComponentProps
@@ -101,6 +105,14 @@
          * Only applies when the sidebar slot is provided.
          */
         sidebarWidth ?: string;
+
+        /**
+         * Optional theme name. When provided, SkPage acts as a theme provider — setting
+         * `data-scheme` on the root element and providing theme context for descendant
+         * components (including portal components like dropdowns and modals).
+         * When omitted, SkPage has no theme behavior.
+         */
+        theme ?: SkThemeName;
     }
 
     //------------------------------------------------------------------------------------------------------------------
@@ -110,6 +122,7 @@
         fixedHeader: false,
         fixedFooter: false,
         sidebarWidth: undefined,
+        theme: undefined,
     });
 
     //------------------------------------------------------------------------------------------------------------------
@@ -138,6 +151,27 @@
             '--sk-page-sidebar-width': props.sidebarWidth,
         };
     });
+
+    //------------------------------------------------------------------------------------------------------------------
+    // Theme Provider
+    //------------------------------------------------------------------------------------------------------------------
+
+    if(props.theme)
+    {
+        const { currentTheme, setTheme } = provideTheme(props.theme);
+
+        // Provide theme for portal components (dropdown, modal, tooltip, etc.)
+        provide('sk-theme', currentTheme);
+
+        // Watch for external theme prop changes
+        watch(() => props.theme, (newTheme) =>
+        {
+            if(newTheme)
+            {
+                setTheme(newTheme);
+            }
+        });
+    }
 </script>
 
 <!--------------------------------------------------------------------------------------------------------------------->

package/src/components/Page/types.ts

@@ -2,6 +2,10 @@
 // Page Types
 //----------------------------------------------------------------------------------------------------------------------
 
+import type { SkThemeName } from '../Theme/types';
+
+//----------------------------------------------------------------------------------------------------------------------
+
 /** Sidebar position */
 export type SkPageSidebarPosition = 'left' | 'right';
 
@@ -16,6 +20,8 @@ export interface SkPageProps
     fixedFooter ?: boolean;
     /** Custom sidebar width */
     sidebarWidth ?: string;
+    /** Optional theme name — when provided, SkPage acts as a theme provider */
+    theme ?: SkThemeName;
 }
 
 //----------------------------------------------------------------------------------------------------------------------

package/src/components/Theme/types.ts

@@ -2,12 +2,29 @@
 // Theme Component Types
 //----------------------------------------------------------------------------------------------------------------------
 
+/**
+ * Registry of available theme names. Augment this interface to register custom themes:
+ *
+ * ```ts
+ * declare module '@skewedaspect/sleekspace-ui' {
+ *     interface SkThemeNameMap {
+ *         ocean : true;
+ *         midnight : true;
+ *     }
+ * }
+ * ```
+ */
+export interface SkThemeNameMap
+{
+    greyscale : true;
+    colorful : true;
+}
+
 /**
  * Available theme names that control the overall color scheme of the application.
- * - 'greyscale': A monochromatic theme with neutral grays and subtle accents
- * - 'colorful': A vibrant theme with saturated colors and stronger contrasts
+ * Derived from {@link SkThemeNameMap} — augment that interface to add custom themes.
  */
-export type SkThemeName = 'greyscale' | 'colorful';
+export type SkThemeName = keyof SkThemeNameMap;
 
 //----------------------------------------------------------------------------------------------------------------------
 

package/src/styles/_scrollbar.scss

@@ -56,8 +56,8 @@
 
         /* Smooth transitions for interactive states */
         transition:
-            background-color var(--sk-transition-duration-fast) var(--sk-transition-easing-standard),
-            border-color var(--sk-transition-duration-fast) var(--sk-transition-easing-standard);
+            background-color var(--sk-transition-duration-fast) var(--sk-transition-easing-ease-out),
+            border-color var(--sk-transition-duration-fast) var(--sk-transition-easing-ease-out);
     }
 
     /* Hover State */

package/src/styles/base/_global.scss

@@ -21,7 +21,7 @@ body
 {
     margin: 0;
     min-height: 100svh;
-    color: var(--sk-neutral-fg);
+    color: var(--sk-text-primary);
 }
 
 img,
@@ -40,8 +40,8 @@ canvas
 
 :focus-visible
 {
-    outline: var(--sk-focus-outline-width) solid currentColor;
-    outline-offset: var(--sk-focus-outline-offset);
+    outline: var(--sk-focus-ring-width) solid currentColor;
+    outline-offset: var(--sk-focus-ring-offset);
 }
 
 //----------------------------------------------------------------------------------------------------------------------

package/src/styles/components/_button.scss

@@ -103,10 +103,10 @@
     --sk-button-outline-bg: rgba(5, 5, 5, 0.15);
 
     /// Subtle variant background opacity (references global foundation token)
-    --sk-button-subtle-opacity: var(--sk-opacity-subtle);
+    --sk-button-subtle-opacity: 0.35;
 
     /// Subtle variant hover background opacity (references global foundation token)
-    --sk-button-subtle-opacity-hover: var(--sk-opacity-subtle-hover);
+    --sk-button-subtle-opacity-hover: 0.65;
 
     /// Subtle variant border opacity (references global foundation token)
     --sk-button-subtle-border-opacity: var(--sk-opacity-subtle-border);
@@ -260,10 +260,9 @@
 
         &:hover:not(:disabled)
         {
-            --sk-button-border-color: oklch(from var(--sk-button-border-base) l c h / var(--sk-button-subtle-border-opacity-hover));
             --sk-button-glow-shadow: 0 0 var(--sk-button-glow-size) oklch(from var(--sk-button-border-base) l c h / var(--sk-button-glow-opacity));
 
-            background-color: oklch(from var(--sk-button-bg) l c h / var(--sk-button-subtle-opacity-hover));
+            background-color: var(--sk-button-bg-hover);
         }
 
         &:active:not(:disabled)
@@ -534,6 +533,12 @@
             @include button-subtle-kind($kind);
         }
 
+        &:disabled,
+        &.sk-loading
+        {
+            background-color: oklch(from var(--sk-button-bg) l c h / 0.45);
+        }
+
         // Special case: neutral text and border are lighter (halfway to white) for better differentiation
         &.sk-neutral
         {
@@ -624,20 +629,51 @@
 
     &.sk-pressed
     {
-        &.sk-outline,
-        &.sk-ghost
+        &.sk-solid
         {
-            background-color: oklch(from var(--sk-button-bg) l c h / var(--sk-button-subtle-opacity));
+            --sk-button-border-color: var(--sk-button-border-hover);
+            background-color: var(--sk-button-bg-hover);
+            color: var(--sk-button-text);
+
+            &:hover:not(:disabled)
+            {
+                --sk-button-glow-shadow: 0 0 var(--sk-button-glow-size) oklch(from var(--sk-button-border-base) l c h / var(--sk-button-glow-opacity));
+                background-color: color-mix(in oklch, var(--sk-button-bg) 70%, white 30%);
+            }
         }
 
-        &.sk-solid
+        &.sk-outline
         {
-            background-color: var(--sk-button-bg-active);
+            --sk-button-border-color: var(--sk-button-border-hover);
+            background-color: var(--sk-button-bg);
+            color: var(--sk-button-text);
         }
 
         &.sk-subtle
         {
+            --sk-button-border-color: transparent;
             background-color: var(--sk-button-bg);
+            color: var(--sk-button-text);
+
+            &:hover:not(:disabled)
+            {
+                --sk-button-border-color: transparent;
+                --sk-button-glow-shadow: 0 0 var(--sk-button-glow-size) oklch(from var(--sk-button-border-base) l c h / var(--sk-button-glow-opacity));
+                background-color: var(--sk-button-bg-hover);
+            }
+        }
+
+        &.sk-ghost
+        {
+            --sk-button-border-color: color-mix(in oklch, var(--sk-button-border-base) 50%, transparent 50%);
+            border-color: color-mix(in oklch, var(--sk-button-border-base) 50%, transparent 50%);
+            background-color: var(--sk-button-outline-bg);
+            color: var(--sk-button-text);
+        }
+
+        &.sk-link
+        {
+            color: var(--sk-button-text);
         }
     }
 

package/src/styles/components/_page.scss

@@ -12,8 +12,8 @@
     display: flex;
     flex-direction: column;
     min-height: 100vh;
-    background: var(--sk-background);
-    color: var(--sk-foreground);
+    background: var(--sk-surface-base);
+    color: var(--sk-text-primary);
 
     //------------------------------------------------------------------------------------------------------------------
     // Header

package/src/styles/themes/README.md

@@ -83,10 +83,14 @@ To create a new theme:
 @forward 'mytheme';  // Add your theme
 ```
 
-4. **Add the TypeScript type** in `src/components/Theme/types.ts`:
+4. **Register the TypeScript type** via module augmentation (e.g. in a `themes.d.ts` or your app's entry file):
 
 ```typescript
-export type SkThemeName = 'greyscale' | 'colorful' | 'mytheme';
+declare module '@skewedaspect/sleekspace-ui' {
+    interface SkThemeNameMap {
+        mytheme : true;
+    }
+}
 ```
 
 5. **Use your theme**:

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

@@ -156,6 +156,10 @@
     --sk-opacity-strong: 0.60;
     --sk-opacity-opaque: 1;
 
+    /* Semantic opacity aliases */
+    --sk-opacity-disabled: 0.5;
+    --sk-opacity-loading: 0.6;
+
     /* ===================================================================
      * Color Mixing Percentages
      * Tokenized mixing amounts for color-mix() function

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

@@ -26,6 +26,14 @@
     --sk-transition-easing-ease-out:    ease-out;
     --sk-transition-easing-ease-in-out: ease-in-out;
 
+    /* ===================================================================
+     * Default Aliases
+     * Generic names that resolve to the most common values
+     * =================================================================== */
+
+    --sk-transition-duration-base: var(--sk-transition-duration-normal);
+    --sk-transition-easing:        var(--sk-transition-easing-ease-out);
+
     /* ===================================================================
      * Common Transition Combinations
      * Convenience tokens for frequently used transitions

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

@@ -3,6 +3,10 @@
  *
  * Background and text colors for surfaces and general use.
  * These provide a consistent color system independent of component kinds.
+ *
+ * Defaults are defined on :root as fallbacks. Themes can override any of these
+ * via [data-scheme] selectors. The [data-scheme] rule also applies background
+ * and text color so that any themed element gets the correct surface treatment.
  */
 
 :root
@@ -34,3 +38,14 @@
     --sk-border-normal: var(--sk-color-gray-70);  /* Standard borders */
     --sk-border-subtle: var(--sk-color-gray-80);  /* Subtle borders/dividers */
 }
+
+/**
+ * Apply text color to any themed element so descendants inherit the correct
+ * color without needing to set it themselves. Background is intentionally NOT
+ * set here — page-level containers like SkPage handle their own background
+ * via the surface tokens.
+ */
+[data-scheme]
+{
+    color: var(--sk-text-primary);
+}