@sarjallab09/figma-intelligence 1.0.0

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

@@ -0,0 +1,293 @@
+/**
+ * time-picker.ts — Gold-standard design knowledge for Time Picker components
+ */
+import type { ComponentKnowledge } from "../types.js";
+
+export const timePickerKnowledge: ComponentKnowledge = {
+  description:
+    "Time selection input | Combobox-driven time chooser | Supports 12h and 24h formats with configurable intervals",
+
+  stateSpecifications: [
+    {
+      state: "Default",
+      visualChange: "Input field shows placeholder or current value; dropdown is closed; clock icon visible",
+      opacity: "1",
+      cursorWeb: "text",
+      usage: "Resting state — field is interactive and ready for input or dropdown activation",
+    },
+    {
+      state: "Focused",
+      visualChange: "Input field border changes to primary color; focus ring appears; dropdown may open automatically",
+      opacity: "1",
+      cursorWeb: "text",
+      usage: "Input field has received keyboard focus via Tab or click — ready for typing or arrow navigation",
+    },
+    {
+      state: "Open",
+      visualChange: "Dropdown list of time options is visible below/above the input; currently highlighted option has a tint",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Dropdown is expanded showing available time slots for selection",
+    },
+    {
+      state: "Error",
+      visualChange: "Input border turns red/error color; error icon appears; inline error message shown below the field",
+      opacity: "1",
+      cursorWeb: "text",
+      usage: "Entered time is invalid, outside the allowed range, or in an incorrect format",
+    },
+    {
+      state: "Disabled",
+      visualChange: "Input field background and text are muted; clock icon is desaturated; no interaction possible",
+      opacity: "0.4",
+      cursorWeb: "not-allowed",
+      usage: "Time selection is unavailable — field is non-interactive",
+    },
+    {
+      state: "Read-Only",
+      visualChange: "Input displays the value but has no editable cursor; border may be removed or subtle",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Time value is displayed but cannot be changed — used in review or summary contexts",
+    },
+    {
+      state: "Hover",
+      visualChange: "Input border shifts to a slightly darker shade; subtle background change",
+      opacity: "1",
+      cursorWeb: "text",
+      usage: "Mouse cursor enters the input field area",
+    },
+  ],
+
+  propertyDescriptions: {
+    value: "Currently selected time as a string (e.g. '14:30' or '2:30 PM') or Date object; controlled by parent",
+    format: "Time format — '12h' for AM/PM display or '24h' for military time; affects both input and dropdown",
+    minuteStep: "Interval between time options in the dropdown — 1, 5, 10, 15, 30, or 60 minutes",
+    minTime: "Earliest selectable time — options before this are disabled or hidden in the dropdown",
+    maxTime: "Latest selectable time — options after this are disabled or hidden in the dropdown",
+    size: "Dimensional preset — Small, Medium, or Large — controlling input height, padding, and font size",
+    placeholder: "Placeholder text shown when no value is set — typically the format hint: 'HH:MM' or 'hh:mm AM/PM'",
+    onChange: "Callback invoked when the time value changes, receiving the new time value",
+    disabled: "When true, the time picker is non-interactive; visuals are muted; no dropdown opens",
+    readOnly: "When true, the value is displayed but not editable; useful for display-only contexts",
+    label: "Visible label text associated with the time picker; positioned above the input field",
+    error: "Error message string; when set, the field enters error state with red border and error text below",
+    clearable: "When true, shows a clear (X) button inside the input to reset the value to empty",
+  },
+
+  sizeSpecifications: [
+    {
+      size: "Small",
+      height: "32px",
+      paddingLR: "10px",
+      fontSize: "12px",
+      iconSize: "16px",
+      borderRadius: "6px",
+    },
+    {
+      size: "Medium",
+      height: "40px",
+      paddingLR: "12px",
+      fontSize: "14px",
+      iconSize: "20px",
+      borderRadius: "8px",
+    },
+    {
+      size: "Large",
+      height: "48px",
+      paddingLR: "14px",
+      fontSize: "16px",
+      iconSize: "24px",
+      borderRadius: "10px",
+    },
+  ],
+
+  designTokenBindings: [
+    {
+      property: "Input Background",
+      tokenName: "$time-picker-input-bg",
+      role: "Background fill of the time input field",
+      fallback: "#FFFFFF",
+    },
+    {
+      property: "Input Border",
+      tokenName: "$time-picker-input-border",
+      role: "Border color of the input field in default state",
+      fallback: "#D0D5DD",
+    },
+    {
+      property: "Input Focus Border",
+      tokenName: "$time-picker-focus-border",
+      role: "Border color when the input is focused",
+      fallback: "#2563EB",
+    },
+    {
+      property: "Input Text",
+      tokenName: "$time-picker-text",
+      role: "Text color for the entered or selected time value",
+      fallback: "#101828",
+    },
+    {
+      property: "Placeholder Text",
+      tokenName: "$time-picker-placeholder",
+      role: "Placeholder text color when no value is set",
+      fallback: "#98A2B3",
+    },
+    {
+      property: "Clock Icon",
+      tokenName: "$time-picker-icon",
+      role: "Clock icon color inside the input field",
+      fallback: "#667085",
+    },
+    {
+      property: "Dropdown Background",
+      tokenName: "$time-picker-dropdown-bg",
+      role: "Background fill of the time options dropdown",
+      fallback: "#FFFFFF",
+    },
+    {
+      property: "Dropdown Shadow",
+      tokenName: "$shadow-dropdown",
+      role: "Elevation shadow on the time options dropdown",
+      fallback: "0 4px 16px rgba(0, 0, 0, 0.12)",
+    },
+    {
+      property: "Option Hover",
+      tokenName: "$time-picker-option-hover-bg",
+      role: "Background tint on a hovered time option in the dropdown",
+      fallback: "#F2F4F7",
+    },
+    {
+      property: "Option Selected",
+      tokenName: "$time-picker-option-selected-bg",
+      role: "Background fill for the currently selected time option",
+      fallback: "#EFF8FF",
+    },
+    {
+      property: "Error Border",
+      tokenName: "$time-picker-error-border",
+      role: "Input border color in error state",
+      fallback: "#F04438",
+    },
+    {
+      property: "Error Text",
+      tokenName: "$time-picker-error-text",
+      role: "Error message text color below the input",
+      fallback: "#D92D20",
+    },
+    {
+      property: "Focus Ring",
+      tokenName: "$focus-ring",
+      role: "Keyboard focus indicator on the input field",
+      fallback: "0 0 0 2px #FFFFFF, 0 0 0 4px #2E90FA",
+    },
+  ],
+
+  structureRules: [
+    "Input field uses horizontal Auto Layout: optional label above → input container (icon + text + clear button) → error message below",
+    "Clock icon is positioned at the trailing end (right in LTR) of the input field",
+    "Clear button (X) appears between the text and clock icon when clearable is true and a value is set",
+    "Dropdown panel is positioned below the input by default; flips above if insufficient viewport space below",
+    "Dropdown is a scrollable list of time options at the configured minuteStep intervals",
+    "Each dropdown option is a single-line text item showing the formatted time (e.g. '2:30 PM' or '14:30')",
+    "Dropdown width matches the input field width at minimum; may be slightly wider for comfortable padding",
+    "The currently selected option is scrolled into view when the dropdown opens",
+    "AM/PM period selector (12h format) may appear as a separate column or as part of each option text",
+  ],
+
+  typeHierarchyRules: [
+    "Input text uses Regular weight (400) — the time value should be clearly readable without emphasis",
+    "Label text uses Medium weight (500) positioned above the input with $spacing-xs gap",
+    "Dropdown option text uses Regular weight (400); selected option may use Medium weight (500)",
+    "Error message text uses Regular weight (400) at 12px below the input field",
+    "Placeholder text uses Regular weight (400) in a muted color — shows format hint like 'HH:MM'",
+  ],
+
+  interactionRules: [
+    { event: "Click Input", trigger: "Click/tap on the input field or clock icon", action: "Focus the input; optionally open the time dropdown" },
+    { event: "Type Time", trigger: "User types a time value directly into the input", action: "Parse the input; validate against format, minTime, maxTime; fire onChange if valid" },
+    { event: "Open Dropdown", trigger: "Click clock icon or press Down arrow when focused", action: "Display the dropdown list; scroll the selected or nearest option into view" },
+    { event: "Select Option", trigger: "Click/tap on a time option in the dropdown", action: "Set the value; close the dropdown; fire onChange; return focus to input" },
+    { event: "Arrow Down", trigger: "Down arrow while dropdown is open", action: "Move highlight to the next time option; scroll if needed" },
+    { event: "Arrow Up", trigger: "Up arrow while dropdown is open", action: "Move highlight to the previous time option; scroll if needed" },
+    { event: "Enter", trigger: "Enter key while an option is highlighted", action: "Select the highlighted option; close the dropdown; fire onChange" },
+    { event: "Escape", trigger: "Escape key while dropdown is open", action: "Close the dropdown without changing the value; return focus to input" },
+    { event: "Tab", trigger: "Tab key while dropdown is open", action: "Select the highlighted option (if any); close the dropdown; move focus to the next field" },
+    { event: "Clear", trigger: "Click the clear (X) button", action: "Reset the value to empty; fire onChange with null/empty; keep focus on input" },
+  ],
+
+  contentGuidance: [
+    "Use the format that matches user expectations: 12h (AM/PM) for US audiences, 24h for most international audiences",
+    "Set a reasonable minuteStep — 15 or 30 minutes for appointments; 5 or 1 for precise time entry",
+    "Show the format hint as placeholder text: 'HH:MM AM/PM' or 'HH:MM' so users know the expected input",
+    "Display the currently selected time in a clearly formatted style matching the chosen format",
+    "Error messages should be specific: 'Select a time between 9:00 AM and 5:00 PM' not 'Invalid time'",
+    "Label the field clearly: 'Start time', 'Meeting time' — not just 'Time'",
+    "When used alongside a date picker, place the time picker to the right of or below the date field",
+  ],
+
+  responsiveBehaviour: [
+    { breakpoint: "Mobile (<768px)", behavior: "Input expands to full container width; dropdown fills available width; touch targets are 44px minimum; consider native time input on supported mobile browsers" },
+    { breakpoint: "Tablet (768-1023px)", behavior: "Standard input width; dropdown positioned below with sufficient padding from viewport edges" },
+    { breakpoint: "Desktop (1024-1439px)", behavior: "Compact input width; dropdown opens below or above based on viewport space" },
+    { breakpoint: "Ultra-wide (>=1440px)", behavior: "Input and dropdown sizes remain fixed; no scaling with viewport width" },
+  ],
+
+  accessibilitySpec: {
+    intro:
+      "Time pickers combine text input with a dropdown listbox. The combobox pattern requires proper ARIA roles on the input and list, keyboard navigation for the dropdown, and clear announcements of the selected time.",
+    requirements: [
+      { requirement: "Combobox Role", level: "A", notes: "Input must have role='combobox' with aria-expanded indicating dropdown visibility" },
+      { requirement: "Listbox Role", level: "A", notes: "Dropdown list must have role='listbox' with each option having role='option'" },
+      { requirement: "Active Descendant", level: "A", notes: "Use aria-activedescendant on the input to indicate the currently highlighted option in the dropdown" },
+      { requirement: "Label Association", level: "A", notes: "Input must be associated with its label via for/id or aria-labelledby" },
+      { requirement: "Keyboard Navigation", level: "A", notes: "Arrow keys navigate the dropdown; Enter selects; Escape closes without selecting" },
+      { requirement: "Error State", level: "A", notes: "When in error, input must have aria-invalid='true' and aria-describedby pointing to the error message" },
+      { requirement: "Contrast", level: "AA", notes: "Input text and dropdown option text must meet 4.5:1 contrast; borders and icons must meet 3:1 non-text contrast" },
+      { requirement: "Touch Target", level: "AA", notes: "Input field and each dropdown option must have a minimum 44px height on touch devices" },
+      { requirement: "Autocomplete", level: "AA", notes: "Typing in the input should filter or scroll to matching time options for faster selection" },
+    ],
+    outro: [
+      "Test with screen readers to verify combobox role, expanded state, option labels, and selected state are announced",
+      "Verify that arrow key navigation within the dropdown does not scroll the background page",
+      "Ensure that the time format (12h/24h) is consistent between the input display and the dropdown options",
+    ],
+  },
+
+  qaAcceptanceCriteria: [
+    { check: "Default Render", platform: "All", expectedResult: "Input shows placeholder with clock icon; dropdown is closed" },
+    { check: "Dropdown Open", platform: "All", expectedResult: "Clicking input or clock icon opens dropdown; selected/nearest option is scrolled into view" },
+    { check: "Option Selection", platform: "All", expectedResult: "Clicking an option sets the value, closes dropdown, and fires onChange" },
+    { check: "12h Format", platform: "All", expectedResult: "Times display with AM/PM suffix; dropdown shows 12-hour formatted options" },
+    { check: "24h Format", platform: "All", expectedResult: "Times display in 00:00-23:59 range; dropdown shows 24-hour formatted options" },
+    { check: "Minute Step", platform: "All", expectedResult: "Dropdown options are spaced by the configured minuteStep interval" },
+    { check: "Min/Max Time", platform: "All", expectedResult: "Options outside minTime-maxTime range are disabled or hidden" },
+    { check: "Keyboard Navigation", platform: "Web", expectedResult: "Arrow keys navigate dropdown; Enter selects; Escape closes; Tab selects and moves focus" },
+    { check: "Type-Ahead", platform: "Web", expectedResult: "Typing in the input filters or scrolls the dropdown to matching times" },
+    { check: "Error State", platform: "All", expectedResult: "Red border, error icon, and error message render; aria-invalid is true" },
+    { check: "Disabled State", platform: "All", expectedResult: "Input and icon are muted; no dropdown opens; not focusable" },
+    { check: "Clear Button", platform: "All", expectedResult: "Clear X button resets value; fires onChange with empty; keeps focus on input" },
+    { check: "Screen Reader", platform: "Web", expectedResult: "Announces combobox role, expanded state, active option, and selected value" },
+    { check: "RTL Support", platform: "Web", expectedResult: "Clock icon moves to left; text alignment and dropdown position adjust for RTL" },
+  ],
+
+  dos: [
+    "Use the combobox ARIA pattern with role='combobox' on the input and role='listbox' on the dropdown",
+    "Support both typed input and dropdown selection for maximum flexibility",
+    "Display a clear format hint as placeholder text so users know the expected input format",
+    "Scroll the dropdown to the selected or nearest time option when opening",
+    "Validate input in real-time and show specific error messages for invalid entries",
+    "Use consistent time formatting between the input display and dropdown options",
+    "Pair with a date picker when both date and time are needed, with clear labeling for each",
+  ],
+
+  donts: [
+    "Do not use a time picker for selecting durations — use a duration input or number fields instead",
+    "Do not default to 12h format for international audiences — respect locale conventions",
+    "Do not use a minuteStep smaller than 1 — sub-minute precision is rarely needed in UI",
+    "Do not auto-close the dropdown on scroll — users may need to scroll through many options",
+    "Do not omit the label — an unlabeled time picker is ambiguous (start time? end time?)",
+    "Do not use a calendar or date grid for time selection — the dropdown list is the standard pattern",
+    "Do not make dropdown options smaller than 32px height — touch targets must be comfortable",
+  ],
+};

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

