canvas-ui-sdk 0.3.23 → 4.0.0

package/mcp/dist/index.js

@@ -20839,416 +20839,860 @@ var StdioServerTransport = class {
 var layoutShells = {
   DashboardShell: {
     path: "@/components/layout",
-    description: "Main dashboard layout with dark sidebar (320px) and fixed header. Sidebar has collapsible sections with nav items.",
+    description: "Full-screen app layout with dark sidebar (320px) and fixed header. Sidebar has collapsible sections with nav items. Hides sidebar on mobile with a slide-out menu. Full viewport height. Use for data-heavy applications with many navigation sections like admin dashboards, CRM tools, or project management.",
+    keywords: ["admin", "dashboard", "sidebar", "navigation", "crm", "back-office", "management", "app"],
+    visualWeight: "light",
     props: ["navigation: NavSection[]", "pageHeader?", "children", "onNavItemClick?"]
   },
   IconSidebarShell: {
     path: "@/components/layout",
-    description: "Layout with narrow icon-only sidebar (96px). Good for apps with few main sections.",
+    description: "App layout with narrow icon-only sidebar (96px) and fixed header. Icons expand to tooltip labels on hover. Full viewport height. Use for apps with few main sections where you want maximum content space.",
+    keywords: ["sidebar", "icon", "compact", "navigation", "app"],
+    visualWeight: "light",
     props: ["navigation?: IconNavItemConfig[]", "pageHeader?", "children", "onNavItemClick?"]
   },
   DoubleSidebarShell: {
     path: "@/components/layout",
-    description: "Two-column sidebar layout (96px icons + 280px nav). Each column can be light/dark themed independently.",
+    description: "Two-column sidebar layout (96px icon strip + 280px nav panel). Each column can be light or dark themed independently. Full viewport height. Use for complex apps with category groupings and nested navigation.",
+    keywords: ["sidebar", "double", "icon", "navigation", "categories", "nested"],
+    visualWeight: "light",
     props: ["sections?: DoubleSidebarSection[]", "iconVariant?", "navVariant?", "children", "onTabClick?"]
   },
   StandardPageShell: {
     path: "@/components/layout",
-    description: "No-sidebar layout with centered content (max 992px). Has optional flair banner and page header with tabs.",
+    description: "No-sidebar layout with centered content (max 992px). Has optional flair banner at top and page header with tabs. Full viewport height. Use for content pages, marketing pages, search results, or any page that doesn't need persistent navigation.",
+    keywords: ["centered", "content", "standard", "page", "no-sidebar", "simple"],
+    visualWeight: "light",
     props: ["bannerTitle?", "pageTitle?", "tabs?", "activeTab?", "showBanner?", "showTabs?", "children"]
   },
   AccountSettingsShell: {
     path: "@/components/layout",
-    description: "Settings page layout with left sidebar navigation (Profile, Security, Payments, Notifications tabs).",
+    description: "Settings page layout with left sidebar tab navigation (Profile, Security, Payments, Notifications) and right content area. Sidebar stacks above content on mobile. Full viewport height. Use for user preferences, account management, or any settings interface.",
+    keywords: ["settings", "account", "preferences", "tabs", "profile", "security"],
+    visualWeight: "light",
     props: ["activeTab?: AccountTab", "onTabChange?", "pageTitle?", "children"]
   },
   MultistepShell: {
     path: "@/components/layout",
-    description: "Multi-step wizard layout with horizontal step tracker, step title/description, and navigation buttons.",
+    description: "Multi-step wizard layout with horizontal step tracker at top, step title/description, and navigation buttons. Content area centered (max 768px). Full viewport height. Use for registration flows, onboarding, or any sequential form process.",
+    keywords: ["wizard", "multistep", "steps", "form", "onboarding", "registration", "flow"],
+    visualWeight: "light",
     props: ["steps?: Step[]", "currentStep?", "onStepClick?", "onCancel?", "onContinue?", "children"]
   },
   MultistepSidebarShell: {
     path: "@/components/layout",
-    description: "Multi-step wizard with sidebar step list instead of horizontal tracker.",
+    description: "Multi-step wizard with step list in a left sidebar instead of horizontal tracker. Full viewport height. Use when steps need descriptions or the flow has many steps.",
+    keywords: ["wizard", "multistep", "sidebar", "steps", "form"],
+    visualWeight: "light",
     props: ["steps?: Step[]", "currentStep?", "children"]
   },
   MultistepProgressBarShell: {
     path: "@/components/layout",
-    description: "Multi-step wizard with a horizontal progress bar at top.",
+    description: "Multi-step wizard with a horizontal progress bar at top instead of numbered steps. Full viewport height. Simpler visual for flows where step count matters less than overall progress.",
+    keywords: ["wizard", "multistep", "progress", "bar", "form"],
+    visualWeight: "light",
     props: ["steps?: MultistepProgressBarStep[]", "currentStep?", "children"]
   },
   VerticalMultistepShell: {
     path: "@/components/layout",
-    description: "Multi-step wizard with vertical step tracker on the left side.",
+    description: "Multi-step wizard with vertical step tracker on the left side. Steps show as a vertical list with descriptions. Full viewport height. Use for compact multi-step forms.",
+    keywords: ["wizard", "multistep", "vertical", "steps", "form", "compact"],
+    visualWeight: "light",
     props: ["steps?: Step[]", "currentStep?", "children"]
   },
   MobileMenuShell: {
     path: "@/components/layout",
-    description: "Mobile-first layout with bottom navigation bar. Good for mobile app-like experiences.",
+    description: "Mobile-first layout with sticky bottom navigation bar (Home, Search, Profile tabs). Full viewport height. Use for mobile app-like experiences or responsive apps that need bottom tab navigation.",
+    keywords: ["mobile", "bottom", "tabs", "navigation", "app", "responsive"],
+    visualWeight: "light",
     props: ["children", "bottomNavItems?"]
   },
   SearchBarShell: {
     path: "@/components/layout",
-    description: "Layout with prominent search bar in header area.",
+    description: "Layout with prominent search bar in header area. Centered content below. Full viewport height. Use for search-focused pages like documentation, knowledge bases, or directory search.",
+    keywords: ["search", "documentation", "knowledge-base", "directory"],
+    visualWeight: "light",
     props: ["children", "onSearch?"]
   }
 };
 var layoutPrimitives = {
   Header: {
     path: "@/components/layout",
-    description: "Top navigation bar with logo, nav links, icon cluster (search, notifications, messages, cart), and avatar dropdown.",
+    description: "Responsive top navigation bar (~64px tall) with logo, nav links, icon cluster (search, notifications, messages, cart), and avatar dropdown. Collapses to hamburger menu on mobile. Light and dark variants.",
+    keywords: ["header", "navbar", "navigation", "top-bar", "logo", "menu"],
+    visualWeight: "light",
     props: ["onMenuClick?", "showDesktopLogo?", "variant?: 'light' | 'dark'", "navItems?", "showAuthButtons?"]
   },
   Sidebar: {
     path: "@/components/layout",
-    description: "Dark or light sidebar with logo and collapsible nav sections. Used inside DashboardShell.",
+    description: "Dark or light sidebar (320px, full height) with logo and collapsible nav sections. Used inside DashboardShell. Each section has a title and list of nav items with icons.",
+    keywords: ["sidebar", "navigation", "menu", "collapsible"],
+    visualWeight: "light",
     props: ["sections: NavSection[]", "variant?: 'dark' | 'light'", "onItemClick?"]
   },
   SidebarNav: {
     path: "@/components/layout",
-    description: "Navigation items component used inside Sidebar. Handles section titles and item rendering.",
+    description: "Navigation items component used inside Sidebar. Handles section titles and item rendering with active states. Compact, fits within sidebar width.",
+    keywords: ["navigation", "sidebar", "menu-items"],
+    visualWeight: "light",
     props: ["sections: NavSection[]", "variant?", "onItemClick?"]
   },
   IconSidebar: {
     path: "@/components/layout",
-    description: "Narrow sidebar with only icons and tooltips. Used inside IconSidebarShell.",
+    description: "Narrow sidebar (96px, full height) with only icons and tooltips. Used inside IconSidebarShell. Shows icon buttons with hover tooltips for labels.",
+    keywords: ["sidebar", "icon", "compact", "narrow", "navigation"],
+    visualWeight: "light",
     props: ["items?: IconNavItemConfig[]", "variant?", "onItemClick?"]
   },
   DoubleSidebar: {
     path: "@/components/layout",
-    description: "Two-column sidebar with icon strip and nav panel. Used inside DoubleSidebarShell.",
+    description: "Two-column sidebar with icon strip (96px) and nav panel (280px, full height). Used inside DoubleSidebarShell. Icons select categories, nav panel shows items for selected category.",
+    keywords: ["sidebar", "double", "icon", "categories", "navigation"],
+    visualWeight: "light",
     props: ["sections?", "iconVariant?", "navVariant?", "onTabClick?"]
   }
 };
 var blocks = {
   ActivityFeed: {
     path: "@/components/blocks",
-    description: "Timeline-style activity feed showing user actions, comments, and file attachments with connecting lines. Supports status changes, comments with reactions, and file attachments.",
+    description: "Timeline-style activity feed with vertical connecting lines between entries. Each entry shows user avatar, action description, timestamp, and optional attachments or reactions. Full-width block (~400-800px depending on items). Use for audit logs, project activity, notification history, or any chronological event stream.",
+    keywords: ["timeline", "audit", "log", "history", "events", "chronological", "feed", "activity"],
+    visualWeight: "heavy",
     props: ["title?", "subtitle?", "items?: ActivityItem[]", "onLike?", "onReply?", "onAttachmentClick?"]
   },
   CircularProgressBarList: {
     path: "@/components/blocks",
-    description: "List block with circular progress indicators showing completion percentages. Features header with sort/filter controls and item action menus.",
+    description: "Vertical list of items, each with a circular progress indicator (percentage ring), title, description, and action menu. Header with sort/filter controls. Full-width block (~400-600px). Use for skill assessments, goal tracking, course completion, or any list where items have progress.",
+    keywords: ["progress", "skills", "goals", "tracking", "completion", "circular", "ring"],
+    visualWeight: "heavy",
     props: ["title?", "items?: ProgressListItem[]", "sortOptions?", "filterOptions?", "onSort?", "onFilter?", "onItemAction?"]
   },
   CircularProgressBar: {
     path: "@/components/blocks",
-    description: "SVG-based circular progress indicator showing a percentage value. Can be used standalone or within CircularProgressBarList.",
+    description: "SVG-based circular progress ring showing a percentage value in the center. Configurable size and stroke width. Compact inline element (~60-120px). Use standalone or within CircularProgressBarList.",
+    keywords: ["progress", "ring", "percentage", "circular", "gauge"],
+    visualWeight: "light",
     props: ["progress: number", "size?", "strokeWidth?", "className?"]
   },
   FaqsTable: {
     path: "@/components/blocks",
-    description: "Expandable FAQ list with accordion behavior. Shows questions with plus/minus toggle icons, revealing answers one at a time.",
+    description: "Expandable FAQ list with accordion behavior. Shows question text with plus/minus toggle icons, revealing answer text one at a time. Full-width block (~300-600px depending on items). Use for FAQ sections, help centers, or any question-and-answer content.",
+    keywords: ["faq", "questions", "answers", "accordion", "help", "expandable"],
+    visualWeight: "medium",
     props: ["title?", "items?: FAQItem[]", "defaultExpandedId?", "className?"]
   },
   StandardDataTable: {
     path: "@/components/blocks",
-    description: "Data table with title, result count, sort/filter dropdowns, and action button. Rows have avatar + name/email/title/role columns.",
+    description: "Tabular data display with sortable columns, avatar-enhanced rows, and row action menus. Header includes result count, sort/filter dropdowns, and primary action button. Full-width block (~400-800px depending on rows). Dense, text-heavy. Use for user directories, order lists, inventory tables, or any structured row-based data.",
+    keywords: ["table", "data", "rows", "sortable", "directory", "list", "inventory", "orders", "users"],
+    visualWeight: "heavy",
     props: ["title?", "data?: TableRow[]", "columns?", "sortOptions?", "filterOptions?", "actionButtonText?", "onAddNew?"]
   },
   FixedColumnDataTable: {
     path: "@/components/blocks",
-    description: "Data table with fixed first column (Name with avatar) that stays visible during horizontal scroll. Ideal for invoice-style tables with columns: Amount, Status badge, Logo, Company, Date Sent.",
+    description: "Data table with fixed first column (name with avatar) that stays visible during horizontal scroll. Remaining columns scroll horizontally. Full-width block (~400-800px). Dense, text-heavy. Use for wide data sets like invoices, financial reports, or comparison tables where the row identifier must stay visible.",
+    keywords: ["table", "fixed-column", "scroll", "wide", "invoices", "financial", "comparison"],
+    visualWeight: "heavy",
     props: ["title?", "data?: FixedColumnTableRow[]", "sortOptions?", "filterOptions?", "actionButtonText?", "onAddNew?", "onRowAction?"]
   },
   NestedDataTable: {
     path: "@/components/blocks",
-    description: "Expandable data table with parent rows that reveal nested child tables. Shows hierarchical data like locations with employees.",
+    description: "Expandable data table with parent rows that reveal nested child tables on click. Shows hierarchical data with expand/collapse toggles. Full-width block (~400-800px). Dense, text-heavy. Use for organizational hierarchies, location-based data, or any parent-child data relationships.",
+    keywords: ["table", "nested", "hierarchy", "expandable", "parent-child", "tree"],
+    visualWeight: "heavy",
     props: ["title?", "data?: ParentRow[]", "sortOptions?", "filterOptions?", "actionButtonText?", "onAddNew?", "onRowAction?", "onChildAction?"]
   },
   ReviewsTable: {
     path: "@/components/blocks",
-    description: "Review listing with user avatars, star ratings, dates, and expandable text. Includes sort/filter dropdowns and action button.",
+    description: "Vertical list of review entries with user avatar, star rating (1-5), date, and expandable review text. Header with sort/filter controls and action button. Full-width block (~400-600px). Use for product reviews, testimonials, feedback lists, or any user-submitted ratings.",
+    keywords: ["reviews", "ratings", "stars", "testimonials", "feedback", "comments"],
+    visualWeight: "heavy",
     props: ["title?", "reviews?: ReviewItem[]", "sortOptions?", "filterOptions?", "actionButtonText?", "onAddNew?", "onReadMore?"]
   },
   MessengerSidebar: {
     path: "@/components/blocks",
-    description: "Thread list sidebar for messaging with search, avatars, timestamps, and unread badges.",
+    description: "Vertical thread list sidebar for messaging apps. Each thread shows avatar, name, last message preview, timestamp, and unread badge. Includes search bar at top. Use for chat apps, support inboxes, or any thread-based messaging interface.",
+    keywords: ["chat", "messaging", "threads", "inbox", "conversations", "support"],
+    visualWeight: "medium",
     props: ["selectedThreadId?", "onSelectThread?", "className?"]
   },
   ChatBubble: {
     path: "@/components/blocks",
-    description: "Single chat message bubble. Sent messages align right with primary color, received align left with avatar.",
+    description: "Single chat message bubble. Sent messages align right with primary color background, received messages align left with avatar and neutral background. Shows timestamp below.",
+    keywords: ["chat", "message", "bubble", "conversation"],
+    visualWeight: "light",
     props: ["message: ChatBubbleMessage"]
   },
   ChatDateSeparator: {
     path: "@/components/blocks",
-    description: "Date separator line between chat messages (e.g., 'Jan 25, 2024').",
+    description: "Horizontal date separator line between chat messages (e.g., 'Jan 25, 2024'). Centered text with lines extending to each side.",
+    keywords: ["chat", "date", "separator", "divider"],
+    visualWeight: "light",
     props: ["date: string"]
   },
   MessengerInput: {
     path: "@/components/blocks",
-    description: "Chat input with textarea, attachment pills, file upload button, and send button.",
+    description: "Chat input bar with expandable textarea, attachment pills, file upload button, and send button. Use at the bottom of any chat or messaging interface.",
+    keywords: ["chat", "input", "message", "compose", "send"],
+    visualWeight: "light",
     props: ["attachments?", "onRemoveAttachment?", "onSend?"]
   },
   ProfileCard: {
     path: "@/components/blocks",
-    description: "Centered profile card with avatar overlapping banner, stats, bio, tags, and social links.",
+    description: "Centered profile card with large avatar overlapping a banner image, user stats row (posts, followers, following), bio text, skill/interest tags, and social media links. Includes a built-in stats row \u2014 if building a profile page, consider using this rather than assembling stats manually. Use for user profiles, author pages, or member directories.",
+    keywords: ["profile", "avatar", "stats", "bio", "social", "user", "member"],
+    visualWeight: "medium",
     props: ["name", "username", "avatarUrl?", "rating?", "location?", "stats?", "bio?", "tags?", "socialLinks?"]
   },
   StepTracker: {
     path: "@/components/blocks",
-    description: "Horizontal multi-step progress indicator with numbered circles and connecting lines.",
+    description: "Horizontal multi-step progress indicator with numbered circles connected by lines. Completed steps show checkmarks, current step is highlighted. Use in multi-step forms, wizards, or onboarding flows.",
+    keywords: ["steps", "wizard", "progress", "tracker", "multistep"],
+    visualWeight: "light",
     props: ["steps: Step[]", "currentStep: number", "onStepClick?"]
   },
   VerticalStepTracker: {
     path: "@/components/blocks",
-    description: "Vertical step tracker for sidebar placement in multi-step flows.",
+    description: "Vertical step tracker for sidebar placement in multi-step flows. Steps shown as a vertical list with numbers, titles, and optional descriptions. Use when horizontal space is limited.",
+    keywords: ["steps", "wizard", "progress", "tracker", "vertical"],
+    visualWeight: "light",
     props: ["steps: Step[]", "currentStep: number", "onStepClick?"]
   },
   ProgressBar: {
     path: "@/components/blocks",
-    description: "Horizontal progress bar. Can use percentage or currentStep/totalSteps.",
+    description: "Horizontal progress bar with filled portion showing completion. Can use percentage or currentStep/totalSteps. Use for upload progress, form completion, or any linear progress indicator.",
+    keywords: ["progress", "loading", "completion", "bar"],
+    visualWeight: "light",
     props: ["progress?", "currentStep?", "totalSteps?"]
   },
   FlairBanner: {
     path: "@/components/blocks",
-    description: "Dark blue hero banner with large title text. Used at top of pages.",
+    description: "Full-width dark blue hero banner with large title text. Use at the top of content pages for visual emphasis. Pairs well with PageHeaderSection below it.",
+    keywords: ["banner", "hero", "header", "decorative", "flair"],
+    visualWeight: "spacer",
     props: ["title: string"]
   },
   Loader: {
     path: "@/components/blocks",
-    description: "Loading feedback component with animated spinner (loading state) and checkmark (success state). Includes title, description, and optional action button.",
+    description: "Loading feedback component with animated spinner (loading state) and checkmark (success state). Shows title, description, and optional action button. Use for form submissions, file uploads, or any async operation feedback.",
+    keywords: ["loading", "spinner", "feedback", "async", "success"],
+    visualWeight: "light",
     props: ["state?: 'loading' | 'success'", "title?", "description?", "buttonText?", "onButtonClick?", "className?"]
   },
   GradientBanner: {
     path: "@/components/blocks",
-    description: "Banner with gradient background. Alternative to FlairBanner.",
+    description: "Full-width banner with gradient background and optional title/subtitle text. Use as a decorative page header or profile banner area.",
+    keywords: ["banner", "gradient", "header", "decorative", "profile"],
+    visualWeight: "spacer",
     props: ["title?", "subtitle?"]
   },
   PageHeaderSection: {
     path: "@/components/blocks",
-    description: "Page title, description, and optional line tabs. Used below banners.",
+    description: "Page title, description text, and optional horizontal line tabs below. Use below banners or at the top of content areas for page-level navigation and context.",
+    keywords: ["header", "title", "tabs", "page-title", "navigation"],
+    visualWeight: "light",
     props: ["title", "description?", "tabs?", "activeTab?", "onTabChange?", "showTabs?"]
   },
   SearchBar: {
     path: "@/components/blocks",
-    description: "Prominent search input with icon.",
+    description: "Prominent search input with search icon. Use for search-focused interfaces like documentation, directories, or knowledge bases.",
+    keywords: ["search", "input", "find", "query"],
+    visualWeight: "light",
     props: ["placeholder?", "value?", "onChange?", "onSearch?"]
   },
   SearchSidebar: {
     path: "@/components/blocks",
-    description: "Sidebar with search results or filters.",
+    description: "Sidebar panel with search results list or filter controls. Use alongside main content for search-driven interfaces.",
+    keywords: ["search", "sidebar", "results", "filter"],
+    visualWeight: "medium",
     props: ["results?", "onResultClick?"]
   },
   FilterPopover: {
     path: "@/components/blocks",
-    description: "Popover with filter controls (checkboxes, date ranges, etc.).",
+    description: "Popover dropdown with filter controls (checkboxes, date ranges, sliders). Triggered by a filter button. Use for refining lists, tables, or search results.",
+    keywords: ["filter", "popover", "dropdown", "refine"],
+    visualWeight: "light",
     props: ["filters?", "onApply?", "onReset?"]
   },
   MenuSection: {
     path: "@/components/blocks",
-    description: "Section within sidebar navigation with title and items.",
+    description: "Collapsible navigation section with section title and list of menu items. Multiple sections stack vertically. Use for categorized navigation, settings menus, or documentation sidebars.",
+    keywords: ["menu", "navigation", "collapsible", "sections", "sidebar"],
+    visualWeight: "medium",
     props: ["title?", "items: NavItem[]"]
   },
   MenufocusTemplate: {
     path: "@/components/blocks",
-    description: "Dropdown menu with trigger button (three dots). Used for row actions in tables.",
+    description: "Three-dot dropdown menu for row-level actions. Opens a list of action items on click. Use for table row actions, card actions, or any contextual menu.",
+    keywords: ["menu", "dropdown", "actions", "context-menu", "three-dot"],
+    visualWeight: "light",
     props: ["items: MenuItem[]", "ariaLabel?"]
   },
   SidebarCards: {
     path: "@/components/blocks",
-    description: "Card list for sidebar showing items with images/titles.",
+    description: "Vertical list of card items for sidebar placement, each with thumbnail image and title. Use for related content, recommended items, or sidebar navigation with visual previews.",
+    keywords: ["sidebar", "cards", "thumbnails", "related", "recommended"],
+    visualWeight: "medium",
     props: ["cards: SidebarCard[]", "onCardClick?"]
   },
   SidebarProfileCard: {
     path: "@/components/blocks",
-    description: "Compact profile card for sidebar with avatar and key info.",
+    description: "Compact profile card for sidebar placement with avatar, name, and role/title. Use in sidebars to show user info, author details, or contact information.",
+    keywords: ["sidebar", "profile", "avatar", "compact", "user"],
+    visualWeight: "light",
     props: ["name", "role?", "avatarUrl?"]
   },
+  StatsCard: {
+    path: "@/components/blocks/profile-info-cards",
+    description: "Horizontal row of 2-3 stat items centered in a bordered card. Each stat shows a bold value and muted label. Prefer this over hand-rolling stat numbers with raw Typography or inline styles \u2014 it handles alignment, consistent sizing, and responsive layout automatically. Use for profile stats (followers, posts, rating), sidebar stats, or any compact numeric summary.",
+    keywords: ["stats", "metrics", "numbers", "statistics", "profile"],
+    visualWeight: "light",
+    props: ["stats: { value: string, label: string }[]", "className?"]
+  },
   ProfileInfoCards: {
     path: "@/components/blocks",
-    description: "Grid of info cards for profile pages (contact, stats, etc.).",
+    description: "Grid of small info cards for profile or detail pages. Each card has a label, value, and optional icon. Use for contact details, stats, metadata, or any key-value information display.",
+    keywords: ["profile", "info", "metadata", "details", "cards", "key-value"],
+    visualWeight: "light",
     props: ["cards: InfoCard[]"]
   },
   ProfileImageUploader: {
     path: "@/components/blocks",
-    description: "Avatar upload component with preview and edit button.",
+    description: "Circular avatar upload component with current image preview and edit/upload button overlay. Use for profile photo editing, team member photos, or any avatar upload interface.",
+    keywords: ["avatar", "upload", "image", "profile", "photo"],
+    visualWeight: "light",
     props: ["currentImage?", "onUpload?"]
   },
   StoreLocationMap: {
     path: "@/components/blocks",
-    description: "Single store location card with address info, directions button, and embedded Google Maps iframe. Uses TitleGroup for header.",
+    description: "Location card with address text, directions button, and embedded map iframe. Uses TitleGroup for header. Use for store locators, office locations, or any place-based information display.",
+    keywords: ["map", "location", "address", "directions", "store"],
+    visualWeight: "medium",
     props: ["title?", "subtitle?", "storeLabel?", "storeName?", "addressLines?", "buttonText?", "onDirectionsClick?", "mapEmbedUrl?", "className?"]
   },
   SettingsListRow: {
     path: "@/components/blocks",
-    description: "Row item for settings lists with label, value, and edit action.",
+    description: "Single row item for settings pages with label on left, current value in center, and edit button on right. Use for user profile fields, account settings, or any editable key-value setting.",
+    keywords: ["settings", "row", "editable", "preference", "key-value"],
+    visualWeight: "light",
     props: ["label", "value?", "onEdit?"]
   },
   CreditCardDisplay: {
     path: "@/components/blocks",
-    description: "Visual credit card display showing card details.",
+    description: "Visual credit/debit card display showing card number (masked), cardholder name, expiry date, and card type logo. Use for payment method displays, saved cards, or financial account interfaces.",
+    keywords: ["credit-card", "payment", "card", "financial", "billing"],
+    visualWeight: "light",
     props: ["cardNumber?", "cardHolder?", "expiry?", "type?"]
   },
   PillTabs: {
     path: "@/components/blocks",
-    description: "Horizontal pill-style tab navigation.",
+    description: "Horizontal row of pill-shaped tab buttons with active state highlighting. Use for content filtering, view switching, or any tab navigation that needs a rounded pill style.",
+    keywords: ["tabs", "pills", "filter", "toggle", "navigation"],
+    visualWeight: "light",
     props: ["tabs: Tab[]", "activeTab?", "onTabChange?"]
   },
   LoginBrandingPanel: {
     path: "@/components/blocks",
-    description: "Branding side panel for login/signup pages with logo and background.",
+    description: "Side panel with background image and centered logo for authentication pages. Takes up one half of a split-screen layout. Use alongside login, signup, or password reset forms.",
+    keywords: ["login", "branding", "auth", "split-screen", "signup"],
+    visualWeight: "spacer",
     props: ["backgroundImage?", "logo?"]
   },
   ContentDropzone: {
     path: "@/components/blocks",
     description: "Placeholder dropzone for content areas. Shows dashed placeholder when empty; arranges children in a flex column with 32px (--spacing-4xl) gap between blocks. Within a block, use 12px (--spacing-lg) gap between title groups and their content.",
+    keywords: ["content", "dropzone", "container", "layout", "spacing"],
+    visualWeight: "light",
     props: ["height?", "className?", "children?"]
   },
   UpvotingPostsTable: {
     path: "@/components/blocks",
-    description: "Social feed with upvoting posts, comments, and nested replies. Features header with sort/filter controls.",
+    description: "Social feed with upvotable posts, comment threads, and nested replies. Each post has an upvote button with count, title, description, and author info. Use for feature request boards, community forums, Q&A sites, or feedback portals.",
+    keywords: ["forum", "upvote", "posts", "community", "feedback", "feature-requests"],
+    visualWeight: "heavy",
     props: ["title?", "subtitle?", "posts?: Post[]", "currentUser?", "sortOptions?", "filterOptions?", "actionButtonText?", "onUpvote?", "onComment?", "onReply?", "onLike?"]
   },
   NestedCommentsTable: {
     path: "@/components/blocks",
-    description: "Threaded discussion component with nested comments, reply/like actions, and collapsible threads.",
+    description: "Threaded discussion with nested comments, reply and like actions, and collapsible sub-threads. Each comment shows avatar, name, timestamp, and content. Use for blog comments, discussion boards, or any nested conversation interface.",
+    keywords: ["comments", "discussion", "threaded", "replies", "forum"],
+    visualWeight: "heavy",
     props: ["title?", "subtitle?", "comments?: Comment[]", "currentUser?", "onComment?", "onReply?", "onLike?"]
   },
   ImageFeedWithNestedComments: {
     path: "@/components/blocks",
-    description: "Instagram-style image feed with large images, social interactions (like/comment/share/bookmark), and nested comment threads.",
+    description: "Full-width image feed with large photos, social interaction buttons (like, comment, share, bookmark), and nested comment threads below each image. Use for photo galleries, social feeds, portfolio showcases, or media-rich community content.",
+    keywords: ["feed", "images", "social", "photos", "gallery", "comments"],
+    visualWeight: "heavy",
     props: ["title?", "subtitle?", "posts?: ImagePost[]", "currentUser?", "onLike?", "onComment?", "onShare?", "onBookmark?", "onReply?", "onCommentLike?"]
   },
   MobileBottomNav: {
     path: "@/components/blocks",
-    description: "Fixed bottom navigation bar for mobile layouts.",
+    description: "Fixed bottom navigation bar with icon tabs (Home, Search, Profile, etc.). Sticks to bottom of viewport. Use for mobile app-like experiences or responsive layouts needing bottom tab navigation.",
+    keywords: ["mobile", "bottom", "navigation", "tabs", "app"],
+    visualWeight: "light",
     props: ["items: BottomNavItem[]", "activeItem?", "onItemClick?"]
   },
   MonthlyCalendarWidget: {
     path: "@/components/blocks",
-    description: "Dual-month calendar for date range selection with price labels, disabled dates, and today indicator. Used for booking and scheduling interfaces.",
+    description: "Dual-month calendar for selecting date ranges. Shows two months side by side with price labels on dates, disabled dates, and today indicator. Use for booking flows, scheduling interfaces, or any date range selection.",
+    keywords: ["calendar", "booking", "dates", "scheduling", "date-range"],
+    visualWeight: "medium",
     props: ["title?", "subtitle?", "initialMonth?", "selectedRange?", "disabledDates?", "pricedDates?", "todayDate?", "onDateSelect?", "onRangeChange?", "onConfirm?", "onCancel?"]
   },
   BottomInputChatWidget: {
     path: "@/components/blocks",
-    description: "Slack-style chat widget with message threads list and conversation view. Features bottom input bar with attachment support.",
+    description: "Chat widget with two views: threads list (showing conversation previews) and conversation view (showing message bubbles). Bottom input bar with attachment support. Use for in-app messaging, support chat, or team communication.",
+    keywords: ["chat", "widget", "messaging", "threads", "support"],
+    visualWeight: "heavy",
     props: ["variant?: 'threads' | 'conversation'", "title?", "threads?", "messages?", "conversationName?", "onThreadClick?", "onBackClick?", "onSend?"]
   },
   LargeImageLabelsList: {
     path: "@/components/blocks",
-    description: "Property-style listing with large images, ratings, prices, and icon labels. Includes header with sort/filter controls.",
+    description: "Vertical list of items with large landscape images, star ratings, price, and descriptive icon labels (beds, baths, area, etc.). Header with sort/filter controls and favorite button. Use for property listings, product catalogs, hotel results, or any image-prominent list.",
+    keywords: ["listings", "property", "images", "catalog", "real-estate", "hotels"],
+    visualWeight: "heavy",
     props: ["title?", "items?: ListItem[]", "sortOptions?", "filterOptions?", "onFavorite?", "onItemClick?"]
   },
   SocialFeed: {
     path: "@/components/blocks",
-    description: "Social media-style feed with post composer, various content types (text, images, video, reposts, link cards), social interactions (like/comment/repost/share), and threaded replies.",
+    description: "Social media feed with post composer at top, and posts showing various content types (text, images, video, reposts, link cards). Each post has social interactions (like, comment, repost, share) and threaded replies. Use for community feeds, social networks, or activity streams.",
+    keywords: ["social", "feed", "posts", "community", "timeline", "network"],
+    visualWeight: "heavy",
     props: ["title?", "posts?: SocialFeedPost[]", "currentUser?", "composerPlaceholder?", "composerImagePreview?", "onPost?", "onLike?", "onComment?", "onRepost?", "onShare?"]
   },
   StandardListWithImage: {
     path: "@/components/blocks",
-    description: "Blog/article-style list block with image thumbnails, title, author, date, description, and tags. Includes header with sort/filter controls.",
+    description: "Vertical list of content items with square image thumbnails, title, author, date, description text, and tags. Header with sort/filter controls. Use for blog posts, articles, courses, events, or any content listing with images.",
+    keywords: ["list", "articles", "blog", "content", "thumbnails", "courses"],
+    visualWeight: "heavy",
     props: ["title?", "subtitle?", "items?: ListItem[]", "sortOptions?", "filterOptions?", "onSort?", "onFilter?", "onItemClick?"]
   },
   SlideshowGridTiles: {
     path: "@/components/blocks",
-    description: "2-column grid of portfolio/slideshow tiles with hover states. Features large images with slideshow navigation, save button, user info with avatar, and engagement stats (likes/views).",
+    description: "2-column grid of portfolio tiles with image slideshow navigation (prev/next arrows), save button, user avatar with name/location, and engagement stats (likes, views). Use for design portfolios, photo galleries, creative showcases, or any visual content grid.",
+    keywords: ["portfolio", "slideshow", "grid", "gallery", "creative"],
+    visualWeight: "heavy",
     props: ["title?", "subtitle?", "items?: SlideshowTileItem[]", "sortOptions?", "filterOptions?", "actionButtonText?", "onAddNew?", "onSort?", "onFilter?", "onSave?", "onItemClick?"]
   },
   ProfileGridTilesList: {
     path: "@/components/blocks",
-    description: "Responsive grid of profile cards with avatar, ratings, certifications, and metadata. Configurable 2-5 columns with mobile responsiveness. Ideal for tutors, team members, or user directories.",
+    description: "Responsive grid of profile cards with avatar, star rating, certification badges, and metadata (location, price, specialization). Configurable 2-5 columns. Use for team directories, service provider listings, tutor marketplaces, or any people-focused catalog.",
+    keywords: ["people", "directory", "profiles", "team", "grid", "marketplace"],
+    visualWeight: "medium",
     props: ["title?", "subtitle?", "items?: ProfileTileItem[]", "columns?: 2|3|4|5", "sortOptions?", "filterOptions?", "actionButtonText?", "onAddNew?", "onSort?", "onFilter?", "onItemClick?"]
   },
   GridTilesList: {
     path: "@/components/blocks",
-    description: "Responsive grid of property/listing tiles with configurable 2-5 columns. Features images, star ratings, prices, favorite buttons, and optional tags. Includes header with sort/filter controls.",
+    description: "Configurable 2-5 column image card grid. Each tile has a square image, title, star rating, location text, price, and favorite button. Optional tag badges. Header with sort/filter controls and action button. Use for product catalogs, property listings, course directories, or any visual item grid.",
+    keywords: ["grid", "tiles", "products", "catalog", "cards", "listings"],
+    visualWeight: "medium",
     props: ["title?", "subtitle?", "columns?: 2|3|4|5", "items?: GridTileItem[]", "sortOptions?", "filterOptions?", "actionButtonText?", "onAddNew?", "onFavorite?", "onItemClick?"]
   },
   Pagination: {
     path: "@/components/blocks",
-    description: "Responsive pagination with results summary, items per page dropdown, and page navigation. Shows 'Viewing X-Y of Z results' on desktop, compact navigation on mobile.",
+    description: "Responsive pagination bar with 'Viewing X-Y of Z results' text, items-per-page dropdown, and page navigation buttons. Results text hides on mobile for compact layout. Use below any paginated list or table.",
+    keywords: ["pagination", "pages", "navigation", "results"],
+    visualWeight: "light",
     props: ["currentPage?", "totalPages?", "totalItems?", "itemsPerPage?", "itemsPerPageOptions?", "onPageChange?", "onItemsPerPageChange?", "showResultsText?", "showItemsPerPage?", "maxVisiblePages?"]
   },
   // Graph and Metric Tiles (Dashboard Widgets)
   MetricCard: {
     path: "@/components/blocks/graph-metric-tiles",
-    description: "Single KPI card displaying a large value with label and optional change indicator (up/down arrow with color).",
+    description: "Single KPI summary card showing a large numeric value, label text, and optional change indicator (up/down arrow with percentage). Use for revenue, users, orders, or any single numeric metric. Prefer this over hand-rolling stat numbers with inline styles \u2014 it handles typography scale, alignment, and card containment automatically.",
+    keywords: ["metric", "kpi", "stat", "number", "dashboard"],
+    visualWeight: "light",
     props: ["label: string", "value: string", "change?: { value: string, direction: 'up' | 'down' }", "className?"]
   },
   MetricCardsRow: {
     path: "@/components/blocks/graph-metric-tiles",
-    description: "Horizontal row of 2-4 MetricCard components with automatic flex layout and spacing.",
+    description: "Row of 2-4 KPI summary cards in a responsive grid. Stacks to 2 columns on tablet and 1 column on mobile. Prefer this for dashboard KPI rows \u2014 each card includes proper containment, change indicators, and responsive grid behavior. Use instead of hand-rolling metric displays.",
+    keywords: ["metrics", "kpi", "dashboard", "stats", "cards", "row"],
+    visualWeight: "light",
     props: ["metrics: MetricCardData[]", "columns?: 2|3|4", "className?"]
   },
   LineChartWidget: {
     path: "@/components/blocks/graph-metric-tiles",
-    description: "Full-width widget with Chart.js line/area chart. Includes header, value display, and footer actions. Chart colors update live with CSS variables.",
+    description: "Dashboard widget with Chart.js line/area chart, header with label and value, and footer with action links. Chart colors update live with CSS variables. Chart height reduces on mobile. Use for trend visualization, revenue charts, or any time-series data.",
+    keywords: ["chart", "line", "graph", "trend", "time-series", "dashboard"],
+    visualWeight: "medium",
     props: ["label: string", "value: string", "description?", "chartData?: number[]", "chartLabels?: string[]", "onMenuClick?", "onManageClick?", "onViewDetailsClick?"]
   },
   DonutChartWidget: {
     path: "@/components/blocks/graph-metric-tiles",
-    description: "Widget with Chart.js doughnut chart and legend metrics grid. Colors mapped to --chart-color-1 through --chart-color-5 CSS variables.",
+    description: "Dashboard widget with Chart.js doughnut chart and legend grid showing category breakdowns. Chart and legend stack vertically on mobile. Colors mapped to --chart-color-1 through --chart-color-5 CSS variables. Use for category distributions, budget breakdowns, or any proportional data.",
+    keywords: ["chart", "donut", "doughnut", "pie", "categories", "dashboard"],
+    visualWeight: "medium",
     props: ["label: string", "value: string", "description?", "legendItems?: DonutChartLegendItem[]", "onMenuClick?", "onManageClick?", "onViewDetailsClick?"]
   },
   MetricListCard: {
     path: "@/components/blocks/graph-metric-tiles",
-    description: "Card displaying a list of transactions or metrics with optional date, label, and value columns.",
+    description: "Dashboard widget showing a vertical list of line items with optional date, label, and value columns. Header with title and subtitle. Use for recent transactions, activity summaries, or any tabular metric list.",
+    keywords: ["metric", "list", "transactions", "activity", "dashboard"],
+    visualWeight: "medium",
     props: ["headerLabel: string", "title: string", "subtitle?", "items: MetricListItem[]", "viewDetailsLabel?", "onMenuClick?", "onManageClick?", "onViewDetailsClick?"]
   },
   ProgressMetricCard: {
     path: "@/components/blocks/graph-metric-tiles",
-    description: "Card with horizontal progress bars, optional images/sublabels, and value display. Uses --canvas-primary for bar color by default.",
+    description: "Dashboard widget with horizontal progress bars, optional thumbnail images, sublabels, and value display. Uses --canvas-primary for bar color. Use for goal tracking, category performance, or any ranked metric with progress.",
+    keywords: ["progress", "metric", "goals", "tracking", "dashboard"],
+    visualWeight: "medium",
     props: ["headerLabel: string", "title: string", "subtitle?", "items: ProgressBarItem[]", "onMenuClick?", "onManageClick?", "onViewDetailsClick?"]
   },
   TwoColumnWidgets: {
     path: "@/components/blocks/graph-metric-tiles",
-    description: "Simple flex layout wrapper for arranging two widget cards side by side with proper gap spacing.",
+    description: "Layout wrapper for arranging two dashboard widgets side by side with proper gap spacing. Stacks vertically on mobile. Use to pair any two widget cards in a dashboard layout.",
+    keywords: ["layout", "two-column", "widgets", "dashboard", "grid"],
+    visualWeight: "light",
     props: ["children: React.ReactNode", "className?"]
   },
   DashboardHeader: {
     path: "@/components/blocks/graph-metric-tiles",
-    description: "Page header for dashboards with title and optional subtitle.",
+    description: "Page header for dashboard pages with large title and optional subtitle text. Font size reduces on mobile via typography tokens.",
+    keywords: ["dashboard", "header", "title", "page-header"],
+    visualWeight: "light",
     props: ["title: string", "subtitle?", "className?"]
   },
   GraphMetricTilesDemo: {
     path: "@/components/blocks/graph-metric-tiles",
-    description: "Complete dashboard demo composing all metric tile components together. Use as reference for dashboard layouts.",
+    description: "Complete dashboard demo composing MetricCardsRow, LineChartWidget, DonutChartWidget, MetricListCard, and ProgressMetricCard together. Use as a reference for building dashboard layouts.",
+    keywords: ["dashboard", "demo", "reference", "widgets"],
+    visualWeight: "heavy",
     props: ["className?"]
+  },
+  // Utility / Structural Blocks
+  TitleGroup: {
+    path: "@/components/blocks",
+    description: "Header section with title, subtitle, optional sort dropdown, filter popover, and action button. Compact (~48px tall). Use as the header for any content block \u2014 pairs with data tables, lists, card grids, or any section that needs a scannable title landmark.",
+    keywords: ["title", "header", "section", "sort", "filter", "action"],
+    visualWeight: "light",
+    props: ["title", "subtitle?", "sortOptions?", "onSort?", "showFilter?", "filterPopoverProps?", "actionButtonText?", "onAction?", "className?"]
+  },
+  EmptyState: {
+    path: "@/components/blocks",
+    description: "Centered empty state display with emoji/icon, title, and optional description inside a dashed border card. Compact (~200px tall). Use when a list, table, or content area has no data to show.",
+    keywords: ["empty", "placeholder", "no-data", "no-results", "blank"],
+    visualWeight: "light",
+    props: ["icon?", "title?", "description?", "className?"]
+  },
+  TileImageGallery: {
+    path: "@/components/blocks",
+    description: "Hero image gallery with one large image on the left and a 2x2 grid of thumbnails on the right, plus a 'View all' button overlay. Full-width block (~400px tall). Use at the top of product detail pages, listing pages, or property pages for immersive visual browsing.",
+    keywords: ["gallery", "images", "photos", "tiles", "product", "listing"],
+    visualWeight: "spacer",
+    props: ["images?", "onViewAll?", "viewAllLabel?", "height?", "className?"]
+  },
+  ReservationCard: {
+    path: "@/components/blocks",
+    description: "Sidebar card for booking/reservation with price display, 'From' and 'To' date inputs, and primary CTA button. Bordered card (~250px tall). Use in a sidebar alongside product/listing detail content for booking flows, appointment scheduling, or any date-based reservation.",
+    keywords: ["reservation", "booking", "dates", "price", "sidebar", "card"],
+    visualWeight: "medium",
+    props: ["price?", "priceUnit?", "fromDate?", "onFromDateChange?", "toDate?", "onToDateChange?", "ctaLabel?", "onCtaClick?", "className?"]
+  },
+  OrderSummarySidebar: {
+    path: "@/components/blocks",
+    description: "Shopping cart sidebar showing line items with quantities, promo code input, tax/shipping info, and order total with separators. Bordered card (~350px tall). Use in a sidebar alongside checkout steps for e-commerce order summaries.",
+    keywords: ["order", "cart", "summary", "checkout", "total", "sidebar"],
+    visualWeight: "medium",
+    props: ["title?", "lineItems?", "promoCodePlaceholder?", "onApplyPromo?", "applyLabel?", "taxes?", "shippingLabel?", "total?", "currency?", "className?"]
+  },
+  BottomActionBar: {
+    path: "@/components/blocks",
+    description: "Sticky bottom bar displaying price with unit and primary CTA button. Fixed to bottom of viewport (~64px tall). Use on mobile-friendly detail pages for persistent booking/purchase actions.",
+    keywords: ["bottom", "action", "bar", "sticky", "cta", "mobile", "price"],
+    visualWeight: "light",
+    props: ["price?", "priceUnit?", "ctaLabel?", "onCtaClick?", "className?"]
+  },
+  EditableList: {
+    path: "@/components/blocks",
+    description: "Editable list where users can add items via input field and remove them with trash icon buttons. Compact inline element. Use for tag lists, skill lists, or any dynamic list where users add/remove items.",
+    keywords: ["list", "editable", "add", "remove", "tags", "dynamic"],
+    visualWeight: "light",
+    props: ["label?", "items?", "onItemsChange?", "addPlaceholder?", "disabled?", "className?"]
+  },
+  PersonaCard: {
+    path: "@/components/blocks",
+    description: "Card displaying persona information with avatar, name, role, goals, pain points, and quote with icons. Medium bordered card (~300px tall). Use for UX persona displays, user research artifacts, or team role descriptions.",
+    keywords: ["persona", "user", "profile", "goals", "research", "ux"],
+    visualWeight: "medium",
+    props: ["persona?", "className?"]
+  },
+  PlaceDetailPanel: {
+    path: "@/components/blocks",
+    description: "Right-side drawer panel for place/business details with hero image, tabs, description, info rows, operating hours, amenities, admission pricing, and reviews. Heavy, content-rich overlay (~full height). Use for map-based detail views, place cards, or business information panels.",
+    keywords: ["place", "detail", "drawer", "business", "map", "reviews", "amenities"],
+    visualWeight: "heavy",
+    props: ["open?", "onOpenChange?", "title?", "subtitle?", "rating?", "heroImageUrl?", "tabs?", "activeTab?", "description?", "infoRows?", "operatingHours?", "amenities?", "reviews?", "className?"]
+  },
+  SelectablePills: {
+    path: "@/components/blocks",
+    description: "Grid of toggleable pill/chip buttons for multi-select. Each pill shows a label and toggles selected state on click. Compact inline element. Use for interest selection, tag filtering, or any multi-choice selection interface.",
+    keywords: ["pills", "chips", "tags", "select", "toggle", "filter", "interests"],
+    visualWeight: "light",
+    props: ["options?", "selected?", "onToggle?", "className?"]
+  },
+  FileUploader: {
+    path: "@/components/blocks",
+    description: "Drag-and-drop file upload area with browse button. Shows upload progress and file previews. Use for document uploads, image uploads, or any file attachment interface.",
+    keywords: ["upload", "file", "drag-drop", "attachment", "document"],
+    visualWeight: "light",
+    props: ["accept?", "maxSize?", "onUpload?", "className?"]
+  },
+  ImageUploader: {
+    path: "@/components/blocks",
+    description: "Image upload component with drag-and-drop, preview grid of uploaded images, and remove buttons. Use for multi-image uploads, gallery management, or product photo uploads.",
+    keywords: ["upload", "image", "drag-drop", "gallery", "photos"],
+    visualWeight: "medium",
+    props: ["images?", "onImagesChange?", "maxImages?", "className?"]
+  },
+  Typography: {
+    path: "@/components/blocks",
+    description: "Text rendering component with semantic HTML tags (h1-h6, p, span, label) and design token typography styles. Maps to --typo-h1 through --typo-body-s tokens automatically. Use for any text content instead of raw HTML tags to ensure consistent typography.",
+    keywords: ["text", "heading", "paragraph", "typography", "font"],
+    visualWeight: "light",
+    props: ["as?: 'h1' | 'h2' | 'h3' | 'h4' | 'h5' | 'h6' | 'p' | 'span' | 'label'", "children", "className?"]
+  },
+  LineTabs: {
+    path: "@/components/blocks",
+    description: "Horizontal tab navigation with underline indicator on active tab. Tabs render as a row of text links with a bottom border highlight. Use for page-level or section-level tab navigation with a minimal underline style.",
+    keywords: ["tabs", "navigation", "underline", "line", "horizontal"],
+    visualWeight: "light",
+    props: ["tabs?", "activeTab?", "onTabChange?", "className?"]
+  },
+  ChatMessage: {
+    path: "@/components/blocks",
+    description: "Individual chat message component with avatar, sender name, timestamp, and message content. Supports sent/received alignment. Use inside chat interfaces for individual message rendering.",
+    keywords: ["chat", "message", "conversation", "bubble"],
+    visualWeight: "light",
+    props: ["message?", "className?"]
+  },
+  MultiselectCheckboxField: {
+    path: "@/components/blocks",
+    description: "Form field with a grid of checkbox options for multi-selection. Each option shows a checkbox with label. Use inside forms for selecting multiple items from a predefined list.",
+    keywords: ["multiselect", "checkbox", "form", "field", "options"],
+    visualWeight: "light",
+    props: ["label?", "options?", "selected?", "onChange?", "className?"]
+  },
+  MultiselectTags: {
+    path: "@/components/blocks",
+    description: "Tag-based multi-select input with removable tag chips and dropdown search. Selected items appear as tags that can be removed. Use for multi-select inputs where selected items should be visually prominent.",
+    keywords: ["multiselect", "tags", "chips", "select", "form"],
+    visualWeight: "light",
+    props: ["label?", "options?", "selected?", "onChange?", "placeholder?", "className?"]
+  },
+  Searchbox: {
+    path: "@/components/blocks",
+    description: "Compact search input with search icon and clear button. Use for inline search within tables, lists, or sidebars.",
+    keywords: ["search", "input", "find", "filter", "compact"],
+    visualWeight: "light",
+    props: ["value?", "onChange?", "placeholder?", "className?"]
+  },
+  TextInput: {
+    path: "@/components/blocks",
+    description: "Styled text input field with label, optional description, and error state. Wraps the base Input with form field structure. Use for individual form fields outside of FormGroup.",
+    keywords: ["input", "text", "field", "form"],
+    visualWeight: "light",
+    props: ["label?", "description?", "error?", "className?"]
+  },
+  MultistepProgressbarShell: {
+    path: "@/components/blocks",
+    description: "Alternative multi-step layout with a horizontal progress bar instead of numbered step tracker. Content area centered below. Use for simplified wizard flows where progress percentage matters more than step numbers.",
+    keywords: ["wizard", "multistep", "progress", "bar", "form"],
+    visualWeight: "light",
+    props: ["steps?", "currentStep?", "children?"]
   }
 };
 var groupModalDrawerBlocks = {
   FormGroup: {
     path: "@/components/blocks",
-    description: "Single-column form layout with header (title, sort, filter, action button), configurable fields, and footer (cancel/save). Supports text inputs, textareas, selects, date pickers, multiselect checkboxes, checkbox groups, radio groups, multiselect tags, image/file uploaders, and sliders.",
+    description: "Single-column form layout with header (title, sort, filter, action button), configurable fields, and footer (cancel/save). Supports text inputs, textareas, selects, date pickers, multiselect checkboxes, checkbox groups, radio groups, multiselect tags, image/file uploaders, and sliders. Use for any data entry form, settings page, or create/edit interface.",
+    keywords: ["form", "fields", "input", "data-entry", "create", "edit", "settings"],
+    visualWeight: "heavy",
     props: ["title?", "description?", "fields?: FormFieldConfig[]", "sortOptions?", "filterOptions?", "inputSize?: 'sm' | 'default' | 'lg'", "onAddNew?", "onCancel?", "onSave?", "onFieldChange?", "showHeader?", "showFooter?"]
   },
   DetailDrawer: {
     path: "@/components/blocks",
-    description: "Right-side detail drawer with tabbed content. Info tab shows metadata fields (with avatars, badges, links), rich content sections, and file attachments. Comments tab shows a chat-style thread with sender names, timestamps, and a comment input.",
+    description: "Right-side sliding drawer with tabbed content. Info tab shows metadata fields (with avatars, badges, links), rich content sections, and file attachments. Comments tab shows a chat-style thread. Use for row detail views, task details, record inspection, or any side-panel detail interface.",
+    keywords: ["drawer", "detail", "side-panel", "inspect", "comments", "overlay"],
+    visualWeight: "heavy",
     props: ["open?", "onOpenChange?", "title?", "subtitle?", "tabs?: DrawerTab[]", "activeTab?", "onTabChange?", "detailFields?: DetailField[][]", "richContent?", "attachments?: DrawerAttachment[]", "comments?: DrawerComment[]", "commentPlaceholder?", "onComment?", "onAttachmentDownload?"]
+  },
+  // Popup / Modal Components
+  ConfirmationPopup: {
+    path: "@/components/blocks",
+    description: "Modal overlay with title, description text, and confirm/cancel action buttons. Confirm button supports destructive (red) and default (primary) variants. Compact centered dialog (~200px tall). Use for delete confirmations, discard warnings, or any yes/no decision.",
+    keywords: ["confirm", "dialog", "modal", "delete", "warning", "destructive"],
+    visualWeight: "light",
+    props: ["open?", "onOpenChange?", "title?", "description?", "confirmLabel?", "cancelLabel?", "variant?", "onConfirm?", "onCancel?", "loading?"]
+  },
+  ContactFormPopup: {
+    path: "@/components/blocks",
+    description: "Contact form modal with gradient banner, large overlapping avatar, and configurable form fields supporting text, email, tel, and textarea inputs. Centered dialog (~450px tall). Use for contact forms, inquiry submissions, or any user-to-user messaging form.",
+    keywords: ["contact", "form", "modal", "message", "email", "inquiry"],
+    visualWeight: "medium",
+    props: ["open?", "onOpenChange?", "name?", "description?", "avatarUrl?", "fields?", "submitLabel?", "cancelLabel?", "onSubmit?", "onCancel?", "loading?"]
+  },
+  DetailsPopup: {
+    path: "@/components/blocks",
+    description: "Read-only details viewer modal displaying label-value pairs. Centered dialog (~300px tall). Use for displaying product specs, property information, record details, or any structured metadata.",
+    keywords: ["details", "view", "modal", "specs", "metadata", "info"],
+    visualWeight: "light",
+    props: ["open?", "onOpenChange?", "title?", "details?", "className?"]
+  },
+  FeedbackPopup: {
+    path: "@/components/blocks",
+    description: "Compact feedback collection modal with textarea for free-text input. Centered dialog (~250px tall). Use for user feedback, bug reports, feature requests, or any free-text submission.",
+    keywords: ["feedback", "modal", "textarea", "comment", "report"],
+    visualWeight: "light",
+    props: ["open?", "onOpenChange?", "title?", "description?", "submitLabel?", "cancelLabel?", "placeholder?", "onSubmit?", "onCancel?", "loading?"]
+  },
+  FormPopup: {
+    path: "@/components/blocks",
+    description: "Scrollable form modal supporting diverse field types: text, select, date, textarea, radio, checkbox, multiselect tags, image/file uploaders, and sliders. Centered dialog (~400-500px tall). Use for create/edit forms, settings dialogs, or any structured data input in a modal context.",
+    keywords: ["form", "modal", "fields", "input", "create", "edit", "dialog"],
+    visualWeight: "medium",
+    props: ["open?", "onOpenChange?", "title?", "description?", "fields?", "cancelLabel?", "saveLabel?", "inputSize?", "onSave?", "onCancel?", "onFieldChange?", "loading?"]
+  },
+  ImagePopup: {
+    path: "@/components/blocks",
+    description: "Minimal lightbox modal for displaying a single image in full view with responsive sizing. Use for image previews, photo zoom, or any image detail view.",
+    keywords: ["image", "lightbox", "modal", "preview", "zoom", "photo"],
+    visualWeight: "light",
+    props: ["open?", "onOpenChange?", "src?", "alt?"]
+  },
+  InvoicePopup: {
+    path: "@/components/blocks",
+    description: "Invoice display modal with header section (logo, title, metadata), line items table, summary calculations (subtotal, discount, total), and action button. Centered dialog (~500px tall). Use for invoice previews, receipt displays, or billing document views.",
+    keywords: ["invoice", "receipt", "billing", "modal", "payment", "document"],
+    visualWeight: "medium",
+    props: ["open?", "onOpenChange?", "title?", "subtitle?", "invoiceNumber?", "invoiceDate?", "recipientName?", "recipientAddress?", "lineItems?", "subtotal?", "discount?", "total?", "actionLabel?", "onAction?", "loading?"]
+  },
+  ListPopup: {
+    path: "@/components/blocks",
+    description: "Editable list management modal with add/remove functionality using EditableList component. Centered dialog (~300px tall). Use for managing tag lists, skill lists, or any dynamic list that needs a dedicated editor.",
+    keywords: ["list", "editable", "modal", "manage", "add", "remove"],
+    visualWeight: "light",
+    props: ["open?", "onOpenChange?", "title?", "listLabel?", "items?", "onSave?", "onCancel?", "addPlaceholder?"]
+  },
+  MultistepFormPopup: {
+    path: "@/components/blocks",
+    description: "Multi-step form wizard modal with configurable form steps, billing plan selection step, and loading/success state displays. Centered dialog (~450px tall). Use for complex multi-step processes in a modal: subscription signups, onboarding wizards, or multi-page forms.",
+    keywords: ["multistep", "wizard", "modal", "form", "steps", "subscription"],
+    visualWeight: "medium",
+    props: ["open?", "onOpenChange?", "steps?", "billingPlans?", "loadingTitle?", "successTitle?", "successDescription?", "onComplete?", "onSuccessButtonClick?"]
+  },
+  NpsSurveyPopup: {
+    path: "@/components/blocks",
+    description: "Numeric rating survey modal with number buttons (configurable 1-10 range) and end-labels (e.g., 'Not likely' to 'Very likely'). Compact centered dialog (~200px tall). Use for NPS surveys, satisfaction ratings, or any numeric scale feedback.",
+    keywords: ["nps", "survey", "rating", "modal", "score", "feedback"],
+    visualWeight: "light",
+    props: ["open?", "onOpenChange?", "title?", "description?", "value?", "onSubmit?", "onCancel?", "minLabel?", "maxLabel?", "min?", "max?"]
+  },
+  PersonalizeFeedPopup: {
+    path: "@/components/blocks",
+    description: "Topic selection modal displaying toggleable topic chips in a grid for feed personalization. Centered dialog (~350px tall). Use for interest selection, feed customization, preference settings, or any multi-choice topic picker.",
+    keywords: ["personalize", "topics", "interests", "modal", "feed", "preferences"],
+    visualWeight: "light",
+    props: ["open?", "onOpenChange?", "title?", "description?", "options?", "defaultSelected?", "onSave?", "onCancel?"]
+  },
+  PricingPlansPopup: {
+    path: "@/components/blocks",
+    description: "Pricing plan selector modal with monthly/annual billing toggle and radio card plan selection. Centered dialog (~400px tall). Use for in-app plan upgrades, subscription changes, or plan selection during checkout.",
+    keywords: ["pricing", "plans", "modal", "subscription", "billing", "upgrade"],
+    visualWeight: "medium",
+    props: ["open?", "onOpenChange?", "title?", "description?", "plans?", "billingPeriod?", "onBillingPeriodChange?", "selectedPlanId?", "onPlanChange?", "confirmLabel?", "cancelLabel?", "onConfirm?", "onCancel?", "loading?"]
+  },
+  PurchaseConfirmationPopup: {
+    path: "@/components/blocks",
+    description: "Checkout confirmation modal displaying summary, masked credit card selection with change option, and confirm/cancel actions. Compact centered dialog (~250px tall). Use for purchase confirmations, payment confirmations, or order finalization.",
+    keywords: ["purchase", "confirmation", "modal", "checkout", "payment", "card"],
+    visualWeight: "light",
+    props: ["open?", "onOpenChange?", "title?", "description?", "cardLabel?", "cardLastFour?", "onChangeCard?", "confirmLabel?", "cancelLabel?", "onConfirm?", "onCancel?", "loading?"]
+  },
+  ShareProjectPopup: {
+    path: "@/components/blocks",
+    description: "Project sharing modal with visibility dropdown, URL copy field, user invite select, and people-with-access list with role dropdowns and enable/disable toggles. Centered dialog (~450px tall). Use for sharing settings, collaboration invites, or permission management.",
+    keywords: ["share", "invite", "modal", "collaboration", "permissions", "access"],
+    visualWeight: "medium",
+    props: ["open?", "onOpenChange?", "title?", "description?", "visibilityOptions?", "shareUrl?", "inviteOptions?", "roles?", "people?", "onInvite?", "onRoleChange?", "onToggle?", "onCopyLink?"]
+  },
+  SlideshowPopup: {
+    path: "@/components/blocks",
+    description: "Full-screen image gallery modal with prev/next navigation, dot indicators, keyboard support (arrow keys), and author/likes/views metadata bar. Use for image slideshows, photo galleries, or portfolio detail views.",
+    keywords: ["slideshow", "gallery", "modal", "images", "fullscreen", "carousel"],
+    visualWeight: "medium",
+    props: ["open?", "onOpenChange?", "slides?", "author?", "likes?", "views?", "initialIndex?", "onSlideChange?"]
+  },
+  SmallEditPopup: {
+    path: "@/components/blocks",
+    description: "Compact edit form modal with text inputs arranged in flexible rows supporting half-width field pairing. Centered dialog (~250px tall). Use for quick edits, inline field editing, or small update forms.",
+    keywords: ["edit", "form", "modal", "compact", "quick-edit", "update"],
+    visualWeight: "light",
+    props: ["open?", "onOpenChange?", "title?", "description?", "fields?", "cancelLabel?", "saveLabel?", "onSave?", "onCancel?", "loading?"]
+  },
+  TermsOfServicePopup: {
+    path: "@/components/blocks",
+    description: "Scrollable content viewer modal for terms/legal documents with styled scrollbar and confirm/decline action buttons. Centered dialog (~450px tall). Use for terms of service, privacy policies, legal agreements, or any long-form content that needs acceptance.",
+    keywords: ["terms", "legal", "modal", "agreement", "policy", "tos"],
+    visualWeight: "medium",
+    props: ["open?", "onOpenChange?", "title?", "children?", "confirmLabel?", "cancelLabel?", "onConfirm?", "onCancel?", "loading?"]
+  },
+  VideoPopup: {
+    path: "@/components/blocks",
+    description: "YouTube video player modal displaying full-width video. Centered dialog. Use for video previews, tutorial popups, or any embedded video in a modal context.",
+    keywords: ["video", "youtube", "modal", "player", "tutorial"],
+    visualWeight: "medium",
+    props: ["open?", "onOpenChange?", "videoId?", "title?"]
+  },
+  ViewProfilePopup: {
+    path: "@/components/blocks",
+    description: "Profile card modal with gradient banner, overlapping avatar, star rating, flexible detail rows (text/tags/icons), message/more-options buttons, and optional profile link. Centered dialog (~400px tall). Use for user profile previews, contact cards, or member detail popups.",
+    keywords: ["profile", "modal", "user", "avatar", "rating", "contact"],
+    visualWeight: "medium",
+    props: ["open?", "onOpenChange?", "name?", "subtitle?", "avatarUrl?", "rating?", "details?", "profileUrl?", "onMessage?", "onMoreOptions?"]
   }
 };
 var videoBlocks = {
   VideoChatControls: {
     path: "@/components/blocks",
-    description: "Row of circular buttons for video calls: camera, mic, cast, leave.",
+    description: "Row of circular toggle buttons for video/audio calls: camera on/off, microphone on/off, screen cast, and leave/end call. Use at the bottom of any video conferencing or audio call interface.",
+    keywords: ["video", "call", "controls", "camera", "microphone"],
+    visualWeight: "light",
     props: ["isVideoOn?", "isMicOn?", "onToggleVideo?", "onToggleMic?", "onCast?", "onLeave?"]
   },
   WebcamPreview: {
     path: "@/components/blocks",
-    description: "Live webcam preview component with optional overlay controls.",
+    description: "Video preview component showing a webcam or video feed with optional overlay controls. Use for video call self-view, camera preview, or live streaming interfaces.",
+    keywords: ["video", "webcam", "camera", "preview", "stream"],
+    visualWeight: "medium",
     props: ["className?", "showControls?"]
   },
   ParticipantList: {
     path: "@/components/blocks",
-    description: "List of video call participants with avatars and status.",
+    description: "Vertical list of participants with avatars, names, and connection status indicators. Use for video call participant panels, meeting attendees, or online user lists.",
+    keywords: ["participants", "attendees", "users", "video-call", "meeting"],
+    visualWeight: "medium",
     props: ["participants: Participant[]"]
   },
   VideoPlaylist: {
     path: "@/components/blocks",
-    description: "Sidebar playlist for video content with thumbnails.",
+    description: "Sidebar playlist of video items with thumbnails, titles, and duration. Current video highlighted. Use for course lessons, tutorial series, or any sequential video content.",
+    keywords: ["playlist", "videos", "lessons", "course", "tutorial"],
+    visualWeight: "medium",
     props: ["videos: Video[]", "currentVideo?", "onVideoSelect?"]
   },
   VideoContentSection: {
     path: "@/components/blocks",
-    description: "Video player area with metadata and description.",
+    description: "Video player area with title, metadata (views, date, channel), description text, and social actions. Use for video detail pages, course lessons, or media content pages.",
+    keywords: ["video", "player", "content", "media", "description"],
+    visualWeight: "heavy",
     props: ["video: Video", "onPlay?"]
   },
   YouTubePlayer: {
     path: "@/components/blocks",
-    description: "Embedded YouTube player component.",
+    description: "Embedded YouTube video player component. Renders a responsive YouTube iframe. Use for embedding tutorial videos, product demos, or any YouTube content.",
+    keywords: ["youtube", "video", "embed", "player"],
+    visualWeight: "medium",
     props: ["videoId: string", "autoplay?"]
   }
 };
@@ -21256,241 +21700,539 @@ var marketingBlocks = {
   // Hero Sections
   HeroSection: {
     path: "@/components/blocks/marketing",
-    description: "Hero with background image and simple search bar overlay.",
+    description: "Full-width hero banner with background image, large heading, subtitle text, and optional search bar overlay. Use as the main visual entry point for landing pages, homepages, or category pages.",
+    keywords: ["hero", "banner", "landing", "search", "homepage"],
+    visualWeight: "spacer",
     props: ["title", "subtitle", "searchPlaceholder?", "backgroundImage?"]
   },
   HeroDarkWithImage: {
     path: "@/components/blocks/marketing",
-    description: "Dark hero section with text on left and image on right.",
+    description: "Dark-background hero section with heading and subtitle on the left, large feature image on the right. Stacks vertically on mobile. Use for product launches, feature announcements, or SaaS landing pages.",
+    keywords: ["hero", "dark", "feature", "product", "landing"],
+    visualWeight: "spacer",
     props: ["title", "subtitle", "image"]
   },
   HeroDarkCentered: {
     path: "@/components/blocks/marketing",
-    description: "Dark centered hero with multi-field search (location, dates, guests).",
+    description: "Dark-background centered hero with large heading, subtitle, and multi-field search bar (location, dates, guests). Use for search-focused homepages like travel, real estate, or marketplace sites.",
+    keywords: ["hero", "dark", "centered", "search", "landing"],
+    visualWeight: "spacer",
     props: ["title", "subtitle"]
   },
   HeroFullwidthImage: {
     path: "@/components/blocks/marketing",
-    description: "Full-width hero image with centered content and multi-field search.",
+    description: "Full-width hero with background image covering entire section, centered heading and subtitle overlay, and multi-field search bar. Use for visually immersive landing pages.",
+    keywords: ["hero", "fullwidth", "image", "immersive", "landing"],
+    visualWeight: "spacer",
     props: ["title", "subtitle", "backgroundImage"]
   },
   CenteredHero: {
     path: "@/components/blocks/marketing",
-    description: "Simple centered hero for about/landing pages.",
+    description: "Clean centered hero with large heading and subtitle text on a plain background. No image or search bar. Use for about pages, company pages, or minimal landing sections.",
+    keywords: ["hero", "centered", "minimal", "about", "clean"],
+    visualWeight: "spacer",
     props: ["title", "subtitle?"]
   },
   // Content Sections
   DestinationCards: {
     path: "@/components/blocks/marketing",
-    description: "Grid of destination cards with images and titles.",
+    description: "4-column card grid with large images, title, item count, and price. Each card has hover zoom effect. Header with title and 'Explore more' link. Use for featured categories, popular items, highlighted locations, or any curated collection showcase.",
+    keywords: ["cards", "grid", "categories", "featured", "browse", "destinations"],
+    visualWeight: "medium",
     props: ["title?", "destinations?"]
   },
   FeaturedPlaces: {
     path: "@/components/blocks/marketing",
-    description: "Featured places section with filter pills and card grid.",
+    description: "3-column card grid with filter pill tabs at top, image cards with name, rating, item count, and price. Header with title and 'Explore more' link. Use for filterable catalogs, featured products, or curated collections with category filtering.",
+    keywords: ["cards", "grid", "filter", "featured", "catalog"],
+    visualWeight: "medium",
     props: ["title?", "filters?", "places?"]
   },
   CategoryGrid: {
     path: "@/components/blocks/marketing",
-    description: "Grid of category cards with icons/images.",
+    description: "5-column grid of category cards, each with a large icon, category title, and item count on a bordered card. Use for browse-by-category sections, service categories, or topic navigation grids.",
+    keywords: ["categories", "grid", "icons", "browse", "navigation"],
+    visualWeight: "medium",
     props: ["categories?"]
   },
   GallerySection: {
     path: "@/components/blocks/marketing",
-    description: "Image gallery with title and grid layout.",
+    description: "3-column masonry-style image gallery with varying image heights. Header with title, subtitle, and two description paragraphs. Light and dark variants. Use for photo galleries, portfolio showcases, or visual inspiration sections.",
+    keywords: ["gallery", "images", "masonry", "photos", "portfolio"],
+    visualWeight: "heavy",
     props: ["title?", "subtitle?", "images?"]
   },
   BlogCards: {
     path: "@/components/blocks/marketing",
-    description: "Grid of blog post cards with images, titles, dates.",
+    description: "3-column grid of blog/article cards with large images, title, description, and 'Read more' link with arrow icon. Header with subtitle and title. Use for blog sections, news feeds, content highlights, or any editorial content grid.",
+    keywords: ["blog", "articles", "news", "content", "cards"],
+    visualWeight: "medium",
     props: ["title?", "subtitle?", "posts?"]
   },
   // How It Works
   HowItWorks: {
     path: "@/components/blocks/marketing",
-    description: "Horizontal 3-step how it works section.",
+    description: "4-column grid of feature items, each with a large icon, title, and description. Light and dark variants. Use for 'how it works' steps, feature highlights, value propositions, or benefit lists.",
+    keywords: ["features", "steps", "benefits", "how-it-works", "value"],
+    visualWeight: "medium",
     props: ["steps?"]
   },
   VerticalHowItWorks: {
     path: "@/components/blocks/marketing",
-    description: "Vertical how it works with large numbers. Has light/dark variants.",
+    description: "Vertical numbered list of steps with large step numbers, titles, and descriptions. Header with title and description. Light and dark variants. Use for process explanations, getting started guides, or numbered feature lists.",
+    keywords: ["steps", "process", "numbered", "how-it-works", "guide"],
+    visualWeight: "medium",
     props: ["variant?: 'light' | 'dark'", "title", "description", "steps?"]
   },
   // Social Proof
   TestimonialCarousel: {
     path: "@/components/blocks/marketing",
-    description: "Dark testimonial carousel with quote, author, and navigation arrows.",
+    description: "Dark-background testimonial carousel showing one quote at a time with author name, role, avatar, and left/right navigation arrows. Use for customer testimonials, user quotes, or endorsement sections.",
+    keywords: ["testimonials", "quotes", "reviews", "social-proof", "carousel"],
+    visualWeight: "medium",
     props: ["testimonials?"]
   },
   ReviewsGrid: {
     path: "@/components/blocks/marketing",
-    description: "Grid of review cards with ratings and text.",
+    description: "3-column grid of review cards, each with quote text, author avatar, name, and location. Cards distributed across columns for masonry effect. Use for customer reviews, testimonial grids, or social proof sections.",
+    keywords: ["reviews", "testimonials", "grid", "social-proof", "quotes"],
+    visualWeight: "medium",
     props: ["title?", "subtitle?", "reviews?"]
   },
   SocialProof: {
     path: "@/components/blocks/marketing",
-    description: "Logo bar showing 'as featured on' brands.",
+    description: "Horizontal logo bar with 'as featured in' label and partner/press brand logos. Use for trust indicators, partner logos, media mentions, or integration partner displays.",
+    keywords: ["logos", "partners", "trust", "featured-in", "brands"],
+    visualWeight: "light",
     props: ["label?", "logos?"]
   },
   MetricsSection: {
     path: "@/components/blocks/marketing",
-    description: "Row of large metric numbers with labels.",
+    description: "Row of 2-4 large metric numbers with labels below, separated by left borders. Header with subtitle and title. Metrics grid shows 2 columns on mobile, 4 on desktop. Prefer this for marketing/landing page stat displays \u2014 includes left-border separators, h1-scale typography, and responsive grid. Use for company stats, key figures, achievement highlights, or any numeric overview section.",
+    keywords: ["metrics", "stats", "numbers", "achievements", "key-figures"],
+    visualWeight: "light",
     props: ["metrics?"]
   },
   // Features
   FeatureWithImage: {
     path: "@/components/blocks/marketing",
-    description: "Feature highlight with image and text side by side.",
+    description: "Two-column feature section with large image on one side and heading, description, benefit list, and CTA button on the other. Image position toggleable (left/right). Stacks vertically on mobile. Use for product features, service explanations, or benefit showcases.",
+    keywords: ["feature", "two-column", "image", "benefits", "product"],
+    visualWeight: "medium",
     props: ["title", "description", "ctaText?", "imagePosition?: 'left' | 'right'"]
   },
   ContentWithImage: {
     path: "@/components/blocks/marketing",
-    description: "Generic content section with image. Similar to FeatureWithImage.",
+    description: "Two-column content section with image and text content side by side. Image position toggleable. Similar to FeatureWithImage but more generic. Use for any content + image layout.",
+    keywords: ["content", "image", "two-column", "text", "layout"],
+    visualWeight: "medium",
     props: ["title", "content", "image", "imagePosition?"]
   },
   CoreValuesGrid: {
     path: "@/components/blocks/marketing",
-    description: "Grid of value cards with icons and descriptions.",
+    description: "3-column grid of value cards, each with an icon in a square container, title, and description text. Centered header with subtitle, title, and description. Light and dark variants. Use for core values, company principles, service benefits, or feature grids.",
+    keywords: ["values", "principles", "benefits", "features", "grid"],
+    visualWeight: "medium",
     props: ["values?"]
   },
   // Team
   TeamCardsGrid: {
     path: "@/components/blocks/marketing",
-    description: "Grid of team member cards with photos and roles.",
+    description: "4-column grid of team member cards with portrait photos, name, and role/title text. Photos have responsive height. Use for team pages, about pages, staff directories, or leadership sections.",
+    keywords: ["team", "members", "people", "staff", "leadership"],
+    visualWeight: "medium",
     props: ["title?", "members?"]
   },
   TeamCircularGrid: {
     path: "@/components/blocks/marketing",
-    description: "Team grid with circular avatar photos.",
+    description: "Grid of team members with circular avatar photos, name, and role text. More compact than TeamCardsGrid. Use for advisory boards, small teams, or avatar-focused people grids.",
+    keywords: ["team", "members", "avatars", "people", "compact"],
+    visualWeight: "medium",
     props: ["title?", "members?"]
   },
   // CTA & Footer
   CtaBanner: {
     path: "@/components/blocks/marketing",
-    description: "Call to action banner with title and button.",
+    description: "Full-width call-to-action banner with heading text and primary action button. Use for newsletter signups, contact prompts, trial starts, or any conversion-focused section.",
+    keywords: ["cta", "call-to-action", "conversion", "signup", "banner"],
+    visualWeight: "light",
     props: ["title", "buttonText", "onButtonClick?"]
   },
   FooterNavbar: {
     path: "@/components/blocks/marketing",
-    description: "Footer with logo, nav links, and social icons.",
+    description: "Full-width footer with company logo, multi-column navigation link groups, and social media icons. Use at the bottom of any marketing or content page.",
+    keywords: ["footer", "navigation", "links", "social", "bottom"],
+    visualWeight: "medium",
     props: ["companyName?", "links?", "socialLinks?"]
   },
   // Other
   FeaturedNewsCards: {
     path: "@/components/blocks/marketing",
-    description: "Featured news/press cards section.",
+    description: "2-column grid of large news/press cards with images, headlines, descriptions, and 'Read more' links. Centered header with subtitle, title, and description. Light and dark variants. Use for press coverage, news highlights, blog features, or content spotlights.",
+    keywords: ["news", "press", "articles", "featured", "highlights"],
+    visualWeight: "medium",
     props: ["title?", "articles?"]
   },
   OfficeLocations: {
     path: "@/components/blocks/marketing",
-    description: "Grid of office location cards with addresses.",
+    description: "3-column grid of location cards, each showing city name and multi-line address in a bordered card. Header with subtitle, title, and description. Use for office locations, store directories, branch listings, or any multi-location display.",
+    keywords: ["offices", "locations", "addresses", "branches", "stores"],
+    visualWeight: "medium",
     props: ["title?", "locations?"]
   }
 };
 var pricingBlocks = {
   PricingCards: {
     path: "@/components/blocks/pricing",
-    description: "Three-tier pricing cards with monthly/annual toggle, features list, and CTA buttons.",
+    description: "Three-tier pricing cards with monthly/annual billing toggle, 'Most Popular' badge, feature checklists, AI add-on badges, and CTA buttons. Below cards is a contact/enterprise banner. Use for SaaS pricing, subscription plans, or any tiered pricing display.",
+    keywords: ["pricing", "plans", "subscription", "tiers", "billing"],
+    visualWeight: "heavy",
     props: ["plans?"]
   },
   FaqAccordion: {
     path: "@/components/blocks/pricing",
-    description: "Expandable FAQ accordion for pricing pages.",
+    description: "Expandable FAQ accordion with question titles and expandable answer text. Use for pricing FAQ sections, help pages, or any expandable Q&A content.",
+    keywords: ["faq", "questions", "answers", "accordion", "help"],
+    visualWeight: "medium",
     props: ["faqs?: FAQ[]"]
   },
   FeaturesComparison: {
     path: "@/components/blocks/pricing",
-    description: "Feature comparison table across pricing tiers.",
+    description: "Feature comparison table showing plan names across columns and feature rows with check/cross indicators. Use for comparing pricing tiers, product editions, or service levels side by side.",
+    keywords: ["comparison", "features", "plans", "table", "tiers"],
+    visualWeight: "heavy",
     props: ["features?", "plans?"]
   },
   PricingCta: {
     path: "@/components/blocks/pricing",
-    description: "CTA section for pricing page (contact sales, etc.).",
+    description: "Call-to-action section for pricing pages with heading, description, and action button. Use for 'Contact Sales', 'Start Free Trial', or any pricing page conversion section.",
+    keywords: ["pricing", "cta", "call-to-action", "sales", "trial"],
+    visualWeight: "light",
     props: ["title?", "description?", "buttonText?"]
   }
 };
+var uiPrimitives = {
+  Button: {
+    path: "@/components/ui",
+    description: "Themed button with 6 variants (primary, primary-outline, primary-neutral, neutral, neutral-delete, delete) and 4 sizes (mini, sm, default, lg). Inline element (~36-48px tall depending on size). Use for form submissions, actions, navigation, or any clickable trigger.",
+    keywords: ["button", "action", "submit", "click", "cta"],
+    visualWeight: "light",
+    props: ["variant?", "size?", "disabled?", "children", "className?", "onClick?"]
+  },
+  Input: {
+    path: "@/components/ui",
+    description: "Themed text input field with border, focus ring, and placeholder styling. Supports standard HTML input attributes. Use for single-line text entry in forms.",
+    keywords: ["input", "text", "field", "form"],
+    visualWeight: "light",
+    props: ["type?", "placeholder?", "value?", "onChange?", "disabled?", "className?"]
+  },
+  Textarea: {
+    path: "@/components/ui",
+    description: "Themed multi-line text area with border and focus ring. Use for long-form text entry like descriptions, comments, or messages.",
+    keywords: ["textarea", "text", "multiline", "form", "comment"],
+    visualWeight: "light",
+    props: ["placeholder?", "value?", "onChange?", "rows?", "disabled?", "className?"]
+  },
+  Select: {
+    path: "@/components/ui",
+    description: "Themed dropdown select with trigger button, content panel, and option items. Built on Radix Select. Use for choosing one option from a list.",
+    keywords: ["select", "dropdown", "option", "form", "choose"],
+    visualWeight: "light",
+    props: ["value?", "onValueChange?", "placeholder?", "children", "disabled?"]
+  },
+  Checkbox: {
+    path: "@/components/ui",
+    description: "Themed checkbox with check indicator. Built on Radix Checkbox. Use for boolean toggles or multi-select lists in forms.",
+    keywords: ["checkbox", "toggle", "form", "boolean"],
+    visualWeight: "light",
+    props: ["checked?", "onCheckedChange?", "disabled?", "className?"]
+  },
+  RadioGroup: {
+    path: "@/components/ui",
+    description: "Themed radio button group for single selection from multiple options. Built on Radix RadioGroup. Use when users must choose exactly one option.",
+    keywords: ["radio", "group", "form", "selection", "choice"],
+    visualWeight: "light",
+    props: ["value?", "onValueChange?", "children", "disabled?", "className?"]
+  },
+  Switch: {
+    path: "@/components/ui",
+    description: "Themed toggle switch for on/off states. Built on Radix Switch. Use for boolean settings, feature toggles, or any on/off preference.",
+    keywords: ["switch", "toggle", "on-off", "boolean", "setting"],
+    visualWeight: "light",
+    props: ["checked?", "onCheckedChange?", "disabled?", "className?"]
+  },
+  Slider: {
+    path: "@/components/ui",
+    description: "Themed range slider with track and thumb. Built on Radix Slider. Use for numeric range selection like price filters, volume controls, or rating inputs.",
+    keywords: ["slider", "range", "numeric", "filter", "control"],
+    visualWeight: "light",
+    props: ["value?", "onValueChange?", "min?", "max?", "step?", "disabled?", "className?"]
+  },
+  Dialog: {
+    path: "@/components/ui",
+    description: "Modal dialog overlay with title, description, and content area. Built on Radix Dialog. Use as the base for popup components or any modal interaction.",
+    keywords: ["dialog", "modal", "overlay", "popup"],
+    visualWeight: "light",
+    props: ["open?", "onOpenChange?", "children"]
+  },
+  Sheet: {
+    path: "@/components/ui",
+    description: "Side panel overlay that slides in from the edge of the screen. Built on Radix Dialog. Use for detail drawers, mobile menus, or side-panel content.",
+    keywords: ["sheet", "drawer", "side-panel", "overlay", "slide"],
+    visualWeight: "light",
+    props: ["open?", "onOpenChange?", "side?", "children"]
+  },
+  Popover: {
+    path: "@/components/ui",
+    description: "Floating content panel anchored to a trigger element. Built on Radix Popover. Use for filter dropdowns, tooltips with rich content, or contextual menus.",
+    keywords: ["popover", "floating", "dropdown", "anchor"],
+    visualWeight: "light",
+    props: ["open?", "onOpenChange?", "children"]
+  },
+  DropdownMenu: {
+    path: "@/components/ui",
+    description: "Dropdown menu with items, labels, separators, and keyboard navigation. Built on Radix DropdownMenu. Use for action menus, context menus, or any dropdown list of actions.",
+    keywords: ["dropdown", "menu", "actions", "context-menu"],
+    visualWeight: "light",
+    props: ["children"]
+  },
+  Tooltip: {
+    path: "@/components/ui",
+    description: "Small text tooltip that appears on hover. Built on Radix Tooltip. Use for brief explanatory text on icons, buttons, or truncated labels.",
+    keywords: ["tooltip", "hover", "hint", "help"],
+    visualWeight: "light",
+    props: ["children"]
+  },
+  Avatar: {
+    path: "@/components/ui",
+    description: "Circular avatar image with fallback initials. Built on Radix Avatar. Use for user photos, profile thumbnails, or any person/entity representation.",
+    keywords: ["avatar", "image", "profile", "user", "photo"],
+    visualWeight: "light",
+    props: ["src?", "alt?", "fallback?", "className?"]
+  },
+  Tabs: {
+    path: "@/components/ui",
+    description: "Tab navigation with content panels. Built on Radix Tabs. Use for switching between different content views within a section.",
+    keywords: ["tabs", "navigation", "panels", "switch"],
+    visualWeight: "light",
+    props: ["value?", "onValueChange?", "children"]
+  },
+  Label: {
+    path: "@/components/ui",
+    description: "Themed form label associated with an input. Built on Radix Label. Use for labeling form fields.",
+    keywords: ["label", "form", "field", "text"],
+    visualWeight: "light",
+    props: ["htmlFor?", "children", "className?"]
+  },
+  Separator: {
+    path: "@/components/ui",
+    description: "Horizontal or vertical separator line. Built on Radix Separator. Use for visually dividing sections of content.",
+    keywords: ["separator", "divider", "line", "hr"],
+    visualWeight: "light",
+    props: ["orientation?", "className?"]
+  },
+  Skeleton: {
+    path: "@/components/ui",
+    description: "Loading placeholder skeleton with animated shimmer effect. Use for content loading states to show layout structure before data loads.",
+    keywords: ["skeleton", "loading", "placeholder", "shimmer"],
+    visualWeight: "light",
+    props: ["className?"]
+  },
+  ScrollArea: {
+    path: "@/components/ui",
+    description: "Custom scrollable container with themed scrollbar. Built on Radix ScrollArea. Use for scrollable panels, long lists, or content that exceeds container height.",
+    keywords: ["scroll", "scrollbar", "overflow", "container"],
+    visualWeight: "light",
+    props: ["children", "className?"]
+  },
+  Calendar: {
+    path: "@/components/ui",
+    description: "Month calendar widget for single or range date selection. Shows month grid with navigation arrows. Use for date pickers, scheduling inputs, or any date selection.",
+    keywords: ["calendar", "date", "picker", "month", "schedule"],
+    visualWeight: "light",
+    props: ["selected?", "onSelect?", "mode?", "disabled?", "className?"]
+  },
+  DateInput: {
+    path: "@/components/ui",
+    description: "Date input field with calendar icon that opens a calendar popover for date selection. Combines Input with Calendar. Use for date entry fields in forms.",
+    keywords: ["date", "input", "picker", "calendar", "form"],
+    visualWeight: "light",
+    props: ["value?", "onChange?", "placeholder?", "className?"]
+  },
+  RangeInput: {
+    path: "@/components/ui",
+    description: "Themed range slider input (HTML range type) with custom styling. Use for simple numeric range selection when Slider is too complex.",
+    keywords: ["range", "slider", "numeric", "input"],
+    visualWeight: "light",
+    props: ["min?", "max?", "step?", "value?", "onChange?", "className?"]
+  }
+};
 var pageTemplates = {
   "page-admin-portal": {
     path: "/page-admin-portal",
-    description: "Admin dashboard with dark sidebar, collapsible nav sections, and data table.",
+    description: "Full-screen admin application with dark sidebar navigation (320px), fixed top header with user avatar, and main content area with data table. Use for admin dashboards, CRM tools, back-office management, or any data-heavy app with many navigation sections.",
     shell: "DashboardShell",
     blocks: ["StandardDataTable", "Header"]
   },
+  "page-account": {
+    path: "/page-account",
+    description: "Account settings page with left sidebar tab navigation (Profile, Security, Payments, Notifications) and right content area showing editable settings rows, avatar upload, and saved payment cards. Use for user account management, profile editing, or any settings interface.",
+    shell: "AccountSettingsShell",
+    blocks: ["ProfileImageUploader", "SettingsListRow", "CreditCardDisplay"]
+  },
+  "page-login": {
+    path: "/page-login",
+    description: "Split-screen authentication page. Left side has a login form with email/password fields, 'Remember me' checkbox, and social login options. Right side has a branding panel with background image and logo. Use for login, signup, or authentication flows.",
+    shell: "custom (split layout)",
+    blocks: ["LoginBrandingPanel"]
+  },
+  "page-reset-password": {
+    path: "/page-reset-password",
+    description: "Password reset/recovery page with header and a centered bordered card containing a content area for the reset form. Minimal layout. Use for password reset, email verification, or any single-action authentication flow.",
+    shell: "custom (Header + centered card)",
+    blocks: ["Header", "ContentDropzone"]
+  },
+  "page-checkout": {
+    path: "/page-checkout",
+    description: "Multi-step purchase flow with 5 steps: shopping cart (quantity controls), shipping info form, shipping method selection, payment method selection, and order confirmation. Right sidebar shows order summary throughout. Use for e-commerce checkout, booking flows, or any multi-step purchase process.",
+    shell: "custom (Header + two-column)",
+    blocks: ["Header", "OrderSummarySidebar", "Button", "Separator"]
+  },
   "page-messenger": {
     path: "/page-messenger",
-    description: "Full messaging interface with thread sidebar and chat area.",
+    description: "Full-screen messaging interface with thread list sidebar (search, avatars, timestamps, unread badges) and conversation area (message bubbles, date separators, input bar). Use for chat applications, customer support inboxes, or team messaging tools.",
     shell: "custom (no shell)",
     blocks: ["MessengerSidebar", "ChatBubble", "ChatDateSeparator", "MessengerInput"]
   },
   "page-product-homepage": {
     path: "/page-product-homepage",
-    description: "Marketing landing page with multiple hero variations and content blocks.",
+    description: "Full-width marketing landing page with stacked sections: header, hero with search, destination cards, featured places, category grid, how-it-works, testimonials, blog cards, and footer. No sidebar. Use for product homepages, marketplace landing pages, travel sites, or SaaS marketing pages.",
     shell: "custom (no shell)",
     blocks: ["Header", "HeroSection", "HeroDarkWithImage", "DestinationCards", "TestimonialCarousel", "FooterNavbar"]
   },
   "page-pricing": {
     path: "/page-pricing",
-    description: "Pricing page with tier cards, FAQ, and feature comparison.",
+    description: "Pricing page with header, three-tier pricing cards with billing toggle, feature comparison table, FAQ accordion, and CTA section. Use for SaaS pricing, subscription plan selection, or any tiered pricing display.",
     shell: "custom (no shell)",
     blocks: ["Header", "PricingCards", "FaqAccordion", "FeaturesComparison"]
   },
   "page-about": {
     path: "/page-about",
-    description: "About page with hero, metrics, values, team, and locations.",
+    description: "Company/organization about page with centered hero, key metrics row, core values grid, team member cards, and office locations. Use for about us pages, company information, or organizational overview pages.",
     shell: "custom (no shell)",
     blocks: ["Header", "CenteredHero", "MetricsSection", "CoreValuesGrid", "TeamCardsGrid"]
   },
-  "page-account": {
-    path: "/page-account",
-    description: "Account settings with tabbed sidebar navigation.",
-    shell: "AccountSettingsShell",
-    blocks: ["ProfileImageUploader", "SettingsListRow", "CreditCardDisplay"]
+  "page-standard": {
+    path: "/page-standard",
+    description: "Standard centered content page (max 992px) with optional flair banner at top, page title/description header, and optional horizontal tabs. No sidebar. Use for content pages, documentation, help centers, or any simple centered layout.",
+    shell: "StandardPageShell",
+    blocks: ["FlairBanner", "PageHeaderSection"]
+  },
+  "page-standard-dashboard": {
+    path: "/page-standard-dashboard",
+    description: "Dashboard page using DashboardShell with dark sidebar navigation and main content area. Content area has a ContentDropzone for placing dashboard widgets. Use as a starting point for any sidebar-based dashboard application.",
+    shell: "DashboardShell",
+    blocks: ["ContentDropzone"]
   },
   "page-centered-profile": {
     path: "/page-centered-profile",
-    description: "Profile page with centered layout and banner.",
+    description: "Profile page with flair banner at top and centered profile card below showing avatar, stats, bio, tags, and social links. Use for user profiles, author pages, or public-facing member pages.",
     shell: "StandardPageShell",
     blocks: ["ProfileCard", "FlairBanner"]
   },
+  "page-sidebar-profile": {
+    path: "/page-sidebar-profile",
+    description: "Profile page with header, gradient banner, and two-column layout. Left sidebar (360px) stacks SidebarProfileCard, StatsCard, PortfolioCard, DescriptionCard, SkillsCard, LinksCard, and BadgesCard. Right content area has PillTabs and a ContentDropzone placeholder. Use for user profiles, freelancer portfolios, or any profile page with detailed sidebar info.",
+    shell: "custom (Header + GradientBanner + two-column)",
+    blocks: ["Header", "GradientBanner", "SidebarProfileCard", "StatsCard", "PortfolioCard", "DescriptionCard", "SkillsCard", "LinksCard", "BadgesCard", "PillTabs", "ContentDropzone"]
+  },
   "page-double-sidebar": {
     path: "/page-double-sidebar",
-    description: "Dashboard with two-column sidebar navigation.",
+    description: "Dashboard with two-column sidebar: narrow icon strip (96px) on far left, wider navigation panel (280px) next to it. Main content area has data table. Use for complex apps with many categories and sub-navigation.",
     shell: "DoubleSidebarShell",
     blocks: ["StandardDataTable"]
   },
   "page-icon-sidebar": {
     path: "/page-icon-sidebar",
-    description: "Dashboard with narrow icon-only sidebar.",
+    description: "Dashboard with narrow icon-only sidebar (96px) for minimal navigation footprint. Main content area has data table. Use for apps with few main sections that want maximum content space.",
     shell: "IconSidebarShell",
     blocks: ["StandardDataTable"]
   },
-  "page-login": {
-    path: "/page-login",
-    description: "Login page with form and branding panel.",
-    shell: "custom (split layout)",
-    blocks: ["LoginBrandingPanel"]
-  },
-  "page-standard": {
-    path: "/page-standard",
-    description: "Standard centered page with banner and tabs.",
-    shell: "StandardPageShell",
-    blocks: ["FlairBanner", "PageHeaderSection"]
-  },
   "page-standard-multistep": {
     path: "/page-standard-multistep",
-    description: "Multi-step form wizard with horizontal step tracker.",
+    description: "Multi-step form wizard with horizontal step tracker at top showing numbered steps. Centered content area (max 768px) with navigation buttons. Use for registration, onboarding, or any sequential form flow.",
     shell: "MultistepShell",
     blocks: ["StepTracker", "ContentDropzone"]
   },
+  "page-multistep-with-sidebar": {
+    path: "/page-multistep-with-sidebar",
+    description: "Multi-step wizard with step list in a left sidebar showing step names and descriptions. Main content area on right. Use when steps need more context or the flow has many steps.",
+    shell: "MultistepSidebarShell",
+    blocks: ["ContentDropzone"]
+  },
+  "page-multistep-with-progressbar": {
+    path: "/page-multistep-with-progressbar",
+    description: "Multi-step form with header and horizontal progress bar showing overall completion. Centered content area with step tracker and navigation buttons. Use for simpler flows where step count matters less than progress percentage.",
+    shell: "custom (Header + StepTracker)",
+    blocks: ["Header", "StepTracker", "ContentDropzone"]
+  },
+  "page-standard-multistep-with-sidebar": {
+    path: "/page-standard-multistep-with-sidebar",
+    description: "Multi-step form with header and two-column layout: vertical step tracker in a bordered left sidebar (280px) and content area on right with navigation buttons. Use for registration flows or onboarding with sidebar step navigation.",
+    shell: "custom (Header + two-column)",
+    blocks: ["Header", "VerticalStepTracker", "ContentDropzone"]
+  },
+  "page-vertical-multistep": {
+    path: "/page-vertical-multistep",
+    description: "Compact multi-step form with vertical step tracker on left (240px) showing step names and descriptions, and content area on right. No header. Centered (max 800px). Use for embedded forms or focused wizard flows.",
+    shell: "custom (two-column, no header)",
+    blocks: ["VerticalStepTracker", "ContentDropzone"]
+  },
+  "page-mobile-menu": {
+    path: "/page-mobile-menu",
+    description: "Mobile-first layout with sticky bottom navigation bar (Home, Search, Profile tabs). Content area above with padding. Use for mobile app-like experiences, responsive apps, or any interface needing bottom tab navigation.",
+    shell: "MobileMenuShell",
+    blocks: ["ContentDropzone"]
+  },
+  "page-search-bar": {
+    path: "/page-search-bar",
+    description: "Search-focused page with StandardPageShell, prominent search bar, and content area below for results. Use for search interfaces, documentation search, directory lookup, or knowledge base exploration.",
+    shell: "StandardPageShell",
+    blocks: ["SearchBar", "ContentDropzone"]
+  },
+  "page-standard-search": {
+    path: "/page-standard-search",
+    description: "Standard page with search functionality using StandardPageShell. Title, description, search bar, and results area. Use for search results pages, filtered listings, or any searchable content interface.",
+    shell: "StandardPageShell",
+    blocks: ["SearchBar", "ContentDropzone"]
+  },
+  "page-form-group": {
+    path: "/page-form-group",
+    description: "Centered single-column form page (max 960px) displaying a FormGroup component with configurable fields, header controls, and save/cancel footer. Use for create/edit forms, data entry pages, or settings forms.",
+    shell: "custom (centered)",
+    blocks: ["FormGroup"]
+  },
+  "page-gallery-profile-product": {
+    path: "/page-gallery-profile-product",
+    description: "Product or profile detail page with header, full-width image gallery at top, then two-column layout: main content area on left, sidebar on right with reservation card, order summary, info cards, and links. Bottom action bar. Use for product detail pages, listing detail views, or service booking pages.",
+    shell: "custom (Header + gallery + two-column)",
+    blocks: ["Header", "TileImageGallery", "ContentDropzone", "ReservationCard", "OrderSummarySidebar"]
+  },
+  "page-menu-sections": {
+    path: "/page-menu-sections",
+    description: "Page with header, centered title/description, and multiple collapsible menu sections below. Each section has a title and expandable items with content areas. Use for documentation, help centers, knowledge bases, or organized content with categories.",
+    shell: "custom (Header + centered)",
+    blocks: ["Header", "MenuSection", "ContentDropzone"]
+  },
   "page-video-chat": {
     path: "/page-video-chat",
-    description: "Video conferencing interface with webcam, participants, and chat.",
+    description: "Video conferencing interface with large webcam preview area, participant list sidebar, video control bar (camera, mic, cast, leave), and optional chat panel. Use for video calls, telemedicine, virtual meetings, or live streaming.",
     shell: "custom (no shell)",
     blocks: ["WebcamPreview", "VideoChatControls", "ParticipantList", "ChatMessageList"]
   },
   "page-video-list": {
     path: "/page-video-list",
-    description: "Video content page with player and playlist sidebar.",
+    description: "Video content page with main video player area (title, metadata, description) and playlist sidebar showing video thumbnails. Use for course platforms, tutorial series, media libraries, or video-on-demand interfaces.",
     shell: "custom (no shell)",
     blocks: ["VideoContentSection", "VideoPlaylist", "YouTubePlayer"]
   }
@@ -21504,7 +22246,8 @@ var categoryMap = {
   "Form/Modal/Drawer": groupModalDrawerBlocks,
   "Video": videoBlocks,
   "Marketing": marketingBlocks,
-  "Pricing": pricingBlocks
+  "Pricing": pricingBlocks,
+  "UI Primitives": uiPrimitives
 };
 var allComponents = Object.entries(categoryMap).flatMap(
   ([category, registry2]) => Object.entries(registry2).map(([name, entry]) => ({
@@ -21512,6 +22255,8 @@ var allComponents = Object.entries(categoryMap).flatMap(
     category,
     path: entry.path,
     description: entry.description,
+    keywords: "keywords" in entry && Array.isArray(entry.keywords) ? [...entry.keywords] : [],
+    visualWeight: "visualWeight" in entry && typeof entry.visualWeight === "string" ? entry.visualWeight : "medium",
     props: entry.props
   }))
 );
@@ -21898,33 +22643,182 @@ var cssVariableCategories = [
 var patterns = [
   {
     name: "Dashboard with sidebar",
-    description: "Admin dashboard with collapsible sidebar navigation and data content area.",
-    components: ["DashboardShell", "StandardDataTable"],
-    example: '<DashboardShell navigation={sections}>\n  <StandardDataTable title="Users" data={rows} />\n</DashboardShell>'
+    description: "Admin dashboard with collapsible sidebar navigation and data content area. Composition rhythm: light KPI summary row at top (~100px, quick status scan), medium chart widgets in the middle (~300px, trend analysis), heavy data table at bottom (~400px+, detailed drill-down). This top-down density progression mirrors how users scan dashboards: overview first, then details.",
+    components: ["DashboardShell", "MetricCardsRow", "TwoColumnWidgets", "LineChartWidget", "DonutChartWidget", "StandardDataTable"],
+    example: '<DashboardShell navigation={sections}>\n  <ContentDropzone>\n    <MetricCardsRow metrics={kpis} columns={4} />\n    <TwoColumnWidgets>\n      <LineChartWidget label="Revenue" value="$12,345" />\n      <DonutChartWidget label="Categories" value="100%" />\n    </TwoColumnWidgets>\n    <StandardDataTable title="Recent Orders" data={rows} />\n  </ContentDropzone>\n</DashboardShell>'
   },
   {
     name: "Settings page",
-    description: "Account settings with tabbed sidebar navigation, profile editing, and list rows.",
+    description: "Account settings with tabbed sidebar navigation, profile editing, and list rows. Light visual weight throughout \u2014 settings pages are scanned vertically through uniform rows, so consistency matters more than visual variety here.",
     components: ["AccountSettingsShell", "SettingsListRow", "ProfileImageUploader"],
     example: '<AccountSettingsShell activeTab="profile">\n  <ProfileImageUploader />\n  <SettingsListRow label="Name" value="John" onEdit={...} />\n</AccountSettingsShell>'
   },
   {
     name: "Marketing landing",
-    description: "Marketing landing page with header, hero section, content blocks, and footer.",
-    components: ["Header", "HeroSection", "DestinationCards", "TestimonialCarousel", "FooterNavbar"],
-    example: '<>\n  <Header />\n  <HeroSection title="..." />\n  <DestinationCards />\n  <TestimonialCarousel />\n  <FooterNavbar />\n</>'
+    description: "Marketing landing page with clear visual rhythm. Opens with spacious hero (focal point, ~400px tall) \u2192 flows to medium-weight card grid (browsable content, ~350px) \u2192 light testimonials (social proof, ~250px) \u2192 compact CTA + footer (clear close, ~300px combined). The alternating density (spacious \u2192 medium \u2192 light \u2192 compact) creates natural scanning rhythm. Each section serves a distinct purpose in the conversion funnel.",
+    components: ["Header", "HeroSection", "DestinationCards", "TestimonialCarousel", "CtaBanner", "FooterNavbar"],
+    example: '<>\n  <Header />\n  <HeroSection title="..." />\n  <DestinationCards />\n  <TestimonialCarousel />\n  <CtaBanner title="..." buttonText="Get Started" />\n  <FooterNavbar />\n</>'
   },
   {
     name: "Multi-step wizard",
-    description: "Multi-step form flow with step tracker and navigation buttons.",
+    description: "Multi-step form flow with step tracker and navigation buttons. Light visual weight \u2014 the step tracker provides orientation (~60px) and the form content area is the single focus (~400px). Avoid adding sidebars or secondary content that competes with the form.",
     components: ["MultistepShell", "StepTracker", "FormGroup"],
     example: '<MultistepShell steps={steps} currentStep={1}>\n  <FormGroup title="Step 1" rows={formRows} />\n</MultistepShell>'
   },
   {
     name: "Messaging app",
-    description: "Chat interface with thread sidebar, message bubbles, and input area.",
+    description: "Chat interface with thread sidebar, message bubbles, and input area. Two-column layout: sidebar (~320px, medium density thread list) and conversation area (fills remaining width, variable density based on messages). The sidebar provides context while the conversation area is the primary focus.",
     components: ["MessengerSidebar", "ChatBubble", "ChatDateSeparator", "MessengerInput"],
     example: '<div className="flex">\n  <MessengerSidebar onSelectThread={...} />\n  <div>\n    <ChatDateSeparator date="Jan 25, 2024" />\n    <ChatBubble message={msg} />\n    <MessengerInput onSend={...} />\n  </div>\n</div>'
+  },
+  {
+    name: "Default page templates",
+    description: "Canvas base templates for common app pages. Use these by default unless the user specifies a different template or provides a reference design that significantly differs. Account settings \u2192 page-account, Admin portal \u2192 page-admin-portal, Login \u2192 page-login, Signup \u2192 page-login (adjust form fields), Password reset \u2192 page-reset-password.",
+    components: [
+      "AccountSettingsShell",
+      "DashboardShell",
+      "LoginBrandingPanel"
+    ],
+    example: '// Account settings\n<AccountSettingsShell activeTab="profile">...</AccountSettingsShell>\n\n// Admin portal\n<DashboardShell navigation={sections}>...</DashboardShell>\n\n// Login / Signup\n<LoginBrandingPanel>...</LoginBrandingPanel>'
+  },
+  {
+    name: "Displaying stats & metrics",
+    description: "When showing numeric stats (followers, ratings, revenue, etc.), always use an SDK component rather than hand-rolling number displays. Choose based on context: StatsCard for profile/sidebar stats in a bordered card, MetricCardsRow for dashboard KPIs with change indicators, MetricsSection for marketing pages with large hero numbers. If the exact layout doesn't match, import the closest component and customize \u2014 they encode typography scale, alignment, spacing, dividers, and responsive behavior that's hard to get right manually.",
+    components: ["StatsCard", "MetricCardsRow", "MetricsSection", "ProfileCard"],
+    example: '// Profile sidebar stats (bordered card)\n<StatsCard stats={[\n  { value: "24", label: "Listings" },\n  { value: "4.96", label: "Rating" },\n  { value: "342", label: "Reviews" },\n]} />\n\n// Dashboard KPIs (with change indicators)\n<MetricCardsRow metrics={[\n  { label: "Revenue", value: "$12,345", change: { value: "+12%", direction: "up" } },\n  { label: "Users", value: "1,234", change: { value: "+5%", direction: "up" } },\n]} columns={4} />\n\n// Marketing hero stats (large numbers with borders)\n<MetricsSection metrics={[\n  { value: "1,200+", label: "Team members" },\n  { value: "$22M", label: "In total funding" },\n]} />'
+  },
+  {
+    name: "Content page balance",
+    description: "Content and detail pages alternate between spacious visual sections and dense informational sections. Typical rhythm: banner/hero (spacious, ~200px) \u2192 profile or header info (medium, ~300px) \u2192 tabbed content or data (heavy, ~500px) \u2192 related items or cards (medium, ~300px). Break up heavy sections with TitleGroup headers to create scannable landmarks. Use ContentDropzone to enforce consistent 32px gaps between blocks.",
+    components: ["FlairBanner", "ProfileCard", "PillTabs", "StandardDataTable", "TitleGroup", "ContentDropzone"],
+    example: '<StandardPageShell showBanner bannerTitle="Explore">\n  <ContentDropzone>\n    {/* Spacious: banner + header */}\n    <ProfileCard name="Jane Doe" ... />\n    {/* Heavy: main content with scannable landmark */}\n    <div className="flex flex-col gap-[var(--spacing-lg)]">\n      <TitleGroup title="Activity" />\n      <ActivityFeed items={activities} />\n    </div>\n    {/* Medium: secondary content */}\n    <div className="flex flex-col gap-[var(--spacing-lg)]">\n      <TitleGroup title="Reviews" />\n      <ReviewsTable reviews={reviews} />\n    </div>\n  </ContentDropzone>\n</StandardPageShell>'
+  },
+  {
+    name: "Product/listing detail page",
+    description: "Detail pages use a two-column layout with visual content on top and structured info below. Typical rhythm: full-width image gallery (spacious, ~400px) \u2192 two-column layout with main content left (heavy, descriptions/reviews) and sidebar right (medium, reservation card/order summary ~300px). The gallery establishes visual context, then the two-column split provides scannable details alongside a persistent action area.",
+    components: ["Header", "TileImageGallery", "ContentDropzone", "ReservationCard", "OrderSummarySidebar", "BottomActionBar"],
+    example: '<>\n  <Header />\n  <TileImageGallery images={images} />\n  <div className="flex gap-[var(--spacing-4xl)] max-w-[1240px] mx-auto">\n    <div className="flex-1">\n      <ContentDropzone>\n        {/* Main content blocks */}\n      </ContentDropzone>\n    </div>\n    <div className="w-[380px]">\n      <ReservationCard />\n    </div>\n  </div>\n</>'
+  }
+];
+
+// src/data/design-rules.ts
+var designRules = [
+  {
+    id: "stats-numbers",
+    trigger: ["stat", "stats", "number", "count", "metric", "kpi", "followers", "rating", "reviews", "listings", "response rate"],
+    warning: "Large numbers displayed in a bare flex row without a card container, dividers, or visual structure look unpolished. Raw inline styles for font sizes bypass the typography token system.",
+    recommendation: "Use an SDK stat/metric component instead of hand-rolling number displays. Choose based on context: StatsCard for profile or sidebar stats in a bordered card, MetricCardsRow for dashboard KPIs with change indicators (up/down arrows), MetricsSection for marketing pages with large hero numbers and left-border separators.",
+    components: ["StatsCard", "MetricCardsRow", "MetricsSection", "ProfileCard"],
+    modificationHint: "StatsCard wraps content in a bordered card \u2014 pass className to override border/background if embedding stats inside an existing card. MetricCardsRow supports 2-4 columns and stacks responsively. MetricsSection uses h1-scale typography automatically."
+  },
+  {
+    id: "profile-page",
+    trigger: ["profile", "user profile", "host profile", "author", "member"],
+    warning: "Building profile layouts from scratch often results in misaligned avatars, inconsistent stat displays, and missing responsive behavior.",
+    recommendation: "Use ProfileCard for a complete profile layout with avatar, stats row, bio, tags, and social links. Use StatsCard for a standalone stats row. Use GradientBanner or FlairBanner for profile header banners.",
+    components: ["ProfileCard", "StatsCard", "GradientBanner", "FlairBanner", "ProfileImageUploader", "SidebarProfileCard"],
+    modificationHint: "ProfileCard includes a built-in stats row \u2014 if you only need stats, extract the StatsCard instead. SidebarProfileCard is a compact variant for sidebar placement."
+  },
+  {
+    id: "dashboard-metrics",
+    trigger: ["dashboard", "admin", "analytics", "revenue", "overview", "kpi"],
+    warning: "Dashboard metric displays need consistent card containers, change indicators, and responsive grid behavior that's difficult to achieve with ad-hoc layouts.",
+    recommendation: "Use MetricCardsRow for the KPI summary row at the top of dashboards. Pair with LineChartWidget, DonutChartWidget, MetricListCard, or ProgressMetricCard for detailed metric views. Use TwoColumnWidgets to arrange widget pairs side by side.",
+    components: ["MetricCardsRow", "MetricCard", "LineChartWidget", "DonutChartWidget", "MetricListCard", "ProgressMetricCard", "TwoColumnWidgets", "DashboardHeader"],
+    modificationHint: "MetricCardsRow supports 2, 3, or 4 columns via the columns prop. All chart widgets update colors automatically from CSS variables. Use GraphMetricTilesDemo as a complete reference layout."
+  },
+  {
+    id: "reviews-ratings",
+    trigger: ["review", "reviews", "rating", "ratings", "testimonial", "feedback", "star", "guest reviews", "customer reviews"],
+    warning: "Hand-rolled review layouts often miss consistent star rendering, proper avatar alignment, or expandable text behavior.",
+    recommendation: "Use ReviewsTable for a sortable/filterable list of user reviews with star ratings and expandable text. Use TestimonialCarousel for a rotating display of highlighted testimonials on marketing pages.",
+    components: ["ReviewsTable", "TestimonialCarousel"],
+    modificationHint: "ReviewsTable expects `reviewText` (not `text`) and `avatarUrl` (not `avatar`). Map your data accordingly. Pass `sortOptions={[]}` and empty `actionButtonText` to hide controls for display-only contexts. Star ratings use --canvas-primary color automatically."
+  },
+  {
+    id: "data-tables",
+    trigger: ["table", "list", "directory", "inventory", "orders", "users"],
+    warning: "Building tables from scratch misses sortable columns, responsive behavior, avatar-enhanced rows, and row action menus.",
+    recommendation: "Use StandardDataTable for typical data displays. Use FixedColumnDataTable when the first column needs to stay visible during horizontal scroll. Use NestedDataTable for hierarchical data.",
+    components: ["StandardDataTable", "FixedColumnDataTable", "NestedDataTable", "Pagination"],
+    modificationHint: "All data tables include header with result count, sort/filter dropdowns, and primary action button. Pass appropriate sortOptions and filterOptions arrays."
+  },
+  {
+    id: "typography-inline",
+    trigger: ["font", "fontsize", "fontweight", "text", "heading", "title", "label"],
+    warning: "Using raw fontSize/fontWeight/fontFamily inline styles bypasses the design token system and creates inconsistent text rendering across themes.",
+    recommendation: "Use the Typography component with variant prop (h1-h6, body-xl, body-l, body-m, body-s, body-xs) instead of inline style objects. Typography automatically applies the correct font family, size, weight, and line height from design tokens.",
+    components: ["Typography"],
+    modificationHint: "Typography supports as prop for semantic HTML elements (e.g., as='h1', as='span') and color prop ('default' | 'muted'). Combine with className for additional Tailwind utilities."
+  },
+  {
+    id: "forms",
+    trigger: ["form", "input", "settings", "edit", "create", "signup", "register"],
+    warning: "Hand-rolling form layouts misses consistent field sizing, label alignment, validation states, and responsive stacking.",
+    recommendation: "Use FormGroup for structured form layouts with configurable field types (text, textarea, select, date, checkbox, radio, multiselect, slider, file upload). Use SettingsListRow for read/edit settings displays.",
+    components: ["FormGroup", "SettingsListRow", "ProfileImageUploader"],
+    modificationHint: "FormGroup supports inputSize prop ('sm' | 'default' | 'lg') for consistent field heights. Pass showHeader/showFooter=false to hide the built-in header or footer."
+  },
+  {
+    id: "navigation-layout",
+    trigger: ["nav", "navigation", "sidebar", "menu", "tabs"],
+    warning: "Building navigation from scratch often results in inconsistent hover states, missing mobile responsive behavior, and accessibility issues.",
+    recommendation: "Use a layout shell (DashboardShell, IconSidebarShell, AccountSettingsShell) for page-level navigation. Use PillTabs or PageHeaderSection for content-level tab navigation. Use MobileBottomNav for mobile app-style navigation.",
+    components: ["DashboardShell", "IconSidebarShell", "AccountSettingsShell", "PillTabs", "PageHeaderSection", "MobileBottomNav", "Header"]
+  },
+  {
+    id: "image-gallery",
+    trigger: ["gallery", "images", "photos", "listing", "property", "product images", "hero image"],
+    warning: "Building image galleries from scratch misses proper aspect ratio handling, responsive grid behavior, and view-all overlay controls. Leaving image props empty results in broken or generic placeholders.",
+    recommendation: "Use TileImageGallery for hero gallery layouts (1 large + 4 grid). Always pass custom images via the images prop that match the content context.",
+    components: ["TileImageGallery", "SlideshowGridTiles", "LoginBrandingPanel"],
+    modificationHint: "TileImageGallery accepts { id, src, alt }[]. First image is the hero (57% width), next 4 fill a 2x2 grid. Use Unsplash with w/h/fit=crop params for optimal loading."
+  },
+  {
+    id: "login-branding",
+    trigger: ["login", "signup", "sign in", "authentication", "branding panel"],
+    warning: "LoginBrandingPanel defaults to /brand-assets/bg.jpg which may not exist in consumer projects, resulting in a blank panel.",
+    recommendation: "Always pass a backgroundImage prop to LoginBrandingPanel with a relevant image. Choose an image that matches the app's domain.",
+    components: ["LoginBrandingPanel"],
+    modificationHint: "Use overlayOpacity prop (0-1, default 0.7) to control how much the flair color tints the image. Lower values show more of the image."
+  },
+  {
+    id: "data-display-format",
+    trigger: ["listings", "products", "portfolio", "properties", "catalog", "grid", "tiles", "cards grid"],
+    warning: "Using StandardDataTable for visual content (properties, products) squeezes images into small row avatars. This wastes the visual impact of the content.",
+    recommendation: "Use GridTilesList when items have prominent images (property photos, product images, portfolio pieces). Use StandardDataTable for text-heavy data (user lists, transactions, logs). The tile format with large images is always more appropriate for visual catalogs.",
+    components: ["GridTilesList", "StandardDataTable", "FixedColumnDataTable"],
+    modificationHint: "GridTilesList supports 2-5 columns via the columns prop. Items need { id, imageUrl, title, rating, location, price, priceUnit?, tag? }. Use columns={3} for dashboard contexts with sidebars."
+  },
+  {
+    id: "layout-rhythm",
+    trigger: ["page", "layout", "compose", "build page", "mockup", "template", "full page"],
+    warning: "Stacking multiple heavy blocks (data tables, feeds, large forms, galleries) without visual breaks creates a wall of content that's hard to scan. Users lose their place and the page feels overwhelming.",
+    recommendation: "Vary visual weight across the page: alternate heavy blocks (data tables, feeds, forms) with lighter elements (MetricCardsRow, PillTabs, TitleGroup section headers) or spacer elements (FlairBanner, GradientBanner). A good rhythm is: light \u2192 heavy \u2192 light \u2192 heavy. Use ContentDropzone to enforce consistent 32px gaps between blocks.",
+    components: ["ContentDropzone", "TitleGroup", "FlairBanner", "GradientBanner", "MetricCardsRow", "PillTabs"],
+    modificationHint: "ContentDropzone handles inter-block spacing (32px) automatically. For extra breathing room between major sections, wrap groups of related blocks together as single ContentDropzone children. TitleGroup adds scannable section landmarks between heavy content."
+  },
+  {
+    id: "above-the-fold",
+    trigger: ["landing", "homepage", "marketing", "hero", "landing page", "home page"],
+    warning: "The first ~600px of a page (above the fold) should establish clear visual hierarchy with one dominant focal point. Starting with dense data blocks or multiple competing elements makes the page feel cluttered and unclear.",
+    recommendation: "Start with a spacer-weight element (HeroSection, HeroDarkWithImage, FlairBanner, GradientBanner) that establishes a clear focal point, followed by a light-to-medium block. Save heavy blocks (data tables, feeds) for below the fold where users scroll intentionally.",
+    components: ["HeroSection", "HeroDarkWithImage", "HeroDarkCentered", "HeroFullwidthImage", "FlairBanner", "GradientBanner", "CenteredHero"]
+  },
+  {
+    id: "page-ending",
+    trigger: ["footer", "page end", "bottom", "cta", "call to action", "complete page"],
+    warning: "Pages that end abruptly after a heavy content block (data table, feed, form) feel incomplete and unprofessional. Users need a clear signal that they've reached the end of content.",
+    recommendation: "End marketing pages with CtaBanner \u2192 FooterNavbar. End app pages with Pagination below data tables or a clear content boundary. Don't end a page with a data table or feed that just cuts off.",
+    components: ["CtaBanner", "FooterNavbar", "Pagination"]
+  },
+  {
+    id: "visual-monotony",
+    trigger: ["cards", "grid", "multiple sections", "several blocks", "many sections", "content sections"],
+    warning: "Using the same component type repeatedly (e.g., three card grids in a row, or multiple same-sized sections) creates visual monotony even if the content differs. The page looks repetitive and lacks scanning landmarks.",
+    recommendation: "Mix component shapes: alternate card grids with text sections, image-heavy blocks with data-focused blocks. Use different column counts (3-col cards \u2192 full-width feature \u2192 4-col grid) to vary visual texture. Insert FeatureWithImage sections between card grids to break up the pattern.",
+    components: ["GridTilesList", "FeatureWithImage", "ContentWithImage", "BlogCards", "GallerySection"],
+    modificationHint: "FeatureWithImage supports imagePosition='left'|'right' \u2014 alternate between left and right for visual variety when stacking multiple feature sections."
   }
 ];
 
@@ -22133,7 +23027,7 @@ server.tool(
 );
 server.tool(
   "get_component",
-  "Returns detailed info for a single component by name, including import path, description, and props.",
+  "Returns detailed info for a single component by name, including import path, description, props, visual weight, and keywords.",
   { name: external_exports.string().describe("Component name (case-insensitive)") },
   async ({ name }) => {
     const comp = componentsByName.get(name.toLowerCase());
@@ -22145,6 +23039,8 @@ server.tool(
       `**Category:** ${comp.category}`,
       `**Import:** \`import { ${comp.name} } from "${comp.path}"\``,
       `**Description:** ${comp.description}`,
+      `**Visual Weight:** ${comp.visualWeight}`,
+      ...comp.keywords.length ? [`**Keywords:** ${comp.keywords.join(", ")}`] : [],
       "",
       "**Props:**",
       ...comp.props.map((p) => `- \`${p}\``)
@@ -22152,6 +23048,38 @@ server.tool(
     return { content: [{ type: "text", text }] };
   }
 );
+server.tool(
+  "suggest_component",
+  "Suggests up to 5 components matching a natural language query. Searches component names, descriptions, and keywords. Use when you know what you need but not the component name.",
+  { query: external_exports.string().describe("What you're looking for (e.g., 'audit log', 'confirmation dialog', 'stat cards')") },
+  async ({ query }) => {
+    const queryWords = query.toLowerCase().split(/\s+/);
+    const scored = allComponents.map((c) => {
+      const haystack = [c.name, c.description, ...c.keywords].join(" ").toLowerCase();
+      let score = 0;
+      for (const kw of queryWords) {
+        if (haystack.includes(kw)) score += 1;
+        if (c.name.toLowerCase().includes(kw)) score += 2;
+        if (c.keywords.some((k) => k.includes(kw))) score += 1;
+      }
+      return { component: c, score };
+    });
+    const top = scored.filter((s) => s.score > 0).sort((a, b) => b.score - a.score).slice(0, 5);
+    if (top.length === 0) {
+      return { content: [{ type: "text", text: "No matching components found. Try different terms or use list_components to browse all components." }] };
+    }
+    const lines = top.map(
+      ({ component: c, score }) => [
+        `## ${c.name} (${c.category})`,
+        `**Import:** \`import { ${c.name} } from "${c.path}"\``,
+        `**Visual Weight:** ${c.visualWeight}`,
+        `**Description:** ${c.description}`,
+        ""
+      ].join("\n")
+    );
+    return { content: [{ type: "text", text: lines.join("\n") }] };
+  }
+);
 server.tool(
   "suggest_template",
   "Suggests up to 3 page templates matching a description. Uses keyword matching against template names, descriptions, shells, and blocks.",
@@ -22194,7 +23122,7 @@ server.tool(
 );
 server.tool(
   "list_patterns",
-  "Lists common usage patterns showing how to combine components for typical app layouts.",
+  "Lists common usage patterns showing how to combine components for typical app layouts. Includes spatial composition guidance.",
   {},
   async () => {
     const lines = patterns.map(
@@ -22263,5 +23191,123 @@ server.tool(
     return { content: [{ type: "text", text }] };
   }
 );
+server.tool(
+  "review_design",
+  "Reviews a page or component layout description for common anti-patterns and suggests SDK components. Optionally validates composition by checking the visual weight sequence of an ordered block list. Use before finalizing layouts to catch issues like uncontained numbers, missing visual hierarchy, poor composition rhythm, or hand-rolled patterns that have SDK equivalents.",
+  {
+    description: external_exports.string().describe("Description of what you're building (e.g., 'profile page with user stats showing 24 listings, 4.96 rating')"),
+    blockSequence: external_exports.array(external_exports.string()).optional().describe("Ordered list of block component names top-to-bottom for composition review (e.g., ['HeroSection', 'DestinationCards', 'CtaBanner', 'FooterNavbar'])")
+  },
+  async ({ description, blockSequence }) => {
+    const lower = description.toLowerCase();
+    const matches = designRules.filter(
+      (rule) => rule.trigger.some((kw) => lower.includes(kw))
+    );
+    const resultSections = [];
+    if (matches.length > 0) {
+      const ruleSections = matches.map(
+        (rule) => [
+          `## ${rule.id}`,
+          "",
+          `**Warning:** ${rule.warning}`,
+          "",
+          `**Recommendation:** ${rule.recommendation}`,
+          "",
+          `**Components:** ${rule.components.join(", ")}`,
+          ...rule.modificationHint ? ["", `**Customization tip:** ${rule.modificationHint}`] : [],
+          ""
+        ].join("\n")
+      );
+      resultSections.push(...ruleSections);
+    }
+    if (blockSequence && blockSequence.length > 0) {
+      const compositionIssues = [];
+      const weights = blockSequence.map((name) => {
+        const comp = componentsByName.get(name.toLowerCase());
+        return {
+          name,
+          weight: comp?.visualWeight ?? "medium"
+        };
+      });
+      for (let i = 0; i < weights.length - 1; i++) {
+        if (weights[i].weight === "heavy" && weights[i + 1].weight === "heavy") {
+          compositionIssues.push(
+            `Adjacent heavy blocks: **${weights[i].name}** \u2192 **${weights[i + 1].name}**. Consider inserting a light element (TitleGroup, MetricCardsRow, PillTabs) or spacer (FlairBanner, GradientBanner) between them for visual breathing room.`
+          );
+        }
+      }
+      if (weights.length > 0 && weights[0].weight === "heavy") {
+        compositionIssues.push(
+          `Page opens with heavy block **${weights[0].name}**. Consider starting with a spacer (HeroSection, FlairBanner) or light element (MetricCardsRow, PageHeaderSection) to establish a clear focal point above the fold.`
+        );
+      }
+      if (weights.length > 0) {
+        const last = weights[weights.length - 1];
+        if (last.weight === "heavy") {
+          compositionIssues.push(
+            `Page ends with heavy block **${last.name}**. Consider adding a clear closing element: Pagination below data tables, CtaBanner \u2192 FooterNavbar for marketing pages, or a light summary section.`
+          );
+        }
+      }
+      for (let i = 0; i < weights.length - 2; i++) {
+        if (weights[i].weight === weights[i + 1].weight && weights[i + 1].weight === weights[i + 2].weight && weights[i].weight !== "light") {
+          compositionIssues.push(
+            `Visual monotony: 3 consecutive ${weights[i].weight}-weight blocks (${weights[i].name} \u2192 ${weights[i + 1].name} \u2192 ${weights[i + 2].name}). Vary visual weight to create scanning rhythm.`
+          );
+        }
+      }
+      const heavyCount = weights.filter((w) => w.weight === "heavy").length;
+      if (weights.length >= 4 && heavyCount / weights.length > 0.6) {
+        compositionIssues.push(
+          `Overall density is high: ${heavyCount} of ${weights.length} blocks are heavy-weight. Consider replacing some with lighter alternatives or adding spacer/light elements to improve scannability.`
+        );
+      }
+      const weightSummary = weights.map((w) => `${w.name} (${w.weight})`).join(" \u2192 ");
+      if (compositionIssues.length > 0) {
+        resultSections.push(
+          [
+            "## Composition Review",
+            "",
+            `**Block sequence:** ${weightSummary}`,
+            "",
+            `Found ${compositionIssues.length} composition issue(s):`,
+            "",
+            ...compositionIssues.map((issue2, i) => `${i + 1}. ${issue2}`),
+            ""
+          ].join("\n")
+        );
+      } else {
+        resultSections.push(
+          [
+            "## Composition Review",
+            "",
+            `**Block sequence:** ${weightSummary}`,
+            "",
+            "Composition looks balanced. The visual weight progression creates good scanning rhythm.",
+            ""
+          ].join("\n")
+        );
+      }
+    }
+    if (resultSections.length === 0) {
+      return {
+        content: [{
+          type: "text",
+          text: "No specific design guidance found for this description. General tips:\n- Use SDK components instead of hand-rolling common patterns\n- Use the Typography component instead of inline font styles\n- Wrap numeric displays in card containers with proper visual structure\n- Check list_components for available components before building custom layouts\n- Vary visual weight across the page (light \u2192 heavy \u2192 light) for good scanning rhythm"
+        }]
+      };
+    }
+    return {
+      content: [{
+        type: "text",
+        text: `# Design Review
+
+Found ${resultSections.length} guideline(s) for your layout:
+
+${resultSections.join("\n---\n\n")}`
+      }]
+    };
+  }
+);
 var transport = new StdioServerTransport();
 await server.connect(transport);