@sarjallab09/figma-intelligence 1.0.0

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

@@ -0,0 +1,289 @@
+/**
+ * Knowledge: Toggle Switch
+ */
+import type { ComponentKnowledge } from "../types.js";
+
+export const toggleKnowledge: ComponentKnowledge = {
+  description:
+    "Binary switch control | Immediate state change | On/Off preference toggle",
+
+  stateSpecifications: [
+    {
+      state: "Off",
+      visualChange: "Track is neutral/muted; thumb is positioned to the left",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Default inactive state — the associated setting is disabled",
+    },
+    {
+      state: "On",
+      visualChange:
+        "Track fills with primary color; thumb slides to the right",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Active state — the associated setting is enabled",
+    },
+    {
+      state: "Disabled (off)",
+      visualChange:
+        "Track and thumb are muted; no pointer events; off position",
+      opacity: "0.4",
+      cursorWeb: "not-allowed",
+      usage: "Toggle is inactive and cannot be changed by the user",
+    },
+    {
+      state: "Disabled (on)",
+      visualChange:
+        "Track shows muted primary; thumb on right; no pointer events",
+      opacity: "0.4",
+      cursorWeb: "not-allowed",
+      usage: "Toggle is active but locked and cannot be changed",
+    },
+    {
+      state: "Focus",
+      visualChange: "Focus ring appears around the track or thumb",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Toggle has keyboard focus and can be operated with Space",
+    },
+    {
+      state: "Hover",
+      visualChange: "Subtle background tint or shadow on the track",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Pointer is over the toggle, indicating interactivity",
+    },
+  ],
+
+  propertyDescriptions: {
+    checked: "Boolean indicating whether the toggle is on (true) or off (false)",
+    disabled: "Prevents interaction and visually mutes the component",
+    label: "Descriptive text adjacent to the toggle explaining its purpose",
+    labelPosition:
+      "Placement of the label relative to the toggle: 'start' (left/above) or 'end' (right/below)",
+    size: "Visual size variant: small, medium, or large",
+  },
+
+  sizeSpecifications: [
+    {
+      size: "Small",
+      height: "16px",
+      paddingLR: "2px",
+      fontSize: "12px",
+      iconSize: "12px",
+      borderRadius: "8px",
+    },
+    {
+      size: "Medium",
+      height: "20px",
+      paddingLR: "2px",
+      fontSize: "14px",
+      iconSize: "14px",
+      borderRadius: "10px",
+    },
+    {
+      size: "Large",
+      height: "24px",
+      paddingLR: "3px",
+      fontSize: "16px",
+      iconSize: "16px",
+      borderRadius: "12px",
+    },
+  ],
+
+  designTokenBindings: [
+    {
+      property: "background-color (track off)",
+      tokenName: "toggle/track/bg/off",
+      role: "Track background when toggle is off",
+      fallback: "#C6C6C6",
+    },
+    {
+      property: "background-color (track on)",
+      tokenName: "toggle/track/bg/on",
+      role: "Track background when toggle is on",
+      fallback: "#0F62FE",
+    },
+    {
+      property: "background-color (thumb)",
+      tokenName: "toggle/thumb/bg",
+      role: "Thumb circle fill color",
+      fallback: "#FFFFFF",
+    },
+    {
+      property: "box-shadow (focus)",
+      tokenName: "toggle/focus-ring",
+      role: "Focus ring outline on keyboard focus",
+      fallback: "0 0 0 2px #0F62FE",
+    },
+    {
+      property: "color (label)",
+      tokenName: "toggle/label/color",
+      role: "Label text color adjacent to the toggle",
+      fallback: "#161616",
+    },
+  ],
+
+  structureRules: [
+    "The toggle consists of a track (pill shape) and a thumb (circle) that slides between left and right positions",
+    "The label is a sibling element positioned to the start or end of the track depending on labelPosition",
+    "Track width is approximately 1.75x its height to allow clear thumb travel",
+    "The thumb diameter equals the track height minus internal padding on both sides",
+    "No additional icons or text are placed inside the track by default",
+  ],
+
+  typeHierarchyRules: [
+    "Label uses the component's base font size at regular weight",
+    "If a description or sub-label is present, it uses one step smaller font size at regular weight",
+    "Label and toggle are vertically center-aligned",
+  ],
+
+  interactionRules: [
+    {
+      event: "click",
+      trigger: "User clicks the track, thumb, or label",
+      action:
+        "Toggle state flips immediately (on to off or off to on); onChange fires",
+    },
+    {
+      event: "keydown (Space)",
+      trigger: "User presses Space while the toggle is focused",
+      action: "Toggle state flips; same behavior as click",
+    },
+    {
+      event: "drag",
+      trigger: "User drags the thumb horizontally across the track",
+      action:
+        "Thumb follows the pointer; state commits when released past the midpoint",
+    },
+    {
+      event: "change",
+      trigger: "Toggle state changes by any method",
+      action:
+        "Effect takes place immediately — no form submission required",
+    },
+  ],
+
+  contentGuidance: [
+    "Label should clearly describe the setting being controlled (e.g. 'Enable notifications')",
+    "Use positive framing — the label describes what happens when the toggle is on",
+    "Avoid double negatives (e.g. 'Disable auto-save' is confusing when toggled off)",
+    "If the toggle controls a destructive or irreversible action, pair it with a confirmation dialog",
+    "Toggles imply an immediate effect — do not use them for choices that require a Save button",
+  ],
+
+  responsiveBehaviour: [
+    {
+      breakpoint: "< 480px",
+      behavior:
+        "Toggle and label are placed on a single row; label may wrap to a second line if needed",
+    },
+    {
+      breakpoint: "480px – 1024px",
+      behavior:
+        "Toggle and label sit inline within settings cards or form rows",
+    },
+    {
+      breakpoint: "> 1024px",
+      behavior:
+        "Toggle may appear in dense settings panels; size stays consistent across breakpoints",
+    },
+  ],
+
+  accessibilitySpec: {
+    intro:
+      "The toggle must use role=\"switch\" so assistive technology announces it as a binary on/off control with immediate effect.",
+    requirements: [
+      {
+        requirement:
+          "Element has role=\"switch\" with aria-checked reflecting the current state (true/false)",
+        level: "A",
+        notes: "WCAG 4.1.2 – Name, Role, Value",
+      },
+      {
+        requirement:
+          "An accessible name is provided via a visible label linked by htmlFor/id or aria-labelledby",
+        level: "A",
+        notes: "WCAG 1.3.1 – Info and Relationships",
+      },
+      {
+        requirement:
+          "State change is announced immediately by screen readers when toggled",
+        level: "A",
+        notes: "WCAG 4.1.2 – users must perceive the state change",
+      },
+      {
+        requirement:
+          "Focus indicator is visible with at least 3:1 contrast against adjacent colors",
+        level: "AA",
+        notes: "WCAG 2.4.7 – Focus Visible",
+      },
+      {
+        requirement:
+          "Track and thumb contrast meet 3:1 non-text UI requirement in both on and off states",
+        level: "AA",
+        notes: "WCAG 1.4.11 – Non-text Contrast",
+      },
+    ],
+    outro: [
+      "Test with VoiceOver and NVDA: focus the toggle, press Space, and verify the state announcement changes",
+      "Ensure the change takes effect immediately without requiring a separate submit action",
+      "Verify that disabled toggles are announced as dimmed/unavailable and cannot be operated",
+    ],
+  },
+
+  qaAcceptanceCriteria: [
+    {
+      check: "Toggle animation",
+      platform: "Web / Mobile",
+      expectedResult:
+        "Thumb slides smoothly between on and off positions; track color transitions within 150ms",
+    },
+    {
+      check: "Disabled state",
+      platform: "Web / Mobile",
+      expectedResult:
+        "Clicking or pressing Space on a disabled toggle has no effect; cursor shows not-allowed",
+    },
+    {
+      check: "Keyboard operation",
+      platform: "Web",
+      expectedResult:
+        "Space key toggles the state; Tab moves focus to/from the toggle",
+    },
+    {
+      check: "Screen reader announcement",
+      platform: "Web",
+      expectedResult:
+        "VoiceOver/NVDA reads label, role as 'switch', and current state ('on' or 'off')",
+    },
+    {
+      check: "Drag behavior",
+      platform: "Web / Mobile",
+      expectedResult:
+        "Dragging the thumb past the midpoint commits the state change; releasing before midpoint reverts",
+    },
+    {
+      check: "Immediate effect",
+      platform: "Web / Mobile",
+      expectedResult:
+        "Toggling fires the onChange callback immediately without waiting for form submission",
+    },
+  ],
+
+  dos: [
+    "Use toggles for binary settings that take effect immediately",
+    "Provide a clear label that describes the 'on' state",
+    "Animate the thumb transition for visual feedback",
+    "Maintain consistent sizing with adjacent form controls",
+    "Ensure both on and off track colors have sufficient contrast against the background",
+  ],
+
+  donts: [
+    "Do not use a toggle when a checkbox with a Save button is more appropriate",
+    "Do not use a toggle for multi-option choices — use radio buttons or a select instead",
+    "Do not place the toggle inside a scrollable container where drag conflicts with scroll",
+    "Do not remove the label — a standalone toggle without text is not self-explanatory",
+    "Do not change the toggle's semantics to behave like a button that triggers navigation",
+  ],
+};

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

