@skewedaspect/sleekspace-ui 0.2.0-beta.1 → 0.2.0-beta.3

package/docs/guides/design-tokens/themes.md

@@ -0,0 +1,38 @@
+---
+section: themes
+---
+
+## Themes
+
+Themes map foundation colors to semantic kinds. Each theme is defined as a CSS attribute selector that overrides semantic tokens.
+
+### Available Themes
+
+**Greyscale (Default):** Neutral is gray, primary is blue, accent is orange.
+
+**Colorful:** Neutral is blue, primary is orange, accent is blue.
+
+### Theme Files
+
+Themes are defined in `src/styles/themes/`. Each theme file exports a `[data-scheme="name"]` selector:
+
+```scss
+/* src/styles/themes/_mytheme.scss */
+[data-scheme='mytheme']
+{
+    --sk-neutral-base: var(--sk-color-purple-50);
+    --sk-primary-base: var(--sk-color-mint-50);
+    --sk-accent-base: var(--sk-color-orange-50);
+    /* ... define all 7 semantic kinds */
+}
+```
+
+### Using Themes
+
+Wrap your app in the `SkTheme` component:
+
+```vue
+<SkTheme theme="greyscale">
+    <YourApp />
+</SkTheme>
+```

package/docs/guides/design-tokens/usage.md

@@ -0,0 +1,55 @@
+---
+section: usage
+---
+
+## Usage Guide
+
+### When to Use Each Tier
+
+**Use Foundation Tokens when:**
+- You need a specific color shade that won't change with themes
+- Building one-off custom components outside the design system
+- Creating gradients or complex color manipulations
+
+```css
+background: var(--sk-color-blue-30);
+border: 1px solid var(--sk-color-gray-70);
+```
+
+**Use Semantic Tokens when (preferred):**
+- Building theme-aware components
+- Using semantic meaning (success, danger, etc.)
+- You want colors to change with theme switching
+
+```css
+background: var(--sk-primary-base);
+color: var(--sk-primary-text);
+border: 1px solid var(--sk-danger-base);
+```
+
+**Use Component Tokens when:**
+- Working within a component's SCSS file
+- Customizing existing components
+- Building component variations
+
+```css
+background: var(--sk-button-bg);
+color: var(--sk-button-text);
+padding: var(--sk-button-padding-base);
+```
+
+### Color Kind vs Semantic Kind
+
+Use **Semantic Kinds** (preferred) for most components:
+
+```vue
+<SkButton kind="primary">Save</SkButton>
+<SkAlert kind="danger">Error occurred</SkAlert>
+```
+
+Use **Color Kinds** when you need a specific color:
+
+```vue
+<SkButton kind="neon-purple">Special</SkButton>
+<SkPanel kind="neon-mint">Custom panel</SkPanel>
+```

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@skewedaspect/sleekspace-ui",
-  "version": "0.2.0-beta.1",
+  "version": "0.2.0-beta.3",
   "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",
