@sarjallab09/figma-intelligence 1.1.0 → 1.2.1

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

@@ -1,143 +0,0 @@
-import type { ComponentKnowledge } from "../types.js";
-
-export const tabsKnowledge: ComponentKnowledge = {
-  description:
-    "Content organizer | Sectioned view switcher | Tabbed navigation pattern",
-
-  stateSpecifications: [
-    { state: "Default-Unselected", visualChange: "Label in secondary color, no indicator bar", opacity: "1", cursorWeb: "pointer", usage: "Tab is available but not currently active" },
-    { state: "Hover-Unselected", visualChange: "Background tint appears behind label", opacity: "1", cursorWeb: "pointer", usage: "Pointer hovering over an inactive tab" },
-    { state: "Focus-Unselected", visualChange: "Focus ring around tab, no indicator", opacity: "1", cursorWeb: "default", usage: "Keyboard focus on an inactive tab" },
-    { state: "Selected", visualChange: "Bold label, indicator bar on bottom edge, primary text color", opacity: "1", cursorWeb: "default", usage: "Currently active tab showing its panel content" },
-    { state: "Selected-Focus", visualChange: "Focus ring around active tab with indicator bar", opacity: "1", cursorWeb: "default", usage: "Keyboard focus on the active tab" },
-    { state: "Disabled", visualChange: "Label dimmed, no hover/focus effects", opacity: "0.4", cursorWeb: "not-allowed", usage: "Tab content is unavailable or locked" },
-    { state: "Overflow", visualChange: "Scroll arrows or 'more' button visible at tab bar edges", opacity: "1", cursorWeb: "pointer", usage: "Too many tabs to fit in available width" },
-  ],
-
-  propertyDescriptions: {
-    selectedIndex: "Zero-based index of the currently active tab",
-    variant: "Visual style — line (underline indicator), contained (filled background), or vertical (sidebar tabs)",
-    size: "Height variant affecting padding and font size of tab labels",
-    label: "Visible text for each individual tab trigger",
-    icon: "Optional leading icon displayed before the tab label",
-    badge: "Notification badge (dot or count) on a tab for unread/new content",
-    disabled: "Prevents a specific tab from being selected",
-    dismissible: "Shows a close icon on the tab allowing removal from the tab bar",
-    scrollable: "Enables horizontal scrolling when tabs overflow container width",
-  },
-
-  sizeSpecifications: [
-    { size: "sm", height: "32px", paddingLR: "12px", fontSize: "12px", iconSize: "16px", borderRadius: "0px" },
-    { size: "md", height: "40px", paddingLR: "16px", fontSize: "14px", iconSize: "16px", borderRadius: "0px" },
-    { size: "lg", height: "48px", paddingLR: "16px", fontSize: "14px", iconSize: "20px", borderRadius: "0px" },
-    { size: "xl", height: "56px", paddingLR: "20px", fontSize: "16px", iconSize: "20px", borderRadius: "0px" },
-    { size: "contained-md", height: "40px", paddingLR: "16px", fontSize: "14px", iconSize: "16px", borderRadius: "4px 4px 0 0" },
-  ],
-
-  designTokenBindings: [
-    { property: "indicator-bar", tokenName: "color/border/interactive", role: "Bottom border of the selected tab", fallback: "#0F62FE" },
-    { property: "label-selected", tokenName: "color/text/primary", role: "Text color of the active tab", fallback: "#161616" },
-    { property: "label-unselected", tokenName: "color/text/secondary", role: "Text color of inactive tabs", fallback: "#525252" },
-    { property: "hover-bg", tokenName: "color/layer/hover/01", role: "Background tint on hover for unselected tab", fallback: "rgba(141,141,141,0.12)" },
-    { property: "divider", tokenName: "color/border/subtle/01", role: "Bottom border of the entire tab bar", fallback: "#E0E0E0" },
-    { property: "focus-ring", tokenName: "color/focus", role: "Keyboard focus outline color", fallback: "#0F62FE" },
-    { property: "badge-bg", tokenName: "color/support/error", role: "Notification badge background", fallback: "#DA1E28" },
-  ],
-
-  structureRules: [
-    "Tab bar uses role='tablist' with individual tabs using role='tab'",
-    "Each tab must have a corresponding panel with role='tabpanel' linked via aria-controls/aria-labelledby",
-    "The indicator bar is 2–3px tall and positioned at the bottom edge of the selected tab",
-    "Indicator animates horizontally to slide from the previous tab to the newly selected tab",
-    "Contained variant wraps each tab in a filled rectangle; selected tab shares background with the panel",
-    "Overflow tabs are accessible via scroll buttons or a dropdown 'more' menu at the end",
-    "Tab panels must be direct siblings or linked via IDREF; only the active panel is visible",
-  ],
-
-  typeHierarchyRules: [
-    "Tab labels use body-compact-01 (14px) for md/lg and label-01 (12px) for sm",
-    "Selected tab label may use semibold weight to reinforce active state",
-    "Badge count uses caption-01 (12px) with inverse text on the badge background",
-    "Tab labels should be single-line; truncate with ellipsis at max-width",
-    "Vertical tab labels use body-01 (14px/20px) with left alignment",
-    "Label width is content-driven with min-width of 64px and max-width of 200px",
-    "If icons are used, all tabs in the bar must have icons for visual consistency",
-  ],
-
-  interactionRules: [
-    { event: "click", trigger: "User clicks an unselected tab", action: "Activate the tab, show its panel, update indicator position" },
-    { event: "keydown:ArrowRight", trigger: "Focus is on a tab in horizontal tablist", action: "Move focus to the next tab; wrap to first if at end" },
-    { event: "keydown:ArrowLeft", trigger: "Focus is on a tab in horizontal tablist", action: "Move focus to the previous tab; wrap to last if at start" },
-    { event: "keydown:Home", trigger: "Focus is on any tab", action: "Move focus to the first tab in the list" },
-    { event: "keydown:End", trigger: "Focus is on any tab", action: "Move focus to the last tab in the list" },
-    { event: "keydown:Enter/Space", trigger: "Focus is on an unselected tab (manual activation mode)", action: "Activate the focused tab and reveal its panel" },
-    { event: "keydown:Delete", trigger: "Focus is on a dismissible tab", action: "Remove the tab and move focus to the nearest remaining tab" },
-  ],
-
-  contentGuidance: [
-    "Tab labels should be 1–2 words; think nouns like 'Overview', 'Settings', 'Activity'",
-    "Do not use verbs for tab labels — tabs are not actions, they are content sections",
-    "Keep the number of tabs between 2 and 8; consider a different pattern for more sections",
-    "Order tabs by user priority — most-used section first",
-    "Avoid mixing tabs with icons and tabs without icons in the same bar",
-    "Badge counts should use compact number formatting (e.g. '99+' not '143')",
-    "If tabs control unrelated content, consider using top-level navigation instead",
-  ],
-
-  responsiveBehaviour: [
-    { breakpoint: "≥ 1056px (lg)", behavior: "All tabs visible inline; indicator animates between tabs" },
-    { breakpoint: "672–1055px (md)", behavior: "Tabs that overflow become scrollable with arrow buttons" },
-    { breakpoint: "< 672px (sm)", behavior: "Consider collapsing to a dropdown select or accordion pattern" },
-    { breakpoint: "Touch devices", behavior: "Support horizontal swipe gesture to switch between tab panels" },
-    { breakpoint: "Vertical variant", behavior: "Sidebar tabs remain visible; panels fill remaining width" },
-  ],
-
-  accessibilitySpec: {
-    intro:
-      "Tabs must implement the WAI-ARIA tabs pattern with proper roles, relationships, and keyboard support. Users must be able to discover and switch between tab panels using keyboard alone.",
-    requirements: [
-      { requirement: "Container must have role='tablist'", level: "A", notes: "Group all tab triggers inside the tablist" },
-      { requirement: "Each trigger must have role='tab' with aria-selected indicating active state", level: "A", notes: "aria-selected='true' on active tab, 'false' on others" },
-      { requirement: "Each panel must have role='tabpanel' and be labelled by its tab via aria-labelledby", level: "A", notes: "Tab uses aria-controls pointing to panel id" },
-      { requirement: "Only the selected tab should have tabindex='0'; others get tabindex='-1'", level: "A", notes: "Roving tabindex enables arrow key navigation" },
-      { requirement: "Arrow keys must move focus between tabs (left/right for horizontal, up/down for vertical)", level: "A", notes: "Focus wraps from last to first and vice versa" },
-      { requirement: "Disabled tabs must have aria-disabled='true' and be skipped by arrow key navigation", level: "A", notes: "Alternatively, disabled tabs can receive focus but not activate" },
-      { requirement: "Panels must be discoverable — hidden panels should use hidden attribute, not display:none with no aria", level: "AA", notes: "Ensures assistive tech can identify available panels" },
-    ],
-    outro: [
-      "Test that screen readers announce 'tab, 1 of 5, selected' pattern on focus",
-      "Verify arrow keys skip disabled tabs when navigating",
-      "Confirm Tab key moves focus from the tablist into the active panel content",
-    ],
-  },
-
-  qaAcceptanceCriteria: [
-    { check: "Clicking a tab shows its panel and hides others", platform: "All", expectedResult: "Only active panel is visible; indicator moves to clicked tab" },
-    { check: "Arrow keys navigate between tabs", platform: "Web", expectedResult: "Focus moves; wrap at boundaries; disabled tabs skipped" },
-    { check: "Tab key moves focus into the panel", platform: "Web", expectedResult: "Focus leaves tablist and enters active panel's first focusable element" },
-    { check: "Indicator animates between tabs", platform: "Web", expectedResult: "Smooth 200ms slide transition for the indicator bar" },
-    { check: "Overflow tabs are accessible", platform: "Web", expectedResult: "Scroll buttons appear; all tabs reachable via keyboard" },
-    { check: "Dismissible tab can be removed", platform: "Web", expectedResult: "Tab removed, focus moves to nearest sibling, panel removed" },
-    { check: "Badge renders correctly on tab", platform: "All", expectedResult: "Badge positioned top-right of label, count visible" },
-  ],
-
-  dos: [
-    "Use semantic tablist/tab/tabpanel roles for all tab implementations",
-    "Animate the indicator bar for clear visual feedback during tab changes",
-    "Provide a scroll mechanism when tabs overflow the container",
-    "Keep tab labels short and descriptive — one or two words",
-    "Set aria-orientation='vertical' on vertical tablists",
-    "Load tab panel content eagerly if SEO matters; lazy-load for performance",
-    "Use the contained variant when tabs sit above a card-like content area",
-  ],
-
-  donts: [
-    "Don't use tabs for sequential steps — use a stepper/wizard pattern instead",
-    "Don't nest tabs within tabs — it creates confusing navigation hierarchy",
-    "Don't change the page URL when switching tabs unless tabs represent distinct routes",
-    "Don't mix tab variants (line and contained) in the same interface",
-    "Don't auto-rotate through tabs like a carousel — tabs are user-driven",
-    "Don't hide critical content in later tabs — users may never discover it",
-    "Don't make the tab panel height change dramatically between tabs without transition",
-  ],
-};

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

