@skewedaspect/sleekspace-ui 0.2.0-beta.1

package/docs/components/accordion.md

@@ -0,0 +1,92 @@
+---
+component: SkAccordion
+category: Layout
+---
+
+# SkAccordion
+
+A collapsible sections container for organizing content into expandable panels. Supports single or multiple open items with smooth animations. Built on RekaUI's Accordion primitive.
+
+## Usage
+
+```vue
+<script setup>
+import { ref } from 'vue';
+
+const openItem = ref('item-1');
+</script>
+
+<template>
+  <SkAccordion v-model="openItem" kind="primary">
+    <SkAccordionItem value="item-1" title="Section One">
+      Content for section one.
+    </SkAccordionItem>
+    <SkAccordionItem value="item-2" title="Section Two">
+      Content for section two.
+    </SkAccordionItem>
+  </SkAccordion>
+</template>
+```
+
+## Single vs Multiple Mode
+
+By default, only one item can be open at a time (`type="single"`). Set `type="multiple"` to allow several items to be expanded simultaneously:
+
+```vue
+<script setup>
+import { ref } from 'vue';
+
+const openItems = ref(['item-1']);
+</script>
+
+<template>
+  <SkAccordion type="multiple" v-model="openItems">
+    <SkAccordionItem value="item-1" title="First">...</SkAccordionItem>
+    <SkAccordionItem value="item-2" title="Second">...</SkAccordionItem>
+    <SkAccordionItem value="item-3" title="Third">...</SkAccordionItem>
+  </SkAccordion>
+</template>
+```
+
+In single mode, set `collapsible` to allow closing all items (by default, one item always stays open).
+
+## Kinds
+
+The `kind` prop on SkAccordion is inherited by all child items:
+
+```vue
+<SkAccordion kind="accent">
+  <SkAccordionItem value="a" title="Accent Item">...</SkAccordionItem>
+</SkAccordion>
+```
+
+Individual items can override the parent kind with their own `kind` prop.
+
+## Slots
+
+SkAccordionItem exposes a `title` slot for custom header content:
+
+```vue
+<SkAccordionItem value="item-1">
+  <template #title="{ open }">
+    <span>Custom Title</span>
+    <SkTag v-if="open" kind="primary" size="sm">Open</SkTag>
+  </template>
+  Panel content here.
+</SkAccordionItem>
+```
+
+## Custom Colors
+
+```vue
+<SkAccordion
+  base-color="oklch(0.6 0.2 280)"
+  text-color="white"
+>
+  <SkAccordionItem value="a" title="Custom Colors">...</SkAccordionItem>
+</SkAccordion>
+```
+
+## Accessibility
+
+Built on RekaUI Accordion which provides full WAI-ARIA accordion pattern support. Keyboard navigation with Arrow keys moves focus between headers, Enter/Space toggles the focused item, and Home/End jump to first/last header.

package/docs/components/alert.md

@@ -0,0 +1,72 @@
+---
+component: SkAlert
+category: Feedback
+---
+
+# SkAlert
+
+A feedback component for displaying informational messages. Each kind renders a corresponding icon (info circle, checkmark, warning triangle, or error cross) alongside the message content.
+
+## Usage
+
+```vue
+<template>
+  <SkAlert kind="success">
+    Your changes have been saved.
+  </SkAlert>
+</template>
+```
+
+## Kinds
+
+Alert supports a focused subset of semantic kinds: `info` (default), `success`, `warning`, and `danger`. Each kind includes a matching SVG icon.
+
+```vue
+<template>
+  <SkAlert kind="info">Informational note.</SkAlert>
+  <SkAlert kind="success">Operation completed.</SkAlert>
+  <SkAlert kind="warning">Proceed with caution.</SkAlert>
+  <SkAlert kind="danger">An error occurred.</SkAlert>
+</template>
+```
+
+## Variants
+
+Set `prominent` to apply a bolder, darker background style:
+
+```vue
+<SkAlert kind="danger" prominent>
+  Critical system failure.
+</SkAlert>
+```
+
+## Slots
+
+The `icon` slot replaces the default kind-specific icon:
+
+```vue
+<SkAlert kind="info">
+  <template #icon>
+    <MyCustomIcon />
+  </template>
+  Custom icon alert.
+</SkAlert>
+```
+
+The default slot holds the message content.
+
+## Custom Colors
+
+```vue
+<SkAlert
+  base-color="oklch(0.65 0.25 280)"
+  text-color="white"
+  prominent
+>
+  Custom purple alert.
+</SkAlert>
+```
+
+## Accessibility
+
+Renders with `role="alert"` which announces the content to screen readers when it appears in the DOM.

