@neuctra/ui-mcp 0.3.1 → 0.4.2

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)
         │
@@ -47,14 +47,14 @@ neuctra-ui-mcp/data/components.json                 (this package's local copy)
         │
         │  read once at server startup
         ▼
-neuctra-ui-mcp/src/server.mjs                        (defines 4 MCP tools over that data)
+neuctra-ui-mcp/src/server.mjs                        (defines 5 MCP tools over that data)
         │
         │  spoken over stdio (stdin/stdout), JSON-RPC under the hood
         ▼
    Claude Code / Cursor / Antigravity / any MCP client
 ```
 
-Two independently-regenerable files feed the server:
+Three independently-regenerable files feed the server:
 
 - **`data/components.json`** — synced from `neuctra-ui-package/registry/components.json`.
   Never edit this by hand; run `npm run sync-registry` after the upstream file changes.
@@ -64,6 +64,13 @@ Two 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 51-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`.
 
 ---
 
@@ -81,14 +88,45 @@ The host starts your server as a subprocess and talks to it over **stdio** — y
 server's stdout carries JSON-RPC messages, not human-readable logs (that's why
 `bin/cli.mjs` prints nothing except protocol traffic; use `console.error`, never
 `console.log`, if you ever add debug output). On connect, the client asks "what tools do
-you have?", gets back the 4 tool definitions below, and adds them to the AI's available
+you have?", gets back the 5 tool definitions below, and adds them to the AI's available
 actions — the same way the tools listed in *this* conversation's system prompt work.
 From then on, the AI decides on its own when a tool call would help, calls it, and reads
 the result back into its context before continuing.
 
 ---
 
-## 4. The four tools, in detail
+## 4. Recommended workflow
+
+The tools are designed to be called in roughly this order when generating UI, not
+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 51-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
+   rules just tell you which colors exist, not how to use them well.
+3. **`list_components`** (filtered by category) or **`search_components`** (keyword) —
+   confirm which real components exist for what you need. This matters specifically
+   because the design guide can describe a *pattern* (e.g. a sidebar nav item) without
+   there being a dedicated component for it — don't assume one exists, confirm here.
+4. **`get_component`** — full spec for every component before writing code against it.
+   Do this every time you touch a component you haven't already pulled specs for in the
+   current conversation, not just once at the start. Never guess prop names from memory.
+5. **Write the UI**, applying the design rules, the tokens, and the exact props from
+   step 4.
+6. **Self-check** against the "Final UI Quality Checklist" section (§49, found by
+   its `number` field in `productDesignGuide.sections` — not by array index) and
+   `antiAiLookRules` from `get_design_rules` before considering the UI
+   done — reread them, don't just rely on having read them once at the start.
+
+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
 
 ### `list_components`
 
@@ -157,36 +195,24 @@ state", "icon button". Matches against name, category, description, and prop nam
 
 ### `get_theme`
 
-Returns the semantic color token system, the styling rules for using it, and three more
-sections aimed squarely at making generated UI indistinguishable from a human design
-pass: a set of **anti-AI-look rules** (no gradients, no decorative shadows/blurs/glows,
-no emoji-as-icons — see below), a **setup** block pointing the AI at the
-`@neuctra/ui-cli` `init` command instead of hand-writing token CSS or a theme context,
-and a **toastNote** explaining the standalone `toast()` import. Without `get_theme`, an
-AI would happily write `className="bg-blue-500"` or reach for a purple-to-pink gradient
-hero, both of which ignore the consumer's actual theme and read as generic AI output.
+Returns the semantic color token system: the token list itself, a **setup** block
+pointing the AI at the `@neuctra/ui-cli` `init` command instead of hand-writing token CSS
+or a theme context, and a **toastNote** explaining the standalone `toast()` import.
+Without `get_theme`, an AI would happily write `className="bg-blue-500"`, ignoring the
+consumer's actual theme. `get_theme` does **not** carry the design/anti-AI-look rules —
+see `get_design_rules` below for those; call both together, not one instead of the other.
 
 **Response shape:**
 ```jsonc
 {
   "system": "Tailwind CSS v4, semantic CSS-variable tokens mapped via @theme, toggled by a .dark class...",
-  "rules": [
-    "Never use hardcoded Tailwind palette colors...",
-    "Always use the semantic token classes below...",
-    // ...
-  ],
-  "antiAiLookRules": [
-    "No gradients on backgrounds, buttons, or text...",
-    "No decorative box-shadows, drop-shadows, or glow effects...",
-    "No backdrop-blur / glassmorphism...",
-    // ...17 rules total — the visual tells that make UI read as AI-generated
-  ],
   "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." },
     // ...23 tokens total
   ],
+  "note": "Values shown are the CLI-generated defaults...",
   "setup": {
     "recommendedCommand": "npx @neuctra/ui-cli@latest init",
     "whatItDoes": ["Installs @neuctra/ui.", "Checks/upgrades React and Tailwind CSS.", "..."],
@@ -196,9 +222,52 @@ hero, both of which ignore the consumer's actual theme and read as generic AI ou
 }
 ```
 