@@ -1,243 +0,0 @@
-/**
- * tag.ts — Gold-standard design knowledge for Tag components
- */
-import type { ComponentKnowledge } from "../types.js";
-
-export const tagKnowledge: ComponentKnowledge = {
-  description:
-    "Categorization label | Conveys metadata or status | Distinct from Chip (selection/input)",
-
-  stateSpecifications: [
-    {
-      state: "Default",
-      visualChange: "Solid or tinted background fill with label text in contrasting color; subtle border",
-      opacity: "1",
-      cursorWeb: "default",
-      usage: "Resting state — tag is visible and communicates its category or status",
-    },
-    {
-      state: "Hover",
-      visualChange: "Background darkens slightly; if removable, the dismiss icon gains emphasis",
-      opacity: "1",
-      cursorWeb: "default",
-      usage: "Mouse cursor enters the tag's area (interactive only if removable or clickable)",
-    },
-    {
-      state: "Active",
-      visualChange: "Background shifts an additional step darker; slight scale-down (0.98) on press",
-      opacity: "1",
-      cursorWeb: "pointer",
-      usage: "Tag is being pressed — applies only to removable or interactive tag variants",
-    },
-    {
-      state: "Focus",
-      visualChange: "2px focus ring offset by 2px from the tag edge, using $focus-ring token",
-      opacity: "1",
-      cursorWeb: "default",
-      usage: "Tag or its dismiss button receives keyboard focus via Tab key",
-    },
-    {
-      state: "Disabled",
-      visualChange: "Background and text switch to muted/disabled tokens; dismiss icon hidden",
-      opacity: "0.4",
-      cursorWeb: "not-allowed",
-      usage: "Tag is present but non-interactive — removal or click actions are unavailable",
-    },
-  ],
-
-  propertyDescriptions: {
-    label: "Visible text rendered inside the tag; should be a concise noun or short phrase (e.g. 'Beta', 'High Priority')",
-    type: "Semantic color variant — Neutral, Info, Success, Warning, or Error — controls background and border treatment",
-    size: "Dimensional preset controlling height, padding, font-size, and icon-size (Small, Medium, Large)",
-    removable: "When true, a dismiss/close icon is appended to the tag allowing the user to remove it",
-    icon: "Optional icon slot rendered before the label text; expects an icon component instance or icon name string",
-    disabled: "When true the tag is non-interactive: muted visuals, pointer-events none, aria-disabled='true'",
-    onRemove: "Callback fired when the dismiss button is activated; receives the tag's identifier or label",
-    onClick: "Optional callback that makes the entire tag clickable — adds pointer cursor and hover states",
-    maxWidth: "Maximum width before the label text truncates with ellipsis; defaults to 200px",
-    outlined: "When true, the tag renders with a transparent background and visible border instead of a solid fill",
-  },
-
-  sizeSpecifications: [
-    {
-      size: "Small",
-      height: "20px",
-      paddingLR: "6px",
-      fontSize: "11px",
-      iconSize: "12px",
-      borderRadius: "4px",
-    },
-    {
-      size: "Medium",
-      height: "24px",
-      paddingLR: "8px",
-      fontSize: "12px",
-      iconSize: "14px",
-      borderRadius: "6px",
-    },
-    {
-      size: "Large",
-      height: "32px",
-      paddingLR: "12px",
-      fontSize: "14px",
-      iconSize: "16px",
-      borderRadius: "8px",
-    },
-  ],
-
-  designTokenBindings: [
-    {
-      property: "Neutral Background",
-      tokenName: "$tag-neutral-bg",
-      role: "Background fill for the neutral/default tag variant",
-      fallback: "#F2F4F7",
-    },
-    {
-      property: "Info Background",
-      tokenName: "$tag-info-bg",
-      role: "Background fill for the informational tag variant",
-      fallback: "#EFF8FF",
-    },
-    {
-      property: "Success Background",
-      tokenName: "$tag-success-bg",
-      role: "Background fill for the success/positive tag variant",
-      fallback: "#ECFDF3",
-    },
-    {
-      property: "Warning Background",
-      tokenName: "$tag-warning-bg",
-      role: "Background fill for the warning/caution tag variant",
-      fallback: "#FFFAEB",
-    },
-    {
-      property: "Error Background",
-      tokenName: "$tag-error-bg",
-      role: "Background fill for the error/destructive tag variant",
-      fallback: "#FEF3F2",
-    },
-    {
-      property: "Text Color",
-      tokenName: "$tag-text",
-      role: "Label and icon color — adjusts per semantic type for contrast",
-      fallback: "#344054",
-    },
-    {
-      property: "Border",
-      tokenName: "$tag-border",
-      role: "Subtle border color applied to all tag variants for definition",
-      fallback: "#D0D5DD",
-    },
-    {
-      property: "Focus Ring",
-      tokenName: "$focus-ring",
-      role: "Keyboard focus indicator ring for interactive tags and dismiss buttons",
-      fallback: "0 0 0 2px #FFFFFF, 0 0 0 4px #2E90FA",
-    },
-    {
-      property: "Font Family",
-      tokenName: "$font-family-sans",
-      role: "Tag label typeface",
-      fallback: "Inter, system-ui, sans-serif",
-    },
-  ],
-
-  structureRules: [
-    "Container uses horizontal Auto Layout with center alignment on both axes",
-    "Icon, label, and dismiss button are direct children of the container — no intermediate wrappers",
-    "Spacing between icon and label uses the $spacing-xxs token (2px default)",
-    "Dismiss button is a separate focusable element within the tag, not a decoration on the label",
-    "Tag groups wrap using flex-wrap with $spacing-xs (4px) gap between tags",
-    "Minimum width ensures the tag never collapses below the icon + dismiss button width",
-    "Outlined variant uses a 1px border with transparent background; border color matches the semantic type",
-  ],
-
-  typeHierarchyRules: [
-    "Font weight is Medium (500) — provides readable emphasis at small sizes",
-    "Text uses sentence case for labels ('High priority', not 'HIGH PRIORITY' or 'High Priority')",
-    "No underline on label text — tags are not links",
-    "Single-line only; truncate with ellipsis if text exceeds maxWidth",
-    "Dismiss icon uses the same color token as the label text for visual consistency",
-  ],
-
-  interactionRules: [
-    { event: "Click Dismiss", trigger: "pointerup on dismiss button", action: "Fire onRemove callback; remove tag from DOM or notify parent" },
-    { event: "Hover Tag", trigger: "pointerenter on tag container", action: "Transition to hover background if tag is interactive (removable or clickable)" },
-    { event: "Hover Dismiss", trigger: "pointerenter on dismiss icon", action: "Dismiss icon gains emphasis (darker fill or background circle)" },
-    { event: "Focus Dismiss", trigger: "Tab key reaches dismiss button", action: "Show focus ring on the dismiss button specifically" },
-    { event: "Keydown Enter/Space", trigger: "Enter or Space on dismiss button", action: "Fire onRemove callback (same as click dismiss)" },
-    { event: "Keydown Backspace", trigger: "Backspace while tag is focused", action: "If removable, fire onRemove — common keyboard shortcut for tag removal" },
-    { event: "Click Tag", trigger: "pointerup on tag body (when onClick is set)", action: "Fire onClick handler; typically used for filtering or detail expansion" },
-    { event: "Focus Tag", trigger: "Tab key or focus()", action: "Show focus ring around entire tag if tag-level interaction is enabled" },
-  ],
-
-  contentGuidance: [
-    "Labels should be concise nouns or short phrases — one to three words maximum",
-    "Use semantic types consistently: Info for informational, Success for positive, Warning for caution, Error for critical",
-    "Do not use tags as action buttons — they represent metadata, not actions",
-    "Icons should reinforce the semantic meaning (e.g. checkmark for success, warning triangle for warning)",
-    "Avoid duplicate tags in the same context — each tag should convey unique information",
-    "When removable, ensure users understand what removing the tag will do (filter change, category removal, etc.)",
-  ],
-
-  responsiveBehaviour: [
-    { breakpoint: "Mobile (<768px)", behavior: "Tag groups wrap naturally; tags maintain minimum size; dismiss targets remain 44x44px touch area" },
-    { breakpoint: "Tablet (768-1023px)", behavior: "Tags render inline; groups may scroll horizontally if space is constrained" },
-    { breakpoint: "Desktop (1024-1439px)", behavior: "Full tag groups visible; wrapping follows natural content flow with consistent gap tokens" },
-    { breakpoint: "Ultra-wide (>=1440px)", behavior: "Tag sizes and spacing remain fixed — do not scale proportionally with viewport width" },
-  ],
-
-  accessibilitySpec: {
-    intro:
-      "Tags communicate categorical or status information. Semantic tags must be perceivable by assistive technology, and removable tags must be fully keyboard-operable.",
-    requirements: [
-      { requirement: "Semantic Role", level: "A", notes: "Use role='status' for semantic tags that convey live status; static labels need no special role" },
-      { requirement: "Accessible Name", level: "A", notes: "Each tag must expose its label text as its accessible name; icon-only tags need aria-label" },
-      { requirement: "Dismiss Button", level: "A", notes: "Removable tags must have a focusable dismiss button with aria-label='Remove [tag label]'" },
-      { requirement: "Removal Announcement", level: "AA", notes: "When a tag is removed, announce the removal via aria-live='polite' region" },
-      { requirement: "Contrast Ratio", level: "AA", notes: "Text-to-background: 4.5:1 minimum for all semantic type variants" },
-      { requirement: "Keyboard Operable", level: "A", notes: "Dismiss button reachable via Tab; activated by Enter, Space, or Backspace" },
-      { requirement: "Color Not Sole Indicator", level: "A", notes: "Semantic type must not rely on color alone — include icon or text to differentiate types" },
-    ],
-    outro: [
-      "When tags are dynamically added or removed, manage focus to the nearest remaining tag or a logical fallback",
-      "Ensure tag groups have a descriptive label (e.g. aria-label='Applied filters') for screen reader context",
-    ],
-  },
-
-  qaAcceptanceCriteria: [
-    { check: "Visual Regression", platform: "All", expectedResult: "Tag renders pixel-perfect against baseline for each type, size, and removable variant" },
-    { check: "Semantic Colors", platform: "All", expectedResult: "All five semantic types (Neutral, Info, Success, Warning, Error) display correct background and text tokens" },
-    { check: "Hover State", platform: "Web", expectedResult: "Interactive tags transition smoothly on mouse enter/leave; static tags show no hover change" },
-    { check: "Focus State", platform: "Web", expectedResult: "Focus ring visible on Tab for dismiss button; visible on tag body if clickable" },
-    { check: "Dismiss Functionality", platform: "All", expectedResult: "Clicking dismiss removes tag; onRemove callback fires with correct identifier" },
-    { check: "Keyboard Dismiss", platform: "Web", expectedResult: "Enter, Space, and Backspace on dismiss button fire onRemove; no double-fire" },
-    { check: "Screen Reader", platform: "Web", expectedResult: "Announces tag label, semantic type if role='status', and 'Remove' button for removable tags" },
-    { check: "Truncation", platform: "All", expectedResult: "Long labels truncate with ellipsis at maxWidth; full text available via tooltip on hover" },
-    { check: "Disabled State", platform: "All", expectedResult: "Muted visuals; dismiss hidden; pointer-events none; aria-disabled='true'" },
-    { check: "Contrast", platform: "All", expectedResult: "All semantic variants pass 4.5:1 text contrast in both light and dark themes" },
-    { check: "RTL Support", platform: "Web", expectedResult: "Icon and dismiss positions swap; padding mirrors; text alignment correct in RTL locales" },
-    { check: "Touch Target", platform: "Mobile", expectedResult: "Dismiss button hit area is at least 44x44px even for Small size tags" },
-  ],
-
-  dos: [
-    "Use semantic type variants consistently across the application to convey meaning",
-    "Keep labels short and descriptive — prefer single words or two-word phrases",
-    "Provide a clear dismiss affordance for removable tags (visible icon, not just hover-revealed)",
-    "Group related tags together with consistent sizing and spacing",
-    "Use the outlined variant for lower-emphasis or secondary tag groups",
-    "Announce tag removal to screen readers via an aria-live region",
-    "Ensure all semantic type colors meet contrast requirements in both light and dark themes",
-  ],
-
-  donts: [
-    "Do not use tags as action buttons — use a Button or Chip component instead",
-    "Do not use color as the only differentiator between semantic types — pair with icons or labels",
-    "Do not allow tag labels to wrap to multiple lines — truncate with ellipsis instead",
-    "Do not nest interactive elements (links, buttons) inside a tag besides the dismiss button",
-    "Do not use more than one semantic type on the same tag — each tag has a single type",
-    "Do not override design token colors with hard-coded hex values",
-    "Do not hide the dismiss button behind a hover reveal — it must be always visible for discoverability",
-    "Do not use tags for user-generated content input — use Chip or Input with tokenization instead",
-  ],
-};

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

