# What Is the Purpose of the Hallmark `study` Verb? > Understand the hallmark study verb, a read-only tool that extracts design DNA from screenshots or URLs. Learn to rebuild layouts without copying assets. - Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark) - Tags: how-to-guide - Published: 2026-08-15 --- **The `hallmark study` verb is a read-only diagnosis tool that extracts the design DNA of a reference screenshot or URL through a structured five-step protocol, enabling designers to understand and rebuild layouts without copying visual assets.** The `hallmark study` verb serves a unique role in the Hallmark CLI workflow by providing **ethical, repeatable design analysis** that respects copyright while delivering actionable structural insights. As implemented in [Nutlope/hallmark](https://github.com/Nutlope/hallmark), this tool bridges the gap between inspiration and implementation through rigorous safety checks and standardized output formats. --- ## How `hallmark study` Works: The Five-Step Protocol The verb executes a disciplined protocol 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). Each step builds cumulative understanding of the reference design: 1. **Surface** — Identifies colour bands, background treatments, and texture patterns 2. **Type** — Extracts font families, scale ratios, weight hierarchies, and role assignments 3. **Structure** — Maps macrostructure (page regions) and microstructure (component nesting) 4. **Motion** — Detects animation cues, transition patterns, and interaction states 5. **Rhythm** — Analyzes spacing systems, grid logic, and visual pacing The protocol produces a **structured JSON schema** containing normalized values—concrete `OKLCH` colour tokens when sourced from URLs, relative band descriptions when sourced from screenshots. --- ## Source Modes: Image vs. URL The `hallmark study` verb handles two distinct input types through unified logic. Both modes respect the same safety constraints but yield different extraction fidelity. ### Image Mode (Screenshot Analysis) When you provide a screenshot, the verb performs purely local analysis: ```bash hallmark study \ --image ./my-screenshot.png \ --output diagnosis.json ``` This mode **never makes network requests**. The tool infers visual properties through computer vision and heuristics, though it cannot reliably identify font names from rasterized text. Motion and rhythm descriptions rely on visual static analysis rather than computed styles. ### URL Mode (Live Web Page Analysis) When targeting a live URL, extraction reaches deeper into the source: ```bash hallmark study \ --url https://example.com \ --output diagnosis.json ``` URL mode fetches HTML and same-origin CSS to extract **exact design tokens**: precise colour values, declared font families, computed spacing, and animation keyframes. However, rhythm analysis remains limited since temporal properties require interaction. --- ## Safety Architecture: The Refusal List and Remote Checks The `hallmark study` verb implements multiple defensive layers before any URL fetch begins. According to the source specification, these checks treat all fetched content as **untrusted data**: - **Scheme validation** — Restricts to `http:` and `https:` protocols exclusively - **IP literal detection** — Blocks direct IP addresses to prevent internal network probing - **Redirect verification** — Validates final destinations against the same safety rules - **Refusal list matching** — Blocks paid-template marketplaces, signature designer works, and copyrighted art repositories If any check fails, the verb **falls back to requesting a manual screenshot** rather than proceeding unsafely. --- ## Output Formats: Diagnosis Reports and Portable Design Files ### Standard Diagnosis Output By default, `hallmark study` generates two artifacts: 1. A **machine-readable JSON schema** containing the full extraction 2. A **human-readable diagnosis report** with mode-specific templates ### Optional [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) Emission For reusable design specifications, explicitly request portable output: ```bash hallmark study \ --url https://example.com \ --emit-design ``` This creates a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file containing extracted DNA, provenance documentation, and anti-pattern warnings. The format follows [[`design-md.md`](https://github.com/Nutlope/hallmark/blob/main/design-md.md)](https://github.com/Nutlope/hallmark/blob/main/design-md.md) specifications, enabling subsequent Hallmark runs to reference this structured design brief. --- ## Key Limitations by Design The `hallmark study` verb maintains strict boundaries to preserve ethical and legal safety: - **Never copies images** — All analysis is descriptive, not reproductive - **Never executes code** — Fetched content is parsed, not rendered or run - **Never alters files** — Read-only operations unless `--emit-design` is explicitly requested - **Rhythm gap in URL mode** — Temporal behavior cannot be inferred without interaction - **Font uncertainty in image mode** — Rasterized text limits type identification These constraints align with the verb's core purpose: **understanding structure without appropriation**. --- ## Integration with Hallmark Workflow The `study` verb sits at the **research phase** of the Hallmark design pipeline. As 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), extracted [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) files feed directly into subsequent verbs that handle implementation, adaptation, and generation tasks. CLI entry point configuration in [[`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json)](https://github.com/Nutlope/hallmark/blob/main/package.json) declares the `hallmark` binary and dependencies powering the study verb's fetching, parsing, and schema validation logic. --- ## Summary - The `hallmark study` verb extracts **design DNA** through a standardized **Surface → Type → Structure → Motion → Rhythm** protocol - Operates in **two modes**: local screenshot analysis or remote URL fetching with layered **safety checks** - Produces **structured JSON schemas** and human-readable reports; optionally emits **portable [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) files** - Maintains **read-only, non-reproducible behavior** to respect copyright and prevent asset copying - Documented comprehensively 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) with implementation details 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) --- ## Frequently Asked Questions ### What is the `hallmark study` verb used for? The `hallmark study` verb provides designers with a **repeatable, ethically-sound method to analyze reference designs**—whether from screenshots or live URLs—without copying visual assets. It produces structured documentation of colour systems, typography, layout architecture, and motion patterns that designers can reference when building original work. ### How does `hallmark study` handle copyright and safety? The verb implements a **multi-layer safety system** including a refusal list of protected works, URL scheme validation, IP literal blocking, and redirect verification. It treats all fetched content as untrusted, never executes code, and never reproduces images. If safety checks fail, the tool requests manual screenshot submission rather than bypassing protections. ### What are the limitations of each source mode? **Image mode** cannot reliably identify font names from rasterized text and infers motion only through static visual cues. **URL mode** extracts exact CSS values including precise colour tokens and declared fonts, but cannot capture rhythm and temporal behavior without interactive analysis. Both modes deliberately avoid reproducing proprietary assets. ### Can `hallmark study` output be used in other tools? Yes. The JSON schema follows a standardized format, and the optional `--emit-design` flag produces a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file conforming to the portable specification. This file includes provenance information and anti-pattern guidance, making it consumable by downstream Hallmark verbs and potentially other design systems that implement compatible parsers.