Hallmark Data Model and Schema: The Complete 40-Field JSON Structure Explained

Hallmark uses a single structured-fields JSON schema with approximately 40 fields defined in study.md as the source of truth for all design extraction and build steps.

The Hallmark data model powers every stage of design analysis, from ingesting a screenshot or URL to generating a portable design.md specification. According to the Nutlope/hallmark repository, this schema acts as a strict contract between the extraction engine, the diagnosis report, and the theme mapping layer.

What Is the Hallmark Schema?

The Hallmark schema is a flat JSON object with nested sub-objects that completely describes a web page's visual DNA. It is stored in skills/hallmark/references/study.md and serves as the single source of truth for downstream operations.

The schema is mode-agnostic: both image mode and URL mode populate the same fields, though URL mode fills "mode-conditional" fields with exact values extracted from fetched HTML/CSS.

Schema Categories and Key Fields

Category	Purpose	Example Fields
Source	Input provenance	source_mode, source_url, refusal
Safety	Security validation	remote_safety (sub-object with 7 flags)
Macrostructure	Page architecture	macrostructure, hero, pitch, nav, footer
Typography	Typeface roles and pairings	display_role, body_face, pairing_logic
Colour	Paper and accent values	paper_band, accent_value, accent_footprint
Rhythm	Visual density and motion	density, asymmetry, motion_library
Provenance	Audit trail for exports	source_mode-related flags

Complete Schema Structure (from study.md)

According to the Hallmark source code, the full schema definition resides in a fenced JSON code block within skills/hallmark/references/study.md:

{
  "source_mode": "image | url",
  "source_url": "<the URL if source_mode=url, else null>",
  "source": "user-described | public-reference | unknown",
  "refusal": "ok | refused (paid-template) | soft-refusal (signature work)",
  "remote_safety": {
    "public_web_url": true,
    "scheme": "https | http | null",
    "ip_literal_detected": false,
    "redirects_checked": "true | false | fallback-requested | unknown | null",
    "fetched": ["html", "same-origin-css", "font-css"],
    "scripts_ignored": true,
    "prompt_injection_detected": false
  },
  "macrostructure": "<name from macrostructures.md>",
  "macrostructure_alt":"<second-closest, if it leans>",
  "hero": { "archetype":"H1‑Marquee …", "knobs":{ "<knob>":"<value>" } },
  "pitch":{ "archetype":"…", "knobs":{ … } },
  "nav":{ "archetype":"N1 …", "knobs":{ … } },
  "footer":{ "archetype":"Ft1 …", "knobs":{ … } },
  "display_role":"italic editorial serif | …",
  "display_face":"<exact font name in URL mode, else null>",
  "body_role":"neutral grotesque | …",
  "body_face":"<exact font name in URL mode, else null>",
  "label_role":"monospace | …",
  "label_face":"<exact font name in URL mode, else null>",
  "pairing_logic":"single family | two families | three families",
  "paper_band":"dark <30 | mid 30‑85 | light >85",
  "paper_value":"<exact oklch/hex/rgb in URL mode, else null>",
  "paper_hue":"warm | cool | neutral‑warm | neutral‑cool | chromatic‑<hue>",
  "accent_hue_band":"warm‑red | orange | yellow | green | teal | cyan‑blue | indigo | magenta | neutral",
  "accent_value":"<exact oklch/hex/rgb in URL mode, else null>",
  "accent_footprint":"small ≤5% | recurring 5‑15% | flood >15%",
  "density":"generous | medium | dense | unknown (URL mode)",
  "asymmetry":"centred | left‑biased | right‑biased | asymmetric‑grid | unknown (URL mode)",
  "treatments":["riso","grain‑overlay","…"],
  "reveal":"none | fade‑up | sweep | …",
  "motion_library":"framer‑motion | gsap | lottie | lenis | motion | none",
  "anti_patterns":["bouncy hover","transition‑all","…"]
}

All fields are required unless explicitly marked "null" or "unknown (URL mode)".

Mode-Conditional Field Behavior

The Hallmark schema handles two input modes with unified field names:

• Image mode: Populates descriptive bands (paper_band, display_role) with qualitative values like "light >85" or "italic editorial serif". Mode-conditional fields return null.

• URL mode: Fills exact-value fields (paper_value, display_face) with precise data extracted from fetched CSS—e.g., "oklch(96% 0.01 90)" or "Inter".

This design ensures schema stability across extraction methods while allowing precise reconstruction when source code is available.

Practical Schema Usage

