@sarjallab09/figma-intelligence 1.0.1 → 1.2.0

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

@@ -1,330 +0,0 @@
-/**
- * Knowledge: Input / Text Field
- */
-import type { ComponentKnowledge } from "../types.js";
-
-export const inputKnowledge: ComponentKnowledge = {
-  description:
-    "Text entry field | Captures user input | Form data collection element",
-
-  stateSpecifications: [
-    {
-      state: "Default",
-      visualChange: "Neutral border, empty or placeholder text visible",
-      opacity: "1",
-      cursorWeb: "text",
-      usage: "Idle state awaiting user interaction",
-    },
-    {
-      state: "Hover",
-      visualChange: "Border color darkens slightly",
-      opacity: "1",
-      cursorWeb: "text",
-      usage: "Indicates the field is interactive on pointer hover",
-    },
-    {
-      state: "Focused",
-      visualChange: "Focus ring appears, border changes to primary color",
-      opacity: "1",
-      cursorWeb: "text",
-      usage: "Field is actively receiving keyboard input",
-    },
-    {
-      state: "Filled",
-      visualChange: "User-entered value replaces placeholder text",
-      opacity: "1",
-      cursorWeb: "text",
-      usage: "Field contains a user-supplied value",
-    },
-    {
-      state: "Error",
-      visualChange:
-        "Border turns error color, error message appears below field",
-      opacity: "1",
-      cursorWeb: "text",
-      usage: "Validation has failed; user must correct the value",
-    },
-    {
-      state: "Disabled",
-      visualChange: "Muted background and text, no interaction possible",
-      opacity: "0.4",
-      cursorWeb: "not-allowed",
-      usage: "Field is non-interactive due to form logic or permissions",
-    },
-    {
-      state: "Read-only",
-      visualChange:
-        "Value is visible but field chrome is reduced; no editable caret",
-      opacity: "1",
-      cursorWeb: "default",
-      usage: "Displays a value the user cannot modify",
-    },
-  ],
-
-  propertyDescriptions: {
-    value: "Current text content of the input",
-    placeholder: "Hint text shown when the field is empty",
-    label: "Visible label rendered above or beside the field",
-    helperText:
-      "Supplementary guidance displayed below the field (e.g. format hint)",
-    error: "Boolean flag indicating the field is in an error state",
-    errorMessage: "Descriptive text explaining the validation failure",
-    disabled: "Prevents all user interaction when true",
-    readOnly: "Displays the value but disallows editing",
-    required: "Marks the field as mandatory for form submission",
-    type: "HTML input type attribute (text, email, password, number, etc.)",
-    maxLength: "Maximum number of characters the field will accept",
-    prefix: "Static content rendered inside the field before the value (e.g. $)",
-    suffix:
-      "Static content rendered inside the field after the value (e.g. kg)",
-    icon: "Optional icon displayed inside the field for contextual meaning",
-  },
-
-  sizeSpecifications: [
-    {
-      size: "Small",
-      height: "32px",
-      paddingLR: "8px",
-      fontSize: "12px",
-      iconSize: "16px",
-      borderRadius: "4px",
-    },
-    {
-      size: "Medium",
-      height: "40px",
-      paddingLR: "12px",
-      fontSize: "14px",
-      iconSize: "20px",
-      borderRadius: "6px",
-    },
-    {
-      size: "Large",
-      height: "48px",
-      paddingLR: "16px",
-      fontSize: "16px",
-      iconSize: "24px",
-      borderRadius: "8px",
-    },
-  ],
-
-  designTokenBindings: [
-    {
-      property: "border-color",
-      tokenName: "input/border/default",
-      role: "Default border surrounding the field",
-      fallback: "#C6C6C6",
-    },
-    {
-      property: "background-color",
-      tokenName: "input/bg/default",
-      role: "Field background fill",
-      fallback: "#FFFFFF",
-    },
-    {
-      property: "color",
-      tokenName: "input/text/default",
-      role: "Entered text color",
-      fallback: "#161616",
-    },
-    {
-      property: "color (placeholder)",
-      tokenName: "input/text/placeholder",
-      role: "Placeholder hint text color",
-      fallback: "#A8A8A8",
-    },
-    {
-      property: "color (label)",
-      tokenName: "input/label/default",
-      role: "Label text color above the field",
-      fallback: "#525252",
-    },
-    {
-      property: "box-shadow (focus)",
-      tokenName: "input/focus-ring",
-      role: "Focus ring outline on keyboard focus",
-      fallback: "0 0 0 2px #0F62FE",
-    },
-    {
-      property: "border-color (error)",
-      tokenName: "input/border/error",
-      role: "Border color when validation fails",
-      fallback: "#DA1E28",
-    },
-    {
-      property: "color (error text)",
-      tokenName: "input/text/error",
-      role: "Error message text color",
-      fallback: "#DA1E28",
-    },
-  ],
-
-  structureRules: [
-    "Label is always a separate element positioned above the field",
-    "Helper text and error message occupy the same slot below the field — only one is visible at a time",
-    "Prefix and suffix are inline elements inside the field container, before/after the editable area",
-    "Icon is placed at the leading or trailing edge inside the field, never both simultaneously",
-    "A clear button appears at the trailing edge when the field contains a value and is not disabled or read-only",
-  ],
-
-  typeHierarchyRules: [
-    "Label uses the component's base font size at semibold weight",
-    "Input value text uses the component's base font size at regular weight",
-    "Placeholder text matches the value font size but uses placeholder color",
-    "Helper text and error message use a font size one step smaller than the value text",
-  ],
-
-  interactionRules: [
-    {
-      event: "click",
-      trigger: "User clicks anywhere inside the field area",
-      action: "Field gains focus and displays the text caret",
-    },
-    {
-      event: "keydown",
-      trigger: "User types while field is focused",
-      action:
-        "Characters are inserted at the caret position; value updates in real time",
-    },
-    {
-      event: "blur",
-      trigger: "Field loses focus (user clicks elsewhere or tabs away)",
-      action:
-        "Validation fires; error state is applied if the value is invalid",
-    },
-    {
-      event: "click (clear)",
-      trigger: "User clicks the clear button inside the field",
-      action:
-        "Value is emptied, field retains focus, and onChange callback fires",
-    },
-  ],
-
-  contentGuidance: [
-    "Labels should be placed above the field, not inside it",
-    "Use placeholder text to show an example value, never as a replacement for the label",
-    "Helper text should describe the expected format or constraints (e.g. 'Must be at least 8 characters')",
-    "Error messages must be specific and actionable — avoid generic phrases like 'Invalid input'",
-    "Keep labels concise: one to three words when possible",
-  ],
-
-  responsiveBehaviour: [
-    {
-      breakpoint: "< 480px",
-      behavior:
-        "Field stretches to full container width; label stacks above the field",
-    },
-    {
-      breakpoint: "480px – 1024px",
-      behavior:
-        "Field width follows the grid column span; side-by-side labels are acceptable",
-    },
-    {
-      breakpoint: "> 1024px",
-      behavior:
-        "Field width may be constrained to a max-width for readability; inline labels permitted",
-    },
-  ],
-
-  accessibilitySpec: {
-    intro:
-      "The text input must be operable via keyboard and correctly announce its label, state, and errors to assistive technology.",
-    requirements: [
-      {
-        requirement:
-          "Field has role=\"textbox\" (implicit via <input>) and a visible <label> element linked by htmlFor/id",
-        level: "A",
-        notes: "WCAG 1.3.1 – Info and Relationships",
-      },
-      {
-        requirement:
-          "When the field is required, aria-required=\"true\" is set and the label includes a visual required indicator",
-        level: "A",
-        notes: "WCAG 3.3.2 – Labels or Instructions",
-      },
-      {
-        requirement:
-          "When validation fails, aria-invalid=\"true\" is set on the input",
-        level: "A",
-        notes: "WCAG 3.3.1 – Error Identification",
-      },
-      {
-        requirement:
-          "Error message element is linked to the input via aria-describedby so screen readers announce the error on focus",
-        level: "A",
-        notes: "WCAG 3.3.1 – Error Identification",
-      },
-      {
-        requirement:
-          "Text and border meet WCAG AA contrast ratio (4.5:1 for text, 3:1 for non-text UI)",
-        level: "AA",
-        notes: "WCAG 1.4.3 / 1.4.11",
-      },
-      {
-        requirement:
-          "Focus indicator is visible with at least 3:1 contrast against adjacent colors",
-        level: "AA",
-        notes: "WCAG 2.4.7 – Focus Visible",
-      },
-    ],
-    outro: [
-      "Test with VoiceOver (macOS/iOS) and NVDA (Windows) to verify label, required, and error announcements",
-      "Ensure Tab moves focus into the field and Shift+Tab moves it out",
-      "Verify that autocomplete attributes (autocomplete) are present for common fields (name, email, address)",
-    ],
-  },
-
-  qaAcceptanceCriteria: [
-    {
-      check: "Focus behavior",
-      platform: "Web / Mobile",
-      expectedResult:
-        "Clicking or tapping the field shows a visible focus ring and text caret",
-    },
-    {
-      check: "Validation on blur",
-      platform: "Web",
-      expectedResult:
-        "Leaving an invalid required field displays the error message and sets the error border",
-    },
-    {
-      check: "Character count",
-      platform: "Web / Mobile",
-      expectedResult:
-        "When maxLength is set, the user cannot type beyond the limit and a counter is displayed",
-    },
-    {
-      check: "Paste handling",
-      platform: "Web",
-      expectedResult:
-        "Pasting text that exceeds maxLength truncates to the limit; value updates correctly",
-    },
-    {
-      check: "RTL support",
-      platform: "Web",
-      expectedResult:
-        "In RTL locales the label, value, and helper text are right-aligned; prefix/suffix positions are mirrored",
-    },
-    {
-      check: "Screen reader announcement",
-      platform: "Web",
-      expectedResult:
-        "VoiceOver/NVDA reads: label, required status, current value, and any error message on focus",
-    },
-  ],
-
-  dos: [
-    "Always pair the input with a visible label element",
-    "Use helper text to clarify expected format or constraints",
-    "Provide real-time character count when maxLength is enforced",
-    "Show the clear button only when the field has a value",
-    "Match the input size variant to surrounding form controls for visual harmony",
-  ],
-
-  donts: [
-    "Do not use placeholder text as a substitute for a label",
-    "Do not disable the field without explaining why to the user",
-    "Do not validate on every keystroke — wait for blur or explicit submission",
-    "Do not show both helper text and error message simultaneously",
-    "Do not remove the focus ring for sighted keyboard users",
-  ],
-};

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

