design-canvas-plugin-style-kit 0.1.0 → 0.1.1

package/README.md

@@ -0,0 +1,140 @@
+# Style Kit — Design Canvas Plugin
+
+**Token-aware design tuning for Fluent UI applications.** Explore token scales, override values live, save variations, prompt Copilot for adjustments, and ship changes via GitHub Issues or PRs.
+
+## Features
+
+- **Token Detection** — Automatically identifies the token framework in use (Fluent UI, Material Design, Spectrum, Chakra UI, or custom tokens) and maps element styles to their corresponding design tokens.
+- **Live Override Engine** — Adjust spacing, typography, colors, border radius, shadows, stroke widths, and motion tokens in real time. Changes are applied instantly via CSS custom property overrides.
+- **Scope Control** — Toggle between Global (all elements) and Element-scoped overrides. Pick any element on the canvas to inspect and tune its specific token usage.
+- **Variations** — Save named sets of overrides as variations. Switch between Base and saved variations to compare different design directions.
+- **Copilot Integration** — Natural language prompt bar for AI-powered style adjustments (e.g., *"make it more compact"* or *"darker background"*). Copilot suggests token changes based on your description.
+- **Search & Filter** — Browse all available tokens with search and category filter pills (Spacing, Typography, Colors, Shape, Motion).
+- **Handoff & Export** — Copy CSS overrides, theme partials, or generate a full fix prompt for Copilot. Create GitHub Issues with context screenshots and assign Copilot for automated fixes.
+- **Light/Dark Mode** — Full dark mode support with a dedicated token system (`--sk-*` custom properties) that adapts to the host application's theme.
+- **Accessibility** — ARIA attributes, keyboard navigation, screen reader labels, and semantic roles throughout the panel UI.
+
+## Installation
+
+```bash
+npm install design-canvas-plugin-style-kit
+```
+
+### Peer Dependencies
+
+- `@design-canvas/toolbox` >= 0.1.0
+
+## Usage
+
+Register the plugin with your Design Canvas instance:
+
+```ts
+import plugin from 'design-canvas-plugin-style-kit';
+
+// In your Design Canvas setup:
+canvas.registerPlugin(plugin);
+```
+
+The plugin exposes the standard Design Canvas plugin interface:
+
+```ts
+plugin.meta       // { id, name, icon, description, panel }
+plugin.activate(ctx)   // Mount the panel, start detection
+plugin.deactivate()    // Clean up listeners and DOM
+plugin.getAPI()        // { getOverrides, serializeOverrides, applyOverride, clearAll }
+plugin.getHandoffContext()  // { overrides, css, themePartial }
+```
+
+## Keyboard Shortcut
+
+| Shortcut | Action |
+|----------|--------|
+| `Ctrl+Shift+K` | Toggle Style Kit panel |
+
+## Development
+
+```bash
+# Install dependencies
+npm install
+
+# Start dev harness (Vite + HMR)
+npm run dev:ui
+
+# Build for production
+npm run build
+
+# Watch mode (library output)
+npm run dev
+
+# Validate plugin structure
+npm run validate
+
+# Full verification (structure + types + patterns)
+npm run verify
+```
+
+### Dev Harness
+
+The `dev/` folder contains a standalone test harness that simulates the Design Canvas panel shell. It provides:
+
+- Light/dark theme toggle
+- Sample DOM elements for token detection testing
+- Panel open/close simulation
+- Full HMR via Vite
+
+Open `http://localhost:5174` after running `npm run dev:ui`.
+
+## Architecture
+
+```
+src/
+├── index.ts            # Plugin entry — meta, activate/deactivate, API
+├── panel.ts            # Panel DOM renderer (imperative, no framework)
+├── panel-styles.ts     # All CSS as a template literal with --sk-* tokens
+├── token-registry.ts   # Static token scale definitions + framework detection
+├── token-detector.ts   # Maps element computed styles → token matches
+├── override-engine.ts  # Applies/tracks CSS custom property overrides
+└── variations.ts       # Persistence layer for named override sets
+```
+
+### Token System
+
+The panel uses its own `--sk-*` CSS custom property system for theming:
+
+| Token | Purpose |
+|-------|---------|
+| `--sk-bg` | Panel background |
+| `--sk-bg-subtle` | Section backgrounds |
+| `--sk-bg-accent` | Interactive accents |
+| `--sk-fg` | Primary text |
+| `--sk-fg-secondary` | Secondary text |
+| `--sk-border` | Borders |
+| `--sk-success` | Success states |
+| `--sk-pulse-color` | Animation highlight |
+
+Light and dark values are defined on `.sk` and `.sk.sk--dark` respectively.
+
+## API
+
+### `getOverrides(): TokenOverride[]`
+
+Returns the current list of active token overrides.
+
+### `serializeOverrides(): { overrides, css, themePartial }`
+
+Serializes all active overrides into exportable formats:
+- `overrides` — Structured array with token names, old/new values, scope
+- `css` — Ready-to-paste CSS custom property declarations
+- `themePartial` — Framework-specific theme object partial
+
+### `applyOverride(tokenName, value, scope): void`
+
+Programmatically apply a token override.
+
+### `clearAll(): void`
+
+Remove all active overrides and reset to base values.
+
+## License
+
+MIT

