# Hallmark Study URL Mode vs Image Mode: Key Differences for Design Diagnosis

> Explore Hallmark's study verb: discover URL mode vs image mode differences for design diagnosis. Learn how each source offers unique insights across five analysis steps.

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

---

**Hallmark's `study` verb diagnoses design DNA from either a live webpage (URL mode) or a screenshot (image mode), with each source providing different depths of information across five analysis steps.**

Hallmark's `study` verb is the core diagnostic tool in the [Nutlope/hallmark](https://github.com/Nutlope/hallmark) repository for extracting design system "DNA" from any source. Understanding when to use **URL mode** versus **image mode** ensures you capture the most accurate tokens, typefaces, and structural information available. The trigger logic is simple: input strings starting with `http://` or `https://` activate URL mode; everything else—including attached images or pasted screenshots—triggers image mode.

## How Source Mode Is Determined

The mode selection happens automatically based on input format. According to [`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md) (lines 11-14), the router checks:

- **URL mode**: Input matches `/^https?:\/\//`
- **Image mode**: Any other input (file paths, image buffers, clipboard captures)

This routing decision cascades through all five analysis steps, determining what data each step can actually collect.

## Step-by-Step Comparison: What Each Mode Can Capture

### Surface (Step 1): Color Extraction

**URL mode** pulls exact color values from CSS custom properties in `:root`, `background-color`, and other computed styles. It records both the **band** (e.g., "light") and the precise **OKLCH/hex/RGB value**.

**Image mode** estimates color bands and accent footprint by visual perception. No exact numeric values are recorded—only qualitative descriptors like `paper_band` and `accent_hue_band`.

### Type (Step 2): Typography Identification

**URL mode** reads declared typefaces from:
- `@font-face` declarations
- Google Fonts `<link>` tags
- `next/font` configurations
- Explicit `font-family` CSS rules

Both **roles** and **exact font names** are stored (e.g., `display_face: "Inter Display"`).

**Image mode** only infers **roles** (e.g., "italic editorial serif"). The actual font name is omitted because visual identification is unreliable.

### Structure (Step 3): Layout Mapping

**URL mode** parses the real DOM—`<nav>`, `<section>`, `<main>`, `<footer>`, and other semantic elements—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 from visible regions in the screenshot. No DOM insight means nested relationships and semantic meaning must be guessed from visual hierarchy alone.

### Motion (Step 4): Animation Detection

**URL mode** detects motion libraries (`framer-motion`, `gsap`, `lottie-web`, `lenis`), CSS `@keyframes`, transitions, and scroll-triggered reveals by scanning source code and stylesheets.

**Image mode** usually reports motion as `"not visible"` unless the screenshot itself is animated (rare) or the user explicitly describes motion in accompanying text.

### Rhythm (Step 5): Visual Pacing

**URL mode** has a **blind spot** here. HTML cannot convey visual pacing, so rhythm fields are marked `unknown (URL mode)`.

**Image mode** directly observes spacing, density, and pacing from the screenshot, enabling actual rhythm judgment.

## Schema Output Differences

The final diagnosis report (template defined in [`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md) lines 73-99) populates different fields depending on source mode:

| URL Mode Populates | Image Mode Populates |
|---|---|
| `paper_value`, `accent_value` (exact colors) | `paper_band`, `accent_hue_band` (qualitative) |
| `display_face`, `body_face` (exact font names) | Role descriptors only (font names `null`) |
| `motion_library` (detected libraries) | `null` or `"not visible"` |
| Rhythm: `unknown (URL mode)` | Rhythm: actual observations |

## Safety and Privacy Considerations

**URL mode** runs multiple safety checks before fetching:
- URL-refusal list (blocked domains)
- Remote-URL safety validation
- "Junk-or-blocked" detection (cloudflare, paywalls, bot protection)

**Image mode** requires no network safety steps. Only image-mode refusal rules apply (malformed images, unsupported formats).

## CLI Usage Examples

```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

```

## When to Use Each Mode

**Choose URL mode when:**
- The page renders server-side with accessible CSS
- You need exact color tokens 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
- The site blocks automated fetching
- Visual rhythm, spacing, and density are critical
- You have a precise screenshot of the intended state

## Summary

- **URL mode** excels at precise tokens, exact typography, DOM structure, and motion detection—fails at rhythm.
- **Image mode** captures rhythm and works with inaccessible pages—sacrifices exact values for visual fidelity.
- Mode selection is automatic based on input format (`http` prefix vs. image path).
- Both modes output to the same diagnosis report schema, but populated fields differ significantly.

## Frequently Asked Questions

### Can I force image mode even with a URL string?

No. The mode router in [`study.md`](https://github.com/Nutlope/hallmark/blob/main/study.md) strictly checks for `http://` or `https://` prefixes. To analyze a URL as an image, capture a screenshot first and pass the image path.

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

HTML and CSS contain no semantic information about visual pacing, density, or spacing rhythm. These qualities only exist in the rendered visual output, which requires image mode observation.

### Does image mode ever detect exact font names?

No. As documented in the type analysis step, image mode deliberately omits exact font names because visual identification is unreliable. Only inferred roles like "bold geometric sans" are reported.

### What happens if URL mode hits a blocked or protected site?

The fetch layer runs "junk-or-blocked" detection. If triggered, the study aborts with an error rather than returning partial or misleading data. Use image mode with a manual screenshot as the fallback.