@sarjallab09/figma-intelligence 1.1.0 → 1.2.0

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

@@ -1,290 +0,0 @@
-/**
- * file-uploader.ts — Gold-standard design knowledge for File Uploader components
- */
-import type { ComponentKnowledge } from "../types.js";
-
-export const fileUploaderKnowledge: ComponentKnowledge = {
-  description:
-    "File upload control | Drag-and-drop or button-triggered | Supports single and multi-file selection with progress feedback",
-
-  stateSpecifications: [
-    {
-      state: "Idle",
-      visualChange: "Dashed border container with upload icon, instructional text, and optional browse button",
-      opacity: "1",
-      cursorWeb: "pointer",
-      usage: "Default resting state — no files selected; ready to accept input via click or drag",
-    },
-    {
-      state: "DragOver",
-      visualChange: "Border becomes solid and primary-colored; background shifts to a light tint; icon may animate upward",
-      opacity: "1",
-      cursorWeb: "copy",
-      usage: "User is dragging files over the drop zone — visual feedback confirms the area will accept the drop",
-    },
-    {
-      state: "Uploading",
-      visualChange: "Progress bar appears below or beside each file entry; file name and size are shown; cancel action is available",
-      opacity: "1",
-      cursorWeb: "default",
-      usage: "Files are being transferred — progress percentage and/or indeterminate bar are displayed",
-    },
-    {
-      state: "Complete",
-      visualChange: "File entry shows a success checkmark icon; progress bar reaches 100% then fades; remove action is available",
-      opacity: "1",
-      cursorWeb: "default",
-      usage: "File upload finished successfully — file is listed with its name, size, and type icon",
-    },
-    {
-      state: "Error",
-      visualChange: "File entry shows error icon and red text describing the failure; retry and remove actions are available",
-      opacity: "1",
-      cursorWeb: "default",
-      usage: "Upload failed due to network error, file type rejection, or size limit exceeded",
-    },
-    {
-      state: "Disabled",
-      visualChange: "Drop zone border and text are muted; drag-and-drop and click are non-functional",
-      opacity: "0.4",
-      cursorWeb: "not-allowed",
-      usage: "File uploading is temporarily unavailable — prerequisites not met or quota reached",
-    },
-    {
-      state: "Focus",
-      visualChange: "2px focus ring around the drop zone or browse button; keyboard activation ready",
-      opacity: "1",
-      cursorWeb: "pointer",
-      usage: "Drop zone or browse button receives keyboard focus via Tab navigation",
-    },
-  ],
-
-  propertyDescriptions: {
-    accept: "Comma-separated MIME types or file extensions that the uploader will accept (e.g. '.pdf,.png,image/*')",
-    maxSize: "Maximum file size in bytes — files exceeding this limit are rejected with an error message",
-    multiple: "When true, allows selecting and uploading multiple files at once; when false, only one file at a time",
-    type: "Upload trigger style — 'dropzone' shows a large drag-and-drop area; 'button' shows a compact upload button",
-    onUpload: "Callback invoked when files are selected or dropped, receiving the FileList or File array",
-    progress: "Upload progress percentage (0-100) for the current file or files; used to control the progress bar",
-    maxFiles: "Maximum number of files allowed in a multi-file upload session; prevents exceeding quota",
-    onRemove: "Callback invoked when a user removes a file from the upload list, receiving the file identifier",
-    disabled: "When true, the uploader is non-interactive — cannot accept clicks, drops, or keyboard activation",
-    label: "Accessible label for the upload control; used as aria-label on the trigger element",
-  },
-
-  sizeSpecifications: [
-    {
-      size: "Small (Button)",
-      height: "32px",
-      paddingLR: "12px",
-      fontSize: "12px",
-      iconSize: "16px",
-      borderRadius: "6px",
-    },
-    {
-      size: "Medium (Button)",
-      height: "40px",
-      paddingLR: "16px",
-      fontSize: "14px",
-      iconSize: "20px",
-      borderRadius: "8px",
-    },
-    {
-      size: "Dropzone",
-      height: "160px (min)",
-      paddingLR: "24px",
-      fontSize: "14px",
-      iconSize: "40px",
-      borderRadius: "8px",
-    },
-    {
-      size: "Dropzone Compact",
-      height: "96px (min)",
-      paddingLR: "16px",
-      fontSize: "12px",
-      iconSize: "24px",
-      borderRadius: "8px",
-    },
-  ],
-
-  designTokenBindings: [
-    {
-      property: "Dropzone Background",
-      tokenName: "$file-uploader-bg",
-      role: "Background fill of the drop zone area in idle state",
-      fallback: "#F9FAFB",
-    },
-    {
-      property: "Dropzone Border",
-      tokenName: "$file-uploader-border",
-      role: "Dashed border around the drop zone in idle state",
-      fallback: "#D0D5DD",
-    },
-    {
-      property: "DragOver Background",
-      tokenName: "$file-uploader-dragover-bg",
-      role: "Background tint when files are dragged over the drop zone",
-      fallback: "#EFF8FF",
-    },
-    {
-      property: "DragOver Border",
-      tokenName: "$file-uploader-dragover-border",
-      role: "Solid primary border during drag-over",
-      fallback: "#2563EB",
-    },
-    {
-      property: "Icon Color",
-      tokenName: "$file-uploader-icon",
-      role: "Upload icon color in the drop zone",
-      fallback: "#667085",
-    },
-    {
-      property: "Text Primary",
-      tokenName: "$file-uploader-text",
-      role: "Primary instructional text color (e.g. 'Drag files here')",
-      fallback: "#344054",
-    },
-    {
-      property: "Text Secondary",
-      tokenName: "$file-uploader-text-secondary",
-      role: "Secondary hint text color (e.g. 'or click to browse')",
-      fallback: "#667085",
-    },
-    {
-      property: "Progress Bar Fill",
-      tokenName: "$file-uploader-progress",
-      role: "Filled portion of the upload progress bar",
-      fallback: "#2563EB",
-    },
-    {
-      property: "Progress Bar Track",
-      tokenName: "$file-uploader-progress-track",
-      role: "Empty portion/background of the progress bar",
-      fallback: "#E4E7EC",
-    },
-    {
-      property: "Error Color",
-      tokenName: "$file-uploader-error",
-      role: "Error text and icon color for failed uploads",
-      fallback: "#F04438",
-    },
-    {
-      property: "Success Color",
-      tokenName: "$file-uploader-success",
-      role: "Success checkmark icon color for completed uploads",
-      fallback: "#12B76A",
-    },
-    {
-      property: "Focus Ring",
-      tokenName: "$focus-ring",
-      role: "Keyboard focus indicator on the drop zone or browse button",
-      fallback: "0 0 0 2px #FFFFFF, 0 0 0 4px #2E90FA",
-    },
-  ],
-
-  structureRules: [
-    "Dropzone variant uses a centered vertical Auto Layout: icon → primary text → secondary text → optional browse button",
-    "Button variant renders as a standard button with an upload icon; file list appears below the button",
-    "File list entries are rendered below the drop zone in a vertical stack with consistent spacing",
-    "Each file entry contains: file type icon, file name, file size, progress bar (during upload), and action button (remove/cancel/retry)",
-    "Drop zone has a dashed border (border-style: dashed) with 2px width using the border token",
-    "The entire drop zone area is a click target that opens the native file picker",
-    "A hidden <input type='file'> element handles the actual file selection via the browser's native picker",
-    "Progress bars within file entries are 4px tall with rounded ends inside the file list item",
-    "File type icons are determined by MIME type: image files show a thumbnail preview; documents show a file icon",
-  ],
-
-  typeHierarchyRules: [
-    "Primary instructional text uses Medium weight (500) at 14px: 'Drag and drop files here'",
-    "Secondary hint text uses Regular weight (400) at 12px: 'or click to browse'",
-    "File name in the file list uses Medium weight (500) at 14px — single line, truncate with ellipsis",
-    "File size uses Regular weight (400) at 12px in a muted color beside or below the file name",
-    "Error messages use Regular weight (400) at 12px in the error token color",
-  ],
-
-  interactionRules: [
-    { event: "Click (Dropzone)", trigger: "Click/tap anywhere on the drop zone", action: "Open the native file picker dialog with the configured accept and multiple settings" },
-    { event: "Click (Browse)", trigger: "Click/tap on the 'Browse' button within the drop zone", action: "Open the native file picker dialog (same as clicking the drop zone)" },
-    { event: "Drag Enter", trigger: "File(s) dragged over the drop zone boundary", action: "Transition to DragOver state; show visual feedback (solid border, tinted background)" },
-    { event: "Drag Leave", trigger: "File(s) dragged outside the drop zone boundary", action: "Return to Idle state; remove DragOver visual treatment" },
-    { event: "Drop", trigger: "File(s) released over the drop zone", action: "Validate files against accept/maxSize/maxFiles; start upload via onUpload; add entries to file list" },
-    { event: "Remove File", trigger: "Click remove/X button on a file entry", action: "Remove the file from the list; fire onRemove; cancel upload if in progress" },
-    { event: "Retry Upload", trigger: "Click retry button on an error file entry", action: "Re-attempt the upload for the failed file; transition back to Uploading state" },
-    { event: "Cancel Upload", trigger: "Click cancel button during upload", action: "Abort the in-progress upload; remove the file entry or show cancelled state" },
-    { event: "Keyboard Activate", trigger: "Enter or Space while drop zone or browse button is focused", action: "Open the native file picker dialog" },
-  ],
-
-  contentGuidance: [
-    "Primary text should clearly state the action: 'Drag and drop your files here' or 'Upload a file'",
-    "Secondary text should indicate the alternative: 'or click to browse' or include format/size hints",
-    "Display accepted file types and size limits in the drop zone: 'PDF, PNG, JPG up to 10MB'",
-    "Show file size in human-readable format: '2.4 MB' not '2516582 bytes'",
-    "Error messages should be specific: 'File exceeds 10MB limit' not 'Upload failed'",
-    "Show a file count summary when multiple files are uploaded: '3 of 5 files uploaded'",
-    "Use thumbnails for image files to provide visual confirmation of the correct file selection",
-  ],
-
-  responsiveBehaviour: [
-    { breakpoint: "Mobile (<768px)", behavior: "Dropzone reduces to compact height; text simplifies to 'Tap to upload'; drag-and-drop still works for supported mobile browsers" },
-    { breakpoint: "Tablet (768-1023px)", behavior: "Standard dropzone layout; file list entries may use a condensed row format" },
-    { breakpoint: "Desktop (1024-1439px)", behavior: "Full dropzone with icon, primary/secondary text, and browse button; file list shows detailed entries" },
-    { breakpoint: "Ultra-wide (>=1440px)", behavior: "Dropzone width remains capped at container max-width; does not expand to fill ultra-wide viewports" },
-  ],
-
-  accessibilitySpec: {
-    intro:
-      "File uploaders combine drag-and-drop interaction with a traditional file picker. Keyboard and screen reader users must have equivalent access to all functionality, including file selection, progress monitoring, and file management.",
-    requirements: [
-      { requirement: "Trigger Role", level: "A", notes: "The drop zone / browse button must have role='button' with a clear accessible name like 'Upload file'" },
-      { requirement: "Keyboard Activation", level: "A", notes: "Enter and Space must open the native file picker dialog when the trigger is focused" },
-      { requirement: "File Input", level: "A", notes: "The hidden <input type='file'> must have a proper label via aria-label or associated <label> element" },
-      { requirement: "Progress Announcement", level: "A", notes: "Upload progress must be announced via role='progressbar' with aria-valuenow, aria-valuemin, and aria-valuemax" },
-      { requirement: "File List", level: "A", notes: "Uploaded files must be in a list (role='list') with accessible names including file name and status" },
-      { requirement: "Remove Action", level: "A", notes: "Remove buttons must have aria-label='Remove [filename]' for each file entry" },
-      { requirement: "Error Announcement", level: "A", notes: "Upload errors must be announced via aria-live='assertive' or role='alert' with descriptive error text" },
-      { requirement: "Contrast", level: "AA", notes: "Drop zone border, text, and icons must meet 4.5:1 text contrast and 3:1 non-text contrast against background" },
-      { requirement: "Drag-and-Drop Alternative", level: "A", notes: "Drag-and-drop must not be the only means of uploading — the browse button/click provides the keyboard-accessible alternative" },
-    ],
-    outro: [
-      "Test with screen readers to verify that file selection, upload progress, completion, and errors are all announced",
-      "Ensure that removing a file returns focus to the next file in the list, or to the upload trigger if the list is empty",
-      "Verify that drag-and-drop instructions are visible but not the only path — keyboard users rely on the click/button path",
-    ],
-  },
-
-  qaAcceptanceCriteria: [
-    { check: "Idle State", platform: "All", expectedResult: "Drop zone shows dashed border, upload icon, and instructional text" },
-    { check: "DragOver State", platform: "Web", expectedResult: "Solid primary border and tinted background appear when files are dragged over" },
-    { check: "File Selection", platform: "All", expectedResult: "Clicking drop zone or browse button opens the native file picker with correct accept filters" },
-    { check: "File Drop", platform: "Web", expectedResult: "Dropping valid files starts upload; invalid files show immediate error in file list" },
-    { check: "Upload Progress", platform: "All", expectedResult: "Progress bar fills from 0-100%; file name and size are visible" },
-    { check: "Upload Complete", platform: "All", expectedResult: "Success checkmark shown; progress bar reaches 100%; remove action available" },
-    { check: "Upload Error", platform: "All", expectedResult: "Error icon and message shown; retry and remove actions available" },
-    { check: "Remove File", platform: "All", expectedResult: "File is removed from list; onRemove callback fires; focus moves appropriately" },
-    { check: "Max Size Validation", platform: "All", expectedResult: "Files exceeding maxSize are rejected with descriptive error before upload begins" },
-    { check: "Max Files Validation", platform: "All", expectedResult: "Additional files beyond maxFiles limit are rejected with appropriate message" },
-    { check: "Keyboard Activation", platform: "Web", expectedResult: "Enter/Space opens file picker when drop zone is focused" },
-    { check: "Screen Reader", platform: "Web", expectedResult: "Announces trigger role, progress percentage, completion, and errors" },
-    { check: "Disabled State", platform: "All", expectedResult: "Drop zone is muted and non-interactive; no file picker opens on click or keyboard" },
-  ],
-
-  dos: [
-    "Always provide a clickable alternative to drag-and-drop for keyboard and assistive technology users",
-    "Display accepted file types and size limits clearly within the drop zone",
-    "Show upload progress with a percentage or progress bar for each file",
-    "Provide clear error messages when files are rejected (wrong type, too large, too many)",
-    "Allow users to remove uploaded files and cancel in-progress uploads",
-    "Use file type icons or thumbnail previews to help users confirm correct file selection",
-    "Maintain the drop zone visible even after files are selected to allow additional uploads",
-  ],
-
-  donts: [
-    "Do not rely solely on drag-and-drop — always include a browse button or click-to-upload",
-    "Do not auto-upload without user confirmation for sensitive or irreversible operations",
-    "Do not silently ignore invalid files — always show an error explaining why the file was rejected",
-    "Do not remove the file list when navigating away — preserve upload state if possible",
-    "Do not allow unlimited file uploads without a maxFiles or maxSize constraint",
-    "Do not use vague error messages like 'Upload failed' — specify the reason (size, type, network)",
-    "Do not make the drop zone smaller than 96px tall — it must be a clear, visible target",
-  ],
-};

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

