What Are the Main Modules and Services in Hallmark? A Complete Architecture Guide

The Hallmark project is organized into three logical modules—a skill definition and rule-set, a static demo site, and packaging/documentation—plus four callable verb services (audit, redesign, study, and default) and seven internal runtime services that execute the design flow.

Hallmark is an open-source design skill for AI coding assistants that generates anti-slop, diversified UI designs. Understanding what modules and services power Hallmark helps developers extend the skill, debug generated output, or integrate it into custom AI workflows. This guide breaks down the complete architecture based on the source code in Nutlope/hallmark.

The Three Core Modules

Skill Definition & Rule-Set

This is the heart of Hallmark. It declares the entry point, the four verbs (audit, redesign, study, and default), and stores every design rule.

Key source files:

• skills/hallmark/SKILL.md – The manifest and verb table. This is where the skill entry point is defined (skill.entry = "skills/hallmark/SKILL.md" in package.json).
• skills/hallmark/references/ – Contains all rule files:
  • macrostructures.md – Index of 21 named macrostructures
  • genres/modern-minimal.md – Genre definitions
  • themes/lumen.md – Theme specifications (palette, display style, accent hue)
  • anti-patterns.md – Rules for detecting design slop
  • slop-test.md – The 58-gate validation test

The skill reads these references at runtime to decide which macrostructure, theme, nav/footer archetype, and enrichment to emit.

Static Demo Site

Provides a runnable HTML + CSS + JS showcase hosted at usehallmark.com. The site contains the token system, base styling, component styles, and a minimal JavaScript loader.

Key source files:

• site/index.html – The live demo page
• site/css/tokens.css – Global CSS tokens (color, spacing, font variables)
• site/css/base.css – Base reset and layout utilities
• site/js/main.js – Theme rotation and hot-key handling

This site is also used by the CI test suite to verify that generated pages render correctly at four mobile breakpoints.

Packaging & Documentation

Describes how to install the skill in Claude Code, Cursor, or Codex, and supplies example briefs, screenshots, and a roadmap.

Key source files:

• package.json – Registers the skill for npx skills add and points the harness to SKILL.md
• README.md – Installation and quick-start guide
• docs/recipes.md – Worked examples for human readers

The Four Verb Services (CLI Entry Points)

These are the service surface that users invoke from the terminal after installing the skill with npx skills add nutlope/hallmark.

Verb	Service	What It Does
(default)	Design Flow	Full pipeline: pre-flight scan → macrostructure pick → theme route → visual ruleset → enrichment → preview → slop-test
audit	Audit Service	Scores existing code against the anti-pattern list without changing it
redesign	Redesign Service	Preserves existing implementation while swapping macrostructure/theme
study	Study Service	Extracts design DNA (macrostructure, type-pairing, color anchor) from a live URL or screenshot

Calling the Verb Services

# 1️⃣ Default design flow – build a new page from a brief

hallmark "Create a SaaS landing page for a new AI‑tool"

# 2️⃣ Audit – score an existing site without changing it

hallmark audit ./site/index.html

# 3️⃣ Redesign – keep copy / routes but change visual language

hallmark redesign ./site/index.html --mood modern-minimal

# 4️⃣ Study – extract DNA from a live URL (requires web fetch)

hallmark study https://www.usehallmark.com/examples/cobalt-01/

Each command triggers the corresponding service, and the output includes a stamped comment referencing the chosen configuration:

/* Hallmark · macrostructure: Marquee Hero · theme: Bloom */

The Seven Runtime Services (Internal Modules)

These internal modules execute during the Design Flow. They are not directly callable but are orchestrated by the skill:

1. Pre-flight scanner – Reads package.json, tokens.css, tailwind.config.*, and other project files to understand the existing codebase.

2. Macrostructure picker – Loads a single file from references/macrostructures/ based on the brief.

3. Theme router – Chooses between catalog themes (from references/themes/) or custom theme generation.

4. Visual rules loader – Loads genre, typography, color, layout, motion, and anti-pattern definitions.

5. Hero enrichment selector – Optionally applies rules from hero-enrichment.md based on context.

6. Preview generator – Produces the markdown "what-I-am-about-to-ship" block for user confirmation.

7. Slop-test validator – Executes the 58-gate test defined in references/slop-test.md to ensure output quality.

Key File Reference Map

File Path	Role in Architecture
skills/hallmark/SKILL.md	Skill manifest; lists verbs and entry point
skills/hallmark/references/macrostructures.md	Index of 21 named macrostructures
skills/hallmark/references/themes/lumen.md	Example theme definition
site/css/tokens.css	Global CSS design tokens
site/css/base.css	Base reset and utilities
site/js/main.js	Demo site interactivity
package.json	NPM skill registration
docs/recipes.md	Human-readable examples

Summary

• Three logical modules organize Hallmark: the skill definition with its rule-set (SKILL.md + references/), the static demo site (site/), and packaging/documentation (package.json, README.md, docs/).

• Four verb services provide the CLI interface: default (full Design Flow), audit, redesign, and study.

• Seven runtime services execute internally: pre-flight scanner, macrostructure picker, theme router, visual rules loader, hero enrichment selector, preview generator, and slop-test validator.

• All outputs are stamped with metadata comments linking back to the specific macrostructure, theme, and diversification rules applied.

Frequently Asked Questions

What file defines the main entry point for the Hallmark skill?

The entry point is defined in skills/hallmark/SKILL.md, which is referenced by package.json via skill.entry. This manifest declares all four verbs and their behaviors.

How does Hallmark validate that generated designs are not "slop"?

The slop-test validator runs a 58-gate test defined in references/slop-test.md. This is the final runtime service in the Design Flow, executed after preview generation.

Can I use Hallmark to analyze an existing website without modifying it?

Yes. Use the hallmark audit verb service. It scores existing code against the anti-pattern list in references/anti-patterns.md without making changes.

What is the difference between the redesign and default hallmark services?

The default service runs the full Design Flow to build from a brief. The redesign service preserves your existing implementation (copy, routes, components) while swapping only the visual language—macrostructure, theme, and styling rules.

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