package/docs/components/avatar.md

@@ -0,0 +1,69 @@
+---
+component: SkAvatar
+category: Feedback
+---
+
+# SkAvatar
+
+A user profile avatar component with three fallback levels: image, initials, and a default person icon. Renders as a square with beveled top-left and bottom-right corners.
+
+## Usage
+
+```vue
+<template>
+  <SkAvatar src="/photo.jpg" alt="Jane Doe" />
+</template>
+```
+
+## Fallback Chain
+
+The avatar displays content in priority order:
+
+1. **Image** -- If `src` is provided and loads successfully.
+2. **Initials** -- If the image fails or no `src`, displays up to 2 uppercase characters from `initials`.
+3. **Icon** -- Falls back to a default person silhouette SVG, or content from the `icon` slot.
+
+```vue
+<template>
+  <!-- Image avatar -->
+  <SkAvatar src="/photo.jpg" alt="Jane" />
+
+  <!-- Initials avatar -->
+  <SkAvatar initials="JD" kind="primary" />
+
+  <!-- Default icon avatar -->
+  <SkAvatar kind="accent" />
+</template>
+```
+
+## Sizes
+
+```vue
+<SkAvatar size="xs" initials="XS" />
+<SkAvatar size="sm" initials="SM" />
+<SkAvatar size="md" initials="MD" />
+<SkAvatar size="lg" initials="LG" />
+<SkAvatar size="xl" initials="XL" />
+```
+
+## Kinds
+
+```vue
+<SkAvatar kind="primary" initials="PR" />
+<SkAvatar kind="accent" initials="AC" />
+<SkAvatar kind="success" initials="OK" />
+```
+
+## Custom Colors
+
+```vue
+<SkAvatar
+  base-color="oklch(0.6 0.25 300)"
+  text-color="white"
+  initials="AB"
+/>
+```
+
+## Accessibility
+
+Provide meaningful `alt` text when using image avatars. For initials-only or icon avatars, surrounding context should convey the user identity.

package/docs/components/breadcrumbs.md

@@ -0,0 +1,65 @@
+---
+component: SkBreadcrumbs
+category: Navigation
+---
+
+# SkBreadcrumbs
+
+A navigation breadcrumb trail showing the current page location within a hierarchy. Automatically inserts separator characters between items.
+
+## Usage
+
+```vue
+<template>
+  <SkBreadcrumbs>
+    <SkBreadcrumbItem href="/">Home</SkBreadcrumbItem>
+    <SkBreadcrumbItem href="/docs">Docs</SkBreadcrumbItem>
+    <SkBreadcrumbItem current>Button</SkBreadcrumbItem>
+  </SkBreadcrumbs>
+</template>
+```
+
+## Separator
+
+The default separator is `/`. Override it with the `separator` prop:
+
+```vue
+<SkBreadcrumbs separator=">">
+  <SkBreadcrumbItem href="/">Home</SkBreadcrumbItem>
+  <SkBreadcrumbItem current>Page</SkBreadcrumbItem>
+</SkBreadcrumbs>
+```
+
+## Item Rendering
+
+SkBreadcrumbItem renders as different elements based on its props:
+
+- **`to`** -- Renders as `<router-link>` for Vue Router navigation.
+- **`href`** -- Renders as `<a>` for standard links.
+- **`current`** or **`disabled`** -- Renders as `<span>` (non-interactive).
+- **No navigation prop** -- Renders as `<button>`.
+
+## Kinds
+
+```vue
+<SkBreadcrumbs kind="primary">
+  <SkBreadcrumbItem href="/">Home</SkBreadcrumbItem>
+  <SkBreadcrumbItem current>Current Page</SkBreadcrumbItem>
+</SkBreadcrumbs>
+```
+
+## Custom Colors
+
+```vue
+<SkBreadcrumbs
+  base-color="oklch(0.7 0.2 260)"
+  text-color="white"
+>
+  <SkBreadcrumbItem href="/">Home</SkBreadcrumbItem>
+  <SkBreadcrumbItem current>Page</SkBreadcrumbItem>
+</SkBreadcrumbs>
+```
+
+## Accessibility
+
+Renders inside a `<nav>` element with `aria-label="Breadcrumb"`. The current page item receives `aria-current="page"`. Disabled items are non-interactive.

