astralkit 0.3.8 → 0.4.0

package/CHANGELOG.md

@@ -5,6 +5,15 @@ 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.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/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.4.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"
   },