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

package/src/components/Sidebar/SkSidebarSection.vue

@@ -15,20 +15,34 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * Groups sidebar items under an optional heading.
-     * Use this to organize navigation into logical sections.
+     * @component SkSidebarSection
+     * @description A grouping container for organizing related sidebar items under a common heading. Use
+     * sections to create logical categories in your navigation, such as "Getting Started", "Components",
+     * or "Settings". The section title appears as a small, muted heading above its items.
+     *
+     * @example
+     * ```vue
+     * <SkSidebarSection title="Documentation">
+     *   <SkSidebarItem as="RouterLink" to="/docs/intro">Introduction</SkSidebarItem>
+     *   <SkSidebarItem as="RouterLink" to="/docs/install">Installation</SkSidebarItem>
+     *   <SkSidebarItem as="RouterLink" to="/docs/config">Configuration</SkSidebarItem>
+     * </SkSidebarSection>
+     * ```
+     *
+     * @slot default - Container for SkSidebarItem components. Items are rendered as a vertical list
+     *                 below the section title (if provided).
      */
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * Groups sidebar items under an optional heading.
-     * Use this to organize navigation into logical sections.
-     */
     export interface SkSidebarSectionComponentProps
     {
-        /** Optional section heading */
+        /**
+         * The heading text displayed above the section's navigation items. When provided, renders
+         * as an h3 element with muted styling to visually separate it from the navigation links.
+         * When omitted, the section renders without a heading, useful for ungrouped items or
+         * when you want spacing between groups without labels.
+         */
         title ?: string;
     }
 

package/src/components/Skeleton/SkSkeleton.vue

@@ -16,8 +16,39 @@
 <script setup lang="ts">
     /**
      * @component SkSkeleton
-     * A loading placeholder component with shimmer or pulse animation.
-     * Use to indicate loading state while content is being fetched.
+     * @description A loading placeholder component that displays animated shapes to indicate content is being fetched.
+     * Skeletons improve perceived performance by showing users the expected layout before data arrives. Supports
+     * multiple shape variants (text, rectangular, circular, square) with customizable dimensions and beveled corners
+     * to match the design system aesthetic.
+     *
+     * @example
+     * ```vue
+     * <!-- Text placeholder -->
+     * <SkSkeleton variant="text" width="200px" />
+     *
+     * <!-- Avatar placeholder -->
+     * <SkSkeleton variant="circular" width="48px" />
+     *
+     * <!-- Card image placeholder with beveled corners -->
+     * <SkSkeleton
+     *     variant="rectangular"
+     *     width="100%"
+     *     height="200px"
+     *     :corners="['top-left', 'top-right']"
+     * />
+     * ```
+     *
+     * @example Loading card skeleton
+     * ```vue
+     * <SkCard>
+     *     <template #media>
+     *         <SkSkeleton variant="rectangular" height="180px" />
+     *     </template>
+     *     <SkSkeleton variant="text" width="70%" />
+     *     <SkSkeleton variant="text" width="100%" />
+     *     <SkSkeleton variant="text" width="40%" />
+     * </SkCard>
+     * ```
      */
 
     import { computed } from 'vue';
@@ -29,17 +60,53 @@
 
     export interface SkSkeletonComponentProps
     {
-        /** Shape variant */
+        /**
+         * The shape variant that determines the skeleton's default proportions and styling.
+         * 'text' creates a short-height line suitable for text placeholders. 'rectangular'
+         * creates a flexible rectangle for images or content blocks. 'circular' creates a
+         * round shape for avatars. 'square' creates equal width/height with beveled corners.
+         * @default 'text'
+         */
         variant ?: SkSkeletonVariant;
-        /** Width (CSS value) */
+
+        /**
+         * The width of the skeleton. Accepts any valid CSS width value (px, rem, %, etc.).
+         * For responsive layouts, use percentage values. For fixed-size elements like avatars,
+         * use pixel or rem values.
+         * @default '100%'
+         */
         width ?: string;
-        /** Height (CSS value) */
+
+        /**
+         * The height of the skeleton. Accepts any valid CSS height value. When not specified,
+         * the height is determined by the variant (text has a small fixed height, circular and
+         * square match their width). Required for rectangular variant to have visible height.
+         * @default undefined (varies by variant)
+         */
         height ?: string;
-        /** Animation style */
+
+        /**
+         * The loading animation style. 'shimmer' creates a moving gradient highlight effect
+         * that sweeps across the skeleton. 'pulse' creates a fading opacity animation.
+         * 'none' disables animation for static placeholders.
+         * @default 'shimmer'
+         */
         animation ?: SkSkeletonAnimation;
-        /** Custom corners to bevel (overrides variant default) */
+
+        /**
+         * Array of corner positions to bevel, overriding the variant's default corner styling.
+         * Use this for skeletons that need to match specific card or panel layouts where only
+         * certain corners are beveled. Options: 'top-left', 'top-right', 'bottom-right', 'bottom-left'.
+         * @default undefined (uses variant default)
+         */
         corners ?: SkSkeletonCorner[];
-        /** Custom bevel size (CSS value, e.g. '0.5rem', '8px') */
+
+        /**
+         * Custom bevel size for beveled corners. Accepts any valid CSS length value.
+         * Only applies when `corners` prop is provided. Use this to match the bevel size
+         * of the component the skeleton is replacing.
+         * @default '0.5rem'
+         */
         bevel ?: string;
     }
 

