npm - astralkit - Versions diffs - 0.2.0 → 0.3.0 - Mend

astralkit 0.2.0 → 0.3.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (22) hide show

package/ai-rules.md +481 -100
package/astralkit-theme-v4.css +612 -0
package/astralkit-theme.css +266 -32
package/astralkit-utilities.css +516 -540
package/lib/utils.js +23 -1
package/package.json +13 -3
package/palettes.css +299 -0
package/primitives/accounts.css +435 -0
package/primitives/animations.css +136 -0
package/primitives/avatar.css +410 -0
package/primitives/badges.css +231 -0
package/primitives/effects.css +388 -0
package/primitives/focus.css +25 -0
package/primitives/forms.css +2155 -0
package/primitives/icons.css +90 -0
package/primitives/layout.css +217 -0
package/primitives/mobile.css +557 -0
package/primitives/navigation.css +1057 -0
package/primitives/sidebar.css +1819 -0
package/primitives/typography.css +324 -0
package/tailwind.cjs +416 -0
package/tailwind.js +491 -0

package/ai-rules.md CHANGED Viewed

@@ -11,6 +11,35 @@ AstralKit uses a **fluid responsive system** — typography and spacing scale co
 ---
+## DO NOT Use (Anti-Slop Rules)
+These constraints prevent generic "AI slop" output. Follow them strictly.
+**Never use raw Tailwind colors.** No `bg-white`, `text-gray-900`, `border-slate-200`. Always use `bg-ak-bg`, `text-ak-text`, `border-ak-border`. Raw colors break theming, dark mode, and palette switching.
+**Never use Framer Motion.** CSS animations only. Use `ak-*` animation tokens (`duration-ak-base`, `ease-ak-default`) or effect primitives (`.ak-press`, `.ak-card-glow`).
+**Never use shadows on containment surfaces.** No `shadow-md` on cards, panels, or dropdowns. Use `border border-ak-border` instead. Shadows are reserved for modals and floating elements only.
+**Never use generic fonts.** The system fonts are DM Sans (`font-ak-sans`), DM Serif Display (`font-ak-serif`), and JetBrains Mono (`font-ak-mono`). Do not add Arial, Inter, Roboto, or system-ui.
+**Never put gradients on every surface.** Gradients are for hero sections and marketing areas only (`.ak-mesh-dark`, `.ak-mesh-light`). Dashboard chrome, cards, and data views use flat semantic surfaces.
+**Before generating a new component, look at existing code first.** Check the project for similar patterns. Match the exact spacing, border treatment, and typography of what already exists. Reference-based output is always better than description-based output.
+---
+## Size Hierarchy Rule
+Create hierarchy through **extreme size jumps**, not subtle ones:
+- **3x+ jumps create hierarchy** — 14px body → 48px heading = clear
+- **1.5x jumps look muddy** — 14px body → 20px heading = unclear
+- **Weight extremes work the same** — 400 vs 700 is clear, 400 vs 500 is muddy
+Apply this to font sizes, spacing, and icon sizes. If two elements look similar, make one dramatically bigger or smaller — don't split the difference.
+---
 ## Token Naming
 All AstralKit tokens use the `ak-` prefix:
@@ -93,6 +122,51 @@ Static spacing: `*-ak-0` · `*-ak-px` · `*-ak-0_5` · `*-ak-1` · `*-ak-1_5` ·
 ---
