@neuctra/ui-mcp 0.4.6 → 0.4.8

package/data/design-rules.json

@@ -0,0 +1,352 @@
+{
+  "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 to display code?\n→ react-syntax-highlighter (see Code Blocks rule)\n\nNeed to visualize stats or trends (dashboards)?\n→ ApexCharts via react-apexcharts (see Dashboard Charts rule)\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."
+      },
+      {
+        "number": 66,
+        "title": "Context-Driven Variety",
+        "content": "Do not reuse the same dashboard shell, stat cards and grid for every request. Two different products should not look like the same template with renamed labels.\n\nBefore building app UI, write a short design brief from the request:\n\n1. Domain: finance, health, devops, commerce, education, CRM...\n2. Primary user: operator, executive, end customer, developer.\n3. Density: compact, balanced or spacious.\n4. Frequency: glanced at daily, or worked in for hours.\n5. The one decision the page must support.\n\nThen pick one variant per group from that brief. The `neuctra-ui-page-builder` tool scores these against the request and returns full specs in `designVariants`.\n\nNavigation shell:\n\n* **Grouped full sidebar** (`grouped-sidebar`): Admin panels and back offices with many destinations (8+) that fall into clear groups.\n* **Icon rail** (`icon-rail`): Focused tools with few top-level areas (6 or fewer) where the canvas or data needs maximum width.\n* **Rail plus contextual panel** (`rail-plus-panel`): Multi-module products where each module has its own list: mail, chat, projects with sub-lists, file managers.\n* **Collapsible sidebar** (`collapsible-sidebar`): General SaaS products with a medium nav (5-10 items) where users sometimes want more room.\n* **Top navigation bar** (`top-navbar`): Products with 6 or fewer sections and wide content: analytics, reports, personal finance, store owners, consumer dashboards.\n* **Inset sidebar** (`inset-sidebar`): Modern, premium or AI products where the main area should feel like a raised workspace.\n* **Workspace switcher sidebar** (`workspace-sidebar`): Multi-tenant products: teams, organizations, agencies managing clients.\n* **Bottom tab bar** (`bottom-tab-bar`): Mobile-first apps and consumer products used mainly on phones.\n\nPage header:\n\n* **Title with actions** (`title-actions`): Pages with one clear primary action.\n* **Personal greeting** (`greeting`): Home dashboards for individual users who return daily.\n* **Title with filter toolbar** (`title-toolbar`): Analytics and reporting views driven by a date range and filters.\n* **Title with view tabs** (`title-tabs`): One entity viewed several ways (overview, activity, settings).\n* **Status banner header** (`status-banner`): Operational and monitoring screens where overall health is the first thing to know.\n\nStat card:\n\n* **Number with delta** (`number-delta`): Headline KPIs compared with the previous period.\n* **Number with sparkline** (`sparkline`): Metrics where the recent trend matters as much as the current value.\n* **Progress toward goal** (`progress-goal`): Values with a target or limit: quotas, budgets, storage, course completion.\n* **Icon tile** (`icon-tile`): Operational counts that users scan and click through: open tickets, pending orders, low stock.\n* **Hero metric** (`hero-metric`): Dashboards with one north-star number (revenue, balance, portfolio value) and a few supporting stats.\n* **Compact stat strip** (`compact-strip`): Dense operational screens: one Card split into columns by dividers instead of separate cards.\n* **Value with breakdown** (`breakdown`): Totals that are meaningful only with their composition: pipeline by stage, tickets by status, traffic by source.\n* **Radial score** (`radial-score`): Single percentage scores: health, satisfaction, completion, performance.\n\nDashboard body:\n\n* **KPI row, chart, table** (`kpi-chart-table`): General overview dashboards where users check numbers, then drill into records.\n* **Bento grid** (`bento`): Executive or product overviews mixing one hero metric with varied tiles.\n* **Main column with side rail** (`main-side-rail`): Work dashboards where people act on items: tasks, approvals, upcoming events, activity.\n* **Table first** (`table-first`): Operational screens where the job is working through records: orders, users, inventory, tickets.\n* **Single metric focus** (`single-focus`): Personal or monitoring dashboards built around one number over time.\n* **Pipeline overview** (`pipeline-board`): Stage-based work: sales deals, hiring, support queues, order fulfilment.\n* **Tabbed sections** (`tabbed-sections`): Analytics with several distinct areas (acquisition, engagement, revenue) that would make one page too long.\n* **Activity feed center** (`feed-center`): Community, social, audit and notification-heavy products where events are the content.\n\nRules:\n\n* Derive a short design brief from the request before choosing anything: domain (finance, health, devops, commerce, education...), primary user (operator, executive, end customer, developer), data density, how often the page is used, and the one decision the page should support.\n* Pick one variant per group deliberately from that brief. The recommended variant is a starting point, not a mandate: if an alternative fits the brief better, use it and say why in one sentence.\n* Inside one existing app, consistency wins: if the project already has an app shell, sidebar or stat card style, reuse it for new pages instead of introducing a new variant. Variety applies across different products and contexts, not between pages of the same product.\n* Content must come from the domain. A clinic dashboard shows appointments, no-shows and wait time; a SaaS dashboard shows MRR, churn and activation. Never ship generic 'Total Users / Revenue / Orders / Growth' placeholders unless the request is literally about those.\n* Do not combine more than two stat card variants on one page, and keep a single variant within one row.\n* Vary the active-state treatment, header style and grid to fit the variant. Do not fall back to the same left-border active item, four equal stat cards and chart-plus-table grid every time."
+      }
+    ],
+    "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\nThis is the content structure for a grouped sidebar, which is only one of several navigation shells. Choose the shell from context (see rule 66: Context-Driven Variety), for example an icon rail for focused tools, a rail plus panel for inbox or chat products, a top navbar for simple analytics, an inset sidebar for modern AI products, or a bottom tab bar for mobile-first apps.\n\nGrouped sidebar content 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\n\nPlaceholders, compulsory:\n\n* Every Input, Textarea, Select, Number Input, Date Picker, Time Picker and search field must have a `placeholder`.\n* The placeholder shows an example or format of the expected value: \"you@company.com\", \"Search projects...\", \"e.g. Q3 marketing plan\".\n* A placeholder is a hint, never a replacement for the Label. Keep the visible Label and add the placeholder.\n* Keep placeholders short and in sentence case. Do not repeat the label word for word (\"Email\" label → \"you@company.com\", not \"Email\")."
+      },
+      {
+        "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.\n\nModal overflow, compulsory:\n\n* A Modal must never grow taller than the viewport. Cap the modal body height (for example `max-h-[70vh]` or `max-h-[calc(100vh-8rem)]`) and give the body `overflow-y-auto`.\n* Only the body scrolls. Keep the header (title, close button) and footer (actions) fixed and always visible.\n* Never let content be clipped or push the action buttons off screen. If the content can exceed the available height (long forms, lists, terms, previews), apply the vertical scroll.\n* Do not add horizontal scroll to a Modal. Wrap or reflow wide content 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`"
+      },
+      {
+        "number": 64,
+        "title": "Code Blocks",
+        "content": "Whenever the UI shows a code block (snippets, install commands, API examples, config files, documentation), use the `react-syntax-highlighter` package (`\"react-syntax-highlighter\": \"^15.6.6\"`). Never hand-roll a code block with a plain `<pre>` and manual coloring, and never use another highlighting library.\n\nInstall:\n\n```bash\nnpm install react-syntax-highlighter@^15.6.6\n```\n\nUsage:\n\n```jsx\nimport { Prism as SyntaxHighlighter } from \"react-syntax-highlighter\";\nimport { oneDark } from \"react-syntax-highlighter/dist/esm/styles/prism\";\n\n<SyntaxHighlighter\n  language=\"tsx\"\n  style={oneDark}\n  showLineNumbers={false}\n  wrapLongLines={false}\n  customStyle={{ margin: 0, borderRadius: \"0.75rem\", fontSize: \"0.875rem\" }}\n>\n  {code}\n</SyntaxHighlighter>\n```\n\nRules:\n\n* Use the Prism build and always set the correct `language`.\n* The highlighter's syntax theme is the only allowed exception to the theme-tokens-only color rule. Everything around it (wrapper, header, copy button, filename) uses Neuctra UI tokens and components.\n* Give multi-line blocks a small header with the filename or language and a copy button.\n* Long lines scroll horizontally inside the block (`overflow-x-auto`); the block must never widen the page.\n* Inline code in a sentence stays a styled `<code>` element, not the highlighter."
+      },
+      {
+        "number": 65,
+        "title": "Dashboard Charts",
+        "content": "When you build a dashboard (analytics, admin, CRM, reports, any page that shows stats over time or comparisons), visualize the stats with ApexCharts using `apexcharts` + `react-apexcharts`. Do not use another chart library and do not fake charts with divs or static images.\n\nInstall:\n\n```bash\nnpm install apexcharts react-apexcharts\n```\n\nUsage (Next.js: load the chart client-side only):\n\n```jsx\n\"use client\";\nimport dynamic from \"next/dynamic\";\nconst Chart = dynamic(() => import(\"react-apexcharts\"), { ssr: false });\n\nconst css = (name) =>\n  getComputedStyle(document.documentElement).getPropertyValue(name).trim();\n\nconst options = {\n  chart: { toolbar: { show: false }, fontFamily: \"inherit\", background: \"transparent\" },\n  colors: [css(\"--primary\"), css(\"--info\"), css(\"--warning\")],\n  grid: { borderColor: css(\"--border\"), strokeDashArray: 4 },\n  xaxis: { categories, labels: { style: { colors: css(\"--muted-foreground\") } } },\n  yaxis: { labels: { style: { colors: css(\"--muted-foreground\") } } },\n  tooltip: { theme: isDark ? \"dark\" : \"light\" },\n  dataLabels: { enabled: false },\n  stroke: { curve: \"smooth\", width: 2 },\n};\n\n<Chart type=\"area\" height={300} options={options} series={series} />\n```\n\nRules:\n\n* Chart colors come from the theme CSS variables (read with getComputedStyle), never hardcoded hex values. Re-read them when the theme switches between light and dark.\n* Place each chart inside a Card with a CardHeader (title, short description, optional range selector) and the chart in CardBody.\n* Pick the chart by the question: line/area for trends over time, bar for comparing categories, donut/radial only for a few parts of a whole (max 5 slices), sparkline inside stat tiles.\n* Keep KPI stat tiles as numbers first; add a chart only where a trend or comparison helps.\n* Hide the toolbar, disable data labels on dense series, keep the grid subtle, and set an explicit height so the layout does not jump while loading.\n* Charts must be responsive: use `width=\"100%\"` and stack chart cards to a single column on small screens."
+      }
+    ],
+    "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.**"
+  }
+}