+### `get_design_rules`
+
+Returns every design rule generated UI must follow, at two levels: the mechanical
+**`stylingRules`** (token usage, surface/background conventions, component composition
+requirements — e.g. `CardBody` is compulsory whenever `Card` has body content, since
+`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 51-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,
+responsive design, accessibility, interaction design, and a final UI quality checklist.
+
+Call this before generating any UI — see the recommended workflow above.
+
+**Response shape (trimmed):**
+```jsonc
+{
+  "stylingRules": [
+    "Theme colors only, compulsory, no exceptions...",
+    "Use the Card component, not a hand-rolled lookalike...",
+    // ...9 rules total
+  ],
+  "antiAiLookRules": [
+    "No gradients, compulsory...",
+    "No shadows, compulsory...",
+    "No blur effects, compulsory...",
+    // ...17 rules total
+  ],
+  "productDesignGuide": {
+    "title": "Neuctra UI — AI Design Rules",
+    "intro": "You are a senior product designer and frontend UI engineer using `@neuctra/ui`...",
+    "sections": [
+      { "number": 1, "title": "Core Design Philosophy", "content": "..." },
+      { "number": 7, "title": "Cards", "content": "..." },
+      // ...51 sections total
+    ],
+    "goldenRule": { "title": "Golden Rule", "content": "..." }
+  }
+}
+```
+
 ---
 
-## 5. Local development
+## 6. Local development
 
 ```bash
 npm install
@@ -208,14 +277,14 @@ npm start                # runs the server on stdio — it will sit there silent
 
 `npm start` alone won't show you anything (it's waiting for a client to speak JSON-RPC
 to it, not for a human to type at it). To actually exercise it, either wire it into a
-real client (section 6) or write a small script using
+real client (section 7) or write a small script using
 `@modelcontextprotocol/sdk`'s `Client` + `StdioClientTransport` to spawn `bin/cli.mjs`
 and call the tools programmatically — that's how this server was verified while building
 it.
 
 ---
 
-## 6. Connecting it to a client
+## 7. Connecting it to a client
 
 All MCP clients use the same JSON shape — the differences are just *where* the config
 file lives.
@@ -256,7 +325,7 @@ Restart the client after editing its config — servers are only launched on sta
 
 ---
 
-## 7. Keeping the registry in sync
+## 8. Keeping the registry in sync
 
 The registry is generated, not hand-maintained. Whenever a component's props change:
 
@@ -271,12 +340,14 @@ npm run sync-registry         # copies the updated file in
 `registry:generate` also runs automatically as part of `neuctra-ui-package`'s
 `prepublishOnly`, and `sync-registry` runs automatically as part of this package's own
 `prepublishOnly` — so a normal `npm publish` in each package keeps things current without
-remembering these steps by hand. `data/theme.json` is the one file with no generator;
-edit it directly if the token set in `neuctra-ui-cli/lib/update-css.js` ever changes.
+remembering these steps by hand. `data/theme.json` and `data/aiDesignRules.json` are the
+two files with no generator; edit them directly — `theme.json` if the token set in
+`neuctra-ui-cli/lib/update-css.js` ever changes or a rule needs adding, `aiDesignRules.json`
+if the product-design guidance itself needs revising.
 
 ---
 
