AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

design-system

Use when setting up brand settings before the first markdown-to-HTML conversion, or changing them. Runs a 10-question onboarding with onboard.py (colors, fonts, style, TOC) and refuses palettes that fail WCAG AA via brand_palette_validator.py.

Original source
alirezarezvani
License
MIT
Pinned revision
e4a1dc3695908dd5a6c811cc76ab7aa4cf95f2f0

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read alirezarezvani--design-system at revision e4a1dc3695908dd5a6c811cc76ab7aa4cf95f2f0, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 4

references/typography_pairing.md

Typography Pairing

Why this exists: The onboarding wizard offers 12 Google Fonts and asks the user to pick a heading + body pair. Most users don't have strong opinions on type. This document codifies the pairs that work without further thought, so the wizard can recommend confidently and the converters can render coherently.

Safe pairs

| Pair | Use for | Reason | |---|---|---| | Inter + Inter | Technical docs, dashboards | Single family across heading/body — clean, neutral, OpenType-rich | | Inter + Source Sans 3 | Long-form reports | Sans-on-sans pairing; Source Sans is more readable at body size | | Source Serif 4 + Source Sans 3 | Editorial / narrative | Adobe's Source family — designed as a coherent system | | Playfair Display + Lora | Magazine-style | Serif heading with personality; serif body that pairs | | Merriweather + Open Sans | Long-form reading | Editorial serif + neutral sans body; oldest-and-safest pair | | IBM Plex Sans + IBM Plex Sans | Technical + brand | Plex is designed for documentation; coherent across weights | | JetBrains Mono + (Inter or Source Sans 3) | Engineering notebooks | Mono headings signal a coding/terminal context |

Sources

1. Ellen Lupton — Thinking with Type (Princeton Architectural Press, 2010)

Foundational. The "stress, weight, and contrast" framework for pairing: the heading and body should share at least one of {stress angle, x-height, terminal style} and contrast in at least one of {weight, scale}. Every recommended pair above satisfies this.

2. Tim Brown — Combining Typefaces (Five Simple Steps, 2013)

The "concord / contrast / conflict" framework. Concord (same family) is always safe — hence the Inter+Inter and IBM Plex Sans+IBM Plex Sans pairs. Contrast is rewarding when done with intent (Playfair + Lora). Conflict is what users should avoid; the wizard's curated list rules out conflict pairs.

3. Erik Spiekermann — Stop Stealing Sheep & Find Out How Type Works (Adobe Press, 2013, 3rd ed.)

Argues that body type carries 95% of the visual weight in a document. The wizard prioritizes body font choice over heading font choice in the recommendation framing.

4. Google Fonts — Pairings and Featured Pairs (fonts.google.com)

The 12 fonts in SAFE_FONTS are pulled from Google Fonts' own curated catalog, biased toward families with multiple weights and broad language coverage. All available under the SIL Open Font License — no licensing concerns.

5. IBM Design Language — Plex Family Documentation (ibm.com/design/language/typography/type-basics)

Documents the "designed as a system" pattern: Plex Sans, Serif, Mono share metrics and x-height, so any combination renders coherently. We surface Plex Sans for users who want IBM-style technical documents.

6. Adobe Fonts — Source Sans, Source Serif, Source Code (fonts.adobe.com/foundries/adobe-originals)

Same "designed as a system" idea: Source family was created by Adobe to be a coherent triple. We surface Source Sans 3 and Source Serif 4 (the current versions, with extended Cyrillic and Vietnamese coverage).

7. Marcin Wichary — The Hardest Working Font in Manhattan (figma.com/blog, 2023)

A case study on choosing Inter for the Figma marketing site. Reinforces Inter as a reasonable default for technical-yet-broad audiences.

What about display fonts, script fonts, decorative fonts?

Excluded from the wizard's options. Decorative fonts work for the first 200 words and exhaust the reader thereafter — they're a marketing-page choice, not a document choice. If the user wants a decorative heading, they can set typography.heading_font to any Google Font name manually after onboarding (the field accepts any string).

What about variable fonts?

Inter, Roboto, Source Sans 3, Source Serif 4, IBM Plex Sans, and JetBrains Mono are all available as variable fonts on Google Fonts. The converters use the wght@400;600 slice by default — sufficient for body + bold heading — to keep CDN payload small. Users who want a wider weight range can override the Google Fonts URL directly in the generated HTML.

Type scale

typography.scale_ratio (default 1.25 = major third) drives a modular scale: body = 1rem, h6 = 1rem × 1.25, h5 = 1rem × 1.25², etc. Defaults:

| Ratio | Name | Effect | |---|---|---| | 1.125 | Major second | Tight; good for dense reference docs | | 1.2 | Minor third | Standard for technical writing | | 1.25 | Major third | Default; balanced for long-form reading | | 1.333 | Perfect fourth | Editorial; pronounced hierarchy | | 1.5 | Perfect fifth | Magazine-style with bold headings |

Each converter applies the scale based on this single ratio — no per-level overrides.

Applied to markdown-html

The converters emit a <link> to Google Fonts at document head and apply the typography choice via CSS:

:root {
  --md-font-heading: 'Source Serif 4', Georgia, serif;
  --md-font-body: 'Source Sans 3', system-ui, sans-serif;
  --md-scale: 1.25;
}
body { font-family: var(--md-font-body); }
h1, h2, h3, h4, h5, h6 { font-family: var(--md-font-heading); }

The system fallback in each font-family declaration means the document still reads well if Google Fonts is blocked.