@@ -1,247 +0,0 @@
-/**
- * link.ts — Gold-standard design knowledge for Link / Anchor components
- */
-import type { ComponentKnowledge } from "../types.js";
-
-export const linkKnowledge: ComponentKnowledge = {
-  description:
-    "Navigational text element | Inline anchor | Standalone hyperlink — distinct from Button",
-
-  stateSpecifications: [
-    {
-      state: "Default",
-      visualChange: "Text rendered in link color with underline style per configuration (always, hover-only, or none)",
-      opacity: "1",
-      cursorWeb: "pointer",
-      usage: "Link is interactive and available for navigation — default resting appearance",
-    },
-    {
-      state: "Hover",
-      visualChange: "Underline appears (if hover-only) and text color shifts to hover token; cursor remains pointer",
-      opacity: "1",
-      cursorWeb: "pointer",
-      usage: "User's pointer is over the link — visual feedback indicates interactivity",
-    },
-    {
-      state: "Visited",
-      visualChange: "Text color changes to visited token — typically a muted or purple-shifted variant",
-      opacity: "1",
-      cursorWeb: "pointer",
-      usage: "User has previously navigated to this link's destination — provides wayfinding context",
-    },
-    {
-      state: "Active",
-      visualChange: "Text color darkens or shifts to active token during the press — momentary visual feedback",
-      opacity: "1",
-      cursorWeb: "pointer",
-      usage: "User is pressing the link — provides tactile feedback before navigation",
-    },
-    {
-      state: "Focus",
-      visualChange: "2px focus ring appears around the link text with 2px offset; link color unchanged",
-      opacity: "1",
-      cursorWeb: "pointer",
-      usage: "Link is focused via keyboard navigation — visible focus indicator required for accessibility",
-    },
-    {
-      state: "Disabled",
-      visualChange: "Text color shifts to disabled token; underline removed; no href attribute rendered",
-      opacity: "0.5",
-      cursorWeb: "not-allowed",
-      usage: "Link is temporarily unavailable — navigation is prevented and visual affordance is removed",
-    },
-  ],
-
-  propertyDescriptions: {
-    label: "Visible text content of the link — must be descriptive of the destination, never generic",
-    href: "Navigation target URL — when omitted or empty, the link renders in disabled state",
-    external: "Boolean — when true, adds target='_blank', rel='noopener noreferrer', and an external link icon",
-    underline: "Underline display mode — 'always' (default), 'hover' (shows on hover only), or 'none' (no underline)",
-    size: "Dimensional preset controlling font-size and line-height — sm, md, or lg",
-    inline: "Boolean — when true, link renders inline within paragraph text; when false, renders as standalone block-level element",
-    iconEnd: "Optional trailing icon slot — typically used for external link indicator or download icon",
-    color: "Color variant override — defaults to the primary link token; can be set to inherit for body text styling",
-    disabled: "Boolean — when true, removes href, sets aria-disabled, and applies disabled visual styling",
-    rel: "Relationship attribute — automatically set to 'noopener noreferrer' for external links; can be manually overridden",
-    target: "Link target — automatically set to '_blank' for external links; defaults to '_self' for internal navigation",
-  },
-
-  sizeSpecifications: [
-    {
-      size: "Small (sm)",
-      height: "16px",
-      paddingLR: "0px",
-      fontSize: "12px",
-      iconSize: "12px",
-      borderRadius: "0px",
-    },
-    {
-      size: "Medium (md)",
-      height: "20px",
-      paddingLR: "0px",
-      fontSize: "14px",
-      iconSize: "14px",
-      borderRadius: "0px",
-    },
-    {
-      size: "Large (lg)",
-      height: "24px",
-      paddingLR: "0px",
-      fontSize: "16px",
-      iconSize: "16px",
-      borderRadius: "0px",
-    },
-  ],
-
-  designTokenBindings: [
-    {
-      property: "Default Text",
-      tokenName: "$link-text-default",
-      role: "Primary link text color in default resting state",
-      fallback: "#2563EB",
-    },
-    {
-      property: "Hover Text",
-      tokenName: "$link-text-hover",
-      role: "Link text color on pointer hover — slightly darker or shifted for feedback",
-      fallback: "#1D4ED8",
-    },
-    {
-      property: "Visited Text",
-      tokenName: "$link-text-visited",
-      role: "Link text color after the destination has been visited",
-      fallback: "#7C3AED",
-    },
-    {
-      property: "Active Text",
-      tokenName: "$link-text-active",
-      role: "Link text color during the active/pressed state",
-      fallback: "#1E40AF",
-    },
-    {
-      property: "Disabled Text",
-      tokenName: "$link-text-disabled",
-      role: "Muted link text color when the link is disabled",
-      fallback: "#D0D5DD",
-    },
-    {
-      property: "Underline",
-      tokenName: "$link-underline",
-      role: "Underline color — typically matches the text color or a lighter variant",
-      fallback: "currentColor",
-    },
-    {
-      property: "Focus Ring",
-      tokenName: "$focus-ring",
-      role: "Visible focus indicator color for keyboard navigation — shared across all focusable components",
-      fallback: "#2563EB",
-    },
-    {
-      property: "Font Family",
-      tokenName: "$font-family-sans",
-      role: "Link typeface — inherits from body text; does not introduce a separate font stack",
-      fallback: "Inter, system-ui, sans-serif",
-    },
-  ],
-
-  structureRules: [
-    "Links render as native <a> elements with an href attribute — never as <span> or <div> with click handlers",
-    "Inline links flow naturally within paragraph text and inherit the parent's font-size and line-height",
-    "Standalone links render as block-level flex containers with their own size preset applied",
-    "External link icon (if present) is placed after the label text with a 4px gap, sized to match the font",
-    "Underline is rendered via text-decoration (not border-bottom) for correct baseline alignment",
-    "Focus ring uses outline with 2px width and 2px offset — not box-shadow — for High Contrast Mode compatibility",
-    "Disabled links render as <a> without an href attribute (not a <span>) to preserve semantic structure",
-  ],
-
-  typeHierarchyRules: [
-    "Link font-size follows the size prop (12/14/16px) and inherits font-weight from surrounding text",
-    "Inline links must match the parent paragraph's font-size and line-height exactly — they do not introduce size breaks",
-    "Link text is never bold or uppercase — it relies on color and underline for visual differentiation",
-    "Standalone links may use font-weight: 500 (medium) for subtle emphasis without disrupting body text hierarchy",
-    "External link icon is vertically centered with the text baseline using inline-flex alignment",
-  ],
-
-  interactionRules: [
-    { event: "Click", trigger: "pointerup on link", action: "Navigate to href destination; if external, open in new tab with noopener noreferrer" },
-    { event: "Hover", trigger: "pointerenter on link", action: "Apply hover text color; show underline if underline='hover'; cursor remains pointer" },
-    { event: "Hover Out", trigger: "pointerleave on link", action: "Revert to default text color; hide underline if underline='hover'" },
-    { event: "Focus", trigger: "keyboard focus via Tab", action: "Display 2px focus ring around link text with 2px offset" },
-    { event: "Active", trigger: "pointerdown on link", action: "Apply active text color for press feedback; revert on pointerup" },
-    { event: "Disabled Click", trigger: "pointerup on disabled link", action: "No navigation occurs; event is suppressed; no href is present" },
-    { event: "External Navigation", trigger: "Click on external link", action: "Screen reader announces 'opens in new window' before navigation" },
-    { event: "Context Menu", trigger: "Right-click on link", action: "Browser context menu shows link-specific options (open in new tab, copy URL)" },
-  ],
-
-  contentGuidance: [
-    "Write descriptive link text that conveys the destination — never use 'click here', 'read more', or 'learn more' alone",
-    "Link text should make sense out of context — screen readers may navigate links in isolation via rotor/elements list",
-    "Keep link text concise (2-5 words for inline links) — long links are harder to scan and click",
-    "Do not embed entire sentences as links — link only the meaningful destination phrase",
-    "External links should indicate they open in a new window, either via icon or explicit text like '(opens in new tab)'",
-    "Use links for navigation to a new page or resource; use buttons for in-page actions that do not change the URL",
-    "Avoid adjacent links without visual separation — use list markup or sufficient spacing between link groups",
-  ],
-
-  responsiveBehaviour: [
-    { breakpoint: "Mobile (<768px)", behavior: "Links maintain minimum 44px touch target via line-height and spacing; font-size may increase to 16px for tap friendliness" },
-    { breakpoint: "Tablet (768-1023px)", behavior: "Same link sizing as desktop; touch targets ensured by adequate line-height" },
-    { breakpoint: "Desktop (1024-1439px)", behavior: "Standard link rendering at specified size presets with pointer-based interactions" },
-    { breakpoint: "Ultra-wide (>=1440px)", behavior: "No scaling — links follow content width and do not stretch or reposition with viewport" },
-  ],
-
-  accessibilitySpec: {
-    intro:
-      "Links must use native <a> elements with descriptive text, proper focus management, and clear indication of navigation behavior.",
-    requirements: [
-      { requirement: "Semantic <a> element", level: "A", notes: "Links must use <a href> — if a non-anchor element is used, it must have role='link' and tabindex='0' with Enter/Space key handling" },
-      { requirement: "Descriptive link text", level: "A", notes: "Link text must describe the destination — 'click here' or 'read more' alone fails this requirement" },
-      { requirement: "External link announcement", level: "A", notes: "External links (target='_blank') must announce 'opens in new window' via aria-label or visually hidden text" },
-      { requirement: "Focus visible", level: "AA", notes: "Links must display a visible focus indicator (2px outline, 2px offset) meeting 3:1 contrast against adjacent colors" },
-      { requirement: "Color independence", level: "A", notes: "Links within body text must be distinguishable by more than color alone — underline or other non-color indicator required" },
-      { requirement: "Contrast", level: "AA", notes: "Link text must meet 4.5:1 contrast against background; underline must meet 3:1 non-text contrast" },
-      { requirement: "Touch target", level: "AAA", notes: "On touch devices, link tap target must be at least 44x44px — achieved via line-height and padding" },
-    ],
-    outro: [
-      "Screen readers announce link text followed by 'link' role — ensure the text is meaningful in isolation",
-      "Visited link color change provides wayfinding but must not be the only indicator of visited state for colorblind users",
-    ],
-  },
-
-  qaAcceptanceCriteria: [
-    { check: "Navigation", platform: "All", expectedResult: "Clicking a link navigates to the specified href destination" },
-    { check: "External Link", platform: "All", expectedResult: "External links open in a new tab with rel='noopener noreferrer' and display an external icon" },
-    { check: "Hover Underline", platform: "Web", expectedResult: "Links with underline='hover' show underline on hover and hide it on pointer leave" },
-    { check: "Visited Color", platform: "Web", expectedResult: "Previously visited links display the visited color token; unvisited links use default token" },
-    { check: "Focus Ring", platform: "Web", expectedResult: "Tab-focused links display a 2px outline with 2px offset meeting 3:1 contrast" },
-    { check: "Disabled State", platform: "All", expectedResult: "Disabled links have no href, show muted color, and prevent navigation on click" },
-    { check: "Inline Rendering", platform: "All", expectedResult: "Inline links flow within paragraph text and inherit the parent's font-size and line-height" },
-    { check: "Standalone Rendering", platform: "All", expectedResult: "Standalone links render with their own size preset and display as flex block elements" },
-    { check: "Screen Reader", platform: "Web", expectedResult: "Links announce descriptive text with 'link' role; external links announce 'opens in new window'" },
-    { check: "Keyboard Navigation", platform: "Web", expectedResult: "Links are reachable via Tab and activated with Enter key; Space does not trigger navigation" },
-    { check: "Touch Target", platform: "Mobile", expectedResult: "Link tap target is at least 44x44px on touch devices via line-height and spacing" },
-    { check: "Dark Mode", platform: "All", expectedResult: "All link color tokens resolve correctly in dark mode with sufficient contrast" },
-  ],
-
-  dos: [
-    "Use native <a> elements with a valid href for all navigational links",
-    "Write descriptive link text that conveys the destination clearly",
-    "Add rel='noopener noreferrer' and target='_blank' for external links automatically",
-    "Include a visible external link icon for links that open in a new window",
-    "Ensure links are visually distinguishable from body text by underline — not color alone",
-    "Provide visited link styling to give users wayfinding context",
-    "Use links for navigation and buttons for actions — do not conflate the two patterns",
-    "Test link text in isolation (via screen reader link list) to verify it is self-descriptive",
-  ],
-
-  donts: [
-    "Do not use 'click here', 'read more', or 'learn more' as standalone link text",
-    "Do not use <button> or <span> with an onClick handler when an <a> with href is appropriate",
-    "Do not open internal links in a new tab — reserve target='_blank' for external destinations only",
-    "Do not remove the underline from inline links in body text — it is the primary non-color indicator",
-    "Do not disable links by simply hiding them — render them with aria-disabled and no href instead",
-    "Do not use link styling for non-navigational actions — use a button component instead",
-    "Do not nest interactive elements inside links — no buttons, inputs, or other links within an <a>",
-    "Do not rely on color alone to differentiate links from surrounding text — always pair with underline or icon",
-  ],
-};