---
name: typography-kit
description: "End-to-end typography system creation: explore typeface pairings for a design direction, create specimen sheets, build a full-page mockup with library components, update component fonts and text styles, and generate a typography standards page. Use when setting up or overhauling a file's typographic system."
---

# Typography Kit

Create an end-to-end typography system for a design library — from typeface exploration through component updates and documentation.

## Running this with Claude and the Figma MCP

Written for Figma's built-in agent, adapted for Claude (Claude Code, Claude Desktop or claude.ai) connected to the official Figma MCP server.

- **Get the file.** If you don't have a Figma link, ask for one. The file key is the segment after `/design/`; a `node-id=1-2` parameter means node `1:2`.
- **Start a session.** Call `create_session` with the file key before any other Figma tool, and pass the returned session ID on every later call.
- **Read before writing.** `get_metadata` shows the structure and the user's current selection, `get_variable_defs` lists the variables on a node, `search_design_system` finds published components, variables and styles, and `get_screenshot` shows what's on the canvas.
- **Write with `use_figma`.** It runs Plugin API JavaScript in the file. Load the `figma-use` skill first (plus `figma-generate-library` when you create variables, styles or components) and list them in `skillNames`. Scripts use top-level `await` and `return` everything they create: nothing persists between calls, so pass node and variable IDs forward as string literals. Colors are 0–1, not 0–255. Switch pages with `await figma.setCurrentPageAsync(page)`, at most once per call; for multi-page work, run one call per page in parallel. `figma.notify()` isn't available.
- **Ask, then wait.** Wherever a step says to ask the user, ask in chat (in Claude Code, use the AskUserQuestion tool) and wait for the answer before building.
- **Clear helper fills.** `figma.createAutoLayout()` frames start with a white fill. Set `fills = []` on rows and wrappers that should be transparent, or they show up as white bars (most visibly in dark-mode previews).
- **Check the result.** After a build step, take one screenshot (`await node.screenshot()` inside `use_figma`, or `get_screenshot`) and fix only what's wrong.

## Step 0: Gather context

Before starting, collect the following from the user. Ask for each one not already answered in the conversation (in Claude Code, with the AskUserQuestion tool):

1. **Design direction / aesthetic** — What mood, style, or inspiration should drive the type choices? (e.g. retro-futurist, minimal corporate, editorial luxury, playful consumer, brutalist)
2. **Number of typefaces** — How many typefaces should the system use? (e.g. 1 versatile family, 2 complementary faces, 3 with a monospace accent)
3. **Font sourcing constraints** — What loading strategy matters?
   - Browser-native / system fonts only (zero downloads)
   - Google Fonts or similarly lightweight open-source fonts with good system fallbacks
   - Any available font (no constraints)
4. **Specimen color scheme** — Should specimens and the standards page use a dark background, light background, or match existing file colors?
5. **Key legibility concerns** — Any specific constraints? (e.g. "must be legible at small sizes", "avoid thin strokes on screen", "needs to work for data-dense dashboards")

## Step 1: Inventory the library

Before exploring fonts, inspect the file to understand what exists:

- **List all component pages** and the components on each (buttons, cards, nav, inputs, etc.)
- **Catalog current font usage** across components — which fonts, weights, and sizes are in use
- **Check existing variables and text styles** — note what's already defined so you can extend or replace
- **Note the existing color system** — identify background, text, and accent colors from variables

This inventory tells you what text roles exist (heading, body, label, button, caption, input, kicker, etc.) and drives the type scale you'll build later.

## Step 2: Check available fonts

Run `await figma.listAvailableFontsAsync()` in a `use_figma` script to discover what's actually loadable in the file. Use the exact style names it returns: they differ by family (Inter uses "Semi Bold", while Lexend, Nunito and Atkinson Hyperlegible Next use "SemiBold"), and load every font with `await figma.loadFontAsync()` before editing text. Filter by the user's sourcing constraint:

- For **browser-native**: look for system fonts (Georgia, Verdana, SF Pro, Roboto, etc.)
- For **Google Fonts / open-source**: search for fonts matching the design direction keywords
- For **any**: search broadly

Cross-reference availability against the design direction. Build a shortlist of candidate typefaces that fit both the aesthetic and the constraint.

