Specimen

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