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

package/docs/components/toast/with-title.md

@@ -0,0 +1,14 @@
+---
+section: with-title
+order: 4
+---
+
+Add a `title` for a more prominent notification.
+
+```vue
+toast.add({
+  kind: 'success',
+  title: 'Changes Saved',
+  message: 'Your profile has been updated successfully.'
+});
+```

package/docs/components/tooltip/_meta.yaml

@@ -0,0 +1,14 @@
+component: SkTooltip
+category: Feedback
+sections:
+  - intro
+  - usage
+  - kinds
+  - positioning
+  - alignment
+  - arrow
+  - custom-colors
+  - delay
+  - provider
+  - app-level-provider
+  - real-world

package/docs/components/tooltip/alignment.md

@@ -0,0 +1,24 @@
+---
+section: alignment
+order: 5
+---
+
+Use the `align` prop to control how the tooltip aligns with the trigger.
+
+```vue
+<!-- Solid variant -->
+<SkTooltip side="bottom" align="start">
+  Aligned to start
+  <template #trigger>
+    <SkButton>Start</SkButton>
+  </template>
+</SkTooltip>
+
+<!-- Outline variant -->
+<SkTooltip side="bottom" align="start" kind="primary" variant="outline">
+  Outline aligned to start
+  <template #trigger>
+    <SkButton kind="primary">Start</SkButton>
+  </template>
+</SkTooltip>
+```

package/docs/components/tooltip/app-level-provider.md

@@ -0,0 +1,21 @@
+---
+section: app-level-provider
+order: 10
+---
+
+For app-wide tooltip coordination, wrap your entire app in SkTooltipProvider (typically in App.vue).
+
+```vue
+<!-- App.vue - recommended setup -->
+<template>
+  <SkTheme theme="colorful">
+    <SkTooltipProvider :delay-duration="300" :skip-delay-duration="100">
+      <RouterView />
+    </SkTooltipProvider>
+  </SkTheme>
+</template>
+
+<script setup>
+import { SkTheme, SkTooltipProvider } from '@skewedaspect/sleekspace-ui';
+</script>
+```

package/docs/components/tooltip/arrow.md

@@ -0,0 +1,21 @@
+---
+section: arrow
+order: 6
+---
+
+Hide the arrow indicator with `:show-arrow="false"`.
+
+```vue
+<SkTooltip :show-arrow="false">
+  This tooltip has no arrow
+  <template #trigger>
+    <SkButton>No Arrow</SkButton>
+  </template>
+</SkTooltip>
+<SkTooltip :show-arrow="false" kind="primary" variant="outline">
+  Outline with no arrow
+  <template #trigger>
+    <SkButton kind="primary">Outline No Arrow</SkButton>
+  </template>
+</SkTooltip>
+```

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

@@ -0,0 +1,24 @@
+---
+section: custom-colors
+order: 7
+---
+
+Use `baseColor` and `textColor` for full color control.
+
+```vue
+<!-- Solid variant -->
+<SkTooltip base-color="oklch(0.5 0.25 300)" text-color="white">
+  Custom purple tooltip
+  <template #trigger>
+    <SkButton>Purple</SkButton>
+  </template>
+</SkTooltip>
+
+<!-- Outline variant -->
+<SkTooltip base-color="oklch(0.5 0.25 300)" text-color="white" variant="outline">
+  Custom purple outline
+  <template #trigger>
+    <SkButton>Purple Outline</SkButton>
+  </template>
+</SkTooltip>
+```

package/docs/components/tooltip/delay.md

@@ -0,0 +1,27 @@
+---
+section: delay
+order: 8
+---
+
+Control how long to wait before showing the tooltip with `delayDuration` (in milliseconds).
+
+```vue
+<SkTooltip :delay-duration="0">
+  Instant tooltip (0ms)
+  <template #trigger>
+    <SkButton>Instant</SkButton>
+  </template>
+</SkTooltip>
+<SkTooltip :delay-duration="400">
+  Default delay (400ms)
+  <template #trigger>
+    <SkButton>Default</SkButton>
+  </template>
+</SkTooltip>
+<SkTooltip :delay-duration="1000">
+  Slow tooltip (1000ms)
+  <template #trigger>
+    <SkButton>Slow</SkButton>
+  </template>
+</SkTooltip>
+```

package/docs/components/tooltip/intro.md

@@ -0,0 +1,8 @@
+---
+section: intro
+order: 1
+---
+
+# 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.

