# Hallmark Study Function: Differences Between URL Mode and Image Mode Explained

> Discover the differences between Hallmark study function's URL mode and image mode. Learn how URL mode extracts design tokens and image mode uses visual perception to cover each other's blind spots.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: deep-dive
- Published: 2026-08-02

---

**URL mode extracts precise design tokens from HTML/CSS while image mode relies on visual perception, creating complementary blind spots where URL mode cannot detect rhythm and image mode cannot identify exact fonts or motion libraries.**

Hallmark's `study` verb diagnoses design DNA from digital sources, operating in either **URL mode** or **image mode** depending on input type. According to the Nutlope/hallmark source code, both modes follow an identical five-step protocol defined in [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md), but their information extraction capabilities diverge significantly because one parses fetched code while the other analyzes static visual perception.

## Input Detection and Mode Triggering

Hallmark determines the operational mode automatically based on input string patterns. In [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) (lines 11-14), the logic specifies that inputs beginning with `http://` or `https://` trigger **URL mode**, while any other input—including attached images or pasted screenshots—activates **image mode**.

This automatic detection eliminates manual flags for mode selection, though explicit CLI usage can specify image paths directly.

## The Five-Step Protocol: Technical Differences

Both modes execute the same five-step workflow—Surface, Type, Structure, Motion, and Rhythm—but the data fidelity varies based on source accessibility.

### Surface Analysis (Step 1): Color Extraction

**URL mode** pulls exact colour values from CSS custom properties including `:root` variables and `background-color` declarations, recording both the categorical band (e.g., "light") and precise OKLCH, hex, or RGB values.

**Image mode** estimates colour bands and accent footprint by visual inspection alone. No exact numeric values are recorded, only relative descriptors like "warm" or "high contrast."

### Typography Detection (Step 2): Font Identification

**URL mode** reads declared typefaces from `@font-face` rules, Google Fonts `<link>` tags, `next/font` implementations, or explicit `font-family` CSS properties. This captures both typographic roles (display vs. body) and exact font family names like "Inter" or "Merriweather."

**Image mode** infers only typographic roles (e.g., "italic editorial serif" or "geometric sans-serif"). The actual font name is omitted because visual identification without access to font files is unreliable.

### Structure Mapping (Step 3): DOM vs Visual Inference

**URL mode** reads the actual DOM structure, parsing semantic HTML elements like `<nav>`, `<section>`, `<main>`, and `<footer>` to map elements to the 21 named macro-structures defined in [`skills/hallmark/references/macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md) and component archetypes from [`skills/hallmark/references/component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/component-cookbook.md).

**Image mode** infers structure strictly from visible regions in the screenshot, lacking access to semantic HTML tags or DOM hierarchy.

### Motion Detection (Step 4): Library Detection Limitations

**URL mode** detects motion libraries including `framer-motion`, `gsap`, `lottie-web`, and `lenis`, plus CSS `@keyframes`, transitions, and scroll-triggered reveal patterns by analyzing the fetched JavaScript and CSS.

**Image mode** typically reports motion as "not visible" unless the screenshot itself depicts animation states or the user provides explicit motion descriptions, as static images cannot convey temporal behavior.

### Rhythm Analysis (Step 5): The URL Mode Blind Spot

**URL mode** contains a critical limitation: HTML cannot convey visual pacing or spatial rhythm. Consequently, rhythm fields are explicitly marked `unknown (URL mode)` in the output schema.

**Image mode** directly observes spacing, density, and visual pacing from the screenshot, enabling accurate rhythm judgment and whitespace analysis.

## Schema Output and Data Fidelity

The diagnostic report populates different schema fields depending on the source mode. **URL mode** populates `paper_value`, `accent_value`, `display_face`, `body_face`, and `motion_library` with concrete tokens and exact colour values.

**Image mode** leaves those precise fields as `null`, populating only band-level descriptors like `paper_band` and `accent_hue_band`. This distinction ensures that downstream consumers understand whether they are working with extracted code values or perceptual estimates.

## Security and Privacy Implications

**URL mode** implements comprehensive safety checks before fetching, including a URL-refusal list, remote-URL safety validation, and "junk-or-blocked" detection to prevent processing malicious or inaccessible endpoints.

**Image mode** requires no network safety steps, applying only image-mode specific refusal rules for inappropriate content, making it suitable for air-gapped environments or proprietary designs behind authentication walls.

## Practical Usage Examples

The CLI syntax varies slightly between modes, though URL mode requires no flags:

```bash

# URL mode – fetches HTML + same-origin CSS

hallmark study https://example.com/product-page

```

```bash

# Image mode – supplies a screenshot; no network fetch occurs

hallmark study --image ./screenshot.png

```

Both commands output a diagnosis report following the template in [`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md) (lines 73-99), though the populated sections will differ based on the source limitations described above.

## Summary

- **URL mode** triggers on `http://` or `https://` prefixes and extracts exact CSS values, font names, DOM structure, and motion libraries, but cannot assess visual rhythm.
- **Image mode** accepts any non-URL input and provides perceptual analysis of rhythm and visual hierarchy, but cannot identify exact colour values, specific font families, or motion implementations.
- **Safety checks** apply only to URL mode, while image mode operates offline without network fetching.
- **Schema fields** differ between modes: URL mode provides concrete tokens (`paper_value`, `display_face`), while image mode provides only categorical bands (`paper_band`, `display_role`).

## Frequently Asked Questions

### When should I use URL mode versus image mode in Hallmark?

Use **URL mode** when analyzing publicly accessible, server-rendered pages where you need exact colour values, specific font names, and motion library detection. Use **image mode** when the page requires authentication, is client-rendered with heavy JavaScript, or when you need accurate assessment of visual rhythm and spacing that CSS cannot convey.

### Why does URL mode report "unknown" for rhythm analysis?

HTML and CSS contain no semantic information about visual pacing, density, or temporal rhythm. Because **URL mode** parses code rather than rendering visuals, it cannot determine how spacious or cramped a design feels to human perception. This remains a **blind spot** explicitly marked in the schema output.

### Can image mode identify which fonts are used in a screenshot?

No. **Image mode** can only infer typographic roles (such as "serif display" or "monospace body") but cannot reliably identify specific font families like "Helvetica Neue" or "Roboto" without access to the underlying font files or CSS declarations.

### Does URL mode work with JavaScript-heavy single-page applications?

**URL mode** fetches the initial HTML and same-origin CSS, but may miss dynamically injected styles or client-side rendered content. For React, Vue, or Angular applications that hydrate content after load, **image mode** often provides more accurate results by capturing the final rendered state as perceived by users.