astralkit 0.3.8 → 0.5.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ 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.5.0] — 2026-06-12
+
+### Added (Material 3 role grammar)
+- **45 new color-role tokens across both the v4 `@theme` and the v3 Tailwind plugin** (full v3/v4 parity). These complete the M3 role grammar that a large set of components now depend on:
+  - **Surface containers** — `surface-3`, `surface-4`, `surface-container`, `surface-container-low`/`-lowest`/`-high`/`-highest`.
+  - **Inverse** — `inverse-surface`, `inverse-on-surface` (dark cards on light themes and vice-versa).
+  - **Secondary / tertiary / accent / error roles** — `secondary`(+`-container`), `on-secondary`(+`-container`), `tertiary`(+`-container`), `on-tertiary`(+`-container`), `accent`, `accent-soft`, `on-accent`, `error`, `error-container`, `on-error`, `on-error-container`, plus `primary-container`/`on-primary-container`.
+  - **Surface / outline** — `on-surface`, `on-surface-variant`, `outline`, `outline-variant`, `scrim`.
+  - **Per-theme controls** — `slider-fill`, `slider-ring` (themed Radix slider fill/ring).
+  - **Status badges** — `status-{new,beta,stable,deprecated}-{bg,border,text}`.
+
+### Fixed
+- **`ak-skeleton` shimmer now respects `prefers-reduced-motion`.** Added a `@media (prefers-reduced-motion: reduce)` guard that stops the looping shimmer on `.ak-skeleton::after`.
+
+## [0.4.0] — 2026-06-06
+
+### Added
+- **`astralkit/motion`** — accessible Framer Motion presets tuned to the AstralKit motion tokens (`fadeInUp`, `fadeIn`, `scaleIn`, `staggerContainer`/`staggerItem`, `revealOnScroll`, `hoverLift`/`pressable`, `akTransition`, and `withReducedMotion`). Plain variant/transition objects — importing adds **no dependency**; bring your own `motion` (MIT). All presets are `prefers-reduced-motion`-safe via `withReducedMotion`.
+
+### Changed
+- **Motion policy reversed: Framer Motion is now allowed.** The previous "no Framer Motion" rule was based on a licensing misunderstanding — the `motion` package is MIT. `ai-rules.md` now permits Framer Motion + CSS + Lenis and points to the `astralkit/motion` presets; **GSAP** is the disallowed one (its license restricts sold products/templates).
+- `ai-rules.md`: motion guidance updated accordingly; premium-effect toolkit (`ak-card-glow`, `ak-mesh-*`, `ak-float`, `ak-scroll-fade`, etc.) emphasized for richer output.
+
 ## [0.3.8] — 2026-06-06
 
 ### Fixed

package/ai-rules.md

