@skunkworksai/ui-kit 0.1.18

package/rules/toggle-group.md

@@ -0,0 +1,50 @@
+# AppToggleGroup
+
+> Docs: https://ui-kit.vercel.app/docs/components/toggle-group
+
+```tsx
+import { AppToggleGroup, AppToggleGroupItem } from "@/components/primitives/AppToggleGroup"
+```
+
+## AppToggleGroup
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `type` | `"single" \| "multiple"` | — | Determines if one or multiple items can be pressed |
+| `variant` | `"default" \| "outline"` | `"default"` | Visual style shared by all items |
+| `size` | `"default" \| "sm" \| "lg"` | `"default"` | Size shared by all items |
+| `value` | `string \| string[]` | — | Controlled value |
+| `onValueChange` | `(value: any) => void` | — | Callback when value changes |
+
+## AppToggleGroupItem
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `value` | `string` | — | Unique value for this item |
+| `disabled` | `boolean` | `false` | Disables this item |
+
+## Usage
+
+### Single Select
+```tsx
+<AppToggleGroup type="single">
+  <AppToggleGroupItem value="left">Left</AppToggleGroupItem>
+  <AppToggleGroupItem value="center">Center</AppToggleGroupItem>
+  <AppToggleGroupItem value="right">Right</AppToggleGroupItem>
+</AppToggleGroup>
+```
+
+### Multiple Select (Outline)
+```tsx
+<AppToggleGroup type="multiple" variant="outline">
+  <AppToggleGroupItem value="bold"><Bold /></AppToggleGroupItem>
+  <AppToggleGroupItem value="italic"><Italic /></AppToggleGroupItem>
+</AppToggleGroup>
+```
+
+## Rules
+- ✅ Use `AppToggleGroup` for related sets of options
+- ✅ Set `type="single"` or `type="multiple"` explicitly
+- ✅ Use `variant="outline"` when items should be clearly separated
+- ❌ Do not add hover styles to the `ToggleGroup` container — hover belongs on items only
+- ❌ If a prop you need is missing, stop and inform the design team

package/rules/toggle.md

