@glasshome/widget-sdk 0.3.7 → 0.4.1

package/README.md

@@ -68,6 +68,24 @@ Provides a `@source` directive for Tailwind v4 so the compiler scans widget SDK
 @source "@glasshome/widget-sdk/tailwind-sources";
 ```
 
+## Escape patterns, when widgets own their visual surface
+
+Most widgets route through the channel API: `<Widget tone>` / `<Widget color colorTo>` / `<Widget.Icon color>`. A small number of widgets intentionally own their entire visual surface and bypass the channel. These are supported escape patterns, not anti-patterns.
+
+### Weather, full-background scenes
+
+The `weather` widget renders a `<WeatherBackground condition>` component that replaces the shell gradient entirely with an animated per-condition scene (sunny rays, rain droplets, snow particles). Channel vars do not apply to the shell; `Widget.Icon color` still receives a CSS string per condition for the icon badge.
+
+### Media-player, vinyl gradient
+
+The `media-player` widget composes a custom `<VinylRecord>` element with an album-art radial overlay. The visual identity is content-driven (album artwork) rather than tone-driven; the channel base color stays neutral underneath.
+
+### Area, per-metric pill colors
+
+The `area` widget renders quick-glance metric pills (CO2 traffic-light, humidity range, temperature) where each pill's color encodes the metric's *semantic state* (CO2 green/amber/red, humidity dry/comfortable/humid). These per-metric color rules are intentionally semantic-per-metric, not channel-driven, and live in the widget's own helpers.
+
+If your widget needs full visual control (a chart, a video stream, a custom animated surface), follow these patterns: keep the `<Widget>` shell neutral (no `tone`/`color`), place your custom DOM inside `<Widget.Content>`, and document the choice in the widget's README.
+
 ## Peer Dependencies
 
 | Package    | Required | Notes                                       |

package/dist/framework/backgrounds/WidgetSliderFill.d.ts

@@ -1,33 +1,44 @@
 /**
  * WidgetSliderFill Component
  *
- * Animated fill overlay that follows a slider value.
- * Automatically adapts direction based on widget orientation.
+ * Animated fill overlay that follows a slider value. Background and glow are
+ * rendered by the `.glasshome-widget-slider-fill` CSS rule in tokens.css via
+ * the channel vars (`--widget-icon-color` with fallback to `--widget-color`).
+ * The `color` prop is the optional per-fill override: when provided it is
+ * written inline as `--widget-icon-color`, mirroring `Widget.Icon.color`
+ * (Phase 26 VIS-A05). Orientation is inherited from the parent Widget context
+ * and drives the `clip-path` direction.
  *
- * @example
+ * @example Default, inherits parent Widget channel color
  * ```tsx
- * <Widget gestures={{ slide: { value, onChange } }}>
- *   <Widget.SliderFill value={brightness} color="rgb(255, 200, 0)" />
+ * <Widget tone="info" gestures={{ slide: { value, onChange } }}>
+ *   <Widget.SliderFill value={position} />
  *   <Widget.Content>...</Widget.Content>
  * </Widget>
  * ```
+ *
+ * @example Per-fill override (sets --widget-icon-color, not background directly)
+ * ```tsx
+ * <Widget.SliderFill value={brightness} color={bulbColor} />
+ * ```
  */
 import type { JSX } from "solid-js";
-export interface WidgetSliderFillProps {
+interface WidgetSliderFillProps {
     /** Current value (0-100) */
     value: number;
-    /** Fill color (CSS color string) */
+    /**
+     * Optional channel override: sets `--widget-icon-color` inline on the fill
+     * root. When omitted the fill renders in the parent Widget's channel color
+     * (var(--widget-color)). Mirrors Widget.Icon.color (Phase 26 VIS-A05).
+     */
     color?: string;
-    /** Show glow effect */
-    glow?: boolean;
-    /** Opacity of the fill (0-1) */
-    opacity?: number;
-    /** Whether slider is currently being dragged (disables transition) */
+    /** Whether the slider is currently being dragged (disables transition) */
     isDragging?: boolean;
     /** Additional CSS classes */
     class?: string;
 }
 /**
- * Animated slider fill that adapts to widget orientation
+ * Animated slider fill that adapts to widget orientation.
  */
 export declare function WidgetSliderFill(props: WidgetSliderFillProps): JSX.Element;
+export {};

package/dist/framework/components/WidgetContent.d.ts

@@ -16,7 +16,7 @@
  * ```
  */
 import type { JSX } from "solid-js";