@@ -0,0 +1,144 @@
+import type { ComponentKnowledge } from "../types.js";
+
+export const toastKnowledge: ComponentKnowledge = {
+  description:
+    "Transient notification | Status feedback message | Auto-dismissing alert",
+
+  stateSpecifications: [
+    { state: "Info", visualChange: "Blue left accent bar, info icon, neutral background", opacity: "1", cursorWeb: "default", usage: "General informational message — e.g. 'Settings updated'" },
+    { state: "Success", visualChange: "Green left accent bar, checkmark icon", opacity: "1", cursorWeb: "default", usage: "Positive outcome confirmation — e.g. 'File saved'" },
+    { state: "Warning", visualChange: "Yellow left accent bar, warning triangle icon", opacity: "1", cursorWeb: "default", usage: "Non-critical issue requiring awareness — e.g. 'Storage nearly full'" },
+    { state: "Error", visualChange: "Red left accent bar, error icon", opacity: "1", cursorWeb: "default", usage: "Failure or critical issue — e.g. 'Upload failed'" },
+    { state: "Entering", visualChange: "Toast slides in from edge with fade, stacking offset applied", opacity: "0→1", cursorWeb: "default", usage: "Transition state when toast appears" },
+    { state: "Dismissing", visualChange: "Toast slides out and fades, siblings animate to close gap", opacity: "1→0", cursorWeb: "default", usage: "Auto-dismiss timer expired or user manually closed" },
+    { state: "Paused", visualChange: "Timer bar freezes, toast remains visible", opacity: "1", cursorWeb: "default", usage: "Hover or focus pauses the auto-dismiss countdown" },
+  ],
+
+  propertyDescriptions: {
+    variant: "Semantic type — info, success, warning, or error — controls color and icon",
+    title: "Short bold heading summarizing the notification",
+    message: "Optional body text providing additional detail about the event",
+    duration: "Auto-dismiss delay in milliseconds; 0 means persistent until manually closed",
+    position: "Screen anchor — top-right, top-center, bottom-right, bottom-center, bottom-left",
+    hasCloseButton: "Shows an X icon allowing manual dismissal before auto-dismiss",
+    actionLabel: "Optional text button inside the toast for a follow-up action (e.g. 'Undo')",
+    onAction: "Callback fired when the user clicks the action button",
+    stacking: "How multiple toasts arrange — stack (vertical list) or replace (latest wins)",
+    maxVisible: "Maximum number of toasts shown simultaneously before older ones collapse",
+  },
+
+  sizeSpecifications: [
+    { size: "compact", height: "40px", paddingLR: "12px", fontSize: "12px", iconSize: "16px", borderRadius: "4px" },
+    { size: "default", height: "auto (min 48px)", paddingLR: "16px", fontSize: "14px", iconSize: "20px", borderRadius: "6px" },
+    { size: "wide", height: "auto (min 48px)", paddingLR: "16px", fontSize: "14px", iconSize: "20px", borderRadius: "6px" },
+    { size: "full-width", height: "auto (min 48px)", paddingLR: "24px", fontSize: "14px", iconSize: "20px", borderRadius: "0px" },
+    { size: "mobile", height: "auto (min 56px)", paddingLR: "16px", fontSize: "16px", iconSize: "24px", borderRadius: "8px" },
+  ],
+
+  designTokenBindings: [
+    { property: "surface-bg", tokenName: "color/layer/01", role: "Toast container background", fallback: "#FFFFFF" },
+    { property: "info-accent", tokenName: "color/support/info", role: "Left border and icon for info variant", fallback: "#0043CE" },
+    { property: "success-accent", tokenName: "color/support/success", role: "Left border and icon for success variant", fallback: "#198038" },
+    { property: "warning-accent", tokenName: "color/support/warning", role: "Left border and icon for warning variant", fallback: "#F1C21B" },
+    { property: "error-accent", tokenName: "color/support/error", role: "Left border and icon for error variant", fallback: "#DA1E28" },
+    { property: "title-text", tokenName: "color/text/primary", role: "Toast title text", fallback: "#161616" },
+    { property: "shadow", tokenName: "shadow/raised/03", role: "Drop shadow for floating toast", fallback: "0 4px 12px rgba(0,0,0,0.15)" },
+  ],
+
+  structureRules: [
+    "Toast container uses position:fixed and is placed outside the main content flow",
+    "Each toast has a 4px left accent bar indicating the semantic variant color",
+    "Internal layout is a horizontal row: accent bar → icon → content (title + message) → action → close",
+    "Stacked toasts offset vertically with 8px gap; newest toast appears at the top of the stack",
+    "A progress bar at the bottom of the toast visualizes the remaining auto-dismiss time",
+    "Toast container has z-index higher than modals to ensure visibility above all layers",
+    "Maximum width is 400px (default) or 100vw on mobile; minimum width is 280px",
+  ],
+
+  typeHierarchyRules: [
+    "Title uses body-compact-01 (14px) in semibold weight for quick scanning",
+    "Message uses body-compact-01 (14px) in regular weight, text-secondary color",
+    "Action button label uses body-compact-01 (14px) in the interactive color, underlined",
+    "Title is limited to a single line; truncate with ellipsis if too long",
+    "Message is limited to 2 lines; longer content should use a different notification pattern",
+    "Timestamp (if shown) uses label-01 (12px) in text-helper color",
+    "Ensure title and message have at least 4.5:1 contrast against the toast surface",
+  ],
+
+  interactionRules: [
+    { event: "timer:expire", trigger: "Auto-dismiss duration elapses", action: "Animate toast out and remove from DOM; shift stack positions" },
+    { event: "click:close", trigger: "User clicks the close icon button", action: "Immediately dismiss the toast with exit animation" },
+    { event: "click:action", trigger: "User clicks the action button (e.g. 'Undo')", action: "Fire onAction callback and dismiss the toast" },
+    { event: "hover", trigger: "Pointer enters the toast surface", action: "Pause the auto-dismiss timer; freeze progress bar" },
+    { event: "hover:leave", trigger: "Pointer leaves the toast surface", action: "Resume the auto-dismiss timer from where it paused" },
+    { event: "focus", trigger: "Keyboard focus enters the toast (close button or action)", action: "Pause auto-dismiss timer to give the user time to interact" },
+    { event: "swipe:horizontal", trigger: "User swipes the toast left or right (mobile)", action: "Dismiss the toast in the swipe direction with slide animation" },
+  ],
+
+  contentGuidance: [
+    "Title should be a concise past-tense statement — 'Message sent' not 'Your message has been sent successfully'",
+    "Message body is optional; omit it if the title alone is sufficient",
+    "Action labels should be single verbs or short phrases — 'Undo', 'View', 'Retry'",
+    "Avoid technical jargon in error toasts — 'Could not save file' not 'ENOSPC: disk quota exceeded'",
+    "Do not use toasts for critical errors that require user action — use an inline alert or modal instead",
+    "Success toasts are often sufficient with just a title and no body text",
+    "Warning toasts should suggest what the user can do to resolve the issue",
+  ],
+
+  responsiveBehaviour: [
+    { breakpoint: "≥ 1056px (lg)", behavior: "Toasts anchor to top-right corner with 16px margin; max-width 400px" },
+    { breakpoint: "672–1055px (md)", behavior: "Toasts anchor to top-center; width adapts up to 400px" },
+    { breakpoint: "< 672px (sm)", behavior: "Toasts span full width at top or bottom of viewport with 8px margin" },
+    { breakpoint: "Reduced motion", behavior: "Skip slide/fade animation; toast appears and disappears instantly" },
+    { breakpoint: "Multiple toasts", behavior: "Stack up to maxVisible; excess toasts show as a collapsed count badge" },
+  ],
+
+  accessibilitySpec: {
+    intro:
+      "Toasts must announce their content to screen readers without stealing focus from the user's current task. They rely on ARIA live regions to push announcements into the screen reader queue.",
+    requirements: [
+      { requirement: "Toast container must use role='status' and aria-live='polite' for non-critical messages", level: "A", notes: "Info and success variants use polite to avoid interrupting the user" },
+      { requirement: "Error toasts must use role='alert' and aria-live='assertive'", level: "A", notes: "Assertive ensures the error is announced immediately" },
+      { requirement: "Close button must have aria-label='Dismiss notification' or equivalent", level: "A", notes: "Icon-only button requires a text label for screen readers" },
+      { requirement: "Action button must be keyboard focusable and have a descriptive label", level: "A", notes: "Avoid generic labels like 'Click here'" },
+      { requirement: "Auto-dismiss timer must pause when the toast receives keyboard focus", level: "A", notes: "WCAG 2.2.1 Timing Adjustable — user must have enough time to read" },
+      { requirement: "Toast must not depend on color alone for status — icon shape must differ per variant", level: "A", notes: "Checkmark for success, triangle for warning, circle-x for error" },
+      { requirement: "Focus must not move to the toast automatically — it should be announced in-place", level: "AA", notes: "Moving focus would disorient users in the middle of a task" },
+    ],
+    outro: [
+      "Test that VoiceOver announces 'File saved' when a success toast appears without moving focus",
+      "Verify error toasts interrupt the current screen reader output via assertive announcement",
+      "Confirm that hover and focus both pause the dismiss timer independently",
+    ],
+  },
+
+  qaAcceptanceCriteria: [
+    { check: "Toast appears and auto-dismisses after configured duration", platform: "All", expectedResult: "Toast visible for duration, then animates out" },
+    { check: "Hover pauses auto-dismiss timer", platform: "Web", expectedResult: "Progress bar freezes; timer resumes on mouse leave" },
+    { check: "Close button dismisses immediately", platform: "All", expectedResult: "Toast removed with exit animation" },
+    { check: "Action button fires callback and dismisses", platform: "All", expectedResult: "Callback executes; toast disappears" },
+    { check: "Multiple toasts stack correctly", platform: "All", expectedResult: "Toasts offset vertically with 8px gap; oldest at bottom" },
+    { check: "Error toast uses assertive live region", platform: "Web", expectedResult: "Screen reader announces error immediately" },
+    { check: "Swipe dismisses on mobile", platform: "Mobile", expectedResult: "Horizontal swipe removes toast with slide animation" },
+  ],
+
+  dos: [
+    "Use aria-live='polite' for info/success and 'assertive' for error toasts",
+    "Pause the auto-dismiss timer on hover and keyboard focus",
+    "Provide an action button for reversible actions — e.g. 'Undo' after deletion",
+    "Use distinct icons per variant so status is not communicated by color alone",
+    "Cap the visible stack at 3–5 toasts to avoid overwhelming the viewport",
+    "Position toasts away from primary navigation and form fields",
+    "Use a progress bar to show remaining time before auto-dismiss",
+  ],
+
+  donts: [
+    "Don't use toasts for critical errors that require immediate user action — use a modal or inline alert",
+    "Don't set auto-dismiss duration below 4 seconds — users need time to read",
+    "Don't stack more than 5 toasts — older toasts should collapse or be replaced",
+    "Don't move focus to the toast — it disrupts the user's current workflow",
+    "Don't use toasts for content that needs to persist — use a banner instead",
+    "Don't omit the close button on persistent (duration: 0) toasts",
+    "Don't use identical toast messages in rapid succession — debounce duplicate events",
+  ],
+};