@sarjallab09/figma-intelligence 1.0.0

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

@@ -0,0 +1,270 @@
+/**
+ * stepper.ts — Gold-standard design knowledge for Stepper (multi-step progress) components
+ */
+import type { ComponentKnowledge } from "../types.js";
+
+export const stepperKnowledge: ComponentKnowledge = {
+  description:
+    "Multi-step progress indicator | Sequential workflow guide | Visual step-by-step navigation aid",
+
+  stateSpecifications: [
+    {
+      state: "Completed",
+      visualChange: "Step circle shows a checkmark icon with filled success background; connecting line is solid and colored",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Step has been finished — user can click to revisit when clickable is true",
+    },
+    {
+      state: "Current",
+      visualChange: "Step circle is filled with primary color and shows the step number; label text is bold; connecting line to previous step is solid",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "User is currently on this step — associated content is displayed",
+    },
+    {
+      state: "Upcoming",
+      visualChange: "Step circle has a muted border with step number in subdued text; connecting line is dashed or muted",
+      opacity: "0.6",
+      cursorWeb: "default",
+      usage: "Step has not yet been reached — not interactive unless clickable is enabled",
+    },
+    {
+      state: "Error",
+      visualChange: "Step circle shows an error/warning icon with red/danger fill; label text turns to error color",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Step was visited but has validation errors that need resolution before proceeding",
+    },
+    {
+      state: "Disabled",
+      visualChange: "Step circle and label are fully muted; connecting lines remain visible but desaturated",
+      opacity: "0.4",
+      cursorWeb: "not-allowed",
+      usage: "Step is not available in the current workflow context — skipped or conditionally hidden",
+    },
+    {
+      state: "Hover (Clickable)",
+      visualChange: "Step circle gains a subtle background tint; cursor changes to pointer indicating interactivity",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Mouse enters a clickable completed or upcoming step",
+    },
+  ],
+
+  propertyDescriptions: {
+    steps: "Array of step objects, each containing a label, optional description, optional icon, and status override",
+    activeStep: "Zero-based index of the currently active step — controls which step content is displayed",
+    orientation: "Layout direction — 'horizontal' for wide layouts or 'vertical' for narrow/sidebar layouts",
+    type: "Step indicator style — 'numbered' shows step indices (1, 2, 3) or 'icon' shows custom icons per step",
+    clickable: "When true, completed steps are interactive and allow users to navigate back to previous steps",
+    onChange: "Callback invoked with the step index when a user clicks a completed step (requires clickable to be true)",
+    size: "Dimensional preset — Small, Medium, or Large — controlling circle size, font size, and connector dimensions",
+    linear: "When true, users can only proceed to the next step sequentially; skipping ahead is not allowed",
+  },
+
+  sizeSpecifications: [
+    {
+      size: "Small",
+      height: "24px (circle)",
+      paddingLR: "8px",
+      fontSize: "12px",
+      iconSize: "14px",
+      borderRadius: "50%",
+    },
+    {
+      size: "Medium",
+      height: "32px (circle)",
+      paddingLR: "12px",
+      fontSize: "14px",
+      iconSize: "16px",
+      borderRadius: "50%",
+    },
+    {
+      size: "Large",
+      height: "40px (circle)",
+      paddingLR: "16px",
+      fontSize: "16px",
+      iconSize: "20px",
+      borderRadius: "50%",
+    },
+  ],
+
+  designTokenBindings: [
+    {
+      property: "Active Circle",
+      tokenName: "$stepper-active-bg",
+      role: "Background fill for the current step circle",
+      fallback: "#2563EB",
+    },
+    {
+      property: "Active Text",
+      tokenName: "$stepper-active-text",
+      role: "Text/number color inside the active step circle",
+      fallback: "#FFFFFF",
+    },
+    {
+      property: "Completed Circle",
+      tokenName: "$stepper-completed-bg",
+      role: "Background fill for completed step circles",
+      fallback: "#12B76A",
+    },
+    {
+      property: "Completed Icon",
+      tokenName: "$stepper-completed-icon",
+      role: "Checkmark icon color inside completed circles",
+      fallback: "#FFFFFF",
+    },
+    {
+      property: "Upcoming Circle Border",
+      tokenName: "$stepper-upcoming-border",
+      role: "Border color for unvisited step circles",
+      fallback: "#D0D5DD",
+    },
+    {
+      property: "Upcoming Text",
+      tokenName: "$stepper-upcoming-text",
+      role: "Number/icon color inside upcoming step circles",
+      fallback: "#98A2B3",
+    },
+    {
+      property: "Error Circle",
+      tokenName: "$stepper-error-bg",
+      role: "Background fill for error-state step circles",
+      fallback: "#F04438",
+    },
+    {
+      property: "Connector Line",
+      tokenName: "$stepper-connector",
+      role: "Color for the line connecting adjacent step circles",
+      fallback: "#E4E7EC",
+    },
+    {
+      property: "Connector Active",
+      tokenName: "$stepper-connector-active",
+      role: "Color for completed connector segments",
+      fallback: "#2563EB",
+    },
+    {
+      property: "Label Text",
+      tokenName: "$stepper-label-color",
+      role: "Text color for step labels below or beside the circles",
+      fallback: "#344054",
+    },
+    {
+      property: "Description Text",
+      tokenName: "$stepper-description-color",
+      role: "Muted text color for optional step descriptions",
+      fallback: "#667085",
+    },
+    {
+      property: "Focus Ring",
+      tokenName: "$focus-ring",
+      role: "Keyboard focus indicator around clickable step circles",
+      fallback: "0 0 0 2px #FFFFFF, 0 0 0 4px #2E90FA",
+    },
+  ],
+
+  structureRules: [
+    "Horizontal stepper uses a horizontal Auto Layout: circles connected by horizontal lines, labels below each circle",
+    "Vertical stepper uses a vertical Auto Layout: circles connected by vertical lines, labels to the right of each circle",
+    "Step circle is always a perfect circle (equal width and height) with centered content (number or icon)",
+    "Connector lines span between adjacent circles — they do not overlap the circles themselves",
+    "Labels are positioned directly below (horizontal) or to the right (vertical) of each step circle",
+    "Optional descriptions appear below the label in a smaller, muted font",
+    "The connector line between a completed step and the current step should be fully colored/solid",
+    "The connector line between the current step and an upcoming step should be dashed or muted",
+    "Minimum spacing between step circles is 80px (horizontal) or 48px (vertical) for readability",
+  ],
+
+  typeHierarchyRules: [
+    "Step labels use Medium weight (500) for upcoming steps and SemiBold (600) for the current step",
+    "Step descriptions use Regular weight (400) at one size smaller than the label (e.g. 12px when label is 14px)",
+    "Step numbers inside circles use SemiBold (600) centered both vertically and horizontally",
+    "Labels use sentence case — 'Payment details', not 'Payment Details' or 'PAYMENT DETAILS'",
+    "Labels should be single-line; truncate with ellipsis for horizontal steppers if text is too long",
+  ],
+
+  interactionRules: [
+    { event: "Click (Completed Step)", trigger: "Click/tap on a completed step circle or label", action: "If clickable, navigate to that step; fire onChange with the step index" },
+    { event: "Click (Upcoming Step)", trigger: "Click/tap on an upcoming step", action: "If clickable and not linear, navigate forward; if linear, no action (step is locked)" },
+    { event: "Hover", trigger: "Pointer enters a clickable step circle", action: "Circle gains hover tint; cursor changes to pointer" },
+    { event: "Focus", trigger: "Tab key reaches a clickable step", action: "Focus ring appears around the step circle; does not change the active step" },
+    { event: "Enter / Space", trigger: "Enter or Space pressed on a focused clickable step", action: "Navigate to that step; fire onChange" },
+    { event: "Next Step", trigger: "Programmatic advancement (e.g. form submission)", action: "Active step advances to the next index; previous step transitions to completed" },
+    { event: "Error Set", trigger: "Validation failure on the current step", action: "Current step circle transitions to error state; user must resolve before advancing" },
+  ],
+
+  contentGuidance: [
+    "Use 2-7 steps — fewer than 2 does not warrant a stepper; more than 7 is overwhelming",
+    "Step labels should be concise noun phrases: 'Shipping', 'Payment', 'Review' — not sentences",
+    "Use descriptions only when the label alone is insufficient to explain the step",
+    "Completed steps should use checkmarks, not the original step number, to reinforce progress",
+    "Error steps should clearly indicate what needs attention — pair with inline form validation",
+    "Consider showing a progress summary (e.g. 'Step 2 of 5') alongside the stepper for screen readers",
+    "For long workflows (7+ steps), consider grouping steps into phases with sub-steppers",
+  ],
+
+  responsiveBehaviour: [
+    { breakpoint: "Mobile (<768px)", behavior: "Switch from horizontal to vertical orientation; or show only current step with prev/next navigation" },
+    { breakpoint: "Tablet (768-1023px)", behavior: "Horizontal orientation with compressed label widths; descriptions may be hidden" },
+    { breakpoint: "Desktop (1024-1439px)", behavior: "Full horizontal layout with labels and descriptions visible; comfortable spacing" },
+    { breakpoint: "Ultra-wide (>=1440px)", behavior: "Stepper width remains capped at container max-width; does not stretch to fill ultra-wide viewports" },
+  ],
+
+  accessibilitySpec: {
+    intro:
+      "Steppers convey sequential progress and optionally allow navigation. Proper semantic structure ensures screen reader users understand their position in the workflow and can navigate between completed steps.",
+    requirements: [
+      { requirement: "List Semantics", level: "A", notes: "Use an ordered list (role='list' with role='listitem' children) to convey sequential order" },
+      { requirement: "Current Step", level: "A", notes: "Mark the active step with aria-current='step' so screen readers announce it as the current position" },
+      { requirement: "Step Labels", level: "A", notes: "Each step must have a visible text label or aria-label; icon-only steps are not sufficient" },
+      { requirement: "Completed Announcement", level: "A", notes: "Completed steps should include visually hidden text 'Completed' or use aria-label='Step 1: Shipping (completed)'" },
+      { requirement: "Error Announcement", level: "A", notes: "Error steps should include visually hidden text 'Error' or use aria-label conveying the error state" },
+      { requirement: "Clickable Steps", level: "A", notes: "Clickable steps must be keyboard-focusable (button or link element) with Enter/Space activation" },
+      { requirement: "Contrast", level: "AA", notes: "Step numbers, labels, and connector lines must meet 4.5:1 text contrast and 3:1 non-text contrast" },
+      { requirement: "Progress Announcement", level: "AA", notes: "When the active step changes, announce the new step via aria-live='polite' region" },
+    ],
+    outro: [
+      "Test with screen readers to verify step position (e.g. '2 of 5'), completion status, and error status are announced",
+      "Ensure that non-clickable upcoming steps are not focusable via keyboard",
+      "Provide a text-based progress indicator (e.g. 'Step 2 of 5') for users who may not perceive the visual stepper",
+    ],
+  },
+
+  qaAcceptanceCriteria: [
+    { check: "Step States", platform: "All", expectedResult: "Completed, Current, Upcoming, and Error states render with correct visual treatment" },
+    { check: "Connector Lines", platform: "All", expectedResult: "Completed connectors are solid/colored; upcoming connectors are dashed/muted" },
+    { check: "Click Navigation", platform: "Web", expectedResult: "Clicking a completed step navigates back; fires onChange with correct index" },
+    { check: "Linear Mode", platform: "Web", expectedResult: "Upcoming steps are not clickable in linear mode; only back-navigation to completed steps works" },
+    { check: "Horizontal Layout", platform: "All", expectedResult: "Steps are evenly spaced horizontally with centered labels below circles" },
+    { check: "Vertical Layout", platform: "All", expectedResult: "Steps stack vertically with labels to the right; connector lines are vertical" },
+    { check: "Error State", platform: "All", expectedResult: "Error step shows danger icon/color; label text changes to error color" },
+    { check: "Keyboard Navigation", platform: "Web", expectedResult: "Tab reaches clickable steps; Enter/Space activates; non-clickable steps are skipped" },
+    { check: "Screen Reader", platform: "Web", expectedResult: "Announces ordered list, step label, position, and completion/error status" },
+    { check: "Responsive", platform: "Mobile", expectedResult: "Switches to vertical layout or condensed view on narrow viewports" },
+    { check: "Contrast", platform: "All", expectedResult: "All step states pass 4.5:1 text contrast and 3:1 non-text contrast" },
+    { check: "RTL Support", platform: "Web", expectedResult: "Horizontal step order reverses; connectors flow right-to-left; labels align correctly" },
+    { check: "Icon Type", platform: "All", expectedResult: "Custom icons render correctly inside step circles; maintain consistent sizing" },
+  ],
+
+  dos: [
+    "Use steppers for workflows with 2-7 sequential steps that must be completed in order",
+    "Always show a clear visual distinction between completed, current, and upcoming steps",
+    "Use checkmarks for completed steps to reinforce a sense of progress",
+    "Provide a summary of the overall progress (e.g. 'Step 2 of 5') for screen readers",
+    "Allow back-navigation to completed steps when users need to edit previous responses",
+    "Use vertical orientation on narrow viewports or sidebar contexts",
+    "Pair error states with specific validation messages so users know what to fix",
+  ],
+
+  donts: [
+    "Do not use steppers for non-sequential content — use tabs or an accordion instead",
+    "Do not use more than 7 steps in a single stepper — group into phases if needed",
+    "Do not allow forward navigation to upcoming steps in linear workflows",
+    "Do not use steppers for single-step processes — a progress bar is more appropriate",
+    "Do not hide step labels on desktop viewports — labels are essential for understanding",
+    "Do not use only color to distinguish step states — combine color with icons and text",
+    "Do not skip the error state — always surface validation failures at the step level",
+  ],
+};

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

