@sarjallab09/figma-intelligence 1.0.0

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

@@ -0,0 +1,238 @@
+/**
+ * grid.ts — Gold-standard design knowledge for Grid layout components
+ */
+import type { ComponentKnowledge } from "../types.js";
+
+export const gridKnowledge: ComponentKnowledge = {
+  description:
+    "CSS Grid-based layout container | Structures content in rows and columns | Purely presentational with no interactive states",
+
+  stateSpecifications: [
+    {
+      state: "Default",
+      visualChange: "Grid container renders its children according to the configured column, gap, and alignment properties; no visible chrome",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Only state — the grid is a passive structural container with no interactive or visual state changes",
+    },
+    {
+      state: "Empty",
+      visualChange: "Grid container renders with no children; may collapse to zero height or show a minimum height placeholder depending on implementation",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "No content has been placed in the grid — container remains in the DOM for layout stability",
+    },
+    {
+      state: "Loading",
+      visualChange: "Grid cells display skeleton placeholders in the configured layout pattern to maintain visual structure during data fetch",
+      opacity: "0.6",
+      cursorWeb: "default",
+      usage: "Child content is being loaded — skeleton cells preview the eventual layout",
+    },
+  ],
+
+  propertyDescriptions: {
+    columns: "Number of equal-width columns in the grid — integer from 1 to 12; maps to CSS grid-template-columns: repeat(N, 1fr)",
+    gap: "Spacing between grid cells — Small (8px), Medium (16px), or Large (24px); applies equally to row and column gaps",
+    rowGap: "Overrides the vertical gap between grid rows independently of the column gap; useful for asymmetric spacing",
+    columnGap: "Overrides the horizontal gap between grid columns independently of the row gap",
+    alignItems: "Vertical alignment of items within their grid cells — start, center, end, stretch (default stretch)",
+    justifyItems: "Horizontal alignment of items within their grid cells — start, center, end, stretch (default stretch)",
+    responsive: "When true the grid automatically reduces columns at smaller breakpoints following the responsive rules",
+    minColumnWidth: "Minimum width for each column before the grid reflows to fewer columns — alternative to fixed column count",
+    autoRows: "Height of implicitly created rows — 'auto' (content-sized) or a fixed value like '200px' or 'minmax(100px, auto)'",
+    templateAreas: "Named grid areas for semantic placement of children — maps to CSS grid-template-areas property",
+    fullBleed: "When true the grid spans the full viewport width, breaking out of its parent container constraints",
+    dense: "When true enables CSS grid auto-flow: dense to fill gaps left by items spanning multiple columns",
+  },
+
+  sizeSpecifications: [
+    {
+      size: "Small Gap",
+      height: "N/A (container)",
+      paddingLR: "0px",
+      fontSize: "N/A",
+      iconSize: "N/A",
+      borderRadius: "0px",
+    },
+    {
+      size: "Medium Gap",
+      height: "N/A (container)",
+      paddingLR: "0px",
+      fontSize: "N/A",
+      iconSize: "N/A",
+      borderRadius: "0px",
+    },
+    {
+      size: "Large Gap",
+      height: "N/A (container)",
+      paddingLR: "0px",
+      fontSize: "N/A",
+      iconSize: "N/A",
+      borderRadius: "0px",
+    },
+  ],
+
+  designTokenBindings: [
+    {
+      property: "Gap Small",
+      tokenName: "$spacing-sm",
+      role: "8px gap between grid cells in the small gap preset",
+      fallback: "8px",
+    },
+    {
+      property: "Gap Medium",
+      tokenName: "$spacing-md",
+      role: "16px gap between grid cells in the medium gap preset",
+      fallback: "16px",
+    },
+    {
+      property: "Gap Large",
+      tokenName: "$spacing-lg",
+      role: "24px gap between grid cells in the large gap preset",
+      fallback: "24px",
+    },
+    {
+      property: "Gap Extra-Large",
+      tokenName: "$spacing-xl",
+      role: "32px gap between grid cells for wide-spacing layouts",
+      fallback: "32px",
+    },
+    {
+      property: "Page Margin",
+      tokenName: "$grid-page-margin",
+      role: "Horizontal margin between the grid container and the viewport edge",
+      fallback: "24px",
+    },
+    {
+      property: "Max Width",
+      tokenName: "$grid-max-width",
+      role: "Maximum width of the grid container — prevents overly wide layouts on ultra-wide screens",
+      fallback: "1280px",
+    },
+    {
+      property: "Breakpoint SM",
+      tokenName: "$breakpoint-sm",
+      role: "Small breakpoint threshold for responsive column reduction",
+      fallback: "640px",
+    },
+    {
+      property: "Breakpoint MD",
+      tokenName: "$breakpoint-md",
+      role: "Medium breakpoint threshold for responsive column reduction",
+      fallback: "768px",
+    },
+    {
+      property: "Breakpoint LG",
+      tokenName: "$breakpoint-lg",
+      role: "Large breakpoint threshold for responsive column count",
+      fallback: "1024px",
+    },
+    {
+      property: "Breakpoint XL",
+      tokenName: "$breakpoint-xl",
+      role: "Extra-large breakpoint threshold where the full column count applies",
+      fallback: "1280px",
+    },
+  ],
+
+  structureRules: [
+    "Grid container is a block-level element using display: grid — never display: flex for grid layouts",
+    "Columns are defined via grid-template-columns: repeat(N, 1fr) where N is the columns property value",
+    "Gap applies to both row-gap and column-gap equally unless rowGap or columnGap overrides are provided",
+    "Grid children can span multiple columns using gridColumn: span N — the grid adjusts row wrapping accordingly",
+    "Page margin is applied as horizontal padding on the grid container — content stays within the maxWidth boundary",
+    "The grid container centers itself within its parent when maxWidth is less than available width using margin: 0 auto",
+    "Full-bleed items break out of the grid margin using negative margins equal to the page margin value",
+    "When responsive is true, the grid uses CSS clamp() or media queries to reduce columns at smaller viewports",
+    "Grid does not have visible borders, backgrounds, or decoration — it is purely a structural layout primitive",
+  ],
+
+  typeHierarchyRules: [
+    "Grid does not impose typography rules — child components manage their own text styling",
+    "Headings within grid cells should follow the page's heading hierarchy — do not skip levels (h1 > h2 > h3)",
+    "Card titles in a grid should all be the same heading level for semantic consistency within the grid",
+    "Text alignment within grid cells should align with the justifyItems property for visual consistency",
+  ],
+
+  interactionRules: [
+    { event: "Resize Viewport", trigger: "Browser window resize event", action: "Reflow grid columns according to responsive breakpoint rules; gap values remain constant" },
+    { event: "Content Overflow", trigger: "Child content exceeds cell bounds", action: "Cell stretches vertically to accommodate content; sibling cells in the same row align accordingly" },
+    { event: "Column Span", trigger: "Child element specifies gridColumn: span N", action: "Item spans N columns; subsequent items reflow around it" },
+    { event: "Dense Packing", trigger: "dense property enabled with variable-span items", action: "Grid auto-placement fills gaps left by spanning items, reducing whitespace" },
+    { event: "Skeleton Load", trigger: "Data loading for grid children", action: "Skeleton placeholder cells render in the grid layout maintaining the expected visual structure" },
+  ],
+
+  contentGuidance: [
+    "Use the grid for page-level layout, card grids, image galleries, and any repeating content arrangement",
+    "Choose column counts that create comfortable reading widths — 3-4 columns for cards, 2 columns for content-heavy layouts",
+    "Maintain consistent gap sizes across grids within the same page for visual rhythm",
+    "Avoid deeply nesting grids inside grids — one level of nesting is acceptable; two levels indicate overengineering",
+    "Use named grid areas (templateAreas) for complex page layouts where semantic placement is more readable than numeric spans",
+    "Grid is a layout primitive — it should not contain application logic or manage component state",
+    "For single-dimension layouts (a row of items or a column of items), prefer Flexbox over Grid",
+  ],
+
+  responsiveBehaviour: [
+    { breakpoint: "Mobile (<640px)", behavior: "Grid collapses to 1 column; all items stack vertically; gap remains consistent; page margin reduces to 16px" },
+    { breakpoint: "Small Tablet (640-767px)", behavior: "Grid uses 2 columns for content that was 3+ columns; gap and alignment maintained" },
+    { breakpoint: "Tablet (768-1023px)", behavior: "Grid uses approximately half the desktop column count (e.g., 6-column becomes 3-column)" },
+    { breakpoint: "Desktop (1024-1279px)", behavior: "Grid uses the full specified column count; page margins and max-width apply normally" },
+    { breakpoint: "Ultra-wide (>=1280px)", behavior: "Grid container width capped at maxWidth; centered on the viewport with auto margins" },
+  ],
+
+  accessibilitySpec: {
+    intro:
+      "Grid is a purely structural layout component with no interactive role. Accessibility concerns are limited to ensuring the DOM order matches visual order and that grid children are properly accessible.",
+    requirements: [
+      { requirement: "No ARIA Role", level: "A", notes: "Grid containers should not use role='grid' — that ARIA role is for interactive data grids (tables); layout grids use no role" },
+      { requirement: "DOM Order", level: "A", notes: "Visual order of grid items must match DOM order — CSS grid ordering (order property) must not break reading/tab sequence" },
+      { requirement: "Heading Hierarchy", level: "A", notes: "Headings within grid cells must follow the page heading hierarchy — no skipping levels" },
+      { requirement: "Landmark Nesting", level: "A", notes: "Grid cells containing landmarks (nav, main, aside) must follow proper landmark nesting rules" },
+      { requirement: "Content Reflow", level: "AA", notes: "At 400% zoom grid must reflow to a single column without horizontal scrolling (WCAG 1.4.10)" },
+      { requirement: "Focus Order", level: "A", notes: "Tab order through grid children must follow a logical reading sequence (left-to-right, top-to-bottom for LTR)" },
+      { requirement: "Spacing for Readability", level: "AAA", notes: "Gap spacing should allow clear visual separation between items for users with cognitive disabilities" },
+    ],
+    outro: [
+      "Verify that CSS grid ordering (order, grid-row, grid-column) does not create a disconnect between DOM and visual order",
+      "Test at 200% and 400% zoom to ensure content reflows gracefully without overflow or overlap",
+      "Ensure that screen readers traverse grid children in the intended reading order",
+    ],
+  },
+
+  qaAcceptanceCriteria: [
+    { check: "Column Count", platform: "Web", expectedResult: "Grid renders the specified number of equal-width columns with correct fr units" },
+    { check: "Gap Spacing", platform: "Web", expectedResult: "Row and column gaps match the specified token value (8/16/24px)" },
+    { check: "Responsive Reflow", platform: "Web", expectedResult: "Grid reduces columns at each breakpoint threshold; single column on mobile" },
+    { check: "Column Span", platform: "Web", expectedResult: "Items with gridColumn: span N correctly span multiple columns and reflow neighbors" },
+    { check: "Alignment", platform: "Web", expectedResult: "alignItems and justifyItems correctly position children within their cells" },
+    { check: "Max Width", platform: "Web", expectedResult: "Grid container does not exceed maxWidth; centers within viewport on ultra-wide screens" },
+    { check: "Dense Packing", platform: "Web", expectedResult: "With dense enabled, gaps left by spanning items are filled by subsequent items" },
+    { check: "DOM Order", platform: "Web", expectedResult: "Tab order matches visual order — no visual/DOM order mismatch" },
+    { check: "Zoom Reflow", platform: "Web", expectedResult: "At 400% zoom grid reflows to single column without horizontal scrollbar" },
+    { check: "Skeleton Loading", platform: "Web", expectedResult: "Skeleton placeholders render in the correct grid layout positions" },
+    { check: "RTL Support", platform: "Web", expectedResult: "Grid items flow right-to-left in RTL locales; alignment properties mirror correctly" },
+    { check: "Empty State", platform: "Web", expectedResult: "Empty grid renders without errors; may show minimum height or collapse gracefully" },
+    { check: "Visual Regression", platform: "All", expectedResult: "Grid layout renders pixel-perfect against baseline for each column/gap configuration" },
+  ],
+
+  dos: [
+    "Use Grid for two-dimensional layouts — rows and columns working together",
+    "Choose gap sizes from the spacing token scale for visual consistency with the rest of the design system",
+    "Use responsive breakpoints to reduce column counts progressively on smaller screens",
+    "Set a maxWidth on the grid container to prevent overly wide layouts on ultra-wide monitors",
+    "Use named grid areas for complex page-level layouts with semantically meaningful region names",
+    "Ensure DOM order matches visual order — avoid CSS order property when it breaks the reading sequence",
+    "Constrain the grid container with page margins that follow the design system spacing scale",
+  ],
+
+  donts: [
+    "Do not use role='grid' on layout grids — role='grid' is reserved for interactive data grids and tables",
+    "Do not nest grids more than one level deep — flatten the layout or reconsider the information architecture",
+    "Do not use CSS grid for simple single-row or single-column layouts — use Flexbox instead",
+    "Do not use the CSS order property in ways that create a mismatch between visual and DOM/tab order",
+    "Do not apply decorative styles (backgrounds, borders, shadows) to the grid container itself — it is invisible chrome",
+    "Do not hardcode pixel widths for columns — use fractional units (1fr) for fluid, responsive behavior",
+    "Do not allow grid content to cause horizontal scrolling at any supported viewport width or zoom level",
+  ],
+};

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

