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

package/dist/tools.json

@@ -0,0 +1,2154 @@
+{
+  "tools": [
+    {
+      "name": "render_ui",
+      "description": "Render a UI from FlikkUI components. Emit a recursive UINode spec: containers (Grid/Stack/Section/Card) take children; leaves take serializable props only. Icons are NAMES from the closed icon set. Follow the per-component contracts.",
+      "input_schema": {
+        "type": "object",
+        "properties": {
+          "spec": {
+            "$ref": "#/$defs/UINode"
+          }
+        },
+        "required": [
+          "spec"
+        ],
+        "$defs": {
+          "UINode": {
+            "type": "object",
+            "properties": {
+              "component": {
+                "type": "string",
+                "enum": [
+                  "Accordion",
+                  "Alert",
+                  "AreaChart",
+                  "Avatar",
+                  "AvatarGroup",
+                  "Badge",
+                  "BarChart",
+                  "Breadcrumbs",
+                  "Button",
+                  "Card",
+                  "ComboChart",
+                  "DescriptionList",
+                  "DonutChart",
+                  "Empty",
+                  "Feed",
+                  "Grid",
+                  "KPI",
+                  "LineChart",
+                  "Metric",
+                  "PageHeading",
+                  "Pill",
+                  "Progress",
+                  "Rating",
+                  "Section",
+                  "Separator",
+                  "Stack",
+                  "StackedBarChart",
+                  "Table",
+                  "Tag",
+                  "Timeline"
+                ]
+              },
+              "props": {
+                "type": "object"
+              },
+              "children": {
+                "type": "array",
+                "items": {
+                  "$ref": "#/$defs/UINode"
+                }
+              },
+              "id": {
+                "type": "string"
+              },
+              "sizeHint": {
+                "type": "object",
+                "description": "Optional height hint (px or CSS size) so streaming skeletons reserve the right space.",
+                "properties": {
+                  "height": {
+                    "type": [
+                      "number",
+                      "string"
+                    ]
+                  }
+                }
+              },
+              "actions": {
+                "type": "object",
+                "description": "Named interactions: { click: { type, payload? } } on Button/leaves; { rowClick: { type, payload? } } on Table (the clicked row arrives as dispatch context). Fully serializable.",
+                "additionalProperties": {
+                  "type": "object",
+                  "properties": {
+                    "type": {
+                      "type": "string"
+                    },
+                    "payload": {}
+                  },
+                  "required": [
+                    "type"
+                  ]
+                }
+              }
+            },
+            "required": [
+              "component"
+            ],
+            "additionalProperties": false
+          }
+        }
+      },
+      "contracts": {
+        "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"
+            }
+          }
+        }
+      },
+      "icons": [
+        "ArrowTrendingUp",
+        "Bolt",
+        "Briefcase",
+        "ChartBar",
+        "ChatBubbleLeftRight",
+        "CheckCircle",
+        "CurrencyDollar",
+        "ExclamationTriangle",
+        "Globe",
+        "PencilSquare",
+        "RocketLaunch",
+        "ShoppingCart",
+        "UserPlus",
+        "Users"
+      ],
+      "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"
+                }
+              }
+            }
+          ]
+        }
+      ]
+    }
+  ]
+}