package/src/components/Slider/SkSlider.vue

@@ -34,9 +34,20 @@
 <script setup lang="ts">
     /**
      * @component SkSlider
-     * A range slider component for selecting numeric values.
-     * Supports single and multi-thumb (range) modes.
-     * Powered by RekaUI with all 7 semantic kinds and custom colors.
+     * @description A range slider component for selecting numeric values within a defined range. Supports both
+     * single-value selection and multi-thumb range selection modes. Built on RekaUI's Slider primitive with
+     * full keyboard accessibility, beveled styling, and horizontal or vertical orientation.
+     *
+     * @example
+     * ```vue
+     * <!-- Single value slider -->
+     * <SkSlider v-model="volume" :min="0" :max="100" kind="primary" />
+     *
+     * <!-- Range slider with two thumbs -->
+     * <SkSlider v-model="priceRange" :min="0" :max="1000" :step="10" />
+     * ```
+     *
+     * @slot - Not applicable. This component does not accept slot content.
      */
 
     import { computed } from 'vue';
@@ -50,29 +61,94 @@
 
     export interface SkSliderComponentProps
     {
-        /** Current value(s) of the slider */
+        /**
+         * The current value(s) of the slider. Pass a single number for a standard slider,
+         * or an array of numbers to create a range slider with multiple thumbs. The number
+         * of thumbs automatically matches the length of the array.
+         */
         modelValue : number | number[];
-        /** Minimum value */
+
+        /**
+         * The minimum allowed value for the slider. The leftmost (or bottommost for vertical)
+         * position of the thumb corresponds to this value. Values outside the min/max range
+         * are clamped automatically.
+         * @default 0
+         */
         min ?: number;
-        /** Maximum value */
+
+        /**
+         * The maximum allowed value for the slider. The rightmost (or topmost for vertical)
+         * position of the thumb corresponds to this value. Values outside the min/max range
+         * are clamped automatically.
+         * @default 100
+         */
         max ?: number;
-        /** Step increment */
+
+        /**
+         * The granularity of the slider. The value will snap to multiples of this step.
+         * For example, a step of 5 on a 0-100 slider allows values 0, 5, 10, ..., 100.
+         * Use smaller steps for fine-grained control or larger steps for discrete selections.
+         * @default 1
+         */
         step ?: number;
-        /** Semantic color kind */
+
+        /**
+         * Semantic color kind that controls the filled track and thumb appearance. Semantic
+         * kinds (neutral, primary, accent, etc.) adapt to your theme. Use custom colors via
+         * `baseColor` and `thumbColor` props for branding-specific styling.
+         * @default 'primary'
+         */
         kind ?: ComponentKind;
-        /** Slider size */
+
+        /**
+         * Size of the slider track and thumb. Controls the visual thickness of the track
+         * and diameter of the thumb. Available sizes: 'sm' (small), 'md' (medium), 'lg' (large).
+         * @default 'md'
+         */
         size ?: SkSliderSize;
-        /** Slider orientation */
+
+        /**
+         * Orientation of the slider layout. Use 'horizontal' for left-to-right value increase,
+         * or 'vertical' for bottom-to-top value increase. Keyboard navigation arrows adapt
+         * automatically based on orientation.
+         * @default 'horizontal'
+         */
         orientation ?: SkSliderOrientation;
-        /** Whether the slider is disabled */
+
+        /**
+         * When true, the slider is disabled and cannot be interacted with. The slider
+         * appears with reduced opacity and the cursor changes to not-allowed. Thumb
+         * positions remain visible but cannot be moved.
+         * @default false
+         */
         disabled ?: boolean;
-        /** Name attribute for form submission */
+
+        /**
+         * The form field name used when submitting the slider value in a form.
+         * Required for native form submission. Each thumb value is submitted separately.
+         */
         name ?: string;
-        /** Minimum steps between thumbs for range slider */
+
+        /**
+         * For range sliders (multiple thumbs), the minimum number of steps that must
+         * separate adjacent thumbs. Prevents thumbs from overlapping or crossing each
+         * other. A value of 0 allows thumbs to touch but not cross.
+         * @default 0
+         */
         minStepsBetweenThumbs ?: number;
-        /** Custom track color (overrides kind) */
+
+        /**
+         * Custom color for the filled portion of the track. Overrides the `kind` prop
+         * color when set. Use any valid CSS color value (hex, rgb, oklch, etc.).
+         * For complete customization, combine with `thumbColor`.
+         */
         baseColor ?: string;
-        /** Custom thumb color */
+
+        /**
+         * Custom color for the slider thumb(s). Independent of the track color, allowing
+         * two-tone designs. Use any valid CSS color value. If not set, the thumb inherits
+         * styling from the current theme.
+         */
         thumbColor ?: string;
     }
 

