astralkit 0.3.2 → 0.3.4

package/CHANGELOG.md

@@ -5,6 +5,11 @@ 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.3] — 2026-04-22
+
+### Changed
+- Widened `tailwind-merge` dependency range from `^2.2.0` to `^2.2.0 || ^3.0.0`. Tailwind CSS v4 projects use `tailwind-merge@v3` (which adds v4 class-name recognition), so accepting either major version lets npm dedupe to the host project's copy instead of nesting a second `node_modules/astralkit/node_modules/tailwind-merge`. Same `twMerge` API in both; no SDK code change required.
+
 ## [0.3.2] — 2026-04-19
 
 ### Fixed (revert of accidental change in 0.3.0 / 0.3.1)

package/ai-rules.md

@@ -17,6 +17,8 @@ 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 `text-white` or `text-black`.** Use `text-ak-on-primary` for text on primary-colored backgrounds, `text-ak-text-inverse` for text on dark/ink surfaces, and `text-ak-text` for standard text. Raw black/white breaks when palettes change — a theme with a dark primary and white on-primary text would get white-on-white if you hardcode `text-white`.
+
 **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.
@@ -74,6 +76,36 @@ Prefer:      class="text-ak-fl-5xl"
 
 Static tokens: `text-ak-2xs` · `text-ak-xs` · `text-ak-sm` · `text-ak-base` · `text-ak-lg` · `text-ak-xl` · `text-ak-2xl`
 
+### Watermark / Giant Decorative Type — `text-ak-watermark-*`
+
+For container-spanning decorative text (brand watermarks behind content). These use `cqi` (container query inline) units with `clamp()` to scale relative to their container width.
+
+```
+Instead of:  class="text-[25vw] leading-[0.85] font-black tracking-ak-tighter uppercase whitespace-nowrap select-none pointer-events-none"
+Prefer:
+  <div class="ak-watermark-area" aria-hidden="true">
+    <span class="ak-watermark text-ak-watermark-lg">Brand</span>
+  </div>
+```
+
+The `.ak-watermark-area` primitive sets: container-type inline-size, select-none, pointer-events-none.
+The `.ak-watermark` primitive sets: font-weight 900, tracking-tighter, leading-display, uppercase, nowrap.
+
+Pick size by character count:
+| Token | Scale | Best for |
+|---|---|---|
+| `text-ak-watermark-2xs` | 13cqi | 9+ chars (Structura, Celebrate Life) |
+| `text-ak-watermark-xs` | 16cqi | 7-8 chars (Framecut, Routeflow) |
+| `text-ak-watermark-sm` | 19cqi | 5-7 chars (Caliper, Olympus, Terra) |
+| `text-ak-watermark-base` | 21cqi | 5-6 chars (intermediate) |
+| `text-ak-watermark-md` | 24cqi | 4-6 chars (Roast, Maison) |
+| `text-ak-watermark-lg` | 26cqi | 4-5 chars (Relay, Swift, Vinyl) |
+| `text-ak-watermark-xl` | 28cqi | 4-5 chars (Nimble) |
+| `text-ak-watermark-2xl` | 30cqi | 3-5 chars (Void, Orbit, Nexus) |
+| `text-ak-watermark-3xl` | 33cqi | 3-4 chars (Cove) |
+| `text-ak-watermark-4xl` | 36cqi | 2-3 chars (very large) |
+| `text-ak-watermark-5xl` | 40cqi | 2-3 chars (massive) |
+
 ---
 
 ## Fluid Spacing — Use `*-ak-fl-*` for Section-Level Spacing
@@ -97,7 +129,7 @@ Space pairs are ideal for section padding (e.g., `py-ak-fl-xl-3xl`), hero spacin
 - Small internal component spacing (button padding, icon gaps, card chrome)
 - Spacing that should remain constant regardless of viewport
 
-Static spacing: `*-ak-0` · `*-ak-px` · `*-ak-0_5` · `*-ak-1` · `*-ak-1_5` · `*-ak-2` · `*-ak-2_5` · `*-ak-3` · `*-ak-3_5` · `*-ak-4` · `*-ak-4_5` · `*-ak-5` · `*-ak-5_5` · `*-ak-6` · `*-ak-7` · `*-ak-8` · `*-ak-10` · `*-ak-12` · `*-ak-16` · `*-ak-20` · `*-ak-24`
+Static spacing: `*-ak-0` · `*-ak-px` · `*-ak-0_5` · `*-ak-0_75` · `*-ak-1` · `*-ak-1_25` · `*-ak-1_5` · `*-ak-2` · `*-ak-2_5` · `*-ak-3` · `*-ak-3_5` · `*-ak-4` · `*-ak-4_5` · `*-ak-5` · `*-ak-5_5` · `*-ak-6` · `*-ak-7` · `*-ak-8` · `*-ak-10` · `*-ak-12` · `*-ak-16` · `*-ak-20` · `*-ak-24`
 
 ---
 
