astralkit 0.6.0 → 0.7.0

package/lib/presets/materials.js

@@ -0,0 +1,245 @@
+/**
+ * astralkit/presets — material appearances.
+ *
+ * An APPEARANCE is a design language: the physical properties of the UI —
+ * surface fill/blur, border weight, shadow character, press behavior, type
+ * weight — expressed as a pack of --ak-material slots. Components consume
+ * the slots via the SDK recipes (.ak-material-control / .ak-material-surface
+ * / .ak-press); switching packs re-materializes a RUNNING app.
+ *
+ * Composability is the point: Appearance × Palette × Radius × Type Scale,
+ * all runtime. shadcn's styles are frozen skins baked at scaffold time —
+ * this dial is the thing that architecture cannot do.
+ *
+ * Each pack: light `variables`, authored `darkVariables`, and a suggested
+ * `radius` (applied only while the Radius dial sits on Default — an explicit
+ * radius pick always wins).
+ */
+
+export const DEFAULT_MATERIAL_ID = 'soft'
+
+const INK = '#0a0a0a'
+const PAPER = '#f4f4f5'
+
+export const MATERIAL_APPEARANCES = [
+  {
+    id: 'soft',
+    name: 'Soft',
+    description: 'The house default — quiet borders, calm surfaces.',
+    radius: null,
+    variables: {},
+    darkVariables: {},
+  },
+  {
+    id: 'flat',
+    name: 'Flat',
+    description: 'Zero elevation, crisp hairlines, sharp corners.',
+    radius: '0.375rem',
+    variables: {
+      '--ak-control-shadow': 'none',
+      '--ak-surface-shadow': 'none',
+      '--ak-surface-border-color': 'var(--color-ak-border-strong)',
+      '--ak-press-transform': 'scale(0.99)',
+      // Zero elevation extends to the small parts: crisp bordered thumb,
+      // shadowless knob, flat tracks, no hover theatrics.
+      '--ak-knob-shadow': 'none',
+      '--ak-thumb-shadow': 'none',
+      '--ak-thumb-border-w': '1px',
+      '--ak-thumb-border-color': 'var(--color-ak-border-strong)',
+      '--ak-thumb-hover-transform': 'none',
+      '--ak-track-shadow': '0 0 0 0 transparent',
+      '--ak-effect-mesh-opacity': '0',
+      '--ak-effect-grain-opacity': '0',
+      '--ak-effect-backlight-opacity': '0',
+    },
+    darkVariables: {
+      '--ak-control-shadow': 'none',
+      '--ak-surface-shadow': 'none',
+      '--ak-surface-border-color': 'rgba(255,255,255,0.22)',
+      '--ak-press-transform': 'scale(0.99)',
+      '--ak-knob-shadow': 'none',
+      '--ak-thumb-shadow': 'none',
+      '--ak-thumb-border-w': '1px',
+      '--ak-thumb-border-color': 'rgba(255,255,255,0.22)',
+      '--ak-thumb-hover-transform': 'none',
+      '--ak-track-shadow': '0 0 0 0 transparent',
+      '--ak-effect-mesh-opacity': '0',
+      '--ak-effect-grain-opacity': '0',
+      '--ak-effect-backlight-opacity': '0',
+    },
+  },
+  {
+    id: 'glass',
+    name: 'Glassmorphic',
+    description: 'White glass — one top-left light source; sheen, rim and speculars all agree on it.',
+    radius: '0.875rem',
+    variables: {
+      // Fred's Glass v2 reference: sheen falls off from the light (125deg),
+      // rim burns hot near it and dies opposite, specular inset on the lit
+      // edge + faint bounce on the shadow side. Standard 18px thickness.
+      '--ak-surface-fill': 'rgba(255,255,255,0.11)',
+      '--ak-surface-fill-2': 'rgba(255,255,255,0.18)',
+      '--ak-surface-sheen': 'linear-gradient(125deg, rgba(255,255,255,0.20), rgba(255,255,255,0.04) 38%, rgba(255,255,255,0) 62%)',
+      '--ak-surface-blur': 'blur(18px) saturate(1.6)',
+      '--ak-surface-border-w': '0px',
+      '--ak-surface-rim': 'linear-gradient(125deg, rgba(255,255,255,0.9) 0%, rgba(255,255,255,0.25) 30%, rgba(255,255,255,0.08) 55%, rgba(255,255,255,0.18) 100%)',
+      '--ak-surface-shadow': '0 24px 48px -16px rgba(0,0,0,0.28), inset 1px 1px 1px rgba(255,255,255,0.45), inset -1px -1px 1px rgba(255,255,255,0.08)',
+      '--ak-surface-shadow-2': '0 10px 22px -10px rgba(0,0,0,0.28), inset 1px 1px 1px rgba(255,255,255,0.4)',
+      '--ak-control-shadow': '0 4px 14px rgba(15,15,20,0.10)',
+      '--ak-press-transform': 'scale(0.97)',
+      // Law 4: glass is for surfaces — small-control active parts stay FLAT
+      // SOLID. Knob/thumb = plain white with a real drop; slider track = a
+      // carved groove (dark inset + light bottom edge). Spring per the ref.
+      '--ak-knob-fill': '#ffffff',
+      '--ak-knob-fill-checked': '#ffffff',
+      '--ak-knob-shadow': '0 2px 5px rgba(0,0,0,0.4)',
+      '--ak-control-spring': 'cubic-bezier(0.34, 1.4, 0.5, 1)',
+      '--ak-thumb-fill': '#ffffff',
+      '--ak-thumb-shadow': '0 2px 5px rgba(0,0,0,0.4)',
+      '--ak-thumb-hover-transform': 'scale(1.1)',
+      '--ak-thumb-active-transform': 'scale(0.96)',
+      '--ak-track-shadow': 'inset 0 2px 3px rgba(0,0,0,0.35), inset 0 -1px 1px rgba(255,255,255,0.25)',
+      '--ak-effect-mesh-opacity': '0.18',
+      '--ak-effect-grain-opacity': '0.015',
+      '--ak-effect-backlight-opacity': '0.08',
+    },
+    darkVariables: {
+      // Smoked glass — dark material, locks in text contrast regardless of
+      // the backdrop. Dimmer sheen and rim, calmer saturation.
+      '--ak-surface-fill': 'rgba(16,17,22,0.45)',
+      '--ak-surface-fill-2': 'rgba(22,24,30,0.55)',
+      '--ak-surface-sheen': 'linear-gradient(125deg, rgba(255,255,255,0.09), rgba(255,255,255,0.02) 38%, rgba(255,255,255,0) 62%)',
+      '--ak-surface-blur': 'blur(18px) saturate(1.2)',
+      '--ak-surface-border-w': '0px',
+      '--ak-surface-rim': 'linear-gradient(125deg, rgba(255,255,255,0.35) 0%, rgba(255,255,255,0.12) 30%, rgba(255,255,255,0.04) 55%, rgba(255,255,255,0.10) 100%)',
+      '--ak-surface-shadow': '0 24px 48px -16px rgba(0,0,0,0.5), inset 1px 1px 1px rgba(255,255,255,0.18), inset -1px -1px 1px rgba(255,255,255,0.04)',
+      '--ak-surface-shadow-2': '0 10px 22px -10px rgba(0,0,0,0.5), inset 1px 1px 1px rgba(255,255,255,0.14)',
+      '--ak-control-shadow': '0 4px 14px rgba(0,0,0,0.35)',
+      '--ak-press-transform': 'scale(0.97)',
+      '--ak-knob-fill': '#ffffff',
+      '--ak-knob-fill-checked': '#ffffff',
+      '--ak-knob-shadow': '0 2px 5px rgba(0,0,0,0.55)',
+      '--ak-control-spring': 'cubic-bezier(0.34, 1.4, 0.5, 1)',
+      '--ak-thumb-fill': '#ffffff',
+      '--ak-thumb-shadow': '0 2px 5px rgba(0,0,0,0.55)',
+      '--ak-thumb-hover-transform': 'scale(1.1)',
+      '--ak-thumb-active-transform': 'scale(0.96)',
+      '--ak-track-shadow': 'inset 0 2px 3px rgba(0,0,0,0.5), inset 0 -1px 1px rgba(255,255,255,0.12)',
+      '--ak-effect-mesh-opacity': '0.14',
+      '--ak-effect-grain-opacity': '0.015',
+      '--ak-effect-backlight-opacity': '0.10',
+    },
+  },
+  {
+    id: 'brutal',
+    name: 'Neo-Brutal',
+    description: 'The house brutalism — ink borders, hard offsets, the push-into-shadow press.',
+    // House brutal keeps FRIENDLY corners (--radius-ak-brutal = 0.5rem) —
+    // hard geometry, soft radius. That contrast IS the AstralKit brutal look.
+    radius: '0.5rem',
+    variables: {
+      // The authored ak-brutal token ladder (ink #000, 4/3/6px offsets) and
+      // the three-act ak-brutal-press choreography, expressed as slots:
+      // rest 4px → hover: slide 2px into a 3px shadow → active: fully
+      // pressed, shadow collapses to zero.
+      // Control shadows use SOFTENED ink (mixed toward the page color) so a
+      // fill that matches the ink — the B&W palette's primary — still reads
+      // against its shadow (Fred's call: tone separation, not rings). Card
+      // shadows stay pure ink; faces are always lighter there.
+      '--ak-control-shadow': '4px 4px 0 0 color-mix(in srgb, #000000 72%, var(--color-ak-bg))',
+      '--ak-control-hover-transform': 'translate(2px, 2px)',
+      '--ak-control-shadow-hover': '3px 3px 0 0 color-mix(in srgb, #000000 72%, var(--color-ak-bg))',
+      '--ak-press-transform': 'translate(4px, 4px)',
+      '--ak-control-shadow-active': '0 0 0 0 #000000',
+      '--ak-surface-border-w': 'var(--border-ak-brutal)',
+      '--ak-surface-border-color': '#000000',
+      '--ak-surface-shadow': '6px 6px 0 0 #000000',
+      '--ak-weight-ui': '700',
+      '--ak-weight-ui-strong': '800',
+      '--ak-weight-heading': '800',
+      '--ak-weight-label': '700',
+      '--ak-tracking-label': '0.05em',
+      // Quiet hover = the brutal backface, bottom edge only: a THICK ink
+      // underline pushed away from the text (not a hairline text-decoration).
+      '--ak-quiet-hover-line': 'underline',
+      '--ak-quiet-hover-thickness': '3px',
+      '--ak-quiet-hover-offset': '2px',
+      '--ak-quiet-hover-bg': 'transparent',
+      '--ak-quiet-hover-color': '#000000',
+      // Brutal focus is dashed ink; nested brutal surfaces go FLAT (border
+      // only) — shadow lives at the top level, per the reference doctrine.
+      '--ak-focus-outline': '3px dashed #000000',
+      '--ak-focus-offset': '4px',
+      '--ak-surface-shadow-2': 'none',
+      // Batch-2 control slots — the squish is the juice: solid ink knob that
+      // stretches on press, square-ish thumb that tilts on hover, loud
+      // bordered tracks. Thumb shadow uses the same softened ink as controls.
+      '--ak-knob-fill': '#000000',
+      '--ak-knob-fill-checked': 'var(--color-ak-bg)',
+      '--ak-knob-shadow': 'none',
+      '--ak-knob-press': 'scaleX(1.25)',
+      '--ak-control-spring': 'cubic-bezier(0.6, 1.6, 0.4, 1)',
+      '--ak-thumb-fill': 'var(--color-ak-bg)',
+      '--ak-thumb-radius': '8px',
+      '--ak-thumb-border-w': '3px',
+      '--ak-thumb-border-color': '#000000',
+      '--ak-thumb-shadow': '2px 2px 0 0 color-mix(in srgb, #000000 72%, var(--color-ak-bg))',
+      '--ak-thumb-hover-transform': 'rotate(8deg) scale(1.08)',
+      '--ak-thumb-active-transform': 'scale(0.94)',
+      '--ak-track-shadow': '0 0 0 0 transparent',
+      '--ak-track-border-w': '2px',
+      '--ak-track-border-color': '#000000',
+      '--ak-effect-mesh-opacity': '0',
+      '--ak-effect-grain-opacity': '0',
+      '--ak-effect-backlight-opacity': '0',
+    },
+    darkVariables: {
+      // Explicit paper values — the :root substitution rule means overriding
+      // --color-ak-brutal-ink here would never reach the shadow tokens.
+      '--ak-control-shadow': '4px 4px 0 0 color-mix(in srgb, #f4f4f5 68%, var(--color-ak-bg))',
+      '--ak-control-hover-transform': 'translate(2px, 2px)',
+      '--ak-control-shadow-hover': '3px 3px 0 0 color-mix(in srgb, #f4f4f5 68%, var(--color-ak-bg))',
+      '--ak-press-transform': 'translate(4px, 4px)',
+      '--ak-control-shadow-active': '0 0 0 0 #f4f4f5',
+      '--ak-surface-border-w': 'var(--border-ak-brutal)',
+      '--ak-surface-border-color': '#f4f4f5',
+      '--ak-surface-shadow': '6px 6px 0 0 #f4f4f5',
+      '--ak-weight-ui': '700',
+      '--ak-weight-ui-strong': '800',
+      '--ak-weight-heading': '800',
+      '--ak-weight-label': '700',
+      '--ak-tracking-label': '0.05em',
+      '--ak-quiet-hover-line': 'underline',
+      '--ak-quiet-hover-thickness': '3px',
+      '--ak-quiet-hover-offset': '2px',
+      '--ak-quiet-hover-bg': 'transparent',
+      '--ak-quiet-hover-color': '#f4f4f5',
+      '--ak-focus-outline': '3px dashed #f4f4f5',
+      '--ak-focus-offset': '4px',
+      '--ak-surface-shadow-2': 'none',
+      '--ak-knob-fill': '#f4f4f5',
+      '--ak-knob-fill-checked': 'var(--color-ak-bg)',
+      '--ak-knob-shadow': 'none',
+      '--ak-knob-press': 'scaleX(1.25)',
+      '--ak-control-spring': 'cubic-bezier(0.6, 1.6, 0.4, 1)',
+      '--ak-thumb-fill': 'var(--color-ak-bg)',
+      '--ak-thumb-radius': '8px',
+      '--ak-thumb-border-w': '3px',
+      '--ak-thumb-border-color': '#f4f4f5',
+      '--ak-thumb-shadow': '2px 2px 0 0 color-mix(in srgb, #f4f4f5 68%, var(--color-ak-bg))',
+      '--ak-thumb-hover-transform': 'rotate(8deg) scale(1.08)',
+      '--ak-thumb-active-transform': 'scale(0.94)',
+      '--ak-track-shadow': '0 0 0 0 transparent',
+      '--ak-track-border-w': '2px',
+      '--ak-track-border-color': '#f4f4f5',
+      '--ak-effect-mesh-opacity': '0',
+      '--ak-effect-grain-opacity': '0',
+      '--ak-effect-backlight-opacity': '0',
+    },
+  },
+]
+
+export function materialToVariables(material, opts) {
+  const mode = (opts && opts.mode) || 'light'
+  return { ...(mode === 'dark' ? material.darkVariables : material.variables) }
+}

