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

> Master Hallmark best practices with this guide. Leverage CLI verbs audit redesign study and the 57-check slop-test gate system for efficient quality enforcement and workflow iteration.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: best-practices
- Published: 2026-07-26

---

**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](https://github.com/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) specification

*Source: [README – Four verbs](https://github.com/Nutlope/hallmark/blob/main/README.md#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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)) and all reference assets into the appropriate user directory.

```bash
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](https://github.com/Nutlope/hallmark/blob/main/README.md#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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md), including **gate 23** which specifically flags verbatim recipe copying.

```bash
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.

```bash
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`](https://github.com/Nutlope/hallmark/blob/main/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.

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

```

> **Tip:** The emitted [`design.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md)*

## Working with Randomized Design Fingerprints

Hallmark stores a per-project log at [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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.

```bash

# 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.