@sarjallab09/figma-intelligence 1.1.0 → 1.2.0

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

@@ -1,221 +0,0 @@
-/**
- * figma_component_spec — Unified component specification generator
- *
- * Replaces both figma_generate_spec and figma_component_doc with a single,
- * modular tool that follows the uSpec pattern: deterministic data extraction
- * from real Figma components + AI-structured output. Content is never fabricated.
- */
-
-import { decisionLog } from "../../../shared/decision-log.js";
-
-// ─── Extractors ─────────────────────────────────────────────────────────────
-import { resolveTargetNodeId, captureSnapshot } from "./extractors/snapshot.js";
-import { extractAnatomy } from "./extractors/anatomy.js";
-import { extractProperties } from "./extractors/properties.js";
-import { extractStates } from "./extractors/states.js";
-import { extractSpacing } from "./extractors/spacing.js";
-import { extractColorTokens } from "./extractors/color-tokens.js";
-import { extractTypography } from "./extractors/typography.js";
-
-// ─── Component Detection ────────────────────────────────────────────────────
-import { detectComponentType } from "./component-detection.js";
-
-// ─── Knowledge Base ────────────────────────────────────────────────────────
-import { getComponentKnowledge } from "./knowledge/index.js";
-
-// ─── Section Builders ───────────────────────────────────────────────────────
-import { buildOverviewSection } from "./sections/overview.js";
-import { buildAnatomySection } from "./sections/anatomy.js";
-import { buildVariantsSection } from "./sections/variants.js";
-import { buildStatesSection } from "./sections/states.js";
-import { buildStateSpecsSection } from "./sections/state-specs.js";
-import { buildPropertiesSection } from "./sections/properties-api.js";
-import { buildSizeSpecsSection } from "./sections/size-specs.js";
-import { buildSpacingSection } from "./sections/spacing-structure.js";
-import { buildColorTokensSection } from "./sections/color-tokens.js";
-import { buildDesignTokensSection } from "./sections/design-tokens.js";
-import { buildTypographySection } from "./sections/typography.js";
-import { buildTypeHierarchySection } from "./sections/type-hierarchy.js";
-import { buildInteractionRulesSection } from "./sections/interaction-rules.js";
-import { buildContentGuidanceSection } from "./sections/content-guidance.js";
-import { buildResponsiveSection } from "./sections/responsive.js";
-import { buildAccessibilitySection } from "./sections/accessibility.js";
-import { buildQaCriteriaSection } from "./sections/qa-criteria.js";
-import { buildUsageSection } from "./sections/usage-guidelines.js";
-import { buildRelatedSection } from "./sections/related-components.js";
-
-// ─── Renderers ──────────────────────────────────────────────────────────────
-import { renderMarkdown } from "./renderers/markdown.js";
-import { renderVisualDoc } from "./renderers/visual-doc.js";
-import { renderJson } from "./renderers/json.js";
-
-// ─── Types ──────────────────────────────────────────────────────────────────
-import type {
-  ComponentSpecArgs,
-  ComponentSpecResult,
-  ComponentSpec,
-  ExtractionResult,
-  SpecSectionOutput,
-  SpecSection,
-  ALL_SECTIONS as AllSectionsType,
-} from "./types.js";
-import { ALL_SECTIONS } from "./types.js";
-
-// ─── Re-exports for apg-doc compatibility ───────────────────────────────────
-export { resolveTargetNodeId, captureSnapshot } from "./extractors/snapshot.js";
-export { createDocumentationPages, formatDocumentReport } from "./legacy-compat.js";
-export type {
-  NodeSnapshot,
-  SnapshotNode,
-  GeneratedDocumentSection,
-  GeneratedDocument,
-} from "./types.js";
-
-// ─── Section builder map ────────────────────────────────────────────────────
-
-type SectionBuilder = (data: ExtractionResult) => SpecSectionOutput | null;
-
-const SECTION_BUILDERS: Record<SpecSection, SectionBuilder> = {
-  overview: buildOverviewSection,
-  anatomy: buildAnatomySection,
-  variants: buildVariantsSection,
-  states: buildStatesSection,
-  "state-specs": buildStateSpecsSection,
-  properties: buildPropertiesSection,
-  "size-specs": buildSizeSpecsSection,
-  spacing: buildSpacingSection,
-  "color-tokens": buildColorTokensSection,
-  "design-tokens": buildDesignTokensSection,
-  typography: buildTypographySection,
-  "type-hierarchy": buildTypeHierarchySection,
-  "interaction-rules": buildInteractionRulesSection,
-  "content-guidance": buildContentGuidanceSection,
-  responsive: buildResponsiveSection,
-  accessibility: buildAccessibilitySection,
-  "qa-criteria": buildQaCriteriaSection,
-  usage: buildUsageSection,
-  related: buildRelatedSection,
-};
-
-// ─── Main Handler ───────────────────────────────────────────────────────────
-
-export async function componentSpecHandler(args: ComponentSpecArgs): Promise<ComponentSpecResult> {
-  // 1. Resolve target node
-  const nodeId = await resolveTargetNodeId(args);
-
-  // 2. Capture base snapshot
-  let snapshot;
-  try {
-    snapshot = await captureSnapshot(nodeId);
-  } catch (err) {
-    throw new Error(
-      `figma_component_spec: Could not read component data. Ensure Figma is open with the bridge plugin running. ` +
-      `Original error: ${err instanceof Error ? err.message : String(err)}`
-    );
-  }
-
-  // 3. Detect component type and load knowledge
-  const { type: componentType, guidance: typeGuidance } = detectComponentType(snapshot);
-  const knowledge = getComponentKnowledge(componentType);
-
-  // 4. Run all extractions — use allSettled so one failure doesn't crash the rest
-  const settled = await Promise.allSettled([
-    extractAnatomy(nodeId),
-    extractSpacing(nodeId),
-    extractColorTokens(nodeId),
-    extractTypography(nodeId),
-  ]);
-
-  const anatomyResult = settled[0].status === "fulfilled" ? settled[0].value : { elements: [] };
-  const spacingResult = settled[1].status === "fulfilled" ? settled[1].value : [];
-  const colorTokensResult = settled[2].status === "fulfilled" ? settled[2].value : [];
-  const typographyResult = settled[3].status === "fulfilled" ? settled[3].value : [];
-
-  const propertiesResult = extractProperties(snapshot);
-  const statesResult = extractStates(snapshot);
-
-  // 5. Assemble extraction result
-  const extraction: ExtractionResult = {
-    snapshot,
-    anatomy: anatomyResult,
-    properties: propertiesResult,
-    states: statesResult,
-    spacing: spacingResult,
-    colorTokens: colorTokensResult,
-    typography: typographyResult,
-    componentType,
-    typeGuidance,
-    knowledge,
-  };
-
-  // 6. Build requested sections
-  const requestedSections = args.sections || ALL_SECTIONS;
-  const sections: SpecSectionOutput[] = [];
-
-  for (const sectionId of requestedSections) {
-    const builder = SECTION_BUILDERS[sectionId];
-    if (!builder) continue;
-    const result = builder(extraction);
-    if (result) sections.push(result);
-  }
-
-  // 7. Assemble spec
-  const spec: ComponentSpec = {
-    componentName: snapshot.name,
-    description: knowledge.description,
-    nodeId: snapshot.id,
-    nodeType: snapshot.type,
-    componentType,
-    sections,
-    extraction,
-  };
-
-  // 8. Render outputs
-  let markdown: string | undefined;
-  let figmaPageId: string | undefined;
-  const warnings: string[] = [];
-
-  if (args.outputFormat === "markdown" || args.outputFormat === "all") {
-    markdown = renderMarkdown(spec);
-  }
-
-  if (args.outputFormat === "figma-page" || args.outputFormat === "all") {
-    try {
-      figmaPageId = await renderVisualDoc(spec, args.pageName);
-    } catch (err) {
-      const errMsg = err instanceof Error ? err.message : String(err);
-      warnings.push(`Figma page rendering failed: ${errMsg}`);
-      // Still return markdown so the user gets something useful
-      if (!markdown) {
-        markdown = renderMarkdown(spec);
-      }
-    }
-  }
-
-  // 9. Log decision
-  const logEntry = await decisionLog.log({
-    tool: "figma_component_spec",
-    nodeIds: figmaPageId ? [snapshot.id, figmaPageId] : [snapshot.id],
-    rationale: `Generated component spec for ${snapshot.name} (${snapshot.type}). Type: ${componentType || "unknown"}. Sections: ${sections.length}. Variants: ${propertiesResult.variantAxes.length}. States: ${statesResult.states.length}.${warnings.length > 0 ? ` Warnings: ${warnings.join("; ")}` : ""}`,
-    tokens: snapshot.tokenAliases,
-    reversible: true,
-    metadata: {
-      outputFormat: args.outputFormat,
-      componentType,
-      sectionCount: sections.length,
-      variantAxisCount: propertiesResult.variantAxes.length,
-      stateCount: statesResult.states.length,
-    },
-  });
-
-  // Transform spec to structured JSON format for output
-  const jsonSpec = renderJson(spec) as ComponentSpec & { component: string; description: string; sections: Record<string, unknown> };
-
-  return {
-    spec: jsonSpec,
-    markdown,
-    figmaPageId,
-    logEntryId: logEntry.id,
-    warnings: warnings.length > 0 ? warnings : undefined,
-  };
-}

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