package/src/components/Spinner/SkSpinner.vue

@@ -41,8 +41,29 @@
 <script setup lang="ts">
     /**
      * @component SkSpinner
-     * An animated loading spinner component with multiple variants.
-     * Supports all 7 semantic kinds and custom colors.
+     * @description An animated loading indicator component with multiple visual variants. Use spinners to indicate
+     * that content is loading or an action is in progress. The component includes appropriate ARIA attributes
+     * (role="status", aria-live="polite") for screen reader accessibility.
+     *
+     * @example
+     * ```vue
+     * <SkSpinner kind="primary" />
+     * ```
+     *
+     * @example Different variants
+     * ```vue
+     * <SkSpinner variant="circular" />
+     * <SkSpinner variant="dots" />
+     * <SkSpinner variant="crosshair" />
+     * ```
+     *
+     * @example Loading button state
+     * ```vue
+     * <SkButton :disabled="loading">
+     *     <SkSpinner v-if="loading" size="sm" color="currentColor" />
+     *     <span v-else>Submit</span>
+     * </SkButton>
+     * ```
      */
 
     import { computed } from 'vue';
@@ -55,13 +76,36 @@
 
     export interface SkSpinnerComponentProps
     {
-        /** Semantic color kind */
+        /**
+         * Semantic color kind that controls the spinner color. Semantic kinds (neutral, primary,
+         * accent, etc.) adapt to your theme. Use 'primary' for general loading states, or match
+         * the kind to the context (e.g., 'danger' when loading after an error action).
+         * @default 'primary'
+         */
         kind ?: ComponentKind;
-        /** Spinner size */
+
+        /**
+         * Size of the spinner. Controls both the spinner dimensions and animation scale.
+         * Use 'sm' for inline loading indicators (e.g., inside buttons), 'md' for standard
+         * loading states, and 'lg' or 'xl' for full-page or section loading overlays.
+         * @default 'md'
+         */
         size ?: SkSpinnerSize;
-        /** Animation variant */
+
+        /**
+         * Animation variant that determines the spinner's visual style:
+         * - 'circular': Two concentric spinning arcs (default, most common)
+         * - 'dots': Three bouncing dots in sequence
+         * - 'crosshair': Rotating crosshair pattern (fits cyberpunk aesthetic)
+         * @default 'circular'
+         */
         variant ?: SkSpinnerVariant;
-        /** Custom spinner color (overrides kind) */
+
+        /**
+         * Custom color for the spinner, overriding the `kind` color. Accepts any valid CSS
+         * color value. Use "currentColor" to inherit the text color from the parent element,
+         * which is useful for spinners inside buttons or other colored containers.
+         */
         color ?: string;
     }
 

package/src/components/Switch/SkSwitch.vue

@@ -61,63 +61,126 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A toggle switch component for binary choices powered by RekaUI.
-     * Supports dynamic labels that change based on state and flexible styling options.
+     * @component SkSwitch
+     * @description A toggle switch component for binary on/off choices. Built on RekaUI's Switch primitive with
+     * full keyboard accessibility (Space/Enter to toggle). Supports dynamic labels that animate when the state
+     * changes and separate theming for the track and thumb. Use with `v-model` for two-way binding.
+     *
+     * @example
+     * ```vue
+     * <SkSwitch v-model="enabled" label="Enable notifications" />
+     * <SkSwitch v-model="darkMode" label-on="Dark" label-off="Light" kind="primary" />
+     * <SkSwitch v-model="premium" base-color="oklch(0.7 0.25 45)" label="Premium" />
+     * ```
+     *
+     * @slot default - Custom label content that overrides all label props. Use for complex labels with icons.
+     * @slot label-on - Custom content for the "on" state label. Overrides `labelOn` prop when provided.
+     * @slot label-off - Custom content for the "off" state label. Overrides `labelOff` prop when provided.
      */
 
     import { computed, toRef, useSlots } from 'vue';
     import { SwitchRoot, SwitchThumb } from 'reka-ui';
