@sarjallab09/figma-intelligence 1.0.0

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

@@ -0,0 +1,239 @@
+/**
+ * spinner.ts — Gold-standard design knowledge for Spinner / Loader components
+ */
+import type { ComponentKnowledge } from "../types.js";
+
+export const spinnerKnowledge: ComponentKnowledge = {
+  description:
+    "Indeterminate loading indicator | Circular progress spinner | Asynchronous status feedback",
+
+  stateSpecifications: [
+    {
+      state: "Active",
+      visualChange: "Circular track visible with animated indicator arc rotating continuously at a steady cadence",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "An asynchronous operation is in progress — data is loading, processing, or being fetched",
+    },
+    {
+      state: "Complete",
+      visualChange: "Indicator arc fills to 100% and transitions into a checkmark icon over 300ms; optional success color shift",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "The asynchronous operation has finished successfully; provides completion feedback before the spinner is removed",
+    },
+    {
+      state: "Overlay",
+      visualChange: "Semi-transparent backdrop covers the parent container or viewport; spinner is centered on the backdrop",
+      opacity: "1",
+      cursorWeb: "wait",
+      usage: "Blocking loading state — prevents interaction with underlying content while the operation completes",
+    },
+    {
+      state: "Inline",
+      visualChange: "Small spinner renders inline with text or within a button; no backdrop or blocking behavior",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Lightweight loading indicator within a component (e.g., inside a button or adjacent to a label)",
+    },
+    {
+      state: "Hidden",
+      visualChange: "Spinner is removed from the DOM or set to display:none; aria-busy removed from parent",
+      opacity: "0",
+      cursorWeb: "default",
+      usage: "Loading is complete and the spinner is no longer needed; content is now fully rendered",
+    },
+  ],
+
+  propertyDescriptions: {
+    size: "Dimensional preset controlling the spinner diameter and stroke width (Extra Small, Small, Medium, Large, Extra Large)",
+    label: "Screen-reader-only text describing the loading context (e.g., 'Loading search results'); visually hidden but announced by assistive technology",
+    overlay: "When true, renders a semi-transparent backdrop behind the spinner that blocks interaction with underlying content",
+    color: "Color variant for the indicator arc — primary (default brand color), inverse (for dark backgrounds), or inherit (matches parent text color)",
+  },
+
+  sizeSpecifications: [
+    {
+      size: "Extra Small",
+      height: "16px",
+      paddingLR: "0px",
+      fontSize: "N/A",
+      iconSize: "16px",
+      borderRadius: "0px",
+    },
+    {
+      size: "Small",
+      height: "24px",
+      paddingLR: "0px",
+      fontSize: "N/A",
+      iconSize: "24px",
+      borderRadius: "0px",
+    },
+    {
+      size: "Medium",
+      height: "32px",
+      paddingLR: "0px",
+      fontSize: "N/A",
+      iconSize: "32px",
+      borderRadius: "0px",
+    },
+    {
+      size: "Large",
+      height: "48px",
+      paddingLR: "0px",
+      fontSize: "N/A",
+      iconSize: "48px",
+      borderRadius: "0px",
+    },
+    {
+      size: "Extra Large",
+      height: "64px",
+      paddingLR: "0px",
+      fontSize: "N/A",
+      iconSize: "64px",
+      borderRadius: "0px",
+    },
+  ],
+
+  designTokenBindings: [
+    {
+      property: "Track Color",
+      tokenName: "$spinner-track",
+      role: "Background circular track visible behind the animated indicator arc",
+      fallback: "#E4E7EC",
+    },
+    {
+      property: "Indicator Color",
+      tokenName: "$spinner-indicator",
+      role: "Animated arc color — the primary visual element of the spinner",
+      fallback: "#2563EB",
+    },
+    {
+      property: "Inverse Indicator",
+      tokenName: "$spinner-indicator-inverse",
+      role: "Indicator color for use on dark or colored backgrounds",
+      fallback: "#FFFFFF",
+    },
+    {
+      property: "Overlay Background",
+      tokenName: "$spinner-overlay-bg",
+      role: "Semi-transparent backdrop color for the overlay variant",
+      fallback: "rgba(255,255,255,0.7)",
+    },
+    {
+      property: "Animation Duration",
+      tokenName: "$transition-spinner",
+      role: "Duration of one full rotation cycle of the indicator arc",
+      fallback: "800ms",
+    },
+    {
+      property: "Animation Easing",
+      tokenName: "$easing-spinner",
+      role: "Easing curve for the rotation animation — linear for steady cadence",
+      fallback: "linear",
+    },
+    {
+      property: "Z-Index Overlay",
+      tokenName: "$z-spinner-overlay",
+      role: "Stacking order for the overlay variant — above content but below modals",
+      fallback: "1050",
+    },
+  ],
+
+  structureRules: [
+    "Spinner uses an SVG circle element with stroke-dasharray and stroke-dashoffset for the animated arc, or equivalent CSS animation on a bordered div",
+    "Track is a full circle with the $spinner-track color; indicator arc covers approximately 75% of the circumference",
+    "Stroke width scales proportionally with spinner size — 2px for xs/sm, 3px for md, 4px for lg/xl",
+    "Overlay variant renders a full-coverage backdrop div with flexbox centering for the spinner element",
+    "Spinner container has equal width and height (square aspect ratio) with no internal padding",
+    "Inline spinners must not alter the line height or layout flow of their parent container",
+    "The animation uses CSS @keyframes rotate or SVG animateTransform — no JavaScript interval timers",
+  ],
+
+  typeHierarchyRules: [
+    "Spinners have no visible text — the label property is screen-reader-only using visually-hidden utility class",
+    "When paired with a visible loading message, the message text uses body font size and Regular (400) weight",
+    "Visible loading text is centered below the spinner with $spacing-sm (8px) gap",
+    "Never display percentage text alongside an indeterminate spinner — use a progress bar for determinate loading",
+  ],
+
+  interactionRules: [
+    { event: "Appear", trigger: "Loading operation begins", action: "Render spinner with fade-in over 100ms; set aria-busy='true' on parent container" },
+    { event: "Disappear", trigger: "Loading operation completes", action: "Fade out over 150ms; remove aria-busy; optionally show completion checkmark for 500ms" },
+    { event: "Overlay Block", trigger: "Overlay variant is active", action: "Prevent pointer events on underlying content; set cursor to wait on the backdrop" },
+    { event: "Escape (Overlay)", trigger: "Escape key while overlay spinner is visible", action: "Cancel the loading operation if cancellation is supported; otherwise no action" },
+    { event: "Reduced Motion", trigger: "prefers-reduced-motion media query matches", action: "Replace rotation animation with a pulsing opacity animation or static indicator" },
+    { event: "Long Wait", trigger: "Loading exceeds a configurable timeout threshold", action: "Optionally display a 'Still loading...' message or a cancel/retry action below the spinner" },
+  ],
+
+  contentGuidance: [
+    "Always provide a descriptive label for screen readers — 'Loading' alone is insufficient; specify what is loading (e.g., 'Loading search results')",
+    "Use the smallest spinner size that remains clearly visible in context — xs for inline/button, md for section, xl for full-page",
+    "Prefer skeleton screens over spinners for content-heavy layouts where the structure of the content is predictable",
+    "Do not display spinners for operations that complete in under 300ms — use a 300ms delay before showing the spinner to avoid flash",
+    "When using the overlay variant, ensure the backdrop does not completely obscure critical context the user may need to reference",
+    "For long-running operations, pair the spinner with a text message explaining what is happening and estimated wait time",
+  ],
+
+  responsiveBehaviour: [
+    { breakpoint: "Mobile (<768px)", behavior: "Full-page spinners use the lg size (48px); inline spinners use xs (16px) or sm (24px); overlay covers the entire viewport" },
+    { breakpoint: "Tablet (768-1023px)", behavior: "Section-level spinners use md (32px); page-level spinners use lg (48px); overlay scoped to the loading region" },
+    { breakpoint: "Desktop (1024-1439px)", behavior: "Standard sizing applies; overlay can be scoped to a panel or the full viewport depending on context" },
+    { breakpoint: "Ultra-wide (>=1440px)", behavior: "Spinner sizes remain fixed — no proportional scaling with viewport; xl (64px) reserved for full-page loading" },
+  ],
+
+  accessibilitySpec: {
+    intro:
+      "Spinners are non-interactive but must communicate loading status to assistive technology users who cannot perceive the visual animation.",
+    requirements: [
+      { requirement: "role='status'", level: "A", notes: "Spinner container must use role='status' to create a live region that announces loading state changes" },
+      { requirement: "aria-live='polite'", level: "A", notes: "The live region should use polite priority to avoid interrupting the user's current screen reader output" },
+      { requirement: "aria-label", level: "A", notes: "Spinner must have a descriptive aria-label explaining what is loading (e.g., 'Loading user profile')" },
+      { requirement: "aria-busy", level: "A", notes: "The parent container being loaded must set aria-busy='true' while loading and remove it on completion" },
+      { requirement: "Contrast", level: "AA", notes: "Indicator arc to track must meet 3:1 non-text contrast ratio; indicator to background must also meet 3:1" },
+      { requirement: "Reduced Motion", level: "AAA", notes: "Rotation animation must be replaced with a non-motion alternative when prefers-reduced-motion is active" },
+      { requirement: "Completion Announcement", level: "A", notes: "When loading completes, the live region must announce completion (e.g., 'Search results loaded')" },
+    ],
+    outro: [
+      "Ensure the spinner does not create a keyboard focus trap — spinners are not focusable elements",
+      "Screen readers should announce the loading state once on appearance, not repeatedly during the animation cycle",
+    ],
+  },
+
+  qaAcceptanceCriteria: [
+    { check: "Animation Smoothness", platform: "Web", expectedResult: "Spinner rotates at a steady 800ms cycle with no jank or frame drops at 60fps" },
+    { check: "Size Variants", platform: "All", expectedResult: "All five sizes (xs/sm/md/lg/xl) render at correct dimensions with proportional stroke width" },
+    { check: "Color Variants", platform: "All", expectedResult: "Primary, inverse, and inherit color variants render correct indicator colors" },
+    { check: "Overlay Blocking", platform: "Web", expectedResult: "Overlay backdrop prevents clicks on underlying content; cursor shows wait" },
+    { check: "Screen Reader", platform: "Web", expectedResult: "Announces loading state via role='status'; announces completion when spinner is removed" },
+    { check: "aria-busy", platform: "Web", expectedResult: "Parent container has aria-busy='true' during loading; attribute removed on completion" },
+    { check: "Delay Threshold", platform: "Web", expectedResult: "Spinner does not appear for operations completing in under 300ms — no visual flash" },
+    { check: "Reduced Motion", platform: "Web", expectedResult: "Rotation replaced with pulsing opacity or static indicator when prefers-reduced-motion is set" },
+    { check: "Inline Layout", platform: "All", expectedResult: "Inline spinner does not alter line height or cause layout shift in the parent container" },
+    { check: "Completion Transition", platform: "Web", expectedResult: "Optional checkmark transition plays for 500ms before spinner is removed" },
+    { check: "Visual Regression", platform: "All", expectedResult: "Spinner renders pixel-perfect against baseline for each size and color variant" },
+    { check: "Dark Mode", platform: "All", expectedResult: "Inverse variant provides sufficient contrast on dark backgrounds; track color adjusts accordingly" },
+  ],
+
+  dos: [
+    "Always provide a descriptive aria-label specific to the loading context, not just 'Loading'",
+    "Use the delay pattern (300ms) before showing the spinner to avoid flash on fast operations",
+    "Set aria-busy='true' on the parent container being loaded to inform assistive technology",
+    "Use the overlay variant for blocking operations where user interaction must be prevented",
+    "Scale the spinner size appropriately for the loading context — inline, section, or page level",
+    "Support prefers-reduced-motion by providing a non-rotation animation alternative",
+    "Remove the spinner and announce completion to screen readers when loading finishes",
+    "Center the spinner both horizontally and vertically within its loading region",
+  ],
+
+  donts: [
+    "Do not use a spinner for determinate progress — use a progress bar with percentage instead",
+    "Do not display the spinner immediately — add a 300ms delay to prevent visual flash on fast operations",
+    "Do not leave aria-busy='true' on the parent container after loading completes",
+    "Do not use JavaScript setInterval for animation — rely on CSS animations or SVG for smooth rendering",
+    "Do not make the spinner focusable or add it to the tab order — it is a presentational status element",
+    "Do not use spinners as the only indicator of loading — pair with status text for screen reader users",
+    "Do not display percentage text alongside an indeterminate spinner — this creates a misleading experience",
+    "Do not override spinner token colors with hard-coded values — use the design token system consistently",
+  ],
+};

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

