@devalok/shilp-sutra 0.40.1 → 0.42.0

package/make-kit/components/text.md

@@ -0,0 +1,139 @@
+# Text
+
+Typography primitive. Use instead of raw `<h1>`–`<h6>`, `<p>`, `<span>` for any visible text.
+
+```tsx
+import { Text } from '@devalok/shilp-sutra/ui/text'
+```
+
+## When to use
+
+- Any visible text: headings, body copy, captions, section labels, inline microcopy.
+- Inline code spans inside body text? Pair with `<Code>`.
+- Polymorphic — `<Text as="span">`, `<Text as="div">`, etc. — to demote semantics while keeping visual weight.
+- Server-safe — renders in RSC trees without `'use client'`.
+
+## Variants
+
+| Variant | Default element | Use |
+|---|---|---|
+| `heading-2xl` | `h1` | Page title / hero. |
+| `heading-xl` | `h2` | Section title. |
+| `heading-lg` | `h3` | Sub-section title. |
+| `heading-md` | `h4` | Card title (used by `<CardTitle>`). |
+| `heading-sm` | `h5` | Compact sub-heading. |
+| `heading-xs` | `h6` | Smallest heading. |
+| `body-lg` | `p` | Lead paragraphs. |
+| `body-md` (default) | `p` | Standard body. |
+| `body-sm` | `p` | Dense body — captions inside cards, table cells. |
+| `body-xs` | `p` | Footnotes, fine print. |
+| `label-lg` / `md` / `sm` / `xs` | `span` | UPPERCASE section labels, eyebrows. |
+| `label-plain-lg` / `md` / `sm` / `xs` | `span` | Mixed-case labels (form labels, inline UI text). |
+| `caption` | `span` | Image / chart captions. |
+| `overline` | `span` | UPPERCASE marketing eyebrow. |
+| `code` | `code` | Inline monospace code. |
+
+`label-*` and `overline` variants are automatically uppercase. `label-plain-*` keeps mixed case.
+
+## Props
+
+| Prop | Type | Notes |
+|---|---|---|
+| `variant` | See variants table | Default `body-md`. |
+| `as` | `ElementType` | Override the auto-selected HTML element. |
+| `className` | `string` | For color / alignment overrides. Use semantic tokens only. |
+
+Plus all standard HTML attributes for whatever element it renders.
+
+## Examples
+
+**Page heading + body:**
+```tsx
+<Stack gap="ds-04">
+  <Text variant="heading-2xl">Projects</Text>
+  <Text variant="body-md" className="text-fg-muted">
+    A workspace for everything you ship.
+  </Text>
+</Stack>
+```
+
+**Section label + heading pair:**
+```tsx
+<Stack gap="ds-02">
+  <Text variant="label-sm" className="text-fg-muted">REVENUE</Text>
+  <Text variant="heading-xl">$2.4M</Text>
+  <Text variant="body-sm" className="text-fg-muted">+18% YoY</Text>
+</Stack>
+```
+
+**Visual demotion via `as`:**
+```tsx
+{/* h2-sized heading rendered as a div — useful when the element already has a heading ancestor */}
+<Card>
+  <CardHeader>
+    <CardTitle>Activity</CardTitle> {/* h4 */}
+    <Text variant="heading-xl" as="div">Weekly summary</Text>
+  </CardHeader>
+</Card>
+```
+
+**Inline span inside a paragraph:**
+```tsx
+<Text>
+  Press <Text as="kbd" variant="code">⌘ K</Text> to open the command palette.
+</Text>
+```
+
+**Caption under an image:**
+```tsx
+<Stack gap="ds-02">
+  <img src={chart} alt="" />
+  <Text variant="caption" className="text-fg-muted">
+    Figure 1. Active users by region.
+  </Text>
+</Stack>
+```
+
+**Form field label (label-plain variant):**
+```tsx
+<Stack gap="ds-02">
+  <Text variant="label-plain-sm" as="label" htmlFor="email">Email</Text>
+  <Input id="email" type="email" />
+</Stack>
+```
+
+Use `<Label>` for form fields when wired with FormField — `Text` is for non-form labels.
+
+**Body with inline code:**
+```tsx
+<Text>
+  Call <Code>onSubmit</Code> with the form values, or pass <Code>asChild</Code> to merge with a child element.
+</Text>
+```
+
+**Truncated single line:**
+```tsx
+<Text variant="body-sm" className="truncate max-w-[200px]">
+  {longUserName}
+</Text>
+```
+
+## Composability
+
+- **Server-safe.** No client hooks. Use freely in RSC trees.
+- **No context cascade** — pure typography primitive. Variants don't propagate through children.
+- **Underpins other components.** `<CardTitle>`, `<Alert>`'s title, `<PageHeader>`, `<EmptyState>`, `<SectionHeader>` all render Text internally with specific variants. Don't wrap another Text inside them.
+- **`as` overrides element only, not variant.** Visual weight stays. Use to demote semantics when you have a heading ancestor.
+
+See `foundations/typography.md` for the full type scale, line-height tokens, font stack.
+
+## Rules
+
+- Use Text for every visible text element. Don't write raw `<h1>` / `<p>` / `<span>` with manual classes.
+- Pick variant by semantic intent, not visual size. `heading-xl` is an `<h2>` — use it for section headings, not because you want big text in a body paragraph (use `as="div"` for that).
+- Don't wrap a `<Text>` inside `<CardTitle>` / `<Alert>` title — they already render Text internally.
+- `label-*` and `overline` variants are automatically uppercase. Don't add `uppercase` class.
+- For form labels paired with controls, use `<Label htmlFor>` from `/ui/label`. `Text variant="label-plain-*"` is for non-form labels.
+- Color overrides go through semantic tokens (`text-fg-muted`, `text-fg`, `text-fg-subtle`). Never raw Tailwind palette utilities.
+- Don't use Text inside another semantic heading — it produces nested headings that break screen-reader navigation.
+- For inline code, use `<Code>`. `Text variant="code"` works but Code is the dedicated primitive.

