@sarjallab09/figma-intelligence 1.0.0

package/figma-intelligence-layer/src/tools/phase5-governance/component-spec/component-detection.ts

@@ -0,0 +1,620 @@
+/**
+ * Component type detection — identifies component type and returns guidance hints
+ * Guidance hints tell extractors what to look for, NOT content to output verbatim.
+ */
+import type { NodeSnapshot, ComponentTypeGuidance } from "./types.js";
+
+const GUIDANCE_MAP: Record<string, ComponentTypeGuidance> = {
+  button: {
+    expectedElements: ["label", "icon", "container"],
+    expectedVariantAxes: ["size", "hierarchy", "state", "type"],
+    expectedStates: ["default", "hover", "pressed", "disabled", "focused", "loading"],
+    semanticRole: "button",
+    wcagPattern: "button",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text, 3:1 non-text",
+  },
+  input: {
+    expectedElements: ["label", "field", "placeholder", "helper text", "icon"],
+    expectedVariantAxes: ["size", "state", "type"],
+    expectedStates: ["default", "focused", "filled", "error", "disabled", "read-only"],
+    semanticRole: "textbox",
+    wcagPattern: "text-field",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text, 3:1 border",
+  },
+  select: {
+    expectedElements: ["label", "trigger", "chevron", "option", "placeholder"],
+    expectedVariantAxes: ["size", "state"],
+    expectedStates: ["default", "open", "focused", "disabled", "error"],
+    semanticRole: "combobox",
+    wcagPattern: "listbox",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text, 3:1 border",
+  },
+  checkbox: {
+    expectedElements: ["box", "checkmark", "label"],
+    expectedVariantAxes: ["size", "state"],
+    expectedStates: ["unchecked", "checked", "indeterminate", "disabled"],
+    semanticRole: "checkbox",
+    wcagPattern: "checkbox",
+    minTouchTarget: 44,
+    contrastRequirement: "3:1 non-text (box border)",
+  },
+  radio: {
+    expectedElements: ["circle", "dot", "label"],
+    expectedVariantAxes: ["size", "state"],
+    expectedStates: ["unselected", "selected", "disabled"],
+    semanticRole: "radio",
+    wcagPattern: "radio-group",
+    minTouchTarget: 44,
+    contrastRequirement: "3:1 non-text (circle border)",
+  },
+  toggle: {
+    expectedElements: ["track", "thumb", "label"],
+    expectedVariantAxes: ["size", "state"],
+    expectedStates: ["off", "on", "disabled"],
+    semanticRole: "switch",
+    wcagPattern: "switch",
+    minTouchTarget: 44,
+    contrastRequirement: "3:1 non-text",
+  },
+  tabs: {
+    expectedElements: ["tab", "indicator", "content"],
+    expectedVariantAxes: ["size", "state", "orientation"],
+    expectedStates: ["default", "active", "hover", "disabled"],
+    semanticRole: "tablist",
+    wcagPattern: "tabs",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text",
+  },
+  modal: {
+    expectedElements: ["header", "body", "footer", "close", "overlay"],
+    expectedVariantAxes: ["size", "type"],
+    expectedStates: ["default"],
+    semanticRole: "dialog",
+    wcagPattern: "dialog-modal",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text",
+  },
+  toast: {
+    expectedElements: ["message", "icon", "close", "action"],
+    expectedVariantAxes: ["type", "state"],
+    expectedStates: ["info", "success", "warning", "error"],
+    semanticRole: "alert",
+    wcagPattern: "alert",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text",
+  },
+  card: {
+    expectedElements: ["image", "title", "body", "footer", "action"],
+    expectedVariantAxes: ["variant", "size"],
+    expectedStates: ["default", "hover", "selected"],
+    semanticRole: "article",
+    wcagPattern: "card",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text, 3:1 border",
+  },
+  chip: {
+    expectedElements: ["label", "icon", "close"],
+    expectedVariantAxes: ["size", "variant", "state"],
+    expectedStates: ["default", "selected", "disabled"],
+    semanticRole: "button",
+    wcagPattern: "button",
+    minTouchTarget: 32,
+    contrastRequirement: "4.5:1 text, 3:1 non-text",
+  },
+  avatar: {
+    expectedElements: ["image", "initials", "icon", "badge"],
+    expectedVariantAxes: ["size", "variant"],
+    expectedStates: ["default"],
+    semanticRole: "img",
+    wcagPattern: "img",
+    minTouchTarget: 44,
+    contrastRequirement: "3:1 non-text",
+  },
+  tooltip: {
+    expectedElements: ["content", "arrow"],
+    expectedVariantAxes: ["placement"],
+    expectedStates: ["default"],
+    semanticRole: "tooltip",
+    wcagPattern: "tooltip",
+    minTouchTarget: 0,
+    contrastRequirement: "4.5:1 text",
+  },
+  accordion: {
+    expectedElements: ["header", "content", "chevron", "title"],
+    expectedVariantAxes: ["state"],
+    expectedStates: ["collapsed", "expanded", "disabled"],
+    semanticRole: "region",
+    wcagPattern: "accordion",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text",
+  },
+  badge: {
+    expectedElements: ["label", "dot"],
+    expectedVariantAxes: ["variant", "size"],
+    expectedStates: ["default"],
+    semanticRole: "status",
+    wcagPattern: "status",
+    minTouchTarget: 0,
+    contrastRequirement: "4.5:1 text, 3:1 non-text",
+  },
+  alert: {
+    expectedElements: ["icon", "title", "message", "close", "action"],
+    expectedVariantAxes: ["variant", "type"],
+    expectedStates: ["info", "success", "warning", "error"],
+    semanticRole: "alert",
+    wcagPattern: "alert",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text",
+  },
+  slider: {
+    expectedElements: ["track", "thumb", "label", "value"],
+    expectedVariantAxes: ["size", "state"],
+    expectedStates: ["default", "hover", "active", "disabled"],
+    semanticRole: "slider",
+    wcagPattern: "slider",
+    minTouchTarget: 44,
+    contrastRequirement: "3:1 non-text",
+  },
+  table: {
+    expectedElements: ["header", "row", "cell", "sort"],
+    expectedVariantAxes: ["variant"],
+    expectedStates: ["default"],
+    semanticRole: "table",
+    wcagPattern: "table",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text",
+  },
+  navigation: {
+    expectedElements: ["logo", "nav items", "actions", "menu"],
+    expectedVariantAxes: ["variant"],
+    expectedStates: ["default"],
+    semanticRole: "navigation",
+    wcagPattern: "navigation",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text",
+  },
+  progress: {
+    expectedElements: ["track", "fill", "label"],
+    expectedVariantAxes: ["variant", "size"],
+    expectedStates: ["default", "indeterminate", "complete"],
+    semanticRole: "progressbar",
+    wcagPattern: "meter",
+    minTouchTarget: 0,
+    contrastRequirement: "3:1 non-text",
+  },
+  // ── Batch 1: New Tier 1 + gap-fill components ─────────────────────────────
+  icon: {
+    expectedElements: ["svg", "path"],
+    expectedVariantAxes: ["size", "type"],
+    expectedStates: ["default"],
+    semanticRole: "img",
+    wcagPattern: "img",
+    minTouchTarget: 0,
+    contrastRequirement: "3:1 non-text",
+  },
+  link: {
+    expectedElements: ["label", "icon"],
+    expectedVariantAxes: ["size", "type", "state"],
+    expectedStates: ["default", "hover", "visited", "active", "focus", "disabled"],
+    semanticRole: "link",
+    wcagPattern: "link",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text",
+  },
+  menu: {
+    expectedElements: ["item", "icon", "label", "shortcut", "divider"],
+    expectedVariantAxes: ["size"],
+    expectedStates: ["closed", "open", "item-hover", "item-disabled"],
+    semanticRole: "menu",
+    wcagPattern: "menu",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text",
+  },
+  spinner: {
+    expectedElements: ["track", "indicator"],
+    expectedVariantAxes: ["size"],
+    expectedStates: ["active", "complete"],
+    semanticRole: "status",
+    wcagPattern: "status",
+    minTouchTarget: 0,
+    contrastRequirement: "3:1 non-text",
+  },
+  breadcrumb: {
+    expectedElements: ["item", "separator", "current"],
+    expectedVariantAxes: ["size"],
+    expectedStates: ["default", "hover", "current-page", "focus"],
+    semanticRole: "navigation",
+    wcagPattern: "breadcrumb",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text",
+  },
+  tag: {
+    expectedElements: ["label", "icon", "close"],
+    expectedVariantAxes: ["type", "size", "removable"],
+    expectedStates: ["default", "hover", "active", "focus", "disabled"],
+    semanticRole: "status",
+    wcagPattern: "status",
+    minTouchTarget: 32,
+    contrastRequirement: "4.5:1 text, 3:1 non-text",
+  },
+  navbar: {
+    expectedElements: ["logo", "nav items", "actions", "hamburger"],
+    expectedVariantAxes: ["type", "size"],
+    expectedStates: ["default", "scrolled", "mobile-collapsed", "mobile-expanded"],
+    semanticRole: "banner",
+    wcagPattern: "banner",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text",
+  },
+  // ── Batch 2: Tier 2 Forms ────────────────────────────────────────────────
+  textarea: {
+    expectedElements: ["label", "field", "helper text", "counter"],
+    expectedVariantAxes: ["size", "state"],
+    expectedStates: ["default", "focused", "filled", "error", "disabled", "read-only"],
+    semanticRole: "textbox",
+    wcagPattern: "text-field",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text, 3:1 border",
+  },
+  search: {
+    expectedElements: ["field", "search icon", "clear icon", "suggestions"],
+    expectedVariantAxes: ["size", "state"],
+    expectedStates: ["default", "focused", "searching", "results", "no-results", "disabled"],
+    semanticRole: "searchbox",
+    wcagPattern: "search",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text, 3:1 border",
+  },
+  combobox: {
+    expectedElements: ["label", "field", "chevron", "listbox", "option"],
+    expectedVariantAxes: ["size", "state"],
+    expectedStates: ["default", "open", "focused", "filtered", "error", "disabled"],
+    semanticRole: "combobox",
+    wcagPattern: "combobox",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text, 3:1 border",
+  },
+  datepicker: {
+    expectedElements: ["label", "trigger", "calendar", "day cell", "nav arrows"],
+    expectedVariantAxes: ["type", "size", "state"],
+    expectedStates: ["default", "open", "focused", "error", "disabled"],
+    semanticRole: "group",
+    wcagPattern: "dialog-date-picker",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text, 3:1 non-text",
+  },
+  numberinput: {
+    expectedElements: ["label", "field", "increment", "decrement"],
+    expectedVariantAxes: ["size", "state"],
+    expectedStates: ["default", "focused", "error", "disabled"],
+    semanticRole: "spinbutton",
+    wcagPattern: "spinbutton",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text, 3:1 border",
+  },
+  form: {
+    expectedElements: ["fields", "labels", "submit", "reset", "error summary"],
+    expectedVariantAxes: ["layout"],
+    expectedStates: ["default", "submitting", "success", "error"],
+    semanticRole: "form",
+    wcagPattern: "form",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text",
+  },
+  // ── Batch 3: Nav + Data + Layout ──────────────────────────────────────────
+  pagination: {
+    expectedElements: ["page button", "prev", "next", "ellipsis"],
+    expectedVariantAxes: ["type", "size"],
+    expectedStates: ["default", "hover", "active-page", "disabled", "focus"],
+    semanticRole: "navigation",
+    wcagPattern: "pagination",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text, 3:1 non-text",
+  },
+  list: {
+    expectedElements: ["item", "icon", "text", "secondary text", "divider"],
+    expectedVariantAxes: ["type", "dividers"],
+    expectedStates: ["default", "hover", "selected", "disabled"],
+    semanticRole: "list",
+    wcagPattern: "listbox",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text",
+  },
+  treeview: {
+    expectedElements: ["node", "expand icon", "label", "checkbox"],
+    expectedVariantAxes: ["size", "selection"],
+    expectedStates: ["expanded", "collapsed", "selected", "disabled"],
+    semanticRole: "tree",
+    wcagPattern: "treeview",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text",
+  },
+  typography: {
+    expectedElements: ["text"],
+    expectedVariantAxes: ["variant", "size"],
+    expectedStates: ["default"],
+    semanticRole: "heading",
+    wcagPattern: "heading",
+    minTouchTarget: 0,
+    contrastRequirement: "4.5:1 text",
+  },
+  divider: {
+    expectedElements: ["line", "label"],
+    expectedVariantAxes: ["orientation", "type"],
+    expectedStates: ["default"],
+    semanticRole: "separator",
+    wcagPattern: "separator",
+    minTouchTarget: 0,
+    contrastRequirement: "3:1 non-text",
+  },
+  skeleton: {
+    expectedElements: ["shape"],
+    expectedVariantAxes: ["type", "animation"],
+    expectedStates: ["loading"],
+    semanticRole: "presentation",
+    wcagPattern: "none",
+    minTouchTarget: 0,
+    contrastRequirement: "N/A",
+  },
+  // ── Batch 4: Overlay + Remaining ──────────────────────────────────────────
+  popover: {
+    expectedElements: ["content", "arrow", "close"],
+    expectedVariantAxes: ["placement", "hasArrow"],
+    expectedStates: ["open", "closed"],
+    semanticRole: "dialog",
+    wcagPattern: "dialog-non-modal",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text",
+  },
+  dropdownmenu: {
+    expectedElements: ["trigger", "panel", "item", "divider"],
+    expectedVariantAxes: ["size", "alignment"],
+    expectedStates: ["open", "closed", "item-hover", "item-disabled"],
+    semanticRole: "menu",
+    wcagPattern: "menu-button",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text",
+  },
+  avatargroup: {
+    expectedElements: ["avatar", "overflow indicator"],
+    expectedVariantAxes: ["size", "maxVisible"],
+    expectedStates: ["default"],
+    semanticRole: "group",
+    wcagPattern: "group",
+    minTouchTarget: 0,
+    contrastRequirement: "3:1 non-text",
+  },
+  grid: {
+    expectedElements: ["cell", "row"],
+    expectedVariantAxes: ["columns", "gap"],
+    expectedStates: ["default"],
+    semanticRole: "presentation",
+    wcagPattern: "none",
+    minTouchTarget: 0,
+    contrastRequirement: "N/A",
+  },
+  emptystate: {
+    expectedElements: ["illustration", "heading", "description", "action"],
+    expectedVariantAxes: ["size"],
+    expectedStates: ["default"],
+    semanticRole: "region",
+    wcagPattern: "region",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text",
+  },
+  banner: {
+    expectedElements: ["icon", "message", "action", "close"],
+    expectedVariantAxes: ["type", "dismissible"],
+    expectedStates: ["default", "dismissed"],
+    semanticRole: "alert",
+    wcagPattern: "alert",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text",
+  },
+  // ── Batch 5: Tier 3 ──────────────────────────────────────────────────────
+  drawer: {
+    expectedElements: ["header", "body", "footer", "close", "overlay"],
+    expectedVariantAxes: ["side", "size"],
+    expectedStates: ["open", "closed"],
+    semanticRole: "dialog",
+    wcagPattern: "dialog-modal",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text",
+  },
+  segmentedcontrol: {
+    expectedElements: ["segment", "indicator"],
+    expectedVariantAxes: ["size", "type"],
+    expectedStates: ["default", "hover", "selected", "disabled"],
+    semanticRole: "radiogroup",
+    wcagPattern: "radio-group",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text, 3:1 non-text",
+  },
+  stepper: {
+    expectedElements: ["step", "connector", "icon", "label"],
+    expectedVariantAxes: ["orientation", "type"],
+    expectedStates: ["completed", "current", "upcoming", "error"],
+    semanticRole: "list",
+    wcagPattern: "list",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text, 3:1 non-text",
+  },
+  fileuploader: {
+    expectedElements: ["dropzone", "trigger", "file list", "progress"],
+    expectedVariantAxes: ["type", "state"],
+    expectedStates: ["idle", "drag-over", "uploading", "complete", "error"],
+    semanticRole: "button",
+    wcagPattern: "button",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text, 3:1 border",
+  },
+  inlinemessage: {
+    expectedElements: ["icon", "message"],
+    expectedVariantAxes: ["type"],
+    expectedStates: ["default"],
+    semanticRole: "status",
+    wcagPattern: "status",
+    minTouchTarget: 0,
+    contrastRequirement: "4.5:1 text",
+  },
+  toolbar: {
+    expectedElements: ["item", "separator", "overflow"],
+    expectedVariantAxes: ["size", "overflow"],
+    expectedStates: ["default", "item-hover", "item-active"],
+    semanticRole: "toolbar",
+    wcagPattern: "toolbar",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text, 3:1 non-text",
+  },
+  calendar: {
+    expectedElements: ["header", "day cell", "month nav", "week labels"],
+    expectedVariantAxes: ["type", "size"],
+    expectedStates: ["today", "selected", "range-start", "range-end", "disabled"],
+    semanticRole: "grid",
+    wcagPattern: "grid",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text, 3:1 non-text",
+  },
+  timepicker: {
+    expectedElements: ["input", "dropdown", "time slot"],
+    expectedVariantAxes: ["format", "size"],
+    expectedStates: ["default", "open", "focused", "error", "disabled"],
+    semanticRole: "combobox",
+    wcagPattern: "combobox",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text, 3:1 border",
+  },
+  rangeslider: {
+    expectedElements: ["track", "fill", "thumb-min", "thumb-max", "label"],
+    expectedVariantAxes: ["size", "state"],
+    expectedStates: ["default", "hover", "active", "disabled"],
+    semanticRole: "slider",
+    wcagPattern: "slider-multithumb",
+    minTouchTarget: 44,
+    contrastRequirement: "3:1 non-text",
+  },
+  inlineedit: {
+    expectedElements: ["display text", "edit icon", "input", "confirm", "cancel"],
+    expectedVariantAxes: ["size", "state"],
+    expectedStates: ["read-mode", "edit-mode", "saving", "error"],
+    semanticRole: "button",
+    wcagPattern: "button",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text",
+  },
+  statusdot: {
+    expectedElements: ["dot", "label"],
+    expectedVariantAxes: ["status", "size"],
+    expectedStates: ["default"],
+    semanticRole: "status",
+    wcagPattern: "status",
+    minTouchTarget: 0,
+    contrastRequirement: "3:1 non-text",
+  },
+  rating: {
+    expectedElements: ["star", "label"],
+    expectedVariantAxes: ["size", "state"],
+    expectedStates: ["default", "hover", "active", "readonly", "disabled"],
+    semanticRole: "radiogroup",
+    wcagPattern: "radio-group",
+    minTouchTarget: 44,
+    contrastRequirement: "3:1 non-text",
+  },
+  sidenavigation: {
+    expectedElements: ["item", "section header", "active indicator", "expand icon"],
+    expectedVariantAxes: ["state"],
+    expectedStates: ["expanded", "collapsed", "item-active", "item-hover"],
+    semanticRole: "navigation",
+    wcagPattern: "navigation",
+    minTouchTarget: 44,
+    contrastRequirement: "4.5:1 text",
+  },
+};
+
+// Detection patterns — ordered specific-first to prevent false matches
+const TYPE_PATTERNS: [RegExp, string][] = [
+  // Compound / multi-word patterns first
+  [/avatar.?group|avatar.?stack/i, "avatargroup"],
+  [/dropdown.?menu|action.?menu/i, "dropdownmenu"],
+  [/range.?slider|dual.?slider/i, "rangeslider"],
+  [/side.?nav|sidebar.?nav|vertical.?nav/i, "sidenavigation"],
+  [/date.?picker|calendar.?input/i, "datepicker"],
+  [/time.?picker/i, "timepicker"],
+  [/number.?input|number.?field|stepper.?input/i, "numberinput"],
+  [/file.?upload|drop.?zone|file.?input/i, "fileuploader"],
+  [/inline.?message|field.?message|helper.?text/i, "inlinemessage"],
+  [/inline.?edit/i, "inlineedit"],
+  [/segmented|segment.?control|button.?group/i, "segmentedcontrol"],
+  [/empty.?state|no.?data|no.?results/i, "emptystate"],
+  [/tree.?view|tree.?list|tree.?node/i, "treeview"],
+  [/search.?bar|search.?field/i, "search"],
+  [/nav.?bar|app.?bar|top.?bar|header.?bar/i, "navbar"],
+  // Specific single-word patterns
+  [/breadcrumb/i, "breadcrumb"],
+  [/pagination|pager/i, "pagination"],
+  [/stepper|wizard|step.?indicator/i, "stepper"],
+  [/toolbar|action.?bar/i, "toolbar"],
+  [/spinner|loader\b/i, "spinner"],
+  [/skeleton|shimmer|placeholder/i, "skeleton"],
+  [/\bbanner\b/i, "banner"],
+  // Core form components
+  [/button|btn|cta/i, "button"],
+  [/textarea|text.?area/i, "textarea"],
+  [/input|text.?field/i, "input"],
+  [/select|dropdown/i, "select"],
+  [/checkbox|check.?box/i, "checkbox"],
+  [/radio/i, "radio"],
+  [/toggle|switch/i, "toggle"],
+  [/slider/i, "slider"],
+  [/combobox|combo.?box|autocomplete/i, "combobox"],
+  [/\bsearch\b/i, "search"],
+  [/\bform\b/i, "form"],
+  // Navigation
+  [/\btab\b|\btabs\b/i, "tabs"],
+  [/\bmenu\b|context.?menu/i, "menu"],
+  // Feedback
+  [/toast|snackbar/i, "toast"],
+  [/alert/i, "alert"],
+  [/progress\b|progress.?bar/i, "progress"],
+  // Overlay
+  [/modal|dialog/i, "modal"],
+  [/tooltip/i, "tooltip"],
+  [/popover|pop.?over/i, "popover"],
+  [/drawer|sheet|side.?panel/i, "drawer"],
+  // Data
+  [/table|data.?grid/i, "table"],
+  [/\blist\b|list.?item/i, "list"],
+  [/\bcalendar\b|month.?view/i, "calendar"],
+  [/\bgrid\b|layout.?grid/i, "grid"],
+  // Core / misc
+  [/card/i, "card"],
+  [/chip/i, "chip"],
+  [/\btag\b/i, "tag"],
+  [/badge/i, "badge"],
+  [/avatar/i, "avatar"],
+  [/\bicon\b/i, "icon"],
+  [/\blink\b|text.?link|hyperlink/i, "link"],
+  [/status.?dot|status.?indicator/i, "statusdot"],
+  [/typography|type.?scale|text.?style/i, "typography"],
+  [/divider|separator|\bhr\b/i, "divider"],
+  [/accordion/i, "accordion"],
+  [/rating|star.?rating/i, "rating"],
+  // Catch-all navigation (last)
+  [/\bnav\b|navigation/i, "navigation"],
+  [/\bloading\b/i, "spinner"],
+];
+
+export function detectComponentType(snapshot: NodeSnapshot): { type?: string; guidance?: ComponentTypeGuidance } {
+  const name = snapshot.name.toLowerCase();
+
+  for (const [pattern, type] of TYPE_PATTERNS) {
+    if (pattern.test(name)) {
+      return { type, guidance: GUIDANCE_MAP[type] };
+    }
+  }
+
+  return {};
+}