# Hallmark Study Verb Modes: URL Mode vs Image Mode Explained

> Understand Hallmark's study verb modes URL vs Image. Learn how Hallmark automatically selects the right mode based on your input for efficient study verb operations.

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

---

**Hallmark's `study` verb operates in two mutually exclusive modes—URL mode and image mode—automatically selected based on whether your input starts with `http://` or `https://`.**

The `study` verb is a core feature of the [Nutlope/hallmark](https://github.com/Nutlope/hallmark) repository that extracts design "DNA" from any source you provide. It analyzes visual and structural signals to generate a diagnostic report you can use to rebuild your own content or export as a portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file.

## How Hallmark Detects Which Mode to Use

Mode selection is **automatic and deterministic**. The tool inspects your input string and branches immediately—no flags or manual configuration required.

| Mode | Trigger | Processing Method |
|------|---------|-------------------|
| **URL mode** | Input starts with `http://` or `https://` | Fetches live page via WebFetch, parses HTML/CSS |
| **Image mode** | Any non-URL input (file path, pasted image, screenshot) | Runs local vision analysis on bitmap data |

This logic is codified in [[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md#L28): "Detection is automatic: a URL (`http://` / `https://` prefix) routes to URL mode; anything else (an attached image, a pasted capture) routes to image mode."

## URL Mode: Analyzing Live Web Pages

When you pass a web address, Hallmark enters **URL mode** and performs network-based extraction.

### What URL Mode Captures

- Exact **font names** from CSS declarations
- Precise **colour values** (hex, RGB, HSL)
- **Structural signals** from DOM hierarchy and layout

### URL Mode Limitation

**Rhythm (timing and animation curves) cannot be inferred** from static HTML/CSS. The diagnostic report explicitly notes this gap since motion design requires runtime observation.

### URL Mode Example

```bash
hallmark study https://example.com/landing-page

```

The WebFetch utility retrieves the page, and Hallmark's parser extracts computable design tokens without executing JavaScript or rendering the page visually.

## Image Mode: Analyzing screenshots and bitmaps

When your input lacks a URL prefix, Hallmark enters **image mode** and processes the file locally through computer vision.

### What Image Mode Captures

- **Macrostructure** (grid systems, visual hierarchy)
- **Archetypes** (design patterns and genre classification)
- **Type-pairing** relationships between fonts
- **Colour anchor** (dominant and accent palettes)
- **Rhythm** (timing, spacing, and motion cues visible in the frame)

Unlike URL mode, image mode **makes no network requests**. All analysis runs on the local bitmap, making it suitable for offline workflows or confidential designs.

### Image Mode Example

```bash
hallmark study ./screenshots/portfolio.png

```

As documented in [[`skills/hallmark/references/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md#L13): "If the user's input starts with `http://` or `https://` → **URL mode**; otherwise → **image mode**. Same verb, same diagnosis output, different signal sources."

## Comparing Hallmark Study Modes: When to Use Each

Both modes produce **identical output schemas**—a structured diagnosis you can act on immediately or serialize to [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md). Choose based on what information you need and what source material you have available.

| Factor | URL Mode | Image Mode |
|--------|----------|------------|
| **Best for** | Live sites, precise front-end auditing | Screenshots, mood boards, competitors' work |
| **Font accuracy** | Exact family names from CSS | Inferred from visual similarity |
| **Colour precision** | Native CSS values | Extracted from pixel sampling |
| **Rhythm detection** | Not available | Available (if visible in frame) |
| **Network required** | Yes | No |
| **Privacy** | Source site sees request | Completely local |

The [[`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html)](https://github.com/Nutlope/hallmark/blob/main/site/index.html#L412) interface exposes this duality with a single command pattern: `/hallmark study <screenshot | URL>`.

## Working with Study Output

Regardless of mode, the `study` verb emits a diagnostic you can use in two ways:

1. **Rebuild** — Apply the extracted DNA to your own content immediately
2. **Export** — Generate a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file for version control or sharing

The uniform output format means your toolchain needs no branching logic for mode-specific handling.

## Summary

- **Two modes power Hallmark's `study` verb**: URL mode for live pages, image mode for static files
- **Automatic detection**: `http://` or `https://` prefix triggers URL mode; all other inputs trigger image mode
- **URL mode** delivers precise CSS-extracted fonts and colours but cannot capture rhythm
- **Image mode** runs vision inference locally, capturing rhythm and macrostructure without network access
- **Both modes** produce identical diagnostic schemas for flexible downstream use

## Frequently Asked Questions

### How does Hallmark choose between URL mode and image mode?

Hallmark inspects the input string prefix. If it starts with `http://` or `https://`, the tool routes to URL mode; otherwise it assumes image mode. This is documented in [[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md#L28) and requires no user flags.

### Can I force image mode even if my filename looks like a URL?

No. The current implementation has no override flag—mode selection is strictly prefix-based. To analyze a screenshot with a URL-like filename, rename it or pass it through a different entry point.

### Why can't URL mode detect animation timing?

URL mode parses static HTML and CSS without executing JavaScript or rendering frames. Since rhythm data exists only in runtime behavior (transitions, keyframes with delays), it falls outside the observable surface. Image mode can infer rhythm only when motion is frozen as blur trails or sequential frames in the screenshot.