package/make-kit/components/toast.md

@@ -0,0 +1,193 @@
+# Toast
+
+Transient floating notification. Imperative API — call from event handlers, never render JSX.
+
+```tsx
+import { toast } from '@devalok/shilp-sutra/ui/toast'
+import { Toaster } from '@devalok/shilp-sutra/ui/toaster'
+```
+
+## When to use
+
+- Confirmation after an action (saved, copied, sent).
+- Non-blocking error feedback (failed to save — try again).
+- Async progress with success/failure resolution — use `toast.promise`.
+- File upload progress — use `toast.upload`.
+- Inline in-flow message that must stay visible? Use `<Alert>`.
+- Page-level strip (cookie banner, account warning)? Use `<Banner>`.
+- Modal interruption? Use `<Dialog>`.
+
+## Setup
+
+Mount `<Toaster />` **once** at the app root. Every `toast.*` call routes to this single container.
+
+```tsx
+// app/layout.tsx (Next.js) or src/App.tsx
+import { Toaster } from '@devalok/shilp-sutra/ui/toaster'
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        {children}
+        <Toaster />
+      </body>
+    </html>
+  )
+}
+```
+
+Without a mounted Toaster, every `toast.*` call is a silent no-op.
+
+## API
+
+```ts
+toast('Plain message')                                    // no icon, no accent
+toast.message('Same as plain')                            // alias
+toast.success('Saved!')                                   // green accent + check
+toast.error('Failed', { description })                    // red accent + X (assertive a11y)
+toast.warning('Disk low')                                 // yellow accent + triangle
+toast.info('New version available')                       // blue accent + info
+toast.loading('Saving...')                                // spinner, duration: Infinity
+toast.promise(asyncFn, { loading, success, error })       // one toast, three states
+toast.undo('Item deleted', { onUndo, duration? })         // 8s default, Undo button
+toast.upload({ files, id?, onRetry?, onRemove? })         // per-file progress
+toast.custom((id) => <MyComponent />, options)            // escape hatch
+toast.dismiss(id?)                                        // specific or all
+```
+
+## Options (every method)
+
+| Option | Type | Notes |
+|---|---|---|
+| `id` | `string` | Stable id — pass the same id to update / dismiss. |
+| `description` | `ReactNode` | Subline under the main message. |
+| `action` | `{ label, onClick }` | Right-aligned action button. |
+| `cancel` | `{ label, onClick }` | Right-aligned dismiss button. |
+| `duration` | `number` (ms) | Default `5000`. `Infinity` for loading toasts. |
+
+## Toaster props
+
+| Prop | Type | Default | Notes |
+|---|---|---|---|
+| `position` | `'top-left' \| 'top-center' \| 'top-right' \| 'bottom-left' \| 'bottom-center' \| 'bottom-right'` | `'bottom-right'` | Global default. |
+| `closeButton` | `boolean` | `false` | Show X on every toast. |
+| `duration` | `number` (ms) | `5000` | Global default — overridable per toast. |
+| `hotkey` | `string[]` | `['altKey', 'KeyT']` | Keyboard shortcut to focus the toast region. |
+| `visibleToasts` | `number` | `3` | Max stacked toasts; older ones move to a "+N" stack. |
+
+## Examples
+
+**Confirmation after save:**
+```tsx
+async function handleSave() {
+  await api.save(data)
+  toast.success('Changes saved')
+}
+```
+
+**Error with description:**
+```tsx
+toast.error('Upload failed', {
+  description: 'File is larger than 10 MB.',
+})
+```
+
+**Async with three states (`toast.promise`):**
+```tsx
+toast.promise(
+  api.publishPost(post),
+  {
+    loading: 'Publishing post...',
+    success: 'Published',
+    error: (err) => `Failed: ${err.message}`,
+  }
+)
+```
+
+One toast, transitions loading → success / error. No manual `.loading()` + `.success()` choreography.
+
+**Undo pattern (soft-delete):**
+```tsx
+function deleteTask(task) {
+  const snapshot = task
+  setTasks((prev) => prev.filter((t) => t.id !== task.id))
+  toast.undo('Task deleted', {
+    onUndo: () => setTasks((prev) => [...prev, snapshot]),
+  })
+}
+```
+
+Default 8s duration — gives the user time to react.
+
+**File upload progress:**
+```tsx
+const id = 'upload-' + Date.now()
+
+toast.upload({
+  id,
+  files: [
+    { id: 'f1', name: 'doc.pdf', size: 1_200_000, status: 'uploading', progress: 0 },
+  ],
+})
+
+xhr.onprogress = (e) => {
+  toast.upload({
+    id,
+    files: [{ id: 'f1', name: 'doc.pdf', size: 1_200_000, status: 'uploading', progress: (e.loaded / e.total) * 100 }],
+  })
+}
+
+xhr.onload = () => {
+  toast.upload({
+    id,
+    files: [{ id: 'f1', name: 'doc.pdf', size: 1_200_000, status: 'complete', progress: 100 }],
+  })
+}
+```
+
+Passing the same `id` updates the existing toast in place — no flicker.
+
+**Custom action:**
+```tsx
+toast('Project archived', {
+  action: { label: 'Open', onClick: () => router.push(`/archive/${id}`) },
+})
+```
+
+**Loading + manual resolution:**
+```tsx
+const id = toast.loading('Compiling...')
+try {
+  await compile()
+  toast.success('Compiled', { id })  // replaces the loading toast
+} catch (err) {
+  toast.error('Compile failed', { id, description: err.message })
+}
+```
+
+## Accessibility
+
+- `toast.error` uses `aria-live="assertive"` — screen readers interrupt the current announcement.
+- Other variants use `aria-live="polite"` — announced after current speech.
+- `<Toaster hotkey={['altKey', 'KeyT']}>` lets keyboard users jump to the toast region.
+
+## Composability
+
+- **One Toaster, many toasts:** Mount once in the root layout. Don't mount per-route — toasts will disappear on navigation.
+- **Imperative only:** No JSX render path. Call `toast.*` from event handlers, async flows, error boundaries.
+- **z-toast (top layer):** Sits above Dialog, Popover, everything. Don't wrap Toaster in a stacking context.
+- **SSR:** Toaster is marked `'use client'` — renders nothing on the server, hydrates on mount.
+
+See `foundations/motion.md` for the spring enter/exit, `foundations/color.md` for accent-bar colors.
+
+## Rules
+
+- Mount `<Toaster />` exactly once, at the app root. Multiple Toasters double-render every toast.
+- Never call `toast()` in render. Always from a handler, effect, or async function.
+- Don't use the removed `useToast()` hook or `toast({ title, color })` object syntax — both were removed in 0.18.
+- Use `toast.promise` for async flows — manual loading → success choreography is error-prone.
+- For undo affordances, use `toast.undo` — gives the consistent 8s duration plus the styled button.
+- Don't use Toast for content the user must read — they auto-dismiss. Use Alert or Banner instead.
+- Pass a stable `id` when you want to update / replace a toast — without an id, repeated calls stack.
+- `toast.error` is assertive — don't use it for soft warnings. Use `toast.warning`.