## Step 3: Create initial specimen pairings

Create **3 specimen cards** side by side, each showing a different typeface pairing. Each card should display:

- Pairing name and brief description of its character
- **Heading** sample (largest display size)
- **Subheading** sample
- **Label** sample (small, possibly uppercase with tracking)
- **Body** sample (paragraph text)
- Font metadata (family, weight, size) for each sample
- CSS fallback stack

Use the user's preferred color scheme for the specimen background. Include clear typography metadata so the user can evaluate both the aesthetic and the technical specs.

## Step 4: Iterate on pairings

Present the specimens and ask for feedback. Based on the user's reaction:

- If they like some but not others, create **3 more alternatives** that lean into what they liked
- If they want to mix elements, create **mix-and-match combinations** with reduced typeface counts per set
- If they want to see a pairing in context, proceed to Step 5 with their preferred option

Repeat until the user has a clear favorite. Don't push for a decision — let them explore.

## Step 5: Build a full-page mockup

Create a complete page layout using **actual component instances** from the library. This is the typography stress test — it shows how the pairing holds up across every component type.

- Instantiate every major component type (nav, headers, cards, badges, testimonials, inputs, alerts, buttons, footer — whatever the library contains)
- Override instance text with realistic portfolio/app content
- Override fonts on all text nodes within instances to use the chosen pairing
- Apply the font mapping consistently:
  - **Display font** → headings, buttons, nav links, brand text, alert titles
  - **Body font** → body copy, descriptions, labels, badges, captions, input values, form labels

If the user wants to compare multiple pairings at full-page scale, clone the mockup and remap fonts for each variant, positioned side by side.

## Step 6: Apply to the library

Once the user confirms their choice, update the actual library:

### 6a. Update all component fonts
Walk every component across all pages and swap fonts from the current typeface to the chosen one. Use context-aware mapping — the role of each text node (heading vs body vs label) determines which font from the pairing it gets.

### 6b. Create text styles
Define a complete set of text styles based on the roles discovered in Step 1 and the sizes/weights used in the mockup. Typical roles include:

- Heading/H1, H2, H3
- Body/Default, Small, Emphasis
- Label/Kicker, Default, Small
- UI/Button, Nav Link, Nav Brand, Alert Title
- Caption/Default, Small
- Input/Label, Value

Each style should have: font family, weight, size, line height, letter spacing, text case, and a description of when to use it.

### 6c. Bind text styles to components
Apply the text styles to every text node in every component, matching by role and context (page, font, size, content).

### 6d. Let the user review the mockup
Let the user review and make adjustments to the mockup. If they change fonts on specific elements, audit the mockup again and update the affected text styles and components to match their changes.

## Step 7: Build the Typography standards page

Create a documentation page on the file's Typography page (or create one if it doesn't exist). The page structure should adapt to what the library contains, but generally include:

### Typeface overview
Cards for each typeface showing: role description, character sample, design notes, and CSS fallback stack.

### Type scale
Every text style shown as a live specimen with metadata (style name, font family, weight, size, line height, letter spacing, text case). Group by role category (Headings, Body, Labels, UI, Caption, Input, etc.). Adapt categories to match what actually exists in the library.

### Usage guidelines
Practical rules derived from the chosen system. Cover:
- Font role separation (which font handles which roles)
- Formatting conventions (e.g. kickers always uppercase)
- Fallback strategy and CSS stacks
- Minimum size recommendations
- Color pairing guidance (which text color tokens to use with which roles)

Use the same color scheme as the specimens for visual consistency.

## Key principles

- **The mockup is the source of truth.** If the user edits the mockup, those changes override previous decisions. Always audit the mockup before finalizing styles and components.
- **Two fonts is the sweet spot.** One display + one workhorse covers most needs. Three is the max before a system gets hard to maintain. Guide users toward simplicity.
- **Every text node needs a style.** No orphaned text — every text node in every component should be bound to a text style by the end.
- **Show, don't tell.** Always create visual specimens rather than describing fonts in text. Users need to see type in context to make good decisions.
- **Respect the existing system.** Preserve variable collections, color tokens, and component structure. You're changing typography, not rebuilding the library.