@sky.ui/mcp 0.0.1 → 0.0.2

package/docs/sky-chart-option-api.md

@@ -1,47 +1,47 @@
-# sky-chart — option API for AI assistants
-
-Use this when the user needs **charts, dashboards, or ECharts-shaped configuration** on **`sky-chart`**. It complements **`get_sky_component_docs`** and **`get_chart_usage`**.
-
-## Tool order
-
-1. **`get_sky_component_docs`** with **`name: "sky-chart"`** (optional **`surface`**) for props, events, slots.
-2. **`get_chart_usage`** — **`list_types`**, then **`get_type`** with **`chart_type`**, or **`option_guide`** for the compact mental model.
-3. **`get_docs`** with **`packages/mcp/docs/sky-chart-option-api.md`** (this file) when you need prose without calling MCP again.
-4. Example-site snippet matrices (when configured) arrive via **`get_sky_component_docs`** enrichment—not a separate tool.
-
-## Mental model
-
-| Input | Role |
-|--------|------|
-| **`type`** | Selects which **lazy-loaded renderer** runs (`bar`, `line`, `pie`, `map`, `radar`, `sankey`, `brush`, …). Must match the chart family you are building. |
-| **`option`** | **Root chart configuration**: ECharts-style field names (`series`, `xAxis`, `tooltip`, …). The host merges theme and layout; renderers read the subset they need. |
-| **`theme`** (attribute) | `light` \| `dark` \| `""`. Empty string follows the active **`sky-theme-provider`**. |
-| **`option.theme`** | Optional **named palette** inside the option object (host may merge backgrounds / colors). |
-
-**`type="brush"`** is a **range UI** (overview + detail). Use host **`start`** / **`end`** (0–100). Linked charts get their own **`option`** and usual **`type`** values.
-
-## Root **`option`** shape (authoritative summary)
-
-The shipped TypeScript root interface is **`EChartsOption`** in the Sky UI repo file **`components-raw/sky-chart/echarts-option.ts`**. Its **top-level keys** include:
-
-- **`series`** (required in the type model; each entry has **`type`** for that series, e.g. `bar`, `line`, `pie`, `map`, …).
-- **`xAxis`**, **`yAxis`**, **`grid`**, **`polar`**, **`angleAxis`**, **`radiusAxis`**, **`radar`**, **`geo`**, **`parallel`**, **`parallelAxis`**, **`calendar`** — coordinate and layout systems as needed.
-- **`dataset`** (and optional **transform**, e.g. boxplot).
-- **`tooltip`**, **`legend`**, **`axisPointer`**, **`dataZoom`**, **`visualMap`**, **`brush`**, **`timeline`** / **`options`** (multi-step timelines).
-- **`color`**, **`backgroundColor`**, **`decal`**, **`graphic`**, **`fisheye`**, **`animation`** / **`animationDuration`** / related fields — presentation and motion.
-
-Fields not listed in **`echarts-option.ts`** may still work when they match **Apache ECharts option** naming for features Sky has wired through; treat **extra fields** as **best-effort** unless confirmed in source or examples.
-
-## Accuracy rules
-
-1. **Prefer `get_sky_component_docs("sky-chart")`** over guessing tags or prop names.
-2. **`type`** on the **custom element** picks the **primary renderer**; keep **`option.series`** consistent with that mode (avoid declaring an unsupported primary renderer).
-3. **`option` is data**, not HTML: validate **untrusted** JSON before assigning (same risk class as remote config).
-4. For **a11y**, pair charts with **text, tables, or live regions** when exact values matter; confirm keyboard/focus behavior from **`get_sky_component_docs`** events and slots.
-
-## Repo paths (for humans / monorepo clones)
-
-- **Root option type:** `components-raw/sky-chart/echarts-option.ts` — interface **`EChartsOption`**.
-- **Renderer registry:** `components-raw/sky-chart/renderer/index.ts` — **`SkyChartType`** keys and lazy imports.
-
-Published installs may not ship **`components-raw/`**; use **`get_sky_component_docs`** and this doc from **@sky.ui/mcp** instead.
+# sky-chart — option API for AI assistants
+
+Use this when the user needs **charts, dashboards, or ECharts-shaped configuration** on **`sky-chart`**. It complements **`get_sky_component_docs`** and **`get_chart_usage`**.
+
+## Tool order
+
+1. **`get_sky_component_docs`** with **`name: "sky-chart"`** (optional **`surface`**) for props, events, slots.
+2. **`get_chart_usage`** — **`list_types`**, then **`get_type`** with **`chart_type`**, or **`option_guide`** for the compact mental model.
+3. **`get_docs`** with **`packages/mcp/docs/sky-chart-option-api.md`** (this file) when you need prose without calling MCP again.
+4. Example-site snippet matrices (when configured) arrive via **`get_sky_component_docs`** enrichment—not a separate tool.
+
+## Mental model
+
+| Input | Role |
+|--------|------|
+| **`type`** | Selects which **lazy-loaded renderer** runs (`bar`, `line`, `pie`, `map`, `radar`, `sankey`, `brush`, …). Must match the chart family you are building. |
+| **`option`** | **Root chart configuration**: ECharts-style field names (`series`, `xAxis`, `tooltip`, …). The host merges theme and layout; renderers read the subset they need. |
+| **`theme`** (attribute) | `light` \| `dark` \| `""`. Empty string follows the active **`sky-theme-provider`**. |
+| **`option.theme`** | Optional **named palette** inside the option object (host may merge backgrounds / colors). |
+
+**`type="brush"`** is a **range UI** (overview + detail). Use host **`start`** / **`end`** (0–100). Linked charts get their own **`option`** and usual **`type`** values.
+
+## Root **`option`** shape (authoritative summary)
+
+The shipped TypeScript root interface is **`EChartsOption`** in the Sky UI repo file **`components-raw/sky-chart/echarts-option.ts`**. Its **top-level keys** include:
+
+- **`series`** (required in the type model; each entry has **`type`** for that series, e.g. `bar`, `line`, `pie`, `map`, …).
+- **`xAxis`**, **`yAxis`**, **`grid`**, **`polar`**, **`angleAxis`**, **`radiusAxis`**, **`radar`**, **`geo`**, **`parallel`**, **`parallelAxis`**, **`calendar`** — coordinate and layout systems as needed.
+- **`dataset`** (and optional **transform**, e.g. boxplot).
+- **`tooltip`**, **`legend`**, **`axisPointer`**, **`dataZoom`**, **`visualMap`**, **`brush`**, **`timeline`** / **`options`** (multi-step timelines).
+- **`color`**, **`backgroundColor`**, **`decal`**, **`graphic`**, **`fisheye`**, **`animation`** / **`animationDuration`** / related fields — presentation and motion.
+
+Fields not listed in **`echarts-option.ts`** may still work when they match **Apache ECharts option** naming for features Sky has wired through; treat **extra fields** as **best-effort** unless confirmed in source or examples.
+
+## Accuracy rules
+
+1. **Prefer `get_sky_component_docs("sky-chart")`** over guessing tags or prop names.
+2. **`type`** on the **custom element** picks the **primary renderer**; keep **`option.series`** consistent with that mode (avoid declaring an unsupported primary renderer).
+3. **`option` is data**, not HTML: validate **untrusted** JSON before assigning (same risk class as remote config).
+4. For **a11y**, pair charts with **text, tables, or live regions** when exact values matter; confirm keyboard/focus behavior from **`get_sky_component_docs`** events and slots.
+
+## Repo paths (for humans / monorepo clones)
+
+- **Root option type:** `components-raw/sky-chart/echarts-option.ts` — interface **`EChartsOption`**.
+- **Renderer registry:** `components-raw/sky-chart/renderer/index.ts` — **`SkyChartType`** keys and lazy imports.
+
+Published installs may not ship **`components-raw/`**; use **`get_sky_component_docs`** and this doc from **@sky.ui/mcp** instead.