@@ -0,0 +1,267 @@
+/**
+ * toolbar.ts — Gold-standard design knowledge for Toolbar components
+ */
+import type { ComponentKnowledge } from "../types.js";
+
+export const toolbarKnowledge: ComponentKnowledge = {
+  description:
+    "Horizontal action bar | Grouped controls container | Provides quick access to contextual actions and tools",
+
+  stateSpecifications: [
+    {
+      state: "Default",
+      visualChange: "Toolbar renders as a horizontal bar with evenly spaced action items in their resting state",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Standard resting state — all toolbar items are interactive and ready for activation",
+    },
+    {
+      state: "Item Hover",
+      visualChange: "Individual toolbar item background shifts to a subtle hover tint; icon/text color may intensify",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Mouse cursor enters a specific toolbar item's hit area",
+    },
+    {
+      state: "Item Active/Pressed",
+      visualChange: "Item background darkens further; slight depression effect for tactile feedback",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Mouse button is held down on a toolbar item",
+    },
+    {
+      state: "Item Selected/Toggled",
+      visualChange: "Item has filled background or bottom indicator bar; icon/text uses active/primary color",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "A toggle-type toolbar item is in its active/on state (e.g. Bold, Italic formatting)",
+    },
+    {
+      state: "Item Disabled",
+      visualChange: "Individual item icon and text are muted; no hover or click response",
+      opacity: "0.4",
+      cursorWeb: "not-allowed",
+      usage: "A specific action is unavailable in the current context (e.g. Undo with no history)",
+    },
+    {
+      state: "Item Focus",
+      visualChange: "2px focus ring around the focused item; achieved via arrow key or Tab navigation",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "A toolbar item receives keyboard focus via the roving tabindex pattern",
+    },
+    {
+      state: "Overflow",
+      visualChange: "Items that do not fit are hidden; an overflow menu button (three dots) appears at the end",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Container is too narrow to display all items — excess items move to an overflow dropdown",
+    },
+  ],
+
+  propertyDescriptions: {
+    items: "Array of toolbar item objects, each with a label, icon, onClick handler, type (button/toggle/separator), and optional disabled flag",
+    size: "Dimensional preset — Small, Medium, or Large — controlling item height, icon size, and padding",
+    overflow: "Overflow behavior — 'visible' keeps all items visible (may overflow container) or 'menu' moves excess items to a dropdown",
+    orientation: "Layout direction — 'horizontal' (default) for standard toolbars or 'vertical' for sidebar tool palettes",
+    ariaLabel: "Accessible label for the toolbar — describes the toolbar purpose (e.g. 'Text formatting', 'Drawing tools')",
+    variant: "Visual style — 'solid' with background fill, 'subtle' with transparent background, or 'outlined' with border",
+    groupSeparator: "When true, renders visual dividers between logical groups of toolbar items",
+  },
+
+  sizeSpecifications: [
+    {
+      size: "Small",
+      height: "32px",
+      paddingLR: "4px",
+      fontSize: "12px",
+      iconSize: "16px",
+      borderRadius: "6px",
+    },
+    {
+      size: "Medium",
+      height: "40px",
+      paddingLR: "6px",
+      fontSize: "14px",
+      iconSize: "20px",
+      borderRadius: "8px",
+    },
+    {
+      size: "Large",
+      height: "48px",
+      paddingLR: "8px",
+      fontSize: "16px",
+      iconSize: "24px",
+      borderRadius: "10px",
+    },
+  ],
+
+  designTokenBindings: [
+    {
+      property: "Toolbar Background",
+      tokenName: "$toolbar-bg",
+      role: "Background fill of the toolbar container",
+      fallback: "#FFFFFF",
+    },
+    {
+      property: "Toolbar Border",
+      tokenName: "$toolbar-border",
+      role: "Border around or below the toolbar for definition",
+      fallback: "#E4E7EC",
+    },
+    {
+      property: "Item Default Color",
+      tokenName: "$toolbar-item-color",
+      role: "Icon and text color for toolbar items in default state",
+      fallback: "#667085",
+    },
+    {
+      property: "Item Hover Background",
+      tokenName: "$toolbar-item-hover-bg",
+      role: "Background tint on individual item hover",
+      fallback: "#F2F4F7",
+    },
+    {
+      property: "Item Active Background",
+      tokenName: "$toolbar-item-active-bg",
+      role: "Background fill when an item is pressed or actively toggled",
+      fallback: "#E4E7EC",
+    },
+    {
+      property: "Item Selected Color",
+      tokenName: "$toolbar-item-selected-color",
+      role: "Icon and text color for a selected/toggled-on item",
+      fallback: "#2563EB",
+    },
+    {
+      property: "Item Selected Background",
+      tokenName: "$toolbar-item-selected-bg",
+      role: "Background fill for a selected/toggled-on item",
+      fallback: "#EFF8FF",
+    },
+    {
+      property: "Separator",
+      tokenName: "$toolbar-separator",
+      role: "Color of the vertical divider line between item groups",
+      fallback: "#E4E7EC",
+    },
+    {
+      property: "Focus Ring",
+      tokenName: "$focus-ring",
+      role: "Keyboard focus indicator around the focused toolbar item",
+      fallback: "0 0 0 2px #FFFFFF, 0 0 0 4px #2E90FA",
+    },
+    {
+      property: "Shadow",
+      tokenName: "$shadow-toolbar",
+      role: "Optional subtle shadow for floating toolbar variants",
+      fallback: "0 1px 3px rgba(0, 0, 0, 0.1)",
+    },
+  ],
+
+  structureRules: [
+    "Toolbar container uses horizontal Auto Layout (or vertical for sidebar variant) with items as direct children",
+    "Items within a logical group have $spacing-2xs (2px) gap; groups are separated by a visual divider",
+    "Separators are 1px vertical lines (horizontal toolbar) or 1px horizontal lines (vertical toolbar) using the separator token",
+    "Each item is a square or near-square button containing an icon centered both horizontally and vertically",
+    "Items with labels render the label below (horizontal) or beside (vertical) the icon in a compact arrangement",
+    "Overflow menu button is always the last visible item and uses a three-dot (ellipsis) icon",
+    "Overflow dropdown menu inherits the menu component pattern with the hidden items listed as menu items",
+    "Toolbar container has minimal internal padding (4-8px) to keep it compact",
+    "Toolbar should not wrap to multiple lines — use the overflow pattern when items exceed container width",
+  ],
+
+  typeHierarchyRules: [
+    "Item labels (when shown) use Medium weight (500) at one size smaller than the size preset fontSize",
+    "Labels are optional — icon-only toolbars are the most common pattern",
+    "Tooltip text for icon-only items uses Regular weight (400) at 12px",
+    "Overflow menu item text uses Regular weight (400) at the standard menu item font size",
+  ],
+
+  interactionRules: [
+    { event: "Click (Button Item)", trigger: "Pointer up on a button-type toolbar item", action: "Fire the item's onClick handler; provide brief visual active feedback" },
+    { event: "Click (Toggle Item)", trigger: "Pointer up on a toggle-type toolbar item", action: "Toggle the item's selected state; update visual treatment; fire onChange" },
+    { event: "Hover", trigger: "Pointer enters a toolbar item", action: "Item background transitions to hover tint; tooltip appears after delay" },
+    { event: "Focus (Tab)", trigger: "Tab key reaches the toolbar", action: "Focus lands on the first (or last-focused) item in the toolbar; focus ring appears" },
+    { event: "Arrow Right", trigger: "Right arrow while focused (horizontal)", action: "Move focus to the next item; skip separators; wrap from last to first" },
+    { event: "Arrow Left", trigger: "Left arrow while focused (horizontal)", action: "Move focus to the previous item; skip separators; wrap from first to last" },
+    { event: "Arrow Down", trigger: "Down arrow while focused (vertical)", action: "Move focus to the next item in a vertical toolbar" },
+    { event: "Arrow Up", trigger: "Up arrow while focused (vertical)", action: "Move focus to the previous item in a vertical toolbar" },
+    { event: "Home", trigger: "Home key while focused", action: "Move focus to the first interactive item in the toolbar" },
+    { event: "End", trigger: "End key while focused", action: "Move focus to the last interactive item in the toolbar" },
+    { event: "Overflow Toggle", trigger: "Click on the overflow menu button", action: "Open a dropdown menu containing the hidden overflow items" },
+  ],
+
+  contentGuidance: [
+    "Group related actions together — separate groups with visual dividers",
+    "Limit toolbar to 5-12 visible items — use overflow for additional actions",
+    "Icon-only toolbars must have tooltips on every item for discoverability",
+    "Use familiar, standard icons — avoid custom icons that require learning",
+    "Place the most frequently used actions at the beginning (left for horizontal, top for vertical)",
+    "Toggle items should have a clear selected vs. unselected visual distinction",
+    "Overflow menu should preserve the same item order as the visible toolbar",
+  ],
+
+  responsiveBehaviour: [
+    { breakpoint: "Mobile (<768px)", behavior: "Toolbar items collapse aggressively into overflow menu; only 3-4 most important items remain visible" },
+    { breakpoint: "Tablet (768-1023px)", behavior: "Most items visible; overflow handles 2-3 least-used items; touch targets are 44px minimum" },
+    { breakpoint: "Desktop (1024-1439px)", behavior: "All items visible in most cases; overflow activates only for very dense toolbars" },
+    { breakpoint: "Ultra-wide (>=1440px)", behavior: "Toolbar width remains capped at container width; items do not spread to fill extra space" },
+  ],
+
+  accessibilitySpec: {
+    intro:
+      "Toolbars group related controls for quick access. The WAI-ARIA toolbar pattern requires proper role assignment, arrow key navigation, and accessible names for all items.",
+    requirements: [
+      { requirement: "Role", level: "A", notes: "Container must have role='toolbar' with aria-label or aria-labelledby describing the toolbar purpose" },
+      { requirement: "Orientation", level: "A", notes: "Use aria-orientation='horizontal' or 'vertical' to inform screen readers of the navigation axis" },
+      { requirement: "Roving Tabindex", level: "A", notes: "Only one item has tabindex='0' at a time; arrow keys move focus; Tab exits the toolbar" },
+      { requirement: "Item Labels", level: "A", notes: "Icon-only items require aria-label; toggle items need aria-pressed='true'/'false'" },
+      { requirement: "Disabled Items", level: "A", notes: "Disabled items have aria-disabled='true'; they remain in the arrow key navigation but are not activatable" },
+      { requirement: "Keyboard Activation", level: "A", notes: "Enter and Space activate the focused toolbar item; toggle items change aria-pressed" },
+      { requirement: "Contrast", level: "AA", notes: "All item icons meet 3:1 non-text contrast; labels meet 4.5:1 text contrast" },
+      { requirement: "Touch Target", level: "AA", notes: "Each toolbar item has a minimum 44x44px touch area" },
+    ],
+    outro: [
+      "Test with screen readers to verify role='toolbar' is announced, along with the toolbar label and item count",
+      "Verify arrow keys navigate between items and wrap at boundaries",
+      "Ensure overflow menu items are announced with their original labels and states",
+    ],
+  },
+
+  qaAcceptanceCriteria: [
+    { check: "Default Render", platform: "All", expectedResult: "Toolbar displays all items in a horizontal row with correct spacing and separators" },
+    { check: "Item Hover", platform: "Web", expectedResult: "Individual items show hover background tint on pointer enter" },
+    { check: "Item Click", platform: "All", expectedResult: "Button items fire onClick; toggle items change selected state and fire onChange" },
+    { check: "Toggle State", platform: "All", expectedResult: "Toggled-on items show filled/selected visual; toggled-off items show default treatment" },
+    { check: "Arrow Key Navigation", platform: "Web", expectedResult: "Left/Right arrows move focus between items; Home/End jump to first/last" },
+    { check: "Tab Behavior", platform: "Web", expectedResult: "Tab enters toolbar on the last-focused item; next Tab exits to the next focusable element" },
+    { check: "Disabled Item", platform: "All", expectedResult: "Disabled items show muted visuals; not clickable; included in arrow key navigation but not activatable" },
+    { check: "Overflow Menu", platform: "Web", expectedResult: "Excess items move to overflow dropdown; dropdown opens on overflow button click" },
+    { check: "Separator Rendering", platform: "All", expectedResult: "Visual dividers appear between groups; correct color and spacing" },
+    { check: "Tooltip", platform: "Web", expectedResult: "Tooltips appear on hover/focus for icon-only items with correct label text" },
+    { check: "Screen Reader", platform: "Web", expectedResult: "Announces toolbar role, label, item labels, toggle states, and disabled states" },
+    { check: "Vertical Orientation", platform: "All", expectedResult: "Items stack vertically; Up/Down arrows navigate; aria-orientation is 'vertical'" },
+    { check: "RTL Support", platform: "Web", expectedResult: "Item order mirrors; arrow key direction reverses; separators position correctly" },
+  ],
+
+  dos: [
+    "Use role='toolbar' with a descriptive aria-label for the toolbar container",
+    "Group related actions and separate groups with visual dividers",
+    "Implement roving tabindex for single-Tab-stop keyboard navigation",
+    "Provide tooltips for all icon-only toolbar items",
+    "Use the overflow pattern when items exceed the available container width",
+    "Give toggle items a clear selected/unselected visual distinction with aria-pressed",
+    "Place the most frequently used actions first (leftmost or topmost)",
+  ],
+
+  donts: [
+    "Do not use a toolbar for navigation — use a navbar or tab bar instead",
+    "Do not allow the toolbar to wrap to multiple rows — use overflow instead",
+    "Do not make toolbar items smaller than the 44x44px minimum touch target",
+    "Do not use text-only toolbar items without icons — toolbars are primarily icon-driven",
+    "Do not mix unrelated actions in the same toolbar — separate into distinct toolbars",
+    "Do not use the toolbar pattern for a simple button group — toolbars imply the WAI-ARIA toolbar pattern",
+    "Do not hide the overflow indicator when items are clipped — users need to discover hidden actions",
+  ],
+};