package/docs/components/tooltip/kinds.md

@@ -0,0 +1,27 @@
+---
+section: kinds
+order: 3
+---
+
+Seven semantic kinds for different contexts and purposes.
+
+```vue
+<SkTooltip kind="neutral">
+  Neutral information
+  <template #trigger>
+    <SkButton kind="neutral">Neutral</SkButton>
+  </template>
+</SkTooltip>
+<SkTooltip kind="primary">
+  Primary action hint
+  <template #trigger>
+    <SkButton kind="primary">Primary</SkButton>
+  </template>
+</SkTooltip>
+<SkTooltip kind="info">
+  Informational message
+  <template #trigger>
+    <SkButton kind="info">Info</SkButton>
+  </template>
+</SkTooltip>
+```

package/docs/components/tooltip/positioning.md

@@ -0,0 +1,24 @@
+---
+section: positioning
+order: 4
+---
+
+Control the tooltip position with the `side` prop. Tooltips automatically adjust to stay within viewport bounds.
+
+```vue
+<!-- Solid variant -->
+<SkTooltip side="top">
+  Appears on top
+  <template #trigger>
+    <SkButton>Top</SkButton>
+  </template>
+</SkTooltip>
+
+<!-- Outline variant -->
+<SkTooltip side="top" kind="primary" variant="outline">
+  Outline on top
+  <template #trigger>
+    <SkButton kind="primary">Top</SkButton>
+  </template>
+</SkTooltip>
+```

package/docs/components/tooltip/provider.md

@@ -0,0 +1,26 @@
+---
+section: provider
+order: 9
+---
+
+Wrap multiple tooltips in SkTooltipProvider for coordinated "skip delay" behavior -- after viewing one tooltip, moving to another shows it instantly.
+
+```vue
+<!-- Without provider: each tooltip has independent delay -->
+<SkTooltip>...</SkTooltip>
+<SkTooltip>...</SkTooltip>
+<SkTooltip>...</SkTooltip>
+
+<!-- With provider: skip delay when moving between tooltips -->
+<SkTooltipProvider :delay-duration="400" :skip-delay-duration="300">
+  <SkTooltip kind="primary">
+    Tooltip 1
+    <template #trigger><SkButton>A</SkButton></template>
+  </SkTooltip>
+  <SkTooltip kind="primary">
+    Tooltip 2
+    <template #trigger><SkButton>B</SkButton></template>
+  </SkTooltip>
+  <!-- More tooltips... -->
+</SkTooltipProvider>
+```

package/docs/components/tooltip/real-world.md

@@ -0,0 +1,32 @@
+---
+section: real-world
+order: 11
+---
+
+Common tooltip use cases in applications: icon buttons, help text, and disabled button explanations.
+
+```vue
+<!-- Icon buttons with tooltips -->
+<SkTooltip>
+  Save changes
+  <template #trigger>
+    <SkButton variant="ghost" size="sm">Save</SkButton>
+  </template>
+</SkTooltip>
+
+<!-- Help text -->
+<SkTooltip kind="info" side="right">
+  Your username must be 3-20 characters and can only contain letters, numbers, and underscores.
+  <template #trigger>
+    <span class="text-info cursor-help">Info</span>
+  </template>
+</SkTooltip>
+
+<!-- Disabled button explanation -->
+<SkTooltip kind="warning">
+  Complete all required fields to enable this button
+  <template #trigger>
+    <SkButton disabled>Submit</SkButton>
+  </template>
+</SkTooltip>
+```

package/docs/components/tooltip/usage.md

@@ -0,0 +1,15 @@
+---
+section: usage
+order: 2
+---
+
+Wrap any element with a tooltip to provide additional information on hover.
+
+```vue
+<SkTooltip>
+  Hover over me for a helpful hint
+  <template #trigger>
+    <SkButton>Hover Me</SkButton>
+  </template>
+</SkTooltip>
+```

package/docs/guides/ai-llms.md

