@sarjallab09/figma-intelligence 1.0.0

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

@@ -0,0 +1,250 @@
+/**
+ * list.ts — Gold-standard design knowledge for List components
+ */
+import type { ComponentKnowledge } from "../types.js";
+
+export const listKnowledge: ComponentKnowledge = {
+  description:
+    "Ordered or unordered list of items | Supports simple, interactive, two-line, and avatar variants | Core layout primitive for collections",
+
+  stateSpecifications: [
+    {
+      state: "Default",
+      visualChange: "List items rendered vertically with consistent spacing; no highlight or selection indicator",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Resting state — list is displayed with all items in their neutral visual treatment",
+    },
+    {
+      state: "Hover",
+      visualChange: "Hovered item background shifts to hover token; subtle highlight row",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Mouse cursor enters an interactive list item's hit area (interactive/selectable variants only)",
+    },
+    {
+      state: "Selected",
+      visualChange: "Selected item has a tinted background and/or leading checkmark icon; primary accent on left edge possible",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Item has been chosen by the user in a selectable list; visually persists until deselected",
+    },
+    {
+      state: "Disabled",
+      visualChange: "Item text and icons use muted/disabled tokens; no hover or click response",
+      opacity: "0.4",
+      cursorWeb: "not-allowed",
+      usage: "Individual item is non-interactive due to permissions, prerequisites, or unavailability",
+    },
+    {
+      state: "Empty",
+      visualChange: "Placeholder message or illustration displayed in place of list items",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "List has zero items — show empty state with guidance on how to populate",
+    },
+  ],
+
+  propertyDescriptions: {
+    items: "Array of item data objects to render; each object contains primary text, optional secondary text, optional icon/avatar",
+    type: "Visual layout variant — 'simple' (text only), 'interactive' (clickable rows), 'twoLine' (primary + secondary text), 'avatar' (leading avatar image)",
+    dividers: "When true, thin separator lines appear between list items using the $divider token",
+    selectable: "Enables selection behavior — 'single' for radio-like selection, 'multi' for checkbox-like, 'none' to disable",
+    onSelect: "Callback fired when an item is selected or deselected; receives the item identifier and selection state",
+    dense: "When true, reduces vertical padding per item for compact layouts (e.g. menus, sidebars)",
+    ordered: "When true, renders as an ordered list with numeric or alphabetic markers; false renders unordered",
+    maxHeight: "Maximum height before the list becomes scrollable; supports virtualisation for large datasets",
+    emptyMessage: "Custom string or component displayed when the items array is empty",
+  },
+
+  sizeSpecifications: [
+    {
+      size: "Small",
+      height: "36px per item",
+      paddingLR: "12px",
+      fontSize: "13px",
+      iconSize: "16px",
+      borderRadius: "4px",
+    },
+    {
+      size: "Medium",
+      height: "48px per item",
+      paddingLR: "16px",
+      fontSize: "14px",
+      iconSize: "20px",
+      borderRadius: "6px",
+    },
+    {
+      size: "Large",
+      height: "64px per item",
+      paddingLR: "20px",
+      fontSize: "16px",
+      iconSize: "24px",
+      borderRadius: "8px",
+    },
+  ],
+
+  designTokenBindings: [
+    {
+      property: "Item Background",
+      tokenName: "$list-item-bg",
+      role: "Default background for each list item",
+      fallback: "transparent",
+    },
+    {
+      property: "Hover Background",
+      tokenName: "$list-hover-bg",
+      role: "Background applied on hover for interactive items",
+      fallback: "#F2F4F7",
+    },
+    {
+      property: "Selected Background",
+      tokenName: "$list-selected-bg",
+      role: "Background tint for selected items",
+      fallback: "#EFF8FF",
+    },
+    {
+      property: "Primary Text",
+      tokenName: "$list-primary-text",
+      role: "Color for the main text label of each item",
+      fallback: "#101828",
+    },
+    {
+      property: "Secondary Text",
+      tokenName: "$list-secondary-text",
+      role: "Color for the secondary/subtitle line in twoLine variant",
+      fallback: "#667085",
+    },
+    {
+      property: "Divider",
+      tokenName: "$list-divider",
+      role: "Color for the horizontal separator lines between items",
+      fallback: "#E4E7EC",
+    },
+    {
+      property: "Selected Accent",
+      tokenName: "$list-selected-accent",
+      role: "Leading edge accent or checkmark color for selected items",
+      fallback: "#2563EB",
+    },
+    {
+      property: "Disabled Text",
+      tokenName: "$list-disabled-text",
+      role: "Muted text color for disabled items",
+      fallback: "#98A2B3",
+    },
+    {
+      property: "Focus Ring",
+      tokenName: "$focus-ring",
+      role: "Keyboard focus indicator ring on focused list item",
+      fallback: "0 0 0 2px #FFFFFF, 0 0 0 4px #2E90FA",
+    },
+    {
+      property: "Font Family",
+      tokenName: "$font-family-sans",
+      role: "Typeface for all list text",
+      fallback: "Inter, system-ui, sans-serif",
+    },
+  ],
+
+  structureRules: [
+    "Container uses vertical Auto Layout with no gap — spacing is handled by item internal padding",
+    "Each item is a horizontal Auto Layout row: optional leading element (icon/avatar/checkbox), text content, optional trailing element (action/meta)",
+    "Text content area uses vertical Auto Layout for twoLine variant: primary text on top, secondary text below",
+    "Divider lines are 1px height, full-width children between items — controlled by the dividers prop",
+    "Avatar variant places a circular avatar (32-40px) as the leading element with $spacing-md gap to text",
+    "Interactive items have a full-width clickable area — the entire row is the hit target, not just the text",
+    "Empty state replaces the item list with a centered message component; maintains container min-height",
+    "Scrollable lists clip overflow and show a scrollbar when content exceeds maxHeight",
+  ],
+
+  typeHierarchyRules: [
+    "Primary text uses Regular (400) weight; font-size matches the selected size preset",
+    "Secondary text uses Regular (400) weight at one step smaller than primary (e.g. 12px when primary is 14px)",
+    "Primary text uses $list-primary-text color; secondary uses $list-secondary-text for visual hierarchy",
+    "Text truncation with ellipsis on single-line items; twoLine primary text may wrap to 2 lines max",
+    "Ordered list markers use tabular numerals; unordered markers use bullet characters or none",
+  ],
+
+  interactionRules: [
+    { event: "Click Item", trigger: "pointerup on an interactive list item", action: "Fire onSelect with item id; toggle selection state if selectable" },
+    { event: "Hover", trigger: "pointerenter on an interactive item", action: "Apply hover background token; transition smoothly" },
+    { event: "Focus", trigger: "Tab key or arrow key navigation", action: "Show focus ring on the focused item; scroll into view if needed" },
+    { event: "Keydown Enter", trigger: "Enter key while an item is focused", action: "Fire onSelect for the focused item (same as click)" },
+    { event: "Keydown Space", trigger: "Space key while a selectable item is focused", action: "Toggle selection on the focused item" },
+    { event: "Keydown Arrow Up/Down", trigger: "Arrow keys while focus is within the list", action: "Move focus to the previous/next item; wrap or stop at boundaries" },
+    { event: "Multi-select", trigger: "Shift+Click or Ctrl+Click on items", action: "Extend or toggle selection range for multi-selectable lists" },
+  ],
+
+  contentGuidance: [
+    "Primary text should be concise — one line for simple, up to two lines for twoLine variant",
+    "Secondary text provides supporting detail: descriptions, metadata, timestamps, or status",
+    "Use consistent content patterns across all items in the same list — do not mix twoLine and simple",
+    "Leading icons should be semantically meaningful, not decorative; use the same icon style throughout",
+    "Avatar variant is ideal for people lists (contacts, team members, chat participants)",
+    "Empty state messages should guide the user on how to add items, not just state that the list is empty",
+    "Trailing elements (badges, timestamps, action buttons) should be used sparingly to avoid clutter",
+  ],
+
+  responsiveBehaviour: [
+    { breakpoint: "Mobile (<768px)", behavior: "List items span full width; trailing elements may stack below primary text; touch targets minimum 48px height" },
+    { breakpoint: "Tablet (768-1023px)", behavior: "Standard layout maintained; consider reducing to simple variant if space is tight" },
+    { breakpoint: "Desktop (1024-1439px)", behavior: "Full layout with all elements visible; twoLine and avatar variants display optimally" },
+    { breakpoint: "Ultra-wide (>=1440px)", behavior: "List width should be constrained (max-width) to maintain readability — do not stretch to fill" },
+  ],
+
+  accessibilitySpec: {
+    intro:
+      "Lists must convey structure and item count to assistive technologies. Interactive lists require full keyboard support including arrow key navigation and selection announcements.",
+    requirements: [
+      { requirement: "Semantic Roles", level: "A", notes: "Non-interactive lists use role='list' with role='listitem' children; interactive/selectable lists use role='listbox' with role='option'" },
+      { requirement: "Keyboard Navigation", level: "A", notes: "Interactive items are focusable via Tab; arrow keys move between items; Enter/Space activate or select" },
+      { requirement: "Selection State", level: "A", notes: "Selected items must have aria-selected='true'; multi-select items use aria-multiselectable on the listbox" },
+      { requirement: "Disabled Items", level: "A", notes: "Disabled items use aria-disabled='true'; they may remain in the focus order with no action on activation" },
+      { requirement: "Contrast Ratio", level: "AA", notes: "Primary text: 4.5:1 minimum; secondary text: 4.5:1; selected indicator: 3:1 non-text contrast" },
+      { requirement: "Touch Target", level: "AA", notes: "Each interactive item row must have at least 44px height for touch accessibility" },
+      { requirement: "Empty State", level: "A", notes: "When the list is empty, provide an accessible label or live region announcing the empty state" },
+    ],
+    outro: [
+      "When items are added or removed dynamically, use aria-live='polite' to announce the change to screen readers",
+      "Focus should remain stable when the list re-renders — do not reset focus to the first item on data updates",
+      "Group related lists with headings using aria-labelledby to provide context for the collection",
+    ],
+  },
+
+  qaAcceptanceCriteria: [
+    { check: "Visual Regression", platform: "All", expectedResult: "List renders pixel-perfect against baseline for each type and size variant" },
+    { check: "Hover State", platform: "Web", expectedResult: "Interactive items show hover background on mouse enter; non-interactive items do not" },
+    { check: "Selection State", platform: "All", expectedResult: "Selected items display tinted background and/or checkmark; aria-selected is true" },
+    { check: "Multi-select", platform: "Web", expectedResult: "Shift+Click selects range; Ctrl+Click toggles individual items; aria-multiselectable set" },
+    { check: "Disabled Items", platform: "All", expectedResult: "Disabled items have muted visuals; no click/hover response; aria-disabled='true'" },
+    { check: "Focus Navigation", platform: "Web", expectedResult: "Tab enters list; arrow keys move between items; focus ring visible; scroll-into-view works" },
+    { check: "Keyboard Activation", platform: "Web", expectedResult: "Enter/Space on focused item fires onSelect; no double-fire" },
+    { check: "Screen Reader", platform: "Web", expectedResult: "Announces role (list/listbox), item count, selected state, and disabled state" },
+    { check: "Dividers", platform: "All", expectedResult: "Separator lines visible when dividers=true; hidden when false; correct token color" },
+    { check: "Empty State", platform: "All", expectedResult: "Empty message displayed when items array is empty; accessible to screen readers" },
+    { check: "Two-line Variant", platform: "All", expectedResult: "Primary and secondary text render on separate lines with correct hierarchy" },
+    { check: "Avatar Variant", platform: "All", expectedResult: "Circular avatar renders at correct size; fallback initials shown for missing images" },
+    { check: "RTL Support", platform: "Web", expectedResult: "Leading/trailing elements swap sides; text alignment mirrors; dividers remain full-width" },
+  ],
+
+  dos: [
+    "Use the simple type for static informational lists (feature lists, specifications, settings)",
+    "Use the interactive type for action-triggering items (navigation menus, command lists)",
+    "Use dividers for long lists to help users visually scan and separate items",
+    "Maintain consistent item structure across all items in a single list instance",
+    "Provide an empty state message when the list can be dynamically populated",
+    "Use the dense prop for sidebar navigation and menus where space is limited",
+    "Ensure avatar images have meaningful alt text for accessibility",
+  ],
+
+  donts: [
+    "Do not nest interactive lists inside other interactive lists — flatten the hierarchy",
+    "Do not mix different item types (simple, twoLine, avatar) within the same list instance",
+    "Do not use a list component for grid-like layouts — use a grid or card grid instead",
+    "Do not hide the selected state indicator — users must always know what is selected",
+    "Do not render more than 50-100 items without virtualization to prevent performance degradation",
+    "Do not use trailing action buttons on every item — it creates visual noise and reduces scannability",
+    "Do not remove disabled items from the DOM; keep them visible but inert for context",
+  ],
+};

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

