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

> Explore the Hallmark architecture Discover its modules skill definition rule-set demo site packaging documentation plus callable verb and internal runtime services for efficient design flow.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: architecture
- Published: 2026-08-03

---

**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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/package.json)).
- **`skills/hallmark/references/`** – Contains all rule files:
  - [`macrostructures.md`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md) – Index of 21 named macrostructures
  - [`genres/modern-minimal.md`](https://github.com/Nutlope/hallmark/blob/main/genres/modern-minimal.md) – Genre definitions
  - [`themes/lumen.md`](https://github.com/Nutlope/hallmark/blob/main/themes/lumen.md) – Theme specifications (palette, display style, accent hue)
  - [`anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/anti-patterns.md) – Rules for detecting design slop
  - [`slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/site/index.html)** – The live demo page
- **[`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css)** – Global CSS tokens (color, spacing, font variables)
- **[`site/css/base.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/base.css)** – Base reset and layout utilities
- **[`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/package.json)** – Registers the skill for `npx skills add` and points the harness to [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)
- **[`README.md`](https://github.com/Nutlope/hallmark/blob/main/README.md)** – Installation and quick-start guide
- **[`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/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

```bash

# 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:

```css
/* 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`](https://github.com/Nutlope/hallmark/blob/main/package.json), [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/references/slop-test.md) to ensure output quality.

## Key File Reference Map

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

## Summary

- **Three logical modules** organize Hallmark: the skill definition with its rule-set ([`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) + `references/`), the static demo site (`site/`), and packaging/documentation ([`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json), [`README.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)**, which is referenced by [`package.json`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.