@@ -0,0 +1,252 @@
+/**
+ * status-dot.ts — Gold-standard design knowledge for Status Dot components
+ */
+import type { ComponentKnowledge } from "../types.js";
+
+export const statusDotKnowledge: ComponentKnowledge = {
+  description:
+    "Simple colored dot indicator | Conveys status at a glance | Paired with text label for accessibility",
+
+  stateSpecifications: [
+    {
+      state: "Default",
+      visualChange: "Solid filled circle in the corresponding status color with optional text label",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Resting state — dot displays current status; not interactive",
+    },
+    {
+      state: "Success",
+      visualChange: "Dot fill uses $status-dot-success token (green); communicates positive or completed status",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Operation succeeded, service is healthy, or item is approved",
+    },
+    {
+      state: "Warning",
+      visualChange: "Dot fill uses $status-dot-warning token (amber/yellow); communicates caution or degraded state",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Service is degraded, approaching a limit, or requires attention",
+    },
+    {
+      state: "Error",
+      visualChange: "Dot fill uses $status-dot-error token (red); communicates failure or critical issue",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Operation failed, service is down, or item has a blocking issue",
+    },
+    {
+      state: "Info",
+      visualChange: "Dot fill uses $status-dot-info token (blue); communicates neutral informational status",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "General informational status — neither positive nor negative",
+    },
+    {
+      state: "Neutral",
+      visualChange: "Dot fill uses $status-dot-neutral token (gray); communicates inactive or unknown status",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "No status determined, pending, or not yet started",
+    },
+    {
+      state: "Offline",
+      visualChange: "Dot fill uses $status-dot-neutral token with a hollow ring style or muted gray",
+      opacity: "0.6",
+      cursorWeb: "default",
+      usage: "User or service is offline or unavailable",
+    },
+    {
+      state: "Online",
+      visualChange: "Dot fill uses $status-dot-online token (green); may include pulse animation",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "User or service is actively online and available",
+    },
+  ],
+
+  propertyDescriptions: {
+    status: "Status variant controlling the dot color — success, warning, error, info, neutral, offline, or online",
+    size: "Dimensional preset controlling dot diameter and optional label font-size (sm, md, lg)",
+    label: "Visible text rendered beside the dot providing accessible context for the status color",
+    pulse: "When true a subtle radial pulse animation plays on the dot to indicate live/active status",
+  },
+
+  sizeSpecifications: [
+    {
+      size: "Small",
+      height: "16px",
+      paddingLR: "0px",
+      fontSize: "12px",
+      iconSize: "8px",
+      borderRadius: "50%",
+    },
+    {
+      size: "Medium",
+      height: "20px",
+      paddingLR: "0px",
+      fontSize: "14px",
+      iconSize: "10px",
+      borderRadius: "50%",
+    },
+    {
+      size: "Large",
+      height: "24px",
+      paddingLR: "0px",
+      fontSize: "16px",
+      iconSize: "12px",
+      borderRadius: "50%",
+    },
+  ],
+
+  designTokenBindings: [
+    {
+      property: "Fill (Success)",
+      tokenName: "$status-dot-success",
+      role: "Dot fill color for success/healthy status",
+      fallback: "#12B76A",
+    },
+    {
+      property: "Fill (Warning)",
+      tokenName: "$status-dot-warning",
+      role: "Dot fill color for warning/degraded status",
+      fallback: "#F79009",
+    },
+    {
+      property: "Fill (Error)",
+      tokenName: "$status-dot-error",
+      role: "Dot fill color for error/critical status",
+      fallback: "#F04438",
+    },
+    {
+      property: "Fill (Info)",
+      tokenName: "$status-dot-info",
+      role: "Dot fill color for informational status",
+      fallback: "#2E90FA",
+    },
+    {
+      property: "Fill (Neutral)",
+      tokenName: "$status-dot-neutral",
+      role: "Dot fill color for inactive/unknown status",
+      fallback: "#98A2B3",
+    },
+    {
+      property: "Fill (Online)",
+      tokenName: "$status-dot-online",
+      role: "Dot fill color for online/available status",
+      fallback: "#12B76A",
+    },
+    {
+      property: "Label Color",
+      tokenName: "$text-secondary",
+      role: "Text color for the accompanying label",
+      fallback: "#344054",
+    },
+    {
+      property: "Font Family",
+      tokenName: "$font-family-sans",
+      role: "Label typeface",
+      fallback: "Inter, system-ui, sans-serif",
+    },
+    {
+      property: "Pulse Animation",
+      tokenName: "$animation-pulse-duration",
+      role: "Duration of the radial pulse keyframe animation",
+      fallback: "1.5s ease-in-out infinite",
+    },
+  ],
+
+  structureRules: [
+    "Container uses horizontal Auto Layout with center vertical alignment",
+    "Dot is a circle frame with equal width and height; border-radius is always 50%",
+    "Label text is a direct sibling of the dot — no intermediate wrappers",
+    "Spacing between dot and label uses the $spacing-xs token (4px default)",
+    "When label is hidden, container collapses to dot size only",
+    "Pulse animation uses a pseudo-element or separate layer behind the dot with opacity fade",
+    "Dot must never be the sole indicator — always pair with a text label or tooltip",
+  ],
+
+  typeHierarchyRules: [
+    "Label font weight is Regular (400) — status context comes from color and text, not weight",
+    "Text uses sentence case ('Service healthy', not 'SERVICE HEALTHY')",
+    "Label font size scales with the size prop; always one step smaller than body text",
+    "No underline or decoration on label text",
+  ],
+
+  interactionRules: [
+    { event: "None", trigger: "N/A", action: "Status dot is a non-interactive indicator; no pointer events by default" },
+    { event: "Hover (optional)", trigger: "pointerenter on container", action: "If wrapped in a tooltip, show tooltip with full status description" },
+    { event: "Pulse Start", trigger: "pulse prop set to true", action: "Begin radial pulse animation on the dot layer" },
+    { event: "Pulse Stop", trigger: "pulse prop set to false", action: "Stop pulse animation; dot returns to static fill" },
+    { event: "Status Change", trigger: "status prop updates", action: "Dot fill transitions smoothly to new status color using $transition-interactive" },
+  ],
+
+  contentGuidance: [
+    "Always provide a text label next to the dot — color alone must never convey meaning (WCAG 1.4.1)",
+    "Labels should describe the status concisely: 'Online', 'Degraded', 'Offline', 'Healthy'",
+    "Avoid using status dots without context — always clarify what the status refers to",
+    "For tables or lists, keep labels consistent across rows (e.g. all use the same vocabulary)",
+    "Use the pulse animation sparingly — only for truly live/active indicators to avoid visual noise",
+  ],
+
+  responsiveBehaviour: [
+    { breakpoint: "Mobile (<768px)", behavior: "Dot and label render inline; label may truncate in tight table cells" },
+    { breakpoint: "Tablet (768-1023px)", behavior: "Standard rendering; no size changes" },
+    { breakpoint: "Desktop (1024-1439px)", behavior: "Standard rendering; status dots commonly appear in tables, sidebars, and dashboards" },
+    { breakpoint: "Ultra-wide (>=1440px)", behavior: "No scaling — dot sizes remain fixed at their size-prop values" },
+  ],
+
+  accessibilitySpec: {
+    intro:
+      "Status dots rely on color to convey meaning, which is invisible to colorblind and screen-reader users. Accessible implementation is non-negotiable.",
+    requirements: [
+      { requirement: "Color Independence", level: "A", notes: "WCAG 1.4.1 — Color must not be the only visual means of conveying status; always include a text label" },
+      { requirement: "ARIA Role", level: "A", notes: "Container should use role='status' so assistive tech announces changes as a live region" },
+      { requirement: "Accessible Name", level: "A", notes: "The dot element itself needs aria-label (e.g. 'Status: Online') or be marked aria-hidden with the label providing context" },
+      { requirement: "Contrast Ratio", level: "AA", notes: "Dot color against its background must meet 3:1 non-text contrast; label text must meet 4.5:1" },
+      { requirement: "Live Region", level: "AA", notes: "When status changes dynamically, the container should be an aria-live='polite' region to announce updates" },
+      { requirement: "Motion Sensitivity", level: "AAA", notes: "Pulse animation must respect prefers-reduced-motion and stop when the user preference is set" },
+    ],
+    outro: [
+      "Never use a standalone dot without text — screen readers cannot perceive color",
+      "When status dots appear in a table, ensure the column header clearly labels the data as 'Status'",
+      "Test with high-contrast mode to verify dots remain visible against forced backgrounds",
+    ],
+  },
+
+  qaAcceptanceCriteria: [
+    { check: "Visual Regression", platform: "All", expectedResult: "Dot renders at correct size and color for each status variant" },
+    { check: "Label Pairing", platform: "All", expectedResult: "Text label is always present and accurately describes the status" },
+    { check: "Color Tokens", platform: "All", expectedResult: "Each status maps to its correct design token; no hard-coded hex values" },
+    { check: "Pulse Animation", platform: "Web", expectedResult: "Pulse plays when pulse=true; stops when false; respects prefers-reduced-motion" },
+    { check: "Screen Reader", platform: "Web", expectedResult: "Announces status text via role='status' or aria-label; dot alone is not announced" },
+    { check: "Color Blindness", platform: "All", expectedResult: "Status is distinguishable without color via the text label" },
+    { check: "Contrast", platform: "All", expectedResult: "Dot meets 3:1 non-text contrast; label meets 4.5:1 text contrast" },
+    { check: "Dynamic Update", platform: "Web", expectedResult: "Changing status prop updates dot color and label; aria-live region announces change" },
+    { check: "Size Variants", platform: "All", expectedResult: "sm=8px dot, md=10px dot, lg=12px dot with proportional label sizing" },
+    { check: "High Contrast Mode", platform: "Web", expectedResult: "Dot remains visible with a border or alternate indicator in forced-colors mode" },
+    { check: "Tooltip Fallback", platform: "Web", expectedResult: "If label is hidden for space, tooltip provides full status description on hover/focus" },
+    { check: "RTL Support", platform: "Web", expectedResult: "Label renders on the correct side of the dot in RTL layouts" },
+  ],
+
+  dos: [
+    "Always pair the status dot with a visible text label for accessibility",
+    "Use the pulse animation only for live/active indicators like 'Online' or 'Recording'",
+    "Map each status type to its corresponding design token — never hard-code colors",
+    "Use role='status' on the container for dynamic status updates",
+    "Respect prefers-reduced-motion by disabling the pulse animation when set",
+    "Keep label text concise and consistent across the interface",
+    "Ensure sufficient contrast between the dot color and its background surface",
+  ],
+
+  donts: [
+    "Do not use a status dot without a text label — color alone is not accessible (WCAG 1.4.1)",
+    "Do not make the dot interactive — use a separate button or link for actions",
+    "Do not use more than 6-7 status types in a single interface to avoid cognitive overload",
+    "Do not hard-code hex values — always reference status design tokens",
+    "Do not use the pulse animation on multiple dots simultaneously — it creates visual noise",
+    "Do not resize dots outside the defined size presets (sm, md, lg)",
+    "Do not rely on the dot as the primary content — it is a supplementary indicator only",
+  ],
+};