astralkit 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -0,0 +1,37 @@
+# Changelog
+
+All notable changes to the `astralkit` SDK package.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.3.1] — 2026-04-18
+
+### Added
+- `peerDependencies` declaration: `tailwindcss >= 3.0.0`. Installing `astralkit` in a project without Tailwind now surfaces a clear peer-dep warning instead of silent breakage.
+- File header comment on `astralkit-theme.css` explicitly marks it as the Tailwind v3 legacy file. Points readers at the `astralkit/theme-v3` export path and explains the v4 alternative.
+
+### Fixed
+- No functional changes from `0.3.0` — this is a metadata + documentation patch.
+
+## [0.3.0] — 2026-04-18
+
+### Changed (breaking behavior fix)
+- **`astralkit/theme` export now resolves to the Tailwind v4 file (`astralkit-theme-v4.css`).** Previously it pointed at `astralkit-theme.css` (the v3 `:root {}` file), which meant Tailwind v4 users were loading tokens that weren't registered with Tailwind's `@theme` system. Utilities like `bg-ak-primary` and `text-ak-text` were only working because the separate `astralkit-utilities.css` contains its own `@theme` blocks; the theme import was effectively dead weight.
+  - If you were relying on `@import "astralkit/theme"` resolving to the v3 `:root` syntax (e.g., in a Tailwind v3 project), import `astralkit/theme-v3` explicitly instead.
+  - If you're on Tailwind v4, no action needed — the new default is what you should have been getting all along.
+
+### Added
+- New `astralkit/theme-v3` export — explicit path to the Tailwind v3 legacy file (`astralkit-theme.css`).
+- `astralkit/theme-v4` export retained (unchanged) — still points at the v4 file. Existing imports keep working.
+- v4 theme refinements across 12 commits of token architecture work (including rail/panel elevated color overrides, sidebar token tuning, avatar size/badge tokens, and Phase A token standardization).
+- `primitives/.npmignore` — excludes `*.backup` and `*.pre-v4-split` scratch files from published tarballs. The `0.3.0` release removed ~220 kB of v3-migration scratch that was accidentally shipping in earlier versions.
+
+### Fixed
+- Tailwind v3 plugin registration (via CLI init) now covers additional `plugins: [...]` formatting variants.
+
+## [0.2.0] — 2026-04-02
+
+### Added
+- Initial public release on npm.
+- Design tokens (theme CSS), utilities CSS, palette presets, primitives folder, `cn()` helper, Tailwind v3/v4 configs.

package/ai-rules.md

@@ -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`