@sarjallab09/figma-intelligence 1.0.0

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

@@ -0,0 +1,243 @@
+/**
+ * button.ts — Gold-standard design knowledge for Button components
+ */
+import type { ComponentKnowledge } from "../types.js";
+
+export const buttonKnowledge: ComponentKnowledge = {
+  description:
+    "Core interface primitive | Triggers actions | Primary CTA element",
+
+  stateSpecifications: [
+    {
+      state: "Default",
+      visualChange: "Solid fill with label text in contrasting color",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Resting state — button is interactive and ready for activation",
+    },
+    {
+      state: "Hover",
+      visualChange: "Background darkens or lightens by one step on the color scale",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Mouse cursor enters the button's hit area",
+    },
+    {
+      state: "Active",
+      visualChange: "Background shifts an additional step; slight scale-down (0.98) gives tactile feedback",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Mouse button is held down or touch press is in progress",
+    },
+    {
+      state: "Disabled",
+      visualChange: "Background and text switch to muted/disabled tokens; no elevation",
+      opacity: "0.4",
+      cursorWeb: "not-allowed",
+      usage: "Action is unavailable due to missing prerequisites or permissions",
+    },
+    {
+      state: "Focus",
+      visualChange: "2px focus ring offset by 2px from the button edge, using $focus-ring token",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Button receives keyboard focus via Tab key or programmatic focus call",
+    },
+    {
+      state: "Loading",
+      visualChange: "Label text replaced or overlaid by a spinner; button dimensions remain fixed",
+      opacity: "1",
+      cursorWeb: "wait",
+      usage: "Asynchronous action is in progress — button is temporarily non-interactive",
+    },
+  ],
+
+  propertyDescriptions: {
+    label: "Visible text rendered inside the button; should be action-oriented (e.g. 'Save', 'Submit')",
+    type: "Visual hierarchy variant — Primary, Secondary, Tertiary, or Danger — controls fill and border treatment",
+    size: "Dimensional preset controlling height, padding, font-size, and icon-size (Small, Medium, Large)",
+    disabled: "When true the button is non-interactive: muted visuals, pointer-events none, aria-disabled='true'",
+    loading: "When true the label is replaced with a spinner and the button ignores clicks until loading completes",
+    iconLeft: "Optional icon slot rendered before the label; expects an icon component instance or icon name string",
+    iconRight: "Optional icon slot rendered after the label; typically used for directional cues (arrows, chevrons)",
+  },
+
+  sizeSpecifications: [
+    {
+      size: "Small",
+      height: "32px",
+      paddingLR: "12px",
+      fontSize: "12px",
+      iconSize: "16px",
+      borderRadius: "6px",
+    },
+    {
+      size: "Medium",
+      height: "40px",
+      paddingLR: "16px",
+      fontSize: "14px",
+      iconSize: "20px",
+      borderRadius: "8px",
+    },
+    {
+      size: "Large",
+      height: "48px",
+      paddingLR: "20px",
+      fontSize: "16px",
+      iconSize: "24px",
+      borderRadius: "10px",
+    },
+  ],
+
+  designTokenBindings: [
+    {
+      property: "Background",
+      tokenName: "$button-primary-bg",
+      role: "Primary variant fill color",
+      fallback: "#2563EB",
+    },
+    {
+      property: "Text Color",
+      tokenName: "$button-primary-text",
+      role: "Label and icon color on primary variant",
+      fallback: "#FFFFFF",
+    },
+    {
+      property: "Border",
+      tokenName: "$button-secondary-border",
+      role: "Visible border on secondary and tertiary variants",
+      fallback: "#D0D5DD",
+    },
+    {
+      property: "Radius",
+      tokenName: "$radius-button",
+      role: "Corner rounding applied to all four corners equally",
+      fallback: "8px",
+    },
+    {
+      property: "Font Family",
+      tokenName: "$font-family-sans",
+      role: "Button label typeface",
+      fallback: "Inter, system-ui, sans-serif",
+    },
+    {
+      property: "Font Weight",
+      tokenName: "$font-weight-medium",
+      role: "Label weight — medium for readability at small sizes",
+      fallback: "500",
+    },
+    {
+      property: "Line Height",
+      tokenName: "$line-height-tight",
+      role: "Tight line height to vertically center single-line label",
+      fallback: "1.2",
+    },
+    {
+      property: "Transition",
+      tokenName: "$transition-interactive",
+      role: "Smooth state transitions for background, border, and shadow",
+      fallback: "150ms ease-in-out",
+    },
+    {
+      property: "Focus Ring",
+      tokenName: "$focus-ring",
+      role: "Keyboard focus indicator ring",
+      fallback: "0 0 0 2px #FFFFFF, 0 0 0 4px #2E90FA",
+    },
+  ],
+
+  structureRules: [
+    "Container uses horizontal Auto Layout with center alignment on both axes",
+    "Icon and label are direct children of the container — no intermediate wrappers",
+    "Spacing between icon and label uses the $spacing-xs token (4px default)",
+    "Touch target is at least 44x44px regardless of visual size (add transparent padding if needed)",
+    "Full-width variant sets container to fill-container on the horizontal axis",
+    "Icon-only variant removes the label layer; container padding becomes equal on all sides",
+    "Loading spinner replaces the label but preserves the container's intrinsic width to prevent layout shift",
+  ],
+
+  typeHierarchyRules: [
+    "Font weight is Medium (500) — never Bold for standard buttons",
+    "Text uses sentence case ('Save changes', not 'Save Changes' or 'SAVE CHANGES')",
+    "No underline on label text — underline is reserved for inline links",
+    "Single-line only; truncate with ellipsis if text overflows the max-width",
+  ],
+
+  interactionRules: [
+    { event: "Click / Tap", trigger: "pointerup inside button bounds", action: "Fire onClick handler; optionally enter loading state" },
+    { event: "Hover", trigger: "pointerenter", action: "Transition to hover background token" },
+    { event: "Mouse Down", trigger: "pointerdown", action: "Transition to active/pressed visual state" },
+    { event: "Focus", trigger: "Tab key or focus()", action: "Show focus ring; do not trigger click" },
+    { event: "Blur", trigger: "Focus moves away", action: "Remove focus ring" },
+    { event: "Keydown Enter", trigger: "Enter key while focused", action: "Fire onClick handler (same as click)" },
+    { event: "Keydown Space", trigger: "Space key while focused", action: "Fire onClick handler on key-up (native button behavior)" },
+  ],
+
+  contentGuidance: [
+    "Labels should be action-oriented verbs or short verb phrases: 'Save', 'Add to cart', 'Continue'",
+    "Avoid vague labels like 'Click here', 'Submit', or 'OK' — be specific about the action",
+    "Keep labels under 3 words when possible; 4-5 words is the practical maximum",
+    "Icons should support the text meaning, not replace it (except in icon-only buttons)",
+    "Icon-only buttons must have an aria-label describing the action",
+  ],
+
+  responsiveBehaviour: [
+    { breakpoint: "Mobile (<768px)", behavior: "Buttons expand to full width in stacked layouts; minimum height 48px for touch" },
+    { breakpoint: "Tablet (768-1023px)", behavior: "Buttons may be inline or full-width depending on context" },
+    { breakpoint: "Desktop (1024-1439px)", behavior: "Inline buttons with standard padding; group spacing follows $spacing-md" },
+    { breakpoint: "Ultra-wide (>=1440px)", behavior: "Button sizes remain capped — do not scale proportionally with viewport" },
+  ],
+
+  accessibilitySpec: {
+    intro:
+      "Buttons are one of the most critical interactive elements. Accessibility must be flawless to meet WCAG 2.1 compliance.",
+    requirements: [
+      { requirement: "Role", level: "A", notes: "Use native <button> element or role='button' with full keyboard handling" },
+      { requirement: "Focusable", level: "A", notes: "Must be reachable via Tab key; disabled buttons may use aria-disabled instead of removing from tab order" },
+      { requirement: "Keyboard Activation", level: "A", notes: "Enter and Space keys must trigger the same action as a click" },
+      { requirement: "Contrast Ratio", level: "AA", notes: "Text-to-background: 4.5:1 minimum; button boundary to surrounding surface: 3:1" },
+      { requirement: "Touch Target", level: "AA", notes: "Minimum 44x44px touch area per WCAG 2.5.5 (AAA recommends 48x48px)" },
+      { requirement: "ARIA Labels", level: "A", notes: "Icon-only buttons require aria-label; loading state should announce 'Loading' via aria-live region" },
+    ],
+    outro: [
+      "Ensure focus management returns focus to the button after modal dismissal or async action completion",
+      "Never remove the focus outline without providing an equally visible alternative indicator",
+    ],
+  },
+
+  qaAcceptanceCriteria: [
+    { check: "Visual Regression", platform: "All", expectedResult: "Button renders pixel-perfect against baseline for each variant and size" },
+    { check: "Hover State", platform: "Web", expectedResult: "Background transitions smoothly on mouse enter/leave" },
+    { check: "Active State", platform: "Web", expectedResult: "Pressed visual appears on pointerdown and reverts on pointerup" },
+    { check: "Focus State", platform: "Web", expectedResult: "Focus ring visible on Tab; hidden on mouse click (focus-visible)" },
+    { check: "Keyboard Activation", platform: "Web", expectedResult: "Enter and Space fire click handler; no double-fire on Space" },
+    { check: "Screen Reader", platform: "Web", expectedResult: "Announces role 'button', accessible name, and disabled/loading state" },
+    { check: "Disabled State", platform: "All", expectedResult: "Muted visuals; pointer-events none; aria-disabled='true'" },
+    { check: "Loading State", platform: "All", expectedResult: "Spinner visible; label hidden; button width unchanged; clicks ignored" },
+    { check: "Truncation", platform: "Web", expectedResult: "Long labels truncate with ellipsis; no line wrapping" },
+    { check: "Icon Alignment", platform: "All", expectedResult: "Icons vertically centered with label; correct spacing token applied" },
+    { check: "Touch Target Size", platform: "Mobile", expectedResult: "Hit area is at least 44x44px even for Small size" },
+    { check: "Contrast", platform: "All", expectedResult: "All variants pass 4.5:1 text contrast and 3:1 non-text contrast" },
+    { check: "RTL Support", platform: "Web", expectedResult: "Icon positions swap; padding mirrors; text alignment correct in RTL locales" },
+  ],
+
+  dos: [
+    "Use the Primary variant for the single most important action on the page",
+    "Use Secondary or Tertiary variants for supporting or less critical actions",
+    "Keep labels short and action-oriented — prefer verbs",
+    "Maintain consistent padding and never override spacing tokens",
+    "Use standard size presets (Small, Medium, Large) — avoid custom heights",
+    "Ensure sufficient color contrast between button fill and label text",
+    "Provide visual feedback for every interactive state (hover, active, focus, loading)",
+  ],
+
+  donts: [
+    "Do not place multiple Primary buttons in the same view or action group",
+    "Do not use vague labels like 'Click here', 'OK', or 'Submit' without context",
+    "Do not allow label text to wrap to multiple lines — truncate instead",
+    "Do not use buttons for navigation — use links or nav components instead",
+    "Do not disable a button without explaining why (use a tooltip or helper text)",
+    "Do not override design token colors with hard-coded hex values",
+    "Do not make buttons smaller than the minimum touch target (44x44px)",
+  ],
+};

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