@@ -1,166 +0,0 @@
-/**
- * _default.ts — Fallback knowledge for unknown/unrecognized component types
- */
-import type { ComponentKnowledge } from "../types.js";
-
-export const defaultKnowledge: ComponentKnowledge = {
-  description:
-    "UI component | Reusable interface element | Design system building block",
-
-  stateSpecifications: [
-    {
-      state: "Default",
-      visualChange: "Base appearance with standard styling",
-      opacity: "1",
-      cursorWeb: "default",
-      usage: "Resting state when no interaction is occurring",
-    },
-    {
-      state: "Hover",
-      visualChange: "Subtle visual emphasis to indicate interactivity",
-      opacity: "1",
-      cursorWeb: "pointer",
-      usage: "Mouse cursor enters the interactive area",
-    },
-    {
-      state: "Disabled",
-      visualChange: "Reduced contrast, muted colors",
-      opacity: "0.4",
-      cursorWeb: "not-allowed",
-      usage: "Component is non-interactive due to current context",
-    },
-    {
-      state: "Focus",
-      visualChange: "Visible focus ring or outline",
-      opacity: "1",
-      cursorWeb: "default",
-      usage: "Component receives keyboard focus",
-    },
-  ],
-
-  propertyDescriptions: {
-    disabled:
-      "When true the component is non-interactive and visually muted",
-    children: "Content rendered inside the component",
-  },
-
-  sizeSpecifications: [
-    {
-      size: "Small",
-      height: "32px",
-      paddingLR: "8px",
-      fontSize: "12px",
-      iconSize: "16px",
-      borderRadius: "4px",
-    },
-    {
-      size: "Medium",
-      height: "40px",
-      paddingLR: "12px",
-      fontSize: "14px",
-      iconSize: "20px",
-      borderRadius: "6px",
-    },
-    {
-      size: "Large",
-      height: "48px",
-      paddingLR: "16px",
-      fontSize: "16px",
-      iconSize: "24px",
-      borderRadius: "8px",
-    },
-  ],
-
-  designTokenBindings: [
-    {
-      property: "Background",
-      tokenName: "$surface-default",
-      role: "Component background fill",
-      fallback: "#FFFFFF",
-    },
-    {
-      property: "Border",
-      tokenName: "$border-default",
-      role: "Component border color",
-      fallback: "#D0D5DD",
-    },
-    {
-      property: "Text Color",
-      tokenName: "$text-primary",
-      role: "Primary text content",
-      fallback: "#101828",
-    },
-    {
-      property: "Focus Ring",
-      tokenName: "$focus-ring",
-      role: "Visible keyboard focus indicator",
-      fallback: "0 0 0 2px #2E90FA",
-    },
-  ],
-
-  structureRules: [
-    "Use Auto Layout for all internal arrangement",
-    "Respect consistent padding and spacing tokens",
-    "Ensure minimum 44x44px touch target on interactive elements",
-    "Keep the layer tree flat; avoid unnecessary nesting",
-  ],
-
-  typeHierarchyRules: [
-    "Use the design system's type scale — do not hard-code font sizes",
-    "Maintain consistent line-height across label text",
-    "Sentence case for UI labels unless the system specifies otherwise",
-  ],
-
-  interactionRules: [
-    { event: "Click / Tap", trigger: "pointerdown + pointerup inside bounds", action: "Trigger primary action" },
-    { event: "Focus", trigger: "Tab key or programmatic focus", action: "Show focus indicator" },
-    { event: "Blur", trigger: "Focus leaves component", action: "Remove focus indicator" },
-  ],
-
-  contentGuidance: [
-    "Keep text labels concise and action-oriented where applicable",
-    "Use placeholder text sparingly — prefer visible labels",
-    "Ensure all decorative icons have empty alt text; meaningful icons need descriptive alt text",
-  ],
-
-  responsiveBehaviour: [
-    { breakpoint: "Mobile (<768px)", behavior: "Stack elements vertically; increase touch targets" },
-    { breakpoint: "Desktop (>=1024px)", behavior: "Use standard sizing and horizontal layouts" },
-  ],
-
-  accessibilitySpec: {
-    intro:
-      "All components must meet WCAG 2.1 AA. Verify keyboard access, screen reader announcements, and color contrast.",
-    requirements: [
-      { requirement: "Focusable", level: "A", notes: "Must be reachable via Tab key when interactive" },
-      { requirement: "Contrast Ratio", level: "AA", notes: "Text: 4.5:1 minimum; large text and UI controls: 3:1" },
-      { requirement: "Screen Reader", level: "A", notes: "Announce role, name, and state to assistive technology" },
-    ],
-    outro: [
-      "Test with at least one screen reader (VoiceOver, NVDA, or JAWS)",
-      "Never rely on color alone to convey meaning",
-    ],
-  },
-
-  qaAcceptanceCriteria: [
-    { check: "Visual Regression", platform: "All", expectedResult: "No unintended visual changes from baseline" },
-    { check: "Keyboard Navigation", platform: "Web", expectedResult: "All interactive elements reachable and operable via keyboard" },
-    { check: "Screen Reader", platform: "Web", expectedResult: "Role, name, and state announced correctly" },
-    { check: "Disabled State", platform: "All", expectedResult: "Non-interactive appearance; no event firing" },
-    { check: "Contrast", platform: "All", expectedResult: "Meets WCAG AA contrast ratios" },
-  ],
-
-  dos: [
-    "Follow the design system's spacing and color tokens",
-    "Provide visible focus indicators for keyboard users",
-    "Test across supported breakpoints",
-    "Use semantic HTML elements where possible",
-  ],
-
-  donts: [
-    "Do not override token values with hard-coded colors",
-    "Do not remove focus outlines without providing an alternative",
-    "Do not rely solely on hover states for critical information",
-    "Do not nest interactive elements inside other interactive elements",
-  ],
-};

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

