@skewedaspect/sleekspace-ui 0.8.1 → 0.9.0

package/docs/guides/pure-css/static-helpers.md

@@ -0,0 +1,1203 @@
+---
+title: Static Helpers Reference
+description: Typed Node.js helper functions that generate Sleekspace HTML strings for SSGs and build scripts — zero runtime, zero Vue dependency.
+---
+
+# Static Helpers Reference
+
+The `/static` subpath exports typed helper functions that generate Sleekspace HTML strings.
+They're intended for Node-based SSGs and build scripts where you want type-safe component
+output without importing Vue or shipping a runtime dependency.
+
+Each helper returns a `string` of plain HTML — zero side effects, zero global state.
+
+## Installation
+
+```bash
+npm install @skewedaspect/sleekspace-ui
+```
+
+The CSS is a separate import:
+
+```typescript
+// In your bundler entry or HTML:
+import '@skewedaspect/sleekspace-ui/style';
+// or link the compiled CSS directly in your HTML
+```
+
+## Import
+
+```typescript
+import { panel, button, alert, text, escapeAttr } from '@skewedaspect/sleekspace-ui/static';
+```
+
+All 31 component helpers plus utilities are exported from this single entry point.
+
+## Helper signature
+
+Every component helper has the same shape:
+
+```typescript
+function helperName(props?: Props, children?: string): string
+```
+
+- `props` — typed props object. All properties are optional with sensible defaults.
+- `children` — inner HTML string. Pass pre-escaped content or use the `text()` utility.
+- Returns — a complete HTML string for the component's root element.
+
+Container helpers (panel, card, etc.) include children in the output. Void helpers
+(input, slider, color-picker) ignore children.
+
+---
+
+## Utilities
+
+### `text(value)`
+
+Escapes a plain string for safe HTML text content. Use whenever interpolating user-controlled
+or data-driven strings into HTML.
+
+```typescript
+import { text, panel } from '@skewedaspect/sleekspace-ui/static';
+
+const html = panel({}, `<p>${ text(userInput) }</p>`);
+```
+
+### `escapeAttr(value)`
+
+Escapes a string for use inside an HTML attribute value (double-quoted).
+
+```typescript
+import { escapeAttr } from '@skewedaspect/sleekspace-ui/static';
+
+const safe = `data-id="${ escapeAttr(rawId) }"`;
+```
+
+### `composeClasses(spec, props)`
+
+Low-level class composition utility. Takes a `ClassSpec` describing how props map to modifier
+classes, returns the space-separated class string. Useful when you need class output without
+a full helper.
+
+```typescript
+import { composeClasses } from '@skewedaspect/sleekspace-ui/static';
+
+const classes = composeClasses({ base: 'sk-panel', kind: true }, { kind: 'primary' });
+// → "sk-panel sk-primary"
+```
+
+### `render(spec, props, children)`
+
+Generic renderer used internally by the thin-wrapper helpers (panel, card, progress, etc.).
+Takes a `RenderSpec` and emits the class-API HTML string. Useful for building custom helpers
+that follow the same class composition rules.
+
+```typescript
+import { render } from '@skewedaspect/sleekspace-ui/static';
+
+const html = render(
+    { tag: 'div', classSpec: { base: 'sk-panel', kind: true }, extraAttrs: { role: 'region' } },
+    { kind: 'accent' },
+    '<p>Custom region</p>'
+);
+// → '<div class="sk-panel sk-accent" role="region"><p>Custom region</p></div>'
+```
+
+---
+
+## Framework Examples
+
+### VitePress
+
+Use inside a `transformHtml` hook or a custom markdown-it plugin to render Sleekspace
+components inside `.md` files.
+
+```typescript
+// .vitepress/config.ts
+import { defineConfig } from 'vitepress';
+import { panel } from '@skewedaspect/sleekspace-ui/static';
+
+export default defineConfig({
+    transformHtml(code) {
+        return code.replace(/<sk-callout kind="([^"]+)">([\s\S]*?)<\/sk-callout>/g, (_, kind, content) =>
+            panel({ kind }, content)
+        );
+    },
+});
+```
+
+Or add a custom markdown-it fence renderer:
+
+```typescript
+// .vitepress/config.ts
+import markdownItSleekspace from './plugins/markdownItSleekspace';
+
+export default defineConfig({
+    markdown: {
+        config(md) {
+            md.use(markdownItSleekspace);
+        },
+    },
+});
+```
+
+---
+
+### Astro
+
+Import directly in `.astro` component files. Astro renders these at build time — no Vue runtime needed.
+
+```astro
+---
+import { panel, button } from '@skewedaspect/sleekspace-ui/static';
+import '@skewedaspect/sleekspace-ui/style';
+
+const callout = panel(
+    { kind: 'accent', size: 'lg' },
+    `<p>Build-time rendered with no runtime cost.</p>`
+);
+---
+
+<Fragment set:html={callout} />
+```
+
+For reuse across pages, wrap in a `.astro` component:
+
+```astro
+---
+// src/components/Callout.astro
+import { panel } from '@skewedaspect/sleekspace-ui/static';
+const { kind = 'neutral', size = 'md' } = Astro.props;
+const html = panel({ kind, size }, await Astro.slots.render('default'));
+---
+<Fragment set:html={html} />
+```
+
+---
+
+### 11ty
+
+Register as a paired shortcode in `.eleventy.js`:
+
+```javascript
+// .eleventy.js
+const { panel, button, alert } = require('@skewedaspect/sleekspace-ui/static');
+
+module.exports = function(eleventyConfig) {
+    eleventyConfig.addPairedShortcode('panel', (content, kind = 'neutral', size = 'md') =>
+        panel({ kind, size }, content)
+    );
+
+    eleventyConfig.addPairedShortcode('alert', (content, kind = 'info') =>
+        alert({ kind }, content)
+    );
+
+    eleventyConfig.addShortcode('button', (label, kind = 'primary', href) =>
+        button({ kind, href }, label)
+    );
+};
+```
+
+Then in your Nunjucks / Liquid templates:
+
+```njk
+{% panel "primary", "lg" %}
+    <p>This panel is rendered at build time.</p>
+{% endpanel %}
+```
+
+---
+
+### Vanilla Node build script
+
+```typescript
+import { writeFileSync } from 'fs';
+import { panel, navBar, button, text } from '@skewedaspect/sleekspace-ui/static';
+
+const nav = navBar(
+    { kind: 'neutral', sticky: true, brand: `<span>${ text('MySite') }</span>` },
+    `<a href="/docs">Docs</a>`
+);
+
+const hero = panel({ kind: 'primary', size: 'xl' },
+    `<h1>Hello world</h1>`
+    + button({ kind: 'accent', size: 'lg' }, text('Get started'))
+);
+
+const page = `<!doctype html>
+<html lang="en">
+<head>
+    <meta charset="utf-8" />
+    <link rel="stylesheet" href="/sleekspace-ui.css" />
+</head>
+<body>
+    ${ nav }
+    <main>${ hero }</main>
+</body>
+</html>`;
+
+writeFileSync('dist/index.html', page);
+```
+
+---
+
+## Component Helper Reference
+
+All 31 helpers are documented below with their props and actual emitted HTML output.
+
+---
+
+### panel
+
+```typescript
+panel(props?: PanelStaticProps, children?: string): string
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `kind` | `SkPanelKind` | `'neutral'` | Kind color |
+| `size` | `SkPanelSize` | `'md'` | Corner decoration size |
+| `corners` | `SkPanelCorner[]` | `['bottom-right']` | Which corners are beveled |
+| `decorationCorner` | `SkPanelCorner` | `'bottom-right'` | Which corner shows accent stripe |
+| `noBorder` | `boolean` | `false` | Remove border |
+| `noDecoration` | `boolean` | `false` | Hide accent stripe |
+| `baseColor` | `string` | — | Override via `--sk-panel-color-base` |
+
+**Output:**
+
+```html
+<div class="sk-panel sk-neutral sk-md sk-cut-bottom-right sk-decoration-bottom-right">
+    <!-- children -->
+</div>
+```
+
+---
+
+### card
+
+```typescript
+card(props?: CardStaticProps, children?: string): string
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `kind` | `SkCardKind` | `'neutral'` | Kind color |
+| `baseColor` | `string` | — | Override via `--sk-panel-color-base` |
+
+**Output:**
+
+```html
+<div class="sk-card sk-neutral"><!-- children --></div>
+```
+
+---
+
+### alert {#alert}
+
+```typescript
+alert(props?: AlertStaticProps, children?: string): string
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `kind` | `SkAlertKind` | `'info'` | Kind color |
+| `subtle` | `boolean` | `false` | Lower-contrast variant |
+| `icon` | `string \| false` | `undefined` | Custom icon HTML, `false` to suppress, or omit for auto |
+| `baseColor` | `string` | — | Override via `--sk-alert-color-base` |
+| `textColor` | `string` | — | Override via `--sk-alert-fg` |
+
+When `icon` is omitted, icons are auto-selected for feedback kinds (info, success, warning, danger).
+Non-feedback kinds (neutral, primary, accent) emit no icon container. Pass `icon: false` to
+suppress the icon on a feedback kind. Pass `icon: '<svg>…</svg>'` for a custom icon.
+
+**Output (info kind — default):**
+
+```html
+<div class="sk-alert sk-info" role="alert">
+    <div class="sk-alert-icon">
+        <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2">
+            <circle cx="12" cy="12" r="10"></circle>
+            <line x1="12" y1="16" x2="12" y2="12"></line>
+            <circle cx="12" cy="8" r="0.5" fill="currentColor"></circle>
+        </svg>
+    </div>
+    <div class="sk-alert-content"><!-- children --></div>
+</div>
+```
+
+**Output (neutral kind — no icon):**
+
+```html
+<div class="sk-alert sk-neutral" role="alert">
+    <div class="sk-alert-content"><!-- children --></div>
+</div>
+```
+
+**Output (icon: false):**
+
+```html
+<div class="sk-alert sk-success" role="alert">
+    <div class="sk-alert-content"><!-- children --></div>
+</div>
+```
+
+---
+
+### divider
+
+```typescript
+divider(props?: DividerStaticProps): string
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `kind` | `ComponentKind` | `'neutral'` | Kind color |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout axis |
+| `size` | `ComponentSize` | `'md'` | Line thickness |
+| `variant` | `'subtle'` | — | Reduced-contrast variant |
+
+Note: divider renders as an `<hr>` element, not a `<div>`.
+
+**Output:**
+
+```html
+<hr class="sk-divider sk-horizontal sk-neutral sk-md" role="separator">
+```
+
+---
+
+### page
+
+```typescript
+page(props?: PageStaticProps, children?: string): string
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `fixedHeader` | `boolean` | `false` | Stick header to viewport top |
+| `fixedFooter` | `boolean` | `false` | Stick footer to viewport bottom |
+| `flush` | `boolean` | `false` | Remove outer padding |
+| `sidebarMode` | `SkPagePanelMode` | — | Sidebar panel mode |
+| `asideMode` | `SkPagePanelMode` | — | Aside panel mode |
+
+**Output:**
+
+```html
+<div class="sk-page"><!-- children --></div>
+```
+
+---
+
+### group
+
+```typescript
+group(props?: GroupStaticProps, children?: string): string
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Flex direction |
+
+**Output:**
+
+```html
+<div class="sk-group sk-horizontal"><!-- children --></div>
+```
+
+---
+
+### skeleton {#skeleton}
+
+```typescript
+skeleton(props?: SkeletonStaticProps): string
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `'text' \| 'circular' \| 'rectangular' \| 'square'` | `'text'` | Shape preset |
+| `animation` | `'shimmer' \| 'pulse' \| 'none'` | `'shimmer'` | Animation style |
+| `width` | `string` | — | CSS width (e.g. `'200px'`, `'100%'`) — emitted as inline style |
+| `height` | `string` | — | CSS height — emitted as inline style |
+
+For `circular` and `square` variants, if only `width` is set, `height` is automatically
+set to the same value.
+
+**Output (text, defaults):**
+
+```html
+<div class="sk-skeleton sk-text sk-shimmer"></div>
+```
+
+**Output (rect with dimensions):**
+
+```html
+<div class="sk-skeleton sk-rectangular sk-shimmer" style="width: 200px; height: 40px;"></div>
+```
+
+**Output (animation: 'none'):**
+
+```html
+<div class="sk-skeleton sk-text"></div>
+```
+
+---
+
+### progress
+
+```typescript
+progress(props?: ProgressStaticProps): string
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `kind` | `ComponentKind` | `'neutral'` | Kind color |
+| `size` | `SkProgressSize` | `'md'` | Bar height |
+| `indeterminate` | `boolean` | `false` | Animated indeterminate state |
+| `value` | `number \| null` | — | Progress value (native attribute) |
+| `max` | `number` | — | Max value (native attribute) |
+
+**Output:**
+
+```html
+<progress class="sk-progress sk-neutral sk-md" value="40" max="100"></progress>
+```
+
+---
+
+### spinner {#spinner}
+
+```typescript
+spinner(props?: SpinnerStaticProps): string
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `kind` | `ComponentKind` | `'primary'` | Kind color |
+| `size` | `SkSpinnerSize` | `'md'` | Spinner diameter |
+| `variant` | `'circular' \| 'dots' \| 'crosshair'` | `'circular'` | Visual style |
+| `color` | `string` | — | Override via `--sk-spinner-color` inline style |
+
+Always emits `role="status"`, `aria-live="polite"`, `aria-label="Loading"`. Inner DOM
+varies by variant.
+
+**Output (circular — default):**
+
+```html
+<div class="sk-spinner sk-primary sk-md sk-variant-circular"
+     role="status" aria-live="polite" aria-label="Loading">
+    <div class="sk-spinner-circular">
+        <div class="sk-arc sk-arc-large"></div>
+        <div class="sk-arc sk-arc-small"></div>
+    </div>
+</div>
+```
+
+**Output (dots):**
+
+```html
+<div class="sk-spinner sk-primary sk-md sk-variant-dots"
+     role="status" aria-live="polite" aria-label="Loading">
+    <div class="sk-spinner-dots">
+        <div class="sk-dot"></div>
+        <div class="sk-dot"></div>
+        <div class="sk-dot"></div>
+    </div>
+</div>
+```
+
+**Output (crosshair):**
+
+```html
+<div class="sk-spinner sk-primary sk-md sk-variant-crosshair"
+     role="status" aria-live="polite" aria-label="Loading">
+    <div class="sk-crosshair-loader"></div>
+</div>
+```
+
+---
+
+### navBar {#navbar}
+
+```typescript
+navBar(props?: NavBarStaticProps, children?: string): string
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `kind` | `SkNavBarKind` | `'neutral'` | Kind color |
+| `sticky` | `boolean` | `true` | Apply `sk-sticky` class |
+| `leading` | `string` | — | HTML for leading slot (sidebar toggle, etc.) |
+| `brand` | `string` | — | HTML for brand slot (logo / site name) |
+| `actions` | `string` | — | HTML for actions slot (right-aligned CTAs / user menu) |
+| `baseColor` | `string` | — | Override via `--sk-navbar-color-base` |
+| `textColor` | `string` | — | Override via `--sk-navbar-fg` |
+
+`children` maps to the nav links slot (`sk-navbar-nav`). Each slot region (`leading`, `brand`,
+nav links, `actions`) is only emitted when it has content.
+
+**Output (brand + nav only):**
+
+```html
+<nav class="sk-navbar sk-neutral sk-sticky">
+    <div class="sk-navbar-content">
+        <div class="sk-navbar-brand">MySite</div>
+        <div class="sk-navbar-nav">
+            <a href="/docs">Docs</a>
+        </div>
+    </div>
+</nav>
+```
+
+**Output (all slots):**
+
+```html
+<nav class="sk-navbar sk-neutral sk-sticky">
+    <div class="sk-navbar-content">
+        <div class="sk-navbar-leading"><!-- sidebar toggle --></div>
+        <div class="sk-navbar-brand">MySite</div>
+        <div class="sk-navbar-nav"><!-- nav links --></div>
+        <div class="sk-navbar-actions"><!-- user menu --></div>
+    </div>
+</nav>
+```
+
+---
+
+### toolbar {#toolbar}
+
+```typescript
+toolbar(props?: ToolbarStaticProps, children?: string): string
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `kind` | `SkToolbarKind` | — | Kind color |
+| `orientation` | `'horizontal' \| 'vertical'` | `'horizontal'` | Layout axis |
+| `corners` | `SkToolbarCorner[]` | `['top-left', 'top-right', 'bottom-right', 'bottom-left']` | Beveled corners |
+| `baseColor` | `string` | — | Override via `--sk-toolbar-color-base` |
+| `textColor` | `string` | — | Override via `--sk-toolbar-fg` |
+
+Always emits `role="toolbar"`. Orientation uses `sk-horizontal` / `sk-vertical` directly.
+By default all four corners are cut.
+
+**Output (defaults):**
+
+```html
+<div class="sk-toolbar sk-horizontal sk-cut-top-left sk-cut-top-right sk-cut-bottom-right sk-cut-bottom-left"
+     role="toolbar">
+    <!-- children -->
+</div>
+```
+
+**Output (with kind, no corners):**
+
+```html
+<div class="sk-toolbar sk-neutral sk-horizontal" role="toolbar">
+    <!-- children -->
+</div>
+```
+
+---
+
+### sidebar
+
+```typescript
+sidebar(props?: SidebarStaticProps, children?: string): string
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `kind` | `SkSidebarKind` | `'neutral'` | Kind color |
+| `side` | `'left' \| 'right'` | `'left'` | Mount side |
+| `dense` | `boolean` | `false` | Compact item padding |
+| `width` | `string` | — | CSS width (not reflected in classes) |
+| `baseColor` | `string` | — | Override via `--sk-sidebar-color-base` |
+
+Children are wrapped in `sk-sidebar-nav`. The helper emits the full inner panel structure.
+
+**Output (left sidebar, neutral):**
+
+```html
+<aside class="sk-sidebar sk-neutral">
+    <div class="sk-panel sk-neutral sk-md sk-cut-bottom-right sk-decoration-bottom-right sk-sidebar-panel">
+        <div class="sk-panel-scroll-content">
+            <nav class="sk-sidebar-nav"><!-- children --></nav>
+        </div>
+    </div>
+</aside>
+```
+
+**Output (right sidebar):**
+
+```html
+<aside class="sk-sidebar sk-neutral sk-sidebar-right">
+    <div class="sk-panel sk-neutral sk-md sk-cut-bottom-left sk-decoration-bottom-left sk-sidebar-panel">
+        <div class="sk-panel-scroll-content">
+            <nav class="sk-sidebar-nav"><!-- children --></nav>
+        </div>
+    </div>
+</aside>
+```
+
+---
+
+### breadcrumbs
+
+```typescript
+breadcrumbs(props?: BreadcrumbsStaticProps, children?: string): string
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `kind` | `SkBreadcrumbsKind` | `'neutral'` | Kind color |
+| `separator` | `string` | — | Separator character/HTML |
+| `baseColor` | `string` | — | Custom color override |
+
+**Output:**
+
+```html
+<nav class="sk-breadcrumbs sk-neutral" aria-label="Breadcrumbs"><!-- children --></nav>
+```
+
+---
+
+### pagination
+
+```typescript
+pagination(props?: PaginationStaticProps, children?: string): string
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `kind` | `SkPaginationKind` | `'neutral'` | Kind color |
+| `baseColor` | `string` | — | Custom color override |
+
+**Output:**
+
+```html
+<nav class="sk-pagination sk-neutral" aria-label="Pagination"><!-- children --></nav>
+```
+
+---
+
+### tag {#tag}
+
+```typescript
+tag(props?: TagStaticProps, children?: string): string
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `kind` | `ComponentKind` | `'neutral'` | Kind color |
+| `variant` | `SkTagVariant` | `'solid'` | Visual style |
+| `size` | `SkTagSize` | `'md'` | Tag size |
+| `removable` | `boolean` | `false` | Show remove button |
+| `baseColor` | `string` | — | Override via `--sk-tag-color-base` |
+| `textColor` | `string` | — | Override via `--sk-tag-fg` |
+
+Content is always wrapped in `sk-tag-content`. The remove button is only emitted when
+`removable: true`.
+
+**Output (simple):**
+
+```html
+<span class="sk-tag sk-neutral sk-solid sk-md">
+    <span class="sk-tag-content">Label</span>
+</span>
+```
+
+**Output (removable):**
+
+```html
+<span class="sk-tag sk-neutral sk-solid sk-md sk-removable">
+    <span class="sk-tag-content">Label</span>
+    <button type="button" class="sk-tag-remove" aria-label="Remove">
+        <svg xmlns="http://www.w3.org/2000/svg" width="24" height="24"
+             viewBox="0 0 24 24" fill="none" stroke="currentColor"
+             stroke-width="2" stroke-linecap="round" stroke-linejoin="round">
+            <line x1="18" y1="6" x2="6" y2="18"></line>
+            <line x1="6" y1="6" x2="18" y2="18"></line>
+        </svg>
+    </button>
+</span>
+```
+
+---
+
+### avatar {#avatar}
+
+```typescript
+avatar(props?: AvatarStaticProps): string
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `kind` | `ComponentKind` | `'neutral'` | Kind color |
+| `size` | `SkAvatarSize` | `'md'` | Avatar size |
+| `src` | `string` | — | Image URL — highest priority |
+| `alt` | `string` | `''` | Image alt text (used with `src`) |
+| `initials` | `string` | — | Up to 2 chars shown when no `src` — second priority |
+| `baseColor` | `string` | — | Override via `--sk-avatar-color-base` |
+| `textColor` | `string` | — | Override via `--sk-avatar-fg` |
+
+Note: no `shape` prop — the Vue component doesn't expose one.
+
+Fallback priority: `src` → `initials` → default person icon SVG.
+
+**Output (with src):**
+
+```html
+<div class="sk-avatar sk-neutral sk-md">
+    <img src="/avatar.jpg" alt="User name" class="sk-avatar-image">
+</div>
+```
+
+**Output (with initials "John Doe" → "JO"):**
+
+```html
+<div class="sk-avatar sk-primary sk-md">
+    <span class="sk-avatar-initials">JO</span>
+</div>
+```
+
+**Output (default fallback):**
+
+```html
+<div class="sk-avatar sk-neutral sk-md">
+    <svg class="sk-avatar-icon" viewBox="0 0 24 24" fill="currentColor">
+        <path d="M12 12c2.21 0 4-1.79 4-4s-1.79-4-4-4-4 1.79-4 4 1.79 4 4 4zm0 2c-2.67 0-8 1.34-8 4v2h16v-2c0-2.66-5.33-4-8-4z"></path>
+    </svg>
+</div>
+```
+
+---
+
+### field {#field}
+
+```typescript
+field(props?: FieldStaticProps, children?: string): string
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `label` | `string` | — | Label text |
+| `description` | `string` | — | Help text below the input (suppressed when `error` is set) |
+| `error` | `string` | — | Error message — also triggers `sk-has-error` class |
+| `required` | `boolean` | `false` | Adds `*` span to label |
+| `labelPosition` | `SkFieldLabelPosition` | `'top'` | Label placement |
+| `id` | `string` | — | Field ID — forwarded to `label[for]` and error/description `id` attrs |
+
+The `sk-field-input-wrapper` div is always emitted. Label, description, and error paragraphs
+are only emitted when their props are set. Description is suppressed when an error is present.
+
+**Output (label + input):**
+
+```html
+<div class="sk-field sk-label-top">
+    <label for="email" class="sk-field-label">Email</label>
+    <div class="sk-field-input-wrapper"><!-- children --></div>
+</div>
+```
+
+**Output (with error):**
+
+```html
+<div class="sk-field sk-label-top sk-has-error">
+    <label for="email" class="sk-field-label">Email</label>
+    <div class="sk-field-input-wrapper"><!-- children --></div>
+    <p id="email-error" class="sk-field-error">Please enter a valid email.</p>
+</div>
+```
+
+**Output (required + description):**
+
+```html
+<div class="sk-field sk-label-top">
+    <label for="bio" class="sk-field-label">Bio<span class="sk-field-required">*</span></label>
+    <div class="sk-field-input-wrapper"><!-- children --></div>
+    <p id="bio-description" class="sk-field-description">Max 160 characters.</p>
+</div>
+```
+
+---
+
+### table {#table}
+
+```typescript
+table(props?: TableStaticProps, children?: string): string
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `kind` | `SkTableKind` | `'neutral'` | Kind color |
+| `variant` | `SkTableVariant` | `'default'` | Visual variant |
+| `striped` | `boolean` | `false` | Alternating row backgrounds |
+| `hoverable` | `boolean` | `true` | Row hover highlight |
+| `bordered` | `boolean` | `true` | Outer border |
+| `innerBorders` | `boolean` | `false` | Inner cell borders (suppressed by default) |
+| `darkBackground` | `boolean` | `false` | Dark background on wrapper |
+| `subtle` | `boolean` | `false` | Reduced contrast on wrapper + table |
+| `baseColor` | `string` | — | Override via `--sk-table-color-base` |
+| `textColor` | `string` | — | Override via `--sk-table-fg` |
+
+Emits a `sk-table-wrapper` div wrapping a `<table>`. Both elements receive modifier classes.
+
+**Output (defaults — hoverable + bordered + no-inner-borders):**
+
+```html
+<div class="sk-table-wrapper sk-table-wrapper-neutral">
+    <table class="sk-table sk-neutral sk-default sk-hoverable sk-bordered sk-no-inner-borders">
+        <!-- thead + tbody -->
+    </table>
+</div>
+```
+
+**Output (striped, inner borders enabled, dark background):**
+
+```html
+<div class="sk-table-wrapper sk-table-wrapper-neutral sk-dark-background">
+    <table class="sk-table sk-neutral sk-default sk-striped sk-hoverable sk-bordered">
+        <!-- thead + tbody -->
+    </table>
+</div>
+```
+
+---
+
+### tooltip
+
+```typescript
+tooltip(props?: TooltipStaticProps, children?: string): string
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `kind` | `SkTooltipKind` | `'neutral'` | Kind color |
+| `variant` | `SkTooltipVariant` | `'solid'` | Visual style |
+| `placement` | `SkTooltipSide` | `'top'` | Tooltip position |
+| `baseColor` | `string` | — | Custom color override |
+
+**Output:**
+
+```html
+<div class="sk-tooltip sk-neutral sk-solid sk-placement-top" role="tooltip">
+    <!-- children -->
+</div>
+```
+
+---
+
+### button
+
+```typescript
+button(props?: ButtonStaticProps, children?: string): string
+```
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `kind` | `SkButtonKind` | `'neutral'` | Kind color |
+| `size` | `SkButtonSize` | `'md'` | Button size |
+| `variant` | `SkButtonVariant` | `'solid'` | Visual style |
+| `type` | `SkButtonType` | `'button'` | HTML button type |
+| `disabled` | `boolean` | `false` | Disabled state |
+| `loading` | `boolean` | `false` | Loading state (adds `aria-busy="true"`) |
+| `pressed` | `boolean` | `false` | Pressed state (adds `aria-pressed="true"`) |
+| `dense` | `boolean` | `false` | Compact padding |
+| `href` | `string` | — | Render as `<a>` instead of `<button>` |
+
+Children are always wrapped in `sk-button-chrome`.
+
+**Output (button):**
+
+```html
+<button class="sk-button sk-neutral sk-md sk-solid" type="button">
+    <span class="sk-button-chrome">Label</span>
+</button>
+```
+
+**Output (anchor):**
+
+```html
+<a class="sk-button sk-accent sk-md sk-outline" href="/docs">
+    <span class="sk-button-chrome">Read the docs</span>
+</a>
+```
+
+---
+
+### input
+
+```typescript
+input(props?: InputStaticProps): string
+```
+
+**Props:** `kind`, `size`, `type`, `value`, `placeholder`, `name`, `id`, `disabled`, `readonly`, `required`
+
+**Output:**
+
+```html
+<input class="sk-input sk-neutral sk-md" type="text" />
+```
+
+---
+
+### textarea
+
+```typescript
+textarea(props?: TextareaStaticProps, children?: string): string
+```
+
+**Props:** `kind`, `size`, `placeholder`, `name`, `id`, `disabled`, `readonly`, `required`
+
+**Output:**
+
+```html
+<textarea class="sk-textarea sk-neutral sk-md"></textarea>
+```
+
+---
+
+### select
+
+```typescript
+select(props?: SelectStaticProps, children?: string): string
+```
+
+**Props:** `kind`, `size`, `name`, `id`, `disabled`, `required`
+
+Children are `<option>` elements composed by the caller.
+
+**Output:**
+
+```html
+<select class="sk-select sk-neutral sk-md">
+    <option value="">Choose…</option>
+    <option value="a">Option A</option>
+</select>
+```
+
+---
+
+### slider
+
+```typescript
+slider(props?: SliderStaticProps): string
+```
+
+**Props:** `kind`, `size`, `min`, `max`, `step`, `value`, `name`, `disabled`
+
+Single thumb only. All numeric props are accepted as strings.
+
+**Output:**
+
+```html
+<input class="sk-slider sk-neutral sk-md" type="range" min="0" max="100" value="40" />
+```
+
+---
+
+### colorPicker
+
+```typescript
+colorPicker(props?: ColorPickerStaticProps): string
+```
+
+**Props:** `size`, `value`, `name`, `disabled`
+
+Note: no `kind` prop — ColorPicker has no kind modifier.
+
+**Output:**
+
+```html
+<input class="sk-color-picker sk-md" type="color" value="#c4842d" />
+```
+
+---
+
+### checkbox
+
+```typescript
+checkbox(props?: CheckboxStaticProps, children?: string): string
+```
+
+**Props:** `kind`, `size`, `checked`, `disabled`, `required`, `name`
+
+Children become the label text inside `sk-checkbox-label`.
+
+**Output:**
+
+```html
+<label class="sk-checkbox sk-neutral sk-md">
+    <input type="checkbox" />
+    <span class="sk-checkbox-box"></span>
+    <span class="sk-checkbox-label">I agree to the terms</span>
+</label>
+```
+
+---
+
+### radio
+
+```typescript
+radio(props?: RadioStaticProps, children?: string): string
+```
+
+**Props:** `kind`, `size`, `name`, `value`, `checked`, `disabled`, `required`
+
+**Output:**
+
+```html
+<label class="sk-radio sk-neutral sk-md">
+    <input type="radio" name="color" value="red" />
+    <span class="sk-radio-dot"></span>
+    <span class="sk-radio-label">Red</span>
+</label>
+```
+
+---
+
+### switchInput
+
+```typescript
+switchInput(props?: SwitchStaticProps, children?: string): string
+```
+
+Named `switchInput` because `switch` is a reserved word in TypeScript/JavaScript.
+
+**Props:** `kind`, `size`, `name`, `checked`, `disabled`, `required`
+
+**Output:**
+
+```html
+<label class="sk-switch sk-neutral sk-md">
+    <input type="checkbox" />
+    <span class="sk-switch-track">
+        <span class="sk-switch-thumb"></span>
+    </span>
+    <span class="sk-switch-label">Enable notifications</span>
+</label>
+```
+
+---
+
+### numberInput
+
+```typescript
+numberInput(props?: NumberInputStaticProps): string
+```
+
+Stepper buttons are intentionally omitted — they require JS.
+
+**Props:** `kind`, `size`, `value`, `min`, `max`, `step`, `name`, `placeholder`, `disabled`, `readonly`, `required`
+
+**Output:**
+
+```html
+<div class="sk-number-input-wrapper sk-neutral sk-md">
+    <input class="sk-number-input-field" type="number" />
+</div>
+```
+
+---
+
+### tagsInput
+
+```typescript
+tagsInput(props?: TagsInputStaticProps, children?: string): string
+```
+
+**Props:** `kind`, `size`, `disabled`
+
+Children are pre-composed `tag()` elements. The add/remove chip behavior requires Vue.
+
+**Output:**
+
+```html
+<div class="sk-tags-input sk-neutral sk-md">
+    <!-- tag chip elements -->
+</div>
+```
+
+---
+
+### dropdown
+
+```typescript
+dropdown(props: DropdownStaticProps, children?: string): string
+```
+
+Note: `summary` is a **required** prop.
+
+**Props:**
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `summary` | `string` | — | **Required.** Text/HTML for the `<summary>` trigger |
+| `kind` | `SemanticKind` | `'neutral'` | Kind color |
+| `size` | `'sm' \| 'md' \| 'lg'` | `'md'` | Size |
+| `open` | `boolean` | `false` | Initial open state |
+
+This is a disclosure widget (`<details>`), not a menu. No focus trap, no keyboard navigation.
+
+**Output:**
+
+```html
+<details class="sk-dropdown sk-neutral sk-md">
+    <summary>Options ▾</summary>
+    <!-- children -->
+</details>
+```
+
+---
+
+## Type safety notes
+
+All helpers export their props interface. Import them if you want to type your own wrapper:
+
+```typescript
+import type { PanelStaticProps } from '@skewedaspect/sleekspace-ui/static';
+
+function myPanel(props: PanelStaticProps, content: string): string {
+    return panel(props, content);
+}
+```