@@ -0,0 +1,255 @@
+/**
+ * icon.ts — Gold-standard design knowledge for Icon components
+ */
+import type { ComponentKnowledge } from "../types.js";
+
+export const iconKnowledge: ComponentKnowledge = {
+  description:
+    "Vector graphic primitive | Visual symbol | Non-interactive glyph used across all other components",
+
+  stateSpecifications: [
+    {
+      state: "Default",
+      visualChange: "Icon renders at specified size and color with full opacity",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Standard icon display — inherits color from parent or uses explicit override",
+    },
+    {
+      state: "Disabled",
+      visualChange: "Icon color shifts to disabled token; reduced opacity inherited from parent",
+      opacity: "0.4",
+      cursorWeb: "not-allowed",
+      usage: "Parent component is disabled — icon reflects that state passively",
+    },
+    {
+      state: "Decorative",
+      visualChange: "Visually identical to Default but semantically hidden from assistive technology",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Icon is purely ornamental and conveys no meaning beyond the adjacent text",
+    },
+    {
+      state: "Informative",
+      visualChange: "Visually identical to Default but carries an accessible label for screen readers",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Icon conveys meaning on its own without adjacent text — requires aria-label",
+    },
+    {
+      state: "Inherited Hover",
+      visualChange: "Icon color may shift when parent element enters hover state — not self-triggered",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Parent interactive element is hovered — icon inherits the color change",
+    },
+    {
+      state: "Inherited Focus",
+      visualChange: "No visual change on the icon itself — focus ring is on the parent element",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Parent interactive element is focused — icon remains visually unchanged",
+    },
+    {
+      state: "High Contrast",
+      visualChange: "Icon color overridden to system foreground color in forced-colors mode",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Windows High Contrast Mode — icon must remain visible against system background",
+    },
+  ],
+
+  propertyDescriptions: {
+    name: "Icon identifier matching the icon library glyph name (e.g., 'close', 'chevron-down', 'search')",
+    size: "Dimensional preset controlling the icon's width and height — xs through xl",
+    color: "Explicit color override; when omitted, the icon inherits currentColor from its parent",
+    decorative: "Boolean flag — when true, icon is aria-hidden and excluded from the accessibility tree",
+    label: "Accessible label for meaningful (non-decorative) icons — sets aria-label on the SVG element",
+    type: "Visual style variant — filled (solid shapes) or outlined (stroke-based paths)",
+    className: "Optional CSS class for custom styling overrides on the SVG wrapper element",
+    rotate: "Rotation angle in degrees — used for directional icons (chevrons, arrows) without needing separate glyphs",
+    flip: "Horizontal or vertical mirror — used for RTL layout support or directional variations",
+  },
+
+  sizeSpecifications: [
+    {
+      size: "Extra Small (xs)",
+      height: "16px",
+      paddingLR: "0px",
+      fontSize: "N/A",
+      iconSize: "16px",
+      borderRadius: "0px",
+    },
+    {
+      size: "Small (sm)",
+      height: "20px",
+      paddingLR: "0px",
+      fontSize: "N/A",
+      iconSize: "20px",
+      borderRadius: "0px",
+    },
+    {
+      size: "Medium (md)",
+      height: "24px",
+      paddingLR: "0px",
+      fontSize: "N/A",
+      iconSize: "24px",
+      borderRadius: "0px",
+    },
+    {
+      size: "Large (lg)",
+      height: "32px",
+      paddingLR: "0px",
+      fontSize: "N/A",
+      iconSize: "32px",
+      borderRadius: "0px",
+    },
+    {
+      size: "Extra Large (xl)",
+      height: "40px",
+      paddingLR: "0px",
+      fontSize: "N/A",
+      iconSize: "40px",
+      borderRadius: "0px",
+    },
+  ],
+
+  designTokenBindings: [
+    {
+      property: "Default Color",
+      tokenName: "color/semantic/icon/default",
+      role: "Inherited icon color when no explicit override is set — maps to currentColor",
+      fallback: "#1D2939",
+    },
+    {
+      property: "Primary Color",
+      tokenName: "color/semantic/icon/primary",
+      role: "Brand-primary icon color for emphasis or active state indicators",
+      fallback: "#2563EB",
+    },
+    {
+      property: "Secondary Color",
+      tokenName: "color/semantic/icon/secondary",
+      role: "Muted icon color for supporting or de-emphasized icons",
+      fallback: "#667085",
+    },
+    {
+      property: "Disabled Color",
+      tokenName: "color/semantic/icon/disabled",
+      role: "Icon color when parent component is in disabled state",
+      fallback: "#D0D5DD",
+    },
+    {
+      property: "Inverse Color",
+      tokenName: "color/semantic/icon/inverse",
+      role: "Icon color on dark backgrounds or inverse surfaces",
+      fallback: "#FFFFFF",
+    },
+    {
+      property: "Error Color",
+      tokenName: "color/semantic/icon/error",
+      role: "Semantic error icon color — used in validation, alerts, and destructive contexts",
+      fallback: "#F04438",
+    },
+    {
+      property: "Success Color",
+      tokenName: "color/semantic/icon/success",
+      role: "Semantic success icon color — used in confirmation and positive feedback",
+      fallback: "#12B76A",
+    },
+  ],
+
+  structureRules: [
+    "Icon renders as an inline SVG element with width and height matching the size preset",
+    "SVG viewBox is always 0 0 24 24 (or source viewBox) — size is controlled by the outer width/height attributes",
+    "Icon aligns vertically with adjacent text using display: inline-flex and align-items: center on the parent",
+    "No wrapper div is required — the SVG element itself is the top-level node",
+    "Fill and stroke colors use currentColor by default, allowing CSS color inheritance from the parent",
+    "Icons must not include embedded text — all glyphs are vector paths for consistent rendering",
+    "RTL layouts flip horizontally-directional icons (arrows, chevrons) but not symmetric ones (close, search)",
+  ],
+
+  typeHierarchyRules: [
+    "Icons are non-textual — they do not participate in the typographic hierarchy",
+    "When paired with a text label, the icon size should match the text line-height for vertical alignment",
+    "Icon size xs (16px) pairs with body-small (12-14px text); md (24px) pairs with body (14-16px text)",
+    "Icons used as standalone glyphs (no adjacent text) should be sized to match the expected visual weight of surrounding content",
+  ],
+
+  interactionRules: [
+    { event: "Click", trigger: "pointerup on icon", action: "No action — icons are non-interactive; click events are handled by the parent component" },
+    { event: "Hover", trigger: "pointerenter on icon", action: "No hover state — icons inherit hover styling from the parent interactive element" },
+    { event: "Parent Disabled", trigger: "Parent sets disabled state", action: "Icon color transitions to color/semantic/icon/disabled with opacity 0.4" },
+    { event: "Color Inheritance", trigger: "Parent CSS color changes", action: "Icon fill updates to match currentColor automatically via SVG fill inheritance" },
+    { event: "RTL Toggle", trigger: "Document direction changes to RTL", action: "Directional icons (arrows, chevrons) apply transform: scaleX(-1)" },
+    { event: "Theme Change", trigger: "Color mode toggles (light/dark)", action: "Icon color tokens resolve to new theme values; SVG re-renders with updated fills" },
+  ],
+
+  contentGuidance: [
+    "Use filled icons for primary actions and emphasis; use outlined icons for secondary or passive contexts",
+    "Pair every icon with a visible text label unless the icon is universally understood (close ×, search 🔍, home)",
+    "Maintain a consistent icon style (filled vs outlined) within a single UI surface — do not mix styles arbitrarily",
+    "Choose icons from the established icon library — do not introduce custom glyphs without design review",
+    "Use semantic color tokens (error, success) for status icons rather than arbitrary color overrides",
+    "Ensure icon metaphors are culturally appropriate and universally recognizable for the target audience",
+  ],
+
+  responsiveBehaviour: [
+    { breakpoint: "Mobile (<768px)", behavior: "Icons remain at their specified size; do not scale with viewport — touch targets are handled by the parent" },
+    { breakpoint: "Tablet (768-1023px)", behavior: "Same icon sizes as desktop; no responsive scaling needed for vector graphics" },
+    { breakpoint: "Desktop (1024-1439px)", behavior: "Standard icon rendering at specified size presets" },
+    { breakpoint: "Ultra-wide (>=1440px)", behavior: "No scaling — icons are fixed-size elements that do not grow with viewport width" },
+  ],
+
+  accessibilitySpec: {
+    intro:
+      "Icons must be categorized as either decorative (hidden from AT) or informative (labeled for AT). There is no middle ground.",
+    requirements: [
+      { requirement: "Decorative aria-hidden", level: "A", notes: "Icons that duplicate adjacent text or are purely ornamental must have aria-hidden='true'" },
+      { requirement: "Informative aria-label", level: "A", notes: "Icons conveying meaning without adjacent text must have role='img' and a descriptive aria-label" },
+      { requirement: "Focusable false", level: "A", notes: "SVG elements must have focusable='false' to prevent IE/Edge from adding them to the tab order" },
+      { requirement: "Title element avoided", level: "A", notes: "Do not use <title> inside SVG for labeling — use aria-label on the SVG element instead for consistent AT support" },
+      { requirement: "Contrast", level: "AA", notes: "Informative icons must meet 3:1 non-text contrast ratio against their background" },
+      { requirement: "High Contrast Mode", level: "AA", notes: "Icons must remain visible in Windows High Contrast Mode — use currentColor, not hardcoded fills" },
+      { requirement: "Reduced Motion", level: "AAA", notes: "If icons have animated transitions (rotation, color fade), they must respect prefers-reduced-motion" },
+    ],
+    outro: [
+      "Screen readers should either skip decorative icons entirely or announce informative icons with their aria-label",
+      "Never rely on an icon alone to convey critical information — always provide a text alternative or label",
+    ],
+  },
+
+  qaAcceptanceCriteria: [
+    { check: "Size Presets", platform: "All", expectedResult: "Icon renders at correct dimensions for each size preset (16/20/24/32/40px)" },
+    { check: "Color Inheritance", platform: "All", expectedResult: "Icon inherits currentColor from parent when no explicit color prop is set" },
+    { check: "Color Override", platform: "All", expectedResult: "Explicit color prop overrides inherited color and maps to correct design token" },
+    { check: "Filled vs Outlined", platform: "All", expectedResult: "Type prop toggles between filled and outlined glyph variants correctly" },
+    { check: "Decorative Hiding", platform: "Web", expectedResult: "Decorative icons have aria-hidden='true' and are absent from the accessibility tree" },
+    { check: "Informative Labeling", platform: "Web", expectedResult: "Informative icons have role='img' and aria-label announced by screen readers" },
+    { check: "RTL Flip", platform: "Web", expectedResult: "Directional icons (arrows, chevrons) mirror horizontally in RTL; symmetric icons remain unchanged" },
+    { check: "Disabled State", platform: "All", expectedResult: "Icon color changes to disabled token and opacity reduces when parent is disabled" },
+    { check: "Dark Mode", platform: "All", expectedResult: "All icon color tokens resolve correctly in dark mode; icons remain visible" },
+    { check: "High Contrast", platform: "Web", expectedResult: "Icons use currentColor and remain visible in Windows High Contrast Mode" },
+    { check: "SVG Rendering", platform: "All", expectedResult: "Icons render as crisp vector paths with no anti-aliasing artifacts at all size presets" },
+  ],
+
+  dos: [
+    "Set decorative=true for icons that accompany visible text labels — they add no new information",
+    "Provide an aria-label for every standalone icon that conveys meaning without adjacent text",
+    "Use currentColor for fills to ensure icons inherit theme and state colors from parents",
+    "Match icon size to adjacent text line-height for consistent vertical alignment",
+    "Use the design system's icon library — maintain glyph consistency across the product",
+    "Apply transform: scaleX(-1) to directional icons in RTL layouts",
+    "Test all icons in both light and dark modes to verify token resolution",
+  ],
+
+  donts: [
+    "Do not make icons interactive — wrap them in a button or link if they need click handling",
+    "Do not use <img> tags for icons — use inline SVG for color inheritance and scalability",
+    "Do not hardcode fill colors in SVG paths — use currentColor for theme compatibility",
+    "Do not mix filled and outlined icon styles within the same UI surface",
+    "Do not add focusable behavior to decorative icons — they must be invisible to keyboard navigation",
+    "Do not use icons as the sole means of conveying critical information without a text alternative",
+    "Do not resize icons with CSS transform: scale — use the size prop to maintain crisp rendering",
+  ],
+};

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