-    import type { SkSwitchKind, SkSwitchSize } from './types';
+
+    // Types
     import type { ComponentCustomColors } from '@/types';
+    import type { SkSwitchKind, SkSwitchSize } from './types';
+
+    // Composables
     import { useCustomColors } from '@/composables/useCustomColors';
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A toggle switch component for binary choices powered by RekaUI.
-     * Supports dynamic labels that change based on state and flexible styling options.
-     *
-     * @example Basic switch
-     * ```vue
-     * <SkSwitch v-model="enabled" label="Enable notifications" />
-     * ```
-     *
-     * @example Custom colors
-     * ```vue
-     * <SkSwitch
-     *   v-model="premium"
-     *   base-color="oklch(0.7 0.25 45)"
-     *   text-color="white"
-     *   label="Premium Features"
-     * />
-     * ```
-     */
     export interface SkSwitchComponentProps extends ComponentCustomColors
     {
-        /** Current state of the switch (true for on, false for off) */
+        /**
+         * The current state of the switch. `true` means on (checked), `false` means off (unchecked).
+         * Use with `v-model` for two-way binding. Required prop that must be explicitly provided.
+         */
         modelValue : boolean;
-        /** Static label text (used as fallback for labelOn/labelOff if not provided) */
+
+        /**
+         * Static label text displayed next to the switch. When `labelOn` or `labelOff` are not
+         * provided, this label remains constant regardless of switch state. Can be overridden
+         * by the default slot for custom label content.
+         * @default undefined
+         */
         label ?: string;
-        /** Label text displayed when switch is on (with animation if enabled) */
+
+        /**
+         * Label text displayed when the switch is in the "on" (true) state. When provided along
+         * with `labelOff`, the label animates between the two values as the switch toggles.
+         * Falls back to `label` prop if not provided.
+         * @default undefined
+         */
         labelOn ?: string;
-        /** Label text displayed when switch is off (with animation if enabled) */
+
+        /**
+         * Label text displayed when the switch is in the "off" (false) state. When provided along
+         * with `labelOn`, the label animates between the two values as the switch toggles.
+         * Falls back to `label` prop if not provided.
+         * @default undefined
+         */
         labelOff ?: string;
-        /** Semantic color kind for the switch background */
+
+        /**
+         * Semantic color kind for the switch track (background). Controls the color when the
+         * switch is in the "on" state. The "off" state uses a neutral muted color by default.
+         * @default 'neutral'
+         */
         kind ?: SkSwitchKind;
-        /** Semantic color kind for the switch thumb (overrides main kind) */
+
+        /**
+         * Semantic color kind for the switch thumb (the sliding circle). When provided, overrides
+         * the default thumb color derived from the main `kind`. Use for two-tone switch designs
+         * where the thumb should be a different color than the track.
+         * @default undefined
+         */
         thumbKind ?: SkSwitchKind;
-        /** Size of the switch control */
+
+        /**
+         * Switch size controlling the track dimensions, thumb size, and label text size.
+         * Available sizes: 'sm' (small), 'md' (medium, default), 'lg' (large), 'xl' (extra large).
+         * @default 'md'
+         */
         size ?: SkSwitchSize;
-        /** Whether the switch is disabled */
+
+        /**
+         * When true, disables the switch preventing all user interaction. The switch appears
+         * with reduced opacity and the cursor changes to not-allowed. Disabled switches are
+         * excluded from form submission.
+         * @default false
+         */
         disabled ?: boolean;
-        /** Whether to disable the fade animation when labels change */
+
+        /**
+         * When true, disables the fade animation when switching between `labelOn` and `labelOff`
+         * labels. The label will change instantly instead of cross-fading. Has no effect if
+         * only a static `label` is provided.
+         * @default false
+         */
         disableLabelAnimation ?: boolean;
-        /** Name attribute for form submission */
+
+        /**
+         * The form field name used when submitting the switch value. When the switch is on,
+         * the `value` prop is submitted under this name. When off, nothing is submitted
+         * (standard checkbox behavior).
+         * @default undefined
+         */
         name ?: string;
-        /** Value attribute for form submission */
+
+        /**
+         * The value submitted with the form when the switch is on. Combined with the `name`
+         * prop for form submission. When the switch is off, this value is not submitted.
+         * @default 'on'
+         */
         value ?: string;
-        /** Whether the switch is required in a form */
+
+        /**
+         * When true, marks the switch as required for form validation. The browser will prevent
+         * form submission if the switch is not in the "on" state. Use for mandatory agreements
+         * or confirmations.
+         * @default false
+         */
         required ?: boolean;
     }
 

