@xferops/design-guide 0.2.1

package/README.md

@@ -0,0 +1,30 @@
+# @xferops/design-guide
+
+MCP server and query helpers for XferOps frontend design guidance.
+
+## What It Provides
+
+- MCP tools for searching and reading guides
+- MCP resources with stable URIs like `guide://table/sorting`
+- Bundled markdown guide content that ships with the package
+- Coverage for app setup, token theming, layout/content primitives, forms, navigation, overlays, feedback states, and table patterns
+
+## Local Usage
+
+```bash
+pnpm --filter @xferops/design-guide build
+node packages/design-guide/dist/server.js
+```
+
+## MCP Client Example
+
+```json
+{
+  "mcpServers": {
+    "xferops-design-guide": {
+      "command": "npx",
+      "args": ["-y", "@xferops/design-guide"]
+    }
+  }
+}
+```

package/dist/chunk-R4AEJOIP.js

@@ -0,0 +1,161 @@
+#!/usr/bin/env node
+
+// src/guides/frontmatter.ts
+function parseFrontmatter(markdown) {
+  const match = markdown.match(/^---\n([\s\S]*?)\n---\n?([\s\S]*)$/);
+  if (!match) {
+    throw new Error("Guide file is missing frontmatter.");
+  }
+  const [, frontmatterBlock, content] = match;
+  const metadata = parseFrontmatterBlock(frontmatterBlock);
+  validateMetadata(metadata);
+  return {
+    metadata,
+    content: content.trimStart()
+  };
+}
+function parseFrontmatterBlock(block) {
+  const result = {};
+  const lines = block.split("\n");
+  for (let index = 0; index < lines.length; index += 1) {
+    const line = lines[index];
+    if (!line.trim()) continue;
+    const keyMatch = line.match(/^([A-Za-z0-9]+):(?:\s*(.*))?$/);
+    if (!keyMatch) {
+      throw new Error(`Unsupported frontmatter line: ${line}`);
+    }
+    const [, key, rawValue = ""] = keyMatch;
+    if (rawValue.trim()) {
+      result[key] = rawValue.trim();
+      continue;
+    }
+    const values = [];
+    while (index + 1 < lines.length && /^\s*-\s+/.test(lines[index + 1])) {
+      index += 1;
+      values.push(lines[index].replace(/^\s*-\s+/, "").trim());
+    }
+    result[key] = values;
+  }
+  return {
+    id: getString(result.id, "id"),
+    title: getString(result.title, "title"),
+    summary: getString(result.summary, "summary"),
+    category: getString(result.category, "category"),
+    slug: getString(result.slug, "slug"),
+    tags: getArray(result.tags, "tags"),
+    sourcePath: typeof result.sourcePath === "string" ? result.sourcePath : void 0,
+    relatedPaths: getArray(result.relatedPaths, "relatedPaths")
+  };
+}
+function getString(value, key) {
+  if (typeof value === "string" && value.length > 0) {
+    return value;
+  }
+  if (value == null) {
+    return void 0;
+  }
+  throw new Error(`Frontmatter key "${key}" must be a string.`);
+}
+function getArray(value, key) {
+  if (Array.isArray(value) && value.every((item) => typeof item === "string")) {
+    return value;
+  }
+  if (value == null) {
+    return void 0;
+  }
+  throw new Error(`Frontmatter key "${key}" must be a string array.`);
+}
+function validateMetadata(metadata) {
+  const requiredKeys = ["id", "title", "summary", "category", "slug", "tags"];
+  for (const key of requiredKeys) {
+    if (metadata[key] == null || Array.isArray(metadata[key]) && metadata[key].length === 0) {
+      throw new Error(`Guide frontmatter is missing "${key}".`);
+    }
+  }
+}
+
+// src/guides/catalog.ts
+import { readdir, readFile } from "fs/promises";
+import { dirname, resolve } from "path";
+import { fileURLToPath } from "url";
+var currentDir = dirname(fileURLToPath(import.meta.url));
+var guidesDir = resolve(currentDir, "../../guides");
+var guideCache = null;
+async function listGuides() {
+  if (!guideCache) {
+    guideCache = loadGuides();
+  }
+  return guideCache;
+}
+async function getGuideById(id) {
+  const guides = await listGuides();
+  return guides.find((guide) => guide.id === id);
+}
+async function getGuideByUri(uri) {
+  const guides = await listGuides();
+  return guides.find((guide) => guide.uri === uri);
+}
+async function loadGuides() {
+  const fileNames = (await readdir(guidesDir)).filter((name) => name.endsWith(".md")).sort((left, right) => left.localeCompare(right));
+  return Promise.all(
+    fileNames.map(async (fileName) => {
+      const relativePath = fileName;
+      const markdown = await readFile(resolve(guidesDir, relativePath), "utf8");
+      const { metadata, content } = parseFrontmatter(markdown);
+      return {
+        ...metadata,
+        uri: `guide://${metadata.category}/${metadata.slug}`,
+        relativePath,
+        content
+      };
+    })
+  );
+}
+
+// src/guides/search.ts
+async function searchGuides(query) {
+  const guides = await listGuides();
+  const normalized = query.trim().toLowerCase();
+  if (!normalized) {
+    return guides;
+  }
+  const terms = normalized.split(/\s+/).filter(Boolean);
+  return guides.map((guide) => ({
+    guide,
+    score: scoreGuide(guide, terms)
+  })).filter((entry) => entry.score > 0).sort((left, right) => right.score - left.score || left.guide.title.localeCompare(right.guide.title)).map((entry) => entry.guide);
+}
+function scoreGuide(guide, terms) {
+  const haystacks = [
+    guide.title.toLowerCase(),
+    guide.summary.toLowerCase(),
+    guide.category.toLowerCase(),
+    guide.slug.toLowerCase(),
+    guide.id.toLowerCase(),
+    guide.uri.toLowerCase(),
+    guide.tags.join(" ").toLowerCase(),
+    guide.content.toLowerCase()
+  ];
+  return terms.reduce((score, term) => {
+    let termScore = 0;
+    for (const haystack of haystacks) {
+      if (haystack === term) {
+        termScore = Math.max(termScore, 8);
+      } else if (haystack.startsWith(term)) {
+        termScore = Math.max(termScore, 5);
+      } else if (haystack.includes(term)) {
+        termScore = Math.max(termScore, 2);
+      }
+    }
+    return score + termScore;
+  }, 0);
+}
+
+export {
+  parseFrontmatter,
+  listGuides,
+  getGuideById,
+  getGuideByUri,
+  searchGuides
+};
+//# sourceMappingURL=chunk-R4AEJOIP.js.map