+## The 60-30-10 Rule
+Every screen must follow this color ratio:
+- **60% — Neutral backgrounds** (`bg-ak-bg`, `bg-ak-surface`, `bg-ak-surface-2`). This is the dominant canvas.
+- **30% — Secondary neutrals** (cards, borders, muted text, secondary surfaces). Uses `border-ak-border`, `text-ak-text-secondary`, `bg-ak-hover`.
+- **10% — Accent** (`bg-ak-primary`, `text-ak-primary`, focus rings). CTAs, active states, links only.
+### Rules AI tools must follow:
+1. `bg-ak-primary` on a full-width section = rule broken. Accent should be buttons, badges, links — not backgrounds.
+2. Status colors (red/green/yellow) are NOT part of the accent budget. Keep them under 5%.
+3. One accent hue per screen. Don't mix primary blue buttons with teal links and purple icons.
+4. In dark mode, accent is MORE visible against dark surfaces — use even less.
+5. If more than 3 elements on screen use `bg-ak-primary` or `text-ak-primary`, it's too much.
+---
+## Dark Mode
+AstralKit includes a complete dark mode. Add `.dark` class to `<html>` (standard with `next-themes`) or use `[data-theme="dark"]`.
+All semantic tokens flip automatically — no per-component changes needed.
+### What changes:
+- Backgrounds: light surfaces → dark surfaces (#111→#252)
+- Text: dark text → light text (#f4f4f5)
+- Borders: solid hex → alpha (`rgba(255,255,255,0.10)`) — adapts to any surface depth
+- Elevation: shadows disappear → lighter surface tones indicate depth
+- Accent: lightened for contrast (Tailwind 600→400 shift)
+- Status colors: lightened (red gets biggest jump)
+- Small shadows (`xs`, `sm`): removed. Only `md`+ for modals/sheets.
+### What stays:
+- All spacing, typography, radius, layout tokens are unchanged
+- Component structure is unchanged — only colors flip
+### For AI tools generating dark mode UI:
+- Never use raw white (`#fff`) for body text — use `text-ak-text` (#f4f4f5)
+- Reserve pure white for headings only, or trust `text-ak-text`
+- Borders must be `border-ak-border` (alpha in dark mode) — never hardcode gray hex
+- No `shadow-ak-sm` in dark mode — it renders as invisible. Use border instead
+- Glass effects: use `bg-ak-surface-glass` (white tint in dark mode, not dark tint)
+---
 ## Semantic Colors
 Prefer AstralKit's semantic color tokens over raw Tailwind colors. This enables theming and dark mode.
@@ -102,14 +176,14 @@ Instead of:  class="bg-white text-gray-900 border-gray-200"
 Prefer:      class="bg-ak-bg text-ak-text border-ak-border"
 ```
-### Background:
-`bg-ak-bg` · `bg-ak-surface` · `bg-ak-surface-2` · `bg-ak-hover` · `bg-ak-active` · `bg-ak-elevated`
-### Richer surfaces:
-`bg-ak-surface-raised` · `bg-ak-surface-raised-soft` · `bg-ak-surface-glass` · `bg-ak-surface-glass-strong`
-### Decorative highlights / loading:
-`ak-highlight-soft` · `ak-highlight-strong` · `ak-skeleton-base` · `ak-skeleton-shine`
+### Background:
+`bg-ak-bg` · `bg-ak-surface` · `bg-ak-surface-2` · `bg-ak-hover` · `bg-ak-active` · `bg-ak-elevated`
+### Richer surfaces:
+`bg-ak-surface-raised` · `bg-ak-surface-raised-soft` · `bg-ak-surface-glass` · `bg-ak-surface-glass-strong`
+### Decorative highlights / loading:
+`ak-highlight-soft` · `ak-highlight-strong` · `ak-skeleton-base` · `ak-skeleton-shine`
 ### Text:
 `text-ak-text` · `text-ak-text-secondary` · `text-ak-text-muted` · `text-ak-text-disabled` · `text-ak-text-inverse`
@@ -149,10 +223,12 @@ Prefer:      class="max-w-ak-page mx-auto px-ak-3"
 ### Max-widths: `max-w-ak-xs` · `sm` · `md` · `lg` · `xl` · `2xl` · `3xl` · `4xl` · `prose` · `page` (80rem)
 ### Heights: `h-ak-nav` (nav bar) · `h-ak-touch` / `w-ak-touch` (touch target)
+### Table rows: `h-ak-row-compact` (40px) · `h-ak-row-default` (48px) · `h-ak-row-comfortable` (52px)
+### Page margin: `px-ak-fl-page-margin` — fluid side padding (16px mobile → 80px desktop)
 ---
-## Layout Primitives — Use Instead of Breakpoint Grids
+## Layout Primitives — Use Instead of Breakpoint Grids
 AstralKit provides breakpoint-free layout primitives:
@@ -166,94 +242,207 @@ AstralKit provides breakpoint-free layout primitives:
 ```
 Instead of:  class="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-4"
-Prefer:      class="ak-grid" style="--ak-grid-min: 280px"
-```
----
-## Visual Polish Primitives
-Use shared utilities for repeated surface and loading patterns instead of re-creating them in component CSS.
-- **`.ak-surface-raised`** — neutral elevated panel surface with border + shadow
-- **`.ak-surface-glass`** — translucent panel treatment with blur
-- **`.ak-sheen`** — reusable highlight overlay for cards/panels with pseudo-element
-- **`.ak-sheen-strong`** — stronger sheen variant
-- **`.ak-skeleton`** — shimmer loading block
-- **`.ak-skeleton-pill`** — pill-shaped skeleton
-- **`.ak-skeleton-circle`** — circular skeleton
-- **`.ak-card-shell`** — reusable card container primitive
-- **`.ak-card-shell-interactive`** — hover/focus lift for cards
-- **`.ak-card-shell-inner`** — internal vertical stack scaffold
-- **`.ak-card-shell-header`** — common card header layout with content + trailing action/badge
-- **`.ak-mobile-sheet-handle`** — standard grabber for bottom sheets and mobile drawers
-When to use shared utilities:
-- if the pattern is decorative and appears in multiple components
-- if the pattern depends on pseudo-elements or animation
-- if the pattern should inherit theme tokens and dark mode automatically
-Keep it component-local when:
-- the layout is unique to one component
-- the spacing/alignment logic is too specific to generalize cleanly
-### Healthy System Language
-Aim for components to describe themselves with clear semantic composition:
-- **"This is a raised card shell"** → use `.ak-card-shell`
-- **"This card/panel lifts on interaction"** → add `.ak-card-shell-interactive`
-- **"This panel has a sheen"** → add `.ak-sheen` only when the surface should feel elevated or premium
-- **"This is a standard skeleton block"** → use `.ak-skeleton`
-- **"This bottom sheet should feel draggable"** → add `.ak-mobile-sheet-handle`
-This keeps visual polish reusable without making every component look overdesigned.
-### Healthy Adoption Rules
-Use `.ak-card-shell` when:
-- the component is a bounded surface with border, radius, and elevation
-- multiple components need a consistent card/panel baseline
-- you want theming and dark mode to flow through shared tokens
-Use `.ak-sheen` when:
-- the surface is intentionally elevated, featured, or premium
-- the highlight improves depth without carrying meaning
-- the effect is subtle and optional
-Avoid `.ak-sheen` when:
-- the surface is already visually busy
-- the component is dense, data-heavy, or utilitarian enough that the effect becomes decorative noise
-- you would apply it to nearly every surface on the screen
-Use `.ak-skeleton` when:
-- the loading placeholder is generic and reusable
-- the component needs consistent loading behavior across the kit
-- the actual loading state is also exposed accessibly with status text or a live region
-Use `.ak-mobile-sheet-handle` when:
-- the surface is a mobile bottom sheet, drawer, or slide-up panel
-- the UI should communicate drag-to-dismiss affordance clearly
-- the handle should remain visually consistent across recurring sheet patterns
-Avoid `.ak-skeleton` when:
-- the component needs a very custom loading illustration or structure
-- the shimmer would interfere with readability or performance in dense contexts
-### Preferred Composition Order
-When a component needs these patterns, compose them from broadest surface to narrowest enhancement:
-1. Start with `.ak-card-shell` for the base container
-2. Add `.ak-card-shell-interactive` only if hover/focus lift is meaningful
-3. Add `.ak-sheen` only if the surface should feel highlighted
-4. Use `.ak-skeleton` only on placeholder elements, not on the final loaded surface
-This preserves restraint while keeping the primitives easy to reach for.
----
-## When Breakpoints ARE Acceptable
+Prefer:      class="ak-grid" style="--ak-grid-min: 280px"
+```
+---
+## Visual Polish Primitives
+Use shared utilities for repeated surface and loading patterns instead of re-creating them in component CSS.
+- **`.ak-surface-raised`** — neutral elevated panel surface with border + shadow
+- **`.ak-surface-glass`** — translucent panel treatment with blur
+- **`.ak-sheen`** — reusable highlight overlay for cards/panels with pseudo-element
+- **`.ak-sheen-strong`** — stronger sheen variant
+- **`.ak-skeleton`** — shimmer loading block
+- **`.ak-skeleton-pill`** — pill-shaped skeleton
+- **`.ak-skeleton-circle`** — circular skeleton
+- **`.ak-card-shell`** — reusable card container primitive
+- **`.ak-card-shell-interactive`** — hover/focus lift for cards
+- **`.ak-card-shell-inner`** — internal vertical stack scaffold
+- **`.ak-card-shell-header`** — common card header layout with content + trailing action/badge
+- **`.ak-mobile-sheet-handle`** — standard grabber for bottom sheets and mobile drawers
+When to use shared utilities:
+- if the pattern is decorative and appears in multiple components
+- if the pattern depends on pseudo-elements or animation
+- if the pattern should inherit theme tokens and dark mode automatically
+Keep it component-local when:
+- the layout is unique to one component
+- the spacing/alignment logic is too specific to generalize cleanly
+### Healthy System Language
+Aim for components to describe themselves with clear semantic composition:
+- **"This is a raised card shell"** → use `.ak-card-shell`
+- **"This card/panel lifts on interaction"** → add `.ak-card-shell-interactive`
+- **"This panel has a sheen"** → add `.ak-sheen` only when the surface should feel elevated or premium
+- **"This is a standard skeleton block"** → use `.ak-skeleton`
+- **"This bottom sheet should feel draggable"** → add `.ak-mobile-sheet-handle`
+This keeps visual polish reusable without making every component look overdesigned.
+### Healthy Adoption Rules
+Use `.ak-card-shell` when:
+- the component is a bounded surface with border, radius, and elevation
+- multiple components need a consistent card/panel baseline
+- you want theming and dark mode to flow through shared tokens
+Use `.ak-sheen` when:
+- the surface is intentionally elevated, featured, or premium
+- the highlight improves depth without carrying meaning
+- the effect is subtle and optional
+Avoid `.ak-sheen` when:
+- the surface is already visually busy
+- the component is dense, data-heavy, or utilitarian enough that the effect becomes decorative noise
+- you would apply it to nearly every surface on the screen
+Use `.ak-skeleton` when:
+- the loading placeholder is generic and reusable
+- the component needs consistent loading behavior across the kit
+- the actual loading state is also exposed accessibly with status text or a live region
+Use `.ak-mobile-sheet-handle` when:
+- the surface is a mobile bottom sheet, drawer, or slide-up panel
+- the UI should communicate drag-to-dismiss affordance clearly
+- the handle should remain visually consistent across recurring sheet patterns
+Avoid `.ak-skeleton` when:
+- the component needs a very custom loading illustration or structure
+- the shimmer would interfere with readability or performance in dense contexts
+### Preferred Composition Order
+When a component needs these patterns, compose them from broadest surface to narrowest enhancement:
+1. Start with `.ak-card-shell` for the base container
+2. Add `.ak-card-shell-interactive` only if hover/focus lift is meaningful
+3. Add `.ak-sheen` only if the surface should feel highlighted
+4. Use `.ak-skeleton` only on placeholder elements, not on the final loaded surface
+This preserves restraint while keeping the primitives easy to reach for.
+---
+## Premium Effects
+Decorative CSS effects for hero sections, landing pages, and feature showcases. All are CSS-only utility classes.
+### Mesh Gradient Backgrounds
+```html
+<!-- Dark hero with purple/blue/teal mesh -->
+<section class="ak-mesh-dark">
+<!-- Light page with subtle pastel wash -->
+<section class="ak-mesh-light">
+<!-- AstralKit branded (violet on deep purple) -->
+<section class="ak-mesh-astral">
+```
+Override colors via `--ak-mesh-color-1` through `--ak-mesh-color-4` and `--ak-mesh-base`.
+### Grain/Noise Overlay
+Add film grain texture on top of gradients or solid backgrounds:
+```html
+<section class="ak-mesh-dark ak-noise">  <!-- dark grain: overlay blend, 5% opacity -->
+<section class="ak-mesh-light ak-noise-light">  <!-- light grain: multiply blend, 10% opacity -->
+```
+### Card Glow on Hover
+```html
+<div class="ak-card-shell ak-card-glow">  <!-- accent-tinted glow -->
+<div class="ak-card-shell ak-card-glow-neutral">  <!-- neutral glow, any theme -->
+```
+### Text Glow (dark backgrounds only)
+```html
+<h1 class="ak-text-glow">Heading</h1>  <!-- soft glow -->
+<span class="ak-text-glow-intense">Accent word</span>  <!-- neon, use sparingly -->
+```
+### Section Effects
+```html
+<section class="ak-spotlight-section">  <!-- radial glow behind section -->
+<div class="ak-section-fade">  <!-- gradient from bg to surface-2 -->
+<div class="ak-section-fade-reverse">  <!-- gradient from surface-2 to bg -->
+```
+### Gradient Borders
+```html
+<div class="ak-gradient-border">  <!-- static conic-gradient border -->
+<div class="ak-animated-border">  <!-- rotating conic border (needs @property) -->
+```
+### Frosted Nav Bar
+```html
+<nav class="ak-nav-frosted">  <!-- Apple-style backdrop-blur nav, auto dark mode -->
+```
+### Button Neon Glow
+```html
+<button class="ak-btn-neon">  <!-- hover: glow + lift, active: settle -->
+```
+### Ambient Glow Behind Images
+```html
+<div class="ak-ambient-glow"><img src="..." /></div>
+```
+### Spotlight Card (requires JS)
+```html
+<div class="ak-spotlight-card">  <!-- cursor-following radial glow -->
+```
+Needs JS to set `--ak-spotlight-x` / `--ak-spotlight-y` on mousemove.
+### Composing Effects
+Layer multiple effects on a single section:
+```html
+<section class="ak-mesh-dark ak-noise">
+  <div class="ak-card-shell ak-surface-glass ak-gradient-border ak-card-glow">
+    <h2 class="ak-text-glow">Feature</h2>
+  </div>
+</section>
+```
+### Performance Rules
+- Mesh gradients + noise: safe everywhere
+- `backdrop-filter` (glass/frosted): limit to 1-2 per viewport
+- `filter: blur()` (ambient glow): safe for 3-4 elements
+- Animated border (`@property`): limit to 4-6 on screen
+- `background-position` animation: one hero section only
+---
+## Density Modes
+AstralKit supports three density levels. Wrap any container with the `data-ak-density` attribute to adjust spacing and control sizes inside it:
+```html
+<!-- Compact: tighter spacing for data-heavy views -->
+<div data-ak-density="compact">
+  <table>...</table>
+</div>
+<!-- Spacious: more breathing room for marketing/consumer -->
+<section data-ak-density="spacious">
+  <div class="ak-grid">...</div>
+</section>
+```
+- **compact** — 25% tighter padding, 32px controls, 40px table rows. Best for admin tables, data grids, power-user dashboards.
+- **comfortable** (default) — the base tokens. 40px controls, 48px table rows.
+- **spacious** — 25% more padding, 48px controls, 56px table rows. Best for marketing pages, consumer-facing UI.
+Density modes cascade — children inherit the overridden tokens automatically.
+---
+## When Breakpoints ARE Acceptable
 The only valid use of breakpoint prefixes is for **layout switches** that cannot be expressed fluidly:
@@ -281,10 +470,10 @@ These are binary layout decisions, not gradual scaling — fluid tokens can't re
 `ease-ak-default` · `ease-ak-in` · `ease-ak-out` · `ease-ak-spring` · `ease-ak-bounce`
 ### Line Height:
-`leading-ak-display` · `leading-ak-tighter` · `leading-ak-none` · `leading-ak-tight` · `leading-ak-snug` · `leading-ak-normal` · `leading-ak-relaxed` · `leading-ak-loose`
+`leading-ak-display` · `leading-ak-tighter` · `leading-ak-none` · `leading-ak-tight` · `leading-ak-snug` · `leading-ak-normal` · `leading-ak-relaxed` · `leading-ak-prose` · `leading-ak-loose`
 ### Letter Spacing:
-`tracking-ak-tighter` · `tracking-ak-tight` · `tracking-ak-normal` · `tracking-ak-wide` · `tracking-ak-wider` · `tracking-ak-widest`
+`tracking-ak-tighter` · `tracking-ak-tight` · `tracking-ak-subtle` · `tracking-ak-normal` · `tracking-ak-wide` · `tracking-ak-wider` · `tracking-ak-widest`
 ### Font Families:
 `font-ak-sans` · `font-ak-serif` · `font-ak-mono`
@@ -295,7 +484,52 @@ These are binary layout decisions, not gradual scaling — fluid tokens can't re
 For quick composite headings: `.ak-h1` through `.ak-h6` — sets font-size, line-height, letter-spacing, weight, and color in one class.
-Body presets: `.ak-body` · `.ak-body-secondary` · `.ak-small` · `.ak-caption` · `.ak-label`
+Body presets: `.ak-body` · `.ak-body-secondary` · `.ak-small` · `.ak-caption`
+Label presets (uppercase, wide tracking): `.ak-label` (default xs) · `.ak-label-xs` (10px) · `.ak-label-sm` (12px) · `.ak-label-md` (14px) · `.ak-label-lg` (16px) · `.ak-label-xl` (18px) · `.ak-label-2xl` (20px)
+Display presets (hero marketing text, fluid): `.ak-display-sm` · `.ak-display-md` · `.ak-display-lg`
+Dashboard presets: `.ak-kpi` (large hero number, 48px fluid, bold, tabular-nums) · `.ak-kpi-sm` (smaller stat, 30px fluid)
+---
+## Pixel-Perfect Rules
+### Nested Radius
+When nesting rounded elements, inner radius = outer radius - padding gap.
+```
+Container: rounded-ak-xl (16px), padding p-ak-2 (16px)
+→ Inner card: rounded-ak-md (8px)   /* 16 - 8 ≈ 8 */
+Container: rounded-ak-lg (12px), padding p-ak-1 (8px)
+→ Inner element: rounded-ak-sm (4px)  /* 12 - 8 = 4 */
+```
+If outer radius is unknown, use one step smaller from the radius scale.
+### Icon-Text Pairing
+Match icon size to adjacent text for vertical alignment:
+| Text size | Icon size | Classes |
+|---|---|---|
+| `text-ak-xs` / `text-ak-sm` | `size-ak-icon-sm` (16px) | Small UI, badges |
+| `text-ak-base` | `size-ak-icon-md` (20px) | Default body, nav |
+| `text-ak-lg` | `size-ak-icon-lg` (24px) | Section headers |
+| `text-ak-xl`+ | `size-ak-icon-xl` (28px) | Page titles |
+### Active State
+Use `.ak-press` on buttons and interactive cards for tactile feedback:
+```html
+<button class="... ak-press">Click me</button>
+```
+Applies `transform: scale(0.98)` on `:active`.
+### Font Weight Discipline
+Use **2-3 font weights maximum** in any single view:
+- **400 (Regular)** — body text, descriptions
+- **500 (Medium)** — nav items, card titles, labels
+- **600-700 (SemiBold/Bold)** — headings, CTAs, KPIs
+Avoid using both 600 AND 700 in the same component — the difference is too subtle and creates visual noise.
 ---
@@ -311,6 +545,33 @@ Use `ak-focus-ring-inset` for elements inside panels where outward rings would c
 ---
+## Chart Colors
+Six colorblind-safe chart colors (Tableau 10 derived). Use for data visualization series:
+`bg-ak-chart-1` · `bg-ak-chart-2` · `bg-ak-chart-3` · `bg-ak-chart-4` · `bg-ak-chart-5` · `bg-ak-chart-6`
+Also available as `text-ak-chart-*` (for SVG `stroke`/`fill` via `currentColor`) and `border-ak-chart-*`.
+For single-series charts, use the primary color at decreasing opacity instead:
+```css
+--chart-1: var(--color-ak-primary);         /* 100% */
+--chart-2: color-mix(in srgb, var(--color-ak-primary) 70%, transparent);
+--chart-3: color-mix(in srgb, var(--color-ak-primary) 45%, transparent);
+```
+---
+## Numeric Typography
+Use `ak-tabular-nums` on any element displaying numbers in columns (stat cards, tables, dashboards). This aligns digits vertically for easy scanning:
+```html
+<span class="ak-tabular-nums text-ak-fl-2xl font-bold">$12,847.00</span>
+```
+---
 ## Quick Reference: Common Patterns
 ```html
@@ -337,3 +598,123 @@ Use `ak-focus-ring-inset` for elements inside panels where outward rings would c
 <nav class="fixed top-0 w-full bg-ak-bg/85 backdrop-blur-md z-(--z-ak-sticky) border-b border-ak-border">
   <div class="max-w-ak-page mx-auto px-ak-3 h-ak-nav flex items-center">
 ```
+---
+## Dashboard Component Patterns
+### Stat Card
+```html
+<div class="border border-ak-border rounded-ak-lg p-ak-3 bg-ak-surface">
+  <p class="text-ak-sm text-ak-text-muted font-medium">Revenue</p>
+  <p class="text-ak-fl-2xl font-bold text-ak-text ak-tabular-nums mt-ak-0_5">$48,290</p>
+  <div class="flex items-center gap-ak-0_5 mt-ak-1">
+    <span class="text-ak-xs font-medium text-ak-success">+12.5%</span>
+    <span class="text-ak-xs text-ak-text-muted">vs last month</span>
+  </div>
+</div>
+```
+### Data Table
+```html
+<table class="w-full text-ak-sm">
+  <thead>
+    <tr class="border-b border-ak-border">
+      <th class="text-left py-ak-1_5 px-ak-2 text-ak-text-muted font-semibold text-ak-xs uppercase tracking-ak-wider">Name</th>
+    </tr>
+  </thead>
+  <tbody>
+    <tr class="border-b border-ak-border-subtle hover:bg-ak-hover transition-colors">
+      <td class="py-ak-1_5 px-ak-2 text-ak-text ak-tabular-nums">$1,240.00</td>
+    </tr>
+  </tbody>
+</table>
+```
+### Form Input
+```html
+<label class="ak-form-label mb-ak-0_5 block">Email</label>
+<input type="email"
+  class="w-full h-ak-control-md px-ak-2 rounded-ak-md border border-ak-border bg-ak-bg text-ak-text text-ak-base placeholder:text-ak-text-placeholder ak-focus-ring" />
+<p class="ak-helper mt-ak-0_5">We'll never share your email.</p>
+```
+### Badge
+```html
+<span class="inline-flex items-center px-ak-1_5 py-ak-px rounded-ak-full text-ak-xs font-medium bg-ak-success-subtle text-ak-success-text">Active</span>
+```
+---
+## Curated Theme Palettes
+AstralKit ships with a neutral black-and-white default. To re-theme, use preset palettes or override variables.
+### Method 1: Preset Palettes (easiest)
+Import the palettes file and add a `data-ak-theme` attribute:
+```css
+/* In globals.css */
+@import "astralkit/palettes";
+```
+```html
+<!-- On <html> or any container -->
+<html data-ak-theme="ocean-blue">
+```
+Available: `ocean-blue` · `forest-gold` · `minimal-violet` · `warm-earth` · `tangerine` · `slate-pro` · `emerald-saas` · `astral-violet` · `midnight` · `ember-dark` · `obsidian` · `deep-teal`
+### Method 2: Custom Override
+Override these variables in your `globals.css` `@theme` block (v4) or `:root` (v3):
+```css
+--color-ak-bg, --color-ak-surface, --color-ak-text, --color-ak-text-secondary,
+--color-ak-primary, --color-ak-primary-hover, --color-ak-primary-active,
+--color-ak-on-primary, --color-ak-border, --color-ak-border-subtle, --color-ak-border-strong
+```
+### Light Palettes
+**AstralKit Default (Violet)**
+`bg: #FAF9F7 · surface: #FFFFFF · text: #150A35 · primary: #6933FF · border: #E6E3EE`
+**Ocean Blue** — Clean blue with coral accents
+`bg: #FFFFFE · surface: #D8EEFE · text: #094067 · primary: #3DA9FC · accent: #EF4565`
+**Forest & Gold** — Deep green with warm golden accents
+`bg: #F2F7F5 · surface: #FFFFFF · text: #00473E · primary: #FAAE2B · accent: #FA5246`
+**Minimal Violet** — Pure white with bold purple
+`bg: #FFFFFE · surface: #D1D1E9 · text: #2B2C34 · primary: #6246EA · accent: #E45858`
+**Warm Earth** — Teal primary with coral-red highlights
+`bg: #F8F5F2 · surface: #FFFFFF · text: #232323 · primary: #078080 · accent: #F45D48`
+**Tangerine** — Light gray with bold orange
+`bg: #EFF0F3 · surface: #FFFFFE · text: #0D0D0D · primary: #FF8E3C · accent: #D9376E`
+**Golden Sand** — Warm parchment with earthy tones
+`bg: #F9F4EF · surface: #FFFFFE · text: #020826 · primary: #8C7851 · accent: #F25042`
+**Lemon Breeze** — Clean white with yellow and teal
+`bg: #FFFFFE · surface: #E3F6F5 · text: #272343 · primary: #FFD803 · accent: #272343`
+**Slate Pro** — Professional gray with blue accent
+`bg: #F8FAFC · surface: #FFFFFF · text: #0F172A · primary: #2563EB · accent: #7C3AED`
+**Emerald SaaS** — Clean white with emerald green
+`bg: #F9FAFB · surface: #FFFFFF · text: #111827 · primary: #059669 · accent: #F59E0B`
+**Indigo Craft** — Warm neutral with indigo
+`bg: #FAFAF9 · surface: #FFFFFF · text: #1C1917 · primary: #4F46E5 · accent: #EC4899`
+### Dark Palettes
+**Midnight** — Deep dark with purple glow
+`bg: #16161A · surface: #242629 · text: #FFFFFE · primary: #7F5AF0 · accent: #2CB67D`
+**Ember Dark** — Dark with orange and pink
+`bg: #0F0E17 · surface: #1A1925 · text: #FFFFFE · primary: #FF8906 · accent: #E53170`
+**Deep Teal** — Dark ocean teal with golden accent
+`bg: #004643 · surface: #001E1D · text: #FFFFFE · primary: #F9BC60 · accent: #E16162`
+**Obsidian** — Pure dark SaaS standard
+`bg: #09090B · surface: #18181B · text: #FAFAFA · primary: #3B82F6 · accent: #8B5CF6`