@@ -0,0 +1,63 @@
+---
+title: AI & LLMs
+---
+
+# AI & LLMs
+
+SleekSpace UI ships with LLM-friendly documentation files that make it easy for AI assistants like Claude, ChatGPT, GitHub Copilot, and Cursor to understand and help with the library.
+
+## Available Files
+
+Two documentation files are available, optimized for different use cases:
+
+| File | Size | Best For |
+|------|------|----------|
+| `llms.txt` | ~7 KB | Quick context, token-efficient prompts |
+| `llms-full.txt` | ~196 KB | Complete reference, in-depth help |
+
+**llms.txt** is a concise index with component summaries. It gives AI assistants enough context to understand what the library offers and how components work together.
+
+**llms-full.txt** is the complete reference. It includes all guide documentation, every component's usage examples, and full API reference tables with all props, slots, and events.
+
+## How to Use
+
+### AI-Powered IDEs (Claude Code, Cursor, Windsurf)
+
+Point your AI assistant to fetch the documentation from our docs site:
+
+- https://sleekspace-ui.skewedaspect.com/llms.txt
+- https://sleekspace-ui.skewedaspect.com/llms-full.txt
+
+Example: "Fetch https://sleekspace-ui.skewedaspect.com/llms.txt and help me create a form with validation."
+
+### Web-Based AI (ChatGPT, Claude.ai)
+
+Direct the AI to read the documentation URLs:
+
+Example prompt:
+
+> "Read https://sleekspace-ui.skewedaspect.com/llms.txt and then help me create a themed dashboard layout."
+
+### Paste Into Context
+
+For quick questions, copy the content of `llms.txt` and paste it into your conversation. For in-depth help with complex implementations, use `llms-full.txt`.
+
+## What's Included
+
+The documentation files contain:
+
+- **All guides** -- Installation, theming, design tokens, custom colors
+- **Every component** -- Usage examples and documentation for all 46 components
+- **Complete API reference** -- Props, slots, and events in structured tables
+- **Best practices** -- Common patterns and recommended approaches
+
+The files are auto-generated from the source documentation, so they stay in sync with the library.
+
+## Why This Matters
+
+AI assistants work best when they have accurate, up-to-date context about the tools you are using. With these files:
+
+- **Accurate help** -- AI responses are based on real documentation, not training data that may be outdated
+- **No hallucinations** -- Props, events, and usage patterns match what the library actually provides
+- **Better suggestions** -- AI can recommend appropriate components, theming approaches, and composition patterns
+- **Faster development** -- Get library-specific help without searching through documentation manually

package/docs/guides/design-tokens/_meta.yaml

@@ -0,0 +1,14 @@
+guide: design-tokens
+title: Design Tokens
+sections:
+  - intro
+  - architecture
+  - foundation-colors
+  - foundation-other
+  - semantic-kinds
+  - semantic-states
+  - themes
+  - component-tokens
+  - usage
+  - advanced
+  - best-practices

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

@@ -0,0 +1,60 @@
+---
+section: advanced
+---
+
+## Advanced Topics
+
+### Custom Colors via Props
+
+Components support custom colors without modifying tokens:
+
+```vue
+<SkButton :base-color="'oklch(0.7 0.25 300)'">
+    Custom Purple Button
+</SkButton>
+```
+
+### Adding New Foundation Colors
+
+Add new color primitives in `_foundation-colors.scss`:
+
+```css
+/* Teal */
+--sk-color-teal-05: oklch(0.9 0.05 180);
+--sk-color-teal-10: oklch(0.85 0.08 180);
+/* ... define all 11 shades */
+--sk-color-teal-95: oklch(0.1 0.02 180);
+```
+
+### Creating a New Theme
+
+1. Create `src/styles/themes/_mytheme.scss`
+2. Define all 7 semantic kinds with the `[data-scheme="mytheme"]` selector
+3. Import in `themes/index.scss`: `@forward 'mytheme';`
+4. Add to TypeScript types: `export type SkThemeName = 'greyscale' | 'colorful' | 'mytheme';`
+5. Use: `<SkTheme theme="mytheme">`
+
+### Component Token Overrides
+
+Override component tokens for one-off customizations:
+
+```vue
+<SkButton
+    style="--sk-button-bg: var(--sk-color-purple-40);
+           --sk-button-text: white;"
+>
+    Custom Button
+</SkButton>
+```
+
+### Scale Multipliers
+
+Global multipliers allow users to scale the entire design system proportionally:
+
+```css
+--sk-space-scale: 1      /* Scales all spacing */
+--sk-font-size-scale: 1  /* Scales all font sizes */
+--sk-radius-scale: 1     /* Scales all border radii */
+```
+
+Set `--sk-space-scale: 1.25` to make the entire UI 25% larger!

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