package/docs/starter-prompt.md

@@ -1,17 +1,17 @@
-# Sky UI — starter prompt for assistants
-
-Paste this at the start of a session when building with Sky UI (Cursor, Claude, Copilot, etc.).
-
-```
-You are helping build UI with Sky UI (@sky.ui/core web components, optional @sky.ui/react / @sky.ui/vue wrappers, @sky.ui/utils for layout CSS, @sky.ui/reactivity when needed).
-
-You MUST use Sky UI MCP tools as the only source for component names, imports, props, events, slots, and theme tokens. Do not invent tags or --sky-* names.
-
-Styling priority (pages, layouts, shells): Prefer @sky.ui/utils utility classes on elements (`class` / `className`) for layout, spacing, typography, and colors. Use get_docs with packages/mcp/docs/utils-usage-guide.md for setup; utility_classes (variant_prefixes, search_classes, check_class) to discover and validate class names; align get_theme (operation guide, then fields/field) for userTheme. Do NOT default to large hand-written plain CSS or unrelated CSS frameworks unless the user asks or a case truly cannot be expressed with utilities.
-
-Order: (1) get_project_guide (kind installation | setup) for install/bundler (2) get_sky_component_docs with optional surface (3) get_component_usage for lit/react/vue (4) get_reactivity_layer for @sky.ui/reactivity topics (5) get_chart_usage for sky-chart types and option guide (6) theme: get_theme operation guide then fields/field (7) layout/styling: utility_classes + get_docs utils-usage-guide. For sky-chart props/events, get_sky_component_docs(name: sky-chart).
-
-When citing MCP JSON, respect `_skyUiMcp.truthLayer` and `_skyUiMcp.agentMust` — do not treat guideline_scoring or heuristic_search as guaranteed API contracts.
-
-If a tool returns code starting with JSON parse errors or empty arrays, say what is missing (e.g. `@sky.ui/core` not installed/built) and retry after suggesting the user fix the environment.
-```
+# Sky UI — starter prompt for assistants
+
+Paste this at the start of a session when building with Sky UI (Cursor, Claude, Copilot, etc.).
+
+```
+You are helping build UI with Sky UI (@sky.ui/core web components, optional @sky.ui/react / @sky.ui/vue wrappers, @sky.ui/utils for layout CSS, @sky.ui/reactivity when needed).
+
+You MUST use Sky UI MCP tools as the only source for component names, imports, props, events, slots, and theme tokens. Do not invent tags or --sky-* names.
+
+Styling priority (pages, layouts, shells): Prefer @sky.ui/utils utility classes on elements (`class` / `className`) for layout, spacing, typography, and colors. Use get_docs with packages/mcp/docs/utils-usage-guide.md for setup; utility_classes (variant_prefixes, search_classes, check_class) to discover and validate class names; align get_theme (operation guide, then fields/field) for userTheme. Do NOT default to large hand-written plain CSS or unrelated CSS frameworks unless the user asks or a case truly cannot be expressed with utilities.
+
+Order: (1) get_project_guide (kind installation | setup) for install/bundler (2) get_sky_component_docs with optional surface (3) get_component_usage for lit/react/vue (4) get_reactivity_layer for @sky.ui/reactivity topics (5) get_chart_usage for sky-chart types and option guide (6) theme: get_theme operation guide then fields/field (7) layout/styling: utility_classes + get_docs utils-usage-guide. For sky-chart props/events, get_sky_component_docs(name: sky-chart).
+
+When citing MCP JSON, respect `_skyUiMcp.truthLayer` and `_skyUiMcp.agentMust` — do not treat guideline_scoring or heuristic_search as guaranteed API contracts.
+
+If a tool returns code starting with JSON parse errors or empty arrays, say what is missing (e.g. `@sky.ui/core` not installed/built) and retry after suggesting the user fix the environment.
+```