package/make-kit/foundations/color.md

@@ -0,0 +1,128 @@
+# Color
+
+The kit ships an OKLCH 12-step ramp per color family (`1`=app-bg, `9`=solid/accent, `12`=hi-contrast text) plus semantic role tokens that map onto those steps. **Use the semantic role.** Reach for the numeric step only when authoring custom states.
+
+## Philosophy
+
+- ~90% of surfaces should be neutral. Accent is for the primary CTA and ~1 emphasis per screen.
+- Never write hex / rgb / hsl. Never use Tailwind's stock palette utilities (`text-zinc-*`, `bg-blue-*`). They don't dark-mode-flip, they aren't themable.
+- Status color (error / success / warning / info) is reserved for state communication, not for decoration.
+
+## Decision tree — "what color do I use?"
+
+```
+Surface (background of a region)?
+  → page bg                → bg-surface-base
+  → card / widget / panel  → bg-surface-raised
+  → sidebar / topbar       → bg-surface-sunken
+  → dialog / popover / dropdown / input → bg-surface-overlay
+  → tooltip                → bg-surface-inverted
+  → disabled control       → bg-surface-disabled
+
+Text on a surface?
+  → primary body / heading → text-fg
+  → secondary / metadata   → text-fg-muted
+  → tertiary / hint        → text-fg-subtle
+  → on inverted bg         → text-surface-inverted-fg
+  → on accent-9 / solid    → text-accent-fg
+  → on error / success / warning / info solid → text-{error|success|warning|info}-fg
+
+Border?
+  → standard hairline      → border-surface-border
+  → emphasized             → border-surface-border-strong
+  → subtle divider         → border-surface-border-subtle
+  → state (form invalid)   → border-error-7 (or use Input state="error" instead)
+
+Status?
+  → error    → bg-error-3 / text-error-11 / border-error-7
+  → success  → bg-success-3 / text-success-11 / border-success-7
+  → warning  → bg-warning-3 / text-warning-11 / border-warning-7
+  → info     → bg-info-3 / text-info-11 / border-info-7
+
+Brand emphasis?
+  → primary CTA           → use <Button> default (no className needed)
+  → small accent tint     → bg-accent-3 / text-accent-11
+  → link                  → text-link (auto-handles hover + visited)
+```
+
+## Semantic surface tokens
+
+| Token | Use |
+|---|---|
+| `surface-base` | Page background. The "back wall" of the app. |
+| `surface-raised` | Cards, widgets, panels, anything that sits **on** the page. |
+| `surface-raised-hover` | Hover state on a `surface-raised` element. |
+| `surface-raised-active` | Pressed / active state. |
+| `surface-sunken` | Shell chrome (sidebar, topbar), board columns, segmented-control tracks. |
+| `surface-overlay` | Floating layers — dialogs, popovers, dropdowns, inputs, toasts. |
+| `surface-inverted` | Tooltips, inverted badges. Pair with `surface-inverted-fg`. |
+| `surface-disabled` | Disabled controls. Pair with `surface-fg-disabled`. |
+
+Available as: `bg-surface-*`, `text-surface-*`, `border-surface-*`.
+
+See `foundations/surfaces.md` for elevation rules and the shadow pairing matrix.
+
+## Foreground / text tokens
+
+| Token | Use |
+|---|---|
+| `text-fg` | Primary body + headings. |
+| `text-fg-muted` | Secondary content, metadata, helper text. |
+| `text-fg-subtle` | Tertiary content, placeholder text. |
+| `text-surface-inverted-fg` | Text on `surface-inverted`. |
+| `text-accent-fg` | Text on `bg-accent-9` (solid brand). |
+| `text-{error\|success\|warning\|info}-fg` | Text on the solid color background. Brand-swap safe. |
+| `text-link` | Anchor color (auto-hover + visited). |
+
+## Border tokens
+
+| Token | Use |
+|---|---|
+| `border-surface-border` | Default 1px line. |
+| `border-surface-border-strong` | Emphasized line — section dividers, table headers. |
+| `border-surface-border-subtle` | Hairline, lower contrast than default. |
+
+## Accent ramp (12 steps)
+
+Available as `accent-1` … `accent-12`. Apply via `bg-accent-N`, `text-accent-N`, `border-accent-N`. Steps map to roles:
+
+| Step | Role |
+|---|---|
+| 1 | App background tint |
+| 2 | Subtle background |
+| 3 | Component background (e.g. soft Button rest) |
+| 4 | Hover bg |
+| 5 | Active / pressed bg |
+| 6 | Border subtle |
+| 7 | Border default |
+| 8 | Border strong |
+| 9 | Solid fill (primary CTA, badge solid) |
+| 10 | Solid hover |
+| 11 | Lo-contrast text |
+| 12 | Hi-contrast text |
+
+The same 12-step pattern repeats for `error-*`, `success-*`, `warning-*`, `info-*` (subset: 2, 3, 4, 5, 6, 7, 9, 10, 11).
+
+## Theming — never hardcode
+
+Consumers swap the accent by overriding `--color-accent-1` through `--color-accent-12` in a `:root { }` block placed **after** the kit's CSS import. Dark mode is derived algorithmically — no separate dark overrides needed.
+
+```css
+/* In consumer's global.css, after @import "@devalok/shilp-sutra/css"; */
+:root {
+  --color-accent-9: oklch(0.55 0.18 230); /* swap brand to blue */
+  /* … the kit will compute related steps via OKLCH curves */
+}
+```
+
+## Rules
+
+- **Never** `bg-white` / `bg-black` / `bg-zinc-*` / `bg-pink-*`. Use semantic tokens.
+- **Never** put a color directly on a Button via className. Set `color="error"` (or whichever).
+- **Never** combine `border-*` and `shadow-*` tokens — shadow tokens contain a ring layer.
+- **Never** use `text-fg` on `bg-accent-9`. Use `text-accent-fg` (brand-swap safe).
+- **Never** invent step numbers. Steps 1, 2, 3, 4, 5, 6, 7, 9, 10, 11, 12 exist. Step 8 exists only on accent / neutral.
+
+## Forced-colors / Windows high-contrast
+
+The kit auto-remaps every semantic color to system keywords (`Canvas`, `CanvasText`, `Highlight`, `LinkText`, `GrayText`) under `@media (forced-colors: active)`. As long as you use semantic tokens, high-contrast mode just works. Hardcoded hex breaks it.

