canvas-ui-sdk 0.3.23 → 4.0.0

package/registry/index.json

@@ -4,62 +4,177 @@
     {
       "name": "account-settings-shell",
       "type": "registry: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"
     },
     {
       "name": "activity-feed",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "avatar",
       "type": "registry:ui",
-      "description": ""
+      "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"
     },
     {
       "name": "blog-cards",
       "type": "registry:block",
-      "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"
+    },
+    {
+      "name": "bottom-action-bar",
+      "type": "registry:block",
+      "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"
     },
     {
       "name": "bottom-input-chat-widget",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "button",
       "type": "registry:ui",
-      "description": ""
+      "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"
     },
     {
       "name": "calendar",
       "type": "registry:ui",
-      "description": ""
+      "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"
     },
     {
       "name": "category-grid",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "centered-hero",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "chat-message",
       "type": "registry:block",
-      "description": ""
+      "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"
     },
     {
       "name": "checkbox",
       "type": "registry:ui",
-      "description": ""
+      "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"
     },
     {
       "name": "circular-progress-bar-list",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "component-search",
@@ -69,37 +184,95 @@
     {
       "name": "confirmation-popup",
       "type": "registry:block",
-      "description": ""
+      "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"
     },
     {
       "name": "contact-form-popup",
       "type": "registry:block",
-      "description": ""
+      "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"
     },
     {
       "name": "content-dropzone",
       "type": "registry:block",
-      "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."
+      "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"
     },
     {
       "name": "content-with-image",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "core-values-grid",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "credit-card-display",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "cta-banner",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "custom-component-helper",
@@ -109,12 +282,31 @@
     {
       "name": "dashboard-shell",
       "type": "registry: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"
     },
     {
       "name": "date-input",
       "type": "registry:ui",
-      "description": ""
+      "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"
     },
     {
       "name": "demo-avatars",
@@ -124,117 +316,336 @@
     {
       "name": "destination-cards",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "detail-drawer",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "details-popup",
       "type": "registry:block",
-      "description": ""
+      "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"
     },
     {
       "name": "dialog",
       "type": "registry:ui",
-      "description": ""
+      "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"
     },
     {
       "name": "double-sidebar",
       "type": "registry: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"
     },
     {
       "name": "double-sidebar-shell",
       "type": "registry: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"
     },
     {
       "name": "dropdown-menu",
       "type": "registry:ui",
-      "description": ""
+      "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"
+    },
+    {
+      "name": "editable-list",
+      "type": "registry:block",
+      "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"
     },
     {
       "name": "empty-state",
       "type": "registry:block",
-      "description": ""
+      "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"
     },
     {
       "name": "faq-accordion",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "faqs-table",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "feature-with-image",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "featured-news-cards",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "featured-places",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "features-comparison",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "feedback-popup",
       "type": "registry:block",
-      "description": ""
+      "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"
     },
     {
       "name": "file-uploader",
       "type": "registry:ui",
-      "description": ""
+      "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"
     },
     {
       "name": "filter-popover",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "fixed-column-data-table",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "flair-banner",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "footer-navbar",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "form-group",
       "type": "registry:block",
-      "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"
+    },
+    {
+      "name": "form-popup",
+      "type": "registry:block",
+      "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"
     },
     {
       "name": "gallery-section",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "gradient-banner",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "graph-metric-tiles",
@@ -244,177 +655,522 @@
     {
       "name": "grid-tiles-list",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "header",
       "type": "registry: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"
     },
     {
       "name": "hero-dark-centered",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "hero-dark-with-image",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "hero-fullwidth-image",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "hero-section",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "how-it-works",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "icon-sidebar",
       "type": "registry: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"
     },
     {
       "name": "icon-sidebar-shell",
       "type": "registry: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"
     },
     {
       "name": "image-feed-with-nested-comments",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "image-popup",
       "type": "registry:block",
-      "description": ""
+      "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"
     },
     {
       "name": "image-uploader",
       "type": "registry:ui",
-      "description": ""
+      "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"
     },
     {
       "name": "input",
       "type": "registry:ui",
-      "description": ""
+      "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"
     },
     {
       "name": "invoice-popup",
       "type": "registry:block",
-      "description": ""
+      "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"
     },
     {
       "name": "label",
       "type": "registry:ui",
-      "description": ""
+      "description": "Themed form label associated with an input. Built on Radix Label. Use for labeling form fields.",
+      "keywords": [
+        "label",
+        "form",
+        "field",
+        "text"
+      ],
+      "visualWeight": "light"
     },
     {
       "name": "large-image-labels-list",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "line-tabs",
       "type": "registry:ui",
-      "description": ""
+      "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"
+    },
+    {
+      "name": "list-popup",
+      "type": "registry:block",
+      "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"
     },
     {
       "name": "loader",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "login-branding-panel",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "menu-section",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "menufocus-template",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "messenger-sidebar",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "metrics-section",
       "type": "registry:block",
-      "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 — 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"
     },
     {
       "name": "mobile-bottom-nav",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "mobile-menu-shell",
       "type": "registry: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"
     },
     {
       "name": "monthly-calendar-widget",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "multiselect-checkbox-field",
       "type": "registry:ui",
-      "description": ""
+      "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"
     },
     {
       "name": "multiselect-tags",
       "type": "registry:ui",
-      "description": ""
+      "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"
+    },
+    {
+      "name": "multistep-form-popup",
+      "type": "registry:block",
+      "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"
     },
     {
       "name": "multistep-progressbar-shell",
       "type": "registry:layout",
-      "description": ""
+      "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"
     },
     {
       "name": "multistep-shell",
       "type": "registry: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"
     },
     {
       "name": "multistep-sidebar-shell",
       "type": "registry: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"
     },
     {
       "name": "nested-comments-table",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "nested-data-table",
       "type": "registry:block",
-      "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"
+    },
+    {
+      "name": "nps-survey-popup",
+      "type": "registry:block",
+      "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"
     },
     {
       "name": "office-locations",
       "type": "registry:block",
-      "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"
+    },
+    {
+      "name": "order-summary-sidebar",
+      "type": "registry:block",
+      "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"
     },
     {
       "name": "page-header-section",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "page-previews",
@@ -424,72 +1180,203 @@
     {
       "name": "pagination",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "participant-list",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "persona-card",
       "type": "registry:block",
-      "description": ""
+      "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"
+    },
+    {
+      "name": "personalize-feed-popup",
+      "type": "registry:block",
+      "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"
     },
     {
       "name": "pill-tabs",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "place-detail-panel",
       "type": "registry:block",
-      "description": ""
+      "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"
     },
     {
       "name": "popover",
       "type": "registry:ui",
-      "description": ""
+      "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"
     },
     {
       "name": "pricing-cards",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "pricing-cta",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "pricing-plans-popup",
       "type": "registry:block",
-      "description": ""
+      "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"
     },
     {
       "name": "profile-card",
       "type": "registry:block",
-      "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 — 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"
     },
     {
       "name": "profile-grid-tiles-list",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "profile-image-uploader",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "profile-info-cards",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "progress-bar",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "project-context-shell",
@@ -504,27 +1391,82 @@
     {
       "name": "purchase-confirmation-popup",
       "type": "registry:block",
-      "description": ""
+      "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"
     },
     {
       "name": "radio-group",
       "type": "registry:ui",
-      "description": ""
+      "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"
     },
     {
       "name": "range-input",
       "type": "registry:ui",
-      "description": ""
+      "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"
+    },
+    {
+      "name": "reservation-card",
+      "type": "registry:block",
+      "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"
     },
     {
       "name": "reviews-grid",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "reviews-table",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "screen-flowchart",
@@ -544,202 +1486,565 @@
     {
       "name": "scroll-area",
       "type": "registry:ui",
-      "description": ""
+      "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"
     },
     {
       "name": "search-bar",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "search-bar-shell",
       "type": "registry: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"
     },
     {
       "name": "search-sidebar",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "searchbox",
       "type": "registry:ui",
-      "description": ""
+      "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"
     },
     {
       "name": "select",
       "type": "registry:ui",
-      "description": ""
+      "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"
     },
     {
       "name": "selectable-pills",
       "type": "registry:ui",
-      "description": ""
+      "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"
     },
     {
       "name": "separator",
       "type": "registry:ui",
-      "description": ""
+      "description": "Horizontal or vertical separator line. Built on Radix Separator. Use for visually dividing sections of content.",
+      "keywords": [
+        "separator",
+        "divider",
+        "line",
+        "hr"
+      ],
+      "visualWeight": "light"
     },
     {
       "name": "settings-list-row",
       "type": "registry:block",
-      "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"
+    },
+    {
+      "name": "share-project-popup",
+      "type": "registry:block",
+      "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"
     },
     {
       "name": "sheet",
       "type": "registry:ui",
-      "description": ""
+      "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"
     },
     {
       "name": "sidebar",
       "type": "registry:ui",
-      "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"
     },
     {
       "name": "sidebar",
       "type": "registry: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"
     },
     {
       "name": "sidebar-cards",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "sidebar-nav",
       "type": "registry: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"
     },
     {
       "name": "sidebar-profile-card",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "skeleton",
       "type": "registry:ui",
-      "description": ""
+      "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"
     },
     {
       "name": "slider",
       "type": "registry:ui",
-      "description": ""
+      "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"
     },
     {
       "name": "slideshow-grid-tiles",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "slideshow-popup",
       "type": "registry:block",
-      "description": ""
+      "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"
+    },
+    {
+      "name": "small-edit-popup",
+      "type": "registry:block",
+      "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"
     },
     {
       "name": "social-feed",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "social-proof",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "standard-data-table",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "standard-list-with-image",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "standard-page-shell",
       "type": "registry: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"
     },
     {
       "name": "step-tracker",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "store-location-map",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "switch",
       "type": "registry:ui",
-      "description": ""
+      "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"
     },
     {
       "name": "tabs",
       "type": "registry:ui",
-      "description": ""
+      "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"
     },
     {
       "name": "team-cards-grid",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "team-circular-grid",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "terms-of-service-popup",
       "type": "registry:block",
-      "description": ""
+      "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"
     },
     {
       "name": "testimonial-carousel",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "text-input",
       "type": "registry:ui",
-      "description": ""
+      "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"
     },
     {
       "name": "textarea",
       "type": "registry:ui",
-      "description": ""
+      "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"
+    },
+    {
+      "name": "tile-image-gallery",
+      "type": "registry:block",
+      "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"
     },
     {
       "name": "title-group",
       "type": "registry:block",
-      "description": ""
+      "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 — 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"
     },
     {
       "name": "tooltip",
       "type": "registry:ui",
-      "description": ""
+      "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"
     },
     {
       "name": "typography",
       "type": "registry:ui",
-      "description": ""
+      "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"
     },
     {
       "name": "upvoting-posts-table",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "use-css-variable-sync",
       "type": "registry:hook",
-      "description": ""
+      "description": "React hook that synchronizes CSS custom properties (design tokens) with a JavaScript theme object. Applies theme overrides by setting CSS variables on a target element. Use for runtime theme switching or dynamic theming.",
+      "keywords": [
+        "hook",
+        "css",
+        "variables",
+        "theme",
+        "sync",
+        "tokens"
+      ],
+      "visualWeight": "light"
     },
     {
       "name": "use-mobile",
       "type": "registry:hook",
-      "description": ""
+      "description": "React hook that returns a boolean indicating if the viewport is mobile-sized (below 768px). Updates on window resize. Use for responsive behavior in components.",
+      "keywords": [
+        "hook",
+        "mobile",
+        "responsive",
+        "breakpoint",
+        "viewport"
+      ],
+      "visualWeight": "light"
     },
     {
       "name": "utils",
@@ -749,47 +2054,121 @@
     {
       "name": "vertical-how-it-works",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "vertical-multistep-shell",
       "type": "registry: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"
     },
     {
       "name": "vertical-step-tracker",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "video-chat-controls",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "video-content-section",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "video-playlist",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "video-popup",
       "type": "registry:block",
-      "description": ""
+      "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"
     },
     {
       "name": "view-profile-popup",
       "type": "registry:block",
-      "description": ""
+      "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"
     },
     {
       "name": "webcam-preview",
       "type": "registry:block",
-      "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"
     },
     {
       "name": "youtube-player",