@neuctra/ui-mcp 0.4.6 → 0.4.7

package/README.md

@@ -103,7 +103,7 @@ Supported page recipes include tool pages, blog pages, dashboards, landing pages
 }
 ```
 
-Use `pageType: "auto"` to infer the layout from the request. The assistant can also choose a specific page type, such as `tool-page`, `blog-page`, or `dashboard`. Use `framework: "auto"` to have the assistant identify the project framework, or provide a framework such as `nextjs-app`, `react-vite`, `react-router`, or `remix`.
+Use `pageType: "auto"` to infer the closest specific layout from the request, or choose any layout ID from the grouped catalog in `data/layouts.json`. The catalog covers marketing, SaaS applications, e-commerce, publishing, support, portfolios, communities, events, forms, and system pages. Use `framework: "auto"` to have the assistant identify the project framework, or provide a framework such as `nextjs-app`, `react-vite`, `react-router`, or `remix`.
 
 ### `get-neuctra-ui-component`
 

package/data/design-rules.json

@@ -0,0 +1,337 @@
+{
+  "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.",
+  "blocks": {
+    "core": [
+      {
+        "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": 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": 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": 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."
+      }
+    ],
+    "layout": [
+      {
+        "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": 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": 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.\n\nSee the Breakpoint Checklist (section 59) for the widths and checks every page must pass."
+      },
+      {
+        "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": 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)."
+      }
+    ],
+    "components": [
+      {
+        "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": 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 — 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,
+        "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": 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": 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": 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`"
+      }
+    ],
+    "accessibilityInteraction": [
+      {
+        "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."
+      }
+    ],
+    "modernDesign": [
+      {
+        "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."
+      }
+    ],
+    "antiAiDesignRules": [
+      {
+        "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."
+      }
+    ]
+  },
+  "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.**"
+  }
+}