@@ -1,259 +0,0 @@
-/**
- * textarea.ts — Gold-standard design knowledge for Textarea components
- */
-import type { ComponentKnowledge } from "../types.js";
-
-export const textareaKnowledge: ComponentKnowledge = {
-  description:
-    "Multi-line text input | Collects free-form content | Supports resizing, character limits, and validation",
-
-  stateSpecifications: [
-    {
-      state: "Default",
-      visualChange: "Field shows border, optional placeholder text in muted color",
-      opacity: "1",
-      cursorWeb: "text",
-      usage: "Resting state — textarea is interactive and ready for input",
-    },
-    {
-      state: "Focused",
-      visualChange: "Border transitions to focus color; 2px focus ring appears offset by 2px from the field edge",
-      opacity: "1",
-      cursorWeb: "text",
-      usage: "User clicks into the field or navigates via Tab key",
-    },
-    {
-      state: "Filled",
-      visualChange: "User-entered text replaces placeholder; border remains default color",
-      opacity: "1",
-      cursorWeb: "text",
-      usage: "Field contains user-entered content and is not currently focused",
-    },
-    {
-      state: "Error",
-      visualChange: "Border switches to error token; error message appears below the field in error color",
-      opacity: "1",
-      cursorWeb: "text",
-      usage: "Validation has failed — field value does not meet requirements",
-    },
-    {
-      state: "Disabled",
-      visualChange: "Background and border switch to disabled tokens; text is muted; no interaction possible",
-      opacity: "0.4",
-      cursorWeb: "not-allowed",
-      usage: "Field is unavailable due to form state, permissions, or prerequisites",
-    },
-    {
-      state: "ReadOnly",
-      visualChange: "Border is removed or reduced to a subtle bottom line; background becomes transparent or tinted",
-      opacity: "1",
-      cursorWeb: "default",
-      usage: "Content is visible and selectable but not editable — used for review or confirmation views",
-    },
-  ],
-
-  propertyDescriptions: {
-    label: "Visible text label rendered above the textarea; describes the expected input (e.g. 'Description', 'Comments')",
-    placeholder: "Hint text displayed inside the field when empty; disappears on input; should not replace the label",
-    value: "The current text content of the textarea; controlled or uncontrolled depending on framework usage",
-    helperText: "Optional instructional text below the field providing guidance on expected input format or constraints",
-    errorMessage: "Validation error message displayed below the field when the field is in an error state; replaces helperText when visible",
-    rows: "Number of visible text rows determining the initial height of the textarea; defaults to 3 for medium size",
-    maxLength: "Maximum number of characters allowed; when set, a character counter is rendered showing current/max count",
-    resize: "CSS resize behavior — 'vertical' (default), 'horizontal', 'both', or 'none'; controls user-resizable handle",
-    required: "When true, the field must have a value before form submission; adds a required indicator to the label",
-    disabled: "When true, the textarea is non-interactive: muted visuals, pointer-events none, aria-disabled='true'",
-    readOnly: "When true, the content is visible and selectable but cannot be modified; uses readOnly visual treatment",
-  },
-
-  sizeSpecifications: [
-    {
-      size: "Small",
-      height: "80px (min-height)",
-      paddingLR: "12px",
-      fontSize: "12px",
-      iconSize: "16px",
-      borderRadius: "6px",
-    },
-    {
-      size: "Medium",
-      height: "120px (min-height)",
-      paddingLR: "12px",
-      fontSize: "14px",
-      iconSize: "20px",
-      borderRadius: "8px",
-    },
-    {
-      size: "Large",
-      height: "160px (min-height)",
-      paddingLR: "12px",
-      fontSize: "16px",
-      iconSize: "24px",
-      borderRadius: "10px",
-    },
-  ],
-
-  designTokenBindings: [
-    {
-      property: "Background",
-      tokenName: "$field-bg",
-      role: "Default field background color",
-      fallback: "#FFFFFF",
-    },
-    {
-      property: "Border",
-      tokenName: "$field-border",
-      role: "Default field border color",
-      fallback: "#D0D5DD",
-    },
-    {
-      property: "Text Color",
-      tokenName: "$field-text",
-      role: "User-entered text color inside the field",
-      fallback: "#1D2939",
-    },
-    {
-      property: "Placeholder",
-      tokenName: "$field-placeholder",
-      role: "Placeholder hint text color",
-      fallback: "#98A2B3",
-    },
-    {
-      property: "Error Text",
-      tokenName: "$field-error-text",
-      role: "Error message text color below the field",
-      fallback: "#D92D20",
-    },
-    {
-      property: "Error Border",
-      tokenName: "$field-error-border",
-      role: "Border color when field is in error state",
-      fallback: "#FDA29B",
-    },
-    {
-      property: "Focus Ring",
-      tokenName: "$focus-ring",
-      role: "Keyboard and click focus indicator ring",
-      fallback: "0 0 0 2px #FFFFFF, 0 0 0 4px #2E90FA",
-    },
-    {
-      property: "Counter Text",
-      tokenName: "$field-helper-text",
-      role: "Character counter and helper text color",
-      fallback: "#667085",
-    },
-    {
-      property: "Label Color",
-      tokenName: "$field-label",
-      role: "Label text color above the field",
-      fallback: "#344054",
-    },
-    {
-      property: "Font Family",
-      tokenName: "$font-family-sans",
-      role: "Textarea content and label typeface",
-      fallback: "Inter, system-ui, sans-serif",
-    },
-  ],
-
-  structureRules: [
-    "Container uses vertical Auto Layout: label on top, field in the middle, helper/error text at the bottom",
-    "Label is a direct child of the container, positioned above the field with $spacing-xs (4px) gap",
-    "Field element uses vertical Auto Layout with top-left text alignment and padding on all four sides",
-    "Helper text and error message occupy the same slot — error message replaces helper text when visible",
-    "Character counter is right-aligned within the helper text row; format is 'current / max'",
-    "Resize handle is visible in the bottom-right corner unless resize is set to 'none'",
-    "Textarea width defaults to fill-container on the horizontal axis; never uses fixed width in standard usage",
-    "Minimum height is enforced per size spec; field grows vertically as content exceeds visible rows",
-  ],
-
-  typeHierarchyRules: [
-    "Label uses font weight Medium (500) at one step smaller than the field font size",
-    "Field text uses Regular (400) weight for comfortable long-form reading",
-    "Helper and error text use font size 12px regardless of field size",
-    "Placeholder text uses the same font size and weight as field text but in the placeholder color token",
-    "Character counter uses tabular-nums font feature for stable width as numbers change",
-  ],
-
-  interactionRules: [
-    { event: "Click", trigger: "pointerdown inside field bounds", action: "Place cursor at click position; enter focused state" },
-    { event: "Focus", trigger: "Tab key or focus()", action: "Show focus ring; place cursor at end of content" },
-    { event: "Blur", trigger: "Focus moves away", action: "Remove focus ring; run validation if configured" },
-    { event: "Input", trigger: "Keypress while focused", action: "Update value; increment character counter; fire onChange handler" },
-    { event: "Paste", trigger: "Ctrl/Cmd+V while focused", action: "Insert clipboard text; truncate to maxLength if exceeded" },
-    { event: "Max Length Reached", trigger: "Character count equals maxLength", action: "Prevent further input; counter text transitions to warning color" },
-    { event: "Resize", trigger: "User drags resize handle", action: "Adjust field dimensions within min/max constraints" },
-  ],
-
-  contentGuidance: [
-    "Labels should clearly describe the expected content: 'Description', 'Additional notes', 'Feedback'",
-    "Placeholder text should provide an example or hint, not repeat the label verbatim",
-    "Helper text should explain constraints: 'Maximum 500 characters' or 'Markdown is supported'",
-    "Error messages should be specific and actionable: 'Description is required' instead of 'Invalid input'",
-    "Keep placeholder text concise — one short sentence or phrase maximum",
-    "Use sentence case for labels, placeholders, and helper text — never all-caps",
-  ],
-
-  responsiveBehaviour: [
-    { breakpoint: "Mobile (<768px)", behavior: "Textarea expands to full width; minimum height increases to 120px for comfortable touch input" },
-    { breakpoint: "Tablet (768-1023px)", behavior: "Textarea fills available column width; resize handle remains active" },
-    { breakpoint: "Desktop (1024-1439px)", behavior: "Standard sizing applies; textarea respects container width constraints" },
-    { breakpoint: "Ultra-wide (>=1440px)", behavior: "Max-width cap of 720px prevents overly wide fields that reduce readability" },
-  ],
-
-  accessibilitySpec: {
-    intro:
-      "Textareas must be fully accessible for screen reader users, keyboard-only users, and voice control users. Proper labeling and live regions are critical for character counters.",
-    requirements: [
-      { requirement: "Role", level: "A", notes: "Use native <textarea> element which provides implicit role='textbox' with aria-multiline='true'" },
-      { requirement: "Label Association", level: "A", notes: "Label must be programmatically associated via for/id pairing or aria-labelledby" },
-      { requirement: "Describedby", level: "A", notes: "Helper text and error messages must be linked via aria-describedby for screen reader announcement" },
-      { requirement: "Required State", level: "A", notes: "Required fields must use aria-required='true' and display a visual required indicator" },
-      { requirement: "Error Identification", level: "A", notes: "Error state must set aria-invalid='true' and reference the error message via aria-errormessage or aria-describedby" },
-      { requirement: "Character Counter", level: "AA", notes: "Counter updates must use aria-live='polite' to announce remaining characters without interrupting the user" },
-      { requirement: "Contrast Ratio", level: "AA", notes: "Text-to-background: 4.5:1 minimum; field border to surrounding surface: 3:1" },
-      { requirement: "Resize Accessible", level: "AA", notes: "Resize functionality must not break reflow; content must remain visible after resizing" },
-    ],
-    outro: [
-      "Ensure focus is clearly visible with a high-contrast focus ring that meets WCAG 2.4.7",
-      "Do not rely solely on color to convey error state — include an error icon or text indicator",
-      "Screen readers should announce the label, current value, helper text, and error state in a logical order",
-    ],
-  },
-
-  qaAcceptanceCriteria: [
-    { check: "Visual Regression", platform: "All", expectedResult: "Textarea renders pixel-perfect against baseline for each size and state" },
-    { check: "Focus State", platform: "Web", expectedResult: "Focus ring visible on Tab; hidden on mouse click (focus-visible); cursor blinks inside field" },
-    { check: "Placeholder Display", platform: "Web", expectedResult: "Placeholder visible when empty; hidden as soon as first character is typed" },
-    { check: "Error State", platform: "All", expectedResult: "Error border, error message visible; helper text replaced; aria-invalid='true'" },
-    { check: "Character Counter", platform: "Web", expectedResult: "Counter updates on each keystroke; prevents input beyond maxLength; announces via aria-live" },
-    { check: "Disabled State", platform: "All", expectedResult: "Muted visuals; pointer-events none; aria-disabled='true'; not focusable via Tab" },
-    { check: "ReadOnly State", platform: "All", expectedResult: "Content is selectable but not editable; no border or reduced border; aria-readonly='true'" },
-    { check: "Resize Handle", platform: "Web", expectedResult: "Handle visible in bottom-right; dragging resizes field within min/max bounds" },
-    { check: "Screen Reader", platform: "Web", expectedResult: "Announces role 'textbox', accessible name from label, helper text, and error state" },
-    { check: "Keyboard Navigation", platform: "Web", expectedResult: "Tab moves focus in/out; all text editing keys work; no focus traps" },
-    { check: "Paste Handling", platform: "Web", expectedResult: "Pasted text is truncated to maxLength; counter updates; no overflow" },
-    { check: "Contrast", platform: "All", expectedResult: "All text passes 4.5:1 contrast; border passes 3:1 non-text contrast" },
-    { check: "RTL Support", platform: "Web", expectedResult: "Text aligns right; resize handle moves to bottom-left; label alignment mirrors" },
-  ],
-
-  dos: [
-    "Always pair the textarea with a visible label — never rely on placeholder alone",
-    "Provide a character counter when maxLength is set so users know their remaining allowance",
-    "Use helper text to communicate formatting expectations or constraints",
-    "Set an appropriate initial height via rows to match the expected content length",
-    "Use the error state with a specific, actionable error message for validation failures",
-    "Allow vertical resizing by default so users can expand the field for longer content",
-    "Maintain consistent padding tokens across all textarea sizes",
-  ],
-
-  donts: [
-    "Do not use a textarea for single-line inputs — use a text input instead",
-    "Do not hide the label and rely solely on placeholder text for field identification",
-    "Do not allow horizontal resizing that breaks page layout — prefer vertical-only resize",
-    "Do not use vague error messages like 'Invalid' — be specific about what needs to change",
-    "Do not set maxLength without showing a character counter — users need visibility into limits",
-    "Do not override design token colors with hard-coded hex values",
-    "Do not disable the field without explaining why via a tooltip or adjacent helper text",
-  ],
-};