Fetchtype Documentation

01

Installation

Or run directly with npx — no installation required:

02

Commands

03

Token Format

Fetchtype tokens live in fetchtype.tokens.json at your project root. The schema covers typography, color, spacing, layout, and hierarchy.

Typography Contexts

Each context maps to a TypographyToken with the following fields:

The 12 typography contexts:

Color Tokens

Defined per mode (light and dark). Each mode contains:

Spacing, Layout & Hierarchy

Optional Top-Level Fields

// Minimal fetchtype.tokens.json
{
  "typography": {
    "body": {
      "fontFamily": ["Inter", "sans-serif"],
      "fontSize": "1rem",
      "fontWeight": 400,
      "lineHeight": 1.6
    }
  },
  "color": { "light": { ... }, "dark": { ... } },
  "spacing": { "unit": "0.25rem", "scale": { "sm": "0.5rem", "md": "1rem" } },
  "layout": { "maxWidth": { "prose": "65ch", "content": "80rem", "wide": "96rem", "full": "100%" }, "breakpoints": {} },
  "hierarchy": { "scale": "major-third", "baseSize": "1rem", "headings": { ... }, "emphasis": { ... } }
}

04

Presets

Start from a design system preset with validated typography, colors, spacing, and hierarchy.

05

Validation Rules

fetchtype validate checks your tokens against rules in three categories: core validation, font analysis, and site audit.

Core Rules

Font Rules

Audit Rules

Run with fetchtype audit <url> to check a live site or HTML file.

06

Exporters

fetchtype build transforms your token file into production-ready output. Default format is CSS custom properties.

07

Font Registry

1,929 Google Fonts with enriched metadata including performance metrics, fallback CSS, pairing recommendations, and context suitability scores.

FontEntry Fields

CLI Commands

Search Filters

08

Motion & Animation

Define your motion personality as tokens. Durations, easings, spring configs, animation presets, and scroll-driven interpolations — all framework-agnostic values that map to Framer Motion, anime.js, CSS transitions, or any animation library.

Token Format

"motion": {
  "duration": {
    "instant": "100ms",
    "fast": "200ms",
    "normal": "300ms",
    "slow": "500ms"
  },
  "easing": {
    "default": "cubic-bezier(0.4, 0, 0.2, 1)",
    "enter": "cubic-bezier(0, 0, 0.2, 1)",
    "exit": "cubic-bezier(0.4, 0, 1, 1)",
    "bounce": "cubic-bezier(0.34, 1.56, 0.64, 1)"
  },
  "spring": {
    "snappy": { "stiffness": 400, "damping": 30, "mass": 1 },
    "gentle": { "stiffness": 120, "damping": 14, "mass": 1 },
    "bouncy": { "stiffness": 300, "damping": 10, "mass": 1 }
  },
  "preset": {
    "fade-in": {
      "property": "opacity",
      "from": 0, "to": 1,
      "duration": "300ms",
      "easing": "cubic-bezier(0, 0, 0.2, 1)"
    }
  },
  "interpolation": {
    "parallax-depth": {
      "input": "scroll",
      "inputRange": [0, 0.5, 1],
      "outputRange": [0, "-50px", "-100px"]
    }
  }
}

Validation Rules

CSS Output

:root {
  --ft-motion-duration-instant: 100ms;
  --ft-motion-duration-fast: 200ms;
  --ft-motion-duration-normal: 300ms;
  --ft-motion-easing-default: cubic-bezier(0.4, 0, 0.2, 1);
  --ft-motion-easing-enter: cubic-bezier(0, 0, 0.2, 1);
  --ft-motion-spring-snappy-stiffness: 400;
  --ft-motion-spring-snappy-damping: 30;
  --ft-motion-spring-snappy-mass: 1;
}

09

Scenes & 3D

Define 3D scene parameters as tokens — camera presets, lighting rigs, PBR materials, and environment config. Framework-agnostic values that map to Three.js, React Three Fiber, Spline, or Babylon.js.