package/src/components/Table/SkTable.vue

@@ -21,39 +21,103 @@
 
 <script setup lang="ts">
     /**
-     * @component
-     * A flexible table component with clean, rounded styling.
-     * Supports various visual styles including striping, hover effects, and custom borders.
+     * @component SkTable
+     * @description A flexible data table component with beveled corner styling and extensive visual customization.
+     * Use SkTable as a wrapper around standard HTML table elements (`<thead>`, `<tbody>`, `<tr>`, `<th>`, `<td>`).
+     * Supports row striping, hover highlighting, configurable borders, and adapts to both light and dark backgrounds.
+     *
+     * @example
+     * ```vue
+     * <SkTable striped hoverable>
+     *     <thead>
+     *         <tr><th>Name</th><th>Status</th></tr>
+     *     </thead>
+     *     <tbody>
+     *         <tr><td>Item 1</td><td>Active</td></tr>
+     *         <tr><td>Item 2</td><td>Pending</td></tr>
+     *     </tbody>
+     * </SkTable>
+     * ```
+     *
+     * @slot default - Standard HTML table content including `<thead>`, `<tbody>`, `<tfoot>`, `<tr>`, `<th>`,
+     *                 and `<td>` elements.
      */
 
     import { computed, toRef } from 'vue';
+
+    // Types
     import type { SkTableKind, SkTableVariant } from './types';
     import type { ComponentCustomColors } from '@/types';
+
+    // Composables
     import { useCustomColors } from '@/composables/useCustomColors';
 
     //------------------------------------------------------------------------------------------------------------------
 
-    /**
-     * A flexible table component with clean, rounded styling.
-     * Supports various visual styles including striping, hover effects, and custom borders.
-     */
     export interface SkTableComponentProps extends ComponentCustomColors
     {
-        /** Semantic color kind for the table */
+        /**
+         * Semantic color kind that controls header backgrounds and accent colors. The kind
+         * affects the table header row styling and can subtly influence row hover colors.
+         * Use semantic kinds to match your application's color language.
+         * @default 'neutral'
+         */
         kind ?: SkTableKind;
-        /** Visual variant style (default or compact) */
+
+        /**
+         * Controls the table's density and spacing. 'default' provides comfortable spacing
+         * for most use cases, 'compact' reduces padding for dense data displays, and
+         * 'comfortable' increases spacing for enhanced readability.
+         * @default 'default'
+         */
         variant ?: SkTableVariant;
-        /** Whether to alternate row background colors */
+
+        /**
+         * When true, alternates row background colors (zebra striping) to improve
+         * readability of wide tables. The striping color adapts to the table's kind
+         * and background context.
+         * @default false
+         */
         striped ?: boolean;
-        /** Whether rows highlight on hover */
+
+        /**
+         * When true, rows highlight on mouse hover to help users track which row
+         * they're viewing. Particularly useful for tables with many columns where
+         * the eye can lose track across the row.
+         * @default true
+         */
         hoverable ?: boolean;
-        /** Whether to show outer borders around the table */
+
+        /**
+         * When true, displays a beveled border around the entire table. Disable for
+         * a more minimal appearance or when embedding the table in a card that already
+         * provides visual containment.
+         * @default true
+         */
         bordered ?: boolean;
-        /** Whether to show borders between cells and rows */
+
+        /**
+         * When true, shows borders between individual cells and rows. Enable for
+         * grid-like data where cell boundaries need clear visual separation. Disable
+         * for a cleaner, more modern appearance.
+         * @default false
+         */
         innerBorders ?: boolean;
-        /** Whether the table has a dark background context */
+
+        /**
+         * When true, adjusts the table colors for display on dark backgrounds. This
+         * ensures proper contrast and visibility when the table is placed on dark
+         * surfaces outside of the normal theme context.
+         * @default false
+         */
         darkBackground ?: boolean;
-        /** Whether to use subtle, lighter styling */
+
+        /**
+         * When true, uses lighter, more subdued colors for the table styling. Useful
+         * when the table should not dominate the visual hierarchy or when displaying
+         * secondary data alongside more prominent content.
+         * @default false
+         */
         subtle ?: boolean;
     }