package/dist/chunk-VVT6HXXI.js

@@ -0,0 +1,455 @@
+// src/token-registry.ts
+var SPACING_H_SCALE = [
+  ["None", "0"],
+  ["XXS", "2px"],
+  ["XS", "4px"],
+  ["SNudge", "6px"],
+  ["S", "8px"],
+  ["MNudge", "10px"],
+  ["M", "12px"],
+  ["L", "16px"],
+  ["XL", "20px"],
+  ["XXL", "24px"],
+  ["XXXL", "32px"]
+];
+var SPACING_V_SCALE = SPACING_H_SCALE;
+var FONT_SIZE_SCALE = [
+  ["Base100", "10px"],
+  ["Base200", "12px"],
+  ["Base300", "14px"],
+  ["Base400", "16px"],
+  ["Base500", "20px"],
+  ["Base600", "24px"],
+  ["Hero700", "28px"],
+  ["Hero800", "32px"],
+  ["Hero900", "40px"],
+  ["Hero1000", "68px"]
+];
+var LINE_HEIGHT_SCALE = [
+  ["Base100", "14px"],
+  ["Base200", "16px"],
+  ["Base300", "20px"],
+  ["Base400", "22px"],
+  ["Base500", "28px"],
+  ["Base600", "32px"],
+  ["Hero700", "36px"],
+  ["Hero800", "40px"],
+  ["Hero900", "52px"],
+  ["Hero1000", "92px"]
+];
+var FONT_WEIGHT_SCALE = [
+  ["Regular", "400"],
+  ["Medium", "500"],
+  ["Semibold", "600"],
+  ["Bold", "700"]
+];
+var BORDER_RADIUS_SCALE = [
+  ["None", "0"],
+  ["Small", "2px"],
+  ["Medium", "4px"],
+  ["Large", "6px"],
+  ["XLarge", "8px"],
+  ["2XLarge", "12px"],
+  ["3XLarge", "16px"],
+  ["4XLarge", "24px"],
+  ["5XLarge", "32px"],
+  ["6XLarge", "40px"],
+  ["Circular", "10000px"]
+];
+var STROKE_WIDTH_SCALE = [
+  ["Thin", "1px"],
+  ["Thick", "2px"],
+  ["Thicker", "3px"],
+  ["Thickest", "4px"]
+];
+var SHADOW_SCALE = [
+  "shadow2",
+  "shadow4",
+  "shadow8",
+  "shadow16",
+  "shadow28",
+  "shadow64",
+  "shadow2Brand",
+  "shadow4Brand",
+  "shadow8Brand",
+  "shadow16Brand",
+  "shadow28Brand",
+  "shadow64Brand"
+];
+var DURATION_SCALE = [
+  ["UltraFast", "50ms"],
+  ["Faster", "100ms"],
+  ["Fast", "150ms"],
+  ["Normal", "200ms"],
+  ["Gentle", "250ms"],
+  ["Slow", "300ms"],
+  ["Slower", "400ms"],
+  ["UltraSlow", "500ms"]
+];
+var CURVE_SCALE = [
+  ["AccelerateMax", "cubic-bezier(1,0,1,1)"],
+  ["AccelerateMid", "cubic-bezier(0.7,0,1,0.5)"],
+  ["AccelerateMin", "cubic-bezier(0.8,0,1,1)"],
+  ["DecelerateMax", "cubic-bezier(0,0,0,1)"],
+  ["DecelerateMid", "cubic-bezier(0.1,0.9,0.2,1)"],
+  ["DecelerateMin", "cubic-bezier(0.33,0,0.1,1)"],
+  ["EasyEaseMax", "cubic-bezier(0.8,0,0.1,1)"],
+  ["EasyEase", "cubic-bezier(0.33,0,0.67,1)"],
+  ["Linear", "cubic-bezier(0,0,1,1)"]
+];
+var FONT_FAMILY_NAMES = [
+  "fontFamilyBase",
+  "fontFamilyMonospace",
+  "fontFamilyNumeric"
+];
+var NEUTRAL_BG = [
+  "colorNeutralBackground1",
+  "colorNeutralBackground2",
+  "colorNeutralBackground3",
+  "colorNeutralBackground4",
+  "colorNeutralBackground5",
+  "colorNeutralBackground6",
+  "colorNeutralBackgroundInverted",
+  "colorNeutralBackgroundStatic",
+  "colorSubtleBackground",
+  "colorTransparentBackground"
+];
+var NEUTRAL_FG = [
+  "colorNeutralForeground1",
+  "colorNeutralForeground2",
+  "colorNeutralForeground3",
+  "colorNeutralForeground4",
+  "colorNeutralForegroundDisabled"
+];
+var BRAND_BG = [
+  "colorBrandBackground",
+  "colorBrandBackground2",
+  "colorBrandBackgroundInverted",
+  "colorBrandBackgroundStatic"
+];
+var BRAND_FG = [
+  "colorBrandForegroundLink",
+  "colorBrandForeground1",
+  "colorBrandForeground2",
+  "colorBrandForegroundInverted"
+];
+var NEUTRAL_STROKE = [
+  "colorNeutralStroke1",
+  "colorNeutralStroke2",
+  "colorNeutralStroke3",
+  "colorNeutralStrokeSubtle",
+  "colorNeutralStrokeDisabled",
+  "colorNeutralStrokeAccessible"
+];
+var BRAND_STROKE = [
+  "colorBrandStroke1",
+  "colorBrandStroke2",
+  "colorCompoundBrandStroke"
+];
+function resolveVar(cssVar) {
+  const provider = document.querySelector(".fui-FluentProvider") ?? document.documentElement;
+  return getComputedStyle(provider).getPropertyValue(cssVar).trim();
+}
+function buildScale(category, label, prefix, entries) {
+  return {
+    category,
+    label,
+    entries: entries.map(([suffix, fallback]) => {
+      const name = `${prefix}${suffix}`;
+      const cssVar = `--${name}`;
+      const value = resolveVar(cssVar) || fallback;
+      return { name, cssVar, value, label: suffix };
+    })
+  };
+}
+function buildColorScale(category, label, names) {
+  return {
+    category,
+    label,
+    entries: names.map((name) => {
+      const cssVar = `--${name}`;
+      const value = resolveVar(cssVar) || "#000";
+      const short = name.replace("colorNeutral", "").replace("colorBrand", "").replace("colorCompound", "").replace("colorSubtle", "Subtle").replace("colorTransparent", "Transparent");
+      return { name, cssVar, value, label: short };
+    })
+  };
+}
+function buildShadowScale() {
+  return {
+    category: "shadow",
+    label: "Shadow",
+    entries: SHADOW_SCALE.map((name) => {
+      const cssVar = `--${name}`;
+      const value = resolveVar(cssVar) || "0 0 0 rgba(0,0,0,0)";
+      const short = name.replace("shadow", "").replace("Brand", " Brand") || name;
+      return { name, cssVar, value, label: short };
+    })
+  };
+}
+function buildFontFamilyScale() {
+  return {
+    category: "fontFamily",
+    label: "Font Family",
+    entries: FONT_FAMILY_NAMES.map((name) => {
+      const cssVar = `--${name}`;
+      const value = resolveVar(cssVar) || "";
+      const short = name.replace("fontFamily", "");
+      return { name, cssVar, value, label: short };
+    })
+  };
+}
+function buildRegistry() {
+  return [
+    buildScale("spacingH", "Horizontal Spacing", "spacingHorizontal", SPACING_H_SCALE),
+    buildScale("spacingV", "Vertical Spacing", "spacingVertical", SPACING_V_SCALE),
+    buildScale("fontSize", "Font Size", "fontSize", FONT_SIZE_SCALE),
+    buildScale("lineHeight", "Line Height", "lineHeight", LINE_HEIGHT_SCALE),
+    buildScale("fontWeight", "Font Weight", "fontWeight", FONT_WEIGHT_SCALE),
+    buildScale("borderRadius", "Border Radius", "borderRadius", BORDER_RADIUS_SCALE),
+    buildScale("strokeWidth", "Stroke Width", "strokeWidth", STROKE_WIDTH_SCALE),
+    buildShadowScale(),
+    buildFontFamilyScale(),
+    buildScale("duration", "Duration", "duration", DURATION_SCALE),
+    buildScale("curve", "Timing Curve", "curve", CURVE_SCALE),
+    buildColorScale("colorNeutralBg", "Neutral Background", NEUTRAL_BG),
+    buildColorScale("colorNeutralFg", "Neutral Foreground", NEUTRAL_FG),
+    buildColorScale("colorBrandBg", "Brand Background", BRAND_BG),
+    buildColorScale("colorBrandFg", "Brand Foreground", BRAND_FG),
+    buildColorScale("colorNeutralStroke", "Neutral Stroke", NEUTRAL_STROKE),
+    buildColorScale("colorBrandStroke", "Brand Stroke", BRAND_STROKE)
+  ];
+}
+function findToken(registry, tokenName) {
+  for (const scale of registry) {
+    const idx = scale.entries.findIndex((e) => e.name === tokenName);
+    if (idx !== -1) return { scale, index: idx };
+  }
+  return null;
+}
+function getResolvedValue(cssVar) {
+  return resolveVar(cssVar);
+}
+function serializeForPrompt(registry) {
+  return registry.map(
+    (s) => `${s.label}: ${s.entries.map((e) => `${e.label}=${e.value}`).join(", ")}`
+  ).join("\n");
+}
+
+// src/override-engine.ts
+var STYLE_ID = "dc-style-kit-overrides";
+var activeOverrides = /* @__PURE__ */ new Map();
+var activeStaticOverrides = /* @__PURE__ */ new Map();
+var listeners = [];
+function getOrCreateStyleEl() {
+  let el = document.getElementById(STYLE_ID);
+  if (!el) {
+    el = document.createElement("style");
+    el.id = STYLE_ID;
+    el.setAttribute("data-design-canvas", "style-kit");
+    document.body.appendChild(el);
+  }
+  return el;
+}
+function overrideKey(o) {
+  const scopeKey = o.scope.type === "global" ? "_global_" : o.scope.selector;
+  return `${scopeKey}::${o.tokenName}`;
+}
+function staticKey(o) {
+  const scopeKey = o.scope.type === "global" ? "_global_" : o.scope.selector;
+  return `${scopeKey}::static::${o.property}`;
+}
+var TOKEN_TO_CSS_PROPERTY = {
+  fontSize: "font-size",
+  fontWeight: "font-weight",
+  lineHeight: "line-height",
+  fontFamily: "font-family",
+  spacingHorizontal: "padding-inline",
+  spacingVertical: "padding-block",
+  borderRadius: "border-radius",
+  strokeWidth: "border-width",
+  colorNeutralBackground: "background-color",
+  colorBrandBackground: "background-color",
+  colorSubtleBackground: "background-color",
+  colorTransparentBackground: "background-color",
+  colorNeutralForeground: "color",
+  colorBrandForeground: "color",
+  colorNeutralStroke: "border-color",
+  colorBrandStroke: "border-color",
+  colorPaletteRedBackground: "background-color",
+  colorPaletteRedForeground: "color",
+  colorPaletteRedBorder: "border-color",
+  colorPaletteGreenBackground: "background-color",
+  colorPaletteGreenForeground: "color",
+  colorPaletteGreenBorder: "border-color",
+  colorPaletteYellowBackground: "background-color",
+  colorPaletteYellowForeground: "color",
+  colorPaletteBlueForeground: "color",
+  colorPaletteBlueBackground: "background-color",
+  colorPaletteBlueBorder: "border-color",
+  shadow: "box-shadow"
+};
+function cssPropertyForToken(tokenName) {
+  for (const [prefix, prop] of Object.entries(TOKEN_TO_CSS_PROPERTY)) {
+    if (tokenName.startsWith(prefix)) return prop;
+  }
+  return null;
+}
+function renderCSS() {
+  const el = getOrCreateStyleEl();
+  const byScope = /* @__PURE__ */ new Map();
+  for (const o of activeOverrides.values()) {
+    const key = o.scope.type === "global" ? "_global_" : o.scope.selector;
+    if (!byScope.has(key)) byScope.set(key, { tokens: [], statics: [] });
+    byScope.get(key).tokens.push(o);
+  }
+  for (const o of activeStaticOverrides.values()) {
+    const key = o.scope.type === "global" ? "_global_" : o.scope.selector;
+    if (!byScope.has(key)) byScope.set(key, { tokens: [], statics: [] });
+    byScope.get(key).statics.push(o);
+  }
+  let css = "/* Style Kit overrides \u2014 auto-generated */\n";
+  for (const [scopeKey, { tokens, statics }] of byScope) {
+    const isGlobal = scopeKey === "_global_";
+    const selector = isGlobal ? ".fui-FluentProvider" : scopeKey;
+    const tokenProps = tokens.map((o) => `  ${o.cssVar}: ${o.newValue};`).join("\n");
+    const concreteProps = isGlobal ? "" : tokens.map((o) => {
+      const prop = cssPropertyForToken(o.tokenName);
+      return prop ? `  ${prop}: ${o.newValue} !important;` : "";
+    }).filter(Boolean).join("\n");
+    const staticProps = statics.map((o) => `  ${o.property}: ${o.newValue} !important;`).join("\n");
+    const allProps = [tokenProps, concreteProps, staticProps].filter(Boolean).join("\n");
+    css += `${selector} {
+${allProps}
+}
+`;
+  }
+  el.textContent = css;
+  notify();
+}
+function notify() {
+  const list = Array.from(activeOverrides.values());
+  for (const fn of listeners) fn(list);
+}
+function applyOverride(override) {
+  const key = overrideKey(override);
+  activeOverrides.set(key, override);
+  renderCSS();
+}
+function removeOverride(tokenName, scope) {
+  const key = overrideKey({ tokenName, scope });
+  activeOverrides.delete(key);
+  renderCSS();
+}
+function getOverrides() {
+  return Array.from(activeOverrides.values());
+}
+function getOverrideForToken(tokenName, scope) {
+  return activeOverrides.get(overrideKey({ tokenName, scope }));
+}
+function clearAll() {
+  activeOverrides.clear();
+  activeStaticOverrides.clear();
+  renderCSS();
+}
+function bulkApply(overrides) {
+  for (const o of overrides) {
+    activeOverrides.set(overrideKey(o), o);
+  }
+  renderCSS();
+}
+function bulkReplace(overrides) {
+  activeOverrides.clear();
+  for (const o of overrides) {
+    activeOverrides.set(overrideKey(o), o);
+  }
+  renderCSS();
+}
+function onOverridesChanged(fn) {
+  listeners.push(fn);
+  return () => {
+    listeners = listeners.filter((l) => l !== fn);
+  };
+}
+function applyStaticOverride(override) {
+  const key = staticKey(override);
+  activeStaticOverrides.set(key, override);
+  renderCSS();
+}
+function removeStaticOverride(property, scope) {
+  const key = staticKey({ property, scope });
+  activeStaticOverrides.delete(key);
+  renderCSS();
+}
+function getStaticOverrideForProperty(property, scope) {
+  return activeStaticOverrides.get(staticKey({ property, scope }));
+}
+function getStaticOverridesList() {
+  return Array.from(activeStaticOverrides.values());
+}
+function serializeOverrides() {
+  const list = getOverrides();
+  const staticList = getStaticOverridesList();
+  const registry = buildRegistry();
+  const tokenEntries = list.map((o) => {
+    const entry = {
+      token: o.tokenName,
+      from: o.originalValue,
+      to: o.newValue,
+      scope: o.scope.type === "global" ? "Global" : o.scope.label
+    };
+    const match = findToken(registry, o.tokenName);
+    if (match) {
+      const swapTarget = match.scale.entries.find(
+        (e) => e.value === o.newValue && e.name !== o.tokenName
+      );
+      if (swapTarget) {
+        entry.swapTo = swapTarget.name;
+      }
+    }
+    return entry;
+  });
+  const staticEntries = staticList.map((o) => ({
+    token: `[static] ${o.property}`,
+    from: o.originalValue,
+    to: o.newValue,
+    scope: o.scope.type === "global" ? "Global" : o.scope.label
+  }));
+  const overrides = [...tokenEntries, ...staticEntries];
+  const css = getOrCreateStyleEl().textContent ?? "";
+  const globalOverrides = list.filter((o) => o.scope.type === "global");
+  const themeLines = globalOverrides.map(
+    (o) => `  ${o.tokenName}: '${o.newValue}',`
+  );
+  const themePartial = `const themeOverrides = {
+${themeLines.join("\n")}
+};`;
+  return { overrides, css, themePartial };
+}
+function destroy() {
+  activeOverrides.clear();
+  activeStaticOverrides.clear();
+  listeners = [];
+  const el = document.getElementById(STYLE_ID);
+  el?.remove();
+}
+
+export {
+  buildRegistry,
+  findToken,
+  getResolvedValue,
+  serializeForPrompt,
+  applyOverride,
+  removeOverride,
+  getOverrides,
+  getOverrideForToken,
+  clearAll,
+  bulkApply,
+  bulkReplace,
+  onOverridesChanged,
+  applyStaticOverride,
+  removeStaticOverride,
+  getStaticOverrideForProperty,
+  getStaticOverridesList,
+  serializeOverrides,
+  destroy
+};

package/dist/index.d.ts

@@ -1,30 +1,5 @@
-declare const plugin: {
-    meta: {
-        id: string;
-        name: string;
-        icon: string;
-        description: string;
-        version: string;
-        panel: {
-            defaultWidth: number;
-            defaultHeight: number;
-            minWidth: number;
-            minHeight: number;
-        };
-    };
-    activate(ctx: any): void;
-    deactivate(): void;
-    getHandoffContext(): {
-        overrides: Array<{
-            token: string;
-            from: string;
-            to: string;
-            scope: string;
-            swapTo?: string;
-        }>;
-        css: string;
-        themePartial: string;
-    };
-};
+import { PluginDefinition } from './types.js';
+
+declare const plugin: PluginDefinition;
 
 export { plugin as default };