@neuctra/ui-mcp 0.2.5 → 0.3.1

package/data/theme.json

@@ -4,10 +4,29 @@
     "Never use hardcoded Tailwind palette colors (text-blue-500, bg-red-500, border-gray-200, etc.) or inline hex/rgb colors in generated UI.",
     "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)."
   ],
+  "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 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. Don't add box-shadow/drop-shadow utilities (shadow-sm through shadow-2xl, glowing hover rings, colored blur halos) to buttons, badges, cards, inputs, or any static surface — a flat surface with border-border is correct. If a floating layer (modal, popover, dropdown menu) needs visual separation from what's behind it, a border plus the surface's own background token (bg-popover, bg-card) is enough; don't reach for shadow as the default way to show elevation.",
+    "No blur effects. Don't use backdrop-blur or any glassmorphism treatment (frosted-glass cards, translucent bg-white/10 panels) anywhere in generated UI, including modal backdrops — use an opaque or semi-opaque solid backdrop (e.g. bg-background/80) instead of a blurred one. Surfaces are opaque (bg-card, bg-popover, bg-background), not translucent.",
+    "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 (—) 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.",
+    "When unsure whether an effect (shadow, gradient, blur, glow, animation) is warranted: leave it out. A flat, token-colored, appropriately-radiused, unshadowed, responsive surface is the correct default for the overwhelming majority of neuctra-ui components."
+  ],
   "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." },
     { "token": "primary-foreground", "className": "text-primary-foreground", "light": "#ffffff", "dark": "#ffffff", "usage": "Text/icons on top of bg-primary." },
@@ -33,5 +52,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.3.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",

package/src/server.mjs

@@ -44,7 +44,7 @@ export function createServer(data) {
 
   const server = new McpServer({
     name: "neuctra-ui",
-    version: "0.1.0",
+    version: "0.3.1",
   });
 
   server.registerTool(
@@ -141,7 +141,7 @@ export function createServer(data) {
     {
       title: "Get Neuctra UI theming rules and tokens",
       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 the semantic color token system (bg-primary, text-foreground, etc.), the styling rules generated UI must follow, a set of rules for avoiding the visual tells that make UI look AI-generated (gradients, decorative shadows/blurs/glows, emoji-as-icons, etc.), the recommended `@neuctra/ui-cli` setup command, and how the toast notification API works. Call this before generating any UI — not just for colors.",
       inputSchema: {},
     },
     async () => {