package/lib/presets/theme-palettes.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Curated 60-30-10 Theme Palettes for AstralKit Theme Builder
+ *
+ * Each palette follows the 60-30-10 rule:
+ * - 60% Dominant: background, surface (large areas)
+ * - 30% Secondary: cards, sidebar, secondary surfaces
+ * - 10% Accent: CTAs, links, highlights, primary actions
+ *
+ * Token mapping:
+ * - background: Page background (60%)
+ * - surface: Card/panel backgrounds (60% variant)
+ * - foreground: Primary text color
+ * - foregroundMuted: Secondary/body text
+ * - primary: Main accent / CTA color (10%)
+ * - secondary: Supporting color (30%)
+ * - accent: Highlight / tertiary color
+ * - border: Divider and border color
+ * - ring: Focus ring color (usually primary-based)
+ * - muted: Muted/disabled backgrounds
+ * - destructive: Error/danger color
+ */
+export interface ThemePalette {
+    id: string;
+    name: string;
+    description: string;
+    mode: 'light' | 'dark';
+    colors: {
+        background: string;
+        surface: string;
+        foreground: string;
+        foregroundMuted: string;
+        primary: string;
+        secondary: string;
+        accent: string;
+        /** Optional text color for filled accent elements. Defaults to computed contrast. */
+        onAccent?: string;
+        border: string;
+        ring: string;
+        muted: string;
+        destructive: string;
+        /** Optional: slider/scrubber filled-track color. Defaults to primary when omitted. */
+        sliderFill?: string;
+        /** Optional: slider thumb ring color. Defaults to paper (bg) when omitted. */
+        sliderRing?: string;
+        /** Optional: branded CTA gradient stops. Defaults are derived from primary. */
+        brandGradient?: {
+            from: string;
+            via: string;
+            to: string;
+            hoverFrom?: string;
+            hoverVia?: string;
+            hoverTo?: string;
+        };
+    };
+    effects?: {
+        glowPrimary?: string;
+        glowSecondary?: string;
+        glowTertiary?: string;
+        glowWarm?: string;
+        meshBase?: string;
+    };
+}
+export type ThemeMode = ThemePalette['mode'];
+export declare const THEME_PALETTES: ThemePalette[];
+/**
+ * Keeps the chosen brand colors while swapping surface, text, border, and muted
+ * scaffolding to the current UI mode.
+ */
+export declare function resolvePaletteForMode(palette: ThemePalette, mode: ThemeMode): ThemePalette;
+/**
+ * Maps a ThemePalette to the actual --color-ak-* CSS variables
+ * that AstralKit components consume.
+ *
+ * This is the critical bridge between our 60-30-10 palette
+ * and the component design token system.
+ */
+export declare function paletteToAkVariables(palette: ThemePalette, options?: {
+    mode?: ThemeMode;
+}): Record<string, string>;
+/**
+ * Palette authorship lint — encodes the recipe learned from curation:
+ * keepers share a near-neutral foreground, neutral light surfaces, and a
+ * mid-luminance primary (or an explicit accent split for light primaries).
+ * Returns human-readable warnings; empty array = palette is well-formed.
+ */
+export declare function validatePalette(palette: ThemePalette): string[];
+/**
+ * Generates CSS :root block from a palette using the ak variable names.
+ */
+export declare function paletteToCSS(palette: ThemePalette): string;