@skewedaspect/sleekspace-ui 0.2.0-beta.1

package/docs/components/tags-input.md

@@ -0,0 +1,88 @@
+---
+component: SkTagsInput
+category: Forms
+---
+
+# SkTagsInput
+
+A multi-value tag input component for entering a list of string values. Type text and press Enter to add tags; use Backspace or the delete button to remove them. Built on RekaUI's TagsInput primitive.
+
+## Usage
+
+```vue
+<script setup>
+import { ref } from 'vue';
+
+const tags = ref(['vue', 'typescript']);
+</script>
+
+<template>
+  <SkTagsInput v-model="tags" placeholder="Add tag..." kind="primary" />
+</template>
+```
+
+## Max Tags
+
+Limit the number of tags. The input field disables when the limit is reached, but existing tags can still be removed:
+
+```vue
+<SkTagsInput v-model="tags" :max="5" />
+```
+
+## Paste Support
+
+By default, pasting text adds tags (splitting on common delimiters). Disable with:
+
+```vue
+<SkTagsInput v-model="tags" :add-on-paste="false" />
+```
+
+## Tag Styling
+
+Control the appearance of the tag badges within the input:
+
+```vue
+<SkTagsInput
+  v-model="tags"
+  kind="primary"
+  tag-kind="accent"
+  tag-variant="outline"
+/>
+```
+
+## Kinds
+
+```vue
+<SkTagsInput v-model="tags" kind="primary" />
+<SkTagsInput v-model="tags" kind="accent" />
+```
+
+When nested inside SkField, the kind is automatically injected.
+
+## Sizes
+
+```vue
+<SkTagsInput v-model="tags" size="sm" />
+<SkTagsInput v-model="tags" size="md" />
+<SkTagsInput v-model="tags" size="lg" />
+```
+
+## States
+
+```vue
+<SkTagsInput v-model="tags" disabled />
+```
+
+## Custom Colors
+
+```vue
+<SkTagsInput
+  v-model="tags"
+  base-color="oklch(0.5 0.2 260)"
+  text-color="white"
+/>
+```
+
+## Accessibility
+
+Built on RekaUI TagsInput which provides keyboard management: Enter adds a tag, Backspace removes the last tag when the input is empty, and Delete buttons on individual tags are keyboard-accessible.

package/docs/components/textarea.md

@@ -0,0 +1,80 @@
+---
+component: SkTextarea
+category: Forms
+---
+
+# SkTextarea
+
+A multiline text input component with validation states and semantic color support. Automatically inherits kind from a parent SkField.
+
+## Usage
+
+```vue
+<script setup>
+import { ref } from 'vue';
+
+const message = ref('');
+</script>
+
+<template>
+  <SkTextarea v-model="message" placeholder="Write your message..." :rows="6" />
+</template>
+```
+
+## Rows
+
+Control the visible height with the `rows` prop (default: 4):
+
+```vue
+<SkTextarea v-model="val" :rows="8" />
+```
+
+## Kinds
+
+```vue
+<SkTextarea v-model="val" kind="success" placeholder="Valid" />
+<SkTextarea v-model="val" kind="danger" placeholder="Invalid" />
+```
+
+When nested inside SkField, the kind is automatically injected based on field validation state.
+
+## Sizes
+
+```vue
+<SkTextarea v-model="val" size="sm" />
+<SkTextarea v-model="val" size="md" />
+<SkTextarea v-model="val" size="lg" />
+```
+
+## States
+
+```vue
+<SkTextarea v-model="val" disabled placeholder="Disabled" />
+<SkTextarea v-model="val" readonly />
+```
+
+## Custom Colors
+
+```vue
+<SkTextarea
+  v-model="val"
+  base-color="oklch(0.5 0.15 260)"
+  text-color="white"
+/>
+```
+
+## Composition
+
+Pair with SkField for labels, descriptions, and error messages:
+
+```vue
+<SkField label="Bio" description="Tell us about yourself." :error="bioError">
+  <template #default="{ id, ...attrs }">
+    <SkTextarea :id="id" v-bind="attrs" v-model="bio" :rows="4" />
+  </template>
+</SkField>
+```
+
+## Accessibility
+
+Renders as a native `<textarea>` element. All standard HTML attributes are forwarded via `v-bind="$attrs"`. Use SkField to associate labels and error messages via `aria-describedby` and `aria-invalid`.

package/docs/components/theme.md