@@ -0,0 +1,11 @@
+---
+section: architecture
+---
+
+## Three-Tier Architecture
+
+**Foundation Tokens** are raw, immutable values that never change. They include 121 OKLCH color primitives (11 families × 11 shades), spacing scales, typography, borders, shadows, and transitions. Example: `--sk-color-blue-50`.
+
+**Semantic Tokens** are theme-aware mappings that give meaning to foundation tokens. They include 7 semantic kinds (neutral, primary, accent, etc.), 10 color kinds for direct palette access, surface and interactive states, and derived hover/active states via `color-mix()`. Example: `--sk-primary-base`.
+
+**Component Tokens** are component-specific values that reference semantic tokens. They are scoped to individual components, enable component-level customization, and can be overridden per instance. Example: `--sk-button-bg`.

package/docs/guides/design-tokens/best-practices.md

@@ -0,0 +1,21 @@
+---
+section: best-practices
+---
+
+## Best Practices
+
+### Do
+
+- Use semantic kinds for theme-aware components
+- Reference higher-tier tokens in lower tiers (component → semantic → foundation)
+- Use `color-mix()` for dynamic color derivation
+- Keep token naming consistent and predictable
+- Document custom tokens with comments
+
+### Don't
+
+- Reference foundation tokens directly in components (breaks theming)
+- Create circular token references
+- Hardcode color values in components
+- Mix naming conventions (stick to `--sk-*`)
+- Define semantic tokens outside theme files

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

@@ -0,0 +1,37 @@
+---
+section: component-tokens
+---
+
+## Component Tokens
+
+Each component defines its own tokens that reference semantic tokens. This provides a layer of indirection for component-level customization.
+
+### Example: Button Component
+
+```scss
+.sk-button {
+    /* Component tokens reference semantic tokens */
+    --sk-button-bg: var(--sk-button-color-base);
+    --sk-button-text: var(--sk-neutral-text);
+    --sk-button-border-width: var(--sk-border-width-thin);
+
+    /* Calculated values */
+    --sk-button-bg-hover: color-mix(
+        in oklch,
+        var(--sk-button-bg) 92%,
+        white 8%
+    );
+
+    /* Usage */
+    background-color: var(--sk-button-bg);
+    color: var(--sk-button-text);
+    border-width: var(--sk-button-border-width);
+}
+```
+
+### Component Token Pattern
+
+- Always prefix with component name: `--sk-button-*`
+- Reference semantic tokens by default
+- Override in kind mixins for different colors
+- Can be customized via inline styles if needed

package/docs/guides/design-tokens/foundation-colors.md

@@ -0,0 +1,13 @@
+---
+section: foundation-colors
+---
+
+## Foundation Tokens
+
+Foundation tokens are the bedrock of the design system. They define exact values using modern CSS features like OKLCH color space.
+
+### Color Primitives
+
+**110 tokens** across **10 color families**, each with 11 shades (05, 10, 20, 30, 40, 50, 60, 70, 80, 90, 95). Shade 50 is typically the most vibrant.
+
+The color families are: gray, blue, red, orange, yellow, green, mint, cyan, purple, and pink. Each follows the pattern `--sk-color-{family}-{shade}`.

package/docs/guides/design-tokens/foundation-other.md

@@ -0,0 +1,41 @@
+---
+section: foundation-other
+---
+
+### Other Foundation Tokens
+
+Beyond colors, foundation tokens cover spacing, borders, typography, transitions, glows, shadows, and scale multipliers.
+
+```css
+/* Spacing */
+--sk-space-3xs: 0.125rem   /* 2px */
+--sk-space-2xs: 0.25rem    /* 4px */
+--sk-space-xs: 0.5rem      /* 8px */
+--sk-space-sm: 0.75rem     /* 12px */
+--sk-space-md: 1rem        /* 16px */
+--sk-space-lg: 1.5rem      /* 24px */
+--sk-space-xl: 2rem        /* 32px */
+--sk-space-2xl: 3rem       /* 48px */
+--sk-space-3xl: 4rem       /* 64px */
+
+/* Border Widths */
+--sk-border-width-none: 0
+--sk-border-width-thin: 1px
+--sk-border-width-normal: 2px
+--sk-border-width-thick: 4px
+--sk-border-width-heavy: 6px
+
+/* Typography */
+--sk-font-family-base: 'Titillium Web', ui-sans-serif, system-ui, sans-serif
+--sk-font-size-xs: 0.75rem
+--sk-font-size-sm: 0.875rem
+--sk-font-size-md: 1rem
+--sk-font-size-lg: 1.125rem
+--sk-font-size-xl: 1.25rem
+
+/* Transitions */
+--sk-transition-duration-instant: 0ms
+--sk-transition-duration-fast: 150ms
+--sk-transition-duration-normal: 200ms
+--sk-transition-duration-slow: 300ms
+```

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