@@ -0,0 +1,247 @@
+/**
+ * menu.ts — Gold-standard design knowledge for Menu / Context Menu / Action Menu components
+ */
+import type { ComponentKnowledge } from "../types.js";
+
+export const menuKnowledge: ComponentKnowledge = {
+  description:
+    "Overlay action panel | Context-triggered item list | Actionable command menu",
+
+  stateSpecifications: [
+    {
+      state: "Closed",
+      visualChange: "Menu is not rendered or has opacity 0 and pointer-events none; trigger element is in its resting state",
+      opacity: "0",
+      cursorWeb: "default",
+      usage: "Default state — menu is hidden until activated by the trigger element",
+    },
+    {
+      state: "Open",
+      visualChange: "Menu panel fades in with elevation shadow; first non-disabled item receives visual focus",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "User clicks the trigger, right-clicks for context menu, or presses Enter/Space/ArrowDown on trigger",
+    },
+    {
+      state: "Item-hover",
+      visualChange: "Hovered menu item receives a highlighted background using $menu-item-hover-bg token",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Mouse cursor enters a menu item's hit area while the menu is open",
+    },
+    {
+      state: "Item-active",
+      visualChange: "Pressed menu item background shifts to $menu-item-active-bg; slight darkening for tactile feedback",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Mouse button is held down on a menu item or Enter/Space is pressed on a focused item",
+    },
+    {
+      state: "Item-disabled",
+      visualChange: "Item text uses $menu-item-disabled-text token; no hover or active state; pointer-events none",
+      opacity: "0.4",
+      cursorWeb: "not-allowed",
+      usage: "Menu item action is unavailable due to missing prerequisites or permissions",
+    },
+    {
+      state: "Item-focus",
+      visualChange: "Focused item shows a 2px focus ring inset within the item bounds using $focus-ring token",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Keyboard navigation highlights the current item via ArrowUp/ArrowDown or type-ahead",
+    },
+  ],
+
+  propertyDescriptions: {
+    items: "Array of menu item objects, each containing label, optional icon, optional keyboard shortcut hint, disabled flag, and divider flag",
+    trigger: "The interactive element (button, icon button, or right-click target) that opens the menu on activation",
+    placement: "Preferred position of the menu relative to the trigger — bottom-start, bottom-end, or right-start; auto-flips on collision",
+    size: "Dimensional preset controlling item height, padding, font-size, and icon-size (Small, Medium, Large)",
+    closeOnSelect: "When true (default), the menu automatically closes after an item is activated; set to false for multi-select menus",
+    maxHeight: "Maximum height of the menu panel before internal scrolling activates; prevents the menu from exceeding viewport bounds",
+  },
+
+  sizeSpecifications: [
+    {
+      size: "Small",
+      height: "28px",
+      paddingLR: "8px",
+      fontSize: "12px",
+      iconSize: "14px",
+      borderRadius: "6px",
+    },
+    {
+      size: "Medium",
+      height: "36px",
+      paddingLR: "12px",
+      fontSize: "14px",
+      iconSize: "16px",
+      borderRadius: "8px",
+    },
+    {
+      size: "Large",
+      height: "44px",
+      paddingLR: "16px",
+      fontSize: "16px",
+      iconSize: "20px",
+      borderRadius: "10px",
+    },
+  ],
+
+  designTokenBindings: [
+    {
+      property: "Background",
+      tokenName: "$menu-bg",
+      role: "Menu panel surface color — typically a white or elevated surface token",
+      fallback: "#FFFFFF",
+    },
+    {
+      property: "Border",
+      tokenName: "$menu-border",
+      role: "Subtle border around the menu panel for definition against the page",
+      fallback: "#E4E7EC",
+    },
+    {
+      property: "Shadow",
+      tokenName: "$menu-shadow",
+      role: "Elevation shadow giving the menu a floating appearance above page content",
+      fallback: "0 4px 16px rgba(0,0,0,0.12)",
+    },
+    {
+      property: "Item Text",
+      tokenName: "$menu-item-text",
+      role: "Default text color for menu item labels",
+      fallback: "#344054",
+    },
+    {
+      property: "Item Hover Background",
+      tokenName: "$menu-item-hover-bg",
+      role: "Background highlight applied to the hovered or focused menu item",
+      fallback: "#F2F4F7",
+    },
+    {
+      property: "Item Active Background",
+      tokenName: "$menu-item-active-bg",
+      role: "Background applied during the pressed/active state of a menu item",
+      fallback: "#E4E7EC",
+    },
+    {
+      property: "Disabled Text",
+      tokenName: "$menu-item-disabled-text",
+      role: "Muted text color for disabled menu items indicating unavailability",
+      fallback: "#98A2B3",
+    },
+    {
+      property: "Divider",
+      tokenName: "$menu-divider",
+      role: "Color of the horizontal separator line between menu item groups",
+      fallback: "#E4E7EC",
+    },
+    {
+      property: "Focus Ring",
+      tokenName: "$focus-ring",
+      role: "Keyboard focus indicator ring for the currently focused menu item",
+      fallback: "0 0 0 2px #FFFFFF, 0 0 0 4px #2E90FA",
+    },
+  ],
+
+  structureRules: [
+    "Menu panel renders in a portal at the document root to avoid clipping by parent overflow",
+    "Menu container uses vertical Auto Layout with no gap — items stack flush; dividers are 1px separator elements",
+    "Each menu item is a horizontal Auto Layout row: optional leading icon, label text, flexible spacer, optional shortcut hint",
+    "Dividers use role='separator' and span the full menu width with vertical margin of $spacing-xs (4px)",
+    "Positioning is calculated dynamically based on trigger element rect and viewport boundaries with collision detection",
+    "Menu width auto-sizes to the widest item up to a maxWidth (280px default); a minWidth (160px) prevents overly narrow panels",
+    "When maxHeight is exceeded, the menu panel becomes internally scrollable with overscroll-behavior: contain",
+  ],
+
+  typeHierarchyRules: [
+    "Item label font weight is Regular (400) — no bold unless the item represents a currently active selection",
+    "Text uses sentence case — capitalize only the first word of each menu item label",
+    "Shortcut hint text uses a monospace font token at one step smaller than the item label font size",
+    "Destructive items (e.g., 'Delete') use $color-danger for label text color to signal risk",
+    "No text truncation within menu items — ensure all labels fit within the maxWidth constraint",
+  ],
+
+  interactionRules: [
+    { event: "Click Trigger", trigger: "pointerup on trigger element", action: "Toggle menu open/closed; set aria-expanded accordingly" },
+    { event: "ArrowDown / ArrowUp", trigger: "Keydown while menu is open", action: "Move visual focus to next/previous non-disabled item; wrap at boundaries" },
+    { event: "Enter / Space", trigger: "Keydown on focused item", action: "Activate the item's action; close menu if closeOnSelect is true" },
+    { event: "Escape", trigger: "Keydown while menu is open", action: "Close the menu and return focus to the trigger element" },
+    { event: "Type-ahead", trigger: "Letter key while menu is open", action: "Move focus to the next item whose label starts with the typed character" },
+    { event: "Home / End", trigger: "Home or End key while menu is open", action: "Move focus to the first or last non-disabled menu item" },
+    { event: "Click Outside", trigger: "pointerdown outside menu and trigger bounds", action: "Close the menu without activating any item" },
+  ],
+
+  contentGuidance: [
+    "Menu item labels should be concise action verbs or short verb phrases: 'Edit', 'Duplicate', 'Move to folder'",
+    "Group related items together with dividers — no more than 3-4 groups per menu to avoid cognitive overload",
+    "Place destructive actions (Delete, Remove) at the bottom of the menu, separated by a divider",
+    "Use leading icons consistently — either all items have icons or none do; avoid mixing",
+    "Keyboard shortcut hints should match platform conventions (Cmd on macOS, Ctrl on Windows)",
+    "Keep the total number of menu items under 12 — use submenus or a different pattern for longer lists",
+    "Disabled items should remain visible to maintain spatial consistency but must indicate their unavailability",
+  ],
+
+  responsiveBehaviour: [
+    { breakpoint: "Mobile (<768px)", behavior: "Menu may render as a bottom sheet or action sheet for reachability; items use 48px touch targets" },
+    { breakpoint: "Tablet (768-1023px)", behavior: "Standard dropdown positioning; ensure menu does not overflow the viewport horizontally" },
+    { breakpoint: "Desktop (1024-1439px)", behavior: "Standard floating menu anchored to trigger; preferred placement honored with collision detection" },
+    { breakpoint: "Ultra-wide (>=1440px)", behavior: "Menu positioning unchanged; maxWidth prevents overly wide panels; no proportional scaling" },
+  ],
+
+  accessibilitySpec: {
+    intro:
+      "Menus are critical navigation and action surfaces. They must be fully operable via keyboard and correctly announced by screen readers to meet WCAG 2.1 compliance.",
+    requirements: [
+      { requirement: "Container Role", level: "A", notes: "Menu container must use role='menu' for proper semantic identification by assistive technology" },
+      { requirement: "Item Role", level: "A", notes: "Each actionable item must use role='menuitem'; dividers use role='separator'" },
+      { requirement: "Trigger Attributes", level: "A", notes: "Trigger element must set aria-haspopup='menu' and aria-expanded (true when open, false when closed)" },
+      { requirement: "Keyboard Navigation", level: "A", notes: "ArrowUp/ArrowDown navigate items; Enter/Space activate; Escape closes; Home/End jump to boundaries" },
+      { requirement: "Focus Management", level: "A", notes: "Focus moves into the menu on open and returns to the trigger on close; focus must not escape the menu while open" },
+      { requirement: "Contrast", level: "AA", notes: "Item text to background must meet 4.5:1; item hover/focus indicator must meet 3:1 against adjacent colors" },
+      { requirement: "Disabled Items", level: "A", notes: "Disabled items must set aria-disabled='true' and be skipped during keyboard navigation" },
+    ],
+    outro: [
+      "Screen readers should announce the menu role, the number of items, and the currently focused item position",
+      "Ensure focus is trapped within the menu while open — Tab should not move focus outside the menu panel",
+    ],
+  },
+
+  qaAcceptanceCriteria: [
+    { check: "Open/Close", platform: "Web", expectedResult: "Menu opens on trigger click and closes on item selection, Escape, or outside click" },
+    { check: "Keyboard Navigation", platform: "Web", expectedResult: "ArrowUp/ArrowDown cycle through items; disabled items are skipped; focus wraps at boundaries" },
+    { check: "Item Activation", platform: "Web", expectedResult: "Enter/Space on focused item fires action callback; click on item fires action callback" },
+    { check: "Focus Return", platform: "Web", expectedResult: "Focus returns to trigger element when menu closes via Escape or item selection" },
+    { check: "Type-ahead", platform: "Web", expectedResult: "Pressing a letter key moves focus to the next matching item by first character" },
+    { check: "Screen Reader", platform: "Web", expectedResult: "Announces role 'menu', item count, current item position, and disabled state" },
+    { check: "Placement", platform: "Web", expectedResult: "Menu renders at specified placement; auto-flips when clipped by viewport" },
+    { check: "Scroll Overflow", platform: "Web", expectedResult: "Menu scrolls internally when items exceed maxHeight; overscroll does not propagate to page" },
+    { check: "Dividers", platform: "All", expectedResult: "Visual separators render between groups; announced as separator by screen readers" },
+    { check: "Disabled Items", platform: "All", expectedResult: "Disabled items show muted visuals; are not activatable; are skipped by keyboard navigation" },
+    { check: "Touch Target", platform: "Mobile", expectedResult: "Menu items have at least 44x44px touch target; bottom-sheet variant used on small screens" },
+    { check: "Reduced Motion", platform: "Web", expectedResult: "Open/close animations disabled when prefers-reduced-motion is set" },
+  ],
+
+  dos: [
+    "Use role='menu' on the container and role='menuitem' on each actionable item",
+    "Return focus to the trigger element when the menu closes",
+    "Group related actions with dividers for visual and semantic clarity",
+    "Support full keyboard navigation including ArrowUp/Down, Enter, Space, Escape, Home, End, and type-ahead",
+    "Place destructive actions at the bottom of the menu, visually separated and color-coded",
+    "Ensure the menu auto-repositions when it would overflow the viewport",
+    "Use consistent iconography — either all items have leading icons or none do",
+    "Close the menu when an item is activated (unless multi-select behavior is required)",
+  ],
+
+  donts: [
+    "Do not nest menus deeper than one sublevel — deeply nested menus are unusable on mobile and difficult for keyboard users",
+    "Do not use a menu for navigation — use a navigation component or link list instead",
+    "Do not place more than 12 items in a single menu level — consider a different pattern for longer lists",
+    "Do not remove disabled items from the menu — keep them visible but inactive for spatial consistency",
+    "Do not auto-close the menu on a timer — the user must control when the menu dismisses",
+    "Do not allow focus to escape the menu while it is open — trap focus within the menu panel",
+    "Do not use hover-only triggers for opening menus — click/tap and keyboard activation must be supported",
+    "Do not override design token colors with hard-coded hex values in menu items",
+  ],
+};

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