-export interface WidgetContentProps {
+interface WidgetContentProps {
     /** Additional CSS classes */
     class?: string;
     /** Content children */
@@ -27,3 +27,4 @@ export interface WidgetContentProps {
  * Ensures proper z-index layering for title, status, and controls
  */
 export declare function WidgetContent(props: WidgetContentProps): JSX.Element;
+export {};

package/dist/framework/components/WidgetIcon.d.ts

@@ -1,48 +1,46 @@
 /**
  * WidgetIcon Component
  *
- * Icon component with automatic sizing and glow effect.
- * Supports both Tailwind classes and dynamic CSS colors for background/glow.
+ * Channel-driven icon. Background and glow read from `--widget-icon-color`
+ * (with fallback to `--widget-color`) and `--widget-glow-strength` via the
+ * `.glasshome-widget-icon` CSS rule in tokens.css. The `color` prop is the
+ * optional per-icon override, pass any CSS color string (oklch, rgb, hex,
+ * hsl, var(...)).
  *
- * @example Static color (Tailwind classes)
+ * @example Default, inherits the parent Widget's channel color
  * ```tsx
- * <Widget.Icon
- *   icon={<Power />}
- *   color="bg-blue-500 dark:bg-blue-400"
- *   glow="shadow-blue-500/50 dark:shadow-blue-400/50"
- * />
+ * <Widget tone="info">
+ *   <Widget.Icon icon={<Power />} />
+ * </Widget>
  * ```
  *
- * @example Dynamic color (CSS color string — adaptive contrast)
+ * @example Per-icon override (e.g. light bulb showing its actual rgb_color)
  * ```tsx
- * <Widget.Icon
- *   icon={<Lightbulb />}
- *   dynamicColor="hsl(320, 100%, 50%)"
- * />
+ * <Widget.Icon icon={<Lightbulb />} color="oklch(0.85 0.2 60)" />
  * ```
  */
 import type { JSX } from "solid-js";
-export interface WidgetIconProps {
+interface WidgetIconProps {
     /** Icon component (JSX.Element) */
     icon: JSX.Element;
-    /** Background color as Tailwind class (e.g. "bg-blue-500 dark:bg-blue-400") */
-    color?: string;
-    /** Glow/shadow effect as Tailwind class (e.g. "shadow-blue-500/50") */
-    glow?: string;
     /**
-     * Dynamic CSS color string (rgb, hsl, hex).
-     * When provided, icon background and glow are derived adaptively from this color.
-     * Takes precedence over `color` and `glow` props.
+     * Optional CSS color string (oklch, hsl, rgb, hex, var()).
+     * Sets `--widget-icon-color` inline on the icon root, overriding the
+     * channel base color for the icon only. When omitted the channel's
+     * `--widget-color` flows through via the tokens.css rule.
+     * BREAKING (Phase 26): previously accepted Tailwind class strings.
      */
-    dynamicColor?: string;
+    color?: string;
     /** Reduce opacity */
     dimmed?: boolean;
-    /** Number of entities - creates stacked background effect (1 = single, 2+ = stacked backgrounds) */
+    /** Number of entities, creates stacked background effect (1 = single, 2+ = stacked backgrounds) */
     entityCount?: number;
     /** Additional CSS classes */
     class?: string;
 }
 /**
- * Widget icon component with auto-responsive sizing
+ * Widget icon component with auto-responsive sizing.
+ * Background + glow rendered by the `.glasshome-widget-icon` CSS rule.
  */
 export declare function WidgetIcon(props: WidgetIconProps): JSX.Element;
+export {};

package/dist/framework/components/WidgetStatus.d.ts

@@ -9,7 +9,7 @@
  * ```
  */
 import type { JSX } from "solid-js";
-export interface WidgetStatusProps {
+interface WidgetStatusProps {
     /** Reduce opacity further */
     dimmed?: boolean;
     /** Additional CSS classes */
@@ -24,3 +24,4 @@ export interface WidgetStatusProps {
  * Positioned above other content with proper z-index
  */
 export declare function WidgetStatus(props: WidgetStatusProps): JSX.Element;
+export {};

package/dist/framework/components/WidgetTitle.d.ts

@@ -14,7 +14,7 @@
  * ```
  */
 import type { JSX } from "solid-js";
-export interface WidgetTitleProps {
+interface WidgetTitleProps {
     /** Optional badge count */
     badge?: number;
     /** Additional CSS classes */
@@ -27,3 +27,4 @@ export interface WidgetTitleProps {
  * Positioned above other content with proper z-index
  */
 export declare function WidgetTitle(props: WidgetTitleProps): JSX.Element;
+export {};

package/dist/framework/components/WidgetValue.d.ts

@@ -15,7 +15,7 @@
  * ```
  */
 import type { JSX } from "solid-js";
-export interface WidgetValueProps {
+interface WidgetValueProps {
     /** The value to display */
     value: number | string;
     /** Unit of measurement */
@@ -29,3 +29,4 @@ export interface WidgetValueProps {
  * Widget value component with auto-formatting and interpretation
  */
 export declare function WidgetValue(props: WidgetValueProps): JSX.Element;
+export {};

package/dist/framework/core/Widget.d.ts

@@ -12,9 +12,9 @@
  * </Widget>
  * ```
  *
- * @example With gradient and loading
+ * @example With CSS gradient and loading
  * ```tsx
- * <Widget gradient="bg-gradient-to-br from-blue-500/40 to-blue-700/40" loading={isLoading}>
+ * <Widget gradient="linear-gradient(135deg, oklch(0.7 0.2 30), oklch(0.5 0.18 270))" loading={isLoading}>
  *   {children}
  * </Widget>
  * ```
@@ -22,16 +22,14 @@
 import { type JSX } from "solid-js";
 import type { WidgetSliderFill as WidgetSliderFillType } from "../backgrounds/WidgetSliderFill";
 import type { WidgetContent as WidgetContentType } from "../components/WidgetContent";
-import type { WidgetEmptyState as WidgetEmptyStateType } from "../components/WidgetEmptyState";
 import type { WidgetIcon as WidgetIconType } from "../components/WidgetIcon";
-import type { WidgetMetrics as WidgetMetricsType } from "../components/WidgetMetrics";
 import type { WidgetStatus as WidgetStatusType } from "../components/WidgetStatus";
-import type { WidgetSubtitle as WidgetSubtitleType } from "../components/WidgetSubtitle";
 import type { WidgetTitle as WidgetTitleType } from "../components/WidgetTitle";
 import type { WidgetValue as WidgetValueType } from "../components/WidgetValue";
 import type { GestureHandlers } from "../gestures/use-widget-gestures";
-import type { WidgetOrientation, WidgetSize, WidgetVariantConfig } from "../types";
-export interface WidgetEmptyStateConfig {
+import type { WidgetVariantConfig } from "../types";
+import type { Tone } from "../theming/tone";
+interface WidgetEmptyStateConfig {
     /** Icon to display */
     icon?: JSX.Element;
     /** Main title/heading */
@@ -39,22 +37,40 @@ export interface WidgetEmptyStateConfig {
     /** Descriptive message */
     message?: string;
 }
-export interface WidgetProps {
+interface WidgetProps {
     /** Widget variant (string ID or inline config) */
     variant?: string | WidgetVariantConfig;
-    /** Gradient background (Tailwind classes like "bg-gradient-to-br from-cyan-600/40 to-blue-700/40") */
+    /**
+     * Semantic tone (success, warning, danger, info, neutral, accent).
+     * Resolves to `--widget-color: var(--tone-{name})` inline on the widget root.
+     * Phase 26 channel API, preferred path for state-driven semantic widgets.
+     */
+    tone?: Tone;
+    /**
+     * CSS color string (oklch, hsl, hex, rgb, var()).
+     * Sets `--widget-color` directly. Overrides `tone` when both supplied.
+     */
+    color?: string;
+    /**
+     * Optional second-stop CSS color string for two-stop gradient identity.
+     * Sets `--widget-color-to`. When omitted the shell formula falls back to `--widget-color`.
+     */
+    colorTo?: string;
+    /**
+     * Full CSS gradient string (e.g. `linear-gradient(135deg, oklch(...), oklch(...))`).
+     * Sets `--widget-gradient` and overrides the auto-derived shell gradient verbatim.
+     * BREAKING (Phase 26): previously accepted Tailwind class strings; now expects raw CSS.
+     */
     gradient?: string;
     /** Show loading overlay */
     loading?: boolean;
-    /** Background glow color (Tailwind color like "bg-blue-500") (runtime override) */
-    backgroundGlow?: string;
     /** Additional CSS classes */
     class?: string;
     /** Is edit mode (disables gestures) */
     isEditMode?: boolean;
     /** Called when delete button is clicked (only shown in edit mode) */
     onDelete?: () => void;
-    /** Empty state configuration - when provided, shows empty state and applies gray gradient */
+    /** Empty state configuration, when provided shows empty state UI inside the shell */
     emptyState?: WidgetEmptyStateConfig;
     /**
      * Gesture handlers from `useWidgetGestures`. When provided, Widget binds
@@ -65,31 +81,14 @@ export interface WidgetProps {
     /** Child elements */
     children?: JSX.Element;
 }
-export interface WidgetComponent {
+interface WidgetComponent {
     (props: WidgetProps): JSX.Element;
     Content: typeof WidgetContentType;
     Icon: typeof WidgetIconType;
     Title: typeof WidgetTitleType;
-    Subtitle: typeof WidgetSubtitleType;
     Status: typeof WidgetStatusType;
     Value: typeof WidgetValueType;
-    Metrics: typeof WidgetMetricsType;
-    EmptyState: typeof WidgetEmptyStateType;
     SliderFill: typeof WidgetSliderFillType;
 }
-/**
- * Classify widget size based on grid dimensions
- */
-export declare function classifySize(gridWidth: number, gridHeight: number): WidgetSize;
-/**
- * Detect orientation from dimensions based on aspect ratio
- * Used for gesture direction (slide horizontal vs vertical)
- */
-export declare function detectOrientation(width: number, height: number): WidgetOrientation;
-/**
- * Detect content layout direction
- * Used for UI arrangement (stack vertically vs horizontally)
- * Considers height threshold - tall widgets benefit from vertical stacking
- */
-export declare function detectContentLayout(width: number, height: number): WidgetOrientation;
 export declare const Widget: WidgetComponent;
+export {};

package/dist/framework/gestures/cursors.d.ts

@@ -3,7 +3,7 @@
  * Each cursor is a data URI embedded inline — no external files needed.
  * Hotspot coordinates are included for proper click positioning.
  */
-export interface CursorDef {
+interface CursorDef {
     css: string;
     hotspotX: number;
     hotspotY: number;
@@ -15,3 +15,4 @@ export declare const cursors: {
     readonly slideVertical: CursorDef;
     readonly slideAuto: CursorDef;
 };
+export {};

package/dist/framework/hooks/index.d.ts

@@ -1,15 +1,8 @@
 /**
  * Framework Hooks - Barrel Export
  *
- * All hooks for widget development: context, responsive, dialog, form,
- * config, entity, entity group, debug data, and gestures.
+ * Hooks for widget development: context, dialog, entity group.
  */
-export { type GestureHandlers, useWidgetGestures } from "../gestures/use-widget-gestures";
-export { type UseDebugDataOptions, useDebugData } from "./use-debug-data";
-export { type UseWidgetConfigOptions, type UseWidgetConfigReturn, useWidgetConfig, } from "./use-widget-config";
-export { type BridgeableWidgetContext, type BridgeFns, type ReactiveWidgetContext, useWidgetContext, warnIfStub, WidgetCtx, } from "./use-widget-context";
+export { type BridgeableWidgetContext, type BridgeFns, type ReactiveWidgetContext, useWidgetContext, WidgetCtx, } from "./use-widget-context";
 export { useWidgetDialog, type WidgetDialogReturn } from "./use-widget-dialog";
-export { type UseWidgetEntityOptions, type UseWidgetEntityResult, useWidgetEntity, } from "./use-widget-entity";
 export { type AggregationPreset, type UseWidgetEntityGroupOptions, type UseWidgetEntityGroupResult, useWidgetEntityGroup, } from "./use-widget-entity-group";
-export { type UseWidgetFormOptions, type UseWidgetFormReturn, useWidgetForm, } from "./use-widget-form";
-export { useWidgetResponsive, type WidgetResponsiveUtils } from "./use-widget-responsive";

package/dist/framework/hooks/use-widget-context.d.ts

@@ -57,11 +57,6 @@ export interface BridgeableWidgetContext extends ReactiveWidgetContext {
     /** Setter functions called by Widget.tsx createEffect to push real values */
     _bridge: BridgeFns;
 }
-/**
- * Emit a one-time dev-mode console.warn when stub context values are read
- * before Widget has mounted and bridged real measured values.
- */
-export declare function warnIfStub(isStub: () => boolean): void;
 /**
  * Widget context
  * Uses reactive accessor pattern for SolidJS

package/dist/framework/index.d.ts

@@ -10,8 +10,6 @@
  *   Widget,
  *   useWidgetGestures,
  *   useWidgetDialog,
- *   spacing,
- *   cn,
  * } from "@glasshome/widget-sdk";
  *
  * export function MyWidget(props) {
@@ -33,25 +31,15 @@
  */
 export { Widget } from "./core/Widget";
 export { WidgetContent } from "./components/WidgetContent";
-export { WidgetEmptyState } from "./components/WidgetEmptyState";
 export { WidgetIcon } from "./components/WidgetIcon";
-export { WidgetMetrics } from "./components/WidgetMetrics";
 export { WidgetStatus } from "./components/WidgetStatus";
-export { WidgetSubtitle } from "./components/WidgetSubtitle";
 export { WidgetTitle } from "./components/WidgetTitle";
 export { WidgetValue } from "./components/WidgetValue";
-export { Glow } from "./backgrounds/Glow";
 export { WidgetSliderFill } from "./backgrounds/WidgetSliderFill";
-export { WidgetStack } from "./layout/WidgetStack";
 export { WidgetDialog, type WidgetDialogProps, type WidgetDialogTab } from "./dialogs";
-export { type AggregationPreset, type BridgeableWidgetContext, type BridgeFns, type ReactiveWidgetContext, type UseDebugDataOptions, type UseWidgetConfigOptions, type UseWidgetConfigReturn, type UseWidgetEntityGroupOptions, type UseWidgetEntityGroupResult, type UseWidgetEntityOptions, type UseWidgetEntityResult, type UseWidgetFormOptions, type UseWidgetFormReturn, useDebugData, useWidgetConfig, useWidgetContext, useWidgetDialog, useWidgetEntity, useWidgetEntityGroup, useWidgetForm, useWidgetResponsive, warnIfStub, WidgetCtx, type WidgetDialogReturn, type WidgetResponsiveUtils, } from "./hooks";
+export { type AggregationPreset, type BridgeableWidgetContext, type BridgeFns, type ReactiveWidgetContext, type UseWidgetEntityGroupOptions, type UseWidgetEntityGroupResult, useWidgetContext, useWidgetDialog, useWidgetEntityGroup, WidgetCtx, type WidgetDialogReturn, } from "./hooks";
 export { type GestureHandlers, useWidgetGestures } from "./gestures/use-widget-gestures";
-export { getSpacingClass, spacing } from "./design-system/spacing";
-export { typography } from "./design-system/typography";
-export { WIDGET_Z, type WidgetZIndex } from "./design-system/z-index";
-export { type AdaptiveIconColors, deriveAdaptiveIconColors, GRADIENT_NAMES, GRADIENT_PRESET_KEYS, GRADIENT_PRESETS, type GradientPreset, getGradient, getGradientFromString, gradientColorPresets, stateColors, type WidgetColorPreset, } from "./theming";
-export { applyCssVars, applyLayout, builtInVariants, classicGlass, compactHorizontal, composeVariants, createFlexLayout, extendVariant, getBuiltInVariant, getBuiltInVariantIds, isBuiltInVariant, mergeVariants, minimal, } from "./variants";
+export { injectTokens, type Tone, ToneSchema, } from "./theming";
 export { widgetFields } from "./fields";
-export { extractDefaults, toFormSchema } from "./to-form-schema";
-export { allEntitiesInState, anyEntityInState, calculateLightGroup, calculateSensorGroup, cn, countActiveEntities, countAvailableEntities, countEntitiesByState, createEmptyStateConfig, type EmptyStateConfigOptions, formatValue, getEntityAttribute, getEntityState, interpretValue, isEntityActive, isEntityAvailable, type LightGroupResult, type SensorGroupResult, type SensorGroupType, type WidgetEmptyStateConfig, } from "./utils";
-export type { AbsoluteLayoutStrategy, BaseComponentProps, ColorVariant, CustomLayoutStrategy, ElementConfig, EntityView, FlexLayoutStrategy, GestureConfig, GradientConfig, GridLayoutStrategy, HoldGestureConfig, ImageOverlay, InteractionConfig, LayoutStrategy, PositionConfig, SlideGestureConfig, SpacingScale, VariantPlugins, VariantRegistry, WidgetContextValue, WidgetDimensions, WidgetElement, WidgetOrientation, WidgetSize, WidgetStyles, WidgetVariant, WidgetVariantConfig, } from "./types";
+export { calculateLightGroup, calculateSensorGroup, countActiveEntities, getEntityAttribute, isEntityActive, type LightGroupResult, type SensorGroupResult, type SensorGroupType, } from "./utils";
+export type { EntityView, WidgetContextValue, WidgetDimensions, WidgetOrientation, WidgetSize, WidgetStyles, WidgetVariantConfig, } from "./types";

package/dist/framework/theming/index.d.ts

@@ -1,8 +1,7 @@
 /**
- * Widget Theming - Shared Colors
+ * Widget Theming
  *
- * Simple color palette for entity states.
- * Widgets can use these or define their own logic.
+ * Tone schema and token injection.
  */
-export { type AdaptiveIconColors, deriveAdaptiveIconColors } from "./adaptive-color";
-export { GRADIENT_NAMES, GRADIENT_PRESET_KEYS, GRADIENT_PRESETS, type GradientPreset, getGradient, getGradientFromString, gradientColorPresets, stateColors, type WidgetColorPreset, } from "./colors";
+export { ToneSchema, type Tone } from "./tone";
+export { injectTokens } from "./tokens";

package/dist/framework/theming/tokens.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Minimal document-shape needed for token injection. Allows tests to pass
+ * a stub without a full DOM implementation.
+ */
+interface InjectTokensRoot {
+    head: {
+        appendChild: (node: unknown) => void;
+        querySelector?: (sel: string) => unknown;
+    };
+    createElement: (tag: string) => {
+        setAttribute: (name: string, value: string) => void;
+        textContent: string | null;
+    };
+}
+/**
+ * Inject the SDK tokens stylesheet into <head>. Idempotent across:
+ *  - Repeated calls within the same module instance (boolean sentinel).
+ *  - Multiple SDK module instances (DOM sentinel data-glasshome-tokens).
+ *  - SSR / non-browser environments (no-op when document is undefined).
+ */
+export declare function injectTokens(doc?: InjectTokensRoot): void;
+/** Test-only: reset the module-level sentinel. Not exported from the package root. */
+export declare function __resetInjectedForTests(): void;
+export {};

package/dist/framework/theming/tone.d.ts

@@ -0,0 +1,10 @@
+import { z } from "zod";
+export declare const ToneSchema: z.ZodEnum<{
+    success: "success";
+    warning: "warning";
+    danger: "danger";
+    info: "info";
+    neutral: "neutral";
+    accent: "accent";
+}>;
+export type Tone = z.infer<typeof ToneSchema>;

package/dist/framework/types.d.ts

@@ -46,15 +46,6 @@ export interface WidgetContextValue {
     /** Whether widget is in edit mode */
     isEditMode: boolean;
 }
-/**
- * Gradient configuration
- */
-export interface GradientConfig {
-    /** Tailwind gradient from class (e.g., "from-blue-500") */
-    from: string;
-    /** Tailwind gradient to class (e.g., "to-blue-700") */
-    to: string;
-}
 /**
  * Slide gesture configuration
  */
@@ -96,26 +87,8 @@ export interface GestureConfig {
  * Spacing scale
  */
 export type SpacingScale = "S1" | "S2" | "S3" | "S4";
-/**
- * Color variants for common components
- */
-export type ColorVariant = "blue" | "green" | "red" | "yellow" | "purple" | "gray" | string;
-/**
- * Image overlay types
- */
-export type ImageOverlay = "gradient" | "dark" | "none";
-/**
- * Base props that all framework components accept
- */
-export interface BaseComponentProps {
-    /** Additional CSS classes (SolidJS uses `class` instead of `className`) */
-    class?: string;
-    /** Child elements */
-    children?: JSX.Element;
-}
 /**
  * CSS variable-based styling configuration
- * Replaces brittle Tailwind class strings with type-safe CSS variables
  */
 export interface WidgetStyles {
     /** Inline CSS properties applied to widget container */
@@ -130,17 +103,11 @@ export interface WidgetStyles {
  */
 export interface FlexLayoutStrategy {
     type: "flex";
-    /** Flex direction */
     direction: "row" | "column" | "row-reverse" | "column-reverse";
-    /** Align items */
     align: "start" | "center" | "end" | "stretch";
-    /** Justify content */
     justify: "start" | "center" | "end" | "between" | "around";
-    /** Flex wrap */
     wrap?: boolean;
-    /** Gap between items (CSS value) */
     gap?: string;
-    /** Custom order for specific elements */
     order?: Partial<Record<WidgetElement, number>>;
 }
 /**
@@ -148,15 +115,10 @@ export interface FlexLayoutStrategy {
  */
 export interface GridLayoutStrategy {
     type: "grid";
-    /** Grid template areas string */
     areas: string;
-    /** Grid template columns */
     columns?: string;
-    /** Grid template rows */
     rows?: string;
-    /** Gap between items (CSS value) */
     gap?: string;
-    /** Grid area assignments for elements */
     elementAreas: Partial<Record<WidgetElement, string>>;
 }
 /**
@@ -164,7 +126,6 @@ export interface GridLayoutStrategy {
  */
 export interface AbsoluteLayoutStrategy {
     type: "absolute";
-    /** Position configurations for specific elements */
     positions: Partial<Record<WidgetElement, PositionConfig>>;
 }
 /**
@@ -172,12 +133,10 @@ export interface AbsoluteLayoutStrategy {
  */
 export interface CustomLayoutStrategy {
     type: "custom";
-    /** Custom render function or component */
     renderer: string;
 }
 /**
  * Discriminated union of all layout strategies
- * Ensures type safety - can't use gridArea with flex, etc.
  */
 export type LayoutStrategy = FlexLayoutStrategy | GridLayoutStrategy | AbsoluteLayoutStrategy | CustomLayoutStrategy;
 /**
@@ -198,68 +157,42 @@ export type WidgetElement = "icon" | "title" | "subtitle" | "status" | "value" |
  * Element-specific configuration
  */
 export interface ElementConfig {
-    /** Show/hide specific elements */
     visible?: Partial<Record<WidgetElement, boolean>>;
-    /** Element-specific styling */
     styles?: Partial<Record<WidgetElement, JSX.CSSProperties>>;
-    /** Element-specific CSS classes */
     classNames?: Partial<Record<WidgetElement, string>>;
 }
 /**
  * Plugin system configuration (serializable)
- * Uses string IDs instead of JSX.Element for serializability
  */
 export interface VariantPlugins {
-    /** Background plugin ID */
     background?: string;
-    /** Overlay plugin ID */
     overlay?: string;
-    /** Decoration plugin IDs */
     decorations?: string[];
 }
 /**
  * Interaction configuration
  */
 export interface InteractionConfig {
-    /** Enable hover effects */
     hover?: boolean;
-    /** Enable active/pressed state */
     active?: boolean;
-    /** Enable focus ring */
     focus?: boolean;
-    /** Custom hover scale (e.g., 1.02) */
     hoverScale?: number;
-    /** Custom active scale (e.g., 0.98) */
     activeScale?: number;
 }
 /**
  * Complete variant configuration
- * This is the core of the variant system
  */
 export interface WidgetVariantConfig {
-    /** Unique variant identifier */
     id: string;
-    /** Human-readable name */
     name: string;
-    /** Description of variant purpose/style */
     description?: string;
-    /** Styling configuration */
     styles?: WidgetStyles;
-    /** Layout strategy */
     layout?: LayoutStrategy;
-    /** Element-specific configuration */
     elements?: ElementConfig;
-    /** Plugin configurations */
     plugins?: VariantPlugins;
-    /** Interaction behavior */
     interactions?: InteractionConfig;
-    /** Base variant to extend (enables composition) */
     extends?: string;
 }
-/**
- * Variant type union (built-in + custom)
- */
-export type WidgetVariant = "classic-glass" | "minimal" | "compact-horizontal" | (string & {});
 /**
  * Variant registry type
  */