package/make-kit/foundations/dark-mode.md

@@ -0,0 +1,81 @@
+# Dark mode
+
+`.dark` class on `<html>` or `<body>` flips every token. No theme provider, no JS reshuffle.
+
+## How it works
+
+The kit declares a custom variant: `@custom-variant dark (&:where(.dark *))`. Identical semantics to Tailwind's old `darkMode: 'class'`. Adding `.dark` higher in the DOM cascades every semantic token to its dark counterpart.
+
+Dark tokens are **algorithmically derived** from the OKLCH primitives, not hand-tuned hex overrides. This means:
+
+- Surfaces *lighten* with elevation in dark mode (opposite of light mode). `surface-overlay` is brighter than `surface-base` when `.dark` is active.
+- Brand swaps (consumer overrides `--color-accent-9`) produce a coherent dark palette without extra work.
+- Status colors stay legible — solid backgrounds darken slightly (L=0.63→0.54 in dark mode) to maintain WCAG AA.
+
+## Wiring the toggle
+
+```tsx
+import { useColorMode } from '@devalok/shilp-sutra/hooks/use-color-mode'
+
+function ThemeToggle() {
+  const { mode, resolvedMode, setMode } = useColorMode()
+  // mode: 'light' | 'dark' | 'system'
+  // resolvedMode: 'light' | 'dark' (after resolving 'system')
+
+  return (
+    <Button
+      variant="soft"
+      onClick={() => setMode(resolvedMode === 'dark' ? 'light' : 'dark')}
+    >
+      <Icon icon={resolvedMode === 'dark' ? IconSun : IconMoon} />
+      {resolvedMode === 'dark' ? 'Light' : 'Dark'}
+    </Button>
+  )
+}
+```
+
+`useColorMode()` handles:
+- Persisting to `localStorage` (`shilp-sutra-color-mode`)
+- Listening to `prefers-color-scheme` when mode is `'system'`
+- Syncing across browser tabs
+- Adding/removing `.dark` on `<html>`
+
+## What you have to do per-component
+
+Nothing. Semantic tokens flip automatically. As long as you use `bg-surface-raised` not `bg-white`, dark mode works.
+
+The only exception: **images, illustrations, decorative SVGs**. These don't flip. Author them as theme-aware:
+
+```tsx
+{resolvedMode === 'dark' ? <img src="/logo-dark.svg" /> : <img src="/logo-light.svg" />}
+```
+
+Or use a single CSS-variable-driven SVG (`fill="currentColor"` + `text-fg`).
+
+## Forced-colors (Windows high-contrast)
+
+Independent of `.dark`. Activated by the OS. Every semantic color remaps to system keywords (`Canvas`, `CanvasText`, `Highlight`, `LinkText`, `GrayText`) under `@media (forced-colors: active)`. No work needed if you use semantic tokens.
+
+## Initial load — avoid the flash
+
+Set the mode **before** React hydrates. Insert this script tag in `<head>` (Next.js: `app/layout.tsx`):
+
+```html
+<script>
+  (function () {
+    var m = localStorage.getItem('shilp-sutra-color-mode') || 'system';
+    var dark = m === 'dark' || (m === 'system' && matchMedia('(prefers-color-scheme: dark)').matches);
+    if (dark) document.documentElement.classList.add('dark');
+  })();
+</script>
+```
+
+Without this, light mode flashes on first paint when the user prefers dark.
+
+## Rules
+
+- **Never** hardcode hex / Tailwind palette colors. They don't dark-mode flip.
+- **Never** write a `dark:bg-*` override on a semantic token — the token already handles dark mode.
+- **For images**, use conditional rendering off `resolvedMode`.
+- **Wire the head script** to prevent the FOUC on first paint.
+- Default to `'system'` mode unless the product is explicitly light-only or dark-only.

