@sarjallab09/figma-intelligence 1.0.1 → 1.2.0

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

@@ -1,289 +0,0 @@
-/**
- * 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

@@ -1,267 +0,0 @@
-/**
- * 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",
-  ],
-};