@sarjallab09/figma-intelligence 1.0.0

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

@@ -0,0 +1,319 @@
+/**
+ * typography.ts — Gold-standard design knowledge for Typography components
+ */
+import type { ComponentKnowledge } from "../types.js";
+
+export const typographyKnowledge: ComponentKnowledge = {
+  description:
+    "Text display component | Renders headings, body, labels, and captions | Semantic HTML mapping with full type scale support",
+
+  stateSpecifications: [
+    {
+      state: "Default",
+      visualChange: "Text rendered in the specified variant, size, weight, and color — no interactive feedback",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Standard resting state — typography is a non-interactive display component",
+    },
+    {
+      state: "Truncated",
+      visualChange: "Text is clipped with an ellipsis at the specified line count or max-width",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Content exceeds the available space; truncation is applied with CSS line-clamp or text-overflow",
+    },
+    {
+      state: "Skeleton",
+      visualChange: "Text content replaced by animated placeholder bars matching the expected line width and height",
+      opacity: "1",
+      cursorWeb: "default",
+      usage: "Content is loading — skeleton lines approximate the final text layout",
+    },
+  ],
+
+  propertyDescriptions: {
+    variant: "Typographic role — 'display' for hero text, 'heading' for section headers, 'body' for paragraphs, 'label' for form labels and UI chrome, 'caption' for small annotations and metadata",
+    size: "Scale step within the variant — maps to a specific font-size/line-height pair from the type scale (e.g. heading size 1-6, body size sm/md/lg)",
+    weight: "Font weight override — 'regular' (400), 'medium' (500), 'semibold' (600), 'bold' (700); defaults vary per variant",
+    color: "Text color token name or semantic color — 'primary', 'secondary', 'disabled', 'error', 'success', 'inverse', or a custom token",
+    align: "Text alignment — 'left' (default), 'center', 'right'; automatically mirrors in RTL contexts",
+    truncate: "Number of lines before truncation; 1 for single-line ellipsis, 2+ for multi-line clamp; 0 or undefined for no truncation",
+    as: "Semantic HTML element override — allows rendering as h1-h6, p, span, label, figcaption, etc. independent of visual variant",
+    italic: "When true, applies italic font style; useful for emphasis, citations, or placeholder text",
+    mono: "When true, switches to the monospace font family; useful for code snippets, numerical data, or technical content",
+  },
+
+  sizeSpecifications: [
+    {
+      size: "Display XL",
+      height: "auto",
+      paddingLR: "0px",
+      fontSize: "60px",
+      iconSize: "N/A",
+      borderRadius: "N/A",
+    },
+    {
+      size: "Display LG",
+      height: "auto",
+      paddingLR: "0px",
+      fontSize: "48px",
+      iconSize: "N/A",
+      borderRadius: "N/A",
+    },
+    {
+      size: "Heading 1",
+      height: "auto",
+      paddingLR: "0px",
+      fontSize: "36px",
+      iconSize: "N/A",
+      borderRadius: "N/A",
+    },
+    {
+      size: "Heading 2",
+      height: "auto",
+      paddingLR: "0px",
+      fontSize: "30px",
+      iconSize: "N/A",
+      borderRadius: "N/A",
+    },
+    {
+      size: "Heading 3",
+      height: "auto",
+      paddingLR: "0px",
+      fontSize: "24px",
+      iconSize: "N/A",
+      borderRadius: "N/A",
+    },
+    {
+      size: "Heading 4",
+      height: "auto",
+      paddingLR: "0px",
+      fontSize: "20px",
+      iconSize: "N/A",
+      borderRadius: "N/A",
+    },
+    {
+      size: "Body LG",
+      height: "auto",
+      paddingLR: "0px",
+      fontSize: "18px",
+      iconSize: "N/A",
+      borderRadius: "N/A",
+    },
+    {
+      size: "Body MD",
+      height: "auto",
+      paddingLR: "0px",
+      fontSize: "16px",
+      iconSize: "N/A",
+      borderRadius: "N/A",
+    },
+    {
+      size: "Body SM",
+      height: "auto",
+      paddingLR: "0px",
+      fontSize: "14px",
+      iconSize: "N/A",
+      borderRadius: "N/A",
+    },
+    {
+      size: "Label",
+      height: "auto",
+      paddingLR: "0px",
+      fontSize: "14px",
+      iconSize: "N/A",
+      borderRadius: "N/A",
+    },
+    {
+      size: "Caption",
+      height: "auto",
+      paddingLR: "0px",
+      fontSize: "12px",
+      iconSize: "N/A",
+      borderRadius: "N/A",
+    },
+  ],
+
+  designTokenBindings: [
+    {
+      property: "Display Font Family",
+      tokenName: "$font-family-display",
+      role: "Typeface for display variant; may differ from body for visual impact",
+      fallback: "Inter, system-ui, sans-serif",
+    },
+    {
+      property: "Heading Font Family",
+      tokenName: "$font-family-heading",
+      role: "Typeface for heading variant",
+      fallback: "Inter, system-ui, sans-serif",
+    },
+    {
+      property: "Body Font Family",
+      tokenName: "$font-family-sans",
+      role: "Typeface for body, label, and caption variants",
+      fallback: "Inter, system-ui, sans-serif",
+    },
+    {
+      property: "Mono Font Family",
+      tokenName: "$font-family-mono",
+      role: "Monospace typeface for code snippets and tabular data",
+      fallback: "'JetBrains Mono', 'Fira Code', monospace",
+    },
+    {
+      property: "Primary Color",
+      tokenName: "$text-primary",
+      role: "Default text color for headings and body content",
+      fallback: "#101828",
+    },
+    {
+      property: "Secondary Color",
+      tokenName: "$text-secondary",
+      role: "Subdued text color for captions, labels, and supporting text",
+      fallback: "#667085",
+    },
+    {
+      property: "Disabled Color",
+      tokenName: "$text-disabled",
+      role: "Muted text color for disabled or placeholder content",
+      fallback: "#98A2B3",
+    },
+    {
+      property: "Inverse Color",
+      tokenName: "$text-inverse",
+      role: "Light text for use on dark backgrounds",
+      fallback: "#FFFFFF",
+    },
+    {
+      property: "Display Line Height",
+      tokenName: "$line-height-display",
+      role: "Line height for display variant — tighter for large text",
+      fallback: "1.1",
+    },
+    {
+      property: "Heading Line Height",
+      tokenName: "$line-height-heading",
+      role: "Line height for heading variant",
+      fallback: "1.25",
+    },
+    {
+      property: "Body Line Height",
+      tokenName: "$line-height-body",
+      role: "Line height for body variant — comfortable reading",
+      fallback: "1.5",
+    },
+    {
+      property: "Letter Spacing Display",
+      tokenName: "$letter-spacing-display",
+      role: "Tighter tracking for large display text",
+      fallback: "-0.02em",
+    },
+    {
+      property: "Letter Spacing Body",
+      tokenName: "$letter-spacing-body",
+      role: "Default tracking for body text",
+      fallback: "0em",
+    },
+  ],
+
+  structureRules: [
+    "Typography component renders a single HTML text element — no wrapper divs unless the 'as' prop specifies a block element",
+    "The 'as' prop controls the rendered HTML element independently of the visual variant (e.g. variant='heading' with as='p')",
+    "When 'as' is not specified, the component infers the element from the variant: display/heading -> h1-h6, body -> p, label -> label, caption -> span",
+    "Truncation uses CSS -webkit-line-clamp for multi-line and text-overflow:ellipsis for single-line",
+    "Typography does not add margin by default — spacing is controlled by parent layout or spacing utilities",
+    "Inline elements (span, label) do not break to new lines unless the parent explicitly sets display:block",
+    "When mono=true, the font-family switches to the monospace token but all other properties remain unchanged",
+    "The component supports semantic nesting: headings inside sections, labels associated with inputs via htmlFor",
+  ],
+
+  typeHierarchyRules: [
+    "Display: weight 700 (Bold) by default, line-height $line-height-display (1.1), letter-spacing -0.02em",
+    "Heading: weight 600 (Semibold) by default, line-height $line-height-heading (1.25), letter-spacing -0.01em",
+    "Body: weight 400 (Regular) by default, line-height $line-height-body (1.5), letter-spacing 0em",
+    "Label: weight 500 (Medium) by default, line-height 1.4, letter-spacing 0.01em for legibility at small sizes",
+    "Caption: weight 400 (Regular) by default, line-height 1.4, letter-spacing 0.01em",
+    "Heading levels must follow a logical hierarchy — never skip levels (e.g. h1 to h3 without h2)",
+    "Only one h1 per page; use variant='heading' with appropriate size for sub-sections",
+    "Body text should never be smaller than 14px for readability; 16px is preferred for long-form content",
+  ],
+
+  interactionRules: [
+    { event: "Text Selection", trigger: "Click and drag over text content", action: "Native browser text selection applies; no custom behavior needed" },
+    { event: "Copy", trigger: "Ctrl/Cmd+C with text selected", action: "Selected text is copied to clipboard using native browser behavior" },
+    { event: "Truncation Hover", trigger: "pointerenter on truncated text", action: "Optional: show a tooltip with the full text content if truncation is active" },
+    { event: "Link Within Text", trigger: "Click on an inline link within body text", action: "Navigate to the link target — this is handled by nested anchor elements, not the typography component" },
+  ],
+
+  contentGuidance: [
+    "Use display variant for hero sections, landing pages, and marketing headlines — maximum 1-2 per page",
+    "Use heading variant for section titles and structural hierarchy; follow semantic h1-h6 ordering",
+    "Use body variant for paragraphs, descriptions, and long-form content; line-height should be 1.5 for readability",
+    "Use label variant for form field labels, UI chrome text, and interactive element descriptions",
+    "Use caption variant for metadata, timestamps, footnotes, and small supporting annotations",
+    "Maintain a consistent type scale across the application — do not create arbitrary font-size values",
+    "Prefer sentence case for headings ('Welcome to the dashboard') over title case unless brand guidelines specify otherwise",
+    "Ensure sufficient line length for body text: 45-75 characters per line is optimal for readability",
+  ],
+
+  responsiveBehaviour: [
+    { breakpoint: "Mobile (<768px)", behavior: "Display text scales down (60px -> 36px); heading sizes reduce by 1-2 steps; body remains at minimum 14px" },
+    { breakpoint: "Tablet (768-1023px)", behavior: "Display text at 75% of desktop; headings at ~85% of desktop; body sizes remain constant" },
+    { breakpoint: "Desktop (1024-1439px)", behavior: "Full type scale applied as specified; optimal reading conditions" },
+    { breakpoint: "Ultra-wide (>=1440px)", behavior: "Type sizes remain capped at desktop values; use max-width on text containers to maintain line length" },
+  ],
+
+  accessibilitySpec: {
+    intro:
+      "Typography is foundational to accessibility. Correct semantic markup, sufficient contrast, and proper heading hierarchy are essential for screen reader navigation and readability.",
+    requirements: [
+      { requirement: "Semantic Markup", level: "A", notes: "Headings must use h1-h6 elements (or role='heading' with aria-level); do not use div/span styled as headings" },
+      { requirement: "Heading Hierarchy", level: "A", notes: "Heading levels must be sequential and logical — never skip levels; one h1 per page" },
+      { requirement: "Contrast Ratio", level: "AA", notes: "Normal text (under 18px or under 14px bold): 4.5:1; large text (18px+ or 14px+ bold): 3:1" },
+      { requirement: "Text Resize", level: "AA", notes: "Text must be resizable up to 200% without loss of content or functionality (WCAG 1.4.4)" },
+      { requirement: "Text Spacing", level: "AA", notes: "Content must remain readable when line-height is increased to 1.5x, letter-spacing to 0.12em, word-spacing to 0.16em (WCAG 1.4.12)" },
+      { requirement: "Color Independence", level: "A", notes: "Do not use color alone to convey meaning — pair with icons, weight, or text labels" },
+      { requirement: "Language", level: "A", notes: "Specify the lang attribute on text in a different language than the page default" },
+    ],
+    outro: [
+      "Truncated text should have the full content available via title attribute or tooltip for both sighted users and assistive technology",
+      "Ensure text containers have sufficient padding and do not clip content when text spacing is adjusted",
+      "Test with browser zoom at 200% and 400% to verify text reflows correctly without horizontal scrolling",
+    ],
+  },
+
+  qaAcceptanceCriteria: [
+    { check: "Visual Regression", platform: "All", expectedResult: "Every variant/size/weight combination renders pixel-perfect against the type scale baseline" },
+    { check: "Semantic HTML", platform: "Web", expectedResult: "Display/heading renders as h1-h6; body as p; caption/label as appropriate elements; 'as' prop overrides correctly" },
+    { check: "Font Loading", platform: "Web", expectedResult: "Custom fonts load without FOIT (flash of invisible text); fallback fonts display during load" },
+    { check: "Truncation Single-line", platform: "All", expectedResult: "Text truncates with ellipsis when content exceeds container width; truncate=1" },
+    { check: "Truncation Multi-line", platform: "Web", expectedResult: "Text truncates at the specified line count using line-clamp; ellipsis appears on the last visible line" },
+    { check: "Responsive Scaling", platform: "Web", expectedResult: "Display and heading sizes scale down correctly at mobile breakpoints; body stays at minimum 14px" },
+    { check: "Contrast Ratio", platform: "All", expectedResult: "All color/variant combinations meet WCAG AA contrast requirements (4.5:1 normal, 3:1 large)" },
+    { check: "Text Resize 200%", platform: "Web", expectedResult: "All text readable at 200% browser zoom; no overflow or clipping" },
+    { check: "Text Spacing Override", platform: "Web", expectedResult: "Content readable with WCAG 1.4.12 text spacing adjustments applied" },
+    { check: "Mono Variant", platform: "All", expectedResult: "Monospace font applied; all metrics (size, weight, color) remain consistent with the selected variant" },
+    { check: "RTL Support", platform: "Web", expectedResult: "Text alignment mirrors correctly; direction:rtl applied; no layout breakage" },
+    { check: "Heading Hierarchy", platform: "Web", expectedResult: "Automated heading-level checker confirms no skipped levels on any page" },
+    { check: "Screen Reader", platform: "Web", expectedResult: "Headings announced with correct level; text content fully readable; truncated content accessible" },
+  ],
+
+  dos: [
+    "Use the type scale consistently — every text element should map to a defined variant/size combination",
+    "Maintain a clear visual hierarchy: display > heading > body > label > caption in size and weight",
+    "Use the 'as' prop to ensure semantic correctness even when visual presentation differs from default mapping",
+    "Set appropriate line-height for each variant: tighter for display/heading, looser for body/caption",
+    "Apply negative letter-spacing on display and large heading text for visual refinement",
+    "Use the secondary color token for supporting text to create clear primary/secondary visual hierarchy",
+    "Ensure body text containers have a max-width of 65-75ch for optimal reading line length",
+  ],
+
+  donts: [
+    "Do not create arbitrary font sizes outside the defined type scale — use variant/size combinations only",
+    "Do not use heading elements for visual styling alone — headings must represent document structure",
+    "Do not skip heading levels (h1 -> h3) — this breaks screen reader navigation",
+    "Do not set body text below 14px — 12px is only acceptable for caption and annotation text",
+    "Do not override font tokens with hard-coded font-family strings",
+    "Do not use color alone to convey meaning in text (e.g. red text for errors without an icon or label)",
+    "Do not disable text selection on body content — users expect to copy text from paragraphs",
+  ],
+};

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

