How the Hallmark Study Verb Extracts Design DNA from Screenshots

The hallmark study verb analyzes screenshots through a five-step vision protocol to generate a structural "design DNA"—capturing macrostructure, color bands, typography roles, and layout archetypes without copying pixel data.

The Hallmark study verb, documented in [study.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md), serves as a diagnostic tool within the Nutlope/hallmark repository that transforms static visual references into reusable design specifications. Unlike simple image analysis, this process extracts a structural fingerprint that can be handed off to other verbs for generating new pages. The system distinguishes between image mode (screenshots) and URL mode (live pages), applying a specialized vision-pass when handling static image inputs.

Source Mode Detection

Before extraction begins, the verb determines whether it operates in image mode or URL mode. Any input that does not parse as a valid URL automatically defaults to image mode, triggering the screenshot-specific analysis pipeline. This detection logic ensures the system applies the appropriate level of inference—recognizing that static images lack temporal data, interactive states, and precise font file information.

The Five-Step Vision Protocol

When processing screenshots, the verb executes a disciplined five-step protocol defined in [study.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md). Each step targets a specific design dimension while acknowledging the limitations of image-only analysis.

Step 1: Surface Analysis

The verb estimates color bands by analyzing the screenshot's visual properties. It records:

• Paper darkness and hue (warm cream, cool gray, etc.)
• Accent hue and footprint (the relative surface area occupied by accent colors)
• Distinctive treatments such as grain textures, glassmorphism, or noise overlays

This step captures the atmospheric foundation of the design without requiring access to the original CSS or asset files.

Step 2: Type Role Extraction

Because screenshots cannot reliably reveal exact font files or font-family declarations, the verb operates on type roles rather than specific typefaces. It identifies descriptors like "italic editorial serif" for headlines or "neutral grotesque" for body text, then proposes one to two candidate fonts from the Hallmark canon (such as Instrument Serif or Tobias) based on visual similarity. This approach avoids false precision while maintaining typographic intent.

Step 3: Structure Mapping

The verb maps visible screen regions to one of twenty-one named macrostructures defined in [macrostructures.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md). For each identified region, it assigns archetype knobs—parameterized variations that describe the layout's proportions and hierarchy. For example, an H2-Split macrostructure might carry the knob ratio=7/5, indicating the asymmetrical balance between content zones. These mappings draw from the component logic documented in [component-cookbook.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/component-cookbook.md).

Step 4: Motion Assessment

Static screenshots provide no animation data. During this step, the verb explicitly records "motion not visible – assuming default reveals" rather than hallucinating transition behaviors. This conservative approach prevents the propagation of incorrect motion assumptions into the generated DNA.

Step 5: Rhythm Evaluation

Rhythm represents a gestalt judgment requiring temporal or interactive context that single images cannot provide. The verb marks rhythm as "unknown" and flags this limitation in the diagnosis report, ensuring users understand that pacing and flow must be defined through other means.

Structured Schema Generation

After completing the five passes, the verb populates a JSON-like schema with required fields for every design dimension. Fields that cannot be determined in image mode receive "unknown" values or null assignments rather than speculative guesses. The schema structure includes:

• Macrostructure identifier and archetype knobs
• Color band tokens (surface, accent, neutral)
• Type role pairings and candidate font suggestions
• Distinctive treatment flags
• Anti-pattern detections (referencing [anti-patterns.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md))

This structured data ensures the extracted DNA remains portable and implementation-agnostic.

Diagnosis Report and Hand-Off

The extracted schema renders into a concise, human-readable diagnosis report following the image-mode template in [study.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md). The report lists the identified macrostructure, type roles, color bands, accent footprint, distinctive treatments, and any flagged anti-patterns.

Users can then choose from three hand-off options:

• Build immediately: Invoke the default verb to generate a page using the extracted DNA
• Lock the DNA: Emit a portable design.md file for version control or manual editing
• Iterative refinement: Modify specific axes before proceeding

Extracting DNA: Practical Examples

Run the study verb against any screenshot file:

hallmark study screenshot.png

Sample output:

You sent me a Split Studio.

The hero is an H2-Split … …
The type pairing is italic editorial serif with neutral grotesque body, monospace for labels.
I won't try to identify exact typefaces from a screenshot — fonts to consider:
Instrument Serif, Tobias.
The surface is warm cream … The accent is neutral ….
...
Want me to build with this DNA, or change one axis first?

To capture the extracted DNA into a reusable specification file:

hallmark study screenshot.png

# (After receiving the diagnosis, respond:)

lock the DNA

This generates a design.md file at the project root, containing the complete DNA—including macrostructure definitions, design tokens, system blocks, and provenance data—as specified in [design-md.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md).

Building from Extracted DNA

Apply the studied design DNA to a new page generation:

hallmark default --use-study-dna

The default verb reads the previously generated design.md (or the in-memory schema) and constructs a page inheriting the studied color bands, type roles, macrostructure, and archetype knobs. This pipeline ensures that the study verb never copies pixel data; it only captures the structural fingerprint safe for reuse in new design contexts.

Summary

• The hallmark study verb operates in image mode when receiving non-URL inputs, triggering a specialized five-step analysis protocol.
• Design DNA extraction captures macrostructures, color bands, type roles, and archetype knobs while explicitly marking unknowns for motion and rhythm.
• The process references canonical files including [study.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/study.md), [macrostructures.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md), and [design-md.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md).
• Users can hand off the extracted DNA to the default build verb or serialize it to design.md for portable reuse.
• The system avoids pixel-level copying, focusing instead on reusable structural abstractions that respect design provenance.

Frequently Asked Questions

Can the study verb identify exact font files from a screenshot?

No. The verb deliberately avoids identifying exact typefaces from static images due to the high risk of false positives. Instead, it records type roles (such as "italic editorial serif" or "neutral grotesque") and suggests one to two candidate fonts from the Hallmark canon that match the visual characteristics. This approach maintains accuracy while providing actionable typographic direction.

What happens to motion and rhythm analysis in image mode?

Static screenshots cannot display animation or interactive pacing. During the motion and rhythm steps of the five-step protocol, the verb records these values as "unknown" or assumes conservative defaults ("motion not visible – assuming default reveals"). Users must define motion behaviors manually or through URL-mode analysis of live pages.

How does the verb handle design anti-patterns?

The study verb references [anti-patterns.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md) to detect and flag problematic design constructs during the structure and surface analysis phases. Detected anti-patterns appear in the diagnosis report but are excluded from the extracted DNA, ensuring that inherited design systems propagate only validated structural patterns.

What is the difference between study output and design.md?

The standard study output produces a human-readable diagnosis report optimized for immediate review and decision-making. When you invoke lock the DNA (or the equivalent command), the system serializes the structured schema into a machine-readable design.md file following the format defined in [design-md.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md). This portable file can be versioned, edited manually, or passed to other Hallmark verbs for page generation.

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