@@ -0,0 +1,244 @@
+/**
+ * table.ts — Gold-standard design knowledge for Data Table / Data Grid components
+ */
+import type { ComponentKnowledge } from "../types.js";
+
+export const tableKnowledge: ComponentKnowledge = {
+  description:
+    "Tabular data display | Sortable data grid | Structured information matrix",
+
+  stateSpecifications: [
+    {
+      state: "Default",
+      visualChange: "Header row with column titles; body rows with cell data; alternating row colors optional",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Standard table displaying structured data",
+    },
+    {
+      state: "Row Hover",
+      visualChange: "Hovered row background shifts to a subtle highlight color",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "Cursor enters a data row — indicates interactivity if rows are clickable",
+    },
+    {
+      state: "Row Selected",
+      visualChange: "Row background uses selection highlight color; checkbox in first column is checked",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "One or more rows are selected via checkbox or row click",
+    },
+    {
+      state: "Column Sorted",
+      visualChange: "Active sort column header shows ascending/descending arrow icon; other sort icons become subtle",
+      opacity: "1",
+      cursorWeb: "pointer",
+      usage: "User clicked a sortable column header to reorder data",
+    },
+    {
+      state: "Loading",
+      visualChange: "Skeleton rows replace data content; header remains visible",
+      opacity: "0.7",
+      cursorWeb: "default",
+      usage: "Data is being fetched from an API or reloaded after a filter change",
+    },
+    {
+      state: "Empty",
+      visualChange: "Table body replaced by a centered empty-state illustration with descriptive message",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "No data matches the current filters or the dataset is genuinely empty",
+    },
+    {
+      state: "Error",
+      visualChange: "Table body replaced by an error message with a retry action",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Data fetch failed due to a network or server error",
+    },
+  ],
+
+  propertyDescriptions: {
+    columns: "Array of column definitions specifying key, header label, width, sortable flag, and alignment",
+    data: "Array of row objects keyed to column definitions; each row renders one table row",
+    selectable: "When true, a checkbox column is prepended to enable single or multi-row selection",
+    sortable: "When true, column headers become clickable to sort ascending/descending",
+    pagination: "Pagination config — page size, current page, total count — renders a footer pagination bar",
+    stickyHeader: "When true, the header row remains fixed at the top during vertical scrolling",
+    zebraStriping: "When true, alternating rows use a subtle background color for improved scanability",
+  },
+
+  sizeSpecifications: [
+    {
+      size: "Compact",
+      height: "32px",
+      paddingLR: "8px",
+      fontSize: "12px",
+      iconSize: "14px",
+      borderRadius: "0px",
+    },
+    {
+      size: "Default",
+      height: "48px",
+      paddingLR: "16px",
+      fontSize: "14px",
+      iconSize: "16px",
+      borderRadius: "0px",
+    },
+    {
+      size: "Comfortable",
+      height: "56px",
+      paddingLR: "16px",
+      fontSize: "14px",
+      iconSize: "18px",
+      borderRadius: "0px",
+    },
+    {
+      size: "Tall",
+      height: "64px",
+      paddingLR: "20px",
+      fontSize: "14px",
+      iconSize: "20px",
+      borderRadius: "0px",
+    },
+  ],
+
+  designTokenBindings: [
+    {
+      property: "Header Background",
+      tokenName: "$table-header-bg",
+      role: "Background fill for the header row",
+      fallback: "#F9FAFB",
+    },
+    {
+      property: "Row Background",
+      tokenName: "$table-row-bg",
+      role: "Default row background color",
+      fallback: "#FFFFFF",
+    },
+    {
+      property: "Row Stripe",
+      tokenName: "$table-row-stripe",
+      role: "Alternating row background for zebra striping",
+      fallback: "#F9FAFB",
+    },
+    {
+      property: "Row Hover",
+      tokenName: "$table-row-hover",
+      role: "Background color on row hover",
+      fallback: "#F3F4F6",
+    },
+    {
+      property: "Row Selected",
+      tokenName: "$table-row-selected",
+      role: "Background color for selected rows",
+      fallback: "#EFF6FF",
+    },
+    {
+      property: "Border",
+      tokenName: "$table-border",
+      role: "Horizontal divider between rows and table outer border",
+      fallback: "#E5E7EB",
+    },
+    {
+      property: "Header Text",
+      tokenName: "$table-header-text",
+      role: "Column header label color — slightly muted for hierarchy",
+      fallback: "#6B7280",
+    },
+  ],
+
+  structureRules: [
+    "Table uses a semantic <table> element (or role='table') with <thead>, <tbody>, and optional <tfoot>",
+    "Each column header cell uses <th scope='col'> for correct screen reader association",
+    "Checkbox column is the first column with a fixed width of 48px and center alignment",
+    "Sticky header uses position sticky with z-index to remain above scrolling body rows",
+    "Column widths support fixed px, percentage, and flex (fr) sizing modes",
+    "Pagination footer is outside the scrollable area and remains fixed at the bottom",
+    "Sort icons are inline with header text — ascending arrow up, descending arrow down",
+  ],
+
+  typeHierarchyRules: [
+    "Header text uses Semi-Bold (600) weight and uppercase or sentence case depending on design system convention",
+    "Body cell text uses Regular (400) weight for data readability",
+    "Numeric cells use tabular (monospace) figures for proper column alignment",
+    "Truncated cell text shows an ellipsis with a tooltip revealing the full content on hover",
+    "Font size is consistent across all cells — do not vary size per column",
+  ],
+
+  interactionRules: [
+    { event: "Header Click", trigger: "pointerup on sortable column header", action: "Toggle sort direction (none → asc → desc → none); fire onSort callback" },
+    { event: "Row Click", trigger: "pointerup on a data row", action: "Fire onRowClick handler; optionally toggle row selection" },
+    { event: "Checkbox Click", trigger: "pointerup on row checkbox", action: "Toggle row selection; update header checkbox (all/some/none) indeterminate state" },
+    { event: "Select All", trigger: "pointerup on header checkbox", action: "Select or deselect all visible rows; fire onSelectionChange callback" },
+    { event: "Pagination", trigger: "Click page number or next/prev button", action: "Load and display the requested page of data" },
+    { event: "Column Resize", trigger: "Drag column border handle", action: "Resize the column width; adjacent column adjusts to maintain table width" },
+    { event: "Keyboard Navigation", trigger: "Arrow keys while table is focused", action: "Move focus between cells; Enter activates the focused cell or row action" },
+  ],
+
+  contentGuidance: [
+    "Column headers should be concise nouns or short noun phrases — 'Status', 'Created Date', 'Amount'",
+    "Right-align numeric and currency columns for easy comparison and scanning",
+    "Left-align text columns; center-align icon or status columns",
+    "Show the most important columns first (left-to-right) as right columns may be off-screen on narrow viewports",
+    "Empty cells should display a dash (—) or 'N/A' rather than being left blank",
+    "Include a visible row count and pagination summary (e.g. 'Showing 1-10 of 247 results')",
+  ],
+
+  responsiveBehaviour: [
+    { breakpoint: "Mobile (<768px)", behavior: "Table becomes horizontally scrollable in a container; or switches to a stacked card layout per row" },
+    { breakpoint: "Tablet (768-1023px)", behavior: "Hide low-priority columns; show a 'More' menu per row for hidden data" },
+    { breakpoint: "Desktop (1024-1439px)", behavior: "Full table with all columns visible; horizontal scroll only if columns exceed viewport" },
+    { breakpoint: "Ultra-wide (>=1440px)", behavior: "Table may expand to fill available width; column widths scale proportionally" },
+    { breakpoint: "Print", behavior: "Remove sticky header; show all pages; hide interactive elements (checkboxes, sort icons)" },
+  ],
+
+  accessibilitySpec: {
+    intro:
+      "Data tables must use semantic HTML and ARIA attributes to ensure screen readers can navigate cells, rows, and columns effectively.",
+    requirements: [
+      { requirement: "Semantic Structure", level: "A", notes: "Use <table>, <thead>, <tbody>, <th scope='col'>, and <td> — or equivalent ARIA roles" },
+      { requirement: "Caption", level: "A", notes: "Provide a <caption> or aria-label on the table describing its purpose" },
+      { requirement: "Sort Announcement", level: "A", notes: "Active sort column uses aria-sort='ascending' or 'descending' on the <th>" },
+      { requirement: "Row Selection", level: "A", notes: "Checkbox inputs have aria-label describing the row they select; header checkbox is labeled 'Select all'" },
+      { requirement: "Keyboard Navigation", level: "AA", notes: "Arrow keys navigate between cells; Tab moves between interactive elements within cells" },
+      { requirement: "Contrast", level: "AA", notes: "Text-to-background: 4.5:1; row borders and selection indicators: 3:1 non-text contrast" },
+      { requirement: "Focus Management", level: "AA", notes: "Focus remains on the correct cell after sort or pagination changes" },
+    ],
+    outro: [
+      "Announce pagination changes to screen readers via an aria-live polite region",
+      "Provide a skip link or keyboard shortcut to jump past large tables",
+    ],
+  },
+
+  qaAcceptanceCriteria: [
+    { check: "Column Sorting", platform: "Web", expectedResult: "Click toggles sort direction; arrow icon updates; data reorders correctly" },
+    { check: "Row Selection", platform: "Web", expectedResult: "Checkbox toggles selection; header checkbox reflects all/some/none state" },
+    { check: "Pagination", platform: "Web", expectedResult: "Page navigation loads correct data slice; current page indicator updates" },
+    { check: "Sticky Header", platform: "Web", expectedResult: "Header remains visible during vertical scroll; no z-index overlap issues" },
+    { check: "Zebra Striping", platform: "All", expectedResult: "Alternating rows use correct background token; selection overrides stripe color" },
+    { check: "Empty State", platform: "All", expectedResult: "Empty illustration and message centered in table body when no data matches" },
+    { check: "Screen Reader", platform: "Web", expectedResult: "Announces table caption, column headers, sort state, and row count" },
+  ],
+
+  dos: [
+    "Use semantic table elements (<table>, <th>, <td>) for proper accessibility",
+    "Right-align numeric columns and left-align text columns consistently",
+    "Provide a clear empty state with guidance on how to populate the table",
+    "Include pagination for datasets larger than 25 rows to maintain performance",
+    "Use sticky headers for tables taller than the viewport",
+    "Show sort direction indicators on all sortable column headers",
+    "Include a 'Select All' checkbox in the header when row selection is enabled",
+  ],
+
+  donts: [
+    "Do not use tables for layout purposes — tables are for tabular data only",
+    "Do not hide the header row — it provides essential context for the data",
+    "Do not allow horizontal scrolling without a visual scroll indicator",
+    "Do not use inconsistent row heights within the same table",
+    "Do not paginate with fewer than 10 items per page — it creates excessive navigation",
+    "Do not sort on columns with non-comparable data (e.g. action buttons)",
+    "Do not remove row hover highlights — they help users track across wide tables",
+  ],
+};