@@ -1,232 +0,0 @@
-/**
- * accordion.ts — Gold-standard design knowledge for Accordion components
- */
-import type { ComponentKnowledge } from "../types.js";
-
-export const accordionKnowledge: ComponentKnowledge = {
-  description:
-    "Expandable content panel | Progressive disclosure control | Collapsible section container",
-
-  stateSpecifications: [
-    {
-      state: "Collapsed",
-      visualChange: "Header visible with chevron pointing right/down; content panel height is 0 with overflow hidden",
-      opacity: "1",
-      cursorWeb: "pointer",
-      usage: "Default resting state — content is hidden to reduce cognitive load",
-    },
-    {
-      state: "Expanded",
-      visualChange: "Chevron rotates 90° (or 180°); content panel animates to full intrinsic height",
-      opacity: "1",
-      cursorWeb: "pointer",
-      usage: "User has activated the header to reveal the section content",
-    },
-    {
-      state: "Hover",
-      visualChange: "Header background shifts to hover token; chevron may gain subtle color change",
-      opacity: "1",
-      cursorWeb: "pointer",
-      usage: "Mouse cursor enters the clickable header region",
-    },
-    {
-      state: "Focus",
-      visualChange: "2px focus ring around the header trigger element, offset by 2px",
-      opacity: "1",
-      cursorWeb: "pointer",
-      usage: "Header receives keyboard focus via Tab key navigation",
-    },
-    {
-      state: "Disabled",
-      visualChange: "Header text and chevron switch to muted tokens; no expand/collapse interaction",
-      opacity: "0.4",
-      cursorWeb: "not-allowed",
-      usage: "Section content is unavailable or irrelevant in the current context",
-    },
-    {
-      state: "Active",
-      visualChange: "Header background darkens momentarily on click/tap before expand animation begins",
-      opacity: "1",
-      cursorWeb: "pointer",
-      usage: "Mouse button is held down or touch press is in progress on the header",
-    },
-  ],
-
-  propertyDescriptions: {
-    title: "Visible heading text rendered in the accordion header; should clearly describe the hidden content",
-    expanded: "Boolean controlling whether the content panel is currently visible; supports controlled and uncontrolled modes",
-    disabled: "When true the header is non-interactive; content cannot be toggled open or closed",
-    allowMultiple: "When true, multiple panels can be open simultaneously; when false, opening one closes the others (exclusive mode)",
-    iconPosition: "Controls whether the expand/collapse chevron appears on the left or right side of the header",
-    size: "Dimensional preset controlling header height, padding, and font-size (Small, Medium, Large)",
-    onToggle: "Callback fired when the expanded state changes; receives the panel index and new expanded boolean",
-  },
-
-  sizeSpecifications: [
-    {
-      size: "Small",
-      height: "36px",
-      paddingLR: "12px",
-      fontSize: "13px",
-      iconSize: "16px",
-      borderRadius: "6px",
-    },
-    {
-      size: "Medium",
-      height: "48px",
-      paddingLR: "16px",
-      fontSize: "14px",
-      iconSize: "20px",
-      borderRadius: "8px",
-    },
-    {
-      size: "Large",
-      height: "56px",
-      paddingLR: "20px",
-      fontSize: "16px",
-      iconSize: "24px",
-      borderRadius: "10px",
-    },
-  ],
-
-  designTokenBindings: [
-    {
-      property: "Header Background",
-      tokenName: "$accordion-header-bg",
-      role: "Fill color for the clickable header region",
-      fallback: "#F9FAFB",
-    },
-    {
-      property: "Header Text",
-      tokenName: "$accordion-header-text",
-      role: "Title label color in the header",
-      fallback: "#101828",
-    },
-    {
-      property: "Chevron Color",
-      tokenName: "$accordion-icon-color",
-      role: "Fill/stroke color for the expand/collapse indicator icon",
-      fallback: "#667085",
-    },
-    {
-      property: "Border",
-      tokenName: "$accordion-border",
-      role: "Divider line between accordion items",
-      fallback: "#E4E7EC",
-    },
-    {
-      property: "Content Background",
-      tokenName: "$accordion-content-bg",
-      role: "Fill color for the expanded content region",
-      fallback: "#FFFFFF",
-    },
-    {
-      property: "Focus Ring",
-      tokenName: "$focus-ring",
-      role: "Keyboard focus indicator on the header trigger",
-      fallback: "0 0 0 2px #FFFFFF, 0 0 0 4px #2E90FA",
-    },
-    {
-      property: "Transition",
-      tokenName: "$transition-expand",
-      role: "Animation timing for expand/collapse height transition",
-      fallback: "250ms ease-in-out",
-    },
-  ],
-
-  structureRules: [
-    "Each accordion item consists of a header (trigger) and a content panel (region) as sibling elements",
-    "Header uses horizontal Auto Layout with space-between to position title and chevron",
-    "Content panel uses vertical Auto Layout; height animates between 0 and intrinsic height",
-    "Chevron icon rotates via CSS transform — no icon swap between states",
-    "Adjacent accordion items are separated by a 1px border using $accordion-border token",
-    "Content panel includes internal padding separate from the header padding for visual breathing room",
-    "The outer container clips overflow to prevent content from leaking during animation",
-  ],
-
-  typeHierarchyRules: [
-    "Header title uses font-weight Semi-Bold (600) to distinguish from body content",
-    "Content text uses Regular weight (400) and the body font-size one step smaller than the header",
-    "Title text uses sentence case — capitalize only the first word",
-    "Long titles truncate with ellipsis; never wrap to a second line in the header",
-    "Nested content may include any block-level elements (paragraphs, lists, images)",
-  ],
-
-  interactionRules: [
-    { event: "Click / Tap", trigger: "pointerup on header", action: "Toggle expanded state; fire onToggle callback" },
-    { event: "Hover", trigger: "pointerenter on header", action: "Transition header to hover background token" },
-    { event: "Focus", trigger: "Tab key to header", action: "Show focus ring on the header trigger element" },
-    { event: "Keydown Enter", trigger: "Enter key while header focused", action: "Toggle expanded state (same as click)" },
-    { event: "Keydown Space", trigger: "Space key while header focused", action: "Toggle expanded state; prevent page scroll" },
-    { event: "Arrow Down", trigger: "Down arrow while header focused", action: "Move focus to the next accordion header in the group" },
-    { event: "Arrow Up", trigger: "Up arrow while header focused", action: "Move focus to the previous accordion header in the group" },
-  ],
-
-  contentGuidance: [
-    "Header titles should be concise and descriptive — summarize the hidden content in 2-5 words",
-    "Content should be meaningful enough to justify hiding — avoid hiding single lines of text",
-    "Use accordions for progressive disclosure when content volume would overwhelm the page",
-    "Group related content into logical sections; each panel should cover one distinct topic",
-    "Avoid nesting accordions within accordions — use a flat hierarchy or a different pattern",
-    "Consider starting with one panel expanded if the content is frequently needed",
-  ],
-
-  responsiveBehaviour: [
-    { breakpoint: "Mobile (<768px)", behavior: "Accordion fills full width; header padding reduces to compact preset; touch target 48px min" },
-    { breakpoint: "Tablet (768-1023px)", behavior: "Accordion may span full width or sit within a card container; same interaction model" },
-    { breakpoint: "Desktop (1024-1439px)", behavior: "Accordion may be constrained to a max-width column; content area has generous padding" },
-    { breakpoint: "Ultra-wide (>=1440px)", behavior: "Max-width capped; accordion does not stretch beyond readable line length (~720px)" },
-  ],
-
-  accessibilitySpec: {
-    intro:
-      "Accordions rely on the disclosure pattern (heading + region) to be accessible. Proper ARIA roles and keyboard support are essential.",
-    requirements: [
-      { requirement: "Heading + Button", level: "A", notes: "Header must use a heading element wrapping a button; the button controls expand/collapse" },
-      { requirement: "aria-expanded", level: "A", notes: "The trigger button must have aria-expanded='true' when open and 'false' when closed" },
-      { requirement: "aria-controls", level: "A", notes: "The trigger button must reference the content panel ID via aria-controls" },
-      { requirement: "role='region'", level: "A", notes: "The content panel should have role='region' and aria-labelledby pointing to the header" },
-      { requirement: "Keyboard Navigation", level: "A", notes: "Enter and Space toggle; arrow keys move between headers in a group" },
-      { requirement: "Contrast", level: "AA", notes: "Header text must meet 4.5:1 contrast; chevron icon must meet 3:1 non-text contrast" },
-      { requirement: "Motion", level: "AAA", notes: "Expand/collapse animation must respect prefers-reduced-motion and collapse instantly when set" },
-    ],
-    outro: [
-      "Screen readers should announce the heading level, expanded state, and panel content when expanded",
-      "Focus must remain on the header trigger after toggling — never move focus into the content automatically",
-    ],
-  },
-
-  qaAcceptanceCriteria: [
-    { check: "Expand Animation", platform: "Web", expectedResult: "Content panel smoothly animates from 0 to full height within 250ms" },
-    { check: "Collapse Animation", platform: "Web", expectedResult: "Content panel smoothly animates to 0 height; no content flash or jump" },
-    { check: "Chevron Rotation", platform: "All", expectedResult: "Chevron rotates smoothly on toggle; points right when collapsed, down when expanded" },
-    { check: "Exclusive Mode", platform: "All", expectedResult: "When allowMultiple=false, opening one panel closes all others" },
-    { check: "Multi-Open Mode", platform: "All", expectedResult: "When allowMultiple=true, multiple panels can remain open simultaneously" },
-    { check: "Keyboard Navigation", platform: "Web", expectedResult: "Tab focuses header; Enter/Space toggles; Arrow keys move between headers" },
-    { check: "Screen Reader", platform: "Web", expectedResult: "Announces heading level, button role, expanded/collapsed state" },
-    { check: "Disabled Panel", platform: "All", expectedResult: "Header appears muted; click and keyboard have no effect; aria-disabled='true'" },
-    { check: "Reduced Motion", platform: "Web", expectedResult: "Animation disabled when prefers-reduced-motion: reduce is set" },
-    { check: "Overflow Content", platform: "Web", expectedResult: "Long content scrolls within panel or extends panel height without clipping" },
-    { check: "Focus Ring", platform: "Web", expectedResult: "Visible focus ring on header when navigated via keyboard" },
-  ],
-
-  dos: [
-    "Use accordions to organize lengthy content into scannable sections",
-    "Provide clear, descriptive header titles so users can find content without expanding",
-    "Allow multiple panels open when users need to compare content across sections",
-    "Use exclusive mode (single open) when context switching is acceptable and screen space is limited",
-    "Respect prefers-reduced-motion by disabling expand/collapse animation",
-    "Maintain consistent spacing between accordion items using design tokens",
-    "Include a visible border or separator between items for clear visual grouping",
-  ],
-
-  donts: [
-    "Do not nest accordions inside other accordions — flatten the hierarchy instead",
-    "Do not use accordions for only one or two items — use a simple disclosure or show the content directly",
-    "Do not hide critical actions or required form fields inside collapsed panels",
-    "Do not auto-collapse panels when the user scrolls — let the user control visibility",
-    "Do not use expand/collapse animations longer than 300ms — they feel sluggish",
-    "Do not override the chevron icon with unrelated iconography — keep the affordance clear",
-    "Do not remove focus indicators from the header trigger",
-  ],
-};