@@ -0,0 +1,65 @@
+---
+component: SkTheme
+category: Theming
+---
+
+# SkTheme
+
+A theme provider component that controls the color scheme for all child components. Sets a `data-scheme` attribute that CSS rules use to apply different semantic token values.
+
+## Usage
+
+```vue
+<template>
+  <SkTheme theme="colorful">
+    <SkPanel kind="primary">
+      <SkButton kind="accent">Themed Button</SkButton>
+    </SkPanel>
+  </SkTheme>
+</template>
+```
+
+## Available Themes
+
+- **greyscale** (default) -- Monochromatic palette.
+- **colorful** -- Vibrant cyberpunk colors.
+
+Custom theme names can be used if matching CSS custom property overrides are defined under the corresponding `[data-scheme="..."]` selector.
+
+## Nested Themes
+
+Themes can be nested. The inner SkTheme overrides the outer one for its subtree:
+
+```vue
+<SkTheme theme="greyscale">
+  <SkButton kind="primary">Greyscale</SkButton>
+
+  <SkTheme theme="colorful">
+    <SkButton kind="primary">Colorful</SkButton>
+  </SkTheme>
+</SkTheme>
+```
+
+## Programmatic Switching
+
+The `useTheme` composable enables runtime theme changes:
+
+```vue
+<script setup>
+import { useTheme } from '@skewedaspect/sleekspace-ui';
+
+const { currentTheme, setTheme } = useTheme();
+</script>
+
+<template>
+  <SkButton @click="setTheme('colorful')">Go Colorful</SkButton>
+</template>
+```
+
+## Portal Components
+
+SkTheme provides the current theme value via Vue's provide/inject system. Portal components (SkModal, SkDropdown, SkListbox, SkTooltip, SkPopover, SkToast) automatically consume this value and apply `data-scheme` on their portaled content so they inherit the correct theme.
+
+## Accessibility
+
+SkTheme is a transparent wrapper that does not affect the DOM semantics. It renders a single `<div>` with a `data-scheme` attribute.

package/docs/components/toast.md

@@ -0,0 +1,95 @@
+---
+component: SkToast
+category: Feedback
+---
+
+# SkToast
+
+A notification toast system for showing brief messages that appear and auto-dismiss. Composed of SkToastProvider (wraps your app) and the `useToast` composable (shows toasts from anywhere). Built on RekaUI's Toast primitive.
+
+## Usage
+
+Wrap your application with SkToastProvider, then use `useToast()` to show notifications:
+
+```vue
+<!-- App.vue -->
+<template>
+  <SkToastProvider position="top-right">
+    <RouterView />
+  </SkToastProvider>
+</template>
+```
+
+```vue
+<!-- AnyComponent.vue -->
+<script setup>
+import { useToast } from '@skewedaspect/sleekspace-ui';
+
+const toast = useToast();
+
+function save() {
+  toast.add({
+    kind: 'success',
+    title: 'Saved',
+    message: 'Your changes have been saved.',
+  });
+}
+</script>
+
+<template>
+  <SkButton @click="save">Save</SkButton>
+</template>
+```
+
+## Toast Options
+
+The `toast.add()` method accepts:
+
+- **kind** -- `info` (default), `success`, `warning`, `danger`.
+- **title** -- Optional heading text.
+- **message** -- Required message content.
+- **duration** -- Auto-dismiss time in ms. Use `0` for no auto-dismiss. Defaults to the provider's duration (5000ms).
+- **closable** -- Show a close button (default: `true`).
+
+```vue
+toast.add({
+  kind: 'danger',
+  title: 'Error',
+  message: 'Something went wrong.',
+  duration: 0,
+  closable: true,
+});
+```
+
+## Dismissing Toasts
+
+```vue
+const id = toast.add({ message: 'Processing...' });
+toast.dismiss(id);    // Dismiss specific toast
+toast.dismissAll();   // Dismiss all toasts
+```
+
+## Position
+
+Set the viewport position on the provider:
+
+```vue
+<SkToastProvider position="top-right">...</SkToastProvider>
+<SkToastProvider position="bottom-center">...</SkToastProvider>
+```
+
+Available positions: `top-left`, `top-center`, `top-right`, `bottom-left`, `bottom-center`, `bottom-right`.
+
+## Swipe to Dismiss
+
+Configure swipe behavior on the provider:
+
+```vue
+<SkToastProvider swipe-direction="left" :swipe-threshold="100">
+  ...
+</SkToastProvider>
+```
+
+## Accessibility
+
+Built on RekaUI Toast which renders notifications in a live region. Toasts are announced by screen readers as they appear. The `F8` hotkey (configurable via `hotkey` prop) focuses the toast viewport. Close buttons have `aria-label="Close"`. Content is portaled and inherits the active theme.

package/docs/components/tooltip.md

