@sarjallab09/figma-intelligence 1.0.0

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

@@ -0,0 +1,232 @@
+/**
+ * tooltip.ts — Gold-standard design knowledge for Tooltip components
+ */
+import type { ComponentKnowledge } from "../types.js";
+
+export const tooltipKnowledge: ComponentKnowledge = {
+  description:
+    "Contextual hint | Hover-triggered information overlay | Supplementary label",
+
+  stateSpecifications: [
+    {
+      state: "Hidden",
+      visualChange: "Tooltip is not rendered in the DOM or has opacity 0 and pointer-events none",
+      opacity: "0",
+      cursorWeb: "default",
+      usage: "Default state — tooltip is invisible until triggered by hover or focus",
+    },
+    {
+      state: "Visible",
+      visualChange: "Tooltip fades in with arrow pointer anchored to the trigger element; positioned above/below/left/right",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "User hovers or focuses the trigger element after the configured delay",
+    },
+    {
+      state: "Entering",
+      visualChange: "Tooltip fades in over 150ms with a subtle scale-up from 0.95 to 1.0",
+      opacity: "0 → 1",
+      cursorWeb: "default",
+      usage: "Transition state during the show animation after delay completes",
+    },
+    {
+      state: "Exiting",
+      visualChange: "Tooltip fades out over 100ms; faster than entry for responsive feel",
+      opacity: "1 → 0",
+      cursorWeb: "default",
+      usage: "Mouse leaves the trigger or focus moves away",
+    },
+    {
+      state: "Repositioned",
+      visualChange: "Tooltip flips to an alternate placement when clipped by viewport edge",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Automatic collision detection repositions the tooltip to stay fully visible",
+    },
+    {
+      state: "Persistent (Focus)",
+      visualChange: "Tooltip remains visible while the trigger element retains keyboard focus",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Keyboard user tabs to the trigger — tooltip stays until focus leaves",
+    },
+  ],
+
+  propertyDescriptions: {
+    content: "Plain text string displayed inside the tooltip; must be concise and non-interactive",
+    placement: "Preferred position relative to the trigger — top, bottom, left, or right; auto-flips on collision",
+    delayShow: "Milliseconds to wait after hover/focus before showing the tooltip (default 300ms)",
+    delayHide: "Milliseconds to wait after hover/focus leaves before hiding (default 100ms)",
+    hasArrow: "When true, a triangular pointer connects the tooltip bubble to its trigger element",
+    maxWidth: "Maximum width before text wraps; prevents overly wide tooltips (default 240px)",
+    triggerElement: "The interactive element that activates the tooltip on hover or focus",
+  },
+
+  sizeSpecifications: [
+    {
+      size: "Small",
+      height: "24px",
+      paddingLR: "8px",
+      fontSize: "11px",
+      iconSize: "12px",
+      borderRadius: "4px",
+    },
+    {
+      size: "Medium",
+      height: "32px",
+      paddingLR: "12px",
+      fontSize: "12px",
+      iconSize: "14px",
+      borderRadius: "6px",
+    },
+    {
+      size: "Large",
+      height: "auto",
+      paddingLR: "16px",
+      fontSize: "13px",
+      iconSize: "16px",
+      borderRadius: "8px",
+    },
+  ],
+
+  designTokenBindings: [
+    {
+      property: "Background",
+      tokenName: "$tooltip-bg",
+      role: "Dark fill for the tooltip bubble ensuring contrast with light pages",
+      fallback: "#1D2939",
+    },
+    {
+      property: "Text Color",
+      tokenName: "$tooltip-text",
+      role: "Light text on dark background for readability",
+      fallback: "#FFFFFF",
+    },
+    {
+      property: "Arrow Fill",
+      tokenName: "$tooltip-arrow",
+      role: "Matches the tooltip background to create a seamless pointer",
+      fallback: "#1D2939",
+    },
+    {
+      property: "Border Radius",
+      tokenName: "$radius-tooltip",
+      role: "Corner rounding for the tooltip bubble",
+      fallback: "6px",
+    },
+    {
+      property: "Shadow",
+      tokenName: "$shadow-tooltip",
+      role: "Subtle elevation shadow to lift tooltip above content",
+      fallback: "0 4px 12px rgba(0,0,0,0.15)",
+    },
+    {
+      property: "Font Family",
+      tokenName: "$font-family-sans",
+      role: "Tooltip text typeface matching the system font stack",
+      fallback: "Inter, system-ui, sans-serif",
+    },
+    {
+      property: "Z-Index",
+      tokenName: "$z-tooltip",
+      role: "Stacking order above all page content and below modals",
+      fallback: "1070",
+    },
+  ],
+
+  structureRules: [
+    "Tooltip renders in a portal at the document root to avoid clipping by parent overflow",
+    "Arrow element is a rotated square (45°) positioned at the tooltip edge closest to the trigger",
+    "Tooltip bubble uses padding on all four sides; vertical padding matches $spacing-xs (4px)",
+    "Text content is a single inline element — no block-level children or interactive elements",
+    "Positioning is calculated dynamically based on trigger element rect and viewport boundaries",
+    "Collision detection auto-flips placement (e.g., top → bottom) when space is insufficient",
+    "Tooltip width is auto-sized to content up to maxWidth, then text wraps",
+  ],
+
+  typeHierarchyRules: [
+    "Font size is one step below body text (12px default) — tooltips are supplementary",
+    "Font weight is Regular (400) — no bold or emphasis within tooltip text",
+    "Text uses sentence case — capitalize only the first word",
+    "Line height is 1.4 for comfortable reading when text wraps to multiple lines",
+    "No rich formatting (bold, italic, links) inside tooltip text — keep it plain",
+  ],
+
+  interactionRules: [
+    { event: "Mouse Enter", trigger: "pointerenter on trigger element", action: "Start show delay timer; show tooltip after delayShow ms" },
+    { event: "Mouse Leave", trigger: "pointerleave from trigger element", action: "Start hide delay timer; hide tooltip after delayHide ms" },
+    { event: "Focus", trigger: "focusin on trigger element", action: "Show tooltip immediately (no delay) for keyboard users" },
+    { event: "Blur", trigger: "focusout from trigger element", action: "Hide tooltip immediately" },
+    { event: "Escape", trigger: "Escape key while tooltip visible", action: "Dismiss tooltip immediately without waiting for delay" },
+    { event: "Scroll", trigger: "Scroll event on ancestor", action: "Reposition tooltip to maintain alignment; hide if trigger scrolls out of view" },
+    { event: "Touch", trigger: "Long press on mobile", action: "Show tooltip after 500ms hold; hide on release" },
+  ],
+
+  contentGuidance: [
+    "Tooltip text should be a brief label or description — 1 to 2 short sentences maximum",
+    "Never put essential information in a tooltip — it may be inaccessible to touch and screen reader users",
+    "Use tooltips for icon-only buttons, truncated text, or supplementary definitions",
+    "Avoid duplicating the trigger element's visible label — add new information only",
+    "Do not include interactive content (links, buttons, form fields) inside tooltips",
+    "Keep text under 80 characters; use a popover for longer content",
+  ],
+
+  responsiveBehaviour: [
+    { breakpoint: "Mobile (<768px)", behavior: "Tooltips on hover are inaccessible; use long-press or replace with inline hints" },
+    { breakpoint: "Tablet (768-1023px)", behavior: "Tooltips work on hover with stylus; ensure touch fallback is available" },
+    { breakpoint: "Desktop (1024-1439px)", behavior: "Standard hover/focus tooltip behavior; preferred placement honored" },
+    { breakpoint: "Ultra-wide (>=1440px)", behavior: "Tooltip positioning unchanged; max-width prevents overly wide bubbles" },
+  ],
+
+  accessibilitySpec: {
+    intro:
+      "Tooltips provide supplementary information and must be accessible via keyboard and screen readers without requiring hover.",
+    requirements: [
+      { requirement: "aria-describedby", level: "A", notes: "Trigger element must reference the tooltip ID via aria-describedby so screen readers announce the hint" },
+      { requirement: "role='tooltip'", level: "A", notes: "The tooltip container must have role='tooltip' for proper semantic identification" },
+      { requirement: "Keyboard Dismissal", level: "A", notes: "Escape key must dismiss the tooltip without moving focus" },
+      { requirement: "Focus Trigger", level: "A", notes: "Tooltip must appear on focus (not just hover) for keyboard-only users" },
+      { requirement: "Contrast", level: "AA", notes: "Tooltip text to background must meet 4.5:1; tooltip boundary to page must meet 3:1" },
+      { requirement: "Timing", level: "A", notes: "Tooltip must remain visible while trigger is hovered or focused — no auto-dismiss timer" },
+      { requirement: "No Interactive Content", level: "A", notes: "Tooltip must not contain focusable or interactive elements; use a popover instead" },
+    ],
+    outro: [
+      "Screen readers should announce the tooltip text as a description of the trigger element",
+      "Ensure the tooltip does not obscure the trigger element or other critical content",
+    ],
+  },
+
+  qaAcceptanceCriteria: [
+    { check: "Show Delay", platform: "Web", expectedResult: "Tooltip appears after configured delayShow (default 300ms); no instant flash" },
+    { check: "Hide Delay", platform: "Web", expectedResult: "Tooltip disappears after delayHide (default 100ms) once hover/focus leaves" },
+    { check: "Placement", platform: "Web", expectedResult: "Tooltip renders at the specified placement (top/bottom/left/right) relative to trigger" },
+    { check: "Collision Flip", platform: "Web", expectedResult: "Tooltip auto-flips when preferred placement would clip the viewport" },
+    { check: "Arrow Alignment", platform: "All", expectedResult: "Arrow pointer points directly at the trigger center and matches tooltip background" },
+    { check: "Keyboard Access", platform: "Web", expectedResult: "Tooltip shows on focus; Escape dismisses; does not trap focus" },
+    { check: "Screen Reader", platform: "Web", expectedResult: "Announces tooltip text as description of the trigger via aria-describedby" },
+    { check: "Max Width Wrap", platform: "Web", expectedResult: "Text wraps at maxWidth; tooltip height grows to accommodate wrapped lines" },
+    { check: "Portal Rendering", platform: "Web", expectedResult: "Tooltip renders in document root portal; not clipped by parent overflow:hidden" },
+    { check: "Touch Devices", platform: "Mobile", expectedResult: "Long press shows tooltip; release hides it; no hover dependency" },
+    { check: "Reduced Motion", platform: "Web", expectedResult: "Fade animation disabled when prefers-reduced-motion is set" },
+  ],
+
+  dos: [
+    "Use tooltips for short, supplementary hints that clarify an element's purpose",
+    "Provide tooltips on icon-only buttons with matching aria-label text",
+    "Keep tooltip text concise — under 80 characters or two short sentences",
+    "Include a visible arrow pointer connecting the tooltip to its trigger",
+    "Use a dark background with light text for strong contrast",
+    "Allow Escape key to dismiss the tooltip at any time",
+    "Test tooltip positioning near viewport edges to verify collision handling",
+  ],
+
+  donts: [
+    "Do not put essential or actionable information inside tooltips",
+    "Do not include links, buttons, or form elements inside tooltip content",
+    "Do not use tooltips as a substitute for visible labels or helper text",
+    "Do not set show delay below 200ms — accidental triggers are disruptive",
+    "Do not auto-dismiss tooltips on a timer — let the user control visibility",
+    "Do not rely on hover-only triggers — keyboard and touch users cannot hover",
+    "Do not allow tooltips to obscure the content they describe",
+  ],
+};

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