@@ -19,7 +19,7 @@ These constraints prevent generic "AI slop" output. Follow them strictly.
 
 **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`).
+**Motion: Framer Motion + CSS + Lenis are allowed; GSAP is not.** Framer Motion (the MIT `motion` package) is fine — prefer the `astralkit/motion` presets (tuned to the motion tokens, reduced-motion-safe). CSS animations via `ak-*` tokens (`duration-ak-base`, `ease-ak-spring`) and effect primitives (`.ak-press`, `.ak-card-glow`, `.ak-float`, `.ak-scroll-fade`) are also encouraged. Lenis for smooth scroll. Always honor `prefers-reduced-motion`. **Do not use GSAP** (its license disallows sold products/templates).
 
 **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.
 

package/astralkit-theme-v4.css

@@ -47,6 +47,8 @@
   --color-ak-bg:              #ffffff;
   --color-ak-surface:         #fafafa;
   --color-ak-surface-2:       #f5f5f5;
+  --color-ak-surface-3:       #efefef;
+  --color-ak-surface-4:       #e9e9e9;
   --color-ak-hover:           #f7f7f7;
   --color-ak-active:          #f0f0f0;
   --color-ak-elevated:        #ffffff;
@@ -54,6 +56,40 @@
   --color-ak-surface-raised-soft: rgba(255, 255, 255, 0.78);
   --color-ak-surface-glass:   rgba(255, 255, 255, 0.72);
   --color-ak-surface-glass-strong: rgba(255, 255, 255, 0.84);
+
+  /* == M3 role layer (additive - old names remain working aliases forever) == */
+  --color-ak-inverse-surface:     #171717;
+  --color-ak-inverse-on-surface:  #fafafa;
+  --color-ak-on-error:            #ffffff;
+  --color-ak-on-tertiary:         #ffffff;
+  /* Selection accent: defaults to brand primary; palettes may split it
+     (e.g. Pulse: ink CTAs via primary, volt-lime selection via accent). */
+  --color-ak-accent:        var(--color-ak-primary);
+  --color-ak-on-accent:     var(--color-ak-on-primary);
+  --color-ak-accent-soft:   var(--color-ak-surface-2);
+  /* M3 names as alias vars (follow their targets in dark automatically) */
+  --color-ak-surface-container-lowest:   var(--color-ak-bg);
+  --color-ak-surface-container-low:      var(--color-ak-surface);
+  --color-ak-surface-container:          var(--color-ak-surface-2);
+  --color-ak-surface-container-high:     var(--color-ak-surface-3);
+  --color-ak-surface-container-highest:  var(--color-ak-surface-4);
+  --color-ak-on-surface:            var(--color-ak-text);
+  --color-ak-on-surface-variant:    var(--color-ak-text-secondary);
+  --color-ak-outline:               var(--color-ak-border);
+  --color-ak-outline-variant:       var(--color-ak-border-subtle);
+  --color-ak-primary-container:     var(--color-ak-primary-subtle);
+  --color-ak-on-primary-container:  var(--color-ak-primary-900);
+  --color-ak-secondary:             var(--color-ak-accent);
+  --color-ak-on-secondary:          var(--color-ak-on-accent);
+  --color-ak-secondary-container:   var(--color-ak-accent-soft);
+  --color-ak-on-secondary-container: var(--color-ak-text);
+  --color-ak-tertiary:              var(--color-ak-info);
+  --color-ak-tertiary-container:    var(--color-ak-info-subtle);
+  --color-ak-on-tertiary-container: var(--color-ak-info-text);
+  --color-ak-error:                 var(--color-ak-danger);
+  --color-ak-error-container:       var(--color-ak-danger-subtle);
+  --color-ak-on-error-container:    var(--color-ak-danger-text);
+  --color-ak-scrim:                 var(--color-ak-overlay);
   --color-ak-highlight-soft:  rgba(255, 255, 255, 0.45);
   --color-ak-highlight-strong: rgba(255, 255, 255, 0.72);
   --color-ak-skeleton-base:   #ededed;
@@ -564,6 +600,12 @@
   --color-ak-bg:              #111113;
   --color-ak-surface:         #18191b;
   --color-ak-surface-2:       #1e1f21;
+  --color-ak-surface-3:       #252628;
+  --color-ak-surface-4:       #2c2d30;
+  --color-ak-inverse-surface:    #f4f4f5;
+  --color-ak-inverse-on-surface: #111113;
+  --color-ak-on-error:           #111113;
+  --color-ak-on-tertiary:        #111113;
   --color-ak-hover:           rgba(255,255,255,0.04);
   --color-ak-active:          rgba(255,255,255,0.08);
   --color-ak-elevated:        #252628;

package/astralkit-theme.css

@@ -49,6 +49,8 @@
   --color-ak-bg:              #ffffff;
   --color-ak-surface:         #fafafa;
   --color-ak-surface-2:       #f5f5f5;
+  --color-ak-surface-3:       #efefef;
+  --color-ak-surface-4:       #e9e9e9;
   --color-ak-hover:           #f7f7f7;
   --color-ak-active:          #f0f0f0;
   --color-ak-elevated:        #ffffff;
@@ -56,6 +58,40 @@
   --color-ak-surface-raised-soft: rgba(255, 255, 255, 0.78);
   --color-ak-surface-glass:   rgba(255, 255, 255, 0.72);
   --color-ak-surface-glass-strong: rgba(255, 255, 255, 0.84);
+
+  /* == M3 role layer (additive - old names remain working aliases forever) == */
+  --color-ak-inverse-surface:     #171717;
+  --color-ak-inverse-on-surface:  #fafafa;
+  --color-ak-on-error:            #ffffff;
+  --color-ak-on-tertiary:         #ffffff;
+  /* Selection accent: defaults to brand primary; palettes may split it
+     (e.g. Pulse: ink CTAs via primary, volt-lime selection via accent). */
+  --color-ak-accent:        var(--color-ak-primary);
+  --color-ak-on-accent:     var(--color-ak-on-primary);
+  --color-ak-accent-soft:   var(--color-ak-surface-2);
+  /* M3 names as alias vars (follow their targets in dark automatically) */
+  --color-ak-surface-container-lowest:   var(--color-ak-bg);
+  --color-ak-surface-container-low:      var(--color-ak-surface);
+  --color-ak-surface-container:          var(--color-ak-surface-2);
+  --color-ak-surface-container-high:     var(--color-ak-surface-3);
+  --color-ak-surface-container-highest:  var(--color-ak-surface-4);
+  --color-ak-on-surface:            var(--color-ak-text);
+  --color-ak-on-surface-variant:    var(--color-ak-text-secondary);
+  --color-ak-outline:               var(--color-ak-border);
+  --color-ak-outline-variant:       var(--color-ak-border-subtle);
+  --color-ak-primary-container:     var(--color-ak-primary-subtle);
+  --color-ak-on-primary-container:  var(--color-ak-primary-900);
+  --color-ak-secondary:             var(--color-ak-accent);
+  --color-ak-on-secondary:          var(--color-ak-on-accent);
+  --color-ak-secondary-container:   var(--color-ak-accent-soft);
+  --color-ak-on-secondary-container: var(--color-ak-text);
+  --color-ak-tertiary:              var(--color-ak-info);
+  --color-ak-tertiary-container:    var(--color-ak-info-subtle);
+  --color-ak-on-tertiary-container: var(--color-ak-info-text);
+  --color-ak-error:                 var(--color-ak-danger);
+  --color-ak-error-container:       var(--color-ak-danger-subtle);
+  --color-ak-on-error-container:    var(--color-ak-danger-text);
+  --color-ak-scrim:                 var(--color-ak-overlay);
   --color-ak-highlight-soft:  rgba(255, 255, 255, 0.45);
   --color-ak-highlight-strong: rgba(255, 255, 255, 0.72);
   --color-ak-skeleton-base:   #ededed;
@@ -564,6 +600,12 @@
   --color-ak-bg:              #111113;
   --color-ak-surface:         #18191b;
   --color-ak-surface-2:       #1e1f21;
+  --color-ak-surface-3:       #252628;
+  --color-ak-surface-4:       #2c2d30;
+  --color-ak-inverse-surface:    #f4f4f5;
+  --color-ak-inverse-on-surface: #111113;
+  --color-ak-on-error:           #111113;
+  --color-ak-on-tertiary:        #111113;
   --color-ak-hover:           rgba(255,255,255,0.04);
   --color-ak-active:          rgba(255,255,255,0.08);
   --color-ak-elevated:        #252628;

package/lib/motion.d.ts

@@ -0,0 +1,29 @@
+// Types for astralkit/motion. Kept structural (no framer-motion dependency).
+// The objects are valid Framer Motion Variants / Transitions / motion props.
+
+type AkVariants = Record<string, Record<string, unknown>>;
+type AkTransition = Record<string, unknown>;
+type AkMotionProps = Record<string, unknown>;
+
+export declare const akTransition: {
+  fast: AkTransition;
+  smooth: AkTransition;
+  spring: AkTransition;
+  springSoft: AkTransition;
+  bounce: AkTransition;
+};
+
+export declare const fadeIn: AkVariants;
+export declare const fadeInUp: AkVariants;
+export declare const fadeInDown: AkVariants;
+export declare const scaleIn: AkVariants;
+
+export declare function staggerContainer(stagger?: number, delayChildren?: number): AkVariants;
+export declare const staggerItem: AkVariants;
+
+export declare const revealOnScroll: AkMotionProps;
+export declare const pressable: AkMotionProps;
+export declare const hoverLift: AkMotionProps;
+export declare const hoverScale: AkMotionProps;
+
+export declare function withReducedMotion(variants: AkVariants, reduced: boolean | null | undefined): AkVariants;

package/lib/motion.js

@@ -0,0 +1,85 @@
+/**
+ * astralkit/motion — accessible Framer Motion presets tuned to AstralKit's
+ * motion tokens (--duration-ak-*, --ease-ak-spring/bounce/default).
+ *
+ * These are plain Framer Motion variant/transition OBJECTS — importing this
+ * module adds NO dependency. You bring your own `motion` (the MIT Framer
+ * Motion package) and spread/assign these presets:
+ *
+ *   import { motion, useReducedMotion } from "motion/react"
+ *   import { fadeInUp, staggerContainer, staggerItem, revealOnScroll, hoverLift, withReducedMotion } from "astralkit/motion"
+ *
+ *   // Entrance
+ *   <motion.div initial="hidden" animate="show" variants={fadeInUp} />
+ *   // Staggered list
+ *   <motion.ul initial="hidden" animate="show" variants={staggerContainer()}>
+ *     {items.map(i => <motion.li key={i} variants={staggerItem} />)}
+ *   </motion.ul>
+ *   // Scroll reveal (spread onto the element)
+ *   <motion.section {...revealOnScroll} />
+ *   // Interaction
+ *   <motion.button {...hoverLift} />
+ *
+ * Accessibility: ALWAYS honor reduced motion —
+ *   const reduced = useReducedMotion()
+ *   <motion.div initial="hidden" animate="show" variants={withReducedMotion(fadeInUp, reduced)} />
+ */
+
+/** Transitions matched to AstralKit's --duration-ak-* / --ease-ak-* tokens. */
+export const akTransition = {
+  fast: { duration: 0.11, ease: [0.4, 0, 0.2, 1] }, // --duration-ak-fast / --ease-ak-default
+  smooth: { duration: 0.24, ease: [0.4, 0, 0.2, 1] }, // --duration-ak-slow / --ease-ak-default
+  spring: { type: 'spring', stiffness: 400, damping: 30 }, // crisp UI spring
+  springSoft: { type: 'spring', stiffness: 260, damping: 26 },
+  bounce: { type: 'spring', stiffness: 500, damping: 18 }, // ~ --ease-ak-bounce
+};
+
+/** Entrance variants — use with initial="hidden" animate="show" (or whileInView). */
+export const fadeIn = {
+  hidden: { opacity: 0 },
+  show: { opacity: 1, transition: akTransition.smooth },
+};
+export const fadeInUp = {
+  hidden: { opacity: 0, y: 12 },
+  show: { opacity: 1, y: 0, transition: akTransition.smooth },
+};
+export const fadeInDown = {
+  hidden: { opacity: 0, y: -12 },
+  show: { opacity: 1, y: 0, transition: akTransition.smooth },
+};
+export const scaleIn = {
+  hidden: { opacity: 0, scale: 0.96 },
+  show: { opacity: 1, scale: 1, transition: akTransition.spring },
+};
+
+/** Stagger a group of children (each child uses `staggerItem`). */
+export const staggerContainer = (stagger = 0.06, delayChildren = 0) => ({
+  hidden: {},
+  show: { transition: { staggerChildren: stagger, delayChildren } },
+});
+export const staggerItem = fadeInUp;
+
+/** Spread onto a motion element for a scroll-triggered reveal (animates once). */
+export const revealOnScroll = {
+  initial: 'hidden',
+  whileInView: 'show',
+  viewport: { once: true, amount: 0.3 },
+  variants: fadeInUp,
+};
+
+/** Interaction presets — spread onto a motion element. */
+export const pressable = { whileTap: { scale: 0.97 }, transition: akTransition.spring };
+export const hoverLift = { whileHover: { y: -2 }, whileTap: { y: 0 }, transition: akTransition.spring };
+export const hoverScale = { whileHover: { scale: 1.02 }, whileTap: { scale: 0.98 }, transition: akTransition.spring };
+
+/**
+ * Return reduced-motion-safe variants. Pass the boolean from useReducedMotion().
+ * When reduced, transforms are dropped and only opacity changes (instantly).
+ */
+export function withReducedMotion(variants, reduced) {
+  if (!reduced) return variants;
+  return {
+    hidden: { opacity: 0 },
+    show: { opacity: 1, transition: { duration: 0 } },
+  };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astralkit",
-  "version": "0.3.8",
+  "version": "0.5.0",
   "description": "Design tokens and component primitives for accessible UI — Tailwind CSS v3 & v4",
   "type": "module",
   "exports": {
@@ -10,6 +10,7 @@
     "./tailwind": "./tailwind.cjs",
     "./tailwind.cjs": "./tailwind.cjs",
     "./utils": "./lib/utils.js",
+    "./motion": "./lib/motion.js",
     "./ai-rules": "./ai-rules.md",
     "./palettes": "./palettes.css"
   },