"scenes": {
  "camera": {
    "default": {
      "type": "perspective",
      "fov": 45,
      "near": 0.1,
      "far": 1000,
      "position": [0, 2, 5]
    }
  },
  "materials": {
    "brand-surface": {
      "type": "physical",
      "color": "#7c3aed",
      "roughness": 0.35,
      "metalness": 0.1
    },
    "glass": {
      "type": "physical",
      "color": "#ffffff",
      "roughness": 0.05,
      "transmission": 0.95,
      "thickness": 0.5
    }
  },
  "environment": {
    "default": {
      "background": "#0a0a0a",
      "fog": { "color": "#0a0a0a", "near": 10, "far": 50 }
    }
  }
}

Material Validation

10

Timeline Compositions

Frame-based, time-bounded compositions for hero animations, product showcases, and promotional content. Inspired by Remotion's programmatic video model — define sequences on a timeline, not imperative code.

"timeline": {
  "fps": 30,
  "compositions": {
    "hero-intro": {
      "width": 1920,
      "height": 1080,
      "durationInFrames": 90,
      "params": {
        "headline": "string",
        "accentColor": "#7c3aed"
      },
      "sequences": [
        { "name": "bg-fade", "from": 0, "durationInFrames": 30 },
        { "name": "title-enter", "from": 15, "durationInFrames": 45, "stagger": 5 },
        { "name": "cta-appear", "from": 50, "durationInFrames": 40 }
      ]
    }
  }
}

11

Spatial Layers

A z-ordered canvas of visual elements, each with composable shader effects and continuous interaction drivers. Inspired by Unicorn Studio's layer-based WebGL model.

"layers": {
  "hero-background": {
    "type": "image",
    "z": 0,
    "effects": [
      { "type": "noise", "intensity": 0.15, "scale": 2.0 },
      { "type": "blur", "radius": "8px" }
    ],
    "interactions": {
      "mouse": {
        "property": "position",
        "intensity": 0.02,
        "smoothing": 0.1
      }
    }
  },
  "hero-mesh": {
    "type": "3d-model",
    "z": 1,
    "interactions": {
      "scroll": {
        "property": "scale",
        "inputRange": [0, 1],
        "outputRange": [1, 1.5]
      }
    }
  }
}

12

MCP Server

Fetchtype ships an MCP server with 12 tools for AI agent integration. Works with Claude, Cursor, Windsurf, and any MCP-compatible client.

Add to your MCP client config:

{
  "mcpServers": {
    "fetchtype": {
      "command": "npx",
      "args": ["fetchtype", "mcp"]
    }
  }
}

13

Agent Integrations

Drop-in configuration files that give AI coding agents full fetchtype awareness — token schema, all 20 rules, CLI commands, and MCP server setup. Copy the right file into your project.

mkdir -p .claude/skills/fetchtype
# Copy SKILL.md from docs/agent-integrations/

Each file teaches the agent the full fetchtype workflow: token schema (12 typography contexts), all 20 validation rules, every CLI command with flags, export formats, and MCP server configuration.

https://github.com/fetchtype/fetchtype/tree/main/docs/agent-integrations

Fastest integration: Skip the config files entirely — just add the MCP server to your tool's config (see section 08 above). This gives the agent 12 tools for validation, font search, pairing, and export with no file copying.

14

REST API

Public REST API for querying the font registry. CORS enabled, public caching.

curl "https://fetchtype.dev/api/v1/fonts?category=sans-serif&variable=true&limit=5"

curl "https://fetchtype.dev/api/v1/fonts/inter"

curl "https://fetchtype.dev/api/v1/fonts/inter/pairings"

v2 — Batch, Compare & Stack

Agent-optimised endpoints for multi-font queries, side-by-side comparison, and complete stack recommendations. CORS enabled.

curl -X POST "https://fetchtype.dev/api/v2/fonts/batch" \
  -H "Content-Type: application/json" \
  -d '{"fontIds":["inter","roboto","playfair-display"]}'

curl "https://fetchtype.dev/api/v2/fonts/compare?fonts=inter,roboto,open-sans"

curl "https://fetchtype.dev/api/v2/fonts/stack?context=interface&budget=120"