package/docs/components/button/_meta.yaml

@@ -0,0 +1,12 @@
+component: SkButton
+category: Forms
+sections:
+  - intro
+  - usage
+  - variants
+  - kinds
+  - sizes
+  - icons
+  - states
+  - custom-colors
+  - accessibility

package/docs/components/button/accessibility.md

@@ -0,0 +1,16 @@
+---
+section: accessibility
+order: 9
+---
+
+Renders with appropriate semantics based on usage. Loading state sets `aria-busy="true"`. Pressed state sets `aria-pressed="true"` for toggle buttons. Disabled buttons use the native `disabled` attribute.
+
+When using icon-only buttons, provide an `aria-label` for screen readers:
+
+```vue
+<SkButton kind="danger" aria-label="Delete item">
+    <template #icon>
+        <FontAwesomeIcon :icon="['fasds', 'trash']" />
+    </template>
+</SkButton>
+```

package/docs/components/button/custom-colors.md

@@ -0,0 +1,18 @@
+---
+section: custom-colors
+order: 8
+---
+
+Use `base-color` for any CSS color value. Text color is automatically calculated for optimal contrast, or override with `text-color`.
+
+```vue
+<SkButton variant="solid" base-color="#8B5CF6">
+    Custom Purple
+</SkButton>
+<SkButton variant="solid" base-color="oklch(0.7 0.25 300)" text-color="white">
+    OKLCH Color
+</SkButton>
+<SkButton variant="outline" base-color="oklch(0.75 0.2 180)">
+    Custom Teal
+</SkButton>
+```

package/docs/components/button/icons.md

@@ -0,0 +1,31 @@
+---
+section: icons
+order: 6
+---
+
+Use `icon`, `leading`, or `trailing` slots. Icon-only buttons automatically become square.
+
+```vue
+<!-- Icon-only button -->
+<SkButton kind="primary">
+    <template #icon>
+        <FontAwesomeIcon :icon="['fasds', 'plus']" />
+    </template>
+</SkButton>
+
+<!-- Button with leading icon -->
+<SkButton kind="primary">
+    <template #leading>
+        <FontAwesomeIcon :icon="['fasds', 'plus']" />
+    </template>
+    With Leading Icon
+</SkButton>
+
+<!-- Button with trailing icon -->
+<SkButton kind="primary">
+    With Trailing Icon
+    <template #trailing>
+        <FontAwesomeIcon :icon="['fasds', 'chevron-right']" />
+    </template>
+</SkButton>
+```

package/docs/components/button/intro.md

@@ -0,0 +1,8 @@
+---
+section: intro
+order: 1
+---
+
+# SkButton
+
+A versatile button component with multiple visual variants, sizes, and interactive states. Renders as a `<button>`, `<a>`, or `<router-link>` depending on the props provided.

package/docs/components/button/kinds.md

@@ -0,0 +1,25 @@
+---
+section: kinds
+order: 4
+---
+
+Choose from semantic kinds (`neutral`, `primary`, `accent`, `success`, `danger`, `warning`, `info`) that adapt to your theme, or color palette kinds (`neon-blue`, `neon-orange`, `neon-purple`, `neon-green`, `neon-mint`, `neon-pink`) for fixed branding colors.
+
+```vue
+<!-- Semantic Kinds -->
+<SkButton kind="neutral">Neutral</SkButton>
+<SkButton kind="primary">Primary</SkButton>
+<SkButton kind="accent">Accent</SkButton>
+<SkButton kind="success">Success</SkButton>
+<SkButton kind="danger">Danger</SkButton>
+<SkButton kind="warning">Warning</SkButton>
+<SkButton kind="info">Info</SkButton>
+
+<!-- Color Palette Kinds -->
+<SkButton kind="neon-blue">Neon Blue</SkButton>
+<SkButton kind="neon-orange">Neon Orange</SkButton>
+<SkButton kind="neon-purple">Neon Purple</SkButton>
+<SkButton kind="neon-green">Neon Green</SkButton>
+<SkButton kind="neon-mint">Neon Mint</SkButton>
+<SkButton kind="neon-pink">Neon Pink</SkButton>
+```

