@neuctra/ui-mcp 0.4.1 → 0.4.3

package/README.md

@@ -36,8 +36,8 @@ generated from your actual TypeScript source. No guessing, no file-spelunking.
 neuctra-ui-package/src/components/basic/*.tsx     (your actual component source)
         │
         │  npm run registry:generate  (ts-morph reads props/JSDoc/defaults,
-        │                               scrapes one example per component
-        │                               from neuctra-ui-docs)
+        │                               scrapes one description + example per
+        │                               component from neuctra-ui-docs-v2)
         ▼
 neuctra-ui-package/registry/components.json        (source of truth)
         │
@@ -64,13 +64,20 @@ Three independently-regenerable files feed the server:
   the color-token rules ("never hardcode colors"), the anti-AI-look rules ("no
   gradients/shadows/blurs/glows/emoji-icons"), the recommended `@neuctra/ui-cli init`
   setup command, and how the standalone `toast()` API works.
-- **`data/aiDesignRules.json`** — also hand-curated, no generator. A 50-section
+- **`data/aiDesignRules.json`** — also hand-curated, no generator. A 63-section
   product/UX design guide (design philosophy, visual hierarchy, page/sidebar/navigation
   structure, per-component usage guidance, spacing/color/border/radius/shadow
   conventions, responsive design, accessibility, and a final UI quality checklist).
   `theme.json`'s `rules`/`antiAiLookRules` are the mechanical, CSS-level rules; this file
   is the higher-level product-design layer — both are served together by
   `get_design_rules`.
+- **`data/seoGuide.json`** — hand-curated, no generator. A 16-topic SEO / AEO / GEO
+  playbook (technical SEO, Core Web Vitals, on-page, keywords and intent, E-E-A-T, answer
+  engine and generative engine optimisation, schema weaving, FAQs, the per-page meta
+  checklist, where metadata goes in each framework plus Next.js metadata gotchas, page
+  templates for tool/category/home pages, site-wide essentials, ads readiness, off-page
+  and monitoring, and a launch checklist). Served by `get_seo_guide`; the logic behind `generate_page_seo` and
+  `audit_page_seo` lives in `src/seo.mjs`.
 
 ---
 
@@ -101,7 +108,7 @@ The tools are designed to be called in roughly this order when generating UI, no
 grabbed ad hoc:
 
 1. **`get_design_rules`** — call this first, before picking any component. It returns
-   the styling rules, the anti-AI-look rules, and the 50-section product/UX guide. This
+   the styling rules, the anti-AI-look rules, and the 63-section product/UX guide. This
    shapes *what* to build (hierarchy, when a group actually needs `Card`, when `Modal`
    vs `Drawer`, etc.) before you start reaching for components.
 2. **`get_theme`** — call alongside step 1, not instead of it. Tokens without the design
@@ -120,13 +127,17 @@ grabbed ad hoc:
    `antiAiLookRules` from `get_design_rules` before considering the UI
    done — reread them, don't just rely on having read them once at the start.
 
+7. **For public pages**, call **`get_seo_guide`** once, then **`generate_page_seo`** for
+   each page (meta, OpenGraph and a woven JSON-LD graph in the project's framework) and
+   **`audit_page_seo`** to check the finished page.
+
 Steps 1–2 only need to happen once per session/task, not once per component — refetching
 `get_theme`/`get_design_rules` for every single component would be wasteful. Step 4 is
 the one that repeats for every new component.
 
 ---
 
-## 5. The five tools, in detail
+## 5. The eight tools, in detail
 
 ### `list_components`
 
@@ -230,7 +241,7 @@ requirements — e.g. `CardBody` is compulsory whenever `Card` has body content,
 `Card` itself renders no padding — and component-specific gotchas like Dropdown's
 trigger already stopping propagation internally) and **`antiAiLookRules`** (no
 gradients/shadows/blurs/glows/emoji-icons/em-dashes — the visual tells that make UI read
-as AI-generated), plus **`productDesignGuide`** — a 50-section product/UX design guide
+as AI-generated), plus **`productDesignGuide`** — a 63-section product/UX design guide
 covering design philosophy, visual hierarchy, page/sidebar/navigation structure,
 per-component usage guidance (when to reach for `Card` vs plain whitespace, `Modal` vs
 `Drawer`, `Table` vs `List`, etc.), spacing/color/border/radius/shadow conventions,
@@ -258,13 +269,59 @@ Call this before generating any UI — see the recommended workflow above.
     "sections": [
       { "number": 1, "title": "Core Design Philosophy", "content": "..." },
       { "number": 7, "title": "Cards", "content": "..." },
-      // ...50 sections total
+      // ...63 sections total
     ],
     "goldenRule": { "title": "Golden Rule", "content": "..." }
   }
 }
 ```
 
+### `get_seo_guide`
+
+Returns the SEO / AEO / GEO playbook from `data/seoGuide.json`: the whole guide, or one
+topic via `topic` (`technical`, `performance`, `on-page`, `keywords-intent`, `eeat`,
+`aeo`, `geo`, `schema`, `faq`, `meta-checklist`, `frameworks`, `page-templates`,
+`site-wide`, `ads-readiness`, `off-page-monitoring`, `launch-checklist`).
+
+```json
+{ "topic": "geo" }
+```
+
+### `generate_page_seo`
+
+Deterministic generator (no LLM, never invents facts) for everything one page needs:
+a meta title (60 chars max) and description (155 max), canonical, robots, OpenGraph
+and Twitter tags, and one JSON-LD `@graph` weaving Organization, WebSite, WebPage,
+BreadcrumbList, the page-type node (TechArticle, BlogPosting, SoftwareApplication for
+tool and product pages, Product with offers), HowTo (from the visible `steps`), ItemList
+(from a category's `items`) and FAQPage together by stable `@id`s (the same scheme as
+`neuctra-ui-docs-v2/lib/seo/schemas`). Returns a ready-to-paste snippet for
+`nextjs-app`, `nextjs-pages`, `react-vite`, `react-router`, `astro`, `tanstack-start`,
+`gatsby` or `html`, plus warnings and AEO/GEO follow-ups.
+
+```json
+{
+  "framework": "nextjs-app",
+  "pageType": "docs",
+  "siteName": "Neuctra UI",
+  "siteUrl": "https://ui.neuctra.com",
+  "path": "/docs/card",
+  "primaryKeyword": "react card component",
+  "description": "Composable React card component with header, body and footer sections...",
+  "faqs": [{ "question": "Does Card support dark mode?", "answer": "Yes. ..." }]
+}
+```
+
+### `audit_page_seo`
+
+Rule-based check of one page. The easiest input is the page's built HTML (`html`, from
+view-source or the `out/` / `dist/` folder): title, description, canonical, headings,
+og:image, JSON-LD types, alt text and word count are extracted from it. Explicit fields
+override the extracted ones, and checks without input are skipped. It catches doubled or
+missing brand suffixes (with `brandName`), duplicate schema nodes, JSON-LD that doesn't
+parse, and pages that render client-only (no H1 in the HTML). Returns a 0–100 score and a sorted
+list of `fail` / `warn` / `pass` items, each with the exact fix.
+
 ---
 
 ## 6. Local development
@@ -363,13 +420,15 @@ neuctra-ui-mcp/
 ├── bin/
 │   └── cli.mjs              # entry point: connects the server to a stdio transport
 ├── src/
-│   └── server.mjs           # defines the 5 tools and their handlers
+│   ├── server.mjs           # defines the 8 tools and their handlers
+│   └── seo.mjs              # pure builders behind generate_page_seo / audit_page_seo
 ├── scripts/
 │   └── sync-registry.mjs    # copies registry/components.json from neuctra-ui-package
 ├── data/
 │   ├── components.json      # synced (generated) — don't edit by hand
 │   ├── theme.json           # hand-curated token + styling/anti-AI-look rules
-│   └── aiDesignRules.json   # hand-curated 50-section product/UX design guide
+│   ├── aiDesignRules.json   # hand-curated 63-section product/UX design guide
+│   └── seoGuide.json        # hand-curated SEO / AEO / GEO playbook
 └── package.json
 ```
 

package/data/aiDesignRules.json

@@ -50,7 +50,7 @@
     {
       "number": 10,
       "title": "Typography",
-      "content": "Typography should create hierarchy without requiring excessive decoration.\n\nRecommended hierarchy:\n\n```text\nPage title\n↓\nSection title\n↓\nComponent title\n↓\nBody text\n↓\nMetadata\n```\n\nUse:\n\n* Strong weight for headings\n* Regular weight for descriptions\n* Muted color for metadata\n* Comfortable line-height for reading\n\nAvoid:\n\n* Excessive bold text\n* Too many font sizes\n* All-caps body text\n* Huge headings on every page\n* Centering everything"
+      "content": "Typography should create hierarchy without requiring excessive decoration.\n\nRecommended hierarchy:\n\n```text\nPage title\n↓\nSection title\n↓\nComponent title\n↓\nBody text\n↓\nMetadata\n```\n\nUse:\n\n* Strong weight for headings\n* Regular weight for descriptions\n* `text-secondary` for paragraphs and descriptions\n* Muted color for metadata\n* Comfortable line-height for reading — but from the text-size class itself (text-sm, text-base, text-lg, ...), not a separate leading-* utility layered on top; the text-size class already pairs a line-height, so adding leading-* alongside it is redundant\n\nSee Type Scale (section 52) and Readable Measure (section 53) for exact classes.\n\nAvoid:\n\n* Excessive bold text\n* Too many font sizes\n* All-caps body text\n* Huge headings on every page\n* Centering everything\n* Adding leading-* on top of a text-size class that already sets line-height"
     },
     {
       "number": 11,
@@ -175,7 +175,7 @@
     {
       "number": 35,
       "title": "Responsive Design",
-      "content": "Design mobile-first.\n\nDesktop:\n\n```text\nSidebar + Main Content\n```\n\nTablet:\n\n```text\nCollapsed Sidebar + Main Content\n```\n\nMobile:\n\n```text\nTop Bar\nContent\n```\n\nNavigation should become more compact rather than simply shrinking.\n\nForms should become single-column where necessary.\n\nCards should stack naturally.\n\nTables may require:\n\n* horizontal scrolling\n* responsive transformation\n* reduced columns\n\nNever allow the layout to become horizontally broken."
+      "content": "Design mobile-first.\n\nDesktop:\n\n```text\nSidebar + Main Content\n```\n\nTablet:\n\n```text\nCollapsed Sidebar + Main Content\n```\n\nMobile:\n\n```text\nTop Bar\nContent\n```\n\nNavigation should become more compact rather than simply shrinking.\n\nForms should become single-column where necessary.\n\nCards should stack naturally.\n\nTables may require:\n\n* horizontal scrolling\n* responsive transformation\n* reduced columns\n\nNever allow the layout to become horizontally broken.\n\nSee the Breakpoint Checklist (section 59) for the widths and checks every page must pass."
     },
     {
       "number": 36,
@@ -185,7 +185,7 @@
     {
       "number": 37,
       "title": "Color Rules",
-      "content": "Use color semantically.\n\nPrimary color:\n\n* Primary actions\n* Active navigation\n* Important interactive elements\n* Focus states\n\nMuted colors:\n\n* Secondary information\n* Metadata\n* Supporting text\n\nSemantic colors:\n\n* Success\n* Warning\n* Error\n* Info\n\nDo not use many unrelated accent colors.\n\nA modern interface should generally have:\n\n```text\n1 primary brand color\n+\nneutral system\n+\nsemantic colors\n```"
+      "content": "Use color semantically.\n\nPrimary color:\n\n* Primary actions\n* Active navigation\n* Important interactive elements\n* Focus states\n\nText colors:\n\n* `text-foreground` for headings and titles\n* `text-secondary` for paragraphs and supporting text\n* `text-muted-foreground` for metadata and hints\n\nSemantic colors:\n\n* Success\n* Warning\n* Error\n* Info\n\nDo not use many unrelated accent colors.\n\nA modern interface should generally have:\n\n```text\n1 primary brand color\n+\nneutral system\n+\nsemantic colors\n```"
     },
     {
       "number": 38,
@@ -251,10 +251,75 @@
       "number": 50,
       "title": "Do Not Overwrite Built-in Component Design",
       "content": "Use each `@neuctra/ui` component's built-in design — its default spacing, radius, colors, and layout — as-is.\n\nDo not pass a `className` just to restyle a component's built-in appearance because of personal preference. The component's own design is already the intended, consistent look.\n\nOnly override with Tailwind's `!` important-modifier (e.g. `!bg-red-500`, `!p-2`, `!rounded-lg`) when there is a real, specific need:\n\n* The component's default would otherwise break the current page's existing layout.\n* The default collides or conflicts with the current UI/design of the site.\n* The component has no prop for the needed variation, and leaving the default would visually damage the surrounding design.\n\nNever reach for `!important` overrides as a routine styling habit, a stylistic preference, or 'just because'.\n\nPrefer:\n\n> built-in component design → prop-based variation (variant, size, etc.) → `!important` override (rare, only to prevent breakage)\n\nover:\n\n> restyle every component by default with className overrides\n\nA component that has been overridden with `!important` on every use is a sign the component itself, or the way it's being used, is wrong — not that every instance needs forcing."
+    },
+    {
+      "number": 51,
+      "title": "Paragraph Text Color",
+      "content": "Use `text-secondary` for all paragraph text: body copy, section descriptions, card descriptions, and supporting text under headings.\n\nDo not use `text-muted-foreground` for paragraphs. It is too low-contrast for reading text.\n\nKeep `text-muted-foreground` for small, low-priority text only:\n\n* Timestamps\n* Metadata\n* Captions\n* Placeholders\n* Helper and hint text\n* Disabled states\n\nUse `text-foreground` for headings, titles, and anything that needs full emphasis.\n\n`secondary` is a text color only. Do not use it as a background (`bg-secondary`).\n\nOrder of emphasis:\n\n```text\ntext-foreground        ← headings\n↓\ntext-secondary         ← paragraphs\n↓\ntext-muted-foreground  ← metadata and hints\n```\n\nToken values:\n\n* Light theme: `--secondary: #3f3f46`\n* Dark theme: `--secondary: #d4d4d8`"
+    },
+    {
+      "number": 52,
+      "title": "Type Scale",
+      "content": "Use one fixed, responsive type scale on every page:\n\n```text\nDisplay / H1  text-4xl sm:text-5xl lg:text-6xl font-bold tracking-tight\nH2            text-3xl sm:text-4xl font-semibold tracking-tight\nH3            text-xl sm:text-2xl font-semibold\nBody          text-base\nSmall         text-sm\nMeta          text-xs\n```\n\nRules:\n\n* Never use more than 4 text sizes on one screen.\n* Add `text-balance` to headings so lines break evenly.\n* Add `text-pretty` to paragraphs to avoid single-word last lines.\n* Step headings down one level at a time. Do not jump from H1 straight to small text.\n* `tracking-tight` only on `text-3xl` and larger. Everything smaller stays at the default tracking.\n* Line-height comes from the text-size class. Do not add `leading-*` on top of it."
+    },
+    {
+      "number": 53,
+      "title": "Readable Measure",
+      "content": "Long lines are hard to read.\n\n* Paragraphs: `max-w-prose` or `max-w-2xl`.\n* Headings may run wider: `max-w-3xl`.\n* Never let body text stretch the full width of a wide container.\n\nThe layout can be wide. The reading column should not be."
+    },
+    {
+      "number": 54,
+      "title": "Spacing Rhythm",
+      "content": "Use the 4/8 spacing scale only. Space shrinks as you go deeper into the layout.\n\n```text\nPage gutters        px-4 sm:px-6 lg:px-8\nBetween sections    py-16 sm:py-20 lg:py-28\nBetween blocks      mt-10 / mt-12\nHeading to body     mt-4\nInside a component  gap-2 / gap-3\n```\n\nBig gaps separate ideas. Small gaps group them. If everything has the same gap, nothing is grouped."
+    },
+    {
+      "number": 55,
+      "title": "Grid & Layout Patterns",
+      "content": "Build layouts from a few reliable patterns:\n\n* **Card grid:** `grid grid-cols-1 sm:grid-cols-2 lg:grid-cols-3 gap-4 sm:gap-6`.\n* **Split:** text and visual side by side with `lg:grid-cols-2`, alternating sides from one section to the next.\n* **Bento:** one large tile (`lg:col-span-2`) with smaller tiles around it, instead of identical boxes.\n* **Asymmetric:** `lg:grid-cols-[2fr_1fr]` for main content plus a side column. Grid templates like this are the one allowed exception to the no-arbitrary-values rule.\n\nAdd `min-w-0` to flex and grid children that contain text, so truncation works instead of overflowing.\n\nAvoid the default \"three equal cards in a row\" on every section."
+    },
+    {
+      "number": 56,
+      "title": "Hero / Above the Fold",
+      "content": "The hero must answer \"what is this and why should I care\" within 5 seconds.\n\nRecommended order:\n\n```text\nBadge            short eyebrow (New, Beta, v2.0)\nH1               value proposition, under 10 words\nLead text        text-lg text-secondary, one or two sentences\nActions          one primary Button + one secondary Button\nProof            real product screenshot, stat row, or customer logos\n```\n\n* Left-align by default. Center only short, single-message heroes.\n* Use a split layout (text left, visual right) on `lg` and stack on mobile.\n* One primary action only. The second action is outline or ghost."
+    },
+    {
+      "number": 57,
+      "title": "Focal Point & Visual Interest",
+      "content": "Eye-catching does not mean effects. Gradients, shadows and blur stay banned.\n\nVisual interest comes from:\n\n* **Scale contrast:** a very large headline next to small, quiet metadata.\n* **One bold element per viewport:** a single `bg-primary` block, button or highlight that the eye lands on first.\n* **Surface layering:** alternate sections between `bg-background`, `bg-card` and `bg-accent` bands to create depth without shadows.\n* **Big numbers:** metrics in large type with `tabular-nums`.\n* **Real imagery:** product screenshots and photos, not decorative filler.\n* **Whitespace:** give the most important element more space than anything around it.\n\nColor ratio: roughly 60% neutral surfaces, 30% text and borders, 10% primary."
+    },
+    {
+      "number": 58,
+      "title": "Section Variety",
+      "content": "A page should feel composed, not stamped out.\n\n* Never use the same layout for two sections in a row.\n* Mix patterns: split, card grid, bento, full-width band, stat row, testimonial, FAQ, CTA band.\n* Alternate background surfaces between neighbouring sections.\n* End every landing page with a clear call-to-action section."
+    },
+    {
+      "number": 59,
+      "title": "Breakpoint Checklist",
+      "content": "Design mobile-first, then check every page at:\n\n```text\n360px   small phone\n768px   tablet\n1024px  small laptop\n1280px  desktop\n1536px  large desktop\n```\n\nAt every width:\n\n* No horizontal scroll.\n* Touch targets are at least 44px.\n* Navigation collapses into a Drawer below `md`.\n* Tables sit inside `overflow-x-auto`.\n* Images use an `aspect-*` class with `object-cover`, so nothing shifts while loading.\n* On mobile, stack content in order of importance (use `order-*` when the source order differs)."
+    },
+    {
+      "number": 60,
+      "title": "Imagery & Media",
+      "content": "* Use consistent aspect ratios: `aspect-video`, `aspect-square`, or `aspect-[4/3]` (allowed ratio).\n* Use one corner radius for all images on a page.\n* Always write real, descriptive `alt` text.\n* Lazy-load images below the fold.\n* Prefer real product screenshots over stock illustrations or abstract shapes."
+    },
+    {
+      "number": 61,
+      "title": "Iconography",
+      "content": "* Use lucide-react icons only.\n* Match icon size to the text beside it: 16px with `text-sm`, 20px with `text-base`, 24px next to headings.\n* Keep the same stroke width across the whole interface.\n* Icons support labels. They do not replace them, except in an IconButton with a Tooltip.\n* Do not wrap every icon in a colored circle."
+    },
+    {
+      "number": 62,
+      "title": "Motion Timing",
+      "content": "Motion explains a change. It is never decoration.\n\n```text\nHover / press     transition-colors duration-150\nOpen / close      200 to 300ms, ease-out\nPage load         no entrance animations\n```\n\n* Respect reduced motion with `motion-reduce:` variants.\n* Animate color and opacity. Do not animate layout or add hover-scale."
+    },
+    {
+      "number": 63,
+      "title": "Microcopy",
+      "content": "Words are part of the design.\n\n* Sentence case for headings, buttons and labels.\n* Buttons start with a verb: \"Create project\", not \"Submit\".\n* Headlines state the benefit, not the feature name.\n* One idea per sentence. Short sentences.\n* No em dashes. Use a period, comma or colon instead."
     }
   ],
   "goldenRule": {
     "title": "Golden Rule",
     "content": "Do not ask:\n\n> \"Which components can I put on this page?\"\n\nAsk:\n\n> \"What does the user need to understand and do, and which Neuctra UI component communicates that most naturally?\"\n\nThe best Neuctra UI interface is not the one that uses the most components.\n\nIt is the one where **every component has a purpose.**"
   }
-}
+}