@@ -0,0 +1,128 @@
+/**
+ * Knowledge base lookup — returns component-type-specific design knowledge
+ */
+import type { ComponentKnowledge } from "../types.js";
+
+import { buttonKnowledge } from "./button.js";
+import { checkboxKnowledge } from "./checkbox.js";
+import { inputKnowledge } from "./input.js";
+import { selectKnowledge } from "./select.js";
+import { toggleKnowledge } from "./toggle.js";
+import { radioKnowledge } from "./radio.js";
+import { modalKnowledge } from "./modal.js";
+import { tabsKnowledge } from "./tabs.js";
+import { cardKnowledge } from "./card.js";
+import { toastKnowledge } from "./toast.js";
+import { accordionKnowledge } from "./accordion.js";
+import { tooltipKnowledge } from "./tooltip.js";
+import { sliderKnowledge } from "./slider.js";
+import { alertKnowledge } from "./alert.js";
+import { badgeKnowledge } from "./badge.js";
+import { avatarKnowledge } from "./avatar.js";
+import { chipKnowledge } from "./chip.js";
+import { tableKnowledge } from "./table.js";
+import { navigationKnowledge } from "./navigation.js";
+import { progressKnowledge } from "./progress.js";
+import { iconKnowledge } from "./icon.js";
+import { linkKnowledge } from "./link.js";
+import { menuKnowledge } from "./menu.js";
+import { spinnerKnowledge } from "./spinner.js";
+import { breadcrumbKnowledge } from "./breadcrumb.js";
+import { tagKnowledge } from "./tag.js";
+import { navbarKnowledge } from "./navbar.js";
+import { textareaKnowledge } from "./textarea.js";
+import { searchKnowledge } from "./search.js";
+import { comboboxKnowledge } from "./combobox.js";
+import { datepickerKnowledge } from "./datepicker.js";
+import { numberInputKnowledge } from "./number-input.js";
+import { formKnowledge } from "./form.js";
+import { paginationKnowledge } from "./pagination.js";
+import { listKnowledge } from "./list.js";
+import { treeviewKnowledge } from "./treeview.js";
+import { typographyKnowledge } from "./typography.js";
+import { dividerKnowledge } from "./divider.js";
+import { skeletonKnowledge } from "./skeleton.js";
+import { popoverKnowledge } from "./popover.js";
+import { dropdownMenuKnowledge } from "./dropdown-menu.js";
+import { avatarGroupKnowledge } from "./avatar-group.js";
+import { gridKnowledge } from "./grid.js";
+import { emptyStateKnowledge } from "./empty-state.js";
+import { bannerKnowledge } from "./banner.js";
+import { drawerKnowledge } from "./drawer.js";
+import { segmentedControlKnowledge } from "./segmented-control.js";
+import { stepperKnowledge } from "./stepper.js";
+import { fileUploaderKnowledge } from "./file-uploader.js";
+import { inlineMessageKnowledge } from "./inline-message.js";
+import { toolbarKnowledge } from "./toolbar.js";
+import { calendarKnowledge } from "./calendar.js";
+import { timePickerKnowledge } from "./time-picker.js";
+import { rangeSliderKnowledge } from "./range-slider.js";
+import { inlineEditKnowledge } from "./inline-edit.js";
+import { statusDotKnowledge } from "./status-dot.js";
+import { ratingKnowledge } from "./rating.js";
+import { defaultKnowledge } from "./_default.js";
+
+const KNOWLEDGE_MAP: Record<string, ComponentKnowledge> = {
+  button: buttonKnowledge,
+  checkbox: checkboxKnowledge,
+  input: inputKnowledge,
+  select: selectKnowledge,
+  toggle: toggleKnowledge,
+  radio: radioKnowledge,
+  modal: modalKnowledge,
+  tabs: tabsKnowledge,
+  card: cardKnowledge,
+  toast: toastKnowledge,
+  accordion: accordionKnowledge,
+  tooltip: tooltipKnowledge,
+  slider: sliderKnowledge,
+  alert: alertKnowledge,
+  badge: badgeKnowledge,
+  avatar: avatarKnowledge,
+  chip: chipKnowledge,
+  table: tableKnowledge,
+  navigation: navigationKnowledge,
+  progress: progressKnowledge,
+  icon: iconKnowledge,
+  link: linkKnowledge,
+  menu: menuKnowledge,
+  spinner: spinnerKnowledge,
+  breadcrumb: breadcrumbKnowledge,
+  tag: tagKnowledge,
+  navbar: navbarKnowledge,
+  textarea: textareaKnowledge,
+  search: searchKnowledge,
+  combobox: comboboxKnowledge,
+  datepicker: datepickerKnowledge,
+  numberinput: numberInputKnowledge,
+  form: formKnowledge,
+  pagination: paginationKnowledge,
+  list: listKnowledge,
+  treeview: treeviewKnowledge,
+  typography: typographyKnowledge,
+  divider: dividerKnowledge,
+  skeleton: skeletonKnowledge,
+  popover: popoverKnowledge,
+  dropdownmenu: dropdownMenuKnowledge,
+  avatargroup: avatarGroupKnowledge,
+  grid: gridKnowledge,
+  emptystate: emptyStateKnowledge,
+  banner: bannerKnowledge,
+  drawer: drawerKnowledge,
+  segmentedcontrol: segmentedControlKnowledge,
+  stepper: stepperKnowledge,
+  fileuploader: fileUploaderKnowledge,
+  inlinemessage: inlineMessageKnowledge,
+  toolbar: toolbarKnowledge,
+  calendar: calendarKnowledge,
+  timepicker: timePickerKnowledge,
+  rangeslider: rangeSliderKnowledge,
+  inlineedit: inlineEditKnowledge,
+  statusdot: statusDotKnowledge,
+  rating: ratingKnowledge,
+};
+
+export function getComponentKnowledge(type?: string): ComponentKnowledge {
+  if (!type) return defaultKnowledge;
+  return KNOWLEDGE_MAP[type] ?? defaultKnowledge;
+}