Building a Schema Manually for Testing

// example-schema.js
const hallmarkSchema = {
  source_mode: "url",
  source_url: "https://example.com",
  source: "public-reference",
  refusal: "ok",
  remote_safety: {
    public_web_url: true,
    scheme: "https",
    ip_literal_detected: false,
    redirects_checked: "true",
    fetched: ["html", "same-origin-css", "font-css"],
    scripts_ignored: true,
    prompt_injection_detected: false
  },
  macrostructure: "Split Studio",
  macrostructure_alt: null,
  hero: { archetype: "H2‑Split", knobs: { ratio: "6/6", right: "proof", divider: "hairline" } },
  nav: { archetype: "N1‑Standard", knobs: {} },
  footer: { archetype: "Ft3‑Index", knobs: { columns: "4" } },
  display_role: "italic editorial serif",
  display_face: "Inter",
  body_role: "neutral grotesque",
  body_face: "Inter",
  label_role: "monospace",
  label_face: null,
  pairing_logic: "two families",
  paper_band: "light >85",
  paper_value: "oklch(96% 0.01 90)",
  paper_hue: "warm",
  accent_hue_band: "neutral",
  accent_value: "#000000",
  accent_footprint: "small ≤5%",
  density: "generous",
  asymmetry: "centred",
  treatments: [],
  reveal: "none",
  motion_library: "framer-motion",
  anti_patterns: []
};

console.log(JSON.stringify(hallmarkSchema, null, 2));

Generating design.md from Schema Data

import fs from "fs";

function generateDesignMD(schema) {
  const header = `/* Hallmark · macrostructure: ${schema.macrostructure} · theme: studied-DNA */\n`;
  const system = `## System\n- Display: ${schema.display_role} (${schema.display_face || "candidate"})\n- Body: ${schema.body_role} (${schema.body_face || "candidate"})\n`;

  const tokens = `## Tokens\n- Paper: ${schema.paper_value || schema.paper_band}\n- Accent: ${schema.accent_value || schema.accent_hue_band}\n`;

  const provenance = `## Provenance\n- Source mode: ${schema.source_mode}\n- URL: ${schema.source_url || "N/A"}\n`;

  return header + system + tokens + provenance;
}

fs.writeFileSync("design.md", generateDesignMD(hallmarkSchema));

Schema-Dependent Reference Files

The Hallmark data model references several canonical files in skills/hallmark/references/:

File	Schema Role
study.md	Primary schema definition and extraction protocol
macrostructures.md	21 named macro-structures for the macrostructure field
component-cookbook.md	Archetype definitions and knob tables for hero, nav, pitch, footer
design-md.md	Output format specification for serialized schemas
SKILL.md	Overview of the hallmark study verb and schema workflow

How the Schema Powers Hallmark's Pipeline

Once populated, the schema drives three downstream operations:

1. Diagnosis report: Compares extracted values against reference databases in macrostructures.md and component-cookbook.md.

2. Theme mapping: Suggests named themes (e.g., Studio, Midnight, Riso) based on field combinations. This mapping is non-binding—users may override.

3. design.md export: Serializes the complete schema to a portable, version-controlled specification.

Summary

• Hallmark's data model is a 40-field JSON schema defined in skills/hallmark/references/study.md.
• The schema serves as a strict contract between extraction, analysis, and build phases.
• Mode-conditional fields handle both image and URL inputs with unified structure.
• Reference files (macrostructures.md, component-cookbook.md) provide controlled vocabularies for key fields.
• The schema enables reproducible design systems through design.md export.

Frequently Asked Questions

What file contains the complete Hallmark schema definition?

The complete schema is defined in skills/hallmark/references/study.md within a fenced JSON code block. This file specifies all ~40 fields, their valid values, and extraction rules for both image and URL modes.

Is the Hallmark schema the same for screenshots and URLs?

Yes. Both modes use identical field names, but URL mode populates "mode-conditional" fields (*_value, *_face, motion_library) with exact extracted data while image mode leaves these as null and relies on descriptive bands.

What is the remote_safety sub-object used for?

The remote_safety field contains 7 security flags that validate URL inputs: public_web_url, scheme, ip_literal_detected, redirects_checked, fetched, scripts_ignored, and prompt_injection_detected. This enables safe, auditable extraction from remote sources.

How does Hallmark map schema data to themes?

After schema population, Hallmark suggests named themes (e.g., Studio, Midnight) based on field combinations. However, theme mapping is advisory only—the schema remains the authoritative source and users may override suggestions.

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