-## 8. Publishing
+## 9. Publishing
 
 ```bash
 npm run sync-registry
@@ -285,25 +356,26 @@ npm publish --access public   # --access public is required: scoped packages def
 
 ---
 
-## 9. Project structure
+## 10. Project structure
 
 ```
 neuctra-ui-mcp/
 ├── bin/
 │   └── cli.mjs              # entry point: connects the server to a stdio transport
 ├── src/
-│   └── server.mjs           # defines the 4 tools and their handlers
+│   └── server.mjs           # defines the 5 tools and their handlers
 ├── 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/rules data
+│   ├── theme.json           # hand-curated token + styling/anti-AI-look rules
+│   └── aiDesignRules.json   # hand-curated 51-section product/UX design guide
 └── package.json
 ```
 
 ---
 
-## 10. Extending it
+## 11. Extending it
 
 To add a new tool (e.g. `get_example` returning just the code snippet, or
 `list_categories`), open `src/server.mjs` and add another `server.registerTool(...)`

package/data/aiDesignRules.json

@@ -0,0 +1,265 @@
+{
+  "title": "Neuctra UI — AI Design Rules",
+  "intro": "You are a senior product designer and frontend UI engineer using `@neuctra/ui`.\n\nYour goal is NOT to simply place components on a page.\n\nYour goal is to create interfaces that feel:\n\n* Modern\n* Human-designed\n* Visually balanced\n* Clean\n* Calm\n* Premium\n* Product-focused\n* Easy to scan\n* Consistent\n* Responsive\n* Accessible\n* Intentional rather than template-generated\n\nUse `@neuctra/ui` components whenever an appropriate component exists.",
+  "sections": [
+    {
+      "number": 1,
+      "title": "Core Design Philosophy",
+      "content": "Every UI decision must have a reason.\n\nDo not generate interfaces by randomly combining components.\n\nThink in this order:\n\n1. What is the user's primary goal?\n2. What information is most important?\n3. What action should receive the most visual attention?\n4. What information can be grouped together?\n5. What should be visually secondary?\n6. What can be hidden until needed?\n7. Which component best communicates the purpose?\n\nPrefer:\n\n> hierarchy → spacing → grouping → interaction → decoration\n\nover:\n\n> components → colors → decoration\n\nThe interface should still look good even if all decorative elements are removed."
+    },
+    {
+      "number": 2,
+      "title": "Visual Hierarchy",
+      "content": "Every page must have a clear hierarchy.\n\nUse approximately:\n\n### Level 1 — Primary\n\nThe most important thing on the page.\n\nExamples:\n\n* Page title\n* Main dashboard metric\n* Primary action\n* Main content\n\nUse:\n\n* Large heading\n* Strong typography\n* Primary Button\n* Card when grouping is necessary\n\n### Level 2 — Secondary\n\nSupporting information.\n\nExamples:\n\n* Description\n* Secondary metrics\n* Filters\n* Supporting actions\n\nUse:\n\n* Text\n* Badge\n* Chip\n* Button\n* Card\n\n### Level 3 — Tertiary\n\nLow-priority information.\n\nExamples:\n\n* Metadata\n* timestamps\n* categories\n* hints\n* supporting labels\n\nUse:\n\n* muted text\n* Badge\n* Chip\n* Kbd\n* Tooltip\n\nNever make tertiary information visually compete with the primary content."
+    },
+    {
+      "number": 3,
+      "title": "Page Structure",
+      "content": "Use a predictable structure:\n\n```text\nPage\n ├── Page Header\n │    ├── Title\n │    ├── Description\n │    └── Primary Action\n │\n ├── Optional Context / Callout\n │\n ├── Filters / Controls\n │\n └── Main Content\n```\n\nDo not add every section automatically.\n\nIf the page does not need a Callout, Card, Badge, or Divider, do not use it.\n\nLess UI is often better UI."
+    },
+    {
+      "number": 4,
+      "title": "Sidebar Design",
+      "content": "The sidebar is navigation, not content.\n\nKeep it visually quiet.\n\n@neuctra/ui has no dedicated Navigation/Sidebar/NavLink component — hand-build nav items from Button's ghost or link variant (icon + label), Text for section labels, and Divider for grouping.\n\nRecommended structure:\n\n```text\nLogo / Product\nVersion\n\nMain Navigation\n\nSection Label\nNavigation items\n\nSection Label\nNavigation items\n\nResources\n\nAbout\n```\n\nUse:\n\n* Button (ghost/link variant) for primary navigation links\n* Text for section labels/grouping\n* Badge for small status/version information\n* Icon Button for compact actions\n* Tooltip when labels are hidden\n* Divider only when separation improves scanning\n\nDo not:\n\n* Put large cards inside the sidebar\n* Use excessive borders\n* Use multiple competing accent colors\n* Put descriptions beside every navigation item\n* Turn every navigation item into a Badge or Chip\n* Add decorative illustrations unnecessarily\n\nThe sidebar should support the page, not dominate it."
+    },
+    {
+      "number": 5,
+      "title": "Navigation Grouping",
+      "content": "Group navigation according to the user's mental model. 'Navigation items' here means hand-built links (Button ghost/link variant), not a dedicated component — see the note in the Sidebar Design section.\n\nFor example:\n\n```text\nGetting Started\n\nOverview\nFull Setup Guide\nTheme Toggle\n\nAI & Integrations\n\nNeuctra UI MCP\n\nLayout & Structure\n\nContainer\nCard\nDivider\n\nTypography & Media\n\nText\nImage\nAvatar\nAvatar Group\nBadge\nChip\nKbd\n```\n\nSection labels should be:\n\n* Small\n* Muted\n* Uppercase or subtle typography\n* Visually separated from navigation items\n\nDo not over-group.\n\nA section should contain enough related items to justify the heading."
+    },
+    {
+      "number": 6,
+      "title": "Navigation Item Rules",
+      "content": "Navigation items (hand-built from Button's ghost/link variant — there is no dedicated Navigation component) should have:\n\n* Clear label\n* Optional icon\n* Strong hover state\n* Obvious active state\n* Comfortable click target\n\nRecommended hierarchy:\n\n```text\nInactive:\nmuted foreground\n\nHover:\nsubtle background\n\nActive:\nprimary-tinted background\nprimary/strong foreground\n```\n\nAvoid making every item look like a Button.\n\nNavigation should visually feel different from action controls."
+    },
+    {
+      "number": 7,
+      "title": "Cards",
+      "content": "Use `Card` when content represents a meaningful visual group.\n\nGood:\n\n```text\nCard\n ├── CardHeader (optional)\n ├── CardBody (compulsory whenever there's body content)\n └── CardFooter (optional)\n```\n\n`Card` itself renders no padding — it's just the border/background/radius shell. All spacing lives in `CardHeader`/`CardBody`/`CardFooter`. Content placed directly inside `<Card>` without `<CardBody>` renders flush against the border with no padding and visibly breaks the layout, so once you've decided to use Card, wrapping its body content in `<CardBody>` is not optional the way `CardHeader`/`CardFooter` are.\n\nUse Cards for:\n\n* Dashboard statistics\n* Settings groups\n* Product previews\n* Related information\n* Independent content blocks\n\nDo NOT wrap everything in Cards.\n\nAvoid:\n\n```text\nPage\n └── Card\n      └── Card\n           └── Card\n```\n\nNested cards should be rare.\n\nIf content is already visually grouped by whitespace, a Card may not be necessary."
+    },
+    {
+      "number": 8,
+      "title": "Container",
+      "content": "Use `Container` to control readable page width.\n\nPrefer:\n\n```text\nFull viewport\n └── Container\n      └── Content\n```\n\nDo not allow text-heavy interfaces to become excessively wide.\n\nFor documentation:\n\n* Keep reading width comfortable.\n* Allow code examples to use more horizontal space.\n* Keep navigation independent from the reading column."
+    },
+    {
+      "number": 9,
+      "title": "Divider",
+      "content": "Use `Divider` only when whitespace is insufficient to communicate separation.\n\nPrefer:\n\n```text\nSection\n\nlarge spacing\n\nNext Section\n```\n\nover:\n\n```text\nSection\n────────────\nNext Section\n```\n\nUse Dividers primarily for:\n\n* Navigation groups\n* Dense settings\n* Table-like layouts\n* Clearly separated sections\n\nDo not place Dividers everywhere."
+    },
+    {
+      "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* `text-secondary` for paragraphs and 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"
+    },
+    {
+      "number": 11,
+      "title": "Badge",
+      "content": "Use `Badge` for compact semantic information.\n\nGood:\n\n```text\nv1.0\nNew\nBeta\nActive\nDeprecated\nSuccess\nWarning\n```\n\nBad:\n\n```text\nEvery navigation item\nEvery card\nEvery paragraph\nEvery heading\n```\n\nA Badge should communicate information, not decoration."
+    },
+    {
+      "number": 12,
+      "title": "Chip",
+      "content": "Use `Chip` for lightweight categories or selectable labels.\n\nGood:\n\n```text\nReact\nTailwind\nTypeScript\nFrontend\nDesign\n```\n\nUse Chip when users may perceive the value as a category, filter, or tag.\n\nDo not use Badge and Chip interchangeably."
+    },
+    {
+      "number": 13,
+      "title": "Button",
+      "content": "Buttons represent actions.\n\nHierarchy:\n\n```text\nPrimary Button\nSecondary Button\nTertiary / subtle Button\nDestructive Button\n```\n\nEvery page should generally have one visually dominant primary action, when an important action exists.\n\nAvoid having multiple primary buttons competing with each other.\n\nExample:\n\n```text\nCreate Project        ← Primary\n\nImport        Export  ← Secondary\n```"
+    },
+    {
+      "number": 14,
+      "title": "Icon Button",
+      "content": "Use `Icon Button` when the action is universally understandable from the icon or when space is limited.\n\nGood examples:\n\n* Close\n* Search\n* Settings\n* More\n* Edit\n* Delete\n* Copy\n* Previous\n* Next\n\nUse `Tooltip` when an icon's meaning is not immediately obvious.\n\nNever sacrifice usability for minimalism."
+    },
+    {
+      "number": 15,
+      "title": "Input / Form Components",
+      "content": "Forms should feel calm and structured.\n\nRecommended:\n\n```text\nForm Section\n ├── Label\n ├── Input\n ├── Description\n └── Error\n```\n\nGroup related fields.\n\nDo not place every field in a separate Card.\n\nUse:\n\n* Input for text\n* Textarea for long text\n* Select for predefined options\n* Checkbox for independent choices\n* RadioGroup for mutually exclusive choices\n* Switch for immediate on/off settings\n* Slider for ranges\n* Number Input for numeric values\n* Date Picker for dates\n* Time Picker for times\n* File Upload for files"
+    },
+    {
+      "number": 16,
+      "title": "Modal",
+      "content": "Use Modal for focused decisions or short tasks.\n\nGood:\n\n* Confirm deletion\n* Create item\n* Edit item\n* Important settings\n* Focused forms\n\nDo not use Modal for:\n\n* Long documentation\n* Large dashboards\n* Complex workflows\n* Information that deserves its own page\n\nIf the content requires significant scrolling, consider a page or Drawer instead."
+    },
+    {
+      "number": 17,
+      "title": "Drawer",
+      "content": "Use Drawer for contextual content that should remain connected to the current page.\n\nGood:\n\n* Filters\n* Detail views\n* Editing\n* Mobile navigation\n* Secondary settings\n\nDrawer is especially useful when the user should keep the underlying page context."
+    },
+    {
+      "number": 18,
+      "title": "Dropdown",
+      "content": "Use Dropdown for actions or compact menus.\n\nGood:\n\n```text\nMore\n ├── Edit\n ├── Duplicate\n ├── Archive\n └── Delete\n```\n\nDo not use Dropdown when users need to compare multiple persistent options.\n\nUse Select instead for form selection."
+    },
+    {
+      "number": 19,
+      "title": "Tooltip",
+      "content": "Use Tooltip for clarification, not essential information.\n\nGood:\n\n```text\nIcon Button\n    ↓\nTooltip: \"Copy\"\n```\n\nDo not hide essential instructions inside tooltips."
+    },
+    {
+      "number": 20,
+      "title": "Popover",
+      "content": "Use Popover for contextual controls or additional information without leaving the page.\n\nGood:\n\n* Advanced filters\n* Color selection\n* Small configuration panels\n* Additional metadata\n* Contextual actions\n\nPopover content should remain lightweight."
+    },
+    {
+      "number": 21,
+      "title": "Tabs",
+      "content": "Use Tabs when multiple related views share the same context.\n\nGood:\n\n```text\nOverview | Activity | Settings\n```\n\nDo not use Tabs simply because the page has multiple sections.\n\nIf users should see the sections together, use normal page sections."
+    },
+    {
+      "number": 22,
+      "title": "Table",
+      "content": "Use Table when users need to compare structured records.\n\nGood:\n\n* Users\n* Orders\n* Transactions\n* Logs\n* Products\n\nProvide:\n\n* Clear column hierarchy\n* Adequate spacing\n* Row hover where useful\n* Pagination when necessary\n* Empty state\n* Loading state\n\nAvoid overly dense tables unless the product specifically requires high information density."
+    },
+    {
+      "number": 23,
+      "title": "List",
+      "content": "Use List when records are naturally read vertically.\n\nGood:\n\n* Notifications\n* Tasks\n* Activities\n* Messages\n* Search results\n\nPrefer List over Table when users don't need column-based comparison."
+    },
+    {
+      "number": 24,
+      "title": "Empty State",
+      "content": "Empty states should explain:\n\n1. What is empty?\n2. Why it matters?\n3. What should the user do next?\n\nExample:\n\n```text\nNo projects yet\n\nCreate your first project to start organizing your work.\n\n[ Create Project ]\n```\n\nDo not create empty states that only say:\n\n> No data found."
+    },
+    {
+      "number": 25,
+      "title": "Alert / Callout",
+      "content": "Use `Callout` for persistent contextual information inside the page.\n\nUse it for:\n\n* Important information\n* Warnings\n* Success states\n* Errors\n* Notices\n* System status\n* Migration messages\n\nExample:\n\n```text\n[Warning]\n\nYour storage is almost full.\nConsider removing unused files.\n```\n\nUse `Callout` when the message belongs to the page's content flow.\n\nDo not use Callout for every notification.\n\nFor temporary notifications, use the toast system.\n\nCallout hierarchy:\n\n```text\nError\nWarning\nSuccess\nInfo\nNeutral\n```\n\nUse semantic types correctly."
+    },
+    {
+      "number": 26,
+      "title": "Progress",
+      "content": "Use Progress when users need to understand completion.\n\nGood:\n\n* Upload progress\n* Onboarding\n* Course completion\n* Project progress\n* Storage usage\n\nDo not use progress bars decoratively.\n\nProgress should represent measurable progress."
+    },
+    {
+      "number": 27,
+      "title": "Skeleton",
+      "content": "Use Skeleton when content is loading and the final layout is known.\n\nThe skeleton should resemble the final content structure.\n\nAvoid replacing the entire page with a generic spinner when the layout can be preserved."
+    },
+    {
+      "number": 28,
+      "title": "Spinner",
+      "content": "Use Spinner for short, localized loading operations.\n\nGood:\n\n```text\n[Save] → spinner → Saving...\n```\n\nAvoid full-page spinners for normal page loading when Skeleton can preserve layout."
+    },
+    {
+      "number": 29,
+      "title": "Accordion",
+      "content": "Use Accordion when information is optional or secondary.\n\nGood:\n\n* FAQs\n* Advanced settings\n* Documentation sections\n* Additional details\n\nDo not hide primary information inside Accordions."
+    },
+    {
+      "number": 30,
+      "title": "Breadcrumb",
+      "content": "Use Breadcrumb when the page has meaningful hierarchy.\n\nExample:\n\n```text\nDocumentation / Components / Forms / Input\n```\n\nDo not use Breadcrumb on simple pages where there is no useful hierarchy."
+    },
+    {
+      "number": 31,
+      "title": "Pagination",
+      "content": "Use Pagination when users need to navigate large datasets.\n\nUse it with:\n\n* Tables\n* Search results\n* Large lists\n\nDo not paginate small datasets unnecessarily."
+    },
+    {
+      "number": 32,
+      "title": "Stepper",
+      "content": "Use Stepper for multi-step processes.\n\nExample:\n\n```text\nAccount → Details → Review → Complete\n```\n\nEach step should have a meaningful stage.\n\nDo not use Stepper for ordinary navigation."
+    },
+    {
+      "number": 33,
+      "title": "Image / Avatar",
+      "content": "Images should support content.\n\nUse:\n\n* Image for visual content\n* Avatar for people\n* Avatar Group for teams/participants\n\nDo not add decorative images simply to fill empty space."
+    },
+    {
+      "number": 34,
+      "title": "Carousel",
+      "content": "Use Carousel only when multiple visual/content items benefit from horizontal browsing.\n\nGood:\n\n* Product screenshots\n* Testimonials\n* Image galleries\n* Featured content\n\nDo not use Carousel for content that users need to compare simultaneously."
+    },
+    {
+      "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."
+    },
+    {
+      "number": 36,
+      "title": "Spacing Rules",
+      "content": "Use spacing to establish hierarchy.\n\nUse smaller spacing:\n\n* Within a component\n* Between label and input\n* Between icon and text\n\nUse larger spacing:\n\n* Between sections\n* Between page regions\n* Before major headings\n\nAvoid equal spacing everywhere.\n\nUnequal spacing creates hierarchy."
+    },
+    {
+      "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\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,
+      "title": "Border Rules",
+      "content": "Borders should clarify structure, not decorate it.\n\nPrefer:\n\n```text\nspacing\n+\nsubtle background differences\n```\n\nbefore adding borders.\n\nUse borders for:\n\n* Inputs\n* Tables\n* Cards when necessary\n* Dividers\n* Clear interactive boundaries\n\nAvoid heavy borders around every element."
+    },
+    {
+      "number": 39,
+      "title": "Radius Rules",
+      "content": "Use consistent corner radii.\n\nDo not randomly mix:\n\n```text\nrounded-sm\nrounded-md\nrounded-lg\nrounded-xl\nrounded-full\n```\n\nUse full rounding primarily for:\n\n* Chips\n* Badges\n* Avatars\n* Compact controls\n\nUse moderate rounding for:\n\n* Cards\n* Inputs\n* Buttons\n* Modals"
+    },
+    {
+      "number": 40,
+      "title": "Shadows",
+      "content": "Never add a shadow yourself, compulsory. Prefer:\n\n```text\nbackground\n+\nborder\n+\nspacing\n```\n\nover a shadow on anything you're styling by hand — buttons, cards, inputs, hand-built panels.\n\nThis is about classNames/markup you author. A number of `@neuctra/ui` components ship their own built-in elevation shadow as part of their default design (overlay/floating components like Modal, Dropdown, Popover, Drawer, Tooltip, and others like Table, DatePicker's calendar panel, Avatar's status dot, Kbd, and the Toast notification, among others — this isn't an exhaustive list to memorize). Leave every component's shipped defaults exactly as they ship: never add a shadow yourself, and never strip a component's built-in one with an override either — both are the same mistake in opposite directions."
+    },
+    {
+      "number": 41,
+      "title": "Modern UI Rule",
+      "content": "Modern does NOT mean:\n\n* excessive gradients\n* glassmorphism everywhere\n* giant rounded cards\n* excessive shadows\n* huge text\n* neon colors\n* random icons\n* excessive animations\n\nModern means:\n\n* clear hierarchy\n* intentional spacing\n* restrained color\n* predictable interaction\n* strong typography\n* useful whitespace\n* consistent components\n* subtle motion\n* responsive behavior"
+    },
+    {
+      "number": 42,
+      "title": "Human-Designed UI Rule",
+      "content": "Before generating the final UI, mentally ask:\n\n> \"Would a professional product designer intentionally put this element here?\"\n\nIf the answer is no, remove it.\n\nDo not add UI simply because a component exists.\n\nThe component library is a toolbox, not a checklist."
+    },
+    {
+      "number": 43,
+      "title": "Avoid AI-Generated UI Patterns",
+      "content": "Never automatically generate:\n\n* Hero section + three cards + gradient\n* Excessive rounded containers\n* Random decorative icons\n* Unnecessary badges\n* Excessive centered text\n* Every section inside a Card\n* Multiple primary buttons\n* Huge empty spaces\n* Excessive shadows\n* Random gradients\n* Generic dashboard cards\n* Repeated identical layouts\n* Decorative statistics without meaning\n\nAvoid the recognizable \"AI-generated SaaS template\" appearance."
+    },
+    {
+      "number": 44,
+      "title": "Component Selection Principle",
+      "content": "When choosing a component, use this decision process:\n\n```text\nNeed navigation?\n→ Tabs / Breadcrumb / Pagination / Stepper\n→ For a sidebar or nav links: hand-build from Button (ghost/link variant) — no dedicated Navigation component exists\n\nNeed an action?\n→ Button / Icon Button\n\nNeed selection?\n→ Select / RadioGroup / Checkbox / Switch\n\nNeed compact metadata?\n→ Badge / Chip\n\nNeed grouped content?\n→ Card\n\nNeed persistent message?\n→ Callout\n\nNeed temporary message?\n→ the toast system (import { toast, ToastProvider } from \"@neuctra/ui\" — not a \"Toast\" component)\n\nNeed focused interaction?\n→ Modal / Drawer / Popover\n\nNeed clarification?\n→ Tooltip\n\nNeed structured records?\n→ Table / List\n\nNeed loading?\n→ Skeleton / Spinner\n\nNeed progress?\n→ Progress\n\nNeed hierarchy?\n→ Accordion / Breadcrumb / Stepper\n```\n\nNever select a component merely because it looks attractive."
+    },
+    {
+      "number": 45,
+      "title": "Documentation UI Rules",
+      "content": "For component documentation, prefer:\n\n```text\nSidebar\n+\nDocumentation Container\n+\nBreadcrumb / Section Context\n+\nComponent Title\n+\nDescription\n+\nLive Preview\n+\nCode\n+\nUsage Guidelines\n+\nProps\n+\nAccessibility\n+\nFAQ\n```\n\nThe documentation page should prioritize the component preview and developer understanding.\n\nKeep code visually distinct from prose."
+    },
+    {
+      "number": 46,
+      "title": "Component Preview Rules",
+      "content": "Every preview should feel like a real product interface.\n\nDo not make previews look like isolated component experiments.\n\nInstead of:\n\n```text\nButton\nButton\nButton\n```\n\nprefer contextual examples:\n\n```text\nProject Settings\n\nProject name\n[ My Project                  ]\n\n[ Cancel ] [ Save Changes ]\n```\n\nThis demonstrates how the component actually behaves in a product."
+    },
+    {
+      "number": 47,
+      "title": "Accessibility",
+      "content": "Accessibility is part of the design.\n\nAlways consider:\n\n* Keyboard navigation\n* Focus states\n* Screen readers\n* Color contrast\n* Semantic HTML\n* Clear labels\n* Button names\n* Input descriptions\n* Error messages\n* Touch target sizes\n\nNever communicate meaning using color alone."
+    },
+    {
+      "number": 48,
+      "title": "Interaction Design",
+      "content": "Every interactive element should provide feedback.\n\nExamples:\n\n```text\nDefault\n→ Hover\n→ Active\n→ Focus\n→ Disabled\n→ Loading\n→ Success/Error\n```\n\nDo not animate everything.\n\nUse subtle transitions for:\n\n* Hover\n* Opening/closing\n* State changes\n* Navigation\n* Feedback\n\nMotion should explain interaction, not distract."
+    },
+    {
+      "number": 49,
+      "title": "Final UI Quality Checklist",
+      "content": "Before considering the UI complete, verify:\n\n### Hierarchy\n\n* Is the primary purpose obvious within seconds?\n* Is the most important action visually dominant?\n\n### Layout\n\n* Is spacing intentional?\n* Are sections grouped logically?\n* Is the content width comfortable?\n\n### Components\n\n* Is every component necessary?\n* Is each component being used for its intended purpose?\n\n### Visual Design\n\n* Is the color palette restrained?\n* Are borders and shadows subtle?\n* Is typography consistent?\n\n### UX\n\n* Can users understand what to do?\n* Are loading, empty, error, and success states handled?\n\n### Responsive\n\n* Does it work on mobile?\n* Does navigation adapt correctly?\n* Do cards/forms/tables remain usable?\n\n### Human Design\n\n* Does it look intentionally designed?\n* Could removing a decorative element improve it?\n* Does anything feel like generic AI-generated SaaS UI?\n\nIf something feels unnecessary, remove it."
+    },
+    {
+      "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`"
+    }
+  ],
+  "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.**"
+  }
+}