@@ -0,0 +1,121 @@
+/**
+ * Legacy compatibility — functions needed by apg-doc that were in spec-generator
+ */
+import { getBridge } from "../../../shared/figma-bridge.js";
+import type { GeneratedDocument } from "./types.js";
+
+export function formatDocumentReport(document: GeneratedDocument): string {
+  const lines = [
+    document.title,
+    "",
+    document.summary,
+    "",
+  ];
+
+  for (const section of document.sections) {
+    lines.push(section.title);
+    for (const item of section.items) {
+      lines.push(section.style === "paragraph" ? item : `- ${item}`);
+    }
+    lines.push("");
+  }
+
+  return lines.join("\n").trim();
+}
+
+export async function createDocumentationPages(documents: GeneratedDocument[], pageName?: string): Promise<string> {
+  const bridge = await getBridge();
+  const result = await bridge.execute(`
+    (async () => {
+      const documents = ${JSON.stringify(documents)};
+      await figma.loadAllPagesAsync();
+      const resolvedPageName = ${JSON.stringify(pageName || "Generated Component Docs")};
+      const existing = figma.root.children.find((candidate) => candidate.name === resolvedPageName);
+      const page = existing || figma.createPage();
+      page.name = resolvedPageName;
+      await figma.setCurrentPageAsync(page);
+
+      for (const child of [...page.children]) {
+        child.remove();
+      }
+
+      await figma.loadFontAsync({ family: "Inter", style: "Bold" });
+      await figma.loadFontAsync({ family: "Inter", style: "Semi Bold" });
+      await figma.loadFontAsync({ family: "Inter", style: "Medium" });
+      await figma.loadFontAsync({ family: "Inter", style: "Regular" });
+
+      const colors = {
+        card: { r: 1, g: 1, b: 1 },
+        stroke: { r: 0.874, g: 0.874, b: 0.914 },
+        heading: { r: 0.121, g: 0.129, b: 0.259 },
+        body: { r: 0.188, g: 0.192, b: 0.224 },
+        muted: { r: 0.376, g: 0.376, b: 0.412 },
+      };
+
+      function makeText(value, size, style, color, width) {
+        const text = figma.createText();
+        text.fontName = { family: "Inter", style };
+        text.fontSize = size;
+        text.lineHeight = { unit: "PIXELS", value: size <= 14 ? 20 : size + 8 };
+        text.characters = value;
+        text.fills = [{ type: "SOLID", color }];
+        text.textAutoResize = width ? "HEIGHT" : "WIDTH_AND_HEIGHT";
+        if (width) {
+          text.resize(width, text.height);
+        }
+        return text;
+      }
+
+      function makeSection(section, width) {
+        const frame = figma.createFrame();
+        frame.layoutMode = "VERTICAL";
+        frame.primaryAxisSizingMode = "AUTO";
+        frame.counterAxisSizingMode = "AUTO";
+        frame.itemSpacing = 10;
+        frame.fills = [];
+        frame.appendChild(makeText(section.title, 18, "Semi Bold", colors.heading, width));
+        for (const item of section.items) {
+          const prefix = section.style === "paragraph" ? "" : "• ";
+          frame.appendChild(makeText(prefix + item, 14, "Regular", colors.body, width));
+        }
+        return frame;
+      }
+
+      let y = 40;
+      for (const document of documents) {
+        const card = figma.createFrame();
+        card.name = document.title;
+        card.layoutMode = "VERTICAL";
+        card.primaryAxisSizingMode = "AUTO";
+        card.counterAxisSizingMode = "AUTO";
+        card.itemSpacing = 20;
+        card.paddingTop = 28;
+        card.paddingRight = 28;
+        card.paddingBottom = 28;
+        card.paddingLeft = 28;
+        card.cornerRadius = 16;
+        card.strokes = [{ type: "SOLID", color: colors.stroke }];
+        card.fills = [{ type: "SOLID", color: colors.card }];
+        card.x = 40;
+        card.y = y;
+        card.resize(1006, 100);
+        card.appendChild(makeText(document.title, 28, "Semi Bold", colors.heading, 920));
+        card.appendChild(makeText(document.summary, 14, "Regular", colors.muted, 920));
+        for (const section of document.sections) {
+          card.appendChild(makeSection(section, 920));
+        }
+        page.appendChild(card);
+        y += Math.max(card.height, 240) + 32;
+      }
+
+      figma.viewport.scrollAndZoomIntoView(page.children);
+      return page.id;
+    })();
+  `);
+
+  if (!result.success) {
+    throw new Error(`createDocumentationPages: failed to create page: ${result.error}`);
+  }
+
+  return result.result as string;
+}