@@ -27,8 +27,7 @@
   ],
   "scripts": {
     "dev": "vite build --watch",
-    "build": "npm run generate:types && vue-docgen-web-types && npm run generate:api-docs && vite build && npm run build:tokens && npm run copy:docs",
-    "generate:api-docs": "tsx scripts/generate-api-docs.ts",
+    "build": "npm run generate:types && vue-docgen-web-types && vite build && npm run build:tokens && npm run copy:docs",
     "build:tokens": "sass src/styles/tokens.scss dist/tokens.css --no-source-map",
     "copy:docs": "cp ../../Readme.md README.md && cp ../../LICENSE LICENSE",
     "generate:types": "tsx scripts/generate-global-types.ts",
@@ -50,7 +49,7 @@
   "license": "MIT",
   "repository": {
     "type": "git",
-    "url": "https://gitlab.com/skewedaspect/sleekspace-ui.git",
+    "url": "git+https://gitlab.com/skewedaspect/sleekspace-ui.git",
     "directory": "packages/sleekspace-ui"
   },
   "bugs": "https://gitlab.com/skewedaspect/sleekspace-ui/-/issues",
@@ -62,7 +61,6 @@
     "@types/node": "^24.8.1",
     "@vitejs/plugin-vue": "^6.0.1",
     "sass": "^1.83.2",
-    "ts-morph": "^27.0.2",
     "typescript": "^5.8.3",
     "vite": "^7.1.10",
     "vite-plugin-dts": "^4.5.3",

package/src/components/Accordion/SkAccordion.vue

@@ -25,9 +25,24 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * Accordion root container for collapsible sections.
-     * Use with SkAccordionItem components.
+     * @component SkAccordion
+     * @description A collapsible content container that organizes information into expandable sections. Built on
+     * RekaUI's Accordion primitive with smooth height animations and full keyboard accessibility. Supports two
+     * modes: single (only one item open at a time) or multiple (any number of items can be open simultaneously).
+     *
+     * @example
+     * ```vue
+     * <SkAccordion v-model="openItem" kind="primary">
+     *   <SkAccordionItem value="faq-1" title="What is SleekSpace?">
+     *     A Vue 3 component library with cyberpunk aesthetic.
+     *   </SkAccordionItem>
+     *   <SkAccordionItem value="faq-2" title="How do I get started?">
+     *     Install via npm and import the components you need.
+     *   </SkAccordionItem>
+     * </SkAccordion>
+     * ```
+     *
+     * @slot default - Container for SkAccordionItem components. Each item becomes a collapsible section.
      */
 
     import { computed, provide, toRef } from 'vue';
@@ -42,46 +57,45 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * Accordion root container for collapsible sections.
-     *
-     * Supports single or multiple open items with smooth animations.
-     *
-     * @example Single mode (default)
-     * ```vue
-     * <SkAccordion v-model="openItem">
-     *   <SkAccordionItem value="item-1" title="Section 1">
-     *     Content 1
-     *   </SkAccordionItem>
-     *   <SkAccordionItem value="item-2" title="Section 2">
-     *     Content 2
-     *   </SkAccordionItem>
-     * </SkAccordion>
-     * ```
-     *
-     * @example Multiple mode
-     * ```vue
-     * <SkAccordion type="multiple" v-model="openItems">
-     *   <SkAccordionItem value="item-1" title="Section 1">
-     *     Content 1
-     *   </SkAccordionItem>
-     *   <SkAccordionItem value="item-2" title="Section 2">
-     *     Content 2
-     *   </SkAccordionItem>
-     * </SkAccordion>
-     * ```
-     */
     export interface SkAccordionComponentProps extends ComponentCustomColors
     {
-        /** Single or multiple open items */
+        /**
+         * Controls whether one or multiple accordion items can be open simultaneously.
+         * In 'single' mode, opening a new item automatically closes the previously open item.
+         * In 'multiple' mode, users can expand any number of items independently.
+         * @default 'single'
+         */
         type ?: SkAccordionType;
-        /** Controlled state (v-model) */
+
+        /**
+         * The value(s) of currently open accordion item(s). Use with `v-model` for two-way binding.
+         * In 'single' mode, this is a string matching one item's `value` prop.
+         * In 'multiple' mode, this is an array of strings matching multiple items' `value` props.
+         */
         modelValue ?: string | string[];
-        /** Allow closing all items (single mode only) */
+
+        /**
+         * When true and in 'single' mode, allows all items to be collapsed by clicking the open item again.
+         * When false, one item must always remain open (the first click selects, subsequent clicks don't collapse).
+         * This prop has no effect in 'multiple' mode where items are always independently collapsible.
+         * @default false
+         */
         collapsible ?: boolean;
-        /** Semantic color kind */
+
+        /**
+         * Semantic color kind that controls the accordion's header and border colors. The kind is automatically
+         * inherited by all child SkAccordionItem components unless they specify their own kind.
+         * Semantic kinds (neutral, primary, accent, etc.) adapt to your theme.
+         * @default 'neutral'
+         */
         kind ?: SkAccordionKind;
-        /** Disable all items */
+
+        /**
+         * When true, disables all accordion items. Items cannot be expanded or collapsed, and
+         * the accordion appears with reduced opacity. Individual items can also be disabled
+         * independently via their own `disabled` prop.
+         * @default false
+         */
         disabled ?: boolean;
     }
 

package/src/components/Accordion/SkAccordionItem.vue

@@ -45,8 +45,22 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * Individual accordion item with collapsible content.
+     * @component SkAccordionItem
+     * @description An individual collapsible section within an SkAccordion container. Each item consists of a
+     * clickable header that toggles the visibility of its content panel. Features smooth height animations,
+     * an animated chevron indicator, and full keyboard navigation support (Enter/Space to toggle, arrow keys
+     * to navigate between items).
+     *
+     * @example
+     * ```vue
+     * <SkAccordionItem value="shipping" title="Shipping Information">
+     *   <p>We ship worldwide with tracking included.</p>
+     * </SkAccordionItem>
+     * ```
+     *
+     * @slot default - The collapsible content displayed when the item is expanded. Can contain any content.
+     * @slot title - Custom header content. Receives `{ open: boolean }` indicating the current expanded state.
+     *               Use this for complex headers with icons, badges, or conditional styling.
      */
 
     import { type ComputedRef, type Ref, computed, inject, ref } from 'vue';
@@ -62,29 +76,35 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * Individual accordion item with collapsible content.
-     *
-     * @example With custom title slot
-     * ```vue
-     * <SkAccordionItem value="item-1">
-     *   <template #title="{ open }">
-     *     <span>Custom Title</span>
-     *     <SkBadge v-if="open" kind="primary">Open</SkBadge>
-     *   </template>
-     *   Content here
-     * </SkAccordionItem>
-     * ```
-     */
     export interface SkAccordionItemComponentProps
     {
-        /** Required unique identifier */
+        /**
+         * A unique identifier for this accordion item. This value is used by the parent SkAccordion
+         * to track which item(s) are currently open. Must be unique among siblings within the same
+         * accordion. The value is exposed in v-model bindings on the parent accordion.
+         */
         value : string;
-        /** Title text (overridden by title slot) */
+
+        /**
+         * Text displayed in the accordion item's header/trigger button. This is the clickable
+         * area that expands or collapses the content. Can be overridden with the `title` slot
+         * for custom header content including icons, badges, or formatted text.
+         */
         title ?: string;
-        /** Disable this item */
+
+        /**
+         * When true, this specific accordion item cannot be expanded or collapsed. The item
+         * appears with reduced opacity and the cursor changes to not-allowed. If the item
+         * was already open when disabled, it remains in its current state.
+         * @default false
+         */
         disabled ?: boolean;
-        /** Override parent kind */
+
+        /**
+         * Overrides the semantic color kind inherited from the parent SkAccordion. Use this
+         * to highlight specific items differently, such as marking one section as 'warning'
+         * or 'danger'. When not specified, the item uses the parent accordion's kind.
+         */
         kind ?: SkAccordionKind;
     }
 

package/src/components/Alert/SkAlert.vue

@@ -64,45 +64,55 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A flexible alert component for displaying informational messages.
-     * Supports multiple semantic kinds (info, success, warning, danger) with optional prominent styling.
+     * @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.
+     * Use alerts to communicate important status updates, validation results, or system messages to users.
+     *
+     * @example
+     * ```vue
+     * <SkAlert kind="success">Your changes have been saved!</SkAlert>
+     * ```
+     *
+     * @example Prominent warning with custom icon
+     * ```vue
+     * <SkAlert kind="warning" prominent>
+     *     <template #icon><CustomIcon /></template>
+     *     This action cannot be undone.
+     * </SkAlert>
+     * ```
+     *
+     * @slot default - The alert message content. Can include text, links, or any HTML content.
+     * @slot icon - Custom icon to override the default kind-based icon. Receives no slot props.
      */
 
     import { computed, toRef } from 'vue';
+
+    // Types
     import type { SkAlertKind } from './types';
     import type { ComponentCustomColors } from '@/types';
+
+    // Composables
     import { useCustomColors } from '@/composables/useCustomColors';
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A flexible alert component for displaying informational messages.
-     * Supports multiple semantic kinds (info, success, warning, danger) with optional prominent styling.
-     *
-     * @example Basic alert
-     * ```vue
-     * <SkAlert kind="success">
-     *   Your changes have been saved!
-     * </SkAlert>
-     * ```
-     *
-     * @example Custom colors
-     * ```vue
-     * <SkAlert
-     *   base-color="oklch(0.65 0.25 280)"
-     *   text-color="white"
-     *   prominent
-     * >
-     *   Custom purple alert with custom colors
-     * </SkAlert>
-     * ```
-     */
     export interface SkAlertComponentProps extends ComponentCustomColors
     {
-        /** Semantic kind determining the alert color and icon (info, success, warning, danger) */
+        /**
+         * 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.
+         * @default 'info'
+         */
         kind ?: SkAlertKind;
-        /** Whether to use prominent styling with darker background and bolder appearance */
+
+        /**
+         * 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.
+         * @default false
+         */
         prominent ?: boolean;
     }
 

package/src/components/Avatar/SkAvatar.vue

@@ -39,9 +39,30 @@
 <script setup lang="ts">
     /**
      * @component SkAvatar
-     * A user profile avatar component with image, initials, or icon fallback.
-     * Square shape with beveled top-left and bottom-right corners.
-     * Supports all 7 semantic kinds and custom colors.
+     * @description A user profile avatar component displaying an image, initials, or placeholder icon. Features a
+     * distinctive square shape with beveled top-left and bottom-right corners matching the SleekSpace design system.
+     * Implements graceful degradation: shows image if provided and loads successfully, falls back to initials if
+     * specified, otherwise displays a generic user icon. Supports all semantic color kinds and custom colors.
+     *
+     * @example
+     * ```vue
+     * <!-- With image -->
+     * <SkAvatar src="/avatars/user.jpg" alt="Jane Doe" size="lg" />
+     *
+     * <!-- With initials fallback -->
+     * <SkAvatar src="/avatars/user.jpg" initials="JD" kind="primary" />
+     *
+     * <!-- Initials only -->
+     * <SkAvatar initials="AB" kind="accent" size="xl" />
+     *
+     * <!-- Custom icon fallback -->
+     * <SkAvatar kind="info">
+     *   <template #icon><RobotIcon /></template>
+     * </SkAvatar>
+     * ```
+     *
+     * @slot icon - Custom fallback icon displayed when no image or initials are provided. Defaults to a generic
+     *   user silhouette icon. Use for bots, system users, or other non-person entities.
      */
 
     import { computed, ref } from 'vue';
@@ -54,19 +75,57 @@
 
     export interface SkAvatarComponentProps
     {
-        /** Image source URL */
+        /**
+         * URL of the avatar image to display. When provided, the component attempts to load and display
+         * this image. If the image fails to load (404, network error, etc.), the component automatically
+         * falls back to initials or the default icon. Supports any valid image URL including data URIs.
+         */
         src ?: string;
-        /** Alt text for image */
+
+        /**
+         * Alternative text for the avatar image, used for accessibility. Screen readers announce this
+         * text, so provide meaningful descriptions like "Jane Doe's profile photo" rather than generic
+         * text like "avatar". Only applies when displaying an image.
+         * @default ''
+         */
         alt ?: string;
-        /** Fallback initials (1-2 characters) */
+
+        /**
+         * Fallback text to display when no image is provided or the image fails to load. Typically
+         * a user's initials (first and last name letters). Automatically truncated to 2 characters
+         * and uppercased. If neither src nor initials are provided, displays the default user icon.
+         */
         initials ?: string;
-        /** Semantic color kind */
+
+        /**
+         * Semantic color kind that controls the avatar's background and text colors when displaying
+         * initials or the fallback icon. Has no visible effect when displaying an image. Semantic kinds
+         * (neutral, primary, accent, info, success, warning, danger) adapt to your theme.
+         * @default 'neutral'
+         */
         kind ?: ComponentKind;
-        /** Avatar size */
+
+        /**
+         * Avatar size controlling both dimensions and text/icon scaling. Available sizes: 'xs' (extra
+         * small, 24px), 'sm' (small, 32px), 'md' (medium, 40px), 'lg' (large, 48px), 'xl' (extra large,
+         * 64px), '2xl' (double extra large, 80px). Choose based on context: 'sm' for lists, 'lg' for
+         * profile headers, 'xl' for profile pages.
+         * @default 'md'
+         */
         size ?: SkAvatarSize;
-        /** Custom background color (overrides kind) */
+
+        /**
+         * Custom background color that overrides the kind's default. Use for brand colors, user-selected
+         * colors, or dynamically generated colors based on user ID. Accepts any valid CSS color value.
+         * Only visible when displaying initials or the fallback icon.
+         */
         baseColor ?: string;
-        /** Custom text color */
+
+        /**
+         * Custom text/icon color that overrides the kind's default. Should provide sufficient contrast
+         * against baseColor for accessibility. Accepts any valid CSS color value. Only visible when
+         * displaying initials or the fallback icon.
+         */
         textColor ?: string;
     }
 

package/src/components/Breadcrumbs/SkBreadcrumbItem.vue

@@ -1,3 +1,7 @@
+<!----------------------------------------------------------------------------------------------------------------------
+  - Breadcrumb Item Component
+  --------------------------------------------------------------------------------------------------------------------->
+
 <template>
     <li class="sk-breadcrumb-item">
         <component
@@ -23,6 +27,34 @@
 <!--------------------------------------------------------------------------------------------------------------------->
 
 <script setup lang="ts">
+    /**
+     * @component SkBreadcrumbItem
+     * @description A single item within a breadcrumb navigation trail representing one level in the hierarchy.
+     * Automatically renders as the appropriate element type based on props: `RouterLink` for Vue Router
+     * navigation, `<a>` for external links, `<span>` for current/disabled items, or `<button>` for click handlers.
+     *
+     * @example
+     * ```vue
+     * <!-- Vue Router link -->
+     * <SkBreadcrumbItem to="/dashboard">Dashboard</SkBreadcrumbItem>
+     *
+     * <!-- External link -->
+     * <SkBreadcrumbItem href="https://docs.example.com">Docs</SkBreadcrumbItem>
+     *
+     * <!-- Current page (non-interactive) -->
+     * <SkBreadcrumbItem current>Settings</SkBreadcrumbItem>
+     *
+     * <!-- With icon -->
+     * <SkBreadcrumbItem to="/">
+     *     <template #icon><HomeIcon /></template>
+     *     Home
+     * </SkBreadcrumbItem>
+     * ```
+     *
+     * @slot default - The breadcrumb label text or custom content.
+     * @slot icon - Optional icon displayed before the label. Useful for home icons or category indicators.
+     */
+
     import { computed, inject } from 'vue';
     import { RouterLink } from 'vue-router';
 
@@ -31,7 +63,37 @@
 
     //------------------------------------------------------------------------------------------------------------------
 
-    export type SkBreadcrumbItemComponentProps = SkBreadcrumbItemProps;
+    export interface SkBreadcrumbItemComponentProps
+    {
+        /**
+         * Vue Router destination for client-side navigation. When provided, the item renders as a
+         * `RouterLink` component. Accepts any valid `RouteLocationRaw` value including path strings,
+         * named routes, and route objects with params.
+         */
+        to ?: SkBreadcrumbItemProps['to'];
+
+        /**
+         * URL for standard anchor link navigation. When provided (and `to` is not set), the item
+         * renders as an `<a>` element. Use this for external links or non-Vue-Router navigation.
+         */
+        href ?: string;
+
+        /**
+         * When true, marks this item as the current page in the breadcrumb trail. The item renders
+         * as a non-interactive `<span>` and receives `aria-current="page"` for accessibility.
+         * Typically used on the last item in the breadcrumb list.
+         * @default false
+         */
+        current ?: boolean;
+
+        /**
+         * When true, the item is disabled and cannot be interacted with. The item renders as a
+         * non-interactive `<span>` with reduced opacity. Use for items that represent inaccessible
+         * or locked sections of the application.
+         * @default false
+         */
+        disabled ?: boolean;
+    }
 
     //------------------------------------------------------------------------------------------------------------------
 

package/src/components/Breadcrumbs/SkBreadcrumbSeparator.vue

@@ -1,3 +1,7 @@
+<!----------------------------------------------------------------------------------------------------------------------
+  - Breadcrumb Separator Component
+  --------------------------------------------------------------------------------------------------------------------->
+
 <template>
     <span class="sk-breadcrumb-separator" aria-hidden="true">
         {{ displaySeparator }}
@@ -13,14 +17,39 @@
 <!--------------------------------------------------------------------------------------------------------------------->
 
 <script setup lang="ts">
+    /**
+     * @component SkBreadcrumbSeparator
+     * @description A visual separator displayed between breadcrumb items. Typically used internally by
+     * `SkBreadcrumbs`, but can be used directly when you need custom separator patterns or want to
+     * place separators manually. The separator is hidden from screen readers via `aria-hidden`.
+     *
+     * @example
+     * ```vue
+     * <!-- Manual separator usage -->
+     * <SkBreadcrumbItem to="/">Home</SkBreadcrumbItem>
+     * <SkBreadcrumbSeparator separator=">" />
+     * <SkBreadcrumbItem current>Settings</SkBreadcrumbItem>
+     * ```
+     */
+
     import { computed, inject } from 'vue';
 
-    // Types
-    import type { SkBreadcrumbSeparatorProps } from './types';
+    //------------------------------------------------------------------------------------------------------------------
+
+    export interface SkBreadcrumbSeparatorComponentProps
+    {
+        /**
+         * Custom separator character or string to display. When not provided, inherits the separator
+         * from the parent `SkBreadcrumbs` component. Use this to override specific separators while
+         * keeping others consistent with the parent setting.
+         * @default '/' (inherited from parent)
+         */
+        separator ?: string;
+    }
 
     //------------------------------------------------------------------------------------------------------------------
 
-    const props = withDefaults(defineProps<SkBreadcrumbSeparatorProps>(), {
+    const props = withDefaults(defineProps<SkBreadcrumbSeparatorComponentProps>(), {
         separator: undefined,
     });