{
  "$schema": "https://ably.com/design/tokens/typography-tokens.schema.json",
  "_metadata": {
    "name": "Ably Typography Tokens",
    "description": "Core typography rules and definitions for Ably's brand and UI. Extracted from Figma SSOT: 01 — Styles.",
    "source": "https://www.figma.com/design/jTQgyIovrhGBOf4Zrvjvbk/01---Styles?node-id=118-1",
    "version": "1.0.0",
    "generated": "2026-02-16",
    "notes": {
      "colour_references": "Colour tokens (e.g. 'neutral-1300') reference values defined in colour-tokens.json.",
      "implementation_detail": "For detailed sizing, letter-spacing, line heights, responsive breakpoints, and CSS font stacks, see the property-specific scale files: references/typography-scale-marketing.json, references/typography-scale-docs.json, references/typography-scale-dashboard.json."
    }
  },

  "typeface": {
    "primary": {
      "family": "Manrope",
      "type": "sans-serif",
      "description": "Ably's primary typeface. A modern, open-source sans-serif used for everything from display headings to body copy. Geometric with optical adjustments for high legibility at all sizes.",
      "license": "SIL Open Font License"
    },
    "monospace": {
      "family": "JetBrains Mono",
      "description": "Used exclusively for code samples, technical content, and data displays.",
      "license": "SIL Open Font License"
    }
  },

  "weights": {
    "_description": "Four weights form a clear visual hierarchy. Don't use weights outside their defined roles without purpose.",
    "bold": {
      "value": 700,
      "role": "Titles, headlines, emphasis, display headings, brand moments"
    },
    "semibold": { "value": 600, "role": "Sub-heads, section labels" },
    "medium": { "value": 500, "role": "Body copy, default reading text" },
    "regular": { "value": 400, "role": "Quote texts, captions, supporting text" }
  },

  "hierarchy": {
    "_description": "How type styles map to content hierarchy. Size decreases down the hierarchy; weight distinguishes role within each level.",

    "display": {
      "role": "Page titles, hero headings, major brand moments",
      "weight": "bold",
      "sizes": "40–48px",
      "notes": "Letter-spacing should be tightened at display sizes — roughly -1% to -3% of the font size, increasing proportionally as size increases. At smaller heading sizes (h4, h5) the tightening is minimal or absent. Apply where the tool supports it; some tools (e.g. Google Slides) do not offer letter-spacing control — in those cases, leave at defaults."
    },
    "headings": {
      "role": "Section headings within a page (h1–h5)",
      "weight": "bold",
      "sizes": "16–40px",
      "notes": "Same letter-spacing principle as display — tightens progressively with size, tapering off at h4/h5. Apply where tooling supports it."
    },
    "subheads": {
      "role": "Section labels, decorative headers, category markers",
      "weight": "semibold",
      "size": "18px"
    },
    "body": {
      "role": "Running text, paragraphs, descriptions",
      "weight": "medium",
      "sizes": "15–16px",
      "notes": "Two sizes: p1 (16px, standard) and p2 (15px, compact). Each has a bold variant for inline emphasis."
    }
  },

  "rules": {
    "alignment": {
      "default": "left",
      "exceptions": "Centre-alignment is acceptable where intention and layout allow.",
      "rule": "Always left-align body copy, documentation, and UI text."
    },
    "sizing": {
      "baseSize": "16px",
      "method": "Size-relative line heights (em values, not fixed pixels). Tighter for headings (~1.2), more open for body text (~1.6). This ensures responsive scaling without breaking layouts on zoom.",
      "letterSpacing": "Tighten letter-spacing on larger headings where the tool allows. Use rem units in code; in other tools, apply visually or leave at defaults.",
      "rule": "Never use fixed pixel line heights. Always use relative values."
    },
    "mixing": {
      "rule": "Aim for two weights per page or slide. A third weight is acceptable in complex, multi-section layouts.",
      "default": "Bold for headings + Medium for body is the standard pairing."
    },
    "fallbacks": {
      "rule": "When Manrope is unavailable (e.g. email clients, third-party tools), use the system sans-serif. When JetBrains Mono is unavailable, use the system monospace.",
      "googleFonts": "Manrope is available on Google Fonts for use in Google Docs, Slides, and Sheets."
    }
  },

  "accessibility": {
    "_description": "Minimum colour/weight pairings for WCAG compliance. Colour tokens reference colour-tokens.json.",
    "light": {
      "headings": { "weight": "bold (700)", "colour": "neutral-1300", "wcag": "AAA" },
      "subheads": { "weight": "semibold (600)", "colour": "neutral-1300", "wcag": "AAA" },
      "body": { "weight": "medium (500)", "colour": "neutral-1000", "wcag": "AAA" },
      "quotes": { "weight": "regular (400)", "colour": "neutral-1300", "wcag": "AAA" },
      "links": { "weight": "regular (400)", "colour": "gui-blue-default", "wcag": "AA" }
    },
    "dark": {
      "headings": { "weight": "bold (700)", "colour": "neutral-000", "wcag": "AAA" },
      "subheads": { "weight": "semibold (600)", "colour": "neutral-000", "wcag": "AAA" },
      "body": { "weight": "medium (500)", "colour": "neutral-500", "wcag": "AAA" },
      "quotes": { "weight": "regular (400)", "colour": "neutral-000", "wcag": "AAA" },
      "links": { "weight": "regular (400)", "colour": "gui-blue-dark", "wcag": "AA" }
    }
  }
}