@sky.ui/mcp 0.0.1 → 0.0.2

package/data/theme-authoring-contract.json

@@ -1,598 +1,598 @@
-{
-  "schemaVersion": "1.0",
-  "themeProperty": "userTheme",
-  "typescriptType": "Partial<import(\"@sky.ui/core/sky-theme-provider\").ThemeConfig> or inline Partial<ThemeConfig>",
-  "providerElement": "sky-theme-provider",
-  "mergeRules": {
-    "strategy": "deepMergePerMode",
-    "description": "userTheme.light is deep-merged with defaultTheme.light; userTheme.dark with defaultTheme.dark. Omitted keys keep package defaults. Active mode (light|dark) selects which ThemeModeConfig is expanded into --sky-* variables."
-  },
-  "agentWorkflow": [
-    "1) Parse the user's goals (e.g. brand color, calmer background, dense UI, rounder cards).",
-    "2) Map phrases to `fields[].id` using `naturalLanguageHooks` and `intentRouters` below.",
-    "3) Build a single JSON object: `{ \"light\": { ...ThemeModeConfig partial }, \"dark\": { ... } }` — only include keys the user changed.",
-    "4) Set `userTheme` on `sky-theme-provider` (or pass from `sky-theme-generator` `value` / `theme-change`).",
-    "5) Call get_theme with operation variables to list emitted `--sky-*` names; never invent new token names—only `userTheme` values change."
-  ],
-  "fields": [
-    {
-      "id": "color_background",
-      "group": "color",
-      "label": "Canvas / app background",
-      "summary": "Base page or shell background. Drives the main surface behind content.",
-      "paths": { "light": "light.color.background", "dark": "dark.color.background" },
-      "naturalLanguageHooks": [
-        "background",
-        "canvas",
-        "page color",
-        "app background",
-        "whiter",
-        "darker backdrop",
-        "softer background"
-      ],
-      "valueKind": "css_color",
-      "emitsVariables": ["--sky-background-color"],
-      "examplePatch": {
-        "light": { "color": { "background": "#f4f6f8" } },
-        "dark": { "color": { "background": "#0c0e12" } }
-      }
-    },
-    {
-      "id": "color_foreground",
-      "group": "color",
-      "label": "Default text / foreground",
-      "summary": "Primary body and UI text color. Many secondary text tokens are mixed from this.",
-      "paths": { "light": "light.color.foreground", "dark": "dark.color.foreground" },
-      "naturalLanguageHooks": [
-        "text color",
-        "body text",
-        "default text",
-        "readability",
-        "foreground",
-        "primary text"
-      ],
-      "valueKind": "css_color",
-      "emitsVariables": ["--sky-text-primary", "--sky-text-secondary" ],
-      "examplePatch": {
-        "light": { "color": { "foreground": "#0f172a" } },
-        "dark": { "color": { "foreground": "#e8eaef" } }
-      }
-    },
-    {
-      "id": "color_active",
-      "group": "color",
-      "label": "Brand / active / primary accent",
-      "summary": "Main interactive and brand color: links, primary buttons, focus ring base, active-* semantic scale.",
-      "paths": { "light": "light.color.active", "dark": "dark.color.active" },
-      "naturalLanguageHooks": [
-        "brand",
-        "primary",
-        "accent",
-        "CTA",
-        "link color",
-        "active color",
-        "button color",
-        "main color",
-        "corporate"
-      ],
-      "valueKind": "css_color",
-      "emitsVariables": [
-        "--sky-active-primary",
-        "--sky-active-*",
-        "--sky-focus-ring",
-        "--sky-ring-active-*"
-      ],
-      "examplePatch": {
-        "light": { "color": { "active": "#0a6cff" } },
-        "dark": { "color": { "active": "#4b9aff" } }
-      }
-    },
-    {
-      "id": "color_success",
-      "group": "color",
-      "label": "Success / positive",
-      "summary": "Confirms, completed states, safe actions.",
-      "paths": { "light": "light.color.success", "dark": "dark.color.success" },
-      "naturalLanguageHooks": ["success", "ok", "positive", "green", "completed", "check"],
-      "valueKind": "css_color",
-      "emitsVariables": ["--sky-success-primary", "--sky-success-*"],
-      "examplePatch": {
-        "light": { "color": { "success": "#16a34a" } },
-        "dark": { "color": { "success": "#4ade80" } }
-      }
-    },
-    {
-      "id": "color_warning",
-      "group": "color",
-      "label": "Warning / caution",
-      "summary": "Non-fatal issues, needs attention without panic.",
-      "paths": { "light": "light.color.warning", "dark": "dark.color.warning" },
-      "naturalLanguageHooks": ["warning", "caution", "amber", "yellow", "attn"],
-      "valueKind": "css_color",
-      "emitsVariables": ["--sky-warning-primary", "--sky-warning-*"],
-      "examplePatch": {
-        "light": { "color": { "warning": "#d97706" } },
-        "dark": { "color": { "warning": "#fbbf24" } }
-      }
-    },
-    {
-      "id": "color_danger",
-      "group": "color",
-      "label": "Danger / destructive / error",
-      "summary": "Errors, delete, irreversible or critical actions.",
-      "paths": { "light": "light.color.danger", "dark": "dark.color.danger" },
-      "naturalLanguageHooks": [
-        "danger",
-        "error",
-        "red",
-        "delete",
-        "destructive",
-        "alert"
-      ],
-      "valueKind": "css_color",
-      "emitsVariables": ["--sky-danger-primary", "--sky-danger-*"],
-      "examplePatch": {
-        "light": { "color": { "danger": "#dc2626" } },
-        "dark": { "color": { "danger": "#f87171" } }
-      }
-    },
-    {
-      "id": "color_info",
-      "group": "color",
-      "label": "Informational accent",
-      "summary": "Neutral information emphasis (banners, tips), distinct from brand active.",
-      "paths": { "light": "light.color.info", "dark": "dark.color.info" },
-      "naturalLanguageHooks": ["info", "tip", "informational", "note", "blue help"],
-      "valueKind": "css_color",
-      "emitsVariables": ["--sky-info-primary", "--sky-info-*"],
-      "examplePatch": {
-        "light": { "color": { "info": "#0284c7" } },
-        "dark": { "color": { "info": "#38bdf8" } }
-      }
-    },
-    {
-      "id": "glass",
-      "group": "surface",
-      "label": "Translucent glass / frosted surface",
-      "summary": "Frosted panels, chips, floating surfaces: base tint (baseColor), optional explicit secondary/tertiary shades, and opacity steps (primary→solid). Not full-screen modals (see overlay).",
-      "pathRoot": { "light": "light.glass", "dark": "dark.glass" },
-      "naturalLanguageHooks": [
-        "frosted",
-        "glass",
-        "translucent",
-        "card blur",
-        "frosted panel",
-        "surface tint",
-        "frosted UI"
-      ],
-      "valueKind": "glass_config",
-      "emitsVariables": [
-        "--sky-glass-primary",
-        "--sky-glass-secondary",
-        "--sky-glass-tertiary",
-        "--sky-glass-solid"
-      ],
-      "examplePatch": {
-        "light": { "glass": { "baseColor": "#e8ecf2", "opacities": { "primary": 0.5, "secondary": 0.5, "tertiary": 0.5, "solid": 1 } } },
-        "dark": { "glass": { "baseColor": "#1a1f2a", "opacities": { "primary": 0.45, "secondary": 0.45, "tertiary": 0.45, "solid": 1 } } }
-      }
-    },
-    {
-      "id": "glass_surface_sheen",
-      "group": "surface",
-      "label": "Vertical glass sheen (gradient)",
-      "summary": "Top/bottom multipliers for large hero or panel `sky-glass-surface` vertical gradient. Optional: omit for flat glass only.",
-      "pathRoot": { "light": "light.glassSurface", "dark": "dark.glassSurface" },
-      "naturalLanguageHooks": ["gradient surface", "sheen", "hero", "tall panel glass", "glassy header"],
-      "valueKind": "object_top_bottom",
-      "emitsVariables": ["--sky-glass-surface"],
-      "examplePatch": {
-        "light": { "glassSurface": { "top": 0.18, "bottom": 0.05 } },
-        "dark": { "glassSurface": { "top": 0.2, "bottom": 0.04 } }
-      }
-    },
-    {
-      "id": "glass_hover",
-      "group": "surface",
-      "label": "Hover wash on surfaces",
-      "summary": "A dark/neutral color with opacity ladder for pointer-hover overlays on cards/tiles. Not a replacement for glass base.",
-      "pathRoot": { "light": "light.glassHover", "dark": "dark.glassHover" },
-      "naturalLanguageHooks": [
-        "hover on card",
-        "hover states",
-        "rollover",
-        "button hover wash",
-        "darker on hover"
-      ],
-      "valueKind": "hover_overlay_config",
-      "emitsVariables": ["--sky-hover-primary", "--sky-hover-secondary", "--sky-hover-tertiary", "--sky-hover-solid"],
-      "examplePatch": {
-        "light": { "glassHover": { "color": "#000000", "opacity": { "primary": 0.06, "secondary": 0.09, "tertiary": 0.12, "solid": 1 } } }
-      }
-    },
-    {
-      "id": "overlay",
-      "group": "overlay",
-      "label": "Scrim / modal / sheet backdrop",
-      "summary": "Full-screen or pane tint above content. Higher opacity than glass; used for modals, drawers, focus traps.",
-      "pathRoot": { "light": "light.overlay", "dark": "dark.overlay" },
-      "naturalLanguageHooks": [
-        "modal backdrop",
-        "overlay",
-        "scrim",
-        "dim the page",
-        "drawer underlay",
-        "screen tint"
-      ],
-      "valueKind": "overlay_config",
-      "emitsVariables": ["--sky-overlay-primary", "--sky-overlay-*"],
-      "examplePatch": {
-        "light": { "overlay": { "color": "#0f172a", "opacities": { "primary": 0.55, "secondary": 0.4, "tertiary": 0.2, "solid": 1 } } }
-      }
-    },
-    {
-      "id": "font_sans",
-      "group": "typography",
-      "label": "Default UI font (sans) stack",
-      "summary": "Applies to body and most UI; feeds semantic `sky-text-*` role shorthands.",
-      "paths": { "light": "light.fontFamily", "dark": "dark.fontFamily" },
-      "naturalLanguageHooks": ["font", "typeface", "sans", "Poppins", "Inter", "system font", "branding type"],
-      "valueKind": "font_stack",
-      "emitsVariables": ["--sky-font", "--sky-font-sans", "--sky-text-body"],
-      "examplePatch": {
-        "light": { "fontFamily": "'Inter', 'Segoe UI', system-ui, sans-serif" }
-      }
-    },
-    {
-      "id": "font_mono",
-      "group": "typography",
-      "label": "Monospace / code font stack",
-      "summary": "For code, data, and monospace presets (sky-font-mono-*).",
-      "paths": { "light": "light.fontFamilyMono", "dark": "dark.fontFamilyMono" },
-      "naturalLanguageHooks": [
-        "monospace",
-        "code font",
-        "Fira",
-        "JetBrains",
-        "terminal"
-      ],
-      "valueKind": "font_stack_optional",
-      "emitsVariables": ["--sky-font-mono", "--sky-font-mono-*"],
-      "examplePatch": {
-        "light": { "fontFamilyMono": "ui-monospace, 'Cascadia Code', monospace" }
-      }
-    },
-    {
-      "id": "font_size_scale",
-      "group": "typography",
-      "label": "Font size scale (record)",
-      "summary": "Map xs, sm, … 6xl to any CSS font-size. Drives `sky-font-size-*` and presets. Override individual keys, not the whole object unless you replace the scale entirely.",
-      "pathRoot": { "light": "light.fontSize", "dark": "dark.fontSize" },
-      "naturalLanguageHooks": [
-        "bigger type",
-        "larger text",
-        "type scale",
-        "heading sizes",
-        "compact text",
-        "tighter typography"
-      ],
-      "valueKind": "record_font_sizes",
-      "emitsVariables": ["--sky-font-size-*", "--sky-text-*"],
-      "examplePatch": {
-        "light": { "fontSize": { "md": "0.95rem", "lg": "1.125rem" } }
-      }
-    },
-    {
-      "id": "line_height_scale",
-      "group": "typography",
-      "label": "Line height scale (record)",
-      "summary": "Tight, snug, normal, relaxed, loose. Feeds `sky-line-height-*` and role shorthands.",
-      "pathRoot": { "light": "light.lineHeight", "dark": "dark.lineHeight" },
-      "naturalLanguageHooks": ["tighter lines", "line height", "looser lines", "leading"],
-      "valueKind": "record_line_heights",
-      "emitsVariables": ["--sky-line-height-*"],
-      "examplePatch": {
-        "light": { "lineHeight": { "normal": "1.5", "relaxed": "1.65" } }
-      }
-    },
-    {
-      "id": "font_weight_scale",
-      "group": "typography",
-      "label": "Font weight scale (record)",
-      "summary": "Named weights: thin, light, normal, medium, semibold, bold, extrabold. Used in role and preset composition.",
-      "pathRoot": { "light": "light.fontWeight", "dark": "dark.fontWeight" },
-      "naturalLanguageHooks": ["bolder", "heavier", "light weight", "weight scale"],
-      "valueKind": "record_weights",
-      "emitsVariables": ["--sky-font-weight-*"],
-      "examplePatch": {
-        "light": { "fontWeight": { "semibold": "650" } }
-      }
-    },
-    {
-      "id": "letter_spacing_scale",
-      "group": "typography",
-      "label": "Letter spacing (record)",
-      "summary": "Tighter, tight, normal, wide, wider – tracking for titles vs body.",
-      "pathRoot": { "light": "light.letterSpacing", "dark": "dark.letterSpacing" },
-      "naturalLanguageHooks": ["letter spacing", "tracking", "wide text"],
-      "valueKind": "record_letter_spacing",
-      "emitsVariables": ["--sky-letter-spacing-*"],
-      "examplePatch": {
-        "light": { "letterSpacing": { "tight": "-0.02em" } }
-      }
-    },
-    {
-      "id": "spacing_scale",
-      "group": "density",
-      "label": "Spacing / density (record of lengths)",
-      "summary": "Numeric scale keys (0, 1, 2, 4, …) become `--sky-space-{key}`; padding and gaps. Reduce values for dense admin UIs; increase for marketing/open layouts.",
-      "pathRoot": { "light": "light.spacing", "dark": "dark.spacing" },
-      "naturalLanguageHooks": [
-        "denser",
-        "compact",
-        "more padding",
-        "tighter layout",
-        "gaps",
-        "spacing scale",
-        "air",
-        "more whitespace"
-      ],
-      "valueKind": "record_css_lengths",
-      "emitsVariables": ["--sky-space-0", "--sky-space-2" ],
-      "examplePatch": {
-        "light": { "spacing": { "2": "0.45rem", "3": "0.65rem", "4": "0.9rem" } }
-      }
-    },
-    {
-      "id": "radius_scale",
-      "group": "shape",
-      "label": "Border radius (record)",
-      "summary": "primary, secondary, tertiary, full — corners of cards, buttons, inputs, chips.",
-      "pathRoot": { "light": "light.radius", "dark": "dark.radius" },
-      "naturalLanguageHooks": [
-        "rounded",
-        "corner",
-        "border radius",
-        "pill",
-        "sharp edges",
-        "squared"
-      ],
-      "valueKind": "record_radii",
-      "emitsVariables": ["--sky-radius-primary", "--sky-radius-*" ],
-      "examplePatch": {
-        "light": { "radius": { "primary": "10px", "secondary": "6px" } }
-      }
-    },
-    {
-      "id": "box_shadow",
-      "group": "shape",
-      "label": "Box shadow (record)",
-      "summary": "primary, secondary, tertiary, inset, hover — card elevation, inputs, modals. Values are full CSS box-shadow strings.",
-      "pathRoot": { "light": "light.boxshadow", "dark": "dark.boxshadow" },
-      "naturalLanguageHooks": ["elevation", "drop shadow", "card shadow", "depth", "skeuomorph"],
-      "valueKind": "record_css_shadows",
-      "emitsVariables": ["--sky-box-shadow-*"],
-      "examplePatch": {
-        "light": { "boxshadow": { "primary": "0 1px 3px rgba(15, 23, 42, 0.08)" } }
-      }
-    },
-    {
-      "id": "blur",
-      "group": "effects",
-      "label": "Blur tier (background blur)",
-      "summary": "primary, secondary, tertiary; emitted as `blur(value)` in `--sky-blur-*` for glass and backdrop effects.",
-      "pathRoot": { "light": "light.blur", "dark": "dark.blur" },
-      "naturalLanguageHooks": ["frosted blur", "background blur", "strength of blur", "frosting"],
-      "valueKind": "record_length_blur",
-      "emitsVariables": ["--sky-blur-primary", "--sky-blur-*" ],
-      "examplePatch": {
-        "light": { "blur": { "primary": "12px" } }
-      }
-    },
-    {
-      "id": "brightness_tiers",
-      "group": "effects",
-      "label": "Brightness (image/effect filter tiers)",
-      "summary": "CSS `brightness()` multipliers. Often used on media or decorative layers, not raw text colors.",
-      "pathRoot": { "light": "light.brightness", "dark": "dark.brightness" },
-      "naturalLanguageHooks": ["brighter", "dimmer image", "brightness", "exposure effect"],
-      "valueKind": "record_filter",
-      "emitsVariables": ["--sky-brightness-primary", "--sky-brightness-*" ],
-      "examplePatch": { "light": { "brightness": { "primary": "1" } } }
-    },
-    {
-      "id": "saturation_tiers",
-      "group": "effects",
-      "label": "Saturation (filter tiers)",
-      "summary": "CSS `saturate()`; decorative or hero imagery, not for semantic status colors (use `color.*` instead).",
-      "pathRoot": { "light": "light.saturation", "dark": "dark.saturation" },
-      "naturalLanguageHooks": [
-        "more vibrant",
-        "vivid",
-        "desaturate",
-        "saturation effect"
-      ],
-      "valueKind": "record_filter",
-      "emitsVariables": ["--sky-saturation-primary", "--sky-saturation-*" ],
-      "examplePatch": { "light": { "saturation": { "primary": "1" } } }
-    },
-    {
-      "id": "border_tiers",
-      "group": "shape",
-      "label": "Border (full CSS value, record)",
-      "summary": "primary, secondary, tertiary — each value is a complete `border` shorthand for strokes around surfaces and controls.",
-      "pathRoot": { "light": "light.border", "dark": "dark.border" },
-      "naturalLanguageHooks": [
-        "border style",
-        "outlines",
-        "hairline",
-        "stroke on cards"
-      ],
-      "valueKind": "record_css_border",
-      "emitsVariables": ["--sky-border-primary", "--sky-border-*" ],
-      "examplePatch": {
-        "light": { "border": { "primary": "1px solid color-mix(in oklch, #0f172a 15%, transparent)" } }
-      }
-    },
-    {
-      "id": "separator",
-      "group": "shape",
-      "label": "Divider / list separator (hairline)",
-      "summary": "One color; feeds `--sky-border-light` (solid RGBA) for 1px separators between list rows or section breaks.",
-      "paths": { "light": "light.separator", "dark": "dark.separator" },
-      "naturalLanguageHooks": [
-        "divider",
-        "separator",
-        "list line",
-        "row divider"
-      ],
-      "valueKind": "css_color",
-      "emitsVariables": ["--sky-border-light"],
-      "examplePatch": {
-        "light": { "separator": "rgba(15, 23, 42, 0.12)" },
-        "dark": { "separator": "rgba(255, 255, 255, 0.1)" }
-      }
-    },
-    {
-      "id": "motion",
-      "group": "motion",
-      "label": "Durations and easing (object)",
-      "summary": "motion.duration: instant, fast, normal, slow. motion.ease: default, in, out, inOut, bounce. Drives `sky-transition-*` and duration/ease tokens.",
-      "pathRoot": { "light": "light.motion", "dark": "dark.motion" },
-      "naturalLanguageHooks": [
-        "animation speed",
-        "snappier",
-        "faster transition",
-        "easing",
-        "motion"
-      ],
-      "valueKind": "motion_config",
-      "emitsVariables": [
-        "--sky-duration-*",
-        "--sky-ease-*",
-        "--sky-transition-default"
-      ],
-      "examplePatch": {
-        "light": { "motion": { "duration": { "fast": "100ms" }, "ease": { "default": "cubic-bezier(0.2,0,0,1)" } } }
-      }
-    },
-    {
-      "id": "z_index",
-      "group": "stacking",
-      "label": "Z-index scale (stacking order)",
-      "summary": "Named levels: base, dropdown, sticky, fixed, modal, popover, toast, max. Emitted as unitless `sky-z-*` numbers (not arbitrary z-index in components).",
-      "pathRoot": { "light": "light.zIndex", "dark": "dark.zIndex" },
-      "naturalLanguageHooks": [
-        "modal on top",
-        "dropdown layer",
-        "tooltip above",
-        "z-index"
-      ],
-      "valueKind": "record_integers",
-      "emitsVariables": ["--sky-z-base", "--sky-z-modal" ],
-      "examplePatch": {
-        "light": { "zIndex": { "modal": 10000, "popover": 10050 } }
-      }
-    },
-    {
-      "id": "opacity_ui",
-      "group": "opacity",
-      "label": "UI opacity (disabled, muted, subtle)",
-      "summary": "0–1 multipliers for disabled controls and de-emphasized text or icons — not the same as glass/overlay opacities.",
-      "pathRoot": { "light": "light.opacity", "dark": "dark.opacity" },
-      "naturalLanguageHooks": [
-        "disabled look",
-        "faded",
-        "muted",
-        "subtle opacity"
-      ],
-      "valueKind": "record_0_1",
-      "emitsVariables": ["--sky-opacity-disabled", "--sky-opacity-*" ],
-      "examplePatch": { "light": { "opacity": { "disabled": 0.4, "muted": 0.6 } } }
-    }
-  ],
-  "recipeTemplates": [
-    {
-      "id": "brand_rollup",
-      "intent": "User gives one brand hex for both light and dark primary accent.",
-      "placeholderKeys": ["primaryHex", "lightPrimaryHex", "darkPrimaryHex"],
-      "patchTemplate": {
-        "light": { "color": { "active": "<lightPrimaryHex or primaryHex>" } },
-        "dark": { "color": { "active": "<darkPrimaryHex or primaryHex>" } }
-      }
-    },
-    {
-      "id": "calm_surface",
-      "intent": "Softer glass + lighter overlay for less harsh surfaces.",
-      "placeholderKeys": [],
-      "patchTemplate": {
-        "light": { "glass": { "opacities": { "primary": 0.38, "secondary": 0.38, "tertiary": 0.38, "solid": 1 } } },
-        "dark": { "overlay": { "opacities": { "primary": 0.45, "secondary": 0.3, "tertiary": 0.15, "solid": 1 } } }
-      }
-    }
-  ],
-  "intentRouters": [
-    {
-      "phrases": [
-        "more padding",
-        "wider",
-        "airy",
-        "breathe",
-        "looser layout",
-        "more space between"
-      ],
-      "fieldIds": ["spacing_scale"],
-      "agentHint": "Increase selected keys in `light.spacing` and `dark.spacing` (e.g. 2,3,4) a few points or rem steps."
-    },
-    {
-      "phrases": [
-        "tighter",
-        "denser",
-        "data-dense",
-        "compact",
-        "admin"
-      ],
-      "fieldIds": ["spacing_scale", "font_size_scale", "line_height_scale"],
-      "agentHint": "Slightly lower spacing and optionally fontSize.md/lg; ensure contrast still holds."
-    },
-    {
-      "phrases": [
-        "frosted",
-        "frosting",
-        "frosted glass"
-      ],
-      "fieldIds": ["glass", "glass_surface_sheen", "blur"],
-      "agentHint": "Tune `glass` base and opacities; optionally `glassSurface` top/bottom; align `blur` tiers for backdrop strength."
-    },
-    {
-      "phrases": [
-        "modals",
-        "backdrop",
-        "scrim"
-      ],
-      "fieldIds": ["overlay", "z_index", "box_shadow"],
-      "agentHint": "Prefer `overlay` for full-screen tints; raise `zIndex.modal` if things stack wrong."
-    },
-    {
-      "phrases": [
-        "on-hover",
-        "on hover"
-      ],
-      "fieldIds": ["glass_hover", "motion", "box_shadow"],
-      "agentHint": "Adjust `glassHover` opacity; motion duration for snappy feel."
-    },
-    {
-      "phrases": [
-        "rebrand",
-        "brand",
-        "company color"
-      ],
-      "fieldIds": [
-        "color_active",
-        "color_background",
-        "color_foreground"
-      ],
-      "agentHint": "Set `active` to brand; nudge `background`/`foreground` for contrast. Keep success/warn/danger unless the brand also replaces them."
-    }
-  ]
-}
+{
+  "schemaVersion": "1.0",
+  "themeProperty": "userTheme",
+  "typescriptType": "Partial<import(\"@sky.ui/core/sky-theme-provider\").ThemeConfig> or inline Partial<ThemeConfig>",
+  "providerElement": "sky-theme-provider",
+  "mergeRules": {
+    "strategy": "deepMergePerMode",
+    "description": "userTheme.light is deep-merged with defaultTheme.light; userTheme.dark with defaultTheme.dark. Omitted keys keep package defaults. Active mode (light|dark) selects which ThemeModeConfig is expanded into --sky-* variables."
+  },
+  "agentWorkflow": [
+    "1) Parse the user's goals (e.g. brand color, calmer background, dense UI, rounder cards).",
+    "2) Map phrases to `fields[].id` using `naturalLanguageHooks` and `intentRouters` below.",
+    "3) Build a single JSON object: `{ \"light\": { ...ThemeModeConfig partial }, \"dark\": { ... } }` — only include keys the user changed.",
+    "4) Set `userTheme` on `sky-theme-provider` (or pass from `sky-theme-generator` `value` / `theme-change`).",
+    "5) Call get_theme with operation variables to list emitted `--sky-*` names; never invent new token names—only `userTheme` values change."
+  ],
+  "fields": [
+    {
+      "id": "color_background",
+      "group": "color",
+      "label": "Canvas / app background",
+      "summary": "Base page or shell background. Drives the main surface behind content.",
+      "paths": { "light": "light.color.background", "dark": "dark.color.background" },
+      "naturalLanguageHooks": [
+        "background",
+        "canvas",
+        "page color",
+        "app background",
+        "whiter",
+        "darker backdrop",
+        "softer background"
+      ],
+      "valueKind": "css_color",
+      "emitsVariables": ["--sky-background-color"],
+      "examplePatch": {
+        "light": { "color": { "background": "#f4f6f8" } },
+        "dark": { "color": { "background": "#0c0e12" } }
+      }
+    },
+    {
+      "id": "color_foreground",
+      "group": "color",
+      "label": "Default text / foreground",
+      "summary": "Primary body and UI text color. Many secondary text tokens are mixed from this.",
+      "paths": { "light": "light.color.foreground", "dark": "dark.color.foreground" },
+      "naturalLanguageHooks": [
+        "text color",
+        "body text",
+        "default text",
+        "readability",
+        "foreground",
+        "primary text"
+      ],
+      "valueKind": "css_color",
+      "emitsVariables": ["--sky-text-primary", "--sky-text-secondary" ],
+      "examplePatch": {
+        "light": { "color": { "foreground": "#0f172a" } },
+        "dark": { "color": { "foreground": "#e8eaef" } }
+      }
+    },
+    {
+      "id": "color_active",
+      "group": "color",
+      "label": "Brand / active / primary accent",
+      "summary": "Main interactive and brand color: links, primary buttons, focus ring base, active-* semantic scale.",
+      "paths": { "light": "light.color.active", "dark": "dark.color.active" },
+      "naturalLanguageHooks": [
+        "brand",
+        "primary",
+        "accent",
+        "CTA",
+        "link color",
+        "active color",
+        "button color",
+        "main color",
+        "corporate"
+      ],
+      "valueKind": "css_color",
+      "emitsVariables": [
+        "--sky-active-primary",
+        "--sky-active-*",
+        "--sky-focus-ring",
+        "--sky-ring-active-*"
+      ],
+      "examplePatch": {
+        "light": { "color": { "active": "#0a6cff" } },
+        "dark": { "color": { "active": "#4b9aff" } }
+      }
+    },
+    {
+      "id": "color_success",
+      "group": "color",
+      "label": "Success / positive",
+      "summary": "Confirms, completed states, safe actions.",
+      "paths": { "light": "light.color.success", "dark": "dark.color.success" },
+      "naturalLanguageHooks": ["success", "ok", "positive", "green", "completed", "check"],
+      "valueKind": "css_color",
+      "emitsVariables": ["--sky-success-primary", "--sky-success-*"],
+      "examplePatch": {
+        "light": { "color": { "success": "#16a34a" } },
+        "dark": { "color": { "success": "#4ade80" } }
+      }
+    },
+    {
+      "id": "color_warning",
+      "group": "color",
+      "label": "Warning / caution",
+      "summary": "Non-fatal issues, needs attention without panic.",
+      "paths": { "light": "light.color.warning", "dark": "dark.color.warning" },
+      "naturalLanguageHooks": ["warning", "caution", "amber", "yellow", "attn"],
+      "valueKind": "css_color",
+      "emitsVariables": ["--sky-warning-primary", "--sky-warning-*"],
+      "examplePatch": {
+        "light": { "color": { "warning": "#d97706" } },
+        "dark": { "color": { "warning": "#fbbf24" } }
+      }
+    },
+    {
+      "id": "color_danger",
+      "group": "color",
+      "label": "Danger / destructive / error",
+      "summary": "Errors, delete, irreversible or critical actions.",
+      "paths": { "light": "light.color.danger", "dark": "dark.color.danger" },
+      "naturalLanguageHooks": [
+        "danger",
+        "error",
+        "red",
+        "delete",
+        "destructive",
+        "alert"
+      ],
+      "valueKind": "css_color",
+      "emitsVariables": ["--sky-danger-primary", "--sky-danger-*"],
+      "examplePatch": {
+        "light": { "color": { "danger": "#dc2626" } },
+        "dark": { "color": { "danger": "#f87171" } }
+      }
+    },
+    {
+      "id": "color_info",
+      "group": "color",
+      "label": "Informational accent",
+      "summary": "Neutral information emphasis (banners, tips), distinct from brand active.",
+      "paths": { "light": "light.color.info", "dark": "dark.color.info" },
+      "naturalLanguageHooks": ["info", "tip", "informational", "note", "blue help"],
+      "valueKind": "css_color",
+      "emitsVariables": ["--sky-info-primary", "--sky-info-*"],
+      "examplePatch": {
+        "light": { "color": { "info": "#0284c7" } },
+        "dark": { "color": { "info": "#38bdf8" } }
+      }
+    },
+    {
+      "id": "glass",
+      "group": "surface",
+      "label": "Translucent glass / frosted surface",
+      "summary": "Frosted panels, chips, floating surfaces: base tint (baseColor), optional explicit secondary/tertiary shades, and opacity steps (primary→solid). Not full-screen modals (see overlay).",
+      "pathRoot": { "light": "light.glass", "dark": "dark.glass" },
+      "naturalLanguageHooks": [
+        "frosted",
+        "glass",
+        "translucent",
+        "card blur",
+        "frosted panel",
+        "surface tint",
+        "frosted UI"
+      ],
+      "valueKind": "glass_config",
+      "emitsVariables": [
+        "--sky-glass-primary",
+        "--sky-glass-secondary",
+        "--sky-glass-tertiary",
+        "--sky-glass-solid"
+      ],
+      "examplePatch": {
+        "light": { "glass": { "baseColor": "#e8ecf2", "opacities": { "primary": 0.5, "secondary": 0.5, "tertiary": 0.5, "solid": 1 } } },
+        "dark": { "glass": { "baseColor": "#1a1f2a", "opacities": { "primary": 0.45, "secondary": 0.45, "tertiary": 0.45, "solid": 1 } } }
+      }
+    },
+    {
+      "id": "glass_surface_sheen",
+      "group": "surface",
+      "label": "Vertical glass sheen (gradient)",
+      "summary": "Top/bottom multipliers for large hero or panel `sky-glass-surface` vertical gradient. Optional: omit for flat glass only.",
+      "pathRoot": { "light": "light.glassSurface", "dark": "dark.glassSurface" },
+      "naturalLanguageHooks": ["gradient surface", "sheen", "hero", "tall panel glass", "glassy header"],
+      "valueKind": "object_top_bottom",
+      "emitsVariables": ["--sky-glass-surface"],
+      "examplePatch": {
+        "light": { "glassSurface": { "top": 0.18, "bottom": 0.05 } },
+        "dark": { "glassSurface": { "top": 0.2, "bottom": 0.04 } }
+      }
+    },
+    {
+      "id": "glass_hover",
+      "group": "surface",
+      "label": "Hover wash on surfaces",
+      "summary": "A dark/neutral color with opacity ladder for pointer-hover overlays on cards/tiles. Not a replacement for glass base.",
+      "pathRoot": { "light": "light.glassHover", "dark": "dark.glassHover" },
+      "naturalLanguageHooks": [
+        "hover on card",
+        "hover states",
+        "rollover",
+        "button hover wash",
+        "darker on hover"
+      ],
+      "valueKind": "hover_overlay_config",
+      "emitsVariables": ["--sky-hover-primary", "--sky-hover-secondary", "--sky-hover-tertiary", "--sky-hover-solid"],
+      "examplePatch": {
+        "light": { "glassHover": { "color": "#000000", "opacity": { "primary": 0.06, "secondary": 0.09, "tertiary": 0.12, "solid": 1 } } }
+      }
+    },
+    {
+      "id": "overlay",
+      "group": "overlay",
+      "label": "Scrim / modal / sheet backdrop",
+      "summary": "Full-screen or pane tint above content. Higher opacity than glass; used for modals, drawers, focus traps.",
+      "pathRoot": { "light": "light.overlay", "dark": "dark.overlay" },
+      "naturalLanguageHooks": [
+        "modal backdrop",
+        "overlay",
+        "scrim",
+        "dim the page",
+        "drawer underlay",
+        "screen tint"
+      ],
+      "valueKind": "overlay_config",
+      "emitsVariables": ["--sky-overlay-primary", "--sky-overlay-*"],
+      "examplePatch": {
+        "light": { "overlay": { "color": "#0f172a", "opacities": { "primary": 0.55, "secondary": 0.4, "tertiary": 0.2, "solid": 1 } } }
+      }
+    },
+    {
+      "id": "font_sans",
+      "group": "typography",
+      "label": "Default UI font (sans) stack",
+      "summary": "Applies to body and most UI; feeds semantic `sky-text-*` role shorthands.",
+      "paths": { "light": "light.fontFamily", "dark": "dark.fontFamily" },
+      "naturalLanguageHooks": ["font", "typeface", "sans", "Poppins", "Inter", "system font", "branding type"],
+      "valueKind": "font_stack",
+      "emitsVariables": ["--sky-font", "--sky-font-sans", "--sky-text-body"],
+      "examplePatch": {
+        "light": { "fontFamily": "'Inter', 'Segoe UI', system-ui, sans-serif" }
+      }
+    },
+    {
+      "id": "font_mono",
+      "group": "typography",
+      "label": "Monospace / code font stack",
+      "summary": "For code, data, and monospace presets (sky-font-mono-*).",
+      "paths": { "light": "light.fontFamilyMono", "dark": "dark.fontFamilyMono" },
+      "naturalLanguageHooks": [
+        "monospace",
+        "code font",
+        "Fira",
+        "JetBrains",
+        "terminal"
+      ],
+      "valueKind": "font_stack_optional",
+      "emitsVariables": ["--sky-font-mono", "--sky-font-mono-*"],
+      "examplePatch": {
+        "light": { "fontFamilyMono": "ui-monospace, 'Cascadia Code', monospace" }
+      }
+    },
+    {
+      "id": "font_size_scale",
+      "group": "typography",
+      "label": "Font size scale (record)",
+      "summary": "Map xs, sm, … 6xl to any CSS font-size. Drives `sky-font-size-*` and presets. Override individual keys, not the whole object unless you replace the scale entirely.",
+      "pathRoot": { "light": "light.fontSize", "dark": "dark.fontSize" },
+      "naturalLanguageHooks": [
+        "bigger type",
+        "larger text",
+        "type scale",
+        "heading sizes",
+        "compact text",
+        "tighter typography"
+      ],
+      "valueKind": "record_font_sizes",
+      "emitsVariables": ["--sky-font-size-*", "--sky-text-*"],
+      "examplePatch": {
+        "light": { "fontSize": { "md": "0.95rem", "lg": "1.125rem" } }
+      }
+    },
+    {
+      "id": "line_height_scale",
+      "group": "typography",
+      "label": "Line height scale (record)",
+      "summary": "Tight, snug, normal, relaxed, loose. Feeds `sky-line-height-*` and role shorthands.",
+      "pathRoot": { "light": "light.lineHeight", "dark": "dark.lineHeight" },
+      "naturalLanguageHooks": ["tighter lines", "line height", "looser lines", "leading"],
+      "valueKind": "record_line_heights",
+      "emitsVariables": ["--sky-line-height-*"],
+      "examplePatch": {
+        "light": { "lineHeight": { "normal": "1.5", "relaxed": "1.65" } }
+      }
+    },
+    {
+      "id": "font_weight_scale",
+      "group": "typography",
+      "label": "Font weight scale (record)",
+      "summary": "Named weights: thin, light, normal, medium, semibold, bold, extrabold. Used in role and preset composition.",
+      "pathRoot": { "light": "light.fontWeight", "dark": "dark.fontWeight" },
+      "naturalLanguageHooks": ["bolder", "heavier", "light weight", "weight scale"],
+      "valueKind": "record_weights",
+      "emitsVariables": ["--sky-font-weight-*"],
+      "examplePatch": {
+        "light": { "fontWeight": { "semibold": "650" } }
+      }
+    },
+    {
+      "id": "letter_spacing_scale",
+      "group": "typography",
+      "label": "Letter spacing (record)",
+      "summary": "Tighter, tight, normal, wide, wider – tracking for titles vs body.",
+      "pathRoot": { "light": "light.letterSpacing", "dark": "dark.letterSpacing" },
+      "naturalLanguageHooks": ["letter spacing", "tracking", "wide text"],
+      "valueKind": "record_letter_spacing",
+      "emitsVariables": ["--sky-letter-spacing-*"],
+      "examplePatch": {
+        "light": { "letterSpacing": { "tight": "-0.02em" } }
+      }
+    },
+    {
+      "id": "spacing_scale",
+      "group": "density",
+      "label": "Spacing / density (record of lengths)",
+      "summary": "Numeric scale keys (0, 1, 2, 4, …) become `--sky-space-{key}`; padding and gaps. Reduce values for dense admin UIs; increase for marketing/open layouts.",
+      "pathRoot": { "light": "light.spacing", "dark": "dark.spacing" },
+      "naturalLanguageHooks": [
+        "denser",
+        "compact",
+        "more padding",
+        "tighter layout",
+        "gaps",
+        "spacing scale",
+        "air",
+        "more whitespace"
+      ],
+      "valueKind": "record_css_lengths",
+      "emitsVariables": ["--sky-space-0", "--sky-space-2" ],
+      "examplePatch": {
+        "light": { "spacing": { "2": "0.45rem", "3": "0.65rem", "4": "0.9rem" } }
+      }
+    },
+    {
+      "id": "radius_scale",
+      "group": "shape",
+      "label": "Border radius (record)",
+      "summary": "primary, secondary, tertiary, full — corners of cards, buttons, inputs, chips.",
+      "pathRoot": { "light": "light.radius", "dark": "dark.radius" },
+      "naturalLanguageHooks": [
+        "rounded",
+        "corner",
+        "border radius",
+        "pill",
+        "sharp edges",
+        "squared"
+      ],
+      "valueKind": "record_radii",
+      "emitsVariables": ["--sky-radius-primary", "--sky-radius-*" ],
+      "examplePatch": {
+        "light": { "radius": { "primary": "10px", "secondary": "6px" } }
+      }
+    },
+    {
+      "id": "box_shadow",
+      "group": "shape",
+      "label": "Box shadow (record)",
+      "summary": "primary, secondary, tertiary, inset, hover — card elevation, inputs, modals. Values are full CSS box-shadow strings.",
+      "pathRoot": { "light": "light.boxshadow", "dark": "dark.boxshadow" },
+      "naturalLanguageHooks": ["elevation", "drop shadow", "card shadow", "depth", "skeuomorph"],
+      "valueKind": "record_css_shadows",
+      "emitsVariables": ["--sky-box-shadow-*"],
+      "examplePatch": {
+        "light": { "boxshadow": { "primary": "0 1px 3px rgba(15, 23, 42, 0.08)" } }
+      }
+    },
+    {
+      "id": "blur",
+      "group": "effects",
+      "label": "Blur tier (background blur)",
+      "summary": "primary, secondary, tertiary; emitted as `blur(value)` in `--sky-blur-*` for glass and backdrop effects.",
+      "pathRoot": { "light": "light.blur", "dark": "dark.blur" },
+      "naturalLanguageHooks": ["frosted blur", "background blur", "strength of blur", "frosting"],
+      "valueKind": "record_length_blur",
+      "emitsVariables": ["--sky-blur-primary", "--sky-blur-*" ],
+      "examplePatch": {
+        "light": { "blur": { "primary": "12px" } }
+      }
+    },
+    {
+      "id": "brightness_tiers",
+      "group": "effects",
+      "label": "Brightness (image/effect filter tiers)",
+      "summary": "CSS `brightness()` multipliers. Often used on media or decorative layers, not raw text colors.",
+      "pathRoot": { "light": "light.brightness", "dark": "dark.brightness" },
+      "naturalLanguageHooks": ["brighter", "dimmer image", "brightness", "exposure effect"],
+      "valueKind": "record_filter",
+      "emitsVariables": ["--sky-brightness-primary", "--sky-brightness-*" ],
+      "examplePatch": { "light": { "brightness": { "primary": "1" } } }
+    },
+    {
+      "id": "saturation_tiers",
+      "group": "effects",
+      "label": "Saturation (filter tiers)",
+      "summary": "CSS `saturate()`; decorative or hero imagery, not for semantic status colors (use `color.*` instead).",
+      "pathRoot": { "light": "light.saturation", "dark": "dark.saturation" },
+      "naturalLanguageHooks": [
+        "more vibrant",
+        "vivid",
+        "desaturate",
+        "saturation effect"
+      ],
+      "valueKind": "record_filter",
+      "emitsVariables": ["--sky-saturation-primary", "--sky-saturation-*" ],
+      "examplePatch": { "light": { "saturation": { "primary": "1" } } }
+    },
+    {
+      "id": "border_tiers",
+      "group": "shape",
+      "label": "Border (full CSS value, record)",
+      "summary": "primary, secondary, tertiary — each value is a complete `border` shorthand for strokes around surfaces and controls.",
+      "pathRoot": { "light": "light.border", "dark": "dark.border" },
+      "naturalLanguageHooks": [
+        "border style",
+        "outlines",
+        "hairline",
+        "stroke on cards"
+      ],
+      "valueKind": "record_css_border",
+      "emitsVariables": ["--sky-border-primary", "--sky-border-*" ],
+      "examplePatch": {
+        "light": { "border": { "primary": "1px solid color-mix(in oklch, #0f172a 15%, transparent)" } }
+      }
+    },
+    {
+      "id": "separator",
+      "group": "shape",
+      "label": "Divider / list separator (hairline)",
+      "summary": "One color; feeds `--sky-border-light` (solid RGBA) for 1px separators between list rows or section breaks.",
+      "paths": { "light": "light.separator", "dark": "dark.separator" },
+      "naturalLanguageHooks": [
+        "divider",
+        "separator",
+        "list line",
+        "row divider"
+      ],
+      "valueKind": "css_color",
+      "emitsVariables": ["--sky-border-light"],
+      "examplePatch": {
+        "light": { "separator": "rgba(15, 23, 42, 0.12)" },
+        "dark": { "separator": "rgba(255, 255, 255, 0.1)" }
+      }
+    },
+    {
+      "id": "motion",
+      "group": "motion",
+      "label": "Durations and easing (object)",
+      "summary": "motion.duration: instant, fast, normal, slow. motion.ease: default, in, out, inOut, bounce. Drives `sky-transition-*` and duration/ease tokens.",
+      "pathRoot": { "light": "light.motion", "dark": "dark.motion" },
+      "naturalLanguageHooks": [
+        "animation speed",
+        "snappier",
+        "faster transition",
+        "easing",
+        "motion"
+      ],
+      "valueKind": "motion_config",
+      "emitsVariables": [
+        "--sky-duration-*",
+        "--sky-ease-*",
+        "--sky-transition-default"
+      ],
+      "examplePatch": {
+        "light": { "motion": { "duration": { "fast": "100ms" }, "ease": { "default": "cubic-bezier(0.2,0,0,1)" } } }
+      }
+    },
+    {
+      "id": "z_index",
+      "group": "stacking",
+      "label": "Z-index scale (stacking order)",
+      "summary": "Named levels: base, dropdown, sticky, fixed, modal, popover, toast, max. Emitted as unitless `sky-z-*` numbers (not arbitrary z-index in components).",
+      "pathRoot": { "light": "light.zIndex", "dark": "dark.zIndex" },
+      "naturalLanguageHooks": [
+        "modal on top",
+        "dropdown layer",
+        "tooltip above",
+        "z-index"
+      ],
+      "valueKind": "record_integers",
+      "emitsVariables": ["--sky-z-base", "--sky-z-modal" ],
+      "examplePatch": {
+        "light": { "zIndex": { "modal": 10000, "popover": 10050 } }
+      }
+    },
+    {
+      "id": "opacity_ui",
+      "group": "opacity",
+      "label": "UI opacity (disabled, muted, subtle)",
+      "summary": "0–1 multipliers for disabled controls and de-emphasized text or icons — not the same as glass/overlay opacities.",
+      "pathRoot": { "light": "light.opacity", "dark": "dark.opacity" },
+      "naturalLanguageHooks": [
+        "disabled look",
+        "faded",
+        "muted",
+        "subtle opacity"
+      ],
+      "valueKind": "record_0_1",
+      "emitsVariables": ["--sky-opacity-disabled", "--sky-opacity-*" ],
+      "examplePatch": { "light": { "opacity": { "disabled": 0.4, "muted": 0.6 } } }
+    }
+  ],
+  "recipeTemplates": [
+    {
+      "id": "brand_rollup",
+      "intent": "User gives one brand hex for both light and dark primary accent.",
+      "placeholderKeys": ["primaryHex", "lightPrimaryHex", "darkPrimaryHex"],
+      "patchTemplate": {
+        "light": { "color": { "active": "<lightPrimaryHex or primaryHex>" } },
+        "dark": { "color": { "active": "<darkPrimaryHex or primaryHex>" } }
+      }
+    },
+    {
+      "id": "calm_surface",
+      "intent": "Softer glass + lighter overlay for less harsh surfaces.",
+      "placeholderKeys": [],
+      "patchTemplate": {
+        "light": { "glass": { "opacities": { "primary": 0.38, "secondary": 0.38, "tertiary": 0.38, "solid": 1 } } },
+        "dark": { "overlay": { "opacities": { "primary": 0.45, "secondary": 0.3, "tertiary": 0.15, "solid": 1 } } }
+      }
+    }
+  ],
+  "intentRouters": [
+    {
+      "phrases": [
+        "more padding",
+        "wider",
+        "airy",
+        "breathe",
+        "looser layout",
+        "more space between"
+      ],
+      "fieldIds": ["spacing_scale"],
+      "agentHint": "Increase selected keys in `light.spacing` and `dark.spacing` (e.g. 2,3,4) a few points or rem steps."
+    },
+    {
+      "phrases": [
+        "tighter",
+        "denser",
+        "data-dense",
+        "compact",
+        "admin"
+      ],
+      "fieldIds": ["spacing_scale", "font_size_scale", "line_height_scale"],
+      "agentHint": "Slightly lower spacing and optionally fontSize.md/lg; ensure contrast still holds."
+    },
+    {
+      "phrases": [
+        "frosted",
+        "frosting",
+        "frosted glass"
+      ],
+      "fieldIds": ["glass", "glass_surface_sheen", "blur"],
+      "agentHint": "Tune `glass` base and opacities; optionally `glassSurface` top/bottom; align `blur` tiers for backdrop strength."
+    },
+    {
+      "phrases": [
+        "modals",
+        "backdrop",
+        "scrim"
+      ],
+      "fieldIds": ["overlay", "z_index", "box_shadow"],
+      "agentHint": "Prefer `overlay` for full-screen tints; raise `zIndex.modal` if things stack wrong."
+    },
+    {
+      "phrases": [
+        "on-hover",
+        "on hover"
+      ],
+      "fieldIds": ["glass_hover", "motion", "box_shadow"],
+      "agentHint": "Adjust `glassHover` opacity; motion duration for snappy feel."
+    },
+    {
+      "phrases": [
+        "rebrand",
+        "brand",
+        "company color"
+      ],
+      "fieldIds": [
+        "color_active",
+        "color_background",
+        "color_foreground"
+      ],
+      "agentHint": "Set `active` to brand; nudge `background`/`foreground` for contrast. Keep success/warn/danger unless the brand also replaces them."
+    }
+  ]
+}