How to Use the Hallmark Study Verb: Extract Design DNA from URLs and Screenshots

The hallmark study verb extracts the structural design DNA from any live URL or screenshot, generating a diagnosis report of macro-structure, archetypes, and type-pairing without copying pixel data.

The hallmark study verb in the Nutlope/hallmark repository enables you to analyze existing web designs and generate reusable design specifications. This tool parses visual and structural elements to create a portable design.md file that captures the essence of a reference without infringing on copyright.

How the Hallmark Study Verb Works

The verb operates through a five-stage pipeline defined in skills/hallmark/references/study.md.

Mode detection determines whether the input is a URL (starting with http:// or https://) or an image file. Refusal checks block copyrighted templates from marketplaces like themeforest.net or templatemonster.com, and URL mode runs a safety scan before fetching. Extraction parses HTML/CSS in URL mode or runs a vision pass in image mode to populate the structured-fields schema. The diagnosis report generates a human-readable summary. Finally, the system presents follow-up actions for the user to choose from.

URL Mode vs. Image Mode

In URL mode, the tool pulls exact font names, colour values, and motion library references from the live site's CSS. Before emitting a design.md file, Hallmark requires user attestation that the source is either their own work or a public reference.

In image mode, the screenshot is treated as user-owned content, allowing immediate design.md emission without attestation, though exact font names may be null and rhythm detection is added.

Practical Usage Examples

Study a live website using URL mode:

hallmark study https://example.com/awesome-landing

Study a local screenshot using image mode:

hallmark study ./my-screenshot.png

Emit a reusable design specification file:

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

Understanding the DNA Diagnosis Report

The report structure follows the extraction protocol in references/study.md and includes:

• Macrostructure: High-level layout pattern (e.g., "Marquee Hero")
• Archetypes: Component patterns like "Header-Nav" or "Feature-Grid"
• Type-pairing: Font combinations with specific weights
• Colour anchor: Primary hue designation (e.g., "desaturated forest-green")
• Rhythm: Vertical stacking patterns (image mode only)
• Anti-patterns: Detected usability issues

Typical output format:

🧬 DNA Diagnosis Report
Macrostructure: Marquee Hero
Archetypes:   Header-Nav, Hero-Media, Feature-Grid
Type-pairing:   Display – Inter (regular), Body – Source (regular)
Colour anchor:   desaturated forest-green (hue ≈ 110°)
Rhythm:         (image-mode only) 3-step vertical stacking

Post-Study Workflows

After receiving the diagnosis, three paths exist according to the verb definition in skills/hallmark/SKILL.md:

1. Rebuild: Hand off to hallmark redesign to apply the DNA to new content
2. Lock: Generate a portable design.md file per the format specified in skills/hallmark/references/design-md.md
3. Stop: Use the analysis without further action

Implementation Details

The verb definition lives in skills/hallmark/SKILL.md, which catalogs the "hallmark study <screenshot | URL>" syntax. The UI entry point in site/index.html (lines 402-419) displays the command badge. Example extractions are documented in docs/study-examples.md.

Summary

• The hallmark study verb analyzes URLs or images to extract structural design DNA without copying pixels
• URL mode provides exact CSS values but requires ownership attestation before emitting design.md
• Image mode adds rhythm detection and skips attestation since the screenshot is user-owned
• Refusal checks block marketplace templates and unsafe URLs automatically
• Extracted DNA can be rebuilt with hallmark redesign or locked into a portable design.md file

Frequently Asked Questions

Does Hallmark study copy the actual design files or code?

No. According to the extraction protocol in references/study.md, the verb only extracts structural information such as macrostructure, archetypes, and type-pairing. It never copies pixel data or source code, making it safe for copyright-compliant design inspiration.

Can I study any website with the Hallmark study verb?

No. The verb includes refusal checks that block sites on the marketplace refuse list, including themeforest.net/* and templatemonster.com/*. Additionally, URL mode runs a safety scan before fetching, and emission of design.md requires attestation that the source is your own work or a public reference.

What is the difference between URL mode and image mode?

URL mode parses live HTML/CSS to extract exact font names, colour values, and motion libraries, but requires user attestation before saving to design.md. Image mode analyzes screenshots using computer vision, which may leave exact font fields null but adds rhythm detection, and requires no attestation since you own the screenshot.

How do I save the extracted design DNA for later use?

Run hallmark study <input> --emit-design to generate a design.md file formatted according to skills/hallmark/references/design-md.md. In URL mode, you must confirm the source is your own work or public domain before the file is written; image mode emits immediately.

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