@@ -0,0 +1,257 @@
+/**
+ * treeview.ts — Gold-standard design knowledge for Treeview components
+ */
+import type { ComponentKnowledge } from "../types.js";
+
+export const treeviewKnowledge: ComponentKnowledge = {
+  description:
+    "Hierarchical expandable tree | Displays nested parent-child relationships | Supports single and multi-selection with full keyboard navigation",
+
+  stateSpecifications: [
+    {
+      state: "Expanded",
+      visualChange: "Chevron icon rotates 90 degrees clockwise; child nodes are revealed with indented layout below the parent",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Parent node has been opened to show its children — aria-expanded='true'",
+    },
+    {
+      state: "Collapsed",
+      visualChange: "Chevron icon points to the right (0 degrees); child nodes are hidden from view",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Parent node is closed — its children are not rendered or are display-none; aria-expanded='false'",
+    },
+    {
+      state: "Selected",
+      visualChange: "Node row has a tinted background using $treeview-selected-bg; text may use primary accent color",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Node has been chosen by the user; in multi-select mode a checkbox indicator is shown",
+    },
+    {
+      state: "Disabled",
+      visualChange: "Node text and icons use muted/disabled tokens; expand/collapse still works but selection is blocked",
+      opacity: "0.4",
+      cursorWeb: "not-allowed",
+      usage: "Individual node is non-selectable due to permissions or unavailability; children may still be accessible",
+    },
+    {
+      state: "Focus",
+      visualChange: "2px focus ring around the focused node row using $focus-ring token; background may subtly highlight",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Node receives keyboard focus via Tab entry or arrow key navigation within the tree",
+    },
+  ],
+
+  propertyDescriptions: {
+    data: "Nested array of tree node objects; each node has an id, label, optional icon, optional children array, and optional disabled flag",
+    selection: "Selection mode — 'single' allows one node selected at a time, 'multi' allows multiple with checkboxes, 'none' disables selection entirely",
+    expandedKeys: "Controlled array of node IDs that are currently expanded; used for controlled expand/collapse behavior",
+    onExpand: "Callback fired when a node is expanded or collapsed; receives the node ID and new expanded state",
+    onSelect: "Callback fired when a node is selected or deselected; receives the node ID and selection state",
+    size: "Dimensional preset controlling node row height, indent depth, font-size, and icon-size (sm, md, lg)",
+    defaultExpandedKeys: "Array of node IDs that should be expanded on initial render (uncontrolled mode)",
+    draggable: "When true, nodes can be reordered via drag-and-drop; fires onMove callback with source and target",
+    showLines: "When true, renders vertical indent guide lines connecting parent to children for visual hierarchy",
+    loadOnExpand: "When true, children are loaded asynchronously on expand; shows a spinner in place of children while loading",
+  },
+
+  sizeSpecifications: [
+    {
+      size: "Small",
+      height: "28px per node",
+      paddingLR: "8px",
+      fontSize: "12px",
+      iconSize: "14px",
+      borderRadius: "4px",
+    },
+    {
+      size: "Medium",
+      height: "36px per node",
+      paddingLR: "12px",
+      fontSize: "14px",
+      iconSize: "18px",
+      borderRadius: "6px",
+    },
+    {
+      size: "Large",
+      height: "44px per node",
+      paddingLR: "16px",
+      fontSize: "16px",
+      iconSize: "22px",
+      borderRadius: "8px",
+    },
+  ],
+
+  designTokenBindings: [
+    {
+      property: "Node Background",
+      tokenName: "$treeview-node-bg",
+      role: "Default background for each tree node row",
+      fallback: "transparent",
+    },
+    {
+      property: "Hover Background",
+      tokenName: "$treeview-hover-bg",
+      role: "Background applied on hover for interactive nodes",
+      fallback: "#F2F4F7",
+    },
+    {
+      property: "Selected Background",
+      tokenName: "$treeview-selected-bg",
+      role: "Background tint for selected nodes",
+      fallback: "#EFF8FF",
+    },
+    {
+      property: "Node Text",
+      tokenName: "$treeview-node-text",
+      role: "Primary text color for node labels",
+      fallback: "#101828",
+    },
+    {
+      property: "Expand Icon",
+      tokenName: "$treeview-expand-icon",
+      role: "Color of the chevron/expand toggle icon",
+      fallback: "#667085",
+    },
+    {
+      property: "Indent Guide",
+      tokenName: "$treeview-indent-line",
+      role: "Color of the vertical indent guide lines between parent and children",
+      fallback: "#E4E7EC",
+    },
+    {
+      property: "Selected Accent",
+      tokenName: "$treeview-selected-accent",
+      role: "Accent color for selection indicator (checkmark or left border)",
+      fallback: "#2563EB",
+    },
+    {
+      property: "Focus Ring",
+      tokenName: "$focus-ring",
+      role: "Keyboard focus indicator ring on focused node",
+      fallback: "0 0 0 2px #FFFFFF, 0 0 0 4px #2E90FA",
+    },
+    {
+      property: "Indent Width",
+      tokenName: "$treeview-indent",
+      role: "Horizontal indent per nesting level",
+      fallback: "24px",
+    },
+    {
+      property: "Font Family",
+      tokenName: "$font-family-sans",
+      role: "Typeface for node labels",
+      fallback: "Inter, system-ui, sans-serif",
+    },
+  ],
+
+  structureRules: [
+    "Root container has role='tree' and uses vertical Auto Layout with no gap — spacing is handled by node row padding",
+    "Each node row is a horizontal Auto Layout: indent spacer, expand icon (if parent), optional node icon, label text, optional trailing content",
+    "Indent spacer width equals nesting depth multiplied by the $treeview-indent token (e.g. depth 2 = 48px)",
+    "Expand/collapse icon is only rendered for nodes with children; leaf nodes replace it with an equal-width spacer",
+    "Child nodes are nested inside the parent's vertical stack and are conditionally rendered based on expanded state",
+    "Multi-select mode adds a checkbox component before the node label; checkbox state mirrors selection state",
+    "Indent guide lines are absolutely positioned 1px-wide vertical lines from parent expand icon to last child",
+    "Drag handle appears as a leading grip icon when draggable is true; visible on hover only",
+  ],
+
+  typeHierarchyRules: [
+    "Node labels use Regular (400) weight for all items; selected nodes may use Medium (500) for emphasis",
+    "Font size is consistent across all nesting depths — do not reduce font-size for deeper nodes",
+    "Labels truncate with ellipsis on overflow; tooltip shows full label on hover for truncated text",
+    "Expand/collapse icon uses a consistent size regardless of the node label font-size",
+  ],
+
+  interactionRules: [
+    { event: "Click Expand Icon", trigger: "pointerup on the chevron/expand toggle", action: "Toggle expanded state of the node; fire onExpand callback" },
+    { event: "Click Node Label", trigger: "pointerup on the node label or row", action: "Select/deselect the node; fire onSelect callback (if selection != 'none')" },
+    { event: "Hover", trigger: "pointerenter on a node row", action: "Apply hover background token to the full-width row" },
+    { event: "Focus", trigger: "Tab enters the tree or arrow key moves focus", action: "Show focus ring on the focused node row" },
+    { event: "Keydown Arrow Down", trigger: "Down arrow while a node is focused", action: "Move focus to the next visible node (skips collapsed children)" },
+    { event: "Keydown Arrow Up", trigger: "Up arrow while a node is focused", action: "Move focus to the previous visible node" },
+    { event: "Keydown Arrow Right", trigger: "Right arrow on a collapsed parent node", action: "Expand the node; if already expanded, move focus to first child" },
+    { event: "Keydown Arrow Left", trigger: "Left arrow on an expanded parent node", action: "Collapse the node; if already collapsed or on leaf, move focus to parent" },
+    { event: "Keydown Enter", trigger: "Enter key while a node is focused", action: "Select/activate the focused node (same as click on label)" },
+    { event: "Keydown Space", trigger: "Space key while a node is focused", action: "Toggle selection on the focused node in multi-select mode" },
+    { event: "Keydown Home", trigger: "Home key while in tree", action: "Move focus to the first visible node in the tree" },
+    { event: "Keydown End", trigger: "End key while in tree", action: "Move focus to the last visible node in the tree" },
+    { event: "Keydown Asterisk", trigger: "* key while a parent node is focused", action: "Expand all sibling nodes at the same level" },
+  ],
+
+  contentGuidance: [
+    "Node labels should be concise and descriptive — represent the item clearly (file name, category, section title)",
+    "Use icons consistently: either all nodes at a level have icons, or none do — avoid mixing",
+    "Limit nesting depth to 4-5 levels for usability; deeper hierarchies become difficult to navigate",
+    "Parent nodes with loadable children should show a loading indicator (spinner) during async fetch",
+    "Use clear expand/collapse affordance — the chevron icon is the standard convention",
+    "For file-tree patterns, use distinct icons for folders (parent nodes) and files (leaf nodes)",
+    "Group related items under meaningful parent labels that describe the category or section",
+  ],
+
+  responsiveBehaviour: [
+    { breakpoint: "Mobile (<768px)", behavior: "Consider replacing tree with a drill-down navigation pattern; if tree is used, reduce indent width and allow horizontal scroll" },
+    { breakpoint: "Tablet (768-1023px)", behavior: "Tree fits in sidebar panels; ensure touch targets are at least 44px; indent guides help distinguish depth" },
+    { breakpoint: "Desktop (1024-1439px)", behavior: "Full tree with standard indent width; ideal for file browsers, settings panels, and navigation sidebars" },
+    { breakpoint: "Ultra-wide (>=1440px)", behavior: "Tree width should be constrained in a sidebar; do not allow the tree to stretch to fill wide content areas" },
+  ],
+
+  accessibilitySpec: {
+    intro:
+      "Treeview is one of the most complex ARIA patterns. It requires precise role assignment, keyboard navigation following the WAI-ARIA TreeView pattern, and correct state management for expanded, selected, and disabled nodes.",
+    requirements: [
+      { requirement: "Tree Role", level: "A", notes: "Root container must have role='tree'; each node must have role='treeitem'" },
+      { requirement: "Expanded State", level: "A", notes: "Parent nodes must have aria-expanded='true' or 'false'; leaf nodes must not have aria-expanded" },
+      { requirement: "Arrow Key Navigation", level: "A", notes: "Up/Down moves focus between visible nodes; Right expands or enters children; Left collapses or moves to parent" },
+      { requirement: "Home/End Keys", level: "A", notes: "Home moves focus to first node; End moves to last visible node in the tree" },
+      { requirement: "Selection State", level: "A", notes: "Selected nodes must have aria-selected='true'; multi-select trees use aria-multiselectable='true' on the root" },
+      { requirement: "Nesting Structure", level: "A", notes: "Child nodes must be grouped in a role='group' container nested inside the parent treeitem" },
+      { requirement: "Contrast Ratio", level: "AA", notes: "Node text: 4.5:1; expand icon: 3:1 non-text; selected indicator: 3:1 non-text contrast" },
+      { requirement: "Touch Target", level: "AA", notes: "Each node row must have at least 44px height for touch interaction; expand icon target at least 24x24px" },
+    ],
+    outro: [
+      "Focus must remain on the correct node after expand/collapse operations — do not reset focus to the root",
+      "When nodes are loaded asynchronously, use aria-busy='true' on the parent node during loading",
+      "Type-ahead is recommended: typing a character should move focus to the next node whose label starts with that character",
+    ],
+  },
+
+  qaAcceptanceCriteria: [
+    { check: "Visual Regression", platform: "All", expectedResult: "Tree renders pixel-perfect against baseline for each size variant and nesting depth" },
+    { check: "Expand/Collapse", platform: "All", expectedResult: "Chevron rotates; children appear/disappear smoothly; aria-expanded updates correctly" },
+    { check: "Selection State", platform: "All", expectedResult: "Selected nodes show tinted background; aria-selected is true; deselection works" },
+    { check: "Multi-select", platform: "Web", expectedResult: "Checkboxes appear; Space toggles selection; Ctrl+Click extends selection" },
+    { check: "Disabled Nodes", platform: "All", expectedResult: "Muted visuals; expand still works; selection is blocked; aria-disabled='true'" },
+    { check: "Keyboard Down/Up", platform: "Web", expectedResult: "Arrow keys move focus to next/previous visible node; skips collapsed children" },
+    { check: "Keyboard Right/Left", platform: "Web", expectedResult: "Right expands or enters children; Left collapses or moves to parent; works on all depths" },
+    { check: "Keyboard Home/End", platform: "Web", expectedResult: "Home focuses first node; End focuses last visible node" },
+    { check: "Focus Ring", platform: "Web", expectedResult: "Focus ring visible on keyboard navigation; hidden on mouse click (focus-visible)" },
+    { check: "Screen Reader", platform: "Web", expectedResult: "Announces role 'tree'/'treeitem', expanded state, selected state, level, set size, and position" },
+    { check: "Indent Guide Lines", platform: "All", expectedResult: "Lines connect parent to children when showLines=true; hidden when false" },
+    { check: "Async Loading", platform: "Web", expectedResult: "Spinner shown while children load; aria-busy on parent; children appear after fetch" },
+    { check: "RTL Support", platform: "Web", expectedResult: "Indent direction mirrors; chevron direction swaps; layout alignment correct" },
+  ],
+
+  dos: [
+    "Use treeview for hierarchical data: file systems, nested categories, organizational structures",
+    "Always provide the expand/collapse chevron affordance for parent nodes — do not rely on double-click alone",
+    "Implement full WAI-ARIA TreeView keyboard pattern including arrow keys, Home, End, and type-ahead",
+    "Use indent guide lines (showLines) for deep hierarchies to help users track parent-child relationships",
+    "Pre-expand the most relevant branch on initial load so users see useful content immediately",
+    "Keep node labels concise and scannable — the hierarchy itself provides context",
+    "Use consistent icons across the same level of nesting",
+  ],
+
+  donts: [
+    "Do not use treeview for flat lists — use a list or menu component instead",
+    "Do not nest deeper than 5 levels — consider a different navigation pattern for deeply nested data",
+    "Do not auto-collapse sibling nodes when expanding a node unless explicitly required (accordion tree)",
+    "Do not use different font sizes for different nesting depths — keep typography consistent",
+    "Do not render hundreds of nodes without virtualization — performance will degrade significantly",
+    "Do not make leaf nodes appear as if they are expandable (no chevron on leaf nodes)",
+    "Do not remove focus from the tree during expand/collapse transitions — focus must remain stable",
+  ],
+};