specimen

name	specimen
description	Typography system compiler that generates structured type scales, font stacks, and typographic tokens. Use when users request type systems, font scales, typography tokens, design system typography, or ask to create/export typographic styles. Pairs with hexed for complete design systems.
license	MIT

Specimen

Specimen is a typography system compiler that generates structured, production-ready type scales and typographic design tokens.

Overview

Typeset generates complete typography systems including:

• Modular type scales (multiple ratio options)
• Font family stacks (primary, secondary, monospace)
• Font weight scales
• Proportional line heights
• Letter spacing (tracking)
• Semantic mappings (h1, h2, body, etc.)

Output is deterministic, structured, and ready for CSS, Tailwind, SCSS, or Figma.

---

What Specimen Produces

A complete typography system including:

1. Type scale: Modular scale from base size (e.g., 16px) using mathematical ratios
2. Font families: Primary, secondary (optional), and monospace stacks
3. Font weights: Standard 100-900 weight scale with semantic names
4. Line heights: Proportional to each type scale step
5. Letter spacing: Optimized tracking for each size
6. Semantic mappings: h1-h4, body, caption, etc. → scale steps

---

Usage Instructions

Step 1: Define System Parameters

Determine the configuration:

config = {
    'base_size': 16,  # Base font size in pixels
    'ratio': 'minor_third',  # Scale ratio (see available ratios below)
    'font_family_primary': 'Inter, system-ui, sans-serif',
    'font_family_secondary': 'Playfair Display, serif',  # Optional
    'font_family_mono': 'JetBrains Mono, monospace',
    'mode': 'balanced'  # 'tight', 'balanced', or 'loose'
}

Available ratios:

• minor_second (1.067) - Very subtle
• major_second (1.125) - Subtle
• minor_third (1.200) - Balanced (recommended)
• major_third (1.250) - Moderate
• perfect_fourth (1.333) - Clear distinction
• augmented_fourth (1.414) - Strong
• perfect_fifth (1.500) - Very strong
• golden_ratio (1.618) - Maximum contrast

Modes:

• tight: 4 steps up, 1 step down (compact scale)
• balanced: 5 steps up, 2 steps down (default)
• loose: 6 steps up, 2 steps down (extended scale)

Step 2: Compile the System

import sys
sys.path.append('/home/claude/specimen/scripts')

from specimen_compiler import compile_from_config

result = compile_from_config(config)

if result['ok']:
    typography_system = result['typography_system']
    # System is ready for export
else:
    print(f"Error: {result['message']}")

Step 3: Export to Desired Formats

from specimen_exports import (
    export_css_variables,
    export_tailwind_config,
    export_scss_variables,
    export_figma_tokens,
    export_json
)

# CSS Variables
css = export_css_variables(typography_system)

# Tailwind Config
tailwind = export_tailwind_config(typography_system)

# SCSS Variables
scss = export_scss_variables(typography_system)

# Figma Tokens (Tokens Studio format)
figma_result = export_figma_tokens(typography_system)
figma_tokens = figma_result['tokens']

# Raw JSON
json_output = export_json(typography_system)

Step 4: Save and Present Outputs

Save exports to /mnt/user-data/outputs/:

import json

# Save JSON system
with open('/mnt/user-data/outputs/typography-system.json', 'w') as f:
    json.dump(typography_system, f, indent=2)

# Save CSS variables
with open('/mnt/user-data/outputs/typography.css', 'w') as f:
    f.write(css)

# Save Tailwind config
with open('/mnt/user-data/outputs/tailwind-typography.config.js', 'w') as f:
    f.write(tailwind)

# Save SCSS variables
with open('/mnt/user-data/outputs/typography.scss', 'w') as f:
    f.write(scss)

# Save Figma tokens
with open('/mnt/user-data/outputs/figma-typography-tokens.json', 'w') as f:
    json.dump(figma_tokens, f, indent=2)

Then use present_files to share them with the user.

---

Integration with Hexed

Specimen pairs perfectly with the Hexed color system compiler:

Combined workflow:

1. Use Hexed to extract color system from images
2. Use Typeset to generate typography system
3. Combine both into complete design system tokens

Example:

# Step 1: Generate colors with Hexed
color_result = compile_from_images(image_paths)
color_system = color_result['color_system']

# Step 2: Generate typography with Specimen
type_result = compile_from_config(typography_config)
type_system = type_result['typography_system']

# Step 3: Create unified design system
design_system = {
    'version': '1.0',
    'colors': color_system,
    'typography': type_system,
    'generated_at': datetime.utcnow().isoformat()
}

---

Best Practices

1. Start with standard ratios - Use minor_third (1.2) or major_third (1.25) for most projects
2. Match to use case:
   • Marketing/editorial: golden_ratio or perfect_fifth
   • UI/product: minor_third or major_third
   • Compact interfaces: major_second
3. Choose appropriate mode:
   • Tight: Mobile apps, compact UIs
   • Balanced: Most websites and apps
   • Loose: Marketing sites, content-heavy sites
4. Font stacks matter - Include fallbacks for web fonts
5. Ask which formats they need - Don't generate all unless requested

---

Recommended Type Scale Ratios by Use Case

Web Applications: minor_third (1.2)

• Balanced hierarchy
• Not too dramatic
• Works well for dashboards and tools

Marketing Sites: perfect_fourth (1.333) or golden_ratio (1.618)

• Strong visual hierarchy
• Eye-catching headings
• Editorial feel

Mobile Apps: major_second (1.125) or minor_third (1.2)

• Compact but clear
• Efficient use of screen space
• Good readability

Content/Editorial: major_third (1.25) or perfect_fourth (1.333)

• Clear hierarchy for long-form content
• Comfortable reading experience
• Traditional typographic feel

---

Common Configurations

Modern SaaS App

{
    'base_size': 16,
    'ratio': 'minor_third',
    'font_family_primary': 'Inter, system-ui, sans-serif',
    'font_family_mono': 'JetBrains Mono, monospace',
    'mode': 'balanced'
}

Marketing Site

{
    'base_size': 18,
    'ratio': 'perfect_fourth',
    'font_family_primary': 'Inter, system-ui, sans-serif',
    'font_family_secondary': 'Playfair Display, serif',
    'mode': 'loose'
}

Mobile App

{
    'base_size': 16,
    'ratio': 'major_second',
    'font_family_primary': 'system-ui, -apple-system, sans-serif',
    'mode': 'tight'
}

---

Author

Created by Heathen (@heathenft)

License

MIT License - See LICENSE file for details