What Is the Purpose of the Hallmark `study` Verb?

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, 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). 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:

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:

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 Emission

For reusable design specifications, explicitly request portable output:

hallmark study \
  --url https://example.com \
  --emit-design

This creates a 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) 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), extracted 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) 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 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) with implementation details in [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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}