@@ -0,0 +1,307 @@
+/**
+ * calendar.ts — Gold-standard design knowledge for Calendar (date picker grid) components
+ */
+import type { ComponentKnowledge } from "../types.js";
+
+export const calendarKnowledge: ComponentKnowledge = {
+  description:
+    "Month-view date grid | Single or range date selection | Interactive calendar for date picking with navigation controls",
+
+  stateSpecifications: [
+    {
+      state: "Today",
+      visualChange: "Day cell has a subtle ring or dot indicator distinguishing it from other days; may use a distinct text color",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Marks the current date for orientation — not necessarily the selected date",
+    },
+    {
+      state: "Selected",
+      visualChange: "Day cell has filled primary background with white text; fully rounded circle or pill shape",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "The date the user has chosen as their selection (single mode)",
+    },
+    {
+      state: "Range Start",
+      visualChange: "Day cell has filled primary background; right side has a connecting highlight leading to range-end",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "First date in a selected range — left corner rounded, right side extends highlight",
+    },
+    {
+      state: "Range End",
+      visualChange: "Day cell has filled primary background; left side has a connecting highlight from range-start",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Last date in a selected range — right corner rounded, left side extends highlight",
+    },
+    {
+      state: "In Range",
+      visualChange: "Day cell has a light tint background connecting range-start and range-end visually",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Dates falling between range-start and range-end; subtle highlight shows continuity",
+    },
+    {
+      state: "Hover",
+      visualChange: "Day cell gains a subtle circular background tint; text color may intensify",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Mouse cursor enters a selectable day cell",
+    },
+    {
+      state: "Focus",
+      visualChange: "2px focus ring around the focused day cell; focus is visible via keyboard navigation",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Day cell receives keyboard focus via arrow key navigation (roving tabindex)",
+    },
+    {
+      state: "Disabled",
+      visualChange: "Day text is muted/grayed out; no hover effect; cell is not interactive",
+      opacity: "0.4",
+      cursorWeb: "not-allowed",
+      usage: "Date is outside the allowed range (before minDate or after maxDate) or blocked by business logic",
+    },
+    {
+      state: "Outside Month",
+      visualChange: "Day numbers from the previous/next month are shown in a muted color to fill the grid",
+      opacity: "0.3",
+      cursorWeb: "pointer",
+      usage: "Dates from adjacent months visible in the grid; may or may not be selectable depending on configuration",
+    },
+  ],
+
+  propertyDescriptions: {
+    value: "Currently selected date (single mode) or date tuple [start, end] (range mode); controlled by parent component",
+    type: "Selection mode — 'single' for picking one date or 'range' for selecting a start and end date",
+    minDate: "Earliest selectable date — dates before this are disabled; accepts Date object or ISO string",
+    maxDate: "Latest selectable date — dates after this are disabled; accepts Date object or ISO string",
+    locale: "Locale string (e.g. 'en-US', 'de-DE') controlling day/month names, first day of week, and date formatting",
+    onSelect: "Callback invoked when a date is selected, receiving the selected Date or [start, end] tuple",
+    month: "Currently displayed month (0-indexed); controls which month's grid is rendered",
+    year: "Currently displayed year; paired with month to determine the visible grid",
+    showOutsideDays: "When true, shows dates from the previous and next months to fill the grid rows",
+    weekStartsOn: "Day the week starts on — 0 for Sunday (US), 1 for Monday (ISO/EU); overrides locale default",
+    disabledDates: "Array of specific dates or date ranges that should be non-selectable within the allowed min/max range",
+  },
+
+  sizeSpecifications: [
+    {
+      size: "Small",
+      height: "280px",
+      paddingLR: "8px",
+      fontSize: "12px",
+      iconSize: "16px",
+      borderRadius: "50% (day cell)",
+    },
+    {
+      size: "Medium",
+      height: "320px",
+      paddingLR: "12px",
+      fontSize: "14px",
+      iconSize: "20px",
+      borderRadius: "50% (day cell)",
+    },
+    {
+      size: "Large",
+      height: "380px",
+      paddingLR: "16px",
+      fontSize: "16px",
+      iconSize: "24px",
+      borderRadius: "50% (day cell)",
+    },
+  ],
+
+  designTokenBindings: [
+    {
+      property: "Background",
+      tokenName: "$calendar-bg",
+      role: "Calendar container background",
+      fallback: "#FFFFFF",
+    },
+    {
+      property: "Day Text",
+      tokenName: "$calendar-day-text",
+      role: "Default day number text color",
+      fallback: "#344054",
+    },
+    {
+      property: "Day Hover",
+      tokenName: "$calendar-day-hover-bg",
+      role: "Circular background tint on day cell hover",
+      fallback: "#F2F4F7",
+    },
+    {
+      property: "Selected Background",
+      tokenName: "$calendar-selected-bg",
+      role: "Filled background for the selected day cell",
+      fallback: "#2563EB",
+    },
+    {
+      property: "Selected Text",
+      tokenName: "$calendar-selected-text",
+      role: "Text color on the selected day cell",
+      fallback: "#FFFFFF",
+    },
+    {
+      property: "Today Indicator",
+      tokenName: "$calendar-today-border",
+      role: "Ring or border color marking today's date",
+      fallback: "#2563EB",
+    },
+    {
+      property: "Range Fill",
+      tokenName: "$calendar-range-bg",
+      role: "Light tint background for dates within a selected range",
+      fallback: "#EFF8FF",
+    },
+    {
+      property: "Outside Month Text",
+      tokenName: "$calendar-outside-text",
+      role: "Muted text color for dates from adjacent months",
+      fallback: "#98A2B3",
+    },
+    {
+      property: "Disabled Text",
+      tokenName: "$calendar-disabled-text",
+      role: "Muted text color for non-selectable dates",
+      fallback: "#D0D5DD",
+    },
+    {
+      property: "Header Text",
+      tokenName: "$calendar-header-text",
+      role: "Month and year label text color in the navigation header",
+      fallback: "#101828",
+    },
+    {
+      property: "Weekday Header",
+      tokenName: "$calendar-weekday-text",
+      role: "Day-of-week column header text color (e.g. Mon, Tue)",
+      fallback: "#667085",
+    },
+    {
+      property: "Navigation Icon",
+      tokenName: "$calendar-nav-icon",
+      role: "Previous/next month arrow icon color",
+      fallback: "#667085",
+    },
+    {
+      property: "Focus Ring",
+      tokenName: "$focus-ring",
+      role: "Keyboard focus indicator around the focused day cell",
+      fallback: "0 0 0 2px #FFFFFF, 0 0 0 4px #2E90FA",
+    },
+  ],
+
+  structureRules: [
+    "Calendar container uses vertical Auto Layout: navigation header → weekday labels → day grid",
+    "Navigation header has horizontal layout: previous month button → month/year label (centered) → next month button",
+    "Weekday labels row shows abbreviated day names (Mon, Tue, ...) in a 7-column grid",
+    "Day grid is a 7-column grid with 5-6 rows depending on the month; each cell is a square",
+    "Day cells are uniformly sized squares with the day number centered both horizontally and vertically",
+    "Selected day cells use a fully circular background (border-radius: 50%)",
+    "Range selection fills the rectangular area between start and end with a connecting background tint",
+    "Range start has left-rounded corners; range end has right-rounded corners; in-between cells have no rounding",
+    "Navigation arrows are positioned at the far left and right of the header row",
+    "Today's date is marked with a subtle ring or dot indicator that does not conflict with the selected state",
+  ],
+
+  typeHierarchyRules: [
+    "Month/year label in the header uses SemiBold weight (600) at the standard fontSize for the size preset",
+    "Weekday labels use Medium weight (500) at one size smaller (e.g. 12px when day cells use 14px)",
+    "Day numbers use Regular weight (400) by default; selected day may use Medium (500)",
+    "Month/year text uses sentence case with full month name: 'January 2026', not 'JAN 2026'",
+    "Weekday labels use short abbreviations: 'Mon', 'Tue' — or single letters: 'M', 'T' for compact sizes",
+  ],
+
+  interactionRules: [
+    { event: "Click Day", trigger: "Pointer up on a selectable day cell", action: "Select the date; fire onSelect; update visual to selected state" },
+    { event: "Click Range Start", trigger: "First click in range mode", action: "Set range start; highlight the clicked date; wait for second click to set range end" },
+    { event: "Click Range End", trigger: "Second click in range mode", action: "Set range end; fill in-between dates with range highlight; fire onSelect with [start, end]" },
+    { event: "Previous Month", trigger: "Click previous arrow button", action: "Navigate to the previous month; update grid; maintain focus position if applicable" },
+    { event: "Next Month", trigger: "Click next arrow button", action: "Navigate to the next month; update grid; maintain focus position if applicable" },
+    { event: "Arrow Keys", trigger: "Arrow keys while a day cell is focused", action: "Move focus: Left/Right by 1 day, Up/Down by 1 week; cross month boundaries automatically" },
+    { event: "Page Up", trigger: "Page Up key while focused", action: "Navigate to the previous month, keeping the same day-of-month focused" },
+    { event: "Page Down", trigger: "Page Down key while focused", action: "Navigate to the next month, keeping the same day-of-month focused" },
+    { event: "Home", trigger: "Home key while focused", action: "Move focus to the first day of the current month" },
+    { event: "End", trigger: "End key while focused", action: "Move focus to the last day of the current month" },
+    { event: "Enter / Space", trigger: "Enter or Space on a focused day", action: "Select the focused date (equivalent to clicking)" },
+    { event: "Hover (Range)", trigger: "Hover over a day while range start is set but end is not", action: "Preview the range highlight between start and hovered date" },
+  ],
+
+  contentGuidance: [
+    "Display the full month name and year in the header for clarity: 'January 2026' not '01/2026'",
+    "Use locale-appropriate day abbreviations and first-day-of-week settings",
+    "Show outside-month dates in a muted style to provide context without confusing the current month",
+    "Clearly distinguish today's date from the selected date — they may not be the same",
+    "For range selection, show a preview highlight on hover so users can see the range before confirming",
+    "Display the selected date(s) in a summary below or beside the calendar when used in a date picker dropdown",
+    "Use month/year dropdowns or year navigation for selecting dates far from the current month",
+  ],
+
+  responsiveBehaviour: [
+    { breakpoint: "Mobile (<768px)", behavior: "Calendar takes full container width; day cells expand to fill; touch targets are at least 44x44px" },
+    { breakpoint: "Tablet (768-1023px)", behavior: "Calendar uses medium size; may display two months side-by-side for range selection" },
+    { breakpoint: "Desktop (1024-1439px)", behavior: "Standard calendar size; single month view for single selection; dual month for range" },
+    { breakpoint: "Ultra-wide (>=1440px)", behavior: "Calendar size remains fixed; does not scale with viewport; positioned near its trigger element" },
+  ],
+
+  accessibilitySpec: {
+    intro:
+      "Calendars are complex interactive widgets requiring robust keyboard navigation and ARIA semantics. The WAI-ARIA grid pattern with roving tabindex ensures keyboard users can navigate dates efficiently while screen readers announce date context.",
+    requirements: [
+      { requirement: "Grid Role", level: "A", notes: "Calendar grid must use role='grid' with each row as role='row' and each day cell as role='gridcell'" },
+      { requirement: "Roving Tabindex", level: "A", notes: "Only one day cell has tabindex='0' at a time; arrow keys move focus; Tab exits the calendar" },
+      { requirement: "Arrow Key Navigation", level: "A", notes: "Left/Right moves by day; Up/Down moves by week; navigation crosses month boundaries automatically" },
+      { requirement: "Page Navigation", level: "A", notes: "Page Up/Down navigates months; Shift+Page Up/Down navigates years" },
+      { requirement: "Accessible Labels", level: "A", notes: "Each day cell must have an accessible label including the full date (e.g. 'January 15, 2026')" },
+      { requirement: "Selected State", level: "A", notes: "Selected dates must have aria-selected='true'; range start/end should convey range context" },
+      { requirement: "Disabled Dates", level: "A", notes: "Disabled dates must have aria-disabled='true' and not respond to selection" },
+      { requirement: "Live Region", level: "AA", notes: "When the month changes, announce the new month/year via aria-live='polite'" },
+      { requirement: "Contrast", level: "AA", notes: "Day numbers must meet 4.5:1 text contrast; selected/today indicators must meet 3:1 non-text contrast" },
+    ],
+    outro: [
+      "Test keyboard navigation across month boundaries — arrow keys on the last day of a month should advance to the next month",
+      "Verify screen readers announce 'selected' for chosen dates and 'disabled' for unavailable dates",
+      "Ensure the month/year header is announced when navigating between months via Page Up/Down",
+    ],
+  },
+
+  qaAcceptanceCriteria: [
+    { check: "Month Rendering", platform: "All", expectedResult: "Correct number of days for each month; proper weekday alignment" },
+    { check: "Today Indicator", platform: "All", expectedResult: "Today's date is visually marked with a ring or dot; distinct from selected state" },
+    { check: "Single Selection", platform: "All", expectedResult: "Clicking a day selects it with filled circle; previous selection clears; onSelect fires" },
+    { check: "Range Selection", platform: "All", expectedResult: "First click sets start; second click sets end; range highlight fills between; onSelect fires with tuple" },
+    { check: "Range Preview", platform: "Web", expectedResult: "Hovering after range start shows preview highlight between start and hovered date" },
+    { check: "Month Navigation", platform: "All", expectedResult: "Previous/Next arrows change the displayed month; header updates correctly" },
+    { check: "Disabled Dates", platform: "All", expectedResult: "Dates outside min/max or in disabledDates array are muted and not clickable" },
+    { check: "Keyboard Navigation", platform: "Web", expectedResult: "Arrow keys move focus by day/week; Page Up/Down changes month; Home/End jump to first/last day" },
+    { check: "Cross-Month Navigation", platform: "Web", expectedResult: "Arrow keys past month boundary navigate to the next/previous month and update grid" },
+    { check: "Locale Support", platform: "All", expectedResult: "Day names, month names, and first day of week respect the locale setting" },
+    { check: "Screen Reader", platform: "Web", expectedResult: "Grid role announced; day cells include full date label; selected/disabled states announced" },
+    { check: "Contrast", platform: "All", expectedResult: "All day states pass 4.5:1 text contrast; selected/today indicators pass 3:1 non-text contrast" },
+    { check: "RTL Support", platform: "Web", expectedResult: "Calendar grid mirrors; navigation arrows swap sides; day order respects RTL reading direction" },
+  ],
+
+  dos: [
+    "Use the WAI-ARIA grid pattern with roving tabindex for keyboard navigation",
+    "Mark today's date distinctly from the selected date so users can orient themselves",
+    "Support full keyboard navigation including arrow keys, Page Up/Down, Home, and End",
+    "Announce month changes to screen readers via an aria-live region",
+    "Show a range preview on hover when the user has selected a range start but not yet an end",
+    "Respect locale settings for day names, month names, and first day of week",
+    "Provide accessible labels on each day cell with the full date (e.g. 'January 15, 2026')",
+  ],
+
+  donts: [
+    "Do not use a calendar for selecting dates far in the past or future — add year navigation or a text input alternative",
+    "Do not make day cells smaller than 32x32px on desktop or 44x44px on mobile/touch devices",
+    "Do not hide the month/year header — users need context for the displayed dates",
+    "Do not allow selection of disabled dates — they must be truly non-interactive",
+    "Do not rely on color alone to indicate today, selected, or range states — use shapes and indicators",
+    "Do not skip month boundary navigation — arrow keys must flow seamlessly across months",
+    "Do not use a calendar component for time selection — use a time picker component instead",
+  ],
+};