@treeui/mcp 0.4.1 → 0.6.0

package/dist/index.d.cts

@@ -46,6 +46,7 @@ interface TreeuiComponentEntry {
     selection: TreeuiSelectionProfile;
     setup: TreeuiComponentSetup;
     recipes: string[];
+    practices: string[];
 }
 interface TreeuiDecisionGuideOption {
     use: string;
@@ -64,6 +65,13 @@ interface TreeuiRecipe {
     compose: string[];
     notes: string[];
 }
+interface TreeuiPractice {
+    id: string;
+    title: string;
+    summary: string;
+    rules: string[];
+    components: string[];
+}
 interface TreeuiSetupEntry {
     install: {
         packageManagerExamples: Record<string, string>;
@@ -90,14 +98,25 @@ interface TreeuiSetupEntry {
         commonCompositions: string[];
     };
 }
+interface TreeuiTokenEntry {
+    cssVar: string;
+    path: string;
+    value: string;
+    category: string;
+    description?: string;
+    /** Per-theme values for tokens that change with `[data-tree-theme]`. */
+    themeValues?: Record<string, string>;
+}
 interface TreeuiCatalog {
     generatedAt: string;
     packageName: string;
     packageVersion: string;
     decisionGuides: TreeuiDecisionGuide[];
     recipes: TreeuiRecipe[];
+    practices: TreeuiPractice[];
     setup: TreeuiSetupEntry;
     components: TreeuiComponentEntry[];
+    tokens: TreeuiTokenEntry[];
 }
 interface TreeuiSearchResult {
     component: TreeuiComponentEntry;
@@ -108,20 +127,33 @@ interface TreeuiRecipeSearchResult {
     recipe: TreeuiRecipe;
     score: number;
 }
+interface TreeuiTokenSearchResult {
+    token: TreeuiTokenEntry;
+    score: number;
+}
 
 declare const catalog: TreeuiCatalog;
 declare const findComponent: (name: string) => TreeuiComponentEntry | undefined;
 declare const searchComponents: (query: string, limit?: number) => TreeuiSearchResult[];
 declare const recommendComponents: (task: string, limit?: number) => TreeuiSearchResult[];
 declare const searchRecipes: (query: string, limit?: number) => TreeuiRecipeSearchResult[];
+declare const searchTokens: (query: string, limit?: number) => TreeuiTokenSearchResult[];
 declare const formatComponentSummary: (component: TreeuiComponentEntry) => string;
 declare const formatSearchResults: (results: TreeuiSearchResult[]) => string;
 declare const formatRecipeResults: (results: TreeuiRecipeSearchResult[]) => string;
+declare const formatTokenResults: (results: TreeuiTokenSearchResult[]) => string;
 declare const formatSetupGuide: (componentName?: string) => string;
 
 declare const buildCatalogFromRepo: (repoRoot: string) => TreeuiCatalog;
 declare const getRepoRootFromPackageRoot: (packageRoot: string) => string;
 
+/**
+ * Flatten the design tokens into catalog entries. Foundation tokens carry a
+ * single value; themed tokens carry one value per theme plus the default-theme
+ * value on `value`.
+ */
+declare const buildTokenEntries: () => TreeuiTokenEntry[];
+
 declare const createTreeuiMcpServer: () => Server<{
     method: string;
     params?: {
@@ -157,4 +189,4 @@ declare const createTreeuiMcpServer: () => Server<{
     } | undefined;
 }>;
 
-export { type TreeuiCatalog, type TreeuiCatalogField, type TreeuiComponentEntry, type TreeuiDecisionGuide, type TreeuiRecipe, type TreeuiSearchResult, type TreeuiSetupEntry, buildCatalogFromRepo, catalog, createTreeuiMcpServer, findComponent, formatComponentSummary, formatRecipeResults, formatSearchResults, formatSetupGuide, getRepoRootFromPackageRoot, recommendComponents, searchComponents, searchRecipes };
+export { type TreeuiCatalog, type TreeuiCatalogField, type TreeuiComponentEntry, type TreeuiDecisionGuide, type TreeuiRecipe, type TreeuiSearchResult, type TreeuiSetupEntry, type TreeuiTokenEntry, type TreeuiTokenSearchResult, buildCatalogFromRepo, buildTokenEntries, catalog, createTreeuiMcpServer, findComponent, formatComponentSummary, formatRecipeResults, formatSearchResults, formatSetupGuide, formatTokenResults, getRepoRootFromPackageRoot, recommendComponents, searchComponents, searchRecipes, searchTokens };

package/dist/index.d.ts

@@ -46,6 +46,7 @@ interface TreeuiComponentEntry {
     selection: TreeuiSelectionProfile;
     setup: TreeuiComponentSetup;
     recipes: string[];
+    practices: string[];
 }
 interface TreeuiDecisionGuideOption {
     use: string;
@@ -64,6 +65,13 @@ interface TreeuiRecipe {
     compose: string[];
     notes: string[];
 }
+interface TreeuiPractice {
+    id: string;
+    title: string;
+    summary: string;
+    rules: string[];
+    components: string[];
+}
 interface TreeuiSetupEntry {
     install: {
         packageManagerExamples: Record<string, string>;
@@ -90,14 +98,25 @@ interface TreeuiSetupEntry {
         commonCompositions: string[];
     };
 }
+interface TreeuiTokenEntry {
+    cssVar: string;
+    path: string;
+    value: string;
+    category: string;
+    description?: string;
+    /** Per-theme values for tokens that change with `[data-tree-theme]`. */
+    themeValues?: Record<string, string>;
+}
 interface TreeuiCatalog {
     generatedAt: string;
     packageName: string;
     packageVersion: string;
     decisionGuides: TreeuiDecisionGuide[];
     recipes: TreeuiRecipe[];
+    practices: TreeuiPractice[];
     setup: TreeuiSetupEntry;
     components: TreeuiComponentEntry[];
+    tokens: TreeuiTokenEntry[];
 }
 interface TreeuiSearchResult {
     component: TreeuiComponentEntry;
@@ -108,20 +127,33 @@ interface TreeuiRecipeSearchResult {
     recipe: TreeuiRecipe;
     score: number;
 }
+interface TreeuiTokenSearchResult {
+    token: TreeuiTokenEntry;
+    score: number;
+}
 
 declare const catalog: TreeuiCatalog;
 declare const findComponent: (name: string) => TreeuiComponentEntry | undefined;
 declare const searchComponents: (query: string, limit?: number) => TreeuiSearchResult[];
 declare const recommendComponents: (task: string, limit?: number) => TreeuiSearchResult[];
 declare const searchRecipes: (query: string, limit?: number) => TreeuiRecipeSearchResult[];
+declare const searchTokens: (query: string, limit?: number) => TreeuiTokenSearchResult[];
 declare const formatComponentSummary: (component: TreeuiComponentEntry) => string;
 declare const formatSearchResults: (results: TreeuiSearchResult[]) => string;
 declare const formatRecipeResults: (results: TreeuiRecipeSearchResult[]) => string;
+declare const formatTokenResults: (results: TreeuiTokenSearchResult[]) => string;
 declare const formatSetupGuide: (componentName?: string) => string;
 
 declare const buildCatalogFromRepo: (repoRoot: string) => TreeuiCatalog;
 declare const getRepoRootFromPackageRoot: (packageRoot: string) => string;
 
+/**
+ * Flatten the design tokens into catalog entries. Foundation tokens carry a
+ * single value; themed tokens carry one value per theme plus the default-theme
+ * value on `value`.
+ */
+declare const buildTokenEntries: () => TreeuiTokenEntry[];
+
 declare const createTreeuiMcpServer: () => Server<{
     method: string;
     params?: {
@@ -157,4 +189,4 @@ declare const createTreeuiMcpServer: () => Server<{
     } | undefined;
 }>;
 
-export { type TreeuiCatalog, type TreeuiCatalogField, type TreeuiComponentEntry, type TreeuiDecisionGuide, type TreeuiRecipe, type TreeuiSearchResult, type TreeuiSetupEntry, buildCatalogFromRepo, catalog, createTreeuiMcpServer, findComponent, formatComponentSummary, formatRecipeResults, formatSearchResults, formatSetupGuide, getRepoRootFromPackageRoot, recommendComponents, searchComponents, searchRecipes };
+export { type TreeuiCatalog, type TreeuiCatalogField, type TreeuiComponentEntry, type TreeuiDecisionGuide, type TreeuiRecipe, type TreeuiSearchResult, type TreeuiSetupEntry, type TreeuiTokenEntry, type TreeuiTokenSearchResult, buildCatalogFromRepo, buildTokenEntries, catalog, createTreeuiMcpServer, findComponent, formatComponentSummary, formatRecipeResults, formatSearchResults, formatSetupGuide, formatTokenResults, getRepoRootFromPackageRoot, recommendComponents, searchComponents, searchRecipes, searchTokens };

package/dist/index.js

@@ -6,15 +6,302 @@ import {
   formatRecipeResults,
   formatSearchResults,
   formatSetupGuide,
+  formatTokenResults,
   recommendComponents,
   searchComponents,
-  searchRecipes
-} from "./chunk-UPSK3E4U.js";
+  searchRecipes,
+  searchTokens
+} from "./chunk-ITEC3SEF.js";
 
 // src/catalog-source.ts
 import fs from "fs";
 import path from "path";
 import { parseAllDocuments } from "yaml";
+
+// ../tokens/src/tokens.ts
+var treeTokens = {
+  font: {
+    family: {
+      sans: "'Google Sans Flex', 'Segoe UI', sans-serif",
+      mono: "'Google Sans Code', 'SFMono-Regular', monospace"
+    },
+    size: {
+      xs: "0.6875rem",
+      sm: "0.8125rem",
+      md: "0.9375rem",
+      base: "0.9375rem",
+      lg: "1.125rem",
+      xl: "1.375rem",
+      "2xl": "1.375rem",
+      "3xl": "1.75rem",
+      "4xl": "2.25rem",
+      "5xl": "3rem"
+    },
+    weight: {
+      regular: "400",
+      medium: "500",
+      semibold: "600",
+      bold: "700",
+      extrabold: "800"
+    },
+    lineHeight: {
+      compact: "1.1",
+      ui: "1.15",
+      tight: "1.25",
+      heading: "1.3",
+      base: "1.5",
+      body: "1.6",
+      relaxed: "1.65"
+    }
+  },
+  space: {
+    0: "0",
+    1: "0.25rem",
+    2: "0.5rem",
+    3: "0.75rem",
+    4: "1rem",
+    5: "1.25rem",
+    6: "1.5rem",
+    8: "2rem",
+    12: "3rem",
+    16: "4rem"
+  },
+  radius: {
+    sm: "0.375rem",
+    md: "0.625rem",
+    lg: "0.875rem",
+    pill: "999px"
+  },
+  shadow: {
+    xs: "0 1px 2px rgba(15, 23, 42, 0.06)",
+    sm: "0 6px 18px rgba(15, 23, 42, 0.08)",
+    md: "0 14px 34px rgba(15, 23, 42, 0.12)"
+  },
+  // Brand gradient for high-emphasis surfaces (e.g. the primary CTA).
+  // References the theme brand vars so it follows light/dark automatically;
+  // override `--tree-gradient-brand` to match a product's marketing gradient.
+  gradient: {
+    brand: "linear-gradient(135deg, var(--tree-color-brand-primary), var(--tree-color-brand-hover))"
+  },
+  border: {
+    width: {
+      subtle: "1px",
+      strong: "1.5px"
+    }
+  },
+  motion: {
+    duration: {
+      fast: "100ms",
+      moderate: "200ms",
+      normal: "300ms",
+      slow: "400ms",
+      slower: "500ms"
+    },
+    easing: {
+      standard: "cubic-bezier(0.2, 0, 0, 1)",
+      easeOut: "cubic-bezier(0, 0, 0.2, 1)",
+      easeInOut: "cubic-bezier(0.4, 0, 0.2, 1)",
+      easeIn: "cubic-bezier(0.4, 0, 1, 1)"
+    }
+  },
+  size: {
+    control: {
+      sm: "2rem",
+      md: "2.5rem",
+      lg: "3rem"
+    },
+    icon: {
+      sm: "1rem",
+      md: "1.25rem",
+      lg: "1.5rem",
+      xl: "2rem",
+      "2xl": "3rem"
+    }
+  },
+  layout: {
+    grid: {
+      columns: "12",
+      base: "8px"
+    },
+    gutter: {
+      sm: "1rem",
+      md: "1.5rem"
+    },
+    margin: {
+      sm: "1.5rem",
+      md: "2rem",
+      lg: "3rem"
+    }
+  },
+  z: {
+    base: "1",
+    dropdown: "1000",
+    popover: "1050",
+    sticky: "1100",
+    overlay: "1200",
+    modal: "1300",
+    toast: "1400"
+  },
+  breakpoint: {
+    sm: "640px",
+    md: "768px",
+    lg: "1024px",
+    xl: "1280px"
+  }
+};
+var treeThemes = {
+  light: {
+    color: {
+      bg: {
+        primary: "#f6f8fa",
+        surface: "#ffffff",
+        subtle: "#eff2f5"
+      },
+      border: {
+        default: "#d0d7de",
+        strong: "#afb8c1"
+      },
+      text: {
+        primary: "#1f2328",
+        muted: "#59636e",
+        inverse: "#ffffff"
+      },
+      brand: {
+        primary: "#0969da",
+        hover: "#0550ae",
+        soft: "#ddf4ff",
+        contrast: "#ffffff"
+      },
+      status: {
+        success: "#1a7f37",
+        warning: "#9a6700",
+        error: "#d1242f",
+        info: "#0969da"
+      },
+      // Categorical data-viz palette. Fixed hue order (blue → orange), validated
+      // for CVD separation and contrast against the light surface. Assign in order;
+      // the components cycle after 8 as a fallback, but prefer folding a 9th+
+      // category into "Other".
+      chart: {
+        1: "#2a78d6",
+        2: "#1baf7a",
+        3: "#eda100",
+        4: "#008300",
+        5: "#4a3aa7",
+        6: "#e34948",
+        7: "#e87ba4",
+        8: "#eb6834"
+      },
+      overlay: "rgba(31, 35, 40, 0.5)",
+      "focus-ring": "rgba(9, 105, 218, 0.32)"
+    }
+  },
+  dark: {
+    color: {
+      bg: {
+        primary: "#1c2128",
+        surface: "#22272e",
+        subtle: "#2d333b"
+      },
+      border: {
+        default: "#444c56",
+        strong: "#576270"
+      },
+      text: {
+        primary: "#adbac7",
+        muted: "#95a3b2",
+        inverse: "#1c2128"
+      },
+      brand: {
+        primary: "#539bf5",
+        hover: "#6cabf7",
+        soft: "#1a3453",
+        contrast: "#0a1a2f"
+      },
+      status: {
+        success: "#57ab5a",
+        warning: "#c69026",
+        error: "#f47067",
+        info: "#6cb6ff"
+      },
+      // Same hue order stepped for the dark surface (not a separate palette) —
+      // each step re-validated for the dark band and >= 3:1 on the dark surface.
+      chart: {
+        1: "#3987e5",
+        2: "#199e70",
+        3: "#c98500",
+        4: "#008300",
+        5: "#9085e9",
+        6: "#e66767",
+        7: "#d55181",
+        8: "#d95926"
+      },
+      overlay: "rgba(13, 17, 23, 0.6)",
+      "focus-ring": "rgba(83, 155, 245, 0.32)"
+    }
+  }
+};
+
+// src/token-source.ts
+var toCssVariable = (path2) => `--tree-${path2.join("-")}`;
+var flattenTokens = (record, path2 = []) => Object.entries(record).flatMap(([key, value]) => {
+  if (typeof value === "string" || typeof value === "number") {
+    return [[[...path2, key], value]];
+  }
+  return flattenTokens(value, [...path2, key]);
+});
+var DEFAULT_THEME_NAME = "light";
+var categoryDescriptions = {
+  font: "Typography token: font family, size, weight, or line height.",
+  space: "Spacing scale step for padding, margin, and gap.",
+  radius: "Corner radius scale step.",
+  shadow: "Elevation shadow.",
+  gradient: "Gradient composed from the themed brand variables.",
+  border: "Border width step.",
+  motion: "Motion duration or easing curve.",
+  size: "Control and icon sizing scale step.",
+  layout: "Layout grid, gutter, or margin measurement.",
+  z: "Stacking layer (z-index).",
+  breakpoint: "Responsive breakpoint width.",
+  color: "Themed semantic color, resolved per [data-tree-theme]."
+};
+var describeToken = (category) => categoryDescriptions[category] ?? "TreeUI design token.";
+var buildTokenEntries = () => {
+  const foundation = flattenTokens(treeTokens).map(
+    ([path2, value]) => ({
+      cssVar: toCssVariable(path2),
+      path: path2.join("."),
+      value: String(value),
+      category: path2[0],
+      description: describeToken(path2[0])
+    })
+  );
+  const themed = /* @__PURE__ */ new Map();
+  for (const [themeName, theme] of Object.entries(treeThemes)) {
+    for (const [path2, value] of flattenTokens(theme)) {
+      const cssVar = toCssVariable(path2);
+      const existing = themed.get(cssVar);
+      if (existing) {
+        existing.themeValues = { ...existing.themeValues, [themeName]: String(value) };
+        continue;
+      }
+      themed.set(cssVar, {
+        cssVar,
+        path: path2.join("."),
+        value: String(value),
+        category: path2[0],
+        description: describeToken(path2[0]),
+        themeValues: { [themeName]: String(value) }
+      });
+    }
+  }
+  for (const entry of themed.values()) {
+    entry.value = entry.themeValues?.[DEFAULT_THEME_NAME] ?? entry.value;
+  }
+  return [...foundation, ...themed.values()];
+};
+
+// src/catalog-source.ts
 var readText = (filePath) => fs.readFileSync(filePath, "utf8");
 var normalizeWhitespace = (value) => value.replace(/\s+/g, " ").trim();
 var stringifyValue = (value) => {
@@ -225,6 +512,21 @@ var normalizeRecipes = (value) => {
     };
   });
 };
+var normalizePractices = (value) => {
+  if (!Array.isArray(value)) {
+    return [];
+  }
+  return value.map((practice) => {
+    const record = practice;
+    return {
+      id: String(record.id),
+      title: String(record.title),
+      summary: stringifyValue(record.summary) ?? "",
+      rules: normalizeStringList(record.rules),
+      components: normalizeStringList(record.components)
+    };
+  });
+};
 var loadYamlDocuments = (filePath) => parseAllDocuments(readText(filePath)).map((document) => document.toJSON()).filter((document) => Boolean(document));
 var buildStoryIndex = (repoRoot) => {
   const storiesDir = path.join(repoRoot, "apps/docs/src/stories");
@@ -263,10 +565,12 @@ var buildCatalogFromRepo = (repoRoot) => {
   const setupDoc = loadYamlDocuments(path.join(docsDir, "SETUP.yaml"))[0] ?? {};
   const recipesDoc = loadYamlDocuments(path.join(docsDir, "RECIPES.yaml"))[0] ?? {};
   const contractsDoc = loadYamlDocuments(path.join(docsDir, "CONTRACTS.yaml"))[0] ?? {};
+  const practicesDoc = JSON.parse(readText(path.join(docsDir, "practices.json")));
   const componentProfiles = selectionDoc.component_profiles ?? {};
   const componentSetup = setupDoc.component_setup ?? {};
   const aliasMap = contractsDoc.compatibility_aliases ?? {};
   const recipes = normalizeRecipes(recipesDoc.recipes);
+  const practices = normalizePractices(practicesDoc.practices);
   const components = fs.readdirSync(componentsDir).filter((fileName) => fileName.endsWith(".yaml")).flatMap((fileName) => {
     const filePath = path.join(componentsDir, fileName);
     return loadYamlDocuments(filePath).flatMap((document) => {
@@ -285,6 +589,7 @@ var buildCatalogFromRepo = (repoRoot) => {
         )
       );
       const componentRecipes = recipes.filter((recipe) => recipe.compose.includes(name)).map((recipe) => recipe.id);
+      const componentPractices = practices.filter((practice) => practice.components.includes(name)).map((practice) => practice.id);
       const entry = {
         name,
         legacyAlias: aliasMap[name] ?? aliases.find((alias) => alias.startsWith("Tree")),
@@ -306,7 +611,8 @@ var buildCatalogFromRepo = (repoRoot) => {
         behavior: normalizeStringList(document.behavior),
         selection,
         setup: setup2,
-        recipes: componentRecipes
+        recipes: componentRecipes,
+        practices: componentPractices
       };
       return [entry];
     });
@@ -349,13 +655,16 @@ var buildCatalogFromRepo = (repoRoot) => {
     packageVersion: vuePackage.version,
     decisionGuides: normalizeDecisionGuides(selectionDoc.decision_guides),
     recipes,
+    practices,
     setup,
-    components
+    components,
+    tokens: buildTokenEntries()
   };
 };
 var getRepoRootFromPackageRoot = (packageRoot) => path.resolve(packageRoot, "../..");
 export {
   buildCatalogFromRepo,
+  buildTokenEntries,
   catalog,
   createTreeuiMcpServer,
   findComponent,
@@ -363,8 +672,10 @@ export {
   formatRecipeResults,
   formatSearchResults,
   formatSetupGuide,
+  formatTokenResults,
   getRepoRootFromPackageRoot,
   recommendComponents,
   searchComponents,
-  searchRecipes
+  searchRecipes,
+  searchTokens
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@treeui/mcp",
-  "version": "0.4.1",
+  "version": "0.6.0",
   "description": "Model Context Protocol server and AI catalog for TreeUI.",
   "type": "module",
   "main": "./dist/index.cjs",