package/docs/components/button/sizes.md

@@ -0,0 +1,14 @@
+---
+section: sizes
+order: 5
+---
+
+Five sizes available: `xs`, `sm`, `md` (default), `lg`, `xl`.
+
+```vue
+<SkButton size="xs" kind="primary">Extra Small</SkButton>
+<SkButton size="sm" kind="primary">Small</SkButton>
+<SkButton size="md" kind="primary">Medium</SkButton>
+<SkButton size="lg" kind="primary">Large</SkButton>
+<SkButton size="xl" kind="primary">Extra Large</SkButton>
+```

package/docs/components/button/states.md

@@ -0,0 +1,12 @@
+---
+section: states
+order: 7
+---
+
+`disabled` prevents interaction, `loading` shows a spinner and disables the button, `pressed` indicates toggle selection (sets `aria-pressed`).
+
+```vue
+<SkButton kind="primary" disabled>Disabled</SkButton>
+<SkButton kind="primary" loading>Loading</SkButton>
+<SkButton kind="primary" pressed>Pressed</SkButton>
+```

package/docs/components/button/usage.md

@@ -0,0 +1,23 @@
+---
+section: usage
+order: 2
+---
+
+Handle clicks with `@click`. For navigation, use `href` for external links or `to` for Vue Router.
+
+```vue
+<!-- Click handler -->
+<SkButton kind="primary" @click="handleClick('Button clicked!')">
+    Click Handler
+</SkButton>
+
+<!-- External link (renders as <a>) -->
+<SkButton kind="accent" href="https://example.com" target="_blank">
+    External Link
+</SkButton>
+
+<!-- Vue Router link (renders as <router-link>) -->
+<SkButton kind="neutral" to="/components/panel">
+    Router Link
+</SkButton>
+```

package/docs/components/button/variants.md

@@ -0,0 +1,14 @@
+---
+section: variants
+order: 3
+---
+
+Control visual hierarchy with five variants: `solid` for primary actions, `outline` for secondary, `subtle` for tertiary, `ghost` for minimal emphasis, and `link` for text-style navigation.
+
+```vue
+<SkButton variant="solid" kind="primary">Solid</SkButton>
+<SkButton variant="outline" kind="primary">Outline</SkButton>
+<SkButton variant="subtle" kind="primary">Subtle</SkButton>
+<SkButton variant="ghost" kind="primary">Ghost</SkButton>
+<SkButton variant="link" kind="primary">Link</SkButton>
+```

package/docs/components/button.md

