@sky.ui/mcp 0.0.1

package/docs/theme-config-guide.md

@@ -0,0 +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.

package/docs/utils-usage-guide.md

@@ -0,0 +1,110 @@
+# Using @sky.ui/utils
+
+Sky UI utilities are **JIT CSS classes** you add in HTML/JSX/Vue/Lit templates (`class` / `className`). A **PostCSS plugin** scans your project, reads **`skyui.config.js`**, and emits only the CSS you use.
+
+## Install
+
+```bash
+npm install @sky.ui/utils postcss
+```
+
+Register in PostCSS (exact wiring depends on your bundler — use MCP **`get_project_guide`** with `kind: setup`):
+
+```js
+import skyui from '@sky.ui/utils/postcss';
+
+export default {
+  plugins: [skyui()]
+};
+```
+
+**Peer dependency:** `postcss` >= 8.4.
+
+## Public imports
+
+| Import | Use |
+| --- | --- |
+| `@sky.ui/utils` / `@sky.ui/utils/postcss` | PostCSS plugin (**`SkyUIPlugin`**) |
+| `@sky.ui/utils/vite` | Vite integration |
+| `@sky.ui/utils/css-data` | VS Code `css.customData` — silences “Unknown at rule” for `@apply` / `@skyui` |
+| `@sky.ui/utils/suggestion-engine` | Editor completions (optional) |
+| `@sky.ui/utils/prettier-plugin` | Sort class strings in `class` / `@apply` |
+| `@sky.ui/utils/runtime` | Browser **`skyui`** helper for static pages |
+
+## `skyui.config.js`
+
+Typical fields:
+
+| Field | Purpose |
+| --- | --- |
+| `content` | Globs of files to scan for class names |
+| `safelist` | Classes always generated (strings or `{ pattern, variants }`) |
+| `plugins` | Built-ins such as `@skyuicss/forms`, `@skyuicss/typography`, `@skyuicss/container-queries` |
+| `theme` / `theme.extend` | Colors, spacing, screens, `preflight`, `formsStrategy`, animations |
+| `breakpoints` | Screen map for `sm:`, `md:`, … |
+
+The plugin discovers config by walking up from the processed CSS file.
+
+## VS Code CSS validation
+
+Add to `.vscode/settings.json` so `@apply` and `@skyui` are not flagged as unknown at-rules:
+
+```json
+{
+  "css.customData": ["./node_modules/@sky.ui/utils/skyui.css-data.json"]
+}
+```
+
+Or install the **Sky UI IntelliSense** extension (bundles the same custom data).
+
+## CSS layers and `@skyui` directives
+
+Declare layer order once:
+
+```css
+@layer skyui.base, skyui.components, skyui.utilities;
+@skyui utilities;
+```
+
+| Directive | Purpose |
+| --- | --- |
+| `@apply` | Compose utilities inside component CSS |
+| `@skyui theme { … }` | CSS-first design tokens |
+| `@skyui source "glob"` | Extra scan paths |
+| `@skyui source inline("a b")` | Safelist in CSS |
+| `@skyui reference` | Tokens only in scoped styles (pair with global utilities) |
+| `@skyui utility` / `@skyui variant` | Custom utility or variant |
+| `@skyui plugin "…"` | Load a plugin spec |
+
+## Built-in plugins (`@skyuicss/*`)
+
+| Spec | Role |
+| --- | --- |
+| `@skyuicss/forms` | Form control utilities; optional `formsStrategy`: `class` \| `base` \| `both` |
+| `@skyuicss/typography` | `prose` utilities (`--sky-prose-*` variables) |
+| `@skyuicss/container-queries` | Container-query variants from theme screens |
+
+Short aliases: `forms`, `typography`, `container-queries`.
+
+## Preflight
+
+`theme.preflight`: `true` | `"minimal"` | `"full"` — optional base reset in `@layer skyui.base` (default off).
+
+## Variants (common families)
+
+Responsive (`sm:`, `md:`, `max-sm:`), dark/light, state (`hover:`, `focus:`, `disabled:`), `not-*`, `group-*` / `peer-*`, `starting:`, `aria-*`, arbitrary (`has-[…]:`, `[&…]:`).
+
+Use MCP **`utility_classes`** (`operation: variant_prefixes`) for the full prefix list, **`search_classes`** to browse names, **`check_class`** to validate a token.
+
+## Theme alignment with components
+
+Use MCP **`get_theme`** — start with **`operation: guide`**, then **`fields`** / **`field`** for `userTheme` paths, and **`operation: variables`** for emitted **`--sky-*`** names. Align `skyui.config` `theme.extend` with tokens from **`@sky.ui/core`**. Prefer utility classes for layout/spacing/typography around **`<sky-*>`** elements.
+
+## Styling workflow for assistants
+
+1. **`get_project_guide`** — install + bundler wiring  
+2. **`utility_classes`** — validate and discover class names  
+3. **`get_theme`** — token names for custom theme keys  
+4. **`get_docs`** — `packages/mcp/docs/utils-usage-guide.md` (this file) when needed  
+
+Prefer utility `class` / `className` over large hand-written CSS unless the user asks otherwise.

