# Hallmark Study URL Mode vs Image Mode: How the Source Type Changes Design Analysis

> Discover how Hallmark's study command differentiates URL mode and image mode. Learn how input type affects CSS value extraction and visual inference in design analysis.

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

---

**Hallmark's `study` command automatically detects whether your input is a URL or image and adapts its five-step diagnostic protocol accordingly, with URL mode extracting precise CSS values while image mode relies on visual inference.**

When you run `hallmark study`, the tool needs to decide whether it can fetch and parse live code or must interpret a static visual. This distinction—**URL mode** versus **image mode**—determines exactly what design DNA the tool can extract. Understanding these differences helps you choose the right input type for your specific workflow.

---

## How Hallmark Detects URL Mode vs Image Mode

The detection logic is straightforward and implemented in [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) (lines 11-14). Hallmark checks whether your input string starts with `http://` or `https://`:

- **URL mode triggered**: Input begins with `http://` or `https://`
- **Image mode triggered**: Any other input (file path, attached image, pasted screenshot)

This automatic routing happens before any network requests or image processing begins.

```bash

# URL mode – triggers network fetch and HTML/CSS parsing

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

# Image mode – processes local screenshot without network access

hallmark study --image ./screenshot.png

```

---

## The Five-Step Protocol: What Each Mode Can See

Both modes follow the same diagnostic structure defined in [`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md), but the *depth of information* at each step varies dramatically.

### Step 1: Surface (Color Extraction)

| Mode | Capabilities |
|------|--------------|
| **URL mode** | Pulls exact color values from CSS custom properties (`:root` variables, `background-color`, etc.). Records both the **band** (e.g., "light") **and** precise OKLCH/hex/RGB values in fields like `paper_value` and `accent_value`. |
| **Image mode** | Estimates color bands and accent footprint by visual inspection. Only band-level descriptors (e.g., `paper_band`, `accent_hue_band`) are recorded; exact numeric values are omitted. |

### Step 2: Type (Typography Detection)

- **URL mode**: Reads declared typefaces from `@font-face` rules, Google Fonts `<link>` tags, `next/font` declarations, or explicit `font-family` CSS. Captures both *roles* and **exact font names** in `display_face` and `body_face` fields.
- **Image mode**: Infers typographic *roles* only (e.g., "italic editorial serif"). The actual font name is **omitted** because visual identification is unreliable.

### Step 3: Structure (Layout Mapping)

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

- **Image mode**: Infers structure from visible regions in the screenshot. Without DOM access, it cannot distinguish semantic containers from presentational grouping.

### Step 4: Motion (Animation Detection)

| Mode | Detection Range |
|------|---------------|
| **URL mode** | Identifies motion libraries (`framer-motion`, `gsap`, `lottie-web`, `lenis`), CSS `@keyframes`, transitions, and scroll-triggered reveals. Populates `motion_library` field. |
| **Image mode** | Usually reports "not visible" unless the screenshot itself captures motion blur or the user provides a description. |

### Step 5: Rhythm (Visual Pacing)

This step reveals a critical **blind spot in URL mode**:

- **URL mode**: Rhythm fields are marked `unknown (URL mode)`. HTML cannot convey visual pacing, density, or spacing relationships.
- **Image mode**: Directly observes spacing, density, and pacing. Can judge rhythm accurately from the screenshot.

---

## Schema Output Differences

The final diagnosis report reflects these capabilities in its populated fields:

| Field | URL Mode | Image Mode |
|-------|----------|------------|
| `paper_value`, `accent_value` | Exact color tokens | `null` |
| `display_face`, `body_face` | Concrete font names | `null` |
| `motion_library` | Detected library name | `null` |
| `paper_band`, `accent_hue_band` | Populated | Populated |
| Rhythm assessment | `unknown` | Actual judgment |

---

## Safety and Privacy Considerations

URL mode includes additional safeguards before any fetch occurs:

- URL refusal list validation
- Remote-URL safety checks
- "Junk-or-blocked" detection

Image mode bypasses network entirely, applying only image-mode refusal rules. This makes image mode preferable for client-rendered pages, authenticated content, or air-gapped environments.

---

## When to Use Each Mode

**Choose URL mode when:**
- The page renders server-side with accessible CSS
- You need exact color values and font names
- Motion libraries and animation details matter
- The site is public and fetchable

**Choose image mode when:**
- The page is client-rendered or behind authentication
- Visual rhythm and spacing analysis is priority
- Network access is restricted or undesirable
- You need to analyze a specific state or viewport

---

## Summary

- Hallmark `study` auto-detects URL mode (`http://` prefix) versus image mode (all other inputs)
- **URL mode excels at**: exact colors, precise fonts, DOM structure, motion libraries
- **Image mode excels at**: visual rhythm, authenticated content, air-gapped analysis
- URL mode has a **critical blind spot**: cannot assess visual pacing (rhythm fields return `unknown`)
- Image mode has **inherent limitations**: no exact values, no motion detection, no DOM semantics
- Choose your input type based on which design DNA components matter most for your analysis

---

## Frequently Asked Questions

### How does Hallmark detect whether to use URL mode or image mode?

Hallmark checks if your input string starts with `http://` or `https://` in [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) (lines 11-14). If it matches, URL mode triggers a network fetch and HTML/CSS parse. Any other input routes to image mode for local visual processing.

### Why can't URL mode analyze visual rhythm?

HTML and CSS cannot encode spatial pacing, density relationships, or compositional timing. These visual properties exist only in the rendered output. URL mode marks rhythm fields as `unknown (URL mode)` because the source code lacks this information.

### When should I prefer image mode over URL mode?

Use image mode when analyzing client-rendered SPAs, authenticated content, specific viewport states, or when network access is unavailable. Image mode is also essential when rhythm and spacing analysis matters, as this is URL mode's primary data gap.

### Does image mode capture motion or animation details?

Generally no—image mode reports motion as "not visible" unless the screenshot itself shows motion artifacts or the user explicitly describes animation behavior. For reliable motion library detection, URL mode's code-based analysis is required.