How to Use Hallmark Study to Extract Design DNA from Screenshots

The hallmark study command analyzes screenshots or public URLs to generate a structured design DNA containing macro-structures, color palettes, typography roles, and motion cues without copying pixel-exact content.

The hallmark CLI by Nutlope provides a study verb that acts as a diagnostic tool for design systems. Whether you upload a screenshot or point to a live URL, the command executes a five-step protocol defined in skills/hallmark/references/study.md to reverse-engineer the underlying design principles into a reusable specification.

What Is Hallmark Study?

hallmark study serves as the diagnosis verb of the Hallmark skill. It reads a reference—either a local screenshot or a public URL—and produces a structured design DNA that captures macro-structures, color palettes, type roles, archetype knobs, and motion cues. The tool never copies pixel-exact content; instead, it abstracts the underlying design decisions into a portable format.

The Five-Step Design DNA Extraction Protocol

The extraction process follows a strict protocol defined in skills/hallmark/references/study.md. Each step transforms raw visual input into structured design tokens.

Step 1: Source Mode Detection

The system first determines how to process the input. According to the study reference file, any value starting with http:// or https:// triggers URL mode, while all other inputs are treated as attached images in image mode (study.md#L11-L14). This distinction determines which extraction methods are available downstream.

Step 2: Surface Extraction

In this phase, the tool identifies the visual surface qualities of the design. For screenshots, a vision pass extracts color bands, hue distributions, and accent footprints. In URL mode, the system reads CSS :root custom properties directly from the stylesheet (study.md#L14-L21). This captures the raw color DNA without sampling individual pixels.

Step 3: Type Extraction

Typography analysis assigns roles (display, body, label) to text elements. When operating in URL mode, the system can pull exact font names from @font-face declarations, Google Fonts links, or hard-coded font-family values found in the CSS (study.md#L22-L44). Image mode relies on visual inference rather than parsing CSS rules.

Step 4: Structure Extraction

The page architecture is matched against one of 21 named macro-structures documented in skills/hallmark/references/macrostructures.md. Each visible region receives an archetype classification plus specific "knob" variations that define the layout's configuration (study.md#L45-L58). This maps the visual hierarchy to a reusable structural pattern.

Step 5: Motion and Rhythm

The final extraction phase captures motion libraries (such as framer-motion or gsap) and reveal patterns from scripts and CSS. Note that rhythm analysis remains a blind spot in URL mode; the report explicitly notes this limitation when analyzing live sites (study.md#L60-L78).

Generating the Diagnosis Report

After extraction, all values populate a JSON schema defined at the bottom of skills/hallmark/references/study.md. The system then renders this data into a concise human-readable diagnosis report using either the image-mode or URL-mode template (study.md#L68-L98). The report presents the design DNA in a structured format suitable for review and approval.

Locking and Reusing Design DNA

Once you approve the diagnosis, you have two pathways to preserve the design DNA:

• Lock to file: Respond with "lock the DNA" when prompted, and the skill writes a portable design.md file following the format specified in skills/hallmark/references/design-md.md. This file contains the exact tokens, fonts, and provenance information (study.md#L81-L100).
• Direct reuse: The default Hallmark verb can consume the DNA immediately to rebuild a page with the same macro-structure and style but fresh content.

Important Safeguards and Refusal Rules

Before extraction begins, hallmark study evaluates a set of refusal rules to protect intellectual property. The system refuses to process paid-template marketplaces, signature-designer work, and copyrighted imagery (study.md#L75-L88). This ensures the tool extracts design principles from legitimate reference material without copying protected assets.

Practical Usage Examples

Extract DNA from a local screenshot:

hallmark study ./screenshots/hero-mybrand.png

Extract DNA from a public URL (triggers URL-mode pipeline):

hallmark study https://www.usehallmark.com/examples/tally/

After receiving the diagnosis, lock the DNA to a portable specification:

# Respond "lock the DNA" when prompted

# Output: design.md file in current directory

Use the generated specification in subsequent builds:

hallmark default --design-md ./design.md

Summary

• hallmark study is the diagnostic verb that extracts design DNA from screenshots or URLs without copying pixels.
• The five-step protocol in skills/hallmark/references/study.md handles source detection, surface extraction, type analysis, structure mapping, and motion capture.
• URL mode enables exact font extraction and CSS variable reading, while image mode relies on computer vision.
• The tool maps layouts to 21 macro-structures defined in macrostructures.md.
• You can lock DNA to a portable design.md file or use it directly for rebuilding.
• Built-in refusal rules prevent extraction from copyrighted or paid-template sources.

Frequently Asked Questions

What file format does the design DNA get locked into?

When you approve the diagnosis and request to "lock the DNA," the skill writes a design.md file following the schema defined in skills/hallmark/references/design-md.md. This markdown file contains the exact design tokens, font specifications, color values, and provenance information in a portable format that can be reused across projects.

Can hallmark study extract fonts from a screenshot?

In image mode (screenshots), the tool assigns typography roles (display, body, label) through visual inference but cannot identify exact font names. In URL mode, the system parses @font-face declarations, Google Fonts links, and font-family CSS properties to extract precise font names (study.md#L22-L44).

What are the 21 macro-structures mentioned in the protocol?

The 21 macro-structures are predefined layout patterns documented in skills/hallmark/references/macrostructures.md. When hallmark study analyzes a page, it matches the visual hierarchy against these patterns—such as hero-split, feature-grid, or editorial-flow—and assigns the appropriate archetype to the design DNA.

Does hallmark study work with any website URL?

The tool accepts any public URL starting with http:// or https://, but it implements refusal rules that block paid-template marketplaces, signature-designer portfolios, and sites containing copyrighted imagery (study.md#L75-L88). The extraction only proceeds if the source passes these intellectual property checks.

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