package/docs/theme-config-guide.md

@@ -1,178 +1,178 @@
-# ThemeConfig / `userTheme` field guide
-
-This document describes **what each entry in `ThemeModeConfig` is for** when you pass **`Partial<ThemeConfig>`** as **`userTheme`** on **`sky-theme-provider`**. Names are stable; **values** change per theme/mode. The provider **deep-merges** your overrides with **`defaultTheme`** separately for **`light`** and **`dark`**.
-
-- **Type layout**: `ThemeConfig` has `{ light: ThemeModeConfig; dark: ThemeModeConfig }`.
-- **Override rule**: Only set what you need; omitted keys keep defaults.
-- **CSS output**: Merged config is turned into **`--sky-*`** custom properties on `:root` and/or `:host` (see `generateVarMap` in `sky-theme-provider`).
-- **Full variable list**: MCP **`get_theme`** with **`operation: variables`** (extracted `--sky-*` names).
-- **For AI / programmatic authoring** (path hooks, `examplePatch`, phrase→field routing): **`get_theme`** — start with **`operation: guide`**, then **`fields`**, **`field`**, **`match_intent`**, **`compose`**. Source: `packages/mcp/data/theme-authoring-contract.json`.
-
----
-
-## Quick mental model
-
-| Area | Role in the UI |
-|------|----------------|
-| **`color`** | Page background, default text, and **brand semantic** colors (active, success, warning, danger, info) that drive buttons, alerts, rings, and states. |
-| **`glass`** | Translucent **surface fills** (cards, panels, chips): base tint + opacity ladder. |
-| **`glassSurface`** | Optional **vertical gradient** strength for the special `sky-glass-surface` token (Sheen top → bottom). |
-| **`glassHover`** | **Hoverwash** overlays on interactive surfaces (darkening/lightening), not full backgrounds. |
-| **`overlay`** | **Scrim / modal / sheet** backdrops—full-screen or layered tint above content. |
-| **`fontFamily` / mono** | Base **sans** and **mono** stacks; feed typography tokens and role tokens. |
-| **`fontSize` / `fontWeight` / `lineHeight` / `letterSpacing`** | Scales used for **`--sky-font-size-*`**, **`--sky-text-*`** roles, and presets. |
-| **`spacing`** | **Density**: padding/gaps as **`--sky-space-{key}`** (not `--sky-spacing-*`). |
-| **`blur` / `radius` / `boxshadow`** | **Chrome**: elevation, corners, shadows—cards, popovers, inputs. |
-| **`brightness` / `saturation`** | **Filter tokens** for effects layers (e.g. imagery, decorative overlays). |
-| **`border`** | **Border styles** as complete CSS values → **`--sky-border-primary`** etc. |
-| **`separator`** | Hairline **divider** color feeding **`--sky-border-light`**. |
-| **`motion`** | **Transition** duration and easing → **`--sky-duration-*`**, **`--sky-ease-*`**, plus **`--sky-transition-default`**. |
-| **`zIndex`** | **Stacking** scale → **`--sky-z-*`**. |
-| **`opacity`** | **UI opacity** for disabled/muted/subtle → **`--sky-opacity-*`**. |
-
----
-
-## `color`
-
-All keys are **source primaries**. The provider **generates** lighter/darker mixes, alpha steps (`g0`–`g2`), hover variants, and **focus rings** from these— you normally only edit the primaries.
-
-| Field | Meaning | Main emitted tokens |
-|-------|---------|---------------------|
-| **`background`** | Default **page / canvas** background. | `--sky-background-color` |
-| **`foreground`** | Default **body text** color. | `--sky-text-primary` (plus derived secondary→quinary text via `color-mix`) |
-| **`active`** | Primary **interactive / brand** color (links, primary buttons, focus ring base). | `--sky-active-*`, `--sky-focus-ring` uses active primary |
-| **`success`** | Positive outcomes, safe actions. | `--sky-success-*` |
-| **`warning`** | Caution, non-blocking issues. | `--sky-warning-*` |
-| **`danger`** | Errors, destructive actions. | `--sky-danger-*` |
-| **`info`** | Neutral informational emphasis. | `--sky-info-*` |
-
-Each semantic family exposes **`--sky-{name}-primary`**, stepped mixes (**secondary … quinary**), **`*-dark`** variants, **alpha** **`g0`–`g2`**, **hover** variants, and **ring** **`sky-ring-{name}-*`** utilities.
-
----
-
-## `glass`
-
-**Translucent UI surfaces** (frosted panels, subtle fills): pick a **base color** and **opacity steps**.
-
-| Subfield | Meaning | Emits |
-|----------|---------|--------|
-| **`baseColor`** | Tint shared by glass layers. | `--sky-glass-primary`, secondary/tertiary (via mix or **`baseShades`**) |
-| **`baseShades.secondary` / `tertiary`** | Optional explicit shades instead of auto-mix. | `--sky-glass-secondary`, `--sky-glass-tertiary` |
-| **`opacities`** (`primary` … `solid`) | Opacity ladder for hierarchy. | `--sky-glass-primary` … **`--sky-glass-solid`** |
-
----
-
-## `glassSurface`
-
-Optional **`top`** / **`bottom`** multipliers (defaults **0.16** / **0.04**) for a **linear gradient** used as **`--sky-glass-surface`**—useful for **hero bands** or **large panels** where you want a stronger vertical sheen than flat glass tokens.
-
----
-
-## `glassHover`
-
-**Pointer-hover overlays** on surfaces: a single **`color`** plus **per-level opacity** (`primary` … `solid`). Emits **`--sky-hover-*`**—think **dimming** a card on hover, not replacing `glass` entirely.
-
----
-
-## `overlay`
-
-**Modal / drawer / loading scrim** tint: **`color`** + **opacity steps**. Emits **`--sky-overlay-*`**. Use for **blocking overlays** above page content; contrast with **`glass`** (inline translucent chrome).
-
----
-
-## Typography: `fontFamily`, `fontFamilyMono`
-
-| Field | Emits / effect |
-|-------|----------------|
-| **`fontFamily`** | `--sky-font`, `--sky-font-sans`; used in semantic **`--sky-text-body`**, **`label`**, **`caption`**, **`title`**, **`heading`**, **`display`**. |
-| **`fontFamilyMono`** | `--sky-font-mono`; monospace presets **`--sky-font-mono-{xs…4xl}`**. |
-
----
-
-## `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`
-
-Maps keyed by **design tokens** (e.g. `md`, `semibold`, `normal`). Emit:
-
-- **`--sky-font-size-*`**, **`--sky-font-weight-*`**, **`--sky-line-height-*`**, **`--sky-letter-spacing-*`**
-- **`--sky-font-{xs…4xl}`** and **`--sky-font-mono-{xs…4xl}`** shorthands
-- **`--sky-text-{body|label|caption|title|heading|display}`** role strings (weight + size/line + family)
-
----
-
-## `spacing`
-
-Numeric-ish keys (`"1"`, `"2"`, `"4"`, …) → **`--sky-space-{key}`**. Used for **padding, gap, inset** across components. **Override spacing here** to change global density, not border widths.
-
----
-
-## `blur`, `radius`, `boxshadow`
-
-| Field | Emits | Typical use |
-|-------|-------|-------------|
-| **`blur`** | `--sky-blur-*` as `blur(...)` | Backdrop blur on glass, frosted headers |
-| **`radius`** | `--sky-radius-*` | Cards, buttons, inputs |
-| **`boxshadow`** | `--sky-box-shadow-*` | Elevation / depth |
-
----
-
-## `brightness`, `saturation`
-
-Emit **`--sky-brightness-*`** / **`--sky-saturation-*`** as CSS **`brightness()`** / **`saturate()`** filters—usually for **media overlays** or **effect layers**, not raw text color.
-
----
-
-## `border`
-
-Complete **border** CSS values per tier (**primary** / **secondary** / **tertiary**) → **`--sky-border-*`**. Use for **strokes around surfaces** and controls.
-
----
-
-## `separator`
-
-Single **hairline** color; emits **`--sky-border-light`** (full RGBA value).
-
----
-
-## `motion`
-
-| Subfield | Emits |
-|----------|--------|
-| **`duration`** (`instant`, `fast`, `normal`, `slow`) | `--sky-duration-*` |
-| **`ease`** (`default`, `in`, `out`, `inOut`, `bounce`) | `--sky-ease-*` |
-
-Also drives **`--sky-transition-default`** and **`--sky-transition-fast`** shorthands.
-
----
-
-## `zIndex`
-
-Named layers (**base**, **dropdown**, **sticky**, **modal**, etc.) → **`--sky-z-*`** **numbers** for predictable stacking.
-
----
-
-## `opacity`
-
-**Semantic UI opacity** (**disabled**, **muted**, **subtle**) → **`--sky-opacity-*`** as unitless multipliers for styling inactive or de-emphasized UI.
-
----
-
-## Derived behavior (no direct theme keys)
-
-These are **computed** from the sections above:
-
-- **Text hierarchy**: `--sky-text-secondary` … **`quinary`** from **`foreground`** via `color-mix`.
-- **Semantic ramps**: full **`active` / `success` / …** scales and **hover**/**ring** tokens.
-- **Focus**: **`--sky-focus-ring`** from **`active`** primary (not a separate color key).
-- **`--sky-text-shadow-on-glass`**: readability helper on glass.
-- **`--sky-text-white` / `--sky-text-black`**: fixed reference whites/blacks for compositions.
-
----
-
-## Authoring workflow
-
-1. Start from **`defaultTheme`** or **`sky-theme-generator`** output so **`light`** and **`dark`** stay paired.
-2. Override **`color`** primaries first for brand alignment; tune **`glass`** / **`overlay`** for surfaces vs scrims.
-3. Adjust **`spacing`** for density; **`radius`** / **`boxshadow`** for visual weight.
-4. Validate contrast manually—the provider **does not** enforce WCAG on **`userTheme`**.
-
-For interactive editing, bind **`sky-theme-generator`** **`value`** / **`theme-change`** into **`userTheme`** on **`sky-theme-provider`** so tokens update live.
+# ThemeConfig / `userTheme` field guide
+
+This document describes **what each entry in `ThemeModeConfig` is for** when you pass **`Partial<ThemeConfig>`** as **`userTheme`** on **`sky-theme-provider`**. Names are stable; **values** change per theme/mode. The provider **deep-merges** your overrides with **`defaultTheme`** separately for **`light`** and **`dark`**.
+
+- **Type layout**: `ThemeConfig` has `{ light: ThemeModeConfig; dark: ThemeModeConfig }`.
+- **Override rule**: Only set what you need; omitted keys keep defaults.
+- **CSS output**: Merged config is turned into **`--sky-*`** custom properties on `:root` and/or `:host` (see `generateVarMap` in `sky-theme-provider`).
+- **Full variable list**: MCP **`get_theme`** with **`operation: variables`** (extracted `--sky-*` names).
+- **For AI / programmatic authoring** (path hooks, `examplePatch`, phrase→field routing): **`get_theme`** — start with **`operation: guide`**, then **`fields`**, **`field`**, **`match_intent`**, **`compose`**. Source: `packages/mcp/data/theme-authoring-contract.json`.
+
+---
+
+## Quick mental model
+
+| Area | Role in the UI |
+|------|----------------|
+| **`color`** | Page background, default text, and **brand semantic** colors (active, success, warning, danger, info) that drive buttons, alerts, rings, and states. |
+| **`glass`** | Translucent **surface fills** (cards, panels, chips): base tint + opacity ladder. |
+| **`glassSurface`** | Optional **vertical gradient** strength for the special `sky-glass-surface` token (Sheen top → bottom). |
+| **`glassHover`** | **Hoverwash** overlays on interactive surfaces (darkening/lightening), not full backgrounds. |
+| **`overlay`** | **Scrim / modal / sheet** backdrops—full-screen or layered tint above content. |
+| **`fontFamily` / mono** | Base **sans** and **mono** stacks; feed typography tokens and role tokens. |
+| **`fontSize` / `fontWeight` / `lineHeight` / `letterSpacing`** | Scales used for **`--sky-font-size-*`**, **`--sky-text-*`** roles, and presets. |
+| **`spacing`** | **Density**: padding/gaps as **`--sky-space-{key}`** (not `--sky-spacing-*`). |
+| **`blur` / `radius` / `boxshadow`** | **Chrome**: elevation, corners, shadows—cards, popovers, inputs. |
+| **`brightness` / `saturation`** | **Filter tokens** for effects layers (e.g. imagery, decorative overlays). |
+| **`border`** | **Border styles** as complete CSS values → **`--sky-border-primary`** etc. |
+| **`separator`** | Hairline **divider** color feeding **`--sky-border-light`**. |
+| **`motion`** | **Transition** duration and easing → **`--sky-duration-*`**, **`--sky-ease-*`**, plus **`--sky-transition-default`**. |
+| **`zIndex`** | **Stacking** scale → **`--sky-z-*`**. |
+| **`opacity`** | **UI opacity** for disabled/muted/subtle → **`--sky-opacity-*`**. |
+
+---
+
+## `color`
+
+All keys are **source primaries**. The provider **generates** lighter/darker mixes, alpha steps (`g0`–`g2`), hover variants, and **focus rings** from these— you normally only edit the primaries.
+
+| Field | Meaning | Main emitted tokens |
+|-------|---------|---------------------|
+| **`background`** | Default **page / canvas** background. | `--sky-background-color` |
+| **`foreground`** | Default **body text** color. | `--sky-text-primary` (plus derived secondary→quinary text via `color-mix`) |
+| **`active`** | Primary **interactive / brand** color (links, primary buttons, focus ring base). | `--sky-active-*`, `--sky-focus-ring` uses active primary |
+| **`success`** | Positive outcomes, safe actions. | `--sky-success-*` |
+| **`warning`** | Caution, non-blocking issues. | `--sky-warning-*` |
+| **`danger`** | Errors, destructive actions. | `--sky-danger-*` |
+| **`info`** | Neutral informational emphasis. | `--sky-info-*` |
+
+Each semantic family exposes **`--sky-{name}-primary`**, stepped mixes (**secondary … quinary**), **`*-dark`** variants, **alpha** **`g0`–`g2`**, **hover** variants, and **ring** **`sky-ring-{name}-*`** utilities.
+
+---
+
+## `glass`
+
+**Translucent UI surfaces** (frosted panels, subtle fills): pick a **base color** and **opacity steps**.
+
+| Subfield | Meaning | Emits |
+|----------|---------|--------|
+| **`baseColor`** | Tint shared by glass layers. | `--sky-glass-primary`, secondary/tertiary (via mix or **`baseShades`**) |
+| **`baseShades.secondary` / `tertiary`** | Optional explicit shades instead of auto-mix. | `--sky-glass-secondary`, `--sky-glass-tertiary` |
+| **`opacities`** (`primary` … `solid`) | Opacity ladder for hierarchy. | `--sky-glass-primary` … **`--sky-glass-solid`** |
+
+---
+
+## `glassSurface`
+
+Optional **`top`** / **`bottom`** multipliers (defaults **0.16** / **0.04**) for a **linear gradient** used as **`--sky-glass-surface`**—useful for **hero bands** or **large panels** where you want a stronger vertical sheen than flat glass tokens.
+
+---
+
+## `glassHover`
+
+**Pointer-hover overlays** on surfaces: a single **`color`** plus **per-level opacity** (`primary` … `solid`). Emits **`--sky-hover-*`**—think **dimming** a card on hover, not replacing `glass` entirely.
+
+---
+
+## `overlay`
+
+**Modal / drawer / loading scrim** tint: **`color`** + **opacity steps**. Emits **`--sky-overlay-*`**. Use for **blocking overlays** above page content; contrast with **`glass`** (inline translucent chrome).
+
+---
+
+## Typography: `fontFamily`, `fontFamilyMono`
+
+| Field | Emits / effect |
+|-------|----------------|
+| **`fontFamily`** | `--sky-font`, `--sky-font-sans`; used in semantic **`--sky-text-body`**, **`label`**, **`caption`**, **`title`**, **`heading`**, **`display`**. |
+| **`fontFamilyMono`** | `--sky-font-mono`; monospace presets **`--sky-font-mono-{xs…4xl}`**. |
+
+---
+
+## `fontSize`, `fontWeight`, `lineHeight`, `letterSpacing`
+
+Maps keyed by **design tokens** (e.g. `md`, `semibold`, `normal`). Emit:
+
+- **`--sky-font-size-*`**, **`--sky-font-weight-*`**, **`--sky-line-height-*`**, **`--sky-letter-spacing-*`**
+- **`--sky-font-{xs…4xl}`** and **`--sky-font-mono-{xs…4xl}`** shorthands
+- **`--sky-text-{body|label|caption|title|heading|display}`** role strings (weight + size/line + family)
+
+---
+
+## `spacing`
+
+Numeric-ish keys (`"1"`, `"2"`, `"4"`, …) → **`--sky-space-{key}`**. Used for **padding, gap, inset** across components. **Override spacing here** to change global density, not border widths.
+
+---
+
+## `blur`, `radius`, `boxshadow`
+
+| Field | Emits | Typical use |
+|-------|-------|-------------|
+| **`blur`** | `--sky-blur-*` as `blur(...)` | Backdrop blur on glass, frosted headers |
+| **`radius`** | `--sky-radius-*` | Cards, buttons, inputs |
+| **`boxshadow`** | `--sky-box-shadow-*` | Elevation / depth |
+
+---
+
+## `brightness`, `saturation`
+
+Emit **`--sky-brightness-*`** / **`--sky-saturation-*`** as CSS **`brightness()`** / **`saturate()`** filters—usually for **media overlays** or **effect layers**, not raw text color.
+
+---
+
+## `border`
+
+Complete **border** CSS values per tier (**primary** / **secondary** / **tertiary**) → **`--sky-border-*`**. Use for **strokes around surfaces** and controls.
+
+---
+
+## `separator`
+
+Single **hairline** color; emits **`--sky-border-light`** (full RGBA value).
+
+---
+
+## `motion`
+
+| Subfield | Emits |
+|----------|--------|
+| **`duration`** (`instant`, `fast`, `normal`, `slow`) | `--sky-duration-*` |
+| **`ease`** (`default`, `in`, `out`, `inOut`, `bounce`) | `--sky-ease-*` |
+
+Also drives **`--sky-transition-default`** and **`--sky-transition-fast`** shorthands.
+
+---
+
+## `zIndex`
+
+Named layers (**base**, **dropdown**, **sticky**, **modal**, etc.) → **`--sky-z-*`** **numbers** for predictable stacking.
+
+---
+
+## `opacity`
+
+**Semantic UI opacity** (**disabled**, **muted**, **subtle**) → **`--sky-opacity-*`** as unitless multipliers for styling inactive or de-emphasized UI.
+
+---
+
+## Derived behavior (no direct theme keys)
+
+These are **computed** from the sections above:
+
+- **Text hierarchy**: `--sky-text-secondary` … **`quinary`** from **`foreground`** via `color-mix`.
+- **Semantic ramps**: full **`active` / `success` / …** scales and **hover**/**ring** tokens.
+- **Focus**: **`--sky-focus-ring`** from **`active`** primary (not a separate color key).
+- **`--sky-text-shadow-on-glass`**: readability helper on glass.
+- **`--sky-text-white` / `--sky-text-black`**: fixed reference whites/blacks for compositions.
+
+---
+
+## Authoring workflow
+
+1. Start from **`defaultTheme`** or **`sky-theme-generator`** output so **`light`** and **`dark`** stay paired.
+2. Override **`color`** primaries first for brand alignment; tune **`glass`** / **`overlay`** for surfaces vs scrims.
+3. Adjust **`spacing`** for density; **`radius`** / **`boxshadow`** for visual weight.
+4. Validate contrast manually—the provider **does not** enforce WCAG on **`userTheme`**.
+
+For interactive editing, bind **`sky-theme-generator`** **`value`** / **`theme-change`** into **`userTheme`** on **`sky-theme-provider`** so tokens update live.