astralkit 0.2.0

package/LICENSE

@@ -0,0 +1,34 @@
+AstralKit License
+
+Copyright (c) 2025-2026 Blue Beacon Creative LLC. All rights reserved.
+
+This software and associated files (the "Software") are the proprietary
+intellectual property of Blue Beacon Creative LLC. The Software is licensed,
+not sold.
+
+The design tokens and CSS utilities included in this package are freely usable
+in any project that uses AstralKit components. Components, boosters, and
+workflows installed via the AstralKit CLI are governed by the AstralKit End
+User License Agreement.
+
+PROHIBITED USES
+
+You may NOT, without the express prior written consent of Blue Beacon Creative LLC:
+
+1. Use the Software's source code as training data, fine-tuning data, or input
+   for any artificial intelligence system, machine learning model, large language
+   model, neural network, or any automated system designed to generate code,
+   text, images, or other output.
+
+2. Resell, sublicense, or redistribute the Software as a standalone product,
+   design system, or token library.
+
+3. Build a competing product using the Software's design tokens, CSS
+   architecture, or utility system.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL BLUE BEACON CREATIVE LLC BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY.
+
+Full license terms: https://astralkit.com/license
+Contact: hello@astralkit.com

package/README.md

@@ -0,0 +1,58 @@
+# astralkit
+
+Design tokens, CSS variables, and utilities for [AstralKit](https://astralkit.com) UI components.
+
+This package provides the foundation that all AstralKit components depend on:
+
+- **Theme CSS** — `ak-*` design tokens (colors, spacing, typography, radius, shadows)
+- **Utilities CSS** — Tailwind CSS utility class extensions
+- **`cn()` helper** — Class merging utility (clsx + tailwind-merge)
+
+## Installation
+
+```bash
+npm install astralkit
+```
+
+Or use the CLI which installs this automatically:
+
+```bash
+npx @astralkit/cli init
+```
+
+## Usage
+
+**In your CSS:**
+```css
+@import "tailwindcss";
+@import "astralkit/theme";
+@import "astralkit/utilities";
+```
+
+**In your components:**
+```tsx
+import { cn } from 'astralkit/utils'
+
+export function Button({ className, ...props }) {
+  return <button className={cn('px-4 py-2 bg-ak-primary text-ak-on-primary', className)} {...props} />
+}
+```
+
+## What's included
+
+| Export | Description |
+|---|---|
+| `astralkit/theme` | CSS custom properties for all design tokens |
+| `astralkit/utilities` | Tailwind CSS utility extensions |
+| `astralkit/utils` | `cn()` class merging function |
+
+## Documentation
+
+- [Getting Started](https://astralkit.com/documentation/quick-start)
+- [Design Tokens](https://astralkit.com/documentation/design-tokens)
+- [CSS Variables Reference](https://astralkit.com/documentation/css-variables-reference)
+- [Theming & Customization](https://astralkit.com/documentation/theming-customization)
+
+## License
+
+Proprietary — [AstralKit License](https://astralkit.com/license)

package/ai-rules.md

@@ -0,0 +1,339 @@
+# AstralKit — AI Coding Rules
+
+> These rules ensure AI coding tools generate correct, responsive AstralKit code.
+> Drop this into your AI tool's config file, or let `astralkit init` do it for you.
+
+## Core Principle
+
+AstralKit uses a **fluid responsive system** — typography and spacing scale continuously with viewport width via CSS `clamp()`. This eliminates breakpoints for most use cases.
+
+**Prefer fluid tokens for scalable properties.** Breakpoint variants (sm:, md:, lg:, xl:) still work — but fluid tokens give you the same result in one class instead of four.
+
+---
+
+## Token Naming
+
+All AstralKit tokens use the `ak-` prefix:
+- Colors: `bg-ak-*`, `text-ak-*`, `border-ak-*`
+- Spacing: `p-ak-*`, `m-ak-*`, `gap-ak-*`
+- Fluid spacing: `p-ak-fl-*`, `m-ak-fl-*`, `gap-ak-fl-*`
+- Fluid type: `text-ak-fl-*`
+- Sizes: `size-ak-icon-*`, `size-ak-avatar-*`
+- Radius: `rounded-ak-*`
+- Shadows: `shadow-ak-*`
+- Layout: `max-w-ak-*`, `h-ak-*`
+- Z-index: `z-(--z-ak-*)`
+- Animation: `duration-ak-*`, `ease-ak-*`
+
+---
+
+## Fluid Typography — `text-ak-fl-*`
+
+For headings and body text, prefer fluid type tokens. These scale smoothly from mobile to desktop with zero breakpoints.
+
+```
+Instead of:  class="text-2xl md:text-3xl lg:text-5xl"
+Prefer:      class="text-ak-fl-5xl"
+```
+
+### Available fluid type tokens (small → large):
+`text-ak-fl-xs` · `text-ak-fl-sm` · `text-ak-fl-base` · `text-ak-fl-lg` · `text-ak-fl-xl` · `text-ak-fl-2xl` · `text-ak-fl-3xl` · `text-ak-fl-4xl` · `text-ak-fl-5xl` · `text-ak-fl-6xl` · `text-ak-fl-7xl` · `text-ak-fl-8xl` · `text-ak-fl-9xl`
+
+### When to use static type (`text-ak-*`) instead:
+- Small UI text that should NOT scale (button labels, badge text, nav links, form labels)
+- Text inside compact components (cards, dropdowns, tooltips)
+
+Static tokens: `text-ak-2xs` · `text-ak-xs` · `text-ak-sm` · `text-ak-base` · `text-ak-lg` · `text-ak-xl` · `text-ak-2xl`
+
+---
+
+## Fluid Spacing — Use `*-ak-fl-*` for Section-Level Spacing
+
+For **section padding, large gaps, and vertical rhythm margins**, use fluid spacing tokens.
+
+```
+Instead of:  class="py-8 md:py-16 lg:py-24"
+Prefer:      class="py-ak-fl-xl-3xl"
+```
+
+### Single-step fluid spacing (scale within one size):
+`*-ak-fl-3xs` · `*-ak-fl-2xs` · `*-ak-fl-xs` · `*-ak-fl-sm` · `*-ak-fl-md` · `*-ak-fl-lg` · `*-ak-fl-xl` · `*-ak-fl-2xl` · `*-ak-fl-3xl`
+
+### Space pairs (dramatic scaling — start small, end large):
+`*-ak-fl-xs-md` · `*-ak-fl-xs-lg` · `*-ak-fl-sm-lg` · `*-ak-fl-sm-xl` · `*-ak-fl-md-xl` · `*-ak-fl-md-2xl` · `*-ak-fl-lg-2xl` · `*-ak-fl-xl-3xl`
+
+Space pairs are ideal for section padding (e.g., `py-ak-fl-xl-3xl`), hero spacing, and large vertical gaps.
+
+### When to use static spacing (`*-ak-*`) instead:
+- 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`
+
+---
+
+## Decision Matrix: Fluid vs Static
+
+| Element | Use Fluid | Use Static |
+|---|---|---|
+| Page headings (h1-h3) | `text-ak-fl-5xl` through `text-ak-fl-3xl` | — |
+| Subheadings (h4-h6) | `text-ak-fl-2xl` through `text-ak-fl-lg` | — |
+| Section intro paragraphs | `text-ak-fl-base` or `text-ak-fl-lg` | — |
+| Section vertical padding | `py-ak-fl-xl-3xl` (space pair) | — |
+| Grid gaps between sections | `gap-ak-fl-lg` or `gap-ak-fl-xl` | — |
+| After-heading margins | `mb-ak-fl-sm` or `mb-ak-fl-md` | — |
+| Feature card padding | `p-ak-fl-md` or `p-ak-fl-sm` | — |
+| Hero/CTA inner padding | `p-ak-fl-lg-2xl` (space pair) | — |
+| Button labels | — | `text-ak-base` |
+| Nav link text | — | `text-ak-base` |
+| Badge/tag text | — | `text-ak-xs` or `text-ak-sm` |
+| Button padding | — | `px-ak-3 py-ak-1` |
+| Icon gaps | — | `gap-ak-1` or `gap-ak-0_5` |
+| Card internal spacing | — | `p-ak-2` or `p-ak-3` |
+
+---
+
+## Semantic Colors
+
+Prefer AstralKit's semantic color tokens over raw Tailwind colors. This enables theming and dark mode.
+
+```
+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`
+
+### Text:
+`text-ak-text` · `text-ak-text-secondary` · `text-ak-text-muted` · `text-ak-text-disabled` · `text-ak-text-inverse`
+
+### Border:
+`border-ak-border` · `border-ak-border-subtle` · `border-ak-border-strong` · `border-ak-border-focus`
+
+### Neutral scale (for decorative/data elements only):
+`ak-neutral-0` through `ak-neutral-950` (11 shades)
+
+### Status:
+`ak-success` · `ak-warning` · `ak-danger` · `ak-info` (each has base, `-subtle`, `-text` variants)
+
+---
+
+## Component Sizes — Use `size-ak-*`
+
+```
+Instead of:  class="w-6 h-6"      (icon)
+Prefer:      class="size-ak-icon-lg"
+
+Instead of:  class="w-10 h-10"    (avatar)
+Prefer:      class="size-ak-avatar-md"
+```
+
+### Icons: `size-ak-icon-xs` (12px) · `sm` (16px) · `md` (20px) · `lg` (24px) · `xl` (28px) · `2xl` (32px) · `3xl` (48px)
+### Avatars: `size-ak-avatar-sm` (32px) · `md` (40px) · `lg` (48px) · `xl` (64px) · `2xl` (96px) · `3xl` (128px)
+
+---
+
+## Layout — Use AK Layout Tokens
+
+```
+Instead of:  class="max-w-7xl mx-auto px-4"
+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)
+
+---
+
+## Layout Primitives — Use Instead of Breakpoint Grids
+
+AstralKit provides breakpoint-free layout primitives:
+
+- **`ak-stack`** — Vertical spacing between children. Customize: `--ak-stack-gap`
+- **`ak-cluster`** — Horizontal wrapping group (tags, nav). Customize: `--ak-cluster-gap`
+- **`ak-grid`** — Auto-responsive grid (RAM pattern). Customize: `--ak-grid-min`
+- **`ak-switcher`** — Horizontal → vertical at threshold. Customize: `--ak-switcher-threshold`
+- **`ak-sidebar`** — Fixed sidebar + fluid main. Customize: `--ak-sidebar-width`
+- **`ak-center`** — Centered content with max-width. Customize: `--ak-center-max`
+- **`ak-cover`** — Viewport-height centered layout. Child: `.ak-cover-center`
+
+```
+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
+
+The only valid use of breakpoint prefixes is for **layout switches** that cannot be expressed fluidly:
+
+- `lg:grid-cols-2` — Switching between stacked and side-by-side layouts
+- `md:flex` / `md:hidden` — Showing/hiding elements (mobile nav vs desktop nav)
+- `sm:flex-row` — Changing flex direction at a specific point
+
+These are binary layout decisions, not gradual scaling — fluid tokens can't replace them.
+
+---
+
+## Other Tokens
+
+### Border Radius:
+`rounded-ak-none` · `rounded-ak-sm` · `rounded-ak-md` · `rounded-ak-lg` · `rounded-ak-xl` · `rounded-ak-2xl` · `rounded-ak-3xl` · `rounded-ak-full`
+
+### Shadows:
+`shadow-ak-xs` · `shadow-ak-sm` · `shadow-ak-md` · `shadow-ak-lg` · `shadow-ak-xl` · `shadow-ak-2xl`
+
+### Z-Index (use arbitrary value syntax):
+`z-(--z-ak-sticky)` · `z-(--z-ak-dropdown)` · `z-(--z-ak-overlay)` · `z-(--z-ak-modal)`
+
+### Animation:
+`duration-ak-fast` · `duration-ak-base` · `duration-ak-slow`
+`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`
+
+### Letter Spacing:
+`tracking-ak-tighter` · `tracking-ak-tight` · `tracking-ak-normal` · `tracking-ak-wide` · `tracking-ak-wider` · `tracking-ak-widest`
+
+### Font Families:
+`font-ak-sans` · `font-ak-serif` · `font-ak-mono`
+
+---
+
+## Heading Presets (Utilities)
+
+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`
+
+---
+
+## Focus & Accessibility
+
+Always use `ak-focus-ring` on interactive elements instead of custom focus styles:
+```html
+<button class="... ak-focus-ring">Click me</button>
+<a href="#" class="... ak-focus-ring">Link</a>
+```
+
+Use `ak-focus-ring-inset` for elements inside panels where outward rings would clip.
+
+---
+
+## Quick Reference: Common Patterns
+
+```html
+<!-- Section -->
+<section class="py-ak-fl-xl-3xl bg-ak-bg">
+  <div class="max-w-ak-page mx-auto px-ak-3 lg:px-ak-5">
+    <h2 class="text-ak-fl-4xl font-bold tracking-ak-tight leading-ak-tight mb-ak-fl-sm">
+    <p class="text-ak-fl-base text-ak-text-secondary leading-ak-relaxed mb-ak-fl-md">
+
+<!-- Auto-responsive card grid -->
+<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">
+
+<!-- Icon -->
+<svg class="size-ak-icon-lg">
+
+<!-- Avatar -->
+<div class="size-ak-avatar-md rounded-ak-full">
+
+<!-- Nav bar -->
+<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">
+```