@flikk/ui 1.0.0-beta.3 → 1.0.0-beta.30

package/dist/generative.schema.json

@@ -0,0 +1,2052 @@
+{
+  "version": 1,
+  "icons": [
+    "ArrowTrendingUp",
+    "Bolt",
+    "Briefcase",
+    "ChartBar",
+    "ChatBubbleLeftRight",
+    "CheckCircle",
+    "CurrencyDollar",
+    "ExclamationTriangle",
+    "Globe",
+    "PencilSquare",
+    "RocketLaunch",
+    "ShoppingCart",
+    "UserPlus",
+    "Users"
+  ],
+  "components": {
+    "Accordion": {
+      "role": "leaf",
+      "description": "Collapsible sections driven by a serializable items array.",
+      "props": {
+        "type": {
+          "kind": "enum",
+          "options": [
+            "single",
+            "multiple"
+          ],
+          "description": "Accordion type - single allows only one item open, multiple allows many"
+        },
+        "variant": {
+          "kind": "enum",
+          "options": [
+            "separated",
+            "stacked"
+          ],
+          "description": "Visual variant - separated (card-like with spacing) or stacked (unified borders)"
+        },
+        "collapsible": {
+          "kind": "boolean",
+          "description": "Whether accordion can be collapsed after being opened (for type=\"single\")"
+        },
+        "items": {
+          "kind": "shape",
+          "shape": "accordionItems",
+          "description": "Data-driven items. When provided, the accordion renders from this array and"
+        }
+      }
+    },
+    "Alert": {
+      "role": "leaf",
+      "description": "Inline callout with semantic color.",
+      "props": {
+        "color": {
+          "kind": "enum",
+          "options": [
+            "neutral",
+            "primary",
+            "success",
+            "warning",
+            "danger"
+          ],
+          "description": "Semantic color"
+        },
+        "title": {
+          "kind": "text",
+          "description": "The main title/message of the alert"
+        },
+        "subtitle": {
+          "kind": "text",
+          "description": "Additional subtitle text"
+        },
+        "icon": {
+          "kind": "icon",
+          "description": "Custom icon for the alert"
+        },
+        "showIcon": {
+          "kind": "boolean",
+          "description": "Whether to show the default icon for the variant"
+        }
+      }
+    },
+    "AreaChart": {
+      "role": "leaf",
+      "description": "Area chart (auto Card shell + shared-height container).",
+      "props": {
+        "dotRadius": {
+          "kind": "number"
+        },
+        "radius": {
+          "kind": "number"
+        },
+        "strokeWidth": {
+          "kind": "number"
+        },
+        "curved": {
+          "kind": "boolean"
+        },
+        "showDots": {
+          "kind": "boolean"
+        },
+        "fillOpacity": {
+          "kind": "number"
+        },
+        "showStroke": {
+          "kind": "boolean"
+        },
+        "stacked": {
+          "kind": "boolean"
+        },
+        "data": {
+          "kind": "shape",
+          "shape": "chartData",
+          "required": true
+        },
+        "config": {
+          "kind": "shape",
+          "shape": "chartConfig",
+          "required": true
+        },
+        "width": {
+          "kind": "union",
+          "types": [
+            "number",
+            "string"
+          ]
+        },
+        "height": {
+          "kind": "union",
+          "types": [
+            "number",
+            "string"
+          ]
+        },
+        "enableKeyboardNavigation": {
+          "kind": "boolean"
+        },
+        "showGrid": {
+          "kind": "boolean"
+        },
+        "showXAxis": {
+          "kind": "boolean"
+        },
+        "showYAxis": {
+          "kind": "boolean"
+        },
+        "legend": {
+          "kind": "enum",
+          "options": [
+            "top",
+            "bottom",
+            "none"
+          ],
+          "description": "Always-visible legend position, rendered from `config`'s labels/colors."
+        },
+        "minValue": {
+          "kind": "number"
+        },
+        "maxValue": {
+          "kind": "number"
+        },
+        "variant": {
+          "kind": "enum",
+          "options": [
+            "default",
+            "minimal",
+            "gradient"
+          ]
+        },
+        "barRadius": {
+          "kind": "number"
+        },
+        "cellRadius": {
+          "kind": "number"
+        },
+        "gap": {
+          "kind": "number"
+        },
+        "curveType": {
+          "kind": "enum",
+          "options": [
+            "linear",
+            "monotone",
+            "step",
+            "stepBefore",
+            "stepAfter"
+          ]
+        },
+        "title": {
+          "kind": "text",
+          "description": "Card header title (the auto shell)"
+        },
+        "subtitle": {
+          "kind": "text",
+          "description": "Card header subtitle (the auto shell)"
+        }
+      }
+    },
+    "Avatar": {
+      "role": "leaf",
+      "description": "User avatar with initials fallback.",
+      "props": {
+        "src": {
+          "kind": "string",
+          "description": "The source URL for the avatar image"
+        },
+        "name": {
+          "kind": "string",
+          "description": "The name of the person or entity represented by the avatar."
+        },
+        "size": {
+          "kind": "union",
+          "types": [
+            "number",
+            "string"
+          ],
+          "default": "md",
+          "description": "The size of the avatar"
+        },
+        "status": {
+          "kind": "enum",
+          "options": [
+            "none",
+            "online",
+            "offline",
+            "busy",
+            "away"
+          ],
+          "default": "none",
+          "description": "Optional status indicator"
+        },
+        "gradient": {
+          "kind": "union",
+          "types": [
+            "boolean",
+            "string"
+          ],
+          "default": false,
+          "description": "Render a deterministic mesh-gradient as the avatar's background layer. The"
+        },
+        "gradientVariant": {
+          "kind": "enum",
+          "options": [
+            "marble",
+            "terra",
+            "spectrum",
+            "mint",
+            "neon"
+          ],
+          "default": "marble",
+          "description": "Curated color palette for the gradient background. Only applies when"
+        },
+        "title": {
+          "kind": "string",
+          "description": "Title text displayed next to the avatar."
+        },
+        "subtitle": {
+          "kind": "string",
+          "description": "Subtitle text displayed below the title (e.g., email, role)."
+        },
+        "verified": {
+          "kind": "boolean",
+          "description": "Whether to show a verification badge overlay at the bottom right."
+        }
+      }
+    },
+    "AvatarGroup": {
+      "role": "leaf",
+      "description": "Overlapping stack of avatars driven by a serializable list.",
+      "props": {
+        "avatars": {
+          "kind": "shape",
+          "shape": "avatarList",
+          "required": true,
+          "description": "Array of avatar props to render in the group"
+        },
+        "max": {
+          "kind": "number",
+          "default": 5,
+          "description": "Maximum number of avatars to display before showing a count"
+        },
+        "size": {
+          "kind": "union",
+          "types": [
+            "number",
+            "string"
+          ],
+          "default": "md",
+          "description": "Size for all avatars in the group"
+        },
+        "spacing": {
+          "kind": "enum",
+          "options": [
+            "tight",
+            "normal",
+            "loose"
+          ],
+          "default": "normal",
+          "description": "Amount of overlap between avatars (higher value = more overlap)"
+        },
+        "direction": {
+          "kind": "enum",
+          "options": [
+            "row",
+            "row-reverse"
+          ],
+          "default": "row",
+          "description": "Direction of the avatar stack"
+        },
+        "ariaLabel": {
+          "kind": "string",
+          "default": "Group of users",
+          "description": "ARIA label for the avatar group for accessibility"
+        },
+        "shouldAnimate": {
+          "kind": "boolean",
+          "default": true,
+          "description": "Enable motion animations for hover effects"
+        }
+      }
+    },
+    "Badge": {
+      "role": "leaf",
+      "description": "Small status label.",
+      "props": {
+        "children": {
+          "kind": "text",
+          "required": true,
+          "description": "The content to be displayed inside the badge"
+        },
+        "variant": {
+          "kind": "enum",
+          "options": [
+            "filled",
+            "outline",
+            "soft"
+          ],
+          "default": "filled",
+          "description": "The visual style variant of the badge (filled, outline, soft)"
+        },
+        "color": {
+          "kind": "enum",
+          "options": [
+            "neutral",
+            "primary",
+            "success",
+            "warning",
+            "danger"
+          ],
+          "default": "primary",
+          "description": "The semantic color of the badge (primary, success, danger, etc.)"
+        },
+        "size": {
+          "kind": "enum",
+          "options": [
+            "sm",
+            "md"
+          ],
+          "default": "md",
+          "description": "The size of the badge"
+        },
+        "pill": {
+          "kind": "boolean",
+          "default": false,
+          "description": "Whether the badge is pill-shaped (fully rounded)"
+        },
+        "withDot": {
+          "kind": "boolean",
+          "default": false,
+          "description": "Whether the badge has a dot indicator"
+        },
+        "iconStart": {
+          "kind": "icon",
+          "description": "Icon element at the start (before content)"
+        },
+        "disabled": {
+          "kind": "boolean",
+          "default": false,
+          "description": "Whether the badge is disabled"
+        }
+      }
+    },
+    "BarChart": {
+      "role": "leaf",
+      "description": "Bar chart (auto Card shell + shared-height container).",
+      "props": {
+        "barRadius": {
+          "kind": "number"
+        },
+        "radius": {
+          "kind": "number"
+        },
+        "gap": {
+          "kind": "number"
+        },
+        "categoryGap": {
+          "kind": "number"
+        },
+        "colors": {
+          "kind": "shape",
+          "shape": "colorList",
+          "description": "Custom color palette for bar series. Colors are applied in order to each data series."
+        },
+        "showAnimation": {
+          "kind": "boolean"
+        },
+        "data": {
+          "kind": "shape",
+          "shape": "chartData",
+          "required": true
+        },
+        "config": {
+          "kind": "shape",
+          "shape": "chartConfig",
+          "required": true
+        },
+        "width": {
+          "kind": "union",
+          "types": [
+            "number",
+            "string"
+          ]
+        },
+        "height": {
+          "kind": "union",
+          "types": [
+            "number",
+            "string"
+          ]
+        },
+        "enableKeyboardNavigation": {
+          "kind": "boolean"
+        },
+        "showGrid": {
+          "kind": "boolean"
+        },
+        "showXAxis": {
+          "kind": "boolean"
+        },
+        "showYAxis": {
+          "kind": "boolean"
+        },
+        "legend": {
+          "kind": "enum",
+          "options": [
+            "top",
+            "bottom",
+            "none"
+          ],
+          "description": "Always-visible legend position, rendered from `config`'s labels/colors."
+        },
+        "minValue": {
+          "kind": "number"
+        },
+        "maxValue": {
+          "kind": "number"
+        },
+        "variant": {
+          "kind": "enum",
+          "options": [
+            "default",
+            "minimal",
+            "gradient"
+          ]
+        },
+        "dotRadius": {
+          "kind": "number"
+        },
+        "cellRadius": {
+          "kind": "number"
+        },
+        "strokeWidth": {
+          "kind": "number"
+        },
+        "curved": {
+          "kind": "boolean"
+        },
+        "curveType": {
+          "kind": "enum",
+          "options": [
+            "linear",
+            "monotone",
+            "step",
+            "stepBefore",
+            "stepAfter"
+          ]
+        },
+        "showDots": {
+          "kind": "boolean"
+        },
+        "fillOpacity": {
+          "kind": "number"
+        },
+        "showStroke": {
+          "kind": "boolean"
+        },
+        "stacked": {
+          "kind": "boolean"
+        },
+        "orientation": {
+          "kind": "enum",
+          "options": [
+            "vertical",
+            "horizontal"
+          ]
+        },
+        "title": {
+          "kind": "text",
+          "description": "Card header title (the auto shell)"
+        },
+        "subtitle": {
+          "kind": "text",
+          "description": "Card header subtitle (the auto shell)"
+        }
+      }
+    },
+    "Breadcrumbs": {
+      "role": "leaf",
+      "description": "Navigation breadcrumb trail driven by a serializable items array.",
+      "props": {
+        "items": {
+          "kind": "shape",
+          "shape": "breadcrumbItems",
+          "required": true,
+          "description": "Array of breadcrumb items"
+        },
+        "maxItems": {
+          "kind": "number",
+          "description": "Maximum number of items to display before collapsing. Defaults to 4"
+        },
+        "variant": {
+          "kind": "enum",
+          "options": [
+            "default",
+            "muted"
+          ],
+          "description": "Visual variant of the breadcrumbs"
+        },
+        "showIcons": {
+          "kind": "boolean",
+          "description": "Whether to show icons if provided in items"
+        }
+      }
+    },
+    "Button": {
+      "role": "leaf",
+      "description": "Action button — pair with node.actions.click ({ type, payload }).",
+      "props": {
+        "color": {
+          "kind": "enum",
+          "options": [
+            "neutral",
+            "primary",
+            "danger"
+          ],
+          "description": "The semantic color/intent of the button"
+        },
+        "variant": {
+          "kind": "enum",
+          "options": [
+            "filled",
+            "outline",
+            "soft",
+            "ghost"
+          ],
+          "description": "The visual style variant of the button"
+        },
+        "size": {
+          "kind": "enum",
+          "options": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "description": "The size of the button"
+        },
+        "state": {
+          "kind": "enum",
+          "options": [
+            "default",
+            "disabled",
+            "loading"
+          ],
+          "description": "The state of the button (default, loading, disabled)"
+        },
+        "iconOnly": {
+          "kind": "boolean",
+          "description": "Whether the button should display as icon-only (square padding)"
+        },
+        "block": {
+          "kind": "boolean",
+          "description": "Whether the button should be full width"
+        },
+        "children": {
+          "kind": "text",
+          "description": "Button contents"
+        },
+        "enableRipple": {
+          "kind": "boolean",
+          "description": "Whether to enable ripple effect on click"
+        },
+        "rippleEffect": {
+          "kind": "enum",
+          "options": [
+            "default",
+            "neon",
+            "aurora",
+            "particle",
+            "glass",
+            "echo"
+          ],
+          "description": "Type of ripple effect: 'default' | 'aurora' | 'particle' | 'glass' | 'neon' | 'echo'"
+        },
+        "rippleClassName": {
+          "kind": "string",
+          "description": "Custom class name for ripple styling"
+        },
+        "rippleScale": {
+          "kind": "number",
+          "description": "Scale multiplier for ripple expansion (default: 10)"
+        },
+        "showReflection": {
+          "kind": "boolean",
+          "description": "Whether to show the glass reflection effect (default: true)"
+        }
+      }
+    },
+    "Card": {
+      "role": "container",
+      "description": "Bounded panel with optional header. Children are spec nodes.",
+      "props": {
+        "title": {
+          "kind": "text",
+          "description": "Card header title"
+        },
+        "subtitle": {
+          "kind": "text",
+          "description": "Card header subtitle"
+        }
+      }
+    },
+    "ComboChart": {
+      "role": "leaf",
+      "description": "Combined bar+line chart — per-series type via config[key].type (auto Card shell).",
+      "props": {
+        "config": {
+          "kind": "shape",
+          "shape": "chartConfig",
+          "required": true
+        },
+        "curved": {
+          "kind": "boolean"
+        },
+        "curveType": {
+          "kind": "enum",
+          "options": [
+            "linear",
+            "monotone"
+          ]
+        },
+        "showDots": {
+          "kind": "boolean"
+        },
+        "categoryGap": {
+          "kind": "number"
+        },
+        "showDualAxis": {
+          "kind": "boolean"
+        },
+        "showValidationWarnings": {
+          "kind": "boolean"
+        },
+        "data": {
+          "kind": "shape",
+          "shape": "chartData",
+          "required": true
+        },
+        "width": {
+          "kind": "union",
+          "types": [
+            "number",
+            "string"
+          ]
+        },
+        "height": {
+          "kind": "union",
+          "types": [
+            "number",
+            "string"
+          ]
+        },
+        "enableKeyboardNavigation": {
+          "kind": "boolean"
+        },
+        "showGrid": {
+          "kind": "boolean"
+        },
+        "showXAxis": {
+          "kind": "boolean"
+        },
+        "showYAxis": {
+          "kind": "boolean"
+        },
+        "legend": {
+          "kind": "enum",
+          "options": [
+            "top",
+            "bottom",
+            "none"
+          ],
+          "description": "Always-visible legend position, rendered from `config`'s labels/colors."
+        },
+        "minValue": {
+          "kind": "number"
+        },
+        "maxValue": {
+          "kind": "number"
+        },
+        "variant": {
+          "kind": "enum",
+          "options": [
+            "default",
+            "minimal",
+            "gradient"
+          ]
+        },
+        "stacked": {
+          "kind": "boolean"
+        },
+        "barRadius": {
+          "kind": "number"
+        },
+        "dotRadius": {
+          "kind": "number"
+        },
+        "cellRadius": {
+          "kind": "number"
+        },
+        "radius": {
+          "kind": "number"
+        },
+        "strokeWidth": {
+          "kind": "number"
+        },
+        "gap": {
+          "kind": "number"
+        },
+        "fillOpacity": {
+          "kind": "number"
+        },
+        "showStroke": {
+          "kind": "boolean"
+        },
+        "title": {
+          "kind": "text",
+          "description": "Card header title (the auto shell)"
+        },
+        "subtitle": {
+          "kind": "text",
+          "description": "Card header subtitle (the auto shell)"
+        }
+      }
+    },
+    "DescriptionList": {
+      "role": "leaf",
+      "description": "Label/value pairs driven by a serializable items array.",
+      "props": {
+        "variant": {
+          "kind": "enum",
+          "options": [
+            "vertical",
+            "horizontal"
+          ],
+          "description": "Layout variant: \"horizontal\" (default) or \"vertical\""
+        },
+        "padding": {
+          "kind": "enum",
+          "options": [
+            "default",
+            "flush"
+          ],
+          "description": "Edge padding behavior. `flush` (default) removes the item side padding so"
+        },
+        "items": {
+          "kind": "shape",
+          "shape": "descriptionListItems",
+          "description": "Data-driven items. When provided, the list renders from this array and any"
+        }
+      }
+    },
+    "DonutChart": {
+      "role": "leaf",
+      "description": "Donut/radial chart (auto Card shell).",
+      "props": {
+        "variant": {
+          "kind": "enum",
+          "options": [
+            "solid",
+            "segmented"
+          ],
+          "default": "solid",
+          "description": "Visual variant for the donut chart (solid or segmented)"
+        },
+        "percentage": {
+          "kind": "number",
+          "required": true,
+          "description": "Percentage value to display (0-100)"
+        },
+        "label": {
+          "kind": "text",
+          "description": "Custom label to display in center"
+        },
+        "subtitle": {
+          "kind": "text",
+          "description": "Subtitle text to display below the main label"
+        },
+        "size": {
+          "kind": "union",
+          "types": [
+            "number",
+            "string"
+          ],
+          "default": 200,
+          "description": "Size of the donut chart"
+        },
+        "thickness": {
+          "kind": "number",
+          "default": 2,
+          "description": "Thickness of the donut stroke"
+        },
+        "segmentCount": {
+          "kind": "number",
+          "default": 32,
+          "description": "Total number of segments when using the segmented variant"
+        },
+        "segmentGap": {
+          "kind": "number",
+          "default": 0.35,
+          "description": "Fraction of each segment kept empty to create spacing (0-0.8)"
+        },
+        "showAnimation": {
+          "kind": "boolean",
+          "default": true,
+          "description": "Whether to show entrance animation"
+        },
+        "colors": {
+          "kind": "shape",
+          "shape": "donutColors",
+          "description": "Color configuration for the chart"
+        },
+        "title": {
+          "kind": "text",
+          "description": "Card header title (the auto shell)"
+        }
+      }
+    },
+    "Empty": {
+      "role": "leaf",
+      "description": "Empty-state placeholder with icon, title and subtitle.",
+      "props": {
+        "title": {
+          "kind": "text",
+          "description": "Primary title/heading text"
+        },
+        "subtitle": {
+          "kind": "text",
+          "description": "Subtitle text explaining the empty state"
+        },
+        "image": {
+          "kind": "string",
+          "description": "Optional image source for illustration "
+        },
+        "imageAlt": {
+          "kind": "string",
+          "description": "Alt text for the image (required if image is provided)"
+        },
+        "icon": {
+          "kind": "icon",
+          "description": "Optional icon component (displayed only when no image is provided)"
+        }
+      }
+    },
+    "Feed": {
+      "role": "leaf",
+      "description": "Activity feed driven by a serializable items array.",
+      "props": {
+        "items": {
+          "kind": "shape",
+          "shape": "feedItems",
+          "description": "Data-driven items. When provided, the feed renders from this array and any"
+        },
+        "collapseAfter": {
+          "kind": "number",
+          "description": "When set with `items`, items beyond this count are wrapped in a"
+        }
+      }
+    },
+    "Grid": {
+      "role": "container",
+      "description": "Responsive CSS-grid container. Children are spec nodes.",
+      "props": {
+        "as": {
+          "kind": "enum",
+          "options": [
+            "div",
+            "ul",
+            "ol",
+            "nav",
+            "section",
+            "header",
+            "footer",
+            "aside",
+            "form",
+            "fieldset"
+          ],
+          "default": "div",
+          "description": "Render as a different tag — e.g. `as=\"ul\"` for a card grid that should be"
+        },
+        "cols": {
+          "kind": "shape",
+          "shape": "gridCols",
+          "default": 1,
+          "description": "Columns: a number (mobile-safe auto-ramp) or a per-breakpoint map."
+        },
+        "gap": {
+          "kind": "enum",
+          "options": [
+            0,
+            1,
+            2,
+            3,
+            4,
+            5,
+            6,
+            8,
+            10,
+            12
+          ],
+          "default": 4,
+          "description": "Gap between grid cells (Tailwind spacing scale → gap-N)."
+        },
+        "flow": {
+          "kind": "enum",
+          "options": [
+            "row",
+            "col",
+            "dense"
+          ],
+          "description": "Grid auto-flow direction."
+        },
+        "align": {
+          "kind": "enum",
+          "options": [
+            "start",
+            "center",
+            "end",
+            "stretch"
+          ],
+          "description": "align-items within cells."
+        },
+        "justify": {
+          "kind": "enum",
+          "options": [
+            "start",
+            "center",
+            "end",
+            "between"
+          ],
+          "description": "justify-content of tracks."
+        }
+      }
+    },
+    "KPI": {
+      "role": "leaf",
+      "description": "KPI stat with trend and progress bar (auto Card shell).",
+      "props": {
+        "value": {
+          "kind": "text",
+          "required": true,
+          "description": "The main metric value to display (e.g. \"$25.5M\", \"1,234\", \"89%\")"
+        },
+        "label": {
+          "kind": "text",
+          "description": "Label describing the metric (e.g. \"Fund raised\", \"Total Revenue\")"
+        },
+        "trend": {
+          "kind": "number",
+          "description": "Percentage change value (e.g. 20, -5.3). Determines trend direction & color."
+        },
+        "trendLabel": {
+          "kind": "text",
+          "description": "Custom trend label override (default: auto-formats as \"+20%\" or \"-5.3%\")"
+        },
+        "progress": {
+          "kind": "number",
+          "description": "Progress value from 0-100. Controls how many bars are filled."
+        },
+        "barCount": {
+          "kind": "number",
+          "default": 24,
+          "description": "Total number of bars in the visualization."
+        },
+        "subtitle": {
+          "kind": "text",
+          "description": "Subtitle text below the bars (e.g. \"Compared to last month\")"
+        },
+        "icon": {
+          "kind": "icon",
+          "description": "Icon to display before the label."
+        },
+        "size": {
+          "kind": "enum",
+          "options": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "default": "md",
+          "description": "Size variant."
+        },
+        "color": {
+          "kind": "enum",
+          "options": [
+            "neutral",
+            "primary",
+            "success",
+            "warning",
+            "danger"
+          ],
+          "default": "primary",
+          "description": "Color for the filled bars and positive trend."
+        }
+      }
+    },
+    "LineChart": {
+      "role": "leaf",
+      "description": "Line chart (auto Card shell + shared-height container).",
+      "props": {
+        "color": {
+          "kind": "enum",
+          "options": [
+            "primary",
+            "success",
+            "warning",
+            "danger"
+          ]
+        },
+        "dotRadius": {
+          "kind": "number"
+        },
+        "radius": {
+          "kind": "number"
+        },
+        "strokeWidth": {
+          "kind": "number"
+        },
+        "curved": {
+          "kind": "boolean"
+        },
+        "curveType": {
+          "kind": "enum",
+          "options": [
+            "linear",
+            "monotone"
+          ]
+        },
+        "showDots": {
+          "kind": "boolean"
+        },
+        "data": {
+          "kind": "shape",
+          "shape": "chartData",
+          "required": true
+        },
+        "config": {
+          "kind": "shape",
+          "shape": "chartConfig",
+          "required": true
+        },
+        "width": {
+          "kind": "union",
+          "types": [
+            "number",
+            "string"
+          ]
+        },
+        "height": {
+          "kind": "union",
+          "types": [
+            "number",
+            "string"
+          ]
+        },
+        "enableKeyboardNavigation": {
+          "kind": "boolean"
+        },
+        "showGrid": {
+          "kind": "boolean"
+        },
+        "showXAxis": {
+          "kind": "boolean"
+        },
+        "showYAxis": {
+          "kind": "boolean"
+        },
+        "legend": {
+          "kind": "enum",
+          "options": [
+            "top",
+            "bottom",
+            "none"
+          ],
+          "description": "Always-visible legend position, rendered from `config`'s labels/colors."
+        },
+        "minValue": {
+          "kind": "number"
+        },
+        "maxValue": {
+          "kind": "number"
+        },
+        "title": {
+          "kind": "text",
+          "description": "Card header title (the auto shell)"
+        },
+        "subtitle": {
+          "kind": "text",
+          "description": "Card header subtitle (the auto shell)"
+        }
+      }
+    },
+    "Metric": {
+      "role": "leaf",
+      "description": "Single business metric with optional icon and trend.",
+      "props": {
+        "value": {
+          "kind": "union",
+          "types": [
+            "number",
+            "string"
+          ],
+          "required": true,
+          "description": "The main value to display (number or formatted string)"
+        },
+        "label": {
+          "kind": "text",
+          "required": true,
+          "description": "Label describing the metric"
+        },
+        "subtitle": {
+          "kind": "text",
+          "description": "Optional subtitle or secondary text"
+        },
+        "trendValue": {
+          "kind": "text",
+          "description": "Trend value to display (e.g., \"+10.34%\", \"-5.2%\")"
+        },
+        "trendDirection": {
+          "kind": "enum",
+          "options": [
+            "up",
+            "down"
+          ],
+          "default": "up",
+          "description": "Trend direction - determines icon and color"
+        },
+        "size": {
+          "kind": "enum",
+          "options": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "default": "md",
+          "description": "Size variant"
+        },
+        "variant": {
+          "kind": "enum",
+          "options": [
+            "filled",
+            "ghost"
+          ],
+          "default": "filled",
+          "description": "Visual style variant"
+        },
+        "color": {
+          "kind": "enum",
+          "options": [
+            "neutral",
+            "primary",
+            "success",
+            "warning",
+            "danger"
+          ],
+          "default": "primary",
+          "description": "Semantic color for icon and accents"
+        },
+        "icon": {
+          "kind": "icon",
+          "description": "Optional icon to display"
+        }
+      }
+    },
+    "PageHeading": {
+      "role": "leaf",
+      "description": "Page header with title/subtitle (managed slot form — header only).",
+      "props": {
+        "title": {
+          "kind": "text",
+          "description": "Heading title (serializable slot). Setting any slot-prop"
+        },
+        "subtitle": {
+          "kind": "text",
+          "description": "Secondary line under the title (serializable slot)."
+        },
+        "separator": {
+          "kind": "boolean",
+          "default": true,
+          "description": "Show bottom separator."
+        }
+      }
+    },
+    "Pill": {
+      "role": "leaf",
+      "description": "Filter/tag chip with optional selected state.",
+      "props": {
+        "children": {
+          "kind": "text",
+          "required": true,
+          "description": "Content to display inside the pill"
+        },
+        "size": {
+          "kind": "enum",
+          "options": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "description": "Size of the pill"
+        },
+        "iconStart": {
+          "kind": "icon",
+          "description": "Icon element to display at the start (before the content)"
+        },
+        "selected": {
+          "kind": "boolean",
+          "description": "Whether the pill is selected (controlled state)"
+        },
+        "readOnly": {
+          "kind": "boolean",
+          "default": false,
+          "description": "Whether the pill is read-only (non-interactive)"
+        }
+      }
+    },
+    "Progress": {
+      "role": "leaf",
+      "description": "Progress bar (0–100).",
+      "props": {
+        "value": {
+          "kind": "number",
+          "description": "Progress value from 0 to 100."
+        },
+        "size": {
+          "kind": "enum",
+          "options": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "default": "md",
+          "description": "The size of the progress bar"
+        },
+        "showLabel": {
+          "kind": "boolean",
+          "default": false,
+          "description": "Whether to show the percentage label"
+        },
+        "labelPosition": {
+          "kind": "enum",
+          "options": [
+            "top",
+            "bottom",
+            "right",
+            "inside"
+          ],
+          "default": "right",
+          "description": "Position of the label"
+        },
+        "animated": {
+          "kind": "boolean",
+          "default": true,
+          "description": "Whether to animate value changes"
+        }
+      }
+    },
+    "Rating": {
+      "role": "leaf",
+      "description": "Read-only star rating display.",
+      "props": {
+        "value": {
+          "kind": "number",
+          "description": "Controlled rating value (0 to max)"
+        },
+        "defaultValue": {
+          "kind": "number",
+          "default": 0,
+          "description": "Default rating value for uncontrolled mode (0 to max)"
+        },
+        "max": {
+          "kind": "number",
+          "default": 5,
+          "description": "Maximum number of stars"
+        },
+        "size": {
+          "kind": "enum",
+          "options": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "default": "md",
+          "description": "The size of the rating stars"
+        },
+        "color": {
+          "kind": "enum",
+          "options": [
+            "primary",
+            "success",
+            "warning",
+            "danger"
+          ],
+          "default": "warning",
+          "description": "The semantic color of the filled stars"
+        },
+        "readOnly": {
+          "kind": "boolean",
+          "default": false,
+          "description": "Whether the rating is read-only (display only, no interaction)"
+        },
+        "disabled": {
+          "kind": "boolean",
+          "default": false,
+          "description": "Whether the rating is disabled"
+        },
+        "allowHalf": {
+          "kind": "boolean",
+          "default": false,
+          "description": "Enable half-step rating increments"
+        }
+      }
+    },
+    "Section": {
+      "role": "container",
+      "description": "Titled page region without card chrome. Children are spec nodes.",
+      "props": {
+        "title": {
+          "kind": "text",
+          "description": "Section heading."
+        },
+        "subtitle": {
+          "kind": "text",
+          "description": "Secondary line under the title."
+        },
+        "gap": {
+          "kind": "enum",
+          "options": [
+            0,
+            1,
+            2,
+            3,
+            4,
+            5,
+            6,
+            8,
+            10,
+            12
+          ],
+          "default": 4,
+          "description": "Spacing between the header and the body (Tailwind spacing scale → mt-N)."
+        }
+      }
+    },
+    "Separator": {
+      "role": "leaf",
+      "description": "Horizontal or vertical divider.",
+      "props": {
+        "vertical": {
+          "kind": "boolean",
+          "default": false,
+          "description": "Whether the separator is vertical (default is horizontal)"
+        },
+        "margin": {
+          "kind": "enum",
+          "options": [
+            "sm",
+            "md",
+            "lg"
+          ],
+          "default": "md",
+          "description": "The margin size for spacing"
+        }
+      }
+    },
+    "Stack": {
+      "role": "container",
+      "description": "Flex container (column by default). Children are spec nodes.",
+      "props": {
+        "as": {
+          "kind": "enum",
+          "options": [
+            "div",
+            "ul",
+            "ol",
+            "nav",
+            "section",
+            "header",
+            "footer",
+            "aside",
+            "form",
+            "fieldset"
+          ],
+          "default": "div",
+          "description": "Render as a different tag — e.g. `as=\"nav\"` for a stack of nav links, or"
+        },
+        "direction": {
+          "kind": "enum",
+          "options": [
+            "row",
+            "col"
+          ],
+          "default": "col",
+          "description": "Flex direction."
+        },
+        "gap": {
+          "kind": "enum",
+          "options": [
+            0,
+            1,
+            2,
+            3,
+            4,
+            5,
+            6,
+            8,
+            10,
+            12
+          ],
+          "default": 4,
+          "description": "Gap between items (Tailwind spacing scale → gap-N)."
+        },
+        "align": {
+          "kind": "enum",
+          "options": [
+            "start",
+            "center",
+            "end",
+            "stretch"
+          ],
+          "description": "align-items."
+        },
+        "justify": {
+          "kind": "enum",
+          "options": [
+            "start",
+            "center",
+            "end",
+            "between"
+          ],
+          "description": "justify-content."
+        },
+        "wrap": {
+          "kind": "boolean",
+          "description": "Allow items to wrap."
+        }
+      }
+    },
+    "StackedBarChart": {
+      "role": "leaf",
+      "description": "Stacked bar chart (auto Card shell + shared-height container).",
+      "props": {
+        "barRadius": {
+          "kind": "number"
+        },
+        "gap": {
+          "kind": "number"
+        },
+        "categoryGap": {
+          "kind": "number"
+        },
+        "stackOffset": {
+          "kind": "enum",
+          "options": [
+            "none",
+            "expand",
+            "wiggle",
+            "silhouette"
+          ]
+        },
+        "showAnimation": {
+          "kind": "boolean"
+        },
+        "showValidationWarnings": {
+          "kind": "boolean"
+        },
+        "data": {
+          "kind": "shape",
+          "shape": "chartData",
+          "required": true
+        },
+        "config": {
+          "kind": "shape",
+          "shape": "chartConfig",
+          "required": true
+        },
+        "width": {
+          "kind": "union",
+          "types": [
+            "number",
+            "string"
+          ]
+        },
+        "height": {
+          "kind": "union",
+          "types": [
+            "number",
+            "string"
+          ]
+        },
+        "enableKeyboardNavigation": {
+          "kind": "boolean"
+        },
+        "showGrid": {
+          "kind": "boolean"
+        },
+        "showXAxis": {
+          "kind": "boolean"
+        },
+        "showYAxis": {
+          "kind": "boolean"
+        },
+        "legend": {
+          "kind": "enum",
+          "options": [
+            "top",
+            "bottom",
+            "none"
+          ],
+          "description": "Always-visible legend position, rendered from `config`'s labels/colors."
+        },
+        "minValue": {
+          "kind": "number"
+        },
+        "maxValue": {
+          "kind": "number"
+        },
+        "variant": {
+          "kind": "enum",
+          "options": [
+            "default",
+            "minimal",
+            "gradient"
+          ]
+        },
+        "dotRadius": {
+          "kind": "number"
+        },
+        "cellRadius": {
+          "kind": "number"
+        },
+        "radius": {
+          "kind": "number"
+        },
+        "strokeWidth": {
+          "kind": "number"
+        },
+        "curved": {
+          "kind": "boolean"
+        },
+        "curveType": {
+          "kind": "enum",
+          "options": [
+            "linear",
+            "monotone",
+            "step",
+            "stepBefore",
+            "stepAfter"
+          ]
+        },
+        "showDots": {
+          "kind": "boolean"
+        },
+        "fillOpacity": {
+          "kind": "number"
+        },
+        "showStroke": {
+          "kind": "boolean"
+        },
+        "stacked": {
+          "kind": "boolean"
+        },
+        "orientation": {
+          "kind": "enum",
+          "options": [
+            "vertical",
+            "horizontal"
+          ]
+        },
+        "title": {
+          "kind": "text",
+          "description": "Card header title (the auto shell)"
+        },
+        "subtitle": {
+          "kind": "text",
+          "description": "Card header subtitle (the auto shell)"
+        }
+      }
+    },
+    "Table": {
+      "role": "leaf",
+      "description": "Data table (auto Card shell, flush padding). `cellType:\"badge\"` columns render status badges.",
+      "props": {
+        "data": {
+          "kind": "shape",
+          "shape": "tableData",
+          "description": "Array of data objects to display - required for data-driven API"
+        },
+        "columns": {
+          "kind": "shape",
+          "shape": "tableColumns",
+          "description": "Column definitions for data display and behavior - required for data-driven API"
+        },
+        "variant": {
+          "kind": "enum",
+          "options": [
+            "default",
+            "striped",
+            "bordered",
+            "compact"
+          ],
+          "description": "Visual variant for different table styles"
+        },
+        "padding": {
+          "kind": "enum",
+          "options": [
+            "default",
+            "flush"
+          ],
+          "default": "default",
+          "description": "Edge padding behavior. `flush` removes left padding from the first cell and right padding"
+        },
+        "freezeHeader": {
+          "kind": "boolean",
+          "description": "Keep header visible when scrolling vertically"
+        },
+        "freezeFirstColumn": {
+          "kind": "boolean",
+          "description": "Keep first column visible when scrolling horizontally"
+        },
+        "freezeLastColumn": {
+          "kind": "boolean",
+          "description": "Keep last column visible when scrolling horizontally"
+        },
+        "sortable": {
+          "kind": "boolean",
+          "description": "Enable sorting functionality for sortable columns"
+        },
+        "filterable": {
+          "kind": "boolean",
+          "description": "Enable filtering functionality for filterable columns"
+        },
+        "filterLogic": {
+          "kind": "enum",
+          "options": [
+            "and",
+            "or"
+          ],
+          "description": "Logic for combining multiple filters (default: 'and')"
+        },
+        "enableBuiltInFilter": {
+          "kind": "boolean",
+          "description": "Enable built-in automatic data filtering (opt-in). When true, the table filters data internally."
+        },
+        "expandable": {
+          "kind": "boolean"
+        },
+        "selectable": {
+          "kind": "boolean"
+        },
+        "selectionType": {
+          "kind": "enum",
+          "options": [
+            "checkbox",
+            "radio"
+          ]
+        },
+        "showColumnManager": {
+          "kind": "boolean"
+        },
+        "caption": {
+          "kind": "text",
+          "description": "Optional accessible caption for the table, rendered as a visually-hidden <caption> element"
+        },
+        "title": {
+          "kind": "text",
+          "description": "Card header title (the auto shell)"
+        },
+        "subtitle": {
+          "kind": "text",
+          "description": "Card header subtitle (the auto shell)"
+        },
+        "rowKey": {
+          "kind": "string",
+          "description": "Row field that uniquely identifies a row",
+          "required": true
+        }
+      }
+    },
+    "Tag": {
+      "role": "leaf",
+      "description": "Compact label chip.",
+      "props": {
+        "children": {
+          "kind": "text",
+          "required": true,
+          "description": "The content of the tag"
+        },
+        "size": {
+          "kind": "enum",
+          "options": [
+            "sm",
+            "md"
+          ],
+          "description": "The size of the tag"
+        },
+        "removable": {
+          "kind": "boolean",
+          "description": "Whether to show the remove button (default: true)"
+        },
+        "disabled": {
+          "kind": "boolean",
+          "description": "Whether the tag is disabled"
+        },
+        "animated": {
+          "kind": "boolean",
+          "description": "Whether to render with motion (layout + enter/exit animation). Default true."
+        }
+      }
+    },
+    "Timeline": {
+      "role": "leaf",
+      "description": "Event timeline driven by a serializable items array.",
+      "props": {
+        "layout": {
+          "kind": "enum",
+          "options": [
+            "vertical",
+            "horizontal"
+          ],
+          "default": "vertical",
+          "description": "Layout orientation of the timeline"
+        },
+        "items": {
+          "kind": "shape",
+          "shape": "timelineItems",
+          "description": "Data-driven items. When provided, the timeline renders from this array and"
+        }
+      }
+    }
+  },
+  "shapes": {
+    "gridCols": {
+      "description": "Column count: a number 1–12 (expands through a mobile-first responsive ramp — 3 is NOT 3 columns on mobile) OR an explicit per-breakpoint map like { base: 1, md: 2, lg: 3 }.",
+      "oneOf": [
+        {
+          "type": "number",
+          "minimum": 1,
+          "maximum": 12
+        },
+        {
+          "type": "object",
+          "additionalProperties": {
+            "type": "number"
+          },
+          "propertyNames": {
+            "enum": [
+              "base",
+              "sm",
+              "md",
+              "lg",
+              "xl",
+              "2xl"
+            ]
+          }
+        }
+      ]
+    },
+    "chartData": {
+      "description": "Array of data points. Each point: one label key (e.g. name/month) plus numeric series keys.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "example": {
+          "name": "Jan",
+          "value": 42
+        }
+      }
+    },
+    "chartConfig": {
+      "description": "seriesKey → { label?, color?, type? }. Colors are CSS values; prefer var(--color-primary) etc. `type: 'bar' | 'line'` applies to ComboChart only.",
+      "type": "object",
+      "example": {
+        "value": {
+          "label": "Signups",
+          "color": "var(--color-primary)"
+        }
+      }
+    },
+    "colorList": {
+      "description": "Array of CSS color strings.",
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "donutColors": {
+      "description": "DonutChart color config object or CSS color strings.",
+      "type": "object"
+    },
+    "tableData": {
+      "description": "Array of row records. Values must be serializable (string/number/boolean/null).",
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    },
+    "tableColumns": {
+      "description": "Array of column defs: { id, header, accessor } all strings & required; optional cellType: \"badge\" renders a color-mapped status Badge; optional colors maps cell value → semantic color.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "id",
+          "header",
+          "accessor"
+        ],
+        "properties": {
+          "id": {
+            "type": "string"
+          },
+          "header": {
+            "type": "string"
+          },
+          "accessor": {
+            "type": "string"
+          },
+          "cellType": {
+            "enum": [
+              "badge"
+            ]
+          },
+          "colors": {
+            "type": "object",
+            "additionalProperties": {
+              "enum": [
+                "primary",
+                "success",
+                "warning",
+                "danger",
+                "neutral",
+                "dark"
+              ]
+            }
+          }
+        }
+      }
+    },
+    "timelineItems": {
+      "description": "Array of { status?, title?, description?, timestamp? } — all strings.",
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    },
+    "descriptionListItems": {
+      "description": "Array of { label, value } — both strings.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "label",
+          "value"
+        ]
+      }
+    },
+    "feedItems": {
+      "description": "Array of { timestamp?, icon? } — strings; icon is a NAME from the icon set.",
+      "type": "array",
+      "items": {
+        "type": "object"
+      }
+    },
+    "breadcrumbItems": {
+      "description": "Array of { label } (required string) plus optional href (string). The last item with no href is the current page. Per-item icons are not supported.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "label"
+        ],
+        "properties": {
+          "label": {
+            "type": "string"
+          },
+          "href": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "avatarList": {
+      "description": "Array of { src?, name? } — both strings (serializable AvatarProps subset). name drives the initials fallback.",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "src": {
+            "type": "string"
+          },
+          "name": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "accordionItems": {
+      "description": "Array of { value, title } (both required strings) plus optional content (string).",
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "value",
+          "title"
+        ],
+        "properties": {
+          "value": {
+            "type": "string"
+          },
+          "title": {
+            "type": "string"
+          },
+          "content": {
+            "type": "string"
+          }
+        }
+      }
+    }
+  },
+  "examples": [
+    {
+      "component": "Stack",
+      "props": {
+        "gap": 4
+      },
+      "children": [
+        {
+          "component": "Grid",
+          "props": {
+            "cols": 3,
+            "gap": 4
+          },
+          "children": [
+            {
+              "component": "Metric",
+              "props": {
+                "value": "$182,000",
+                "label": "Total Revenue",
+                "trendValue": "+12%",
+                "trendDirection": "up",
+                "icon": "CurrencyDollar",
+                "color": "success",
+                "variant": "filled"
+              }
+            }
+          ]
+        },
+        {
+          "component": "Card",
+          "props": {
+            "title": "New Signups"
+          },
+          "children": [
+            {
+              "component": "AreaChart",
+              "props": {
+                "data": [
+                  {
+                    "name": "Jan",
+                    "value": 42
+                  },
+                  {
+                    "name": "Feb",
+                    "value": 61
+                  }
+                ],
+                "config": {
+                  "value": {
+                    "label": "Signups",
+                    "color": "var(--color-primary)"
+                  }
+                }
+              }
+            }
+          ]
+        },
+        {
+          "component": "Table",
+          "props": {
+            "title": "Recent Orders",
+            "rowKey": "id",
+            "data": [
+              {
+                "id": "#4821",
+                "customer": "Acme Co.",
+                "amount": "$1,240",
+                "status": "Paid"
+              }
+            ],
+            "columns": [
+              {
+                "id": "id",
+                "header": "Order",
+                "accessor": "id"
+              },
+              {
+                "id": "status",
+                "header": "Status",
+                "accessor": "status",
+                "cellType": "badge"
+              }
+            ]
+          },
+          "actions": {
+            "rowClick": {
+              "type": "select-order"
+            }
+          }
+        }
+      ]
+    }
+  ]
+}