Best Practices for Using Hallmark: A Complete Guide to Design-Skill Workflows

The best practices for using Hallmark involve leveraging the three CLI verbs (audit, redesign, study), utilizing the 57-check slop-test gate system to enforce quality, and iterating through brief modifications rather than editing generated HTML files.

Hallmark is an open-source design-skill that generates fully-styled HTML and CSS pages from high-level briefs. According to the Nutlope/hallmark repository, maximizing output quality requires understanding its architecture—including verbs, macrostructures, themes, and the slop-test quality assurance system. These best practices for using Hallmark ensure you produce unique, anti-pattern-free static sites while maintaining complete creative control over the design process.

Understanding Hallmark's Core Architecture

Hallmark operates through a layered architecture defined in skills/hallmark/SKILL.md. The system combines randomized structural choices with strict quality gates to ensure each generated page feels custom while avoiding generic AI-generated aesthetics.

The Four Verbs

The CLI provides four entry points that drive distinct workflows:

• audit – Scores existing code against Hallmark's quality standards and identifies anti-patterns
• redesign – Rebuilds a page from existing copy and information architecture (IA)
• study – Extracts design DNA (macrostructure, theme, typography) from a live URL and emits a portable design.md specification

Source: README – Four verbs

Macrostructures and Themes

Hallmark selects from 21 macrostructures (e.g., Long Document, Quote-Led, Bento Grid) that define page layout topology. This selection pairs with 20 curated themes (e.g., Linen, Cobalt, Carnival) supplying color palettes and typography. Both choices are randomized per run unless explicitly overridden via custom theme mode.

Source: skills/hallmark/references/macrostructures.md and skills/hallmark/references/themes/

Enrichment Archetypes and Slop-Test Gates

After selecting macrostructure and theme, Hallmark applies an enrichment tier ranging from "Tier-A" (rich SVG art) to "Tier-C" (plain typographic layout). This tier is determined by the slop-test gate system, which runs 57 quality checks to guarantee layout integrity and prevent AI-generated visual clichés.

Source: skills/hallmark/SKILL.md

Installation and Setup

Install Hallmark into Claude Code, Cursor, or Codex environments using the skills CLI. This copies the rule-set (SKILL.md) and all reference assets into the appropriate user directory.

npx skills add nutlope/hallmark

Re-run this command periodically to pull new themes, macrostructures, and enrichment tiers as the repository updates.

Source: README – Install

Mastering the Three Primary Verbs

Effective Hallmark workflows rely on understanding when to apply each verb command.

Audit Existing Code

Before editing legacy projects, run the audit verb to surface anti-patterns and accessibility violations. This command evaluates code against the standards defined in skills/hallmark/references/anti-patterns.md, including gate 23 which specifically flags verbatim recipe copying.

hallmark audit ./my-old-site

Redesign from Briefs

The redesign verb ingests a target folder, extracts copy and IA, and writes a self-contained HTML and CSS site using a fresh macrostructure and theme combination.

hallmark redesign .

Outputs appear in site/_tests/ and should be committed as static assets. Never edit these generated files directly—changes will be overwritten on the next run.

Study External Inspiration

Use the study verb to extract design DNA from live URLs. This emits a design.md file containing the macrostructure, theme, and typographic choices from the target site, which you can then feed back into hallmark redesign for a new execution while preserving the original copy and IA.

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

Tip: The emitted design.md serves as a portable specification. Combine it with custom theme parameters to iterate on competitor aesthetics without violating copyrights.

Source: docs/recipes.md

Working with Randomized Design Fingerprints

Hallmark stores a per-project log at .hallmark/log.json that prevents the same macrostructure and theme combination from repeating across runs. To generate a fresh design fingerprint:

1. Re-run hallmark redesign . to trigger new randomization
2. Verify the log file updated to track the new combination

This ensures each iteration produces a unique visual output while maintaining content consistency.

Implementing Custom Themes

When catalog themes cannot express your brand requirements, use Custom mode by defining a bespoke palette, typography, and layout in skills/hallmark/references/custom-theme.md. Reference this file via the hallmark redesign verb to bypass the 20 standard themes while retaining the full slop-test gate enforcement.

# Example workflow with custom theme

hallmark redesign . --theme custom

The custom theme file follows the same specification format as the Terminal theme demonstrated in the Streampipe recipe documentation.

Quality Assurance and Anti-Patterns

The slop-test system guards against anti-patterns documented in skills/hallmark/references/anti-patterns.md. Key protections include:

• Layout integrity checks – Ensures grid systems maintain responsive behavior
• Semantic markup validation – Enforces proper HTML5 element usage
• Anti-copying gates – Prevents verbatim duplication of recipe outputs (gate 23)

Always review the anti-patterns list before submitting generated sites to production, as these rules define Hallmark's standards for "non-sloppy" design.

Summary

• Use hallmark audit before modifying existing codebases to identify anti-patterns early
• Leverage hallmark study to extract portable design specifications from inspiration URLs
• Commit generated sites from site/_tests/* as version-controlled static assets, but never edit them directly
• Maintain iteration logs via .hallmark/log.json to track design fingerprints and prevent repetition
• Extend via custom themes when brand requirements exceed the 20 catalog themes, while allowing slop-test gates to maintain quality
• Update regularly using npx skills add nutlope/hallmark to access new macrostructures and quality checks

Frequently Asked Questions

How do I prevent Hallmark from generating the same design twice?

Hallmark automatically tracks generated macrostructure and theme combinations in .hallmark/log.json. To force a new design fingerprint, simply re-run hallmark redesign .—the system checks this log file and randomizes selections to avoid repeats.

Can I use Hallmark with brand-specific colors and fonts?

Yes. When standard themes are insufficient, activate Custom mode by creating a specification in skills/hallmark/references/custom-theme.md. This allows bespoke visual definitions while still enforcing the 57-check slop-test gate system for quality assurance.

What should I do if Hallmark produces a "sloppy" or generic-looking design?

Run hallmark audit on the output to identify which of the 57 slop-test gates failed. Common issues include layout integrity violations or AI-generated visual clichés flagged in skills/hallmark/references/anti-patterns.md. Adjust your brief or macrostructure selection and regenerate.

Is it safe to edit the generated HTML files directly?

No. Generated files in site/_tests/ are ephemeral artifacts. Direct edits will be overwritten on the next hallmark redesign run. Instead, modify the source brief, custom theme parameters, or enrichment archetypes to achieve permanent changes.

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