[
  { "need": "Button", "component": "GnButton", "props": ["variant", "size", "icon", "loading", "disabled"], "useWhen": "Any clickable command or submit action" },
  { "need": "Icon-only button", "component": "GnIconButton", "props": ["icon", "label", "size"], "useWhen": "Action that shows only an icon (always pass `label` for accessibility)" },
  { "need": "Copy button", "component": "GnCopyButton", "props": ["text", "icon", "successIcon", "duration", "label", "size"], "useWhen": "Copy-to-clipboard action with built-in success feedback" },
  { "need": "Status label", "component": "GnBadge", "props": ["variant", "outline"], "useWhen": "Small colored status text (active, pending, failed) — never a hand-styled span" },
  { "need": "Message block", "component": "GnAlert", "props": ["variant"], "useWhen": "Inline info/warning/error message inside page content" },
  { "need": "Card / panel", "component": "GnCard", "props": ["title (slot)", "footer (slot)"], "useWhen": "Framed content block with optional title and footer" },
  { "need": "Horizontal card", "component": "GnHorizontalCard", "props": ["image", "title", "titleHref", "icon", "footer (slot)"], "useWhen": "Media-left preview card (image + linked title)" },
  { "need": "Login card", "component": "GnLoginCard", "props": ["title", "logoIcon", "usernameLabel", "passwordLabel", "rememberMe", "submitText", "error", "forgotHref", "signupHref"], "useWhen": "Username/password sign-in form" },
  { "need": "User card", "component": "GnUserCard", "props": ["name", "email", "role", "avatar", "href", "compact", "actions"], "useWhen": "Person or account profile block with avatar, email and role" },
  { "need": "Page title bar", "component": "GnPageHeader", "props": ["kicker", "title", "subtitle", "meta", "actions (slot)"], "useWhen": "Screen-level title with kicker, subtitle, meta and action buttons" },
  { "need": "Text field", "component": "GnInput", "props": ["v-model", "label", "icon", "state", "help"], "useWhen": "Single-line text input with label, icon and validation state" },
  { "need": "Textarea", "component": "GnTextarea", "props": ["v-model", "label", "state", "help"], "useWhen": "Multiline text input" },
  { "need": "Select dropdown", "component": "GnSelect", "props": ["v-model", "label", "options"], "useWhen": "Choose one option from a short list via native dropdown" },
  { "need": "Checkbox", "component": "GnCheckbox", "props": ["v-model", "label", "disabled"], "useWhen": "Boolean opt-in/opt-out choice" },
  { "need": "Toggle switch", "component": "GnSwitch", "props": ["v-model", "label", "disabled"], "useWhen": "Instant on/off setting toggle" },
  { "need": "Radio", "component": "GnRadio / GnRadioGroup", "props": ["v-model", "options"], "useWhen": "Single choice from a small, fully visible option set" },
  { "need": "Range slider", "component": "GnRange", "props": ["v-model", "label", "min", "max"], "useWhen": "Numeric value picked on a min–max scale" },
  { "need": "File upload", "component": "GnFileUpload", "props": ["v-model", "badge", "multiple", "accept"], "useWhen": "File picker with previews; it owns preview object URLs" },
  { "need": "Searchable select", "component": "GnCombobox", "props": ["v-model", "label", "options", "placeholder"], "useWhen": "Choose one option from a large or filterable list" },
  { "need": "Tag / multi-value input", "component": "GnTagInput", "props": ["v-model", "label", "placeholder", "separator", "unique", "maxItems"], "useWhen": "Enter multiple free-form values as chips" },
  { "need": "Tabs", "component": "GnTabs", "props": ["v-model", "items"], "useWhen": "Switch between views within one page" },
  { "need": "Router tabs", "component": "GnRouterTabs", "props": ["`items` (with `to`)", "activeMatch"], "useWhen": "Tabs mapped to vue-router routes" },
  { "need": "Accordion", "component": "GnAccordion", "props": ["items", "v-model", "multiple"], "useWhen": "Collapsible disclosure groups" },
  { "need": "Modal dialog", "component": "GnModal", "props": ["v-model:open", "title", "closeOnBackdrop"], "useWhen": "Blocking dialog; Escape, focus trap and focus return are handled for you" },
  { "need": "Side drawer", "component": "GnDrawer", "props": ["v-model:open", "title", "position"], "useWhen": "Slide-in panel for details, quick edit or secondary flows" },
  { "need": "Toasts", "component": "GnToastProvider + useToast", "propsNote": "Wrap app once; call `toast.success({ title, text })`", "useWhen": "Transient global notification; one toast at a time by design" },
  { "need": "Confirm dialog", "component": "GnConfirmDialog", "props": ["v-model:open", "title", "message", "confirmVariant"], "useWhen": "Yes/no confirmation before a destructive or important action" },
  { "need": "Table", "component": "GnTable", "props": ["columns", "rows", "caption", "emptyText"], "useWhen": "Structured data rows with per-cell customization slots" },
  { "need": "Toolbar", "component": "GnToolbar", "props": ["title", "meta", "actions (slot)"], "useWhen": "Title/meta + action buttons row above content" },
  { "need": "Input group", "component": "GnInputGroup", "props": ["addon (slot)", "action (slot)"], "useWhen": "Input with prefix/suffix addon or embedded action button" },
  { "need": "Search field", "component": "GnSearchField", "props": ["v-model"], "useWhen": "Search input with clear button" },
  { "need": "Pagination", "component": "GnPagination", "props": ["page", "total-pages"], "useWhen": "Page switcher for tables and lists" },
  { "need": "Empty state", "component": "GnEmptyState", "props": ["title", "text", "icon", "actions (slot)"], "useWhen": "No-data placeholder with icon, text and actions" },
  { "need": "Skeleton loader", "component": "GnSkeleton", "props": [], "useWhen": "Loading placeholder blocks while content loads" },
  { "need": "Key-value list", "component": "GnDescriptionList", "props": ["items"], "useWhen": "Read-only key-value metadata pairs" },
  { "need": "Progress bar", "component": "GnProgress", "props": ["value", "label", "animated"], "useWhen": "Determinate progress from 0 to max" },
  { "need": "Usage meter card", "component": "GnUsageMeter", "props": ["title", "value", "max", "meta"], "useWhen": "Limit/quota usage card with progress bar" },
  { "need": "Staged progress", "component": "GnProgressStages", "props": ["items"], "useWhen": "Segmented progress across named stages" },
  { "need": "Wizard steps", "component": "GnSteps", "props": ["items", "vertical"], "useWhen": "Step-by-step wizard flow indicator (horizontal or vertical)" },
  { "need": "Chip / tag", "component": "GnChip", "props": ["variant", "selected", "removable"], "useWhen": "Small label that can be selectable or removable" },
  { "need": "Chip group", "component": "GnChipGroup", "props": [], "useWhen": "Row/wrap container for a group of chips" },
  { "need": "Avatar", "component": "GnAvatar", "props": ["src", "alt", "initials", "icon", "size", "status"], "useWhen": "User/entity avatar from image, initials or icon, with optional status" },
  { "need": "Identity row", "component": "GnIdentity", "propsNote": "`title`, `meta`, `avatar` props", "useWhen": "Compact avatar + title + meta row" },
  { "need": "Avatar stack", "component": "GnAvatarStack", "props": ["items"], "useWhen": "Overlapping group of avatars" },
  { "need": "Timeline", "component": "GnTimeline", "props": ["items"], "useWhen": "Vertical event history with state markers" },
  { "need": "Activity log", "component": "GnActivityLog", "props": ["items"], "useWhen": "Compact audit or job log rows" },
  { "need": "Basic list", "component": "GnList", "props": ["items"], "useWhen": "Simple item list" },
  { "need": "Definition list", "component": "GnDefinitionList", "props": ["items"], "useWhen": "Term/description pairs" },
  { "need": "Action list", "component": "GnActionList", "props": ["items"], "useWhen": "List of clickable actions" },
  { "need": "Loader / spinner", "component": "GnLoader", "props": [], "useWhen": "Indeterminate loading spinner" },
  { "need": "Status card", "component": "GnStatusCard", "props": ["title", "text", "icon", "variant"], "useWhen": "Card communicating a state (success/warning/error/info)" },
  { "need": "Metric card", "component": "GnMetricCard", "props": ["label", "value", "icon", "delta", "negative", "meta"], "useWhen": "KPI number with delta and meta" },
  { "need": "Action card", "component": "GnActionCard", "props": ["title", "text", "actions (slot)"], "useWhen": "Card with text and action buttons" },
  { "need": "Dropdown menu", "component": "GnDropdown", "props": ["items", "label", "variant"], "useWhen": "Menu of actions revealed from a trigger button" },
  { "need": "Popover panel", "component": "GnPopover", "props": ["title", "text", "label"], "useWhen": "Small anchored panel with title and text" },
  { "need": "Tooltip", "component": "GnTooltip", "props": ["text"], "useWhen": "Short hover hint" },
  { "need": "Navigation list", "component": "GnNavList", "props": ["items"], "useWhen": "Vertical navigation links list (router-aware)" },
  { "need": "App shell", "component": "GnNavigationShell", "props": ["brand", "items", "current", "footerLeft", "footerRight"], "useWhen": "Whole-app topbar/drawer/footer navigation frame" }
]