package/make-kit/foundations/icons.md

@@ -0,0 +1,107 @@
+# Icons
+
+The kit uses **Tabler Icons** exclusively. Custom icon libraries are not supported.
+
+## Install
+
+`@tabler/icons-react` is declared as a peer dependency:
+
+```bash
+npm i @tabler/icons-react
+```
+
+## Import + use
+
+```tsx
+import { Icon } from '@devalok/shilp-sutra/ui/icon'
+import { IconHome, IconUser, IconSettings } from '@tabler/icons-react'
+
+<Icon icon={IconHome} />
+<Icon icon={IconUser} size={20} />
+<Icon icon={IconSettings} className="text-fg-muted" />
+```
+
+Or pass the component directly to a prop that accepts `IconInput`:
+
+```tsx
+<Button startIcon={IconPlus}>Add</Button>
+<Badge icon={IconCheck}>Verified</Badge>
+```
+
+## `IconInput` (universal icon prop type)
+
+Every icon-accepting prop across the kit (`startIcon`, `endIcon`, `icon`, `leftIcon`, `rightIcon`) takes `IconInput`. Four shapes work interchangeably:
+
+```tsx
+// 1. Component reference (Tabler component)
+<Button startIcon={IconPlus} />
+
+// 2. Rendered <Icon> element
+<Button startIcon={<Icon icon={IconPlus} />} />
+
+// 3. Rendered Tabler element directly
+<Button startIcon={<IconPlus />} />
+
+// 4. Any custom node (svg, span with bg)
+<Button startIcon={<MyCustomIcon />} />
+```
+
+Prefer shape 1 (component ref) — the kit applies the right size and color via context.
+
+## Sizing via `IconProvider`
+
+Don't add `className="h-4 w-4"` on every Icon. Wrap a subtree:
+
+```tsx
+import { IconProvider } from '@devalok/shilp-sutra/ui/icon-context'
+
+<IconProvider size={16}>
+  <NavSection>
+    <Icon icon={IconHome} />
+    <Icon icon={IconUser} />
+    {/* all icons here = 16px */}
+  </NavSection>
+</IconProvider>
+```
+
+Override per-icon with `<Icon icon={...} size={24} />`.
+
+Default sizes by component context:
+
+| Context | Default size |
+|---|---|
+| Button (md) | 16 |
+| Button (sm / xs) | 14 |
+| Button (lg / xl) | 18 / 20 |
+| Input (any size) | 16 |
+| Badge | 12 |
+| Standalone | 16 (recommended) |
+
+## Color
+
+Icons inherit `currentColor` by default. To color one:
+
+```tsx
+<Icon icon={IconAlertTriangle} className="text-warning-11" />
+<Icon icon={IconCheck} className="text-success-11" />
+```
+
+Inside a `<Button>` or `<Badge>`, color is inherited from the button/badge — don't override.
+
+## Multi-color / branded icons (OAuth, etc.)
+
+OAuthButton ships brand glyphs for 13 providers. To use a brand's official multi-color SVG, pass `icon` to override:
+
+```tsx
+<OAuthButton provider="google" icon={<GoogleColorSVG />} />
+```
+
+For custom branded icons elsewhere, use raw `<svg>` — `<Icon>` is for Tabler outline glyphs.
+
+## Rules
+
+- **Tabler only** — no lucide-react, no heroicons, no mui-icons. The kit is sized for Tabler's stroke weight.
+- **Use `<Icon icon={...} />`** — don't render Tabler components directly when inside a kit component that accepts `IconInput`.
+- **Don't size with className** (`h-4 w-4`) — use `size` prop or `IconProvider`.
+- **Don't color icons inside Button / Badge** — they inherit from the parent. Color only on standalone icons.
+- **Don't pass a string** (`"check"`) — `IconInput` excludes strings/numbers. Always a component or element.