@@ -0,0 +1,19 @@
+---
+section: intro
+---
+
+# Design Tokens
+
+A comprehensive token system for scalable, themeable design. Inspired by Web Awesome's three-tier architecture.
+
+Design tokens are the visual design atoms of the design system — specifically, they are named entities that store visual design attributes. They provide a single source of truth for colors, spacing, typography, and other design decisions.
+
+**Token Philosophy:** Tokens are organized in a three-tier hierarchy: Foundation → Semantic → Component. This separation enables powerful theming while maintaining consistency.
+
+This token system addresses common design system challenges:
+
+- **Consistency** — Single source of truth eliminates duplicate formulas and hard-coded values
+- **Maintainability** — Clear hierarchy makes global updates simple
+- **Scalability** — Easy to add new components and extend the palette
+- **Customization** — Scale multipliers allow flexible theming without breaking the system
+- **Developer Experience** — Intuitive naming and comprehensive documentation

package/docs/guides/design-tokens/semantic-kinds.md

@@ -0,0 +1,33 @@
+---
+section: semantic-kinds
+---
+
+## Semantic Tokens
+
+Semantic tokens provide meaning and context to foundation tokens. They enable theming by mapping different foundation colors to the same semantic purpose.
+
+### Semantic Kinds (Themeable)
+
+These change based on the active theme. Each kind has 5 tokens: base, hover, active, text, and text-contrast.
+
+- **neutral** — Default/neutral UI elements
+- **primary** — Primary actions & brand
+- **accent** — Secondary emphasis
+- **info** — Informational content
+- **success** — Success states
+- **warning** — Warning states
+- **danger** — Error/destructive actions
+
+```css
+--sk-{kind}-base          /* Main color */
+--sk-{kind}-hover         /* Hover state (auto-derived) */
+--sk-{kind}-active        /* Active state (auto-derived) */
+--sk-{kind}-text          /* Text color (white) */
+--sk-{kind}-text-contrast /* Alternative text (dark) */
+```
+
+### Color Kinds (Non-Themeable)
+
+Direct access to specific colors, regardless of theme. Use these when you need a fixed color that doesn't change with theming.
+
+boulder, neon-blue, light-blue, neon-orange, neon-purple, neon-green, neon-mint, neon-pink, yellow, red

package/docs/guides/design-tokens/semantic-states.md

@@ -0,0 +1,55 @@
+---
+section: semantic-states
+---
+
+### Automatic State Derivation
+
+Hover and active states are automatically calculated using CSS `color-mix()`:
+
+```css
+--sk-primary-hover: color-mix(
+    in oklch,
+    var(--sk-primary-base),
+    var(--sk-color-gray-10)
+    var(--sk-mix-amount-moderate)  /* 15% */
+);
+
+--sk-primary-active: color-mix(
+    in oklch,
+    var(--sk-primary-base),
+    var(--sk-color-gray-10)
+    var(--sk-mix-amount-strong)    /* 25% */
+);
+```
+
+### Surface & Text Semantics
+
+Background and text colors for layouts and content, separate from interactive component colors.
+
+```css
+/* Surface Colors */
+--sk-surface-base: var(--sk-color-gray-10)
+--sk-surface-raised: var(--sk-color-gray-05)
+--sk-surface-overlay: var(--sk-color-gray-20)
+
+/* Text Colors */
+--sk-text-primary: var(--sk-color-gray-95)
+--sk-text-secondary: var(--sk-color-gray-70)
+--sk-text-tertiary: var(--sk-color-gray-50)
+--sk-text-disabled: var(--sk-color-gray-40)
+```
+
+### Interactive State Semantics
+
+Unified focus and selection states across all interactive components.
+
+```css
+/* Focus Ring */
+--sk-focus-ring-color: var(--sk-primary-base)
+--sk-focus-ring-width: var(--sk-border-width-normal)
+--sk-focus-ring-offset: 2px
+
+/* Selection */
+--sk-selection-background: var(--sk-primary-base)
+--sk-selection-text: var(--sk-primary-text)
+```