package/dist/chunk-R4AEJOIP.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/guides/frontmatter.ts","../src/guides/catalog.ts","../src/guides/search.ts"],"sourcesContent":["export type GuideMetadata = {\n  id: string;\n  title: string;\n  summary: string;\n  category: string;\n  slug: string;\n  tags: string[];\n  sourcePath?: string;\n  relatedPaths?: string[];\n};\n\nexport function parseFrontmatter(markdown: string): {\n  metadata: GuideMetadata;\n  content: string;\n} {\n  const match = markdown.match(/^---\\n([\\s\\S]*?)\\n---\\n?([\\s\\S]*)$/);\n\n  if (!match) {\n    throw new Error(\"Guide file is missing frontmatter.\");\n  }\n\n  const [, frontmatterBlock, content] = match;\n  const metadata = parseFrontmatterBlock(frontmatterBlock);\n\n  validateMetadata(metadata);\n\n  return {\n    metadata: metadata as GuideMetadata,\n    content: content.trimStart()\n  };\n}\n\nfunction parseFrontmatterBlock(block: string): Partial<GuideMetadata> {\n  const result: Record<string, string | string[]> = {};\n  const lines = block.split(\"\\n\");\n\n  for (let index = 0; index < lines.length; index += 1) {\n    const line = lines[index];\n\n    if (!line.trim()) continue;\n\n    const keyMatch = line.match(/^([A-Za-z0-9]+):(?:\\s*(.*))?$/);\n\n    if (!keyMatch) {\n      throw new Error(`Unsupported frontmatter line: ${line}`);\n    }\n\n    const [, key, rawValue = \"\"] = keyMatch;\n\n    if (rawValue.trim()) {\n      result[key] = rawValue.trim();\n      continue;\n    }\n\n    const values: string[] = [];\n\n    while (index + 1 < lines.length && /^\\s*-\\s+/.test(lines[index + 1])) {\n      index += 1;\n      values.push(lines[index].replace(/^\\s*-\\s+/, \"\").trim());\n    }\n\n    result[key] = values;\n  }\n\n  return {\n    id: getString(result.id, \"id\"),\n    title: getString(result.title, \"title\"),\n    summary: getString(result.summary, \"summary\"),\n    category: getString(result.category, \"category\"),\n    slug: getString(result.slug, \"slug\"),\n    tags: getArray(result.tags, \"tags\"),\n    sourcePath: typeof result.sourcePath === \"string\" ? result.sourcePath : undefined,\n    relatedPaths: getArray(result.relatedPaths, \"relatedPaths\")\n  };\n}\n\nfunction getString(value: unknown, key: string): string | undefined {\n  if (typeof value === \"string\" && value.length > 0) {\n    return value;\n  }\n\n  if (value == null) {\n    return undefined;\n  }\n\n  throw new Error(`Frontmatter key \"${key}\" must be a string.`);\n}\n\nfunction getArray(value: unknown, key: string): string[] | undefined {\n  if (Array.isArray(value) && value.every((item) => typeof item === \"string\")) {\n    return value;\n  }\n\n  if (value == null) {\n    return undefined;\n  }\n\n  throw new Error(`Frontmatter key \"${key}\" must be a string array.`);\n}\n\nfunction validateMetadata(metadata: Partial<GuideMetadata>): asserts metadata is GuideMetadata {\n  const requiredKeys = [\"id\", \"title\", \"summary\", \"category\", \"slug\", \"tags\"] as const;\n\n  for (const key of requiredKeys) {\n    if (metadata[key] == null || (Array.isArray(metadata[key]) && metadata[key].length === 0)) {\n      throw new Error(`Guide frontmatter is missing \"${key}\".`);\n    }\n  }\n}\n","import { readdir, readFile } from \"node:fs/promises\";\nimport { dirname, resolve } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { parseFrontmatter, type GuideMetadata } from \"./frontmatter\";\n\nexport type GuideRecord = GuideMetadata & {\n  uri: string;\n  relativePath: string;\n  content: string;\n};\n\nconst currentDir = dirname(fileURLToPath(import.meta.url));\nconst guidesDir = resolve(currentDir, \"../../guides\");\n\nlet guideCache: Promise<GuideRecord[]> | null = null;\n\nexport async function listGuides(): Promise<GuideRecord[]> {\n  if (!guideCache) {\n    guideCache = loadGuides();\n  }\n\n  return guideCache;\n}\n\nexport async function getGuideById(id: string): Promise<GuideRecord | undefined> {\n  const guides = await listGuides();\n  return guides.find((guide) => guide.id === id);\n}\n\nexport async function getGuideByUri(uri: string): Promise<GuideRecord | undefined> {\n  const guides = await listGuides();\n  return guides.find((guide) => guide.uri === uri);\n}\n\nasync function loadGuides(): Promise<GuideRecord[]> {\n  const fileNames = (await readdir(guidesDir))\n    .filter((name) => name.endsWith(\".md\"))\n    .sort((left, right) => left.localeCompare(right));\n\n  return Promise.all(\n    fileNames.map(async (fileName) => {\n      const relativePath = fileName;\n      const markdown = await readFile(resolve(guidesDir, relativePath), \"utf8\");\n      const { metadata, content } = parseFrontmatter(markdown);\n\n      return {\n        ...metadata,\n        uri: `guide://${metadata.category}/${metadata.slug}`,\n        relativePath,\n        content\n      };\n    })\n  );\n}\n","import type { GuideRecord } from \"./catalog\";\nimport { listGuides } from \"./catalog\";\n\nexport async function searchGuides(query: string): Promise<GuideRecord[]> {\n  const guides = await listGuides();\n  const normalized = query.trim().toLowerCase();\n\n  if (!normalized) {\n    return guides;\n  }\n\n  const terms = normalized.split(/\\s+/).filter(Boolean);\n\n  return guides\n    .map((guide) => ({\n      guide,\n      score: scoreGuide(guide, terms)\n    }))\n    .filter((entry) => entry.score > 0)\n    .sort((left, right) => right.score - left.score || left.guide.title.localeCompare(right.guide.title))\n    .map((entry) => entry.guide);\n}\n\nfunction scoreGuide(guide: GuideRecord, terms: string[]): number {\n  const haystacks = [\n    guide.title.toLowerCase(),\n    guide.summary.toLowerCase(),\n    guide.category.toLowerCase(),\n    guide.slug.toLowerCase(),\n    guide.id.toLowerCase(),\n    guide.uri.toLowerCase(),\n    guide.tags.join(\" \").toLowerCase(),\n    guide.content.toLowerCase()\n  ];\n\n  return terms.reduce((score, term) => {\n    let termScore = 0;\n\n    for (const haystack of haystacks) {\n      if (haystack === term) {\n        termScore = Math.max(termScore, 8);\n      } else if (haystack.startsWith(term)) {\n        termScore = Math.max(termScore, 5);\n      } else if (haystack.includes(term)) {\n        termScore = Math.max(termScore, 2);\n      }\n    }\n\n    return score + termScore;\n  }, 0);\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.ts

@@ -0,0 +1,27 @@
+type GuideMetadata = {
+    id: string;
+    title: string;
+    summary: string;
+    category: string;
+    slug: string;
+    tags: string[];
+    sourcePath?: string;
+    relatedPaths?: string[];
+};
+declare function parseFrontmatter(markdown: string): {
+    metadata: GuideMetadata;
+    content: string;
+};
+
+type GuideRecord = GuideMetadata & {
+    uri: string;
+    relativePath: string;
+    content: string;
+};
+declare function listGuides(): Promise<GuideRecord[]>;
+declare function getGuideById(id: string): Promise<GuideRecord | undefined>;
+declare function getGuideByUri(uri: string): Promise<GuideRecord | undefined>;
+
+declare function searchGuides(query: string): Promise<GuideRecord[]>;
+
+export { type GuideMetadata, type GuideRecord, getGuideById, getGuideByUri, listGuides, parseFrontmatter, searchGuides };

package/dist/index.js

@@ -0,0 +1,16 @@
+#!/usr/bin/env node
+import {
+  getGuideById,
+  getGuideByUri,
+  listGuides,
+  parseFrontmatter,
+  searchGuides
+} from "./chunk-R4AEJOIP.js";
+export {
+  getGuideById,
+  getGuideByUri,
+  listGuides,
+  parseFrontmatter,
+  searchGuides
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}

package/dist/server.d.ts

@@ -0,0 +1,6 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+declare function createServer(): McpServer;
+declare function startServer(): Promise<void>;
+
+export { createServer, startServer };

package/dist/server.js

@@ -0,0 +1,246 @@
+#!/usr/bin/env node
+import {
+  getGuideById,
+  listGuides,
+  searchGuides
+} from "./chunk-R4AEJOIP.js";
+
+// src/server.ts
+import { fileURLToPath } from "url";
+import { McpServer, ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+// package.json
+var package_default = {
+  name: "@xferops/design-guide",
+  version: "0.1.0",
+  private: false,
+  type: "module",
+  main: "./dist/index.js",
+  types: "./dist/index.d.ts",
+  bin: {
+    "xferops-design-guide-mcp": "./dist/server.js"
+  },
+  files: [
+    "dist",
+    "guides"
+  ],
+  publishConfig: {
+    access: "public",
+    registry: "https://registry.npmjs.org/"
+  },
+  exports: {
+    ".": {
+      types: "./dist/index.d.ts",
+      default: "./dist/index.js"
+    },
+    "./server": {
+      types: "./dist/server.d.ts",
+      default: "./dist/server.js"
+    }
+  },
+  scripts: {
+    build: "tsup",
+    typecheck: "tsc -p tsconfig.json --noEmit",
+    test: "vitest run"
+  },
+  dependencies: {
+    "@modelcontextprotocol/sdk": "^1.20.2",
+    zod: "^4.1.11"
+  },
+  devDependencies: {
+    "@types/node": "^24.5.2",
+    tsx: "^4.20.6"
+  }
+};
+
+// src/server.ts
+function createServer() {
+  const server = new McpServer(
+    {
+      name: "@xferops/design-guide",
+      version: package_default.version
+    },
+    {
+      capabilities: {
+        logging: {}
+      }
+    }
+  );
+  server.registerTool(
+    "search_guides",
+    {
+      title: "Search Design Guides",
+      description: "Search the XferOps frontend design guide catalog by keyword, tag, or area.",
+      inputSchema: z.object({
+        query: z.string().describe("Keywords such as table sorting, forms, overlays, or navigation.")
+      }),
+      outputSchema: z.object({
+        guides: z.array(
+          z.object({
+            id: z.string(),
+            title: z.string(),
+            summary: z.string(),
+            tags: z.array(z.string()),
+            uri: z.string(),
+            sourcePath: z.string().optional()
+          })
+        )
+      })
+    },
+    async ({ query }) => {
+      const guides = (await searchGuides(query)).map((guide) => ({
+        id: guide.id,
+        title: guide.title,
+        summary: guide.summary,
+        tags: guide.tags,
+        uri: guide.uri,
+        sourcePath: guide.sourcePath
+      }));
+      return {
+        content: [
+          {
+            type: "text",
+            text: guides.length ? guides.map((guide) => `${guide.title} (${guide.uri})`).join("\n") : "No guides matched the query."
+          }
+        ],
+        structuredContent: { guides }
+      };
+    }
+  );
+  server.registerTool(
+    "get_guide",
+    {
+      title: "Get Design Guide",
+      description: "Read a guide by id such as table/sorting or by URI such as guide://table/sorting.",
+      inputSchema: z.object({
+        identifier: z.string().describe("Guide id or guide URI.")
+      }),
+      outputSchema: z.object({
+        id: z.string(),
+        title: z.string(),
+        summary: z.string(),
+        uri: z.string(),
+        content: z.string(),
+        sourcePath: z.string().optional()
+      })
+    },
+    async ({ identifier }) => {
+      const guideId = identifier.startsWith("guide://") ? identifier.replace("guide://", "") : identifier.replace(/^\/+/, "");
+      const guide = await getGuideById(guideId);
+      if (!guide) {
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Guide not found: ${identifier}`
+            }
+          ],
+          isError: true
+        };
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: guide.content
+          }
+        ],
+        structuredContent: {
+          id: guide.id,
+          title: guide.title,
+          summary: guide.summary,
+          uri: guide.uri,
+          content: guide.content,
+          sourcePath: guide.sourcePath
+        }
+      };
+    }
+  );
+  server.registerResource(
+    "guide-catalog",
+    "guide://catalog",
+    {
+      title: "Guide Catalog",
+      description: "Catalog of available XferOps frontend design guides.",
+      mimeType: "application/json"
+    },
+    async (uri) => {
+      const guides = await listGuides();
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            text: JSON.stringify(
+              guides.map((guide) => ({
+                id: guide.id,
+                title: guide.title,
+                summary: guide.summary,
+                tags: guide.tags,
+                uri: guide.uri,
+                sourcePath: guide.sourcePath
+              })),
+              null,
+              2
+            )
+          }
+        ]
+      };
+    }
+  );
+  server.registerResource(
+    "guide-document",
+    new ResourceTemplate("guide://{category}/{slug}", {
+      list: async () => {
+        const guides = await listGuides();
+        return {
+          resources: guides.map((guide) => ({
+            uri: guide.uri,
+            name: guide.title,
+            description: guide.summary,
+            mimeType: "text/markdown"
+          }))
+        };
+      }
+    }),
+    {
+      title: "Guide Document",
+      description: "A markdown guide for a specific frontend topic.",
+      mimeType: "text/markdown"
+    },
+    async (uri, { category, slug }) => {
+      const guide = await getGuideById(`${category}/${slug}`);
+      if (!guide) {
+        throw new Error(`Guide not found for URI: ${uri.href}`);
+      }
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            text: guide.content
+          }
+        ]
+      };
+    }
+  );
+  return server;
+}
+async function startServer() {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("@xferops/design-guide MCP server running on stdio");
+}
+var entryPath = process.argv[1];
+if (entryPath && fileURLToPath(import.meta.url) === entryPath) {
+  void startServer().catch((error) => {
+    console.error("Fatal error in @xferops/design-guide:", error);
+    process.exit(1);
+  });
+}
+export {
+  createServer,
+  startServer
+};
+//# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/server.ts","../package.json"],"sourcesContent":["import { fileURLToPath } from \"node:url\";\nimport { McpServer, ResourceTemplate } from \"@modelcontextprotocol/sdk/server/mcp.js\";\nimport { StdioServerTransport } from \"@modelcontextprotocol/sdk/server/stdio.js\";\nimport { z } from \"zod\";\nimport packageJson from \"../package.json\";\nimport { getGuideById, listGuides } from \"./guides/catalog\";\nimport { searchGuides } from \"./guides/search\";\n\nexport function createServer() {\n  const server = new McpServer(\n    {\n      name: \"@xferops/design-guide\",\n      version: packageJson.version\n    },\n    {\n      capabilities: {\n        logging: {}\n      }\n    }\n  );\n\n  server.registerTool(\n    \"search_guides\",\n    {\n      title: \"Search Design Guides\",\n      description: \"Search the XferOps frontend design guide catalog by keyword, tag, or area.\",\n      inputSchema: z.object({\n        query: z.string().describe(\"Keywords such as table sorting, forms, overlays, or navigation.\")\n      }),\n      outputSchema: z.object({\n        guides: z.array(\n          z.object({\n            id: z.string(),\n            title: z.string(),\n            summary: z.string(),\n            tags: z.array(z.string()),\n            uri: z.string(),\n            sourcePath: z.string().optional()\n          })\n        )\n      })\n    },\n    async ({ query }) => {\n      const guides = (await searchGuides(query)).map((guide) => ({\n        id: guide.id,\n        title: guide.title,\n        summary: guide.summary,\n        tags: guide.tags,\n        uri: guide.uri,\n        sourcePath: guide.sourcePath\n      }));\n\n      return {\n        content: [\n          {\n            type: \"text\",\n            text: guides.length\n              ? guides.map((guide) => `${guide.title} (${guide.uri})`).join(\"\\n\")\n              : \"No guides matched the query.\"\n          }\n        ],\n        structuredContent: { guides }\n      };\n    }\n  );\n\n  server.registerTool(\n    \"get_guide\",\n    {\n      title: \"Get Design Guide\",\n      description: \"Read a guide by id such as table/sorting or by URI such as guide://table/sorting.\",\n      inputSchema: z.object({\n        identifier: z.string().describe(\"Guide id or guide URI.\")\n      }),\n      outputSchema: z.object({\n        id: z.string(),\n        title: z.string(),\n        summary: z.string(),\n        uri: z.string(),\n        content: z.string(),\n        sourcePath: z.string().optional()\n      })\n    },\n    async ({ identifier }) => {\n      const guideId = identifier.startsWith(\"guide://\")\n        ? identifier.replace(\"guide://\", \"\")\n        : identifier.replace(/^\\/+/, \"\");\n      const guide = await getGuideById(guideId);\n\n      if (!guide) {\n        return {\n          content: [\n            {\n              type: \"text\",\n              text: `Guide not found: ${identifier}`\n            }\n          ],\n          isError: true\n        };\n      }\n\n      return {\n        content: [\n          {\n            type: \"text\",\n            text: guide.content\n          }\n        ],\n        structuredContent: {\n          id: guide.id,\n          title: guide.title,\n          summary: guide.summary,\n          uri: guide.uri,\n          content: guide.content,\n          sourcePath: guide.sourcePath\n        }\n      };\n    }\n  );\n\n  server.registerResource(\n    \"guide-catalog\",\n    \"guide://catalog\",\n    {\n      title: \"Guide Catalog\",\n      description: \"Catalog of available XferOps frontend design guides.\",\n      mimeType: \"application/json\"\n    },\n    async (uri) => {\n      const guides = await listGuides();\n\n      return {\n        contents: [\n          {\n            uri: uri.href,\n            text: JSON.stringify(\n              guides.map((guide) => ({\n                id: guide.id,\n                title: guide.title,\n                summary: guide.summary,\n                tags: guide.tags,\n                uri: guide.uri,\n                sourcePath: guide.sourcePath\n              })),\n              null,\n              2\n            )\n          }\n        ]\n      };\n    }\n  );\n\n  server.registerResource(\n    \"guide-document\",\n    new ResourceTemplate(\"guide://{category}/{slug}\", {\n      list: async () => {\n        const guides = await listGuides();\n\n        return {\n          resources: guides.map((guide) => ({\n            uri: guide.uri,\n            name: guide.title,\n            description: guide.summary,\n            mimeType: \"text/markdown\"\n          }))\n        };\n      }\n    }),\n    {\n      title: \"Guide Document\",\n      description: \"A markdown guide for a specific frontend topic.\",\n      mimeType: \"text/markdown\"\n    },\n    async (uri, { category, slug }) => {\n      const guide = await getGuideById(`${category}/${slug}`);\n\n      if (!guide) {\n        throw new Error(`Guide not found for URI: ${uri.href}`);\n      }\n\n      return {\n        contents: [\n          {\n            uri: uri.href,\n            text: guide.content\n          }\n        ]\n      };\n    }\n  );\n\n  return server;\n}\n\nexport async function startServer() {\n  const server = createServer();\n  const transport = new StdioServerTransport();\n\n  await server.connect(transport);\n  console.error(\"@xferops/design-guide MCP server running on stdio\");\n}\n\nconst entryPath = process.argv[1];\n\nif (entryPath && fileURLToPath(import.meta.url) === entryPath) {\n  void startServer().catch((error) => {\n    console.error(\"Fatal error in @xferops/design-guide:\", error);\n    process.exit(1);\n  });\n}\n","{\n  \"name\": \"@xferops/design-guide\",\n  \"version\": \"0.1.0\",\n  \"private\": false,\n  \"type\": \"module\",\n  \"main\": \"./dist/index.js\",\n  \"types\": \"./dist/index.d.ts\",\n  \"bin\": {\n    \"xferops-design-guide-mcp\": \"./dist/server.js\"\n  },\n  \"files\": [\n    \"dist\",\n    \"guides\"\n  ],\n  \"publishConfig\": {\n    \"access\": \"public\",\n    \"registry\": \"https://registry.npmjs.org/\"\n  },\n  \"exports\": {\n    \".\": {\n      \"types\": \"./dist/index.d.ts\",\n      \"default\": \"./dist/index.js\"\n    },\n    \"./server\": {\n      \"types\": \"./dist/server.d.ts\",\n      \"default\": \"./dist/server.js\"\n    }\n  },\n  \"scripts\": {\n    \"build\": \"tsup\",\n    \"typecheck\": \"tsc -p tsconfig.json --noEmit\",\n    \"test\": \"vitest run\"\n  },\n  \"dependencies\": {\n    \"@modelcontextprotocol/sdk\": \"^1.20.2\",\n    \"zod\": \"^4.1.11\"\n  },\n  \"devDependencies\": {\n    \"@types/node\": \"^24.5.2\",\n    \"tsx\": \"^4.20.6\"\n  }\n}\n"],"mappings":"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","names":[]}

package/guides/feedback-status-states.md

@@ -0,0 +1,107 @@
+---
+id: feedback/status-states
+title: Status, Empty, and Loading States
+summary: Use Alert, Badge, Spinner, EmptyState, and Skeleton for user feedback and progressive loading.
+category: feedback
+slug: status-states
+tags:
+  - feedback
+  - alert
+  - badge
+  - empty-state
+  - skeleton
+  - loading
+sourcePath: apps/docs/src/App.tsx
+relatedPaths:
+  - packages/ui/src/components/Alert
+  - packages/ui/src/components/Badge
+  - packages/ui/src/components/Spinner
+  - packages/ui/src/components/EmptyState
+  - packages/ui/src/components/Skeleton
+  - packages/ui/src/components/Button
+---
+
+# Status, Empty, and Loading States
+
+These primitives cover the common feedback cases around status messaging, loading, and empty datasets.
+
+## Import the Feedback Components
+
+```tsx
+import {
+  Alert,
+  Badge,
+  Button,
+  EmptyState,
+  Skeleton,
+  Spinner,
+  Stack,
+  Text
+} from "@xferops/ui";
+```
+
+## Use `Alert` and `Badge` for Status
+
+Use `Alert` for explanatory messaging and `Badge` for compact labels inside other UI.
+
+```tsx
+<Stack gap="sm">
+  <Alert
+    tone="warning"
+    title="API key expires soon"
+    description="Rotate the credential before Friday to avoid sync failures."
+  />
+
+  <Stack direction="row" gap="sm" wrap>
+    <Badge>Draft</Badge>
+    <Badge tone="accent">Live</Badge>
+    <Badge tone="success">Paid</Badge>
+    <Badge tone="danger">Overdue</Badge>
+  </Stack>
+</Stack>
+```
+
+## Use `Spinner` and `Skeleton` for Loading
+
+Choose `Spinner` when work is in progress and `Skeleton` when the shape of incoming content is already known.
+
+```tsx
+<Stack gap="md">
+  <Stack direction="row" align="center" gap="sm">
+    <Spinner size="sm" />
+    <Text as="span" size="sm" tone="muted">
+      Syncing workspace data
+    </Text>
+  </Stack>
+
+  <Stack gap="xs">
+    <Skeleton height={14} width="35%" />
+    <Skeleton height={12} width="80%" />
+    <Skeleton height={12} width="72%" />
+  </Stack>
+</Stack>
+```
+
+## Use `EmptyState` for No-Data Screens
+
+```tsx
+<EmptyState
+  iconText="[]"
+  titleText="No invoices yet"
+  descriptionText="Create your first invoice to get paid faster."
+  actionsContent={
+    <>
+      <Button size="sm">Create invoice</Button>
+      <Button size="sm" variant="secondary">
+        View docs
+      </Button>
+    </>
+  }
+/>
+```
+
+## Notes
+
+- Prefer the narrowest primitive that matches the job: `Badge` for inline state, `Alert` for message blocks, `EmptyState` for whole-section fallback.
+- `Skeleton` is decorative and already `aria-hidden`, so pair it with real loading announcements when the wait matters.
+- Keep action content inside `EmptyState` short and task-oriented.