package/docs/vue-wrapper-v-model.md

@@ -0,0 +1,36 @@
+# Vue wrappers: `v-model` support and usage
+
+## When `v-model` works
+
+Use `v-model` on a `@sky.ui/vue` wrapper **when that component is documented for two-way binding**—confirm the primary value prop and update event in **`get_sky_component_docs`** (props/events surfaces).
+
+If the component does **not** document a two-way pair, treat it as **one-way**: bind with `:prop` / `@event` using the names from those tools. Do not assume `v-model` matches other UI libraries.
+
+## Usage patterns
+
+**Default `v-model`** — when the primary bound prop is the default for that component (often `modelValue` / `value`-style APIs exposed to Vue):
+
+```vue
+<SkyExample v-model="selected" />
+```
+
+**Named `v-model`** — when you bind a specific prop (replace `propName` with the actual prop from docs):
+
+```vue
+<SkyExample v-model:propName="selected" />
+```
+
+**Explicit two-way** — use the prop and event names from docs (`get_component_events`). Payload is on **`CustomEvent.detail`**:
+
+```vue
+<SkyExample :foo="state" @foo-changed="onFooChanged" />
+```
+
+```ts
+function onFooChanged(e: Event) {
+  const detail = (e as CustomEvent).detail;
+  // Map detail to local state using the shape documented for this component.
+}
+```
+
+Sky UI elements expose **`CustomEvent`** payloads on **`detail`**; wrappers follow the same contract where two-way binding applies.

package/package.json

@@ -0,0 +1,63 @@
+{
+  "name": "@sky.ui/mcp",
+  "version": "0.0.1",
+  "private": false,
+  "description": "MCP server for Sky UI — component catalog, docs, theme tokens, and live snippets from library.sky-ui.com for AI coding assistants.",
+  "type": "module",
+  "bin": {
+    "sky-ui-mcp": "dist/mcp-stdio-entry.js"
+  },
+  "exports": {
+    ".": "./dist/server.js",
+    "./docs": "./dist/docs.js",
+    "./package.json": "./package.json"
+  },
+  "license": "SEE LICENSE IN LICENSE.md",
+  "files": [
+    "dist",
+    "data",
+    "docs",
+    "README.md",
+    "LICENSE.md"
+  ],
+  "scripts": {
+    "build": "node ./scripts/gen-chart-api-sections.mjs && node ./scripts/gen-utils-suggestion-fallback.mjs && node ./scripts/gen-reactivity-readme-snapshot.mjs && tsc -p tsconfig.json && node ./scripts/verify-mcp-tool-parity.mjs && node ./scripts/validate-guideline-component-refs.mjs && node ./scripts/scan-guideline-banned-patterns.mjs && npm run check:guideline-coverage",
+    "start": "node ./dist/mcp-stdio-entry.js",
+    "dev": "tsx ./src/server.ts",
+    "serve:post": "tsx ./src/post-endpoint-server.ts",
+    "serve:post:dist": "node ./dist/post-endpoint-server.js",
+    "check:guideline-coverage": "node ./scripts/check-guideline-coverage.mjs",
+    "check:guideline-coverage:strict": "node ./scripts/check-guideline-coverage.mjs --strict",
+    "check:guideline-banned-patterns": "node ./scripts/scan-guideline-banned-patterns.mjs",
+    "clean": "rimraf dist"
+  },
+  "dependencies": {
+    "@fastify/cors": "^11.2.0",
+    "@fastify/rate-limit": "^10.3.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "fastify": "^5.8.5",
+    "typescript": "^5.9.3",
+    "zod": "^3.25.0"
+  },
+  "peerDependencies": {
+    "@sky.ui/core": ">=0.0.1",
+    "@sky.ui/utils": ">=0.0.1"
+  },
+  "peerDependenciesMeta": {
+    "@sky.ui/utils": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/node": "^22.10.0",
+    "rimraf": "^6.1.2",
+    "tsx": "^4.19.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  }
+}