@neuctra/ui-mcp 0.2.5 → 0.4.1

package/data/theme.json

@@ -1,12 +1,34 @@
 {
   "system": "Tailwind CSS v4, semantic CSS-variable tokens mapped via @theme, toggled by a .dark class (not prefers-color-scheme).",
   "rules": [
-    "Never use hardcoded Tailwind palette colors (text-blue-500, bg-red-500, border-gray-200, etc.) or inline hex/rgb colors in generated UI.",
+    "Theme colors only, compulsory, no exceptions: never use hardcoded Tailwind palette colors (text-blue-500, bg-red-500, border-gray-200, etc.), inline hex/rgb colors, or any other extra/arbitrary color not in the token list below, anywhere in generated UI — not even for a one-off accent, illustration, or 'just this one element'. Every color used must be one of the semantic tokens below.",
     "Always use the semantic token classes below (bg-primary, text-foreground, border-border, ...) so generated UI automatically follows the consumer's theme in both light and dark mode.",
     "Every base token except background/foreground/border/input/ring has a matching '-foreground' token for text/icons placed on top of it (e.g. bg-primary + text-primary-foreground, bg-destructive + text-destructive-foreground).",
-    "Page background: bg-background, text-foreground. Card/panel surfaces: bg-card (or bg-muted/bg-accent for secondary surfaces). Popovers/dropdowns/tooltips: bg-popover.",
+    "Page background: bg-background. Card surfaces: bg-card. A distinct section within a page (not the whole page, not a card): bg-accent, or bg-card again if it needs to read as a panel. Popovers/dropdowns/tooltips: bg-popover. Never use bg-muted as a page, section, or card background — muted is reserved for non-surface fills only (skeleton placeholders, disabled-state fills, inline code backgrounds), not for anything a user reads content on top of.",
     "Status colors: success (positive/confirmation), warning (caution), info (neutral notice), destructive (danger/errors) — use these instead of ad-hoc green/yellow/blue/red.",
-    "Dark mode requires no extra work in generated code: the same class names resolve to the .dark palette automatically because the consumer's CSS defines both blocks. Do not write dark: variants for color — only use dark: for things the token system doesn't cover (rare)."
+    "Dark mode requires no extra work in generated code: the same class names resolve to the .dark palette automatically because the consumer's CSS defines both blocks. Do not write dark: variants for color — only use dark: for things the token system doesn't cover (rare).",
+    "Use the Card component, not a hand-rolled lookalike: this rule only applies once you've decided a group of content (a settings section, a stat/summary tile, a list item container, a form section, a feature block, etc.) needs a bounded/bordered panel treatment — it does not mean every grouping must be boxed (see the design rules' 'less UI is often better UI' guidance: whitespace-only grouping is often correct and a Card is often unnecessary). When a panel treatment is warranted, build it with <Card> — never a raw div styled to look like a card (e.g. bg-card border border-border rounded-lg p-4 by hand). <CardBody> is compulsory whenever the card has body content, not optional: <Card>'s own root element applies zero padding (only the border/background/radius) — all internal spacing lives in the sub-components via their shared padding context, so placing content directly as a child of <Card> without wrapping it in <CardBody> renders that content flush against the card's border with no padding, which visibly breaks the UI. <CardHeader> (title/description/icon/actions) and <CardFooter> (actions/meta) remain genuinely optional — include each only if that section is needed — but never skip <CardBody> when there is body content, and never place content as a direct child of <Card> itself.",
+    "Dropdown's trigger button: never call e.stopPropagation() (or preventDefault() for the same purpose) in an onClick you attach to the Dropdown's trigger element. The Dropdown component already stops propagation internally to manage its own open/close and outside-click behavior; adding it again on the consumer's trigger handler is redundant and can break the dropdown's outside-click / nested-dropdown / row-click interactions. If the trigger sits inside another clickable element (a table row, a card), rely on Dropdown's own handling instead of manually stopping propagation.",
+    "Do not overwrite a component's built-in design. Use each @neuctra/ui component's default classes/variants/sizes as-is by default — do not routinely pass a className that overrides its built-in spacing, radius, colors, or layout just to restyle it. Only override with Tailwind's `!` important-modifier (e.g. `!bg-red-500`, `!p-2`) when there's a real, specific need — the component's default would otherwise break the current page's existing layout/design, collide with a surrounding container, or the component itself has no prop for the needed variation — never as a routine styling habit or a stylistic preference."
+  ],
+  "antiAiLookRules": [
+    "This section exists because AI-generated UI has recognizable tells. Read it before generating anything visual — the goal is UI indistinguishable from a deliberate human design pass, not a demo that screams 'built by an LLM'.",
+    "No gradients, compulsory: never use gradients on backgrounds, buttons, or text (bg-gradient-to-r, from-purple-500 to-pink-500, bg-clip-text text-transparent, etc.). Use a flat bg-primary (or the relevant status token) instead. This is the single most common AI-UI tell — do not use it even 'just for one hero section'.",
+    "No shadows, compulsory: never add box-shadow/drop-shadow utilities (shadow-sm through shadow-2xl, glowing hover rings, colored blur halos) to any element YOU style directly — buttons, badges, cards, inputs, hand-built panels/overlays, or any other static surface you write classNames for. A flat surface with border-border is correct. Scope note (applies to every rule in this list, not just this one): this governs classNames/markup you author yourself. It does not mean stripping or fighting any pre-built @neuctra/ui component's own internal default styling, no matter which component or what that default is (several components ship their own shadow — e.g. Modal, Drawer, Popover, Dropdown, Tooltip, Table, DatePicker's calendar panel, Avatar's status dot, Kbd, and the Toast/ToastProvider notification — this is not an exhaustive list and isn't meant to be maintained as one). Per the 'don't overwrite built-in component design' rule: leave every component's shipped defaults exactly as they ship. Never add a decorative shadow yourself, and never override one away with `!important` either — both are the same mistake in opposite directions.",
+    "No blur effects, compulsory: never use backdrop-blur or any glassmorphism treatment (frosted-glass cards, translucent bg-white/10 panels) on any element YOU style directly, including a hand-built modal/drawer backdrop — use an opaque or semi-opaque solid backdrop (e.g. bg-background/80) instead of a blurred one. Surfaces you author are opaque (bg-card, bg-popover, bg-background), not translucent. Same scope note as the shadow rule above: this is about classNames/markup you write, not about a pre-built @neuctra/ui component's own internal backdrop-blur (e.g. Modal/Drawer's backdrop, Dropdown's menu panel, Carousel's nav buttons ship with backdrop-blur baked in, among others) — leave every component's shipped defaults exactly as they ship, whichever component it is.",
+    "No blanket border-radius escalation — don't reach for rounded-2xl/rounded-3xl/rounded-full on every card, input, and button by default. Match the radius already used by the surrounding neuctra-ui components (rounded-md/rounded-lg/rounded-xl per component, see each component's own classes) instead of picking a bigger one because it 'looks more modern'.",
+    "No decorative hover/focus glow rings. ring-* and focus-visible:ring-ring exist for accessibility (keyboard focus indication) only — never add a colored ring or glow as a pointer-hover decoration on cards, buttons, or images.",
+    "No animate-pulse / bounce / scale-105-on-hover / floating-icon motion sprinkled across static content as decoration. Motion should communicate state (loading, a toast entering, a modal opening) — components already handle that internally. Don't add extra hover-scale or idle animation to elements that aren't interactive or aren't mid-transition.",
+    "No emoji used as icons or bullet markers in generated UI (✨, 🚀, 💡, ✅ as list bullets, feature markers, or button icons). Use lucide-react icons — the same icon set every neuctra-ui component already uses — passed via each component's icon props (iconBefore, iconAfter, icon, etc.).",
+    "No 'icon in a colored circle badge' repeated on every single feature/stat/card by default (a bg-primary/10 rounded-full p-3 wrapper around every icon). Use it sparingly, only where the component's own design already calls for it — repeating the same decorative wrapper on every card in a grid is a generic-template tell.",
+    "No arbitrary one-off spacing/sizing values (p-[13px], gap-[7px], w-[327px]) — use the Tailwind spacing scale (p-3, gap-2, w-80, etc.) so spacing stays consistent with the rest of the design system.",
+    "Prefer information density and restraint over generic centered-hero-with-huge-padding layouts. Not every section needs max-w-7xl mx-auto text-center py-24 — match the density and layout the consumer's existing UI already uses.",
+    "Make every layout fully responsive by default — mobile, tablet, and desktop (sm:/md:/lg:/xl: breakpoints), stacking to a single column and adjusting spacing/type-scale at small widths. Never ship a fixed-width or desktop-only layout and call it done.",
+    "No em dashes (—), compulsory: never use an em dash in generated copy or UI text (headings, body copy, button labels, placeholder text). It's a recognizable AI-writing tell. Use a period, comma, colon, or restructure the sentence instead.",
+    "No over-effects: don't stack multiple decorative treatments on one element (e.g. a gradient plus a shadow plus a hover-scale plus a glow, all on the same button). Every visual effect that does appear should communicate a real state or interaction (hover, focus, loading, an entering toast) — never decoration for its own sake.",
+    "Use correct line-height and letter-spacing for readability. Body text: leading-relaxed or leading-normal, never leading-none/leading-tight on paragraphs. Letter-spacing: leave at the default (tracking-normal) for body and headings; only use tracking-wide for short uppercase labels (badges, eyebrow text, nav labels), and never tracking-wide on paragraph-length text.",
+    "The bar is modern, visually appealing UI achieved through typography hierarchy, whitespace, correct token usage, and responsive layout, not through gradients, shadows, blur, or glow effects standing in for actual design decisions.",
+    "Decent, restrained design, compulsory: build UI that is decent and intentional, never over-designed. When unsure whether an effect (shadow, gradient, blur, glow, animation, an extra color) is warranted on something you're authoring yourself: leave it out. A flat, token-colored, appropriately-radiused, unshadowed, responsive surface using only the semantic color tokens is the correct default for the overwhelming majority of neuctra-ui components — restraint is the default, not the exception."
   ],
   "tokens": [
     { "token": "primary", "className": "bg-primary / text-primary / border-primary", "pairsWith": "primary-foreground", "light": "#00c214", "dark": "#00c214", "usage": "Brand color: primary buttons, active states, links, focus accents." },
@@ -33,5 +55,18 @@
     { "token": "info", "className": "bg-info / text-info / border-info", "pairsWith": "info-foreground", "light": "#2563eb", "dark": "#3b82f6", "usage": "Neutral notices, informational banners/badges." },
     { "token": "info-foreground", "className": "text-info-foreground", "light": "#fafafa", "dark": "#eff6ff", "usage": "Text on bg-info." }
   ],
-  "note": "Values shown are the CLI-generated defaults (npx @neuctra/ui-cli init). A consumer project may have redefined these hex values in its own CSS — the token NAMES and pairing rules are the stable contract; always prefer the class names over the hex values."
+  "note": "Values shown are the CLI-generated defaults (npx @neuctra/ui-cli init). A consumer project may have redefined these hex values in its own CSS — the token NAMES and pairing rules are the stable contract; always prefer the class names over the hex values.",
+  "setup": {
+    "recommendedCommand": "npx @neuctra/ui-cli@latest init",
+    "whatItDoes": [
+      "Installs @neuctra/ui.",
+      "Checks React (upgrades to >=18 if needed) and Tailwind CSS (upgrades to v4 if needed) — @neuctra/ui requires Tailwind v4 syntax (@theme, @source, @custom-variant).",
+      "Writes/updates the project's global CSS with the token blocks shown in this response (:root + .dark + @theme mapping) and the correct @source path for the project's own layout.",
+      "Generates a theme context file at src/contexts/ThemeContext.jsx (or .tsx if the project is TypeScript) exporting ThemeProvider and useTheme — handles localStorage persistence, system-preference detection with live updates, and avoids a flash of the wrong theme on load.",
+      "Wraps the app's entry point in <ThemeProvider>."
+    ],
+    "whenToSuggestIt": "If a project doesn't have @neuctra/ui installed yet, or has no theme token CSS / no ThemeContext, suggest running this command instead of hand-writing the CSS token blocks or a theme context from scratch — it is the maintained, correct source for both.",
+    "manualSetupStillDocumented": "If the consumer can't run a CLI (e.g. you're only shown existing code, not given shell access), the full manual step-by-step — including the exact ThemeContext implementation the CLI generates — is at the project's /docs/full-setup page (FullSetupDocPage) and is safe to reproduce by hand."
+  },
+  "toastNote": "@neuctra/ui's toast notification system is a standalone function, not hook-only: import { toast, ToastProvider } from '@neuctra/ui' and call toast(...) / toast.success(...) / toast.error(...) / toast.warning(...) / toast.info(...) / toast.loading(...) / toast.promise(...) from anywhere — event handlers, API clients, utility files — no useToast() hook required at the call site. Mount <ToastProvider> once near the app root so there is somewhere for toasts to render; mounting it more than once duplicates every toast. useToast() still exists for consumers who prefer a hook — it returns the identical global toast/dismiss, so both styles stay in sync. See get_component with name \"ToastProvider\" for the full prop list (including position, one of top-left/top-center/top-right/bottom-left/bottom-center/bottom-right)."
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@neuctra/ui-mcp",
-  "version": "0.2.5",
+  "version": "0.4.1",
   "description": "MCP server exposing the @neuctra/ui component registry (props, defaults, examples, theme tokens) so AI coding tools generate accurate Neuctra UI code.",
   "type": "module",
   "license": "MIT",
@@ -26,6 +26,7 @@
     ".": "./src/server.mjs",
     "./data/components.json": "./data/components.json",
     "./data/theme.json": "./data/theme.json",
+    "./data/aiDesignRules.json": "./data/aiDesignRules.json",
     "./package.json": "./package.json"
   },
   "files": [

package/src/server.mjs

@@ -7,18 +7,23 @@ import { z } from "zod";
 // Reads data/*.json from disk. Only works on runtimes with a filesystem
 // (Node, Bun, Deno) — callers on edge/serverless runtimes without one
 // (Cloudflare Workers) must import the JSON files themselves at build time
-// and pass them into createServer({ registry, theme }) instead. Resolving
-// __dirname is deferred inside this function (not module top-level) because
-// import.meta.url is unavailable in some bundled edge runtimes even when
-// this function itself is never called there.
+// and pass them into createServer({ registry, theme, aiDesignRules }) instead.
+// Resolving __dirname is deferred inside this function (not module top-level)
+// because import.meta.url is unavailable in some bundled edge runtimes even
+// when this function itself is never called there.
 function loadDataFromDisk() {
   const __dirname = path.dirname(fileURLToPath(import.meta.url));
   const DATA_DIR = path.resolve(__dirname, "..", "data");
   const registry = JSON.parse(
     fs.readFileSync(path.join(DATA_DIR, "components.json"), "utf8"),
   );
-  const theme = JSON.parse(fs.readFileSync(path.join(DATA_DIR, "theme.json"), "utf8"));
-  return { registry, theme };
+  const theme = JSON.parse(
+    fs.readFileSync(path.join(DATA_DIR, "theme.json"), "utf8"),
+  );
+  const aiDesignRules = JSON.parse(
+    fs.readFileSync(path.join(DATA_DIR, "aiDesignRules.json"), "utf8"),
+  );
+  return { registry, theme, aiDesignRules };
 }
 
 function summarize(component) {
@@ -39,12 +44,12 @@ function matchesQuery(component, query) {
 }
 
 export function createServer(data) {
-  const { registry, theme } = data ?? loadDataFromDisk();
+  const { registry, theme, aiDesignRules } = data ?? loadDataFromDisk();
   const componentsByName = new Map(registry.components.map((c) => [c.name, c]));
 
   const server = new McpServer({
     name: "neuctra-ui",
-    version: "0.1.0",
+    version: "0.4.0",
   });
 
   server.registerTool(
@@ -88,7 +93,9 @@ export function createServer(data) {
       inputSchema: {
         name: z
           .string()
-          .describe('Exact component name, e.g. "Input", "Select", "Modal", "CardHeader".'),
+          .describe(
+            'Exact component name, e.g. "Input", "Select", "Modal", "CardHeader".',
+          ),
       },
     },
     async ({ name }) => {
@@ -123,13 +130,15 @@ export function createServer(data) {
     {
       title: "Search Neuctra UI components",
       description:
-        "Search components by keyword against name, category, description, and prop names. Use this when you know what you need (e.g. \"date picker\", \"loading state\", \"icon button\") but not the exact component name.",
+        'Search components by keyword against name, category, description, and prop names. Use this when you know what you need (e.g. "date picker", "loading state", "icon button") but not the exact component name.',
       inputSchema: {
         query: z.string().describe("Keyword or short phrase to search for."),
       },
     },
     async ({ query }) => {
-      const results = registry.components.filter((c) => matchesQuery(c, query)).map(summarize);
+      const results = registry.components
+        .filter((c) => matchesQuery(c, query))
+        .map(summarize);
       return {
         content: [{ type: "text", text: JSON.stringify(results, null, 2) }],
       };
@@ -139,14 +148,40 @@ export function createServer(data) {
   server.registerTool(
     "get_theme",
     {
-      title: "Get Neuctra UI theming rules and tokens",
+      title: "Get Neuctra UI theming tokens",
+      description:
+        "Get the semantic color token system (bg-primary, text-foreground, etc.), the recommended `@neuctra/ui-cli` setup command, and how the toast notification API works. Call get_design_rules alongside this before generating any UI — not just for colors.",
+      inputSchema: {},
+    },
+    async () => {
+      const { rules, antiAiLookRules, ...themeOnly } = theme;
+      return {
+        content: [{ type: "text", text: JSON.stringify(themeOnly, null, 2) }],
+      };
+    },
+  );
+
+  server.registerTool(
+    "get_design_rules",
+    {
+      title: "Get Neuctra UI design rules",
       description:
-        "Get the semantic color token system (bg-primary, text-foreground, etc.) and the styling rules generated UI must follow. Call this before generating any UI so colors come from theme tokens instead of hardcoded Tailwind palette classes or hex values — hardcoded colors will not respect the consumer's light/dark theme.",
+        "Get every design rule generated UI must follow when using @neuctra/ui. Covers two levels: (1) styling rules — token usage, surface/background conventions, component composition requirements like CardBody being compulsory whenever Card has body content, component-specific gotchas like Dropdown's trigger propagation, and the full set of rules for avoiding the visual tells that make UI look AI-generated (gradients, decorative shadows/blurs/glows, emoji-as-icons, etc.); (2) product/UX design rules — a numbered 50-section guide covering design philosophy, visual hierarchy, page/sidebar/navigation structure, per-component usage guidance (when to use Card, Modal vs Drawer, Table vs List, etc.), spacing/color/border/radius/shadow conventions, responsive design, accessibility, interaction design, a final UI quality checklist, and the rule against overwriting a component's built-in design. Call this before generating any UI — not just get_theme.",
       inputSchema: {},
     },
     async () => {
+      const { rules, antiAiLookRules } = theme;
       return {
-        content: [{ type: "text", text: JSON.stringify(theme, null, 2) }],
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              { stylingRules: rules, antiAiLookRules, productDesignGuide: aiDesignRules },
+              null,
+              2,
+            ),
+          },
+        ],
       };
     },
   );