@sarjallab09/figma-intelligence 1.1.0 → 1.2.0

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

@@ -1,319 +0,0 @@
-/**
- * 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

@@ -1,121 +0,0 @@
-/**
- * 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;
-}