@@ -0,0 +1,110 @@
+---
+component: SkButton
+category: Forms
+---
+
+# SkButton
+
+A versatile button component with multiple visual variants, sizes, and interactive states. Can render as a `<button>`, `<a>`, or `<router-link>` depending on the props provided.
+
+## Usage
+
+```vue
+<template>
+  <SkButton kind="primary" variant="solid">
+    Click Me
+  </SkButton>
+</template>
+```
+
+## Variants
+
+- **solid** (default) -- Filled background with contrasting text.
+- **outline** -- Transparent background with colored border.
+- **subtle** -- Light tinted background.
+- **ghost** -- No background, colored text only.
+- **link** -- Styled as an inline text link.
+
+```vue
+<SkButton variant="solid">Solid</SkButton>
+<SkButton variant="outline">Outline</SkButton>
+<SkButton variant="subtle">Subtle</SkButton>
+<SkButton variant="ghost">Ghost</SkButton>
+<SkButton variant="link">Link</SkButton>
+```
+
+## Kinds
+
+```vue
+<SkButton kind="primary">Primary</SkButton>
+<SkButton kind="accent">Accent</SkButton>
+<SkButton kind="success">Success</SkButton>
+<SkButton kind="warning">Warning</SkButton>
+<SkButton kind="danger">Danger</SkButton>
+<SkButton kind="info">Info</SkButton>
+<SkButton kind="neutral">Neutral</SkButton>
+```
+
+## Sizes
+
+```vue
+<SkButton size="xs">Extra Small</SkButton>
+<SkButton size="sm">Small</SkButton>
+<SkButton size="md">Medium</SkButton>
+<SkButton size="lg">Large</SkButton>
+<SkButton size="xl">Extra Large</SkButton>
+```
+
+## Slots
+
+- **leading** -- Icon or content before the button text.
+- **default** -- Button label text.
+- **trailing** -- Icon or content after the button text.
+- **icon** -- Icon-only mode (renders a square button when no default slot is used).
+
+```vue
+<SkButton kind="primary">
+  <template #leading><SearchIcon /></template>
+  Search
+</SkButton>
+
+<SkButton kind="danger">
+  <template #icon><TrashIcon /></template>
+</SkButton>
+```
+
+## States
+
+- **disabled** -- Reduces opacity and prevents interaction.
+- **loading** -- Shows a spinner overlay and disables the button.
+- **pressed** -- Toggle state for toolbar-style buttons. Sets `aria-pressed`.
+
+```vue
+<SkButton disabled>Disabled</SkButton>
+<SkButton :loading="isSaving">Save</SkButton>
+<SkButton :pressed="isBold" @click="isBold = !isBold">Bold</SkButton>
+```
+
+## Link Rendering
+
+Provide `href` for an anchor tag or `to` for Vue Router navigation:
+
+```vue
+<SkButton href="https://example.com">External Link</SkButton>
+<SkButton :to="{ name: 'dashboard' }">Dashboard</SkButton>
+```
+
+## Custom Colors
+
+```vue
+<SkButton
+  base-color="oklch(0.7 0.25 300)"
+  text-color="white"
+>
+  Custom Purple
+</SkButton>
+```
+
+## Accessibility
+
+Renders with `role="button"`. Loading state sets `aria-busy="true"`. Pressed state sets `aria-pressed="true"`. Disabled buttons cannot receive focus via mouse click but remain in the tab order with the disabled attribute.

package/docs/components/card.md

@@ -0,0 +1,87 @@
+---
+component: SkCard
+category: Layout
+---
+
+# SkCard
+
+A structured content container with optional header, media, content, and footer sections. Built on top of SkPanel, it inherits beveled corners and decorative accents.
+
+## Usage
+
+```vue
+<template>
+  <SkCard kind="primary" title="Card Title">
+    <p>Card body content.</p>
+    <template #footer>
+      <SkButton kind="primary">Action</SkButton>
+    </template>
+  </SkCard>
+</template>
+```
+
+## Slots
+
+- **header** -- Rendered above the content area. Also appears when the `title` prop is set.
+- **media** -- Full-width section for images or video, rendered between header and content.
+- **default** -- Main content area.
+- **footer** -- Bottom section, typically for action buttons.
+
+```vue
+<SkCard>
+  <template #header>
+    <h3>Custom Header</h3>
+  </template>
+  <template #media>
+    <img src="/banner.jpg" alt="Banner" />
+  </template>
+  <p>Body content.</p>
+  <template #footer>
+    <SkButton variant="ghost">Cancel</SkButton>
+    <SkButton kind="primary">Save</SkButton>
+  </template>
+</SkCard>
+```
+
+## Kinds
+
+```vue
+<SkCard kind="accent" title="Accent Card">Content</SkCard>
+<SkCard kind="info" title="Info Card">Content</SkCard>
+```
+
+## Sizes
+
+The `size` prop controls padding and spacing within the card:
+
+```vue
+<SkCard size="sm" title="Compact">Small padding.</SkCard>
+<SkCard size="lg" title="Spacious">Large padding.</SkCard>
+```
+
+## Scrollable Content
+
+Set `scrollable` to make the content area independently scrollable when the card has a constrained height:
+
+```vue
+<SkCard scrollable style="height: 300px" title="Scrollable">
+  <p>Long content that scrolls...</p>
+</SkCard>
+```
+
+## Custom Colors
+
+```vue
+<SkCard
+  base-color="#1e293b"
+  text-color="#e2e8f0"
+  header-color="#0f172a"
+  title="Dark Card"
+>
+  Custom colored card with a darker header.
+</SkCard>
+```
+
+## Accessibility
+
+Semantic structure is the developer's responsibility. Use appropriate heading levels in the header slot and provide alt text for media content.