@@ -0,0 +1,40 @@
+# AppToggle
+
+> Docs: https://ui-kit.vercel.app/docs/components/toggle
+
+```tsx
+import { AppToggle } from "@/components/primitives/AppToggle"
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `"default" \| "outline"` | `"default"` | Visual style |
+| `size` | `"default" \| "sm" \| "lg"` | `"default"` | Size of the toggle |
+| `pressed` | `boolean` | — | Controlled pressed state |
+| `onPressedChange` | `(pressed: boolean) => void` | — | Callback when pressed state changes |
+| `disabled` | `boolean` | `false` | Disables the toggle |
+
+## Usage
+
+### Basic
+```tsx
+<AppToggle aria-label="Toggle italic">
+  <Italic className="h-4 w-4" />
+</AppToggle>
+```
+
+### Outline variant
+```tsx
+<AppToggle variant="outline" aria-label="Toggle bold">
+  <Bold className="h-4 w-4" />
+</AppToggle>
+```
+
+## Rules
+- ✅ Use `AppToggle` for simple on/off states that don't look like switches
+- ✅ Always provide an `aria-label` when using icon-only toggles
+- ✅ Use `variant="outline"` for secondary actions
+- ❌ Do not use `AppToggle` for navigation
+- ❌ If a prop you need is missing, stop and inform the design team

package/rules/tokens.md

@@ -0,0 +1,88 @@
+# Token rules
+
+## Where tokens are defined
+
+All design tokens are CSS custom properties defined in `dist/tokens-source.css` (shipped with the package). This file is the single source of truth for all color, typography, radius, shadow, and spacing values.
+
+## Token source file
+
+```
+node_modules/@skunkworksai/ui-kit/dist/tokens-source.css
+```
+
+Tweakcn-compatible format — contains `@import "tailwindcss"`, `:root {}`, `.dark {}`, and `@theme inline {}` blocks.
+
+## Required setup — scaffold tokens.css
+
+`@skunkworksai/ui-kit/styles` ships infrastructure-only CSS — no color values. Without a token file the UI renders with no colors.
+
+During project setup, copy the token source into the consumer project:
+
+```bash
+cp node_modules/@skunkworksai/ui-kit/dist/tokens-source.css src/tokens.css
+```
+
+Then import both files in the app entry — **order matters**:
+
+```ts
+// main.tsx
+import '@skunkworksai/ui-kit/styles'  // infrastructure first
+import './tokens.css'                   // token values second
+```
+
+## Customizing tokens
+
+Edit `src/tokens.css` directly. Use [tweakcn.com](https://tweakcn.com) to adjust values visually — paste the file in, tweak, paste back.
+
+```css
+/* src/tokens.css */
+:root {
+  --primary: oklch(0.6 0.2 250);
+  --radius: 0.75rem;
+}
+
+.dark {
+  --primary: oklch(0.65 0.2 250);
+}
+```
+
+## Using tokens in components
+
+Always reference tokens via Tailwind utility classes, never hardcode values:
+
+```tsx
+// ✅ Correct
+<div className="bg-background text-foreground" />
+<div className="bg-primary text-primary-foreground" />
+<div className="border-border rounded-lg shadow-md" />
+
+// ❌ Wrong
+<div style={{ background: '#fff', color: '#111' }} />
+<div className="bg-blue-500" />
+```
+
+## Available token groups
+
+| Group | Tokens |
+|-------|--------|
+| Brand | `--primary`, `--primary-foreground`, `--secondary`, `--secondary-foreground`, `--accent`, `--accent-foreground` |
+| Surface | `--background`, `--foreground`, `--card`, `--card-foreground`, `--popover`, `--popover-foreground`, `--muted`, `--muted-foreground` |
+| Status | `--destructive`, `--destructive-foreground`, `--success`, `--success-foreground`, `--warning`, `--warning-foreground` |
+| Border | `--border`, `--input`, `--ring` |
+| Sidebar | `--sidebar`, `--sidebar-foreground`, `--sidebar-primary`, `--sidebar-primary-foreground`, `--sidebar-accent`, `--sidebar-accent-foreground`, `--sidebar-border`, `--sidebar-ring` |
+| Shape | `--radius` (base), `--radius-sm`, `--radius-md`, `--radius-lg`, `--radius-xl` |
+| Shadow | `--shadow`, `--shadow-sm`, `--shadow-md`, `--shadow-lg`, `--shadow-xl`, `--shadow-2xl` |
+| Typography | `--font-sans`, `--font-mono`, `--font-serif` |
+| Charts | `--chart-1` through `--chart-5` |
+
+## Dark mode
+
+Dark mode activates when `.dark` class is on a parent element (managed by `AppThemeProvider`). Tokens update automatically — no `dark:` Tailwind prefix needed on color classes.
+
+```tsx
+// ✅ Correct — color flips automatically in dark mode
+<div className="bg-background text-foreground" />
+
+// ❌ Wrong — manual dark override, fighting the token system
+<div className="bg-white dark:bg-gray-900" />
+```

package/rules/tooltip.md

@@ -0,0 +1,78 @@
+# AppTooltip
+
+> Docs: https://ui-kit.vercel.app/docs/components/tooltip
+
+```tsx
+import { AppTooltip, AppTooltipProvider, AppTooltipTrigger, AppTooltipContent } from "@/components/primitives/AppTooltip"
+```
+
+## AppTooltip
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `delayDuration` | `number` | `700` | Delay in ms before showing the tooltip |
+| `open` | `boolean` | — | Controlled open state |
+| `onOpenChange` | `(open: boolean) => void` | — | Callback when open state changes |
+
+## AppTooltipTrigger
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `asChild` | `boolean` | `false` | Merges props onto child element. Use when wrapping an existing interactive element. |
+
+## AppTooltipContent
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `side` | `"top" \| "right" \| "bottom" \| "left"` | `"top"` | Preferred side for the content |
+| `sideOffset` | `number` | `4` | Distance from the trigger in pixels |
+
+## Usage
+
+### Basic
+```tsx
+<AppTooltipProvider>
+  <AppTooltip>
+    <AppTooltipTrigger asChild>
+      <AppButton variant="outline">Hover me</AppButton>
+    </AppTooltipTrigger>
+    <AppTooltipContent>
+      <p>Add to library</p>
+    </AppTooltipContent>
+  </AppTooltip>
+</AppTooltipProvider>
+```
+
+### With keyboard shortcut
+```tsx
+<AppTooltipContent>
+  <p className="flex items-center gap-1.5">
+    Bold
+    <kbd className="pointer-events-none rounded border border-primary-foreground/20 bg-primary-foreground/10 px-1 font-mono text-[10px]">
+      ⌘B
+    </kbd>
+  </p>
+</AppTooltipContent>
+```
+
+### Tooltip on a disabled button
+```tsx
+<AppTooltipTrigger asChild>
+  <span tabIndex={0} className="inline-flex">
+    <AppButton variant="outline" disabled>Disabled</AppButton>
+  </span>
+</AppTooltipTrigger>
+```
+
+## Rules
+- ✅ Always wrap `AppTooltip` in `AppTooltipProvider` (place at app root or layout level)
+- ✅ Use `asChild` on `AppTooltipTrigger` when wrapping an existing interactive element
+- ✅ For disabled buttons: wrap in `<span tabIndex={0}>` so pointer events reach the trigger
+- ✅ Keep tooltip content brief and purely informative
+- ✅ Arrow is rendered automatically — do not add one manually
+- ❌ Do not put interactive elements (buttons, links) inside `AppTooltipContent`
+- ❌ If a prop you need is missing, stop and inform the design team
+
+## Responsive
+
+`AppTooltipContent` renders `null` on mobile (<768px) because hover does not exist on touch. Every element that uses a tooltip as its only accessible label must also carry an `aria-label` on the trigger so it remains accessible on mobile.

package/rules/typography.md

@@ -0,0 +1,81 @@
+# AppTypography
+
+> Docs: https://ui-kit.vercel.app/docs/components/typography
+
+```tsx
+import { AppTypography } from "@skunkworksai/ui-kit"
+import type { AppTypographyVariant } from "@skunkworksai/ui-kit"
+```
+
+## Props
+
+| Prop | Type | Default | Description |
+|------|------|---------|-------------|
+| `variant` | `AppTypographyVariant` | — | **Required.** Controls visual style and default HTML tag. |
+| `as` | `React.ElementType` | — | Overrides the rendered HTML tag while keeping the variant's styles. |
+| `className` | `string` | — | Additional Tailwind classes merged via `cn()`. |
+
+## Variants
+
+| Variant | Tag | Notes |
+|---------|-----|-------|
+| `display` | `h1` | Largest heading. For hero/page-level display text. |
+| `h1` | `h1` | Page title. `text-4xl font-extrabold tracking-tight`. |
+| `h2` | `h2` | Section heading. Includes bottom border. |
+| `h3` | `h3` | Subsection heading. |
+| `h4` | `h4` | Label-weight heading. |
+| `p` | `p` | Body paragraph. Adds top margin when not first child. |
+| `lead` | `p` | Large intro text. `text-xl text-muted-foreground`. |
+| `large` | `div` | Semibold large text. Use for callout values. |
+| `small` | `small` | Caption / footnote text. |
+| `muted` | `p` | Secondary / helper text. `text-muted-foreground`. |
+| `mono` | `p` | Monospace text for non-code inline values. |
+| `blockquote` | `blockquote` | Styled block quote with left border. |
+| `code` | `code` | Inline code snippet. Muted background, monospace. |
+| `list` | `ul` | Disc list. Children must be `<li>` elements. |
+
+## Usage
+
+### Headings
+```tsx
+<AppTypography variant="display">Welcome to UI Kit</AppTypography>
+<AppTypography variant="h1">Page Title</AppTypography>
+<AppTypography variant="h2">Section Heading</AppTypography>
+<AppTypography variant="h3">Subsection</AppTypography>
+<AppTypography variant="h4">Label</AppTypography>
+```
+
+### Body text
+```tsx
+<AppTypography variant="lead">A short intro sentence that sets context.</AppTypography>
+<AppTypography variant="p">Full paragraph body text with comfortable line height.</AppTypography>
+<AppTypography variant="small">Supplementary detail or caption.</AppTypography>
+<AppTypography variant="muted">Helper text or secondary information.</AppTypography>
+<AppTypography variant="mono">const value = 42</AppTypography>
+```
+
+### List
+```tsx
+<AppTypography variant="list">
+  <li>First item</li>
+  <li>Second item</li>
+  <li>Third item</li>
+</AppTypography>
+```
+
+### Override tag with `as` prop
+```tsx
+{/* h2 styles on an h3 element for correct document outline */}
+<AppTypography variant="h2" as="h3">Section Title</AppTypography>
+
+{/* p styles inline */}
+<AppTypography variant="p" as="span">Inline text</AppTypography>
+```
+
+## Rules
+- ✅ Always use `AppTypography` for all styled text — never raw `<h1>`–`<h4>`, `<p>`, `<blockquote>`, `<code>`
+- ✅ Use `as` when semantic HTML must differ from the visual style
+- ✅ For `list` variant, always use `<li>` children
+- ❌ Never set `font-size`, `font-weight`, or color directly — use the `variant` prop
+- ❌ Never use arbitrary Tailwind type classes (`text-[13px]`) — request a variant instead
+- ❌ If a variant you need is missing, stop and inform the design team

package/scripts/scaffold.mjs

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { cpSync, existsSync } from 'node:fs'
+import { join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+
+const pkgRoot = resolve(fileURLToPath(new URL('.', import.meta.url)), '..')
+const cwd = process.cwd()
+
+function scaffold(src, dest, label) {
+  if (existsSync(dest)) {
+    console.log(`[skip] ${label} already exists at ${dest} — delete it first to re-scaffold`)
+    return
+  }
+  cpSync(src, dest, { recursive: true })
+  console.log(`[ok]   ${label} -> ${dest}`)
+}
+
+scaffold(
+  join(pkgRoot, 'dist', 'tokens-source.css'),
+  join(cwd, 'src', 'tokens.css'),
+  'tokens.css'
+)
+
+scaffold(
+  join(pkgRoot, 'dist', 'assets'),
+  join(cwd, 'src', 'assets'),
+  'assets/'
+)