@@ -0,0 +1,144 @@
+import type { ComponentKnowledge } from "../types.js";
+
+export const modalKnowledge: ComponentKnowledge = {
+  description:
+    "Overlay dialog | Focused interaction container | Content interruption layer",
+
+  stateSpecifications: [
+    { state: "Closed", visualChange: "Modal and backdrop are not rendered in the DOM or are display:none", opacity: "0", cursorWeb: "default", usage: "No modal is active; page is fully interactive" },
+    { state: "Opening", visualChange: "Backdrop fades in, modal slides/scales into view", opacity: "0→1", cursorWeb: "default", usage: "Transition state during entrance animation" },
+    { state: "Open-Default", visualChange: "Backdrop at reduced opacity, modal centered and fully visible", opacity: "1", cursorWeb: "default", usage: "User is interacting with modal content" },
+    { state: "Open-Scrollable", visualChange: "Modal body scrolls independently, header/footer remain fixed", opacity: "1", cursorWeb: "default", usage: "Content exceeds the modal viewport height" },
+    { state: "Closing", visualChange: "Modal fades/slides out, backdrop fades", opacity: "1→0", cursorWeb: "default", usage: "Transition state during exit animation" },
+    { state: "Danger", visualChange: "Primary action button uses danger/destructive color", opacity: "1", cursorWeb: "default", usage: "Confirming an irreversible or destructive action" },
+    { state: "Passive", visualChange: "No action buttons; informational content only with close icon", opacity: "1", cursorWeb: "default", usage: "Displaying read-only information or media" },
+  ],
+
+  propertyDescriptions: {
+    open: "Controls visibility of the modal; when true the dialog is rendered and focus is trapped",
+    size: "Width variant — xs (320px), sm (480px), md (640px), lg (800px), full (100vw–margins)",
+    title: "Heading text rendered in the modal header bar",
+    subtitle: "Optional secondary text below the title providing additional context",
+    hasCloseIcon: "Renders an X button in the top-right corner of the header",
+    preventCloseOnClickOutside: "When true, clicking the backdrop does not dismiss the modal",
+    danger: "Applies destructive styling to the primary action button",
+    primaryButtonText: "Label for the main CTA button in the footer",
+    secondaryButtonText: "Label for the secondary/cancel button in the footer",
+    selectorPrimaryFocus: "CSS selector for the element that receives initial focus on open",
+  },
+
+  sizeSpecifications: [
+    { size: "xs", height: "auto (max 80vh)", paddingLR: "16px", fontSize: "14px", iconSize: "20px", borderRadius: "4px" },
+    { size: "sm", height: "auto (max 80vh)", paddingLR: "24px", fontSize: "14px", iconSize: "20px", borderRadius: "4px" },
+    { size: "md", height: "auto (max 80vh)", paddingLR: "32px", fontSize: "14px", iconSize: "20px", borderRadius: "8px" },
+    { size: "lg", height: "auto (max 84vh)", paddingLR: "32px", fontSize: "16px", iconSize: "24px", borderRadius: "8px" },
+    { size: "full", height: "100vh – 48px", paddingLR: "48px", fontSize: "16px", iconSize: "24px", borderRadius: "0px" },
+  ],
+
+  designTokenBindings: [
+    { property: "backdrop", tokenName: "color/overlay", role: "Semi-transparent background behind modal", fallback: "rgba(22,22,22,0.5)" },
+    { property: "surface", tokenName: "color/layer/01", role: "Modal container background", fallback: "#FFFFFF" },
+    { property: "header-text", tokenName: "color/text/primary", role: "Title and subtitle text", fallback: "#161616" },
+    { property: "border-bottom", tokenName: "color/border/subtle/01", role: "Divider between header and body", fallback: "#E0E0E0" },
+    { property: "close-icon", tokenName: "color/icon/primary", role: "Close button icon fill", fallback: "#161616" },
+    { property: "danger-button-bg", tokenName: "color/support/error", role: "Background of destructive primary action", fallback: "#DA1E28" },
+    { property: "shadow", tokenName: "shadow/raised/04", role: "Elevation shadow around modal container", fallback: "0 8px 24px rgba(0,0,0,0.2)" },
+  ],
+
+  structureRules: [
+    "Modal must use the native <dialog> element or role='dialog' with aria-modal='true'",
+    "Structure follows a three-zone layout: fixed header, scrollable body, fixed footer",
+    "Header contains title, optional subtitle, and close icon aligned to the end",
+    "Footer contains action buttons right-aligned; primary button comes last in DOM order",
+    "Backdrop is a sibling or pseudo-element that spans the entire viewport",
+    "Modal must be centered both vertically and horizontally with responsive margins",
+    "When content overflows, only the body zone scrolls — header and footer remain pinned",
+  ],
+
+  typeHierarchyRules: [
+    "Title uses heading-03 (20px/28px) to establish the modal's purpose immediately",
+    "Subtitle uses body-01 (14px/20px) in text-secondary color",
+    "Body content follows standard body-01 typography with 20px line-height",
+    "Footer button labels use body-compact-01 (14px) in uppercase or sentence case per system",
+    "Title must not exceed two lines — truncate with ellipsis if necessary",
+    "Ensure at least 16px vertical spacing between title and body content",
+    "Danger button label should use the same type style as primary but with inverse text color",
+  ],
+
+  interactionRules: [
+    { event: "keydown:Escape", trigger: "Modal is open and not preventCloseOnClickOutside", action: "Close the modal and return focus to the trigger element" },
+    { event: "click:backdrop", trigger: "User clicks outside modal surface", action: "Close modal unless preventCloseOnClickOutside is true" },
+    { event: "click:close-icon", trigger: "User clicks the X button", action: "Close modal and return focus to trigger" },
+    { event: "keydown:Tab", trigger: "Focus is on the last focusable element inside modal", action: "Wrap focus back to the first focusable element (focus trap)" },
+    { event: "keydown:Shift+Tab", trigger: "Focus is on the first focusable element", action: "Wrap focus to the last focusable element (reverse trap)" },
+    { event: "open", trigger: "Modal becomes visible", action: "Lock body scroll, move focus to selectorPrimaryFocus or first focusable element" },
+    { event: "close", trigger: "Modal is dismissed by any method", action: "Restore body scroll, return focus to the element that opened the modal" },
+  ],
+
+  contentGuidance: [
+    "Use a clear, action-oriented title — e.g. 'Delete project?' not 'Are you sure?'",
+    "Keep body content concise; modals are for focused tasks, not long-form reading",
+    "Primary button label should match the action described in the title — e.g. 'Delete' for 'Delete project?'",
+    "Secondary button should be a clear escape — 'Cancel' or 'Go back', never just 'No'",
+    "Avoid stacking modals on top of modals; redesign the flow if nesting is needed",
+    "For forms inside modals, validate inline and disable the primary button until valid",
+    "Danger modals should explicitly name the resource being affected in the body text",
+  ],
+
+  responsiveBehaviour: [
+    { breakpoint: "≥ 1056px (lg)", behavior: "Modal renders centered with defined width; backdrop visible" },
+    { breakpoint: "672–1055px (md)", behavior: "Modal width may increase to md or lg size; side margins shrink to 24px" },
+    { breakpoint: "< 672px (sm)", behavior: "Modal becomes full-width sheet docked to bottom or fills viewport" },
+    { breakpoint: "Landscape mobile", behavior: "Modal height capped at 80vh with scrollable body" },
+    { breakpoint: "Reduced motion", behavior: "Skip entrance/exit animations; modal appears/disappears instantly" },
+  ],
+
+  accessibilitySpec: {
+    intro:
+      "Modals must trap focus, lock background scrolling, and announce their purpose to assistive technologies. They represent a critical interruption pattern that must be fully keyboard operable.",
+    requirements: [
+      { requirement: "Container must have role='dialog' and aria-modal='true'", level: "A", notes: "Native <dialog> with showModal() provides this automatically" },
+      { requirement: "Must have an accessible name via aria-labelledby pointing to the title element", level: "A", notes: "aria-label is acceptable if no visible title exists" },
+      { requirement: "Focus must be trapped inside the modal while open", level: "A", notes: "Tab and Shift+Tab must cycle within modal boundaries" },
+      { requirement: "Escape key must close the modal", level: "A", notes: "Unless explicitly prevented for critical workflows like unsaved data" },
+      { requirement: "On close, focus must return to the element that triggered the modal", level: "A", notes: "Store a reference to document.activeElement before opening" },
+      { requirement: "Background content must be inert (aria-hidden or inert attribute)", level: "A", notes: "Prevents screen readers from accessing content behind the modal" },
+      { requirement: "Opening transition must respect prefers-reduced-motion", level: "AA", notes: "Disable or reduce animation duration to 0ms" },
+    ],
+    outro: [
+      "Test that VoiceOver announces the dialog title on open",
+      "Verify tab trapping with both Tab and Shift+Tab at modal boundaries",
+      "Confirm background scroll is locked on iOS Safari, which requires special handling",
+    ],
+  },
+
+  qaAcceptanceCriteria: [
+    { check: "Focus moves into modal on open", platform: "Web", expectedResult: "First focusable element or selectorPrimaryFocus receives focus" },
+    { check: "Tab key is trapped within modal", platform: "Web", expectedResult: "Focus cycles through modal elements only" },
+    { check: "Escape closes the modal", platform: "Web", expectedResult: "Modal dismissed, focus returns to trigger" },
+    { check: "Backdrop click closes modal", platform: "Web", expectedResult: "Modal dismissed unless preventCloseOnClickOutside is set" },
+    { check: "Body scroll is locked", platform: "All", expectedResult: "Page behind modal does not scroll on any device" },
+    { check: "Danger variant shows red primary button", platform: "All", expectedResult: "Button uses danger token, label remains legible" },
+    { check: "Long content scrolls inside body zone", platform: "All", expectedResult: "Header and footer stay fixed; only body scrolls" },
+  ],
+
+  dos: [
+    "Return focus to the triggering element when the modal closes",
+    "Provide a visible close affordance (X icon or cancel button) at all times",
+    "Use the danger variant when the action is destructive or irreversible",
+    "Keep modal content focused on a single task or decision",
+    "Apply inert or aria-hidden to all content behind the backdrop",
+    "Animate entrance and exit with a 200–300ms duration for smooth perception",
+    "Test with screen readers to confirm the title is announced on open",
+  ],
+
+  donts: [
+    "Don't open a modal from within another modal — flatten the flow instead",
+    "Don't use modals for simple confirmations that could be inline alerts",
+    "Don't auto-close modals on a timer — users need time to read and decide",
+    "Don't remove the backdrop — it provides critical visual context for layering",
+    "Don't place critical page-level navigation inside a modal",
+    "Don't allow background scrolling while the modal is open",
+    "Don't use a modal when the content would benefit from a full page layout",
+  ],
+};