@skewedaspect/sleekspace-ui 0.3.0 → 0.5.0

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,264 @@ 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:** The `theme` prop is typed as `SkThemeName` which is `'greyscale' | 'colorful'`. For custom theme names, cast the value: `:theme="'ocean' as any"`. If you're building a library that adds themes, you can augment the type via module declaration.
+
+### 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.3.0",
+  "version": "0.5.0",
   "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,11 +49,11 @@
   "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",
-  "homepage": "https://gitlab.com/skewedaspect/sleekspace-ui",
+  "bugs": "https://gitlab.com/skewed-aspect/sleekspace-ui/-/issues",
+  "homepage": "https://sleekspace.skewedaspect.com",
   "peerDependencies": {
     "vue": "^3.3.0"
   },

package/src/components/Alert/SkAlert.vue

@@ -4,9 +4,9 @@
 
 <template>
     <div :class="classes" :style="customColorStyles" role="alert">
-        <div class="sk-alert-icon">
+        <div v-if="shouldShowIcon" class="sk-alert-icon">
             <slot name="icon">
-                <!-- Default icons for each kind -->
+                <!-- Default icons for feedback kinds -->
                 <svg
                     v-if="kind === 'info'"
                     viewBox="0 0 24 24"
@@ -66,7 +66,7 @@
     /**
      * @component SkAlert
      * @description A contextual feedback component for displaying informational, success, warning, or error messages.
-     * Features automatic icon selection based on alert kind and supports both subtle and prominent visual styles.
+     * Features automatic icon selection based on alert kind and supports prominent (default) and subtle visual styles.
      * Use alerts to communicate important status updates, validation results, or system messages to users.
      *
      * @example
@@ -74,11 +74,10 @@
      * <SkAlert kind="success">Your changes have been saved!</SkAlert>
      * ```
      *
-     * @example Prominent warning with custom icon
+     * @example Subtle info alert
      * ```vue
-     * <SkAlert kind="warning" prominent>
-     *     <template #icon><CustomIcon /></template>
-     *     This action cannot be undone.
+     * <SkAlert kind="info" subtle>
+     *     A helpful tip for the user.
      * </SkAlert>
      * ```
      *
@@ -86,7 +85,7 @@
      * @slot icon - Custom icon to override the default kind-based icon. Receives no slot props.
      */
 
-    import { computed, toRef } from 'vue';
+    import { computed, toRef, useSlots } from 'vue';
 
     // Types
     import type { SkAlertKind } from './types';
@@ -97,32 +96,50 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
+    // Kinds that have default icons
+    const FEEDBACK_KINDS = [ 'info', 'success', 'warning', 'danger' ] as const;
+
+    //------------------------------------------------------------------------------------------------------------------
+
     export interface SkAlertComponentProps extends ComponentCustomColors
     {
         /**
-         * Semantic kind that determines the alert's color scheme and default icon. Each kind
-         * conveys a different meaning: 'info' for general information, 'success' for positive
-         * confirmations, 'warning' for cautionary messages, and 'danger' for errors or critical issues.
+         * Semantic kind that determines the alert's color scheme and default icon. Supports all
+         * semantic kinds (neutral, primary, accent, info, success, warning, danger) as well as
+         * direct color kinds (neon-blue, neon-purple, etc.). Default icons are provided for the
+         * four feedback kinds (info, success, warning, danger).
          * @default 'info'
          */
         kind ?: SkAlertKind;
 
         /**
-         * When true, applies prominent styling with a more vivid background color and stronger
-         * visual presence. Use prominent alerts for critical messages that require immediate
-         * user attention, such as errors or important warnings.
+         * When true, applies subdued styling with a lighter, semi-transparent background.
+         * Use subtle alerts for less critical messages that shouldn't dominate the visual
+         * hierarchy, such as tips or supplementary information.
          * @default false
          */
-        prominent ?: boolean;
+        subtle ?: boolean;
+
+        /**
+         * Controls visibility of the icon container. When undefined (default), the icon is shown
+         * automatically if there's a default icon for the kind (info, success, warning, danger)
+         * or if custom content is provided via the icon slot. Set to false to force-hide the icon,
+         * or true to force-show the container even when empty.
+         * @default undefined
+         */
+        showIcon ?: boolean;
     }
 
     //------------------------------------------------------------------------------------------------------------------
 
     const props = withDefaults(defineProps<SkAlertComponentProps>(), {
         kind: 'info',
-        prominent: false,
+        subtle: false,
+        showIcon: undefined,
     });
 
+    const slots = useSlots();
+
     //------------------------------------------------------------------------------------------------------------------
 
     const classes = computed(() =>
@@ -130,10 +147,26 @@
         return {
             'sk-alert': true,
             [`sk-${ props.kind }`]: true,
-            'sk-prominent': props.prominent,
+            'sk-subtle': props.subtle,
         };
     });
 
+    // Determine if we should show the icon container
+    const shouldShowIcon = computed(() =>
+    {
+        // Explicit override takes precedence
+        if(props.showIcon !== undefined)
+        {
+            return props.showIcon;
+        }
+
+        // Auto-show if kind has a default icon or if slot content is provided
+        const hasDefaultIcon = FEEDBACK_KINDS.includes(props.kind as typeof FEEDBACK_KINDS[number]);
+        const hasSlotContent = !!slots.icon;
+
+        return hasDefaultIcon || hasSlotContent;
+    });
+
     //------------------------------------------------------------------------------------------------------------------
 
     // Custom color styles

package/src/components/Alert/types.ts

@@ -2,9 +2,14 @@
 // Alert Component Types
 //----------------------------------------------------------------------------------------------------------------------
 
+// Types
+import type { ComponentKind } from '@/types';
+
+//----------------------------------------------------------------------------------------------------------------------
+
 /**
- * Alert semantic kinds (feedback-focused subset)
+ * Alert kind - supports all semantic and color kinds
  */
-export type SkAlertKind = 'info' | 'success' | 'warning' | 'danger';
+export type SkAlertKind = ComponentKind;
 
 //----------------------------------------------------------------------------------------------------------------------

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/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/_alert.scss

@@ -37,7 +37,7 @@
     /// Glow effect opacity
     --sk-alert-glow-opacity: 0.3;
 
-    /// Subtle background opacity (for non-prominent alerts)
+    /// Subtle background opacity (for default non-prominent alerts)
     --sk-alert-subtle-opacity: var(--sk-opacity-subtle);
 
     //------------------------------------------------------------------------------------------------------------------
@@ -107,8 +107,8 @@
         color: var(--sk-alert-fg);
         border-color: var(--sk-alert-border-color);
 
-        // Prominent variants get the dark foreground color
-        &.sk-prominent
+        // Non-subtle variants get the dark foreground color
+        &:not(.sk-subtle)
         {
             --sk-alert-fg: var(--sk-#{ $kind }-text);
         }
@@ -185,10 +185,10 @@
     }
 
     //------------------------------------------------------------------------------------------------------------------
-    // Prominent variant
+    // Non-subtle (prominent) variant - applied when NOT subtle
     //------------------------------------------------------------------------------------------------------------------
 
-    &.sk-prominent
+    &:not(.sk-subtle)
     {
         --sk-alert-padding: 1rem;
         --sk-alert-icon-size: 1.5rem;

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/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