@@ -1,265 +0,0 @@
-/**
- * form.ts — Gold-standard design knowledge for Form wrapper/container components
- */
-import type { ComponentKnowledge } from "../types.js";
-
-export const formKnowledge: ComponentKnowledge = {
-  description:
-    "Form wrapper and container | Groups and validates field collections | Manages layout, submission, and error presentation",
-
-  stateSpecifications: [
-    {
-      state: "Default",
-      visualChange: "Form container renders with configured layout; all child fields in their default state; submit button enabled",
-      opacity: "1",
-      cursorWeb: "default",
-      usage: "Resting state — form is ready for user input with all fields editable",
-    },
-    {
-      state: "Submitting",
-      visualChange: "Submit button enters loading state with spinner; all form fields become temporarily non-interactive; overlay may dim the form",
-      opacity: "1",
-      cursorWeb: "wait",
-      usage: "Form data is being sent to the server — prevents duplicate submissions and communicates progress",
-    },
-    {
-      state: "Success",
-      visualChange: "Success banner or inline message appears at the top or bottom of the form; fields may reset or become read-only",
-      opacity: "1",
-      cursorWeb: "default",
-      usage: "Server has confirmed successful data submission; form may reset or transition to a confirmation view",
-    },
-    {
-      state: "Error",
-      visualChange: "Form-level error banner appears at the top; individual fields with errors show their error states; focus moves to the first errored field",
-      opacity: "1",
-      cursorWeb: "default",
-      usage: "Validation has failed on one or more fields — either client-side on submit/blur/change, or server-side after submission",
-    },
-  ],
-
-  propertyDescriptions: {
-    layout: "Arrangement of form fields — 'vertical' stacks fields top-to-bottom, 'horizontal' arranges fields side-by-side in a row",
-    labelPosition: "Placement of field labels relative to their inputs — 'top' (above), 'left' (inline start), or 'right' (inline end)",
-    requiredIndicator: "Visual marker for required fields — typically an asterisk (*) appended to the label, configurable as text or icon",
-    spacing: "Gap between consecutive form fields — uses spacing tokens ($spacing-sm, $spacing-md, $spacing-lg) based on density preset",
-    onSubmit: "Callback fired when the form is submitted; receives all field values; should handle async submission and error responses",
-    onReset: "Callback fired when the form is reset; restores all fields to their initial values and clears validation errors",
-    validateOn: "Timing of field validation — 'submit' validates only on form submission, 'blur' on field blur, 'change' on every value change",
-  },
-
-  sizeSpecifications: [
-    {
-      size: "Compact",
-      height: "12px",
-      paddingLR: "12px",
-      fontSize: "12px",
-      iconSize: "16px",
-      borderRadius: "6px",
-    },
-    {
-      size: "Default",
-      height: "16px",
-      paddingLR: "16px",
-      fontSize: "14px",
-      iconSize: "20px",
-      borderRadius: "8px",
-    },
-    {
-      size: "Spacious",
-      height: "24px",
-      paddingLR: "24px",
-      fontSize: "16px",
-      iconSize: "24px",
-      borderRadius: "10px",
-    },
-  ],
-
-  designTokenBindings: [
-    {
-      property: "Form Background",
-      tokenName: "$form-bg",
-      role: "Background color for the form container; transparent by default to inherit page background",
-      fallback: "transparent",
-    },
-    {
-      property: "Label Text",
-      tokenName: "$form-label-text",
-      role: "Text color for all field labels within the form",
-      fallback: "#344054",
-    },
-    {
-      property: "Label Font Weight",
-      tokenName: "$form-label-weight",
-      role: "Font weight for field labels — Medium for visual hierarchy",
-      fallback: "500",
-    },
-    {
-      property: "Required Indicator",
-      tokenName: "$form-required-indicator",
-      role: "Color for the required field marker (asterisk or icon)",
-      fallback: "#F04438",
-    },
-    {
-      property: "Error Text",
-      tokenName: "$form-error-text",
-      role: "Text color for field-level and form-level error messages",
-      fallback: "#F04438",
-    },
-    {
-      property: "Error Banner Background",
-      tokenName: "$form-error-banner-bg",
-      role: "Background fill for the form-level error summary banner",
-      fallback: "#FEF3F2",
-    },
-    {
-      property: "Success Banner Background",
-      tokenName: "$form-success-banner-bg",
-      role: "Background fill for the form-level success confirmation banner",
-      fallback: "#ECFDF3",
-    },
-    {
-      property: "Helper Text",
-      tokenName: "$form-helper-text",
-      role: "Text color for supplementary guidance below individual fields",
-      fallback: "#667085",
-    },
-    {
-      property: "Section Divider",
-      tokenName: "$form-section-divider",
-      role: "Color for horizontal rules separating form sections or fieldsets",
-      fallback: "#EAECF0",
-    },
-    {
-      property: "Spacing Compact",
-      tokenName: "$spacing-sm",
-      role: "Gap between fields in compact density mode",
-      fallback: "12px",
-    },
-    {
-      property: "Spacing Default",
-      tokenName: "$spacing-md",
-      role: "Gap between fields in default density mode",
-      fallback: "16px",
-    },
-    {
-      property: "Spacing Spacious",
-      tokenName: "$spacing-lg",
-      role: "Gap between fields in spacious density mode",
-      fallback: "24px",
-    },
-  ],
-
-  structureRules: [
-    "Form wraps child components (Input, Select, Checkbox, Radio, Textarea, Button) in a vertical or horizontal Auto Layout",
-    "Each field group consists of: label, input component, helper/error text — stacked vertically with $spacing-xs gap",
-    "Fieldset/legend pattern groups related fields into sections with a visible heading and optional divider",
-    "Required indicator (asterisk) is positioned immediately after the label text with no additional spacing",
-    "Form-level error banner is always the first visible child when present, positioned above all form fields",
-    "Submit and reset buttons are grouped in a horizontal row at the bottom of the form with $spacing-md gap between them",
-    "Primary action (submit) is placed on the right in LTR layouts, on the left in RTL layouts",
-    "Horizontal layout arranges fields in columns using CSS Grid or flex-wrap; each column has equal or specified width",
-    "Form container width defaults to 100% of its parent; max-width may be set to constrain overly wide forms",
-    "Inline validation error messages appear directly below their associated field, not in a distant location",
-  ],
-
-  typeHierarchyRules: [
-    "Field labels use font-weight Medium (500) at the form's configured label font-size",
-    "Helper text uses font-weight Regular (400) at one step smaller than the label font-size",
-    "Error messages use font-weight Medium (500) at the same size as helper text for emphasis",
-    "Section headings (legend elements) use font-weight SemiBold (600) at one step larger than labels",
-    "All form text uses sentence case — never all-caps except for rare acronyms",
-    "Form-level error/success banner text uses font-weight Medium (500) at the label font-size",
-  ],
-
-  interactionRules: [
-    { event: "Submit", trigger: "Click submit button or press Enter in a single-line input", action: "Run all field validations; if valid, fire onSubmit and enter submitting state; if invalid, show errors and focus first errored field" },
-    { event: "Reset", trigger: "Click reset button", action: "Restore all fields to initial values; clear all validation errors; fire onReset callback" },
-    { event: "Field Blur", trigger: "Focus leaves a field (validateOn='blur')", action: "Validate the blurred field; show inline error if invalid; clear error if now valid" },
-    { event: "Field Change", trigger: "Value changes in a field (validateOn='change')", action: "Validate the changed field in real-time; show or clear inline error immediately" },
-    { event: "Tab Navigation", trigger: "Tab key cycles through form fields", action: "Move focus to the next focusable field in document order; skip disabled fields" },
-    { event: "Enter Key", trigger: "Enter key in a text input", action: "Submit the form if it is a single-field form or if the input is the last field before the submit button" },
-    { event: "Error Banner Click", trigger: "Click on an error in the form-level error summary", action: "Scroll to and focus the corresponding errored field" },
-    { event: "Submission Success", trigger: "Server responds with success", action: "Exit submitting state; show success banner; optionally reset form or transition to confirmation" },
-    { event: "Submission Failure", trigger: "Server responds with errors", action: "Exit submitting state; map server errors to fields; show form-level error banner; focus first errored field" },
-  ],
-
-  contentGuidance: [
-    "Field labels should be concise and descriptive: 'Email address', 'Password', 'Company name'",
-    "Use consistent label placement (top, left, or right) throughout the entire form — never mix positions",
-    "Mark required fields with an asterisk (*) and include a legend explaining the indicator at the top of the form",
-    "Error messages should describe the problem and how to fix it: 'Enter a valid email address' not 'Invalid input'",
-    "Group related fields into logical sections with clear headings: 'Personal Information', 'Shipping Address'",
-    "Place the primary submit button at the bottom-right (LTR) with a clear action label: 'Create account', 'Save changes'",
-    "If a reset button is needed, style it as a secondary or tertiary variant to avoid accidental use",
-    "Helper text should provide examples or format guidance: 'e.g. john@example.com' or 'At least 8 characters'",
-  ],
-
-  responsiveBehaviour: [
-    { breakpoint: "Mobile (<768px)", behavior: "All fields stack vertically at full width; labels positioned above fields (top); submit button spans full width at 48px height" },
-    { breakpoint: "Tablet (768-1023px)", behavior: "Two-column layout for related field pairs (first/last name); labels may be top or left depending on available width" },
-    { breakpoint: "Desktop (1024-1439px)", behavior: "Multi-column layout with left-aligned labels for dense forms; inline buttons with standard padding" },
-    { breakpoint: "Ultra-wide (>=1440px)", behavior: "Form max-width is capped (typically 720-960px) and centered to prevent overly wide layouts" },
-  ],
-
-  accessibilitySpec: {
-    intro:
-      "Forms are the primary data collection pattern on the web. Proper semantic markup, label association, and error handling are essential for all users including those using assistive technology.",
-    requirements: [
-      { requirement: "Form Element", level: "A", notes: "Use the native <form> element to enable implicit submission and provide landmarks for screen readers" },
-      { requirement: "Label Association", level: "A", notes: "Every input must have a visible <label> with a matching for/id pair, or use aria-labelledby" },
-      { requirement: "Required Fields", level: "A", notes: "Required fields must have aria-required='true' and a visible required indicator in the label" },
-      { requirement: "Error Identification", level: "A", notes: "Each errored field must have aria-invalid='true' and aria-describedby pointing to its error message" },
-      { requirement: "Error Suggestion", level: "AA", notes: "Error messages must describe the nature of the error and suggest how to correct it" },
-      { requirement: "Form-Level Errors", level: "A", notes: "Form-level error summary uses aria-describedby on the form element or role='alert' for immediate announcement" },
-      { requirement: "Fieldset/Legend", level: "A", notes: "Related field groups wrapped in <fieldset> with <legend> describing the group purpose" },
-      { requirement: "Focus Management", level: "A", notes: "On validation failure, focus moves to the first errored field or the error summary banner" },
-      { requirement: "Tab Order", level: "A", notes: "Fields follow a logical tab order matching the visual layout; no tab traps or skipped fields" },
-      { requirement: "Contrast Ratio", level: "AA", notes: "Label and error text: 4.5:1 against background; required indicator: 3:1 non-text contrast" },
-    ],
-    outro: [
-      "Ensure screen readers announce form-level success and error states via aria-live regions",
-      "Provide a clear path from the error summary to individual fields — each error item should be an anchor link",
-      "Do not rely solely on color to communicate errors — use icons, borders, and text in combination",
-    ],
-  },
-
-  qaAcceptanceCriteria: [
-    { check: "Visual Regression", platform: "All", expectedResult: "Form renders pixel-perfect against baseline for each layout mode and density preset" },
-    { check: "Label Alignment", platform: "All", expectedResult: "Labels align consistently per labelPosition prop (top, left, right) across all fields" },
-    { check: "Required Indicator", platform: "All", expectedResult: "Asterisk appears next to required field labels; legend explains the indicator" },
-    { check: "Submit Validation", platform: "Web", expectedResult: "Clicking submit with empty required fields shows inline errors and focuses the first errored field" },
-    { check: "Blur Validation", platform: "Web", expectedResult: "When validateOn='blur', leaving an invalid field shows its error message immediately" },
-    { check: "Change Validation", platform: "Web", expectedResult: "When validateOn='change', error clears in real-time as user corrects the value" },
-    { check: "Submitting State", platform: "Web", expectedResult: "Submit button shows spinner; fields become non-interactive; duplicate submissions prevented" },
-    { check: "Success State", platform: "Web", expectedResult: "Success banner appears; form resets or transitions as configured" },
-    { check: "Error Banner", platform: "Web", expectedResult: "Form-level error summary appears with links to each errored field; clicking a link focuses the field" },
-    { check: "Keyboard Navigation", platform: "Web", expectedResult: "Tab cycles through all fields in visual order; Enter submits from text inputs" },
-    { check: "Screen Reader", platform: "Web", expectedResult: "Announces form landmark, field labels, required state, error messages, and submission status" },
-    { check: "Fieldset Grouping", platform: "Web", expectedResult: "Related fields grouped in fieldset with legend; screen readers announce the group name" },
-    { check: "Reset Functionality", platform: "Web", expectedResult: "Reset button restores all fields to initial values and clears all errors" },
-    { check: "Responsive Layout", platform: "All", expectedResult: "Fields stack vertically on mobile, multi-column on desktop; labels reposition per breakpoint" },
-    { check: "Contrast", platform: "All", expectedResult: "Labels pass 4.5:1 contrast; error indicators pass 3:1 non-text contrast" },
-    { check: "RTL Support", platform: "Web", expectedResult: "Labels, fields, and buttons mirror correctly in RTL locales; submit button moves to left" },
-  ],
-
-  dos: [
-    "Use semantic <form>, <fieldset>, and <legend> elements for proper structure and screen reader support",
-    "Associate every input with a visible label — never rely on placeholder text alone as a label",
-    "Mark required fields consistently with both a visual indicator and aria-required='true'",
-    "Provide an error summary at the form level that links to individual errored fields",
-    "Focus the first errored field automatically when validation fails on submit",
-    "Use consistent spacing tokens between fields — never override with arbitrary pixel values",
-    "Place the primary action button at the form bottom with a descriptive verb label",
-  ],
-
-  donts: [
-    "Do not use placeholder text as a substitute for labels — it disappears on input and fails accessibility",
-    "Do not disable the submit button to indicate validation errors — show the errors and let users correct them",
-    "Do not mix label positions (top/left/right) within the same form",
-    "Do not rely solely on color to indicate errors — always pair with icons and descriptive text",
-    "Do not reset the form on submission failure — preserve user input so they can correct errors",
-    "Do not validate on every keystroke without debouncing — it creates excessive noise for screen readers",
-    "Do not use generic error messages like 'This field is required' — be specific about what is expected",
-  ],
-};