@@ -185,12 +217,31 @@ Prefer:      class="bg-ak-bg text-ak-text border-ak-border"
 ### Decorative highlights / loading:
 `ak-highlight-soft` · `ak-highlight-strong` · `ak-skeleton-base` · `ak-skeleton-shine`
 
+### Primary color family:
+`bg-ak-primary` · `bg-ak-primary-hover` · `bg-ak-primary-active` — action backgrounds (button, link hover, active press)
+`text-ak-on-primary` — text ON a primary-colored background (white in light mode, dark in dark mode)
+`bg-ak-primary-subtle` · `bg-ak-primary-subtle-hover` — soft/pastel primary tint for gentle emphasis (badges, pastel buttons, tag backgrounds)
+`ak-primary-50` through `ak-primary-950` — full primary color ramp for fine-grained shading
+
 ### Text:
-`text-ak-text` · `text-ak-text-secondary` · `text-ak-text-muted` · `text-ak-text-disabled` · `text-ak-text-inverse`
+`text-ak-text` · `text-ak-text-emphasis` · `text-ak-text-secondary` · `text-ak-text-muted` · `text-ak-text-disabled` · `text-ak-text-inverse` · `text-ak-text-link` · `text-ak-text-placeholder`
+
+**Text scale usage:**
+- `ak-text` — primary body text, headings
+- `ak-text-emphasis` — high-emphasis secondary text, slightly softened ink (between text and text-secondary)
+- `ak-text-secondary` — descriptions, supporting copy
+- `ak-text-muted` — timestamps, captions, tertiary info
+- `ak-text-disabled` — disabled controls
+- `ak-text-inverse` — text on dark/ink backgrounds (NOT on primary — use `ak-on-primary` for that)
+- `ak-text-link` — inline hyperlinks
+- `ak-text-placeholder` — input placeholders
 
 ### Border:
 `border-ak-border` · `border-ak-border-subtle` · `border-ak-border-strong` · `border-ak-border-focus`
 
+### Overlay:
+`bg-ak-overlay` — semi-transparent backdrop for modals and drawers
+
 ### Neutral scale (for decorative/data elements only):
 `ak-neutral-0` through `ak-neutral-950` (11 shades)
 
@@ -223,6 +274,11 @@ 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)
+### Control heights (buttons, inputs, selects):
+`min-h-ak-control-sm` (32px) · `min-h-ak-control-md` (40px) · `min-h-ak-control-lg` (48px) · `min-h-ak-control-xl` (56px) · `min-h-ak-control-2xl` (64px)
+
+Also available as `h-ak-control-*` for exact height. Use `min-h-` for buttons (allows text wrap), `h-` for inputs (fixed height).
+
 ### 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)
 
@@ -545,6 +601,56 @@ Use `ak-focus-ring-inset` for elements inside panels where outward rings would c
 
 ---
 
+## Button & Control Variant Patterns
+
+Buttons are composed from three layers: **base** (structure) + **size** (dimensions) + **variant** (colors). Never freestyle button classes — compose from these layers.
+
+### Base (always present):
+```
+inline-flex items-center justify-center font-semibold rounded-ak-lg cursor-pointer transition-colors duration-ak-base
+```
+
+### Size scale:
+| Size | Padding | Text | Min Height | Gap |
+|---|---|---|---|---|
+| xs | `py-ak-0_75 px-ak-1_5` | `text-ak-xs` | `min-h-ak-control-sm` | `gap-ak-0_75` |
+| sm | `py-ak-1 px-ak-2` | `text-ak-sm` | `min-h-ak-control-md` | `gap-ak-0_75` |
+| md | `py-ak-1_25 px-ak-2_5` | `text-ak-base` | `min-h-ak-control-lg` | `gap-ak-1` |
+| lg | `py-ak-1_5 px-ak-3` | `text-ak-lg` | `min-h-ak-control-xl` | `gap-ak-1` |
+| xl | `py-ak-2 px-ak-4` | `text-ak-xl` | `min-h-ak-control-2xl` | `gap-ak-1_5` |
+
+### Variant colors (pick ONE per button):
+```
+Primary:     bg-ak-primary text-ak-on-primary hover:bg-ak-primary-hover
+Secondary:   bg-ak-surface-2 text-ak-text hover:bg-ak-border
+Ghost:       bg-ak-surface text-ak-text border border-ak-border hover:bg-ak-surface-2
+Soft:        bg-ak-primary-subtle text-ak-text hover:bg-ak-primary-subtle-hover
+Link:        bg-transparent text-ak-primary hover:bg-ak-primary-subtle hover:underline
+Destructive: bg-ak-danger text-ak-text-inverse hover:bg-ak-danger/90
+```
+
+### Hover state patterns:
+- **Color shift** (secondary, ghost, soft): Change background one step darker via semantic tokens
+- **Invert** (primary, ink): Swap fill/text and add an inset ring — `hover:bg-ak-surface hover:text-ak-primary hover:shadow-[inset_0_0_0_1.5px_var(--color-ak-primary)]`
+- **Never use opacity as hover** — it's not accessible. Use a visible color change.
+
+### Disabled state:
+Add `opacity-50 cursor-not-allowed` and the `disabled` attribute. Never change colors for disabled — the opacity communicates the state.
+
+### Icon-only buttons:
+Use explicit `w-ak-*` and `h-ak-*` instead of padding. Example: `w-ak-5 h-ak-5 p-0` for a sm icon button. Always add `aria-label`.
+
+### Complete example:
+```html
+<!-- Primary md button with leading icon -->
+<button class="inline-flex items-center justify-center font-semibold rounded-ak-lg cursor-pointer transition-colors duration-ak-base py-ak-1_25 px-ak-2_5 text-ak-base min-h-ak-control-lg gap-ak-1 bg-ak-primary text-ak-on-primary hover:bg-ak-primary-hover ak-focus-ring">
+  <i class="ph ph-plus shrink-0" aria-hidden="true" />
+  Add item
+</button>
+```
+
+---
+
 ## Chart Colors
 
 Six colorblind-safe chart colors (Tableau 10 derived). Use for data visualization series:
@@ -585,8 +691,8 @@ Use `ak-tabular-nums` on any element displaying numbers in columns (stat cards,
 <div class="ak-grid" style="--ak-grid-min: 280px">
   <div class="p-ak-fl-md rounded-ak-md bg-ak-surface border border-ak-border-subtle">
 
-<!-- Button -->
-<button class="bg-ak-neutral-900 text-white px-ak-3 py-ak-1 rounded-ak-full text-ak-base font-semibold hover:bg-ak-neutral-800 transition-colors ak-focus-ring">
+<!-- Button (primary) -->
+<button class="inline-flex items-center justify-center bg-ak-primary text-ak-on-primary px-ak-2_5 py-ak-1_25 min-h-ak-control-lg rounded-ak-lg text-ak-base font-semibold hover:bg-ak-primary-hover transition-colors duration-ak-base ak-focus-ring">
 
 <!-- Icon -->
 <svg class="size-ak-icon-lg">
@@ -662,14 +768,62 @@ Import the palettes file and add a `data-ak-theme` attribute:
 ```
 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):
+### Method 2: Custom Theme Palette
+Create a `[data-ak-theme="your-brand"]` block and override the semantic tokens. Apply it to any container — `<html>`, a `<div>`, or a layout wrapper. Palettes cascade to all children.
+
 ```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
+[data-ak-theme="your-brand"] {
+  /* ── Required: core surfaces ── */
+  --color-ak-bg:              #your-page-bg;
+  --color-ak-surface:         #your-card-bg;
+  --color-ak-surface-2:       #your-secondary-surface;
+  --color-ak-hover:           #your-hover-surface;
+
+  /* ── Required: text scale ── */
+  --color-ak-text:            #your-ink;
+  --color-ak-text-emphasis:   #your-high-emphasis;   /* between text and text-secondary */
+  --color-ak-text-secondary:  #your-secondary-text;
+  --color-ak-text-muted:      #your-muted-text;
+  --color-ak-text-inverse:    #your-inverse-text;    /* text on dark/ink backgrounds */
+
+  /* ── Required: primary action color ── */
+  --color-ak-primary:         #your-brand-color;
+  --color-ak-primary-hover:   #your-brand-darker;
+  --color-ak-primary-active:  #your-brand-darkest;
+  --color-ak-on-primary:      #ffffff;               /* text ON primary bg */
+  --color-ak-primary-subtle:  #your-brand-pastel;    /* soft tint for badges, soft buttons */
+  --color-ak-primary-subtle-hover: #your-brand-pastel-darker;
+
+  /* ── Required: borders ── */
+  --color-ak-border:          #your-border;
+  --color-ak-border-subtle:   #your-light-border;
+  --color-ak-border-strong:   #your-strong-border;
+
+  /* ── Recommended: full primary ramp (enables fine-grained shading) ── */
+  --color-ak-primary-50:  #lightest;
+  --color-ak-primary-100: ...;
+  --color-ak-primary-200: ...;
+  /* ... through --color-ak-primary-950 */
+
+  /* ── Optional: status colors (defaults work for most brands) ── */
+  --color-ak-success: ...;  --color-ak-warning: ...;  --color-ak-danger: ...;  --color-ak-info: ...;
+}
 ```
 
+```html
+<div data-ak-theme="your-brand">
+  <!-- All ak-* classes inside here use your palette -->
+</div>
+```
+
+**Key rules for palette authors:**
+1. Every button, card, and text element uses `ak-*` semantic tokens — if you set the palette correctly, the entire UI re-themes automatically
+2. `--color-ak-on-primary` MUST contrast with `--color-ak-primary` — this is the text color on primary buttons
+3. `--color-ak-text-inverse` MUST contrast with `--color-ak-text` — this is for text on ink/dark surfaces
+4. `--color-ak-primary-subtle` should be a very light tint of your primary (10-15% opacity equivalent)
+5. Populate the full primary ramp (50-950) if you need fine-grained variants beyond the semantic tokens
+6. Brand-specific extras that don't map to any ak-* semantic (custom pastel chips, brand shadows, display fonts) go in a separate scoped CSS file — not in the palette block
+
 ### Light Palettes
 
 **AstralKit Default (Violet)**

package/astralkit-theme-v4.css

@@ -61,9 +61,11 @@
   --color-ak-overlay:         rgba(0, 0, 0, 0.5);
   --color-ak-on-primary:      #ffffff;
   --color-ak-primary-subtle:  #f5f5f5;
+  --color-ak-primary-subtle-hover: #e5e5e5;
 
   /* ── Semantic text ── */
   --color-ak-text:            #171717;
+  --color-ak-text-emphasis:   #2b2b2b;
   --color-ak-text-secondary:  #525252;
   --color-ak-text-muted:      #a3a3a3;
   --color-ak-text-disabled:   #d4d4d4;
@@ -101,18 +103,26 @@
   /* ── Type scale (static) ── */
   --text-ak-2xs:    0.6875rem;
   --text-ak-xs:     0.75rem;
+  --text-ak-xs_5:   0.8125rem;
   --text-ak-sm:     0.875rem;
+  --text-ak-sm_5:   0.9375rem;
   --text-ak-base:   1rem;
   --text-ak-lg:     1.125rem;
   --text-ak-xl:     1.25rem;
+  --text-ak-xl_5:   1.375rem;
   --text-ak-2xl:    1.5rem;
+  --text-ak-2xl_5:  1.625rem;
   --text-ak-3xl:    2rem;
   --text-ak-4xl:    2.5rem;
+  --text-ak-4xl_5:  2.75rem;
   --text-ak-5xl:    3rem;
   --text-ak-6xl:    3.75rem;
+  --text-ak-6xl_5:  4rem;
   --text-ak-7xl:    4.5rem;
+  --text-ak-7xl_5:  5.25rem;
   --text-ak-8xl:    6rem;
   --text-ak-9xl:    7rem;
+  --text-ak-10xl:   8rem;
 
   /* ── Fluid type scale (viewport: 320px → 1400px) ──
      One class, zero breakpoints. Use text-ak-fl-* instead of text-ak-*.
@@ -152,15 +162,20 @@
   --text-ak-display-9xl:  clamp(5.5rem,    3.06rem + 7.64vw, 10rem);
 
   /* ── Line Height ── */
-  --leading-ak-display: 0.85;
-  --leading-ak-tighter: 1.1;
-  --leading-ak-none:    1;
-  --leading-ak-tight:   1.25;
-  --leading-ak-snug:    1.375;
-  --leading-ak-normal:  1.5;
-  --leading-ak-relaxed: 1.625;
-  --leading-ak-prose:   1.75;
-  --leading-ak-loose:   2;
+  --leading-ak-display:    0.85;
+  --leading-ak-squeezed:   0.92;
+  --leading-ak-condensed:  0.95;
+  --leading-ak-none:       1;
+  --leading-ak-fitted:   1.02;
+  --leading-ak-compact:  1.05;
+  --leading-ak-tighter:  1.1;
+  --leading-ak-snugger:  1.2;
+  --leading-ak-tight:    1.25;
+  --leading-ak-snug:     1.375;
+  --leading-ak-normal:   1.5;
+  --leading-ak-relaxed:  1.625;
+  --leading-ak-prose:    1.75;
+  --leading-ak-loose:    2;
 
   /* ── Letter Spacing ── */
   --tracking-ak-tighter: -0.05em;
@@ -176,7 +191,9 @@
   --spacing-ak-0:    0rem;
   --spacing-ak-px:   0.0625rem;
   --spacing-ak-0_5:  0.25rem;
+  --spacing-ak-0_75: 0.375rem;
   --spacing-ak-1:    0.5rem;
+  --spacing-ak-1_25: 0.625rem;
   --spacing-ak-1_5:  0.75rem;
   --spacing-ak-2:    1rem;
   --spacing-ak-2_5:  1.25rem;
@@ -219,6 +236,7 @@
   --height-ak-control-md:   2.5rem;    /* 40px — STANDARD */
   --height-ak-control-lg:   3rem;      /* 48px — prominent CTAs */
   --height-ak-control-xl:   3.5rem;    /* 56px — hero CTAs */
+  --height-ak-control-2xl:  4rem;      /* 64px — oversized CTAs */
 
   /* ── Table row heights ── */
   --height-ak-row-compact:     2.5rem;    /* 40px */
@@ -544,9 +562,11 @@
   --color-ak-overlay:         rgba(0,0,0,0.7);
   --color-ak-on-primary:      #111113;
   --color-ak-primary-subtle:  rgba(129, 140, 248, 0.15);
+  --color-ak-primary-subtle-hover: rgba(129, 140, 248, 0.24);
 
   /* ── Text ── */
   --color-ak-text:            #f4f4f5;
+  --color-ak-text-emphasis:   #d4d4d8;
   --color-ak-text-secondary:  #a1a1aa;
   --color-ak-text-muted:      #71717a;
   --color-ak-text-disabled:   #52525b;

package/astralkit-theme.css

@@ -63,9 +63,11 @@
   --color-ak-overlay:         rgba(0, 0, 0, 0.5);
   --color-ak-on-primary:      #ffffff;
   --color-ak-primary-subtle:  #f5f5f5;
+  --color-ak-primary-subtle-hover: #e5e5e5;
 
   /* ── Semantic text ── */
   --color-ak-text:            #171717;
+  --color-ak-text-emphasis:   #2b2b2b;
   --color-ak-text-secondary:  #525252;
   --color-ak-text-muted:      #a3a3a3;
   --color-ak-text-disabled:   #d4d4d4;
@@ -103,18 +105,26 @@
   /* ── Type scale (static) ── */
   --text-ak-2xs:    0.6875rem;
   --text-ak-xs:     0.75rem;
+  --text-ak-xs_5:   0.8125rem;
   --text-ak-sm:     0.875rem;
+  --text-ak-sm_5:   0.9375rem;
   --text-ak-base:   1rem;
   --text-ak-lg:     1.125rem;
   --text-ak-xl:     1.25rem;
+  --text-ak-xl_5:   1.375rem;
   --text-ak-2xl:    1.5rem;
+  --text-ak-2xl_5:  1.625rem;
   --text-ak-3xl:    2rem;
   --text-ak-4xl:    2.5rem;
+  --text-ak-4xl_5:  2.75rem;
   --text-ak-5xl:    3rem;
   --text-ak-6xl:    3.75rem;
+  --text-ak-6xl_5:  4rem;
   --text-ak-7xl:    4.5rem;
+  --text-ak-7xl_5:  5.25rem;
   --text-ak-8xl:    6rem;
   --text-ak-9xl:    7rem;
+  --text-ak-10xl:   8rem;
 
   /* ── Fluid type scale (viewport: 320px → 1400px) ──
      One class, zero breakpoints. Use text-ak-fl-* instead of text-ak-*.
@@ -153,16 +163,37 @@
   --text-ak-display-8xl:  clamp(5rem,      3.06rem + 6.94vw, 9rem);
   --text-ak-display-9xl:  clamp(5.5rem,    3.06rem + 7.64vw, 10rem);
 
+  /* ── Watermark / Giant Decorative Type ──
+     Container-scaled sizes for decorative watermarks. Uses cqi
+     (container query inline) so text fits its container, not the viewport.
+     Parent must be a container (ak-watermark primitive handles this). ── */
+  --text-ak-watermark-2xs:  clamp(1rem, 13cqi, 13rem);
+  --text-ak-watermark-xs:   clamp(1rem, 16cqi, 16rem);
+  --text-ak-watermark-sm:   clamp(1rem, 19cqi, 20rem);
+  --text-ak-watermark-base: clamp(1rem, 21cqi, 22rem);
+  --text-ak-watermark-md:   clamp(1rem, 24cqi, 26rem);
+  --text-ak-watermark-lg:   clamp(1rem, 26cqi, 28rem);
+  --text-ak-watermark-xl:   clamp(1rem, 28cqi, 30rem);
+  --text-ak-watermark-2xl:  clamp(1rem, 30cqi, 34rem);
+  --text-ak-watermark-3xl:  clamp(1rem, 33cqi, 38rem);
+  --text-ak-watermark-4xl:  clamp(1rem, 36cqi, 42rem);
+  --text-ak-watermark-5xl:  clamp(1rem, 40cqi, 48rem);
+
   /* ── Line Height ── */
-  --leading-ak-display: 0.85;
-  --leading-ak-tighter: 1.1;
-  --leading-ak-none:    1;
-  --leading-ak-tight:   1.25;
-  --leading-ak-snug:    1.375;
-  --leading-ak-normal:  1.5;
-  --leading-ak-relaxed: 1.625;
-  --leading-ak-prose:   1.75;
-  --leading-ak-loose:   2;
+  --leading-ak-display:    0.85;
+  --leading-ak-squeezed:   0.92;
+  --leading-ak-condensed:  0.95;
+  --leading-ak-none:       1;
+  --leading-ak-fitted:   1.02;
+  --leading-ak-compact:  1.05;
+  --leading-ak-tighter:  1.1;
+  --leading-ak-snugger:  1.2;
+  --leading-ak-tight:    1.25;
+  --leading-ak-snug:     1.375;
+  --leading-ak-normal:   1.5;
+  --leading-ak-relaxed:  1.625;
+  --leading-ak-prose:    1.75;
+  --leading-ak-loose:    2;
 
   /* ── Letter Spacing ── */
   --tracking-ak-tighter: -0.05em;
@@ -178,7 +209,9 @@
   --spacing-ak-0:    0rem;
   --spacing-ak-px:   0.0625rem;
   --spacing-ak-0_5:  0.25rem;
+  --spacing-ak-0_75: 0.375rem;
   --spacing-ak-1:    0.5rem;
+  --spacing-ak-1_25: 0.625rem;
   --spacing-ak-1_5:  0.75rem;
   --spacing-ak-2:    1rem;
   --spacing-ak-2_5:  1.25rem;
@@ -221,6 +254,7 @@
   --height-ak-control-md:   2.5rem;    /* 40px — STANDARD */
   --height-ak-control-lg:   3rem;      /* 48px — prominent CTAs */
   --height-ak-control-xl:   3.5rem;    /* 56px — hero CTAs */
+  --height-ak-control-2xl:  4rem;      /* 64px — oversized CTAs */
 
   /* ── Table row heights ── */
   --height-ak-row-compact:     2.5rem;    /* 40px */
@@ -544,9 +578,11 @@
   --color-ak-overlay:         rgba(0,0,0,0.7);
   --color-ak-on-primary:      #111113;
   --color-ak-primary-subtle:  rgba(129, 140, 248, 0.15);
+  --color-ak-primary-subtle-hover: rgba(129, 140, 248, 0.24);
 
   /* ── Text ── */
   --color-ak-text:            #f4f4f5;
+  --color-ak-text-emphasis:   #d4d4d8;
   --color-ak-text-secondary:  #a1a1aa;
   --color-ak-text-muted:      #71717a;
   --color-ak-text-disabled:   #52525b;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astralkit",
-  "version": "0.3.2",
+  "version": "0.3.4",
   "description": "Design tokens and component primitives for accessible UI — Tailwind CSS v3 & v4",
   "type": "module",
   "exports": {
@@ -29,7 +29,7 @@
   ],
   "dependencies": {
     "clsx": "^2.1.0",
-    "tailwind-merge": "^2.2.0"
+    "tailwind-merge": "^2.2.0 || ^3.0.0"
   },
   "peerDependencies": {
     "tailwindcss": ">=3.0.0"
@@ -39,11 +39,17 @@
       "optional": false
     }
   },
-  "keywords": ["astralkit", "design-tokens", "tailwind", "css", "ui"],
+  "keywords": [
+    "astralkit",
+    "design-tokens",
+    "tailwind",
+    "css",
+    "ui"
+  ],
   "homepage": "https://astralkit.com",
   "repository": {
     "type": "git",
-    "url": "https://github.com/astral-kit/astralkit"
+    "url": "git+https://github.com/astral-kit/astralkit.git"
   },
   "license": "SEE LICENSE IN LICENSE",
   "author": "Blue Beacon Creative LLC",

package/palettes.css

@@ -297,3 +297,32 @@
   --shadow-ak-xs: none;
   --shadow-ak-sm: none;
 }
+
+/* ─── Brand Design System Palettes ─── */
+
+[data-ak-theme="logozap"] {
+  --color-ak-bg:              #FAFAF7;
+  --color-ak-surface:         #FFFFFF;
+  --color-ak-surface-2:       #F0EFEA;
+  --color-ak-text:            #0A0A0A;
+  --color-ak-text-secondary:  #5A5A5A;
+  --color-ak-text-muted:      #8C8C8C;
+  --color-ak-text-disabled:   #C4C2BA;
+  --color-ak-text-placeholder: #8C8C8C;
+  --color-ak-primary:         #1E7BFF;
+  --color-ak-primary-hover:   #0B4FD9;
+  --color-ak-primary-active:  #0942B0;
+  --color-ak-on-primary:      #FFFFFF;
+  --color-ak-primary-subtle:  #CFE3FF;
+  --color-ak-border:          #E4E2DA;
+  --color-ak-border-subtle:   #EEEDE8;
+  --color-ak-border-strong:   #5A5A5A;
+  --color-ak-border-focus:    #1E7BFF;
+  --color-ak-text-link:       #1E7BFF;
+  --color-ak-hover:           #F0EFEA;
+  --color-ak-active:          #E4E2DA;
+  --color-ak-danger:          #EF4444;
+  --color-ak-success:         #22C55E;
+  --color-ak-warning:         #F59E0B;
+  --color-ak-info:            #3B82F6;
+}

package/primitives/typography.css

@@ -298,6 +298,26 @@
   color: var(--color-ak-text);
 }
 
+/* -- Watermark Primitive --
+   Decorative container-spanning text. Pair with text-ak-watermark-* size token.
+   Wrap in .ak-watermark-area so cqi units size relative to the container.
+   Usage:
+     <div class="ak-watermark-area" aria-hidden="true">
+       <span class="ak-watermark text-ak-watermark-lg">Brand</span>
+     </div> */
+.ak-watermark-area {
+  container-type: inline-size;
+  user-select: none;
+  pointer-events: none;
+}
+.ak-watermark {
+  font-weight: 900;
+  letter-spacing: var(--tracking-ak-tighter);
+  line-height: var(--leading-ak-display);
+  text-transform: uppercase;
+  white-space: nowrap;
+}
+
 /* Panel section headings — add letter-spacing, keep original font-size */
 [data-ak-panel] h3.text-ak-base.font-bold {
   letter-spacing: var(--tracking-ak-section);

package/tailwind.cjs

@@ -22,7 +22,11 @@ const AK_SPACING = {
   'ak-px':   'var(--spacing-ak-px)',
   'ak-0_5':  'var(--spacing-ak-0_5)',
   'ak-0.5':  'var(--spacing-ak-0_5)',
+  'ak-0_75': 'var(--spacing-ak-0_75)',
+  'ak-0.75': 'var(--spacing-ak-0_75)',
   'ak-1':    'var(--spacing-ak-1)',
+  'ak-1_25': 'var(--spacing-ak-1_25)',
+  'ak-1.25': 'var(--spacing-ak-1_25)',
   'ak-1_5':  'var(--spacing-ak-1_5)',
   'ak-1.5':  'var(--spacing-ak-1_5)',
   'ak-2':    'var(--spacing-ak-2)',
@@ -105,10 +109,12 @@ module.exports = plugin(
           'ak-elevated':        'var(--color-ak-elevated)',
           'ak-on-primary':      'var(--color-ak-on-primary)',
           'ak-primary-subtle':  'var(--color-ak-primary-subtle)',
+          'ak-primary-subtle-hover': 'var(--color-ak-primary-subtle-hover)',
           'ak-overlay':         'var(--color-ak-overlay)',
 
           // Semantic text
           'ak-text':            'var(--color-ak-text)',
+          'ak-text-emphasis':   'var(--color-ak-text-emphasis)',
           'ak-text-secondary':  'var(--color-ak-text-secondary)',
           'ak-text-muted':      'var(--color-ak-text-muted)',
           'ak-text-disabled':   'var(--color-ak-text-disabled)',
@@ -190,19 +196,34 @@ module.exports = plugin(
         fontSize: {
           // Static scale
           'ak-2xs':  'var(--text-ak-2xs)',
-          'ak-xs':   'var(--text-ak-xs)',
-          'ak-sm':   'var(--text-ak-sm)',
-          'ak-base': 'var(--text-ak-base)',
+          'ak-xs':     'var(--text-ak-xs)',
+          'ak-xs_5':  'var(--text-ak-xs_5)',
+          'ak-xs.5':  'var(--text-ak-xs_5)',
+          'ak-sm':    'var(--text-ak-sm)',
+          'ak-sm_5':  'var(--text-ak-sm_5)',
+          'ak-sm.5':  'var(--text-ak-sm_5)',
+          'ak-base':  'var(--text-ak-base)',
           'ak-lg':   'var(--text-ak-lg)',
-          'ak-xl':   'var(--text-ak-xl)',
-          'ak-2xl':  'var(--text-ak-2xl)',
-          'ak-3xl':  'var(--text-ak-3xl)',
-          'ak-4xl':  'var(--text-ak-4xl)',
-          'ak-5xl':  'var(--text-ak-5xl)',
-          'ak-6xl':  'var(--text-ak-6xl)',
-          'ak-7xl':  'var(--text-ak-7xl)',
-          'ak-8xl':  'var(--text-ak-8xl)',
-          'ak-9xl':  'var(--text-ak-9xl)',
+          'ak-xl':     'var(--text-ak-xl)',
+          'ak-xl_5':  'var(--text-ak-xl_5)',
+          'ak-xl.5':  'var(--text-ak-xl_5)',
+          'ak-2xl':   'var(--text-ak-2xl)',
+          'ak-2xl_5': 'var(--text-ak-2xl_5)',
+          'ak-2xl.5': 'var(--text-ak-2xl_5)',
+          'ak-3xl':   'var(--text-ak-3xl)',
+          'ak-4xl':   'var(--text-ak-4xl)',
+          'ak-4xl_5': 'var(--text-ak-4xl_5)',
+          'ak-4xl.5': 'var(--text-ak-4xl_5)',
+          'ak-5xl':   'var(--text-ak-5xl)',
+          'ak-6xl':   'var(--text-ak-6xl)',
+          'ak-6xl_5': 'var(--text-ak-6xl_5)',
+          'ak-6xl.5': 'var(--text-ak-6xl_5)',
+          'ak-7xl':   'var(--text-ak-7xl)',
+          'ak-7xl_5': 'var(--text-ak-7xl_5)',
+          'ak-7xl.5': 'var(--text-ak-7xl_5)',
+          'ak-8xl':   'var(--text-ak-8xl)',
+          'ak-9xl':   'var(--text-ak-9xl)',
+          'ak-10xl':  'var(--text-ak-10xl)',
           // Fluid scale
           'ak-fl-xs':   'clamp(0.6875rem, 0.67rem + 0.06vw, 0.75rem)',
           'ak-fl-sm':   'clamp(0.75rem, 0.71rem + 0.12vw, 0.875rem)',
@@ -231,13 +252,30 @@ module.exports = plugin(
           'ak-display-7xl':  'clamp(4.5rem, 3.06rem + 5.56vw, 8rem)',
           'ak-display-8xl':  'clamp(5rem, 3.06rem + 6.94vw, 9rem)',
           'ak-display-9xl':  'clamp(5.5rem, 3.06rem + 7.64vw, 10rem)',
+
+          'ak-watermark-2xs':  'clamp(1rem, 13cqi, 13rem)',
+          'ak-watermark-xs':   'clamp(1rem, 16cqi, 16rem)',
+          'ak-watermark-sm':   'clamp(1rem, 19cqi, 20rem)',
+          'ak-watermark-base': 'clamp(1rem, 21cqi, 22rem)',
+          'ak-watermark-md':   'clamp(1rem, 24cqi, 26rem)',
+          'ak-watermark-lg':   'clamp(1rem, 26cqi, 28rem)',
+          'ak-watermark-xl':   'clamp(1rem, 28cqi, 30rem)',
+          'ak-watermark-2xl':  'clamp(1rem, 30cqi, 34rem)',
+          'ak-watermark-3xl':  'clamp(1rem, 33cqi, 38rem)',
+          'ak-watermark-4xl':  'clamp(1rem, 36cqi, 42rem)',
+          'ak-watermark-5xl':  'clamp(1rem, 40cqi, 48rem)',
         },
 
         /* ── Line Height ── */
         lineHeight: {
-          'ak-display': 'var(--leading-ak-display)',
+          'ak-display':   'var(--leading-ak-display)',
+          'ak-squeezed':  'var(--leading-ak-squeezed)',
+          'ak-condensed': 'var(--leading-ak-condensed)',
+          'ak-none':      'var(--leading-ak-none)',
+          'ak-fitted':  'var(--leading-ak-fitted)',
+          'ak-compact': 'var(--leading-ak-compact)',
           'ak-tighter': 'var(--leading-ak-tighter)',
-          'ak-none':    'var(--leading-ak-none)',
+          'ak-snugger': 'var(--leading-ak-snugger)',
           'ak-tight':   'var(--leading-ak-tight)',
           'ak-snug':    'var(--leading-ak-snug)',
           'ak-normal':  'var(--leading-ak-normal)',
@@ -337,7 +375,8 @@ module.exports = plugin(
           'ak-control-sm': 'var(--height-ak-control-sm)',
           'ak-control-md': 'var(--height-ak-control-md)',
           'ak-control-lg': 'var(--height-ak-control-lg)',
-          'ak-control-xl': 'var(--height-ak-control-xl)',
+          'ak-control-xl':  'var(--height-ak-control-xl)',
+          'ak-control-2xl': 'var(--height-ak-control-2xl)',
           'ak-row-compact':     'var(--height-ak-row-compact)',
           'ak-row-default':     'var(--height-ak-row-default)',
           'ak-row-comfortable': 'var(--height-ak-row-comfortable)',
@@ -353,6 +392,7 @@ module.exports = plugin(
           'ak-control-md': 'var(--height-ak-control-md)',
           'ak-control-lg': 'var(--height-ak-control-lg)',
           'ak-control-xl': 'var(--height-ak-control-xl)',
+          'ak-control-2xl': 'var(--height-ak-control-2xl)',
           'ak-row-compact':     'var(--height-ak-row-compact)',
           'ak-row-default':     'var(--height-ak-row-default)',
           'ak-row-comfortable': 'var(--height-ak-row-comfortable)',