@@ -0,0 +1,90 @@
+---
+component: SkTooltip
+category: Feedback
+---
+
+# SkTooltip
+
+A hover-triggered tooltip for displaying brief supplementary information next to a trigger element. Supports standalone and provider modes for coordinated tooltip behavior. Built on RekaUI's Tooltip primitive and uses a portal.
+
+## Usage
+
+```vue
+<template>
+  <SkTooltip>
+    <template #trigger>
+      <SkButton>Hover me</SkButton>
+    </template>
+    This is the tooltip content.
+  </SkTooltip>
+</template>
+```
+
+## Standalone vs Provider Mode
+
+By default, each SkTooltip manages its own show delay. Wrap multiple tooltips in SkTooltipProvider for coordinated "skip delay" behavior -- after viewing one tooltip, moving to another shows it instantly:
+
+```vue
+<SkTooltipProvider :delay-duration="300">
+  <SkTooltip>
+    <template #trigger><SkButton>A</SkButton></template>
+    Tooltip A
+  </SkTooltip>
+  <SkTooltip>
+    <template #trigger><SkButton>B</SkButton></template>
+    Tooltip B
+  </SkTooltip>
+</SkTooltipProvider>
+```
+
+## Positioning
+
+```vue
+<SkTooltip side="right" align="start" :side-offset="8">
+  <template #trigger><SkButton>Right</SkButton></template>
+  Positioned to the right.
+</SkTooltip>
+```
+
+Available `side` values: `top` (default), `right`, `bottom`, `left`. Available `align` values: `start`, `center` (default), `end`.
+
+## Arrow
+
+The arrow is shown by default. Hide it with:
+
+```vue
+<SkTooltip :show-arrow="false">...</SkTooltip>
+```
+
+## Variants
+
+- **solid** (default) -- Filled background.
+- **outline** -- Bordered with transparent background.
+
+```vue
+<SkTooltip variant="solid">...</SkTooltip>
+<SkTooltip variant="outline">...</SkTooltip>
+```
+
+## Kinds
+
+```vue
+<SkTooltip kind="primary">...</SkTooltip>
+<SkTooltip kind="danger">...</SkTooltip>
+```
+
+## Custom Colors
+
+```vue
+<SkTooltip
+  base-color="oklch(0.3 0.1 260)"
+  text-color="white"
+>
+  <template #trigger><SkButton>Info</SkButton></template>
+  Dark purple tooltip.
+</SkTooltip>
+```
+
+## Accessibility
+
+Built on RekaUI Tooltip which shows on focus and hover, hides on Escape. The trigger receives `aria-describedby` pointing to the tooltip content. Content is portaled and inherits the active theme.

package/docs/guides/custom-colors.md

@@ -0,0 +1,84 @@
+---
+title: Custom Colors
+---
+
+# Custom Colors
+
+All visual SleekSpace components support `baseColor` and `textColor` props for one-off color overrides that bypass the semantic kind system.
+
+## baseColor and textColor Props
+
+Pass any valid CSS color value to override a component's colors:
+
+```vue
+<template>
+  <!-- OKLCH color -->
+  <SkButton
+    base-color="oklch(0.7 0.25 300)"
+    text-color="white"
+  >
+    Purple Button
+  </SkButton>
+
+  <!-- Hex color -->
+  <SkPanel base-color="#1e40af" text-color="#e0f2fe">
+    Custom blue panel
+  </SkPanel>
+
+  <!-- CSS variable -->
+  <SkAlert base-color="var(--my-brand-color)">
+    Brand-colored alert
+  </SkAlert>
+</template>
+```
+
+Accepted formats include hex, RGB, HSL, OKLCH, named CSS colors, and CSS custom properties.
+
+## How It Works
+
+When `baseColor` is provided, the component sets CSS custom properties on its root element via the `useCustomColors` composable. These override the semantic token values that the component's SCSS normally references.
+
+For a component named `button`, the composable sets:
+
+- `--sk-button-color-base` from `baseColor`
+- `--sk-button-fg` from `textColor`
+
+If `textColor` is omitted, the component falls back to `--sk-neutral-text` from the active theme.
+
+## Composable Usage (for custom components)
+
+If you are building your own component and want the same custom color behavior, use the `useCustomColors` composable:
+
+```vue
+<script setup>
+import { toRef } from 'vue';
+import { useCustomColors } from '@skewedaspect/sleekspace-ui';
+
+const props = defineProps({
+  baseColor: String,
+  textColor: String,
+});
+
+const customColorStyles = useCustomColors(
+  'my-component',
+  toRef(() => props.baseColor),
+  toRef(() => props.textColor)
+);
+</script>
+
+<template>
+  <div :style="customColorStyles">
+    <slot />
+  </div>
+</template>
+```
+
+## Interaction with kind
+
+When both `kind` and `baseColor` are provided, `baseColor` takes precedence for color values. The `kind` class may still be applied for non-color styling, but the CSS custom properties from `baseColor`/`textColor` override the semantic token colors.
+
+## Components Supporting Custom Colors
+
+Nearly all visual components accept `baseColor` and `textColor`, including: SkButton, SkPanel, SkCard, SkAlert, SkTag, SkTabs, SkInput, SkCheckbox, SkSwitch, SkRadio, SkDropdown, SkListbox, SkModal, SkTooltip, SkPopover, SkNavBar, SkSidebar, SkBreadcrumbs, SkPagination, SkAccordion, SkCollapsible, SkTagsInput, SkTextarea, and SkNumberInput.
+
+Some components use specialized color props instead (SkProgress uses `trackColor`, SkSlider uses `thumbColor`, SkSpinner uses `color`).

package/docs/guides/design-tokens.md

@@ -0,0 +1,105 @@
+---
+title: Design Tokens
+---
+
+# Design Tokens
+
+SleekSpace UI uses a three-tier token hierarchy: Foundation, Semantic, and Component. This architecture enables consistent theming while allowing granular customization.
+
+## Token Hierarchy
+
+### Foundation Tokens
+
+Primitive values that form the raw design vocabulary. These do not change with themes.
+
+- **Colors** (OKLCH): 10 hues (gray, blue, red, orange, yellow, green, mint, cyan, purple, pink) with 11 shades each (5 through 95). Pattern: `--sk-color-{hue}-{shade}`.
+- **Spacing**: `--sk-spacing-{xs|sm|md|lg|xl|2xl|3xl|4xl}`
+- **Radii**: `--sk-radius-{none|sm|md|lg|xl|2xl|full}`
+- **Border Widths**: `--sk-border-width-{thin|base|thick}`
+- **Shadows**: `--sk-shadow-{sm|md|lg|xl|2xl}`
+- **Glow Effects**: `--sk-glow-{sm|md|lg}`
+- **Typography**: Font families, sizes, weights, line heights
+- **Transitions**: `--sk-transition-duration-{fast|base|slow}`
+
+### Semantic Tokens
+
+Context-aware tokens that map to foundation values and change with the active theme. Use these for all component colors.
+
+Pattern: `--sk-{kind}-{property}`
+
+Each of the 7 semantic kinds (neutral, primary, accent, info, success, warning, danger) defines:
+
+- `--sk-{kind}-base` -- Background/base color
+- `--sk-{kind}-text` -- Foreground/text color
+- `--sk-{kind}-hover` -- Hover state color
+
+### Component Tokens
+
+Optional tokens scoped to individual components, defined inline in component SCSS files:
+
+```css
+--sk-button-height-base: 2.5rem;
+--sk-panel-padding: var(--sk-spacing-md);
+--sk-navbar-height: 4rem;
+```
+
+## Using Tokens in Custom CSS
+
+### Semantic tokens for colors
+
+```scss
+.my-component {
+  background: var(--sk-primary-base);
+  color: var(--sk-primary-text);
+
+  &:hover {
+    background: var(--sk-primary-hover);
+  }
+}
+```
+
+### Foundation tokens for non-color properties
+
+```scss
+.my-component {
+  padding: var(--sk-spacing-md);
+  border-width: var(--sk-border-width-base);
+  box-shadow: var(--sk-shadow-md);
+  transition-duration: var(--sk-transition-duration-base);
+}
+```
+
+### In JavaScript
+
+```js
+const primaryColor = getComputedStyle(document.documentElement)
+  .getPropertyValue('--sk-primary-base');
+```
+
+## OKLCH Color Space
+
+All colors use OKLCH (Oklab Lightness Chroma Hue) for perceptually uniform results:
+
+```css
+--sk-primary-base: oklch(0.65 0.2 260);
+/* 65% lightness, 0.2 chroma, 260 degrees hue (blue) */
+```
+
+Runtime shade calculation uses relative OKLCH:
+
+```css
+--color-sk-primary-70: oklch(from var(--sk-primary-base) calc(l * 0.70) c h);
+```
+
+## Token Files
+
+Foundation tokens are in `src/styles/tokens/`:
+- `_foundation-colors.scss`
+- `_foundation-spacing.scss`
+- `_foundation-radius.scss`
+- `_foundation-borders.scss`
+- `_foundation-shadows.scss`
+- `_foundation-typography.scss`
+- `_foundation-transitions.scss`
+
+Semantic tokens are in `_semantic-colors.scss`. Component tokens are defined inline in each component's SCSS file under `src/styles/components/`.