What Is Hallmark and What Does It Do? A Design Skill for AI Coding Assistants

Hallmark is a design skill for AI coding assistants like Claude Code, Cursor, and Codex that generates user-interface code specifically engineered to look handcrafted rather than AI-generated.

Hallmark is an open-source design skill hosted in the Nutlope/hallmark repository that encodes anti-AI-slop design rules to prevent generic LLM defaults. It operates as a structured skill package that AI assistants load to produce UI code respecting existing project palettes, typography, and motion libraries. Unlike standard code generation, Hallmark enforces strict quality gates and thematic consistency to ensure outputs feel intentionally designed.

Core Architecture and Components

The Hallmark ecosystem consists of several key components defined in the repository structure.

Skill Definition and Metadata

The skills/hallmark/SKILL.md file serves as the entry point that tells the host assistant what the skill does, defines its verbs, and establishes safety rails. This file declares Hallmark's purpose: to refuse generic defaults and instead apply a tight set of anti-pattern rules, slop-test gates, and token discipline.

The package.json at the repository root declares the skill as a Node module, listing its entry file and supported harnesses including Claude Code, Cursor, and Codex. This metadata allows AI assistants to discover and load the skill dynamically.

Reference Libraries and Rulesets

The skills/hallmark/references/ directory contains markdown files with concrete design rules that Hallmark loads on demand. These include macrostructure definitions (21 named page structures like "Marquee Hero" and "Bento Grid"), twenty catalog themes plus custom theme specifications, typography and colour constraints, and anti-pattern lists.

Supporting Infrastructure

The site/ directory hosts a static site for live demos at usehallmark.com and generated page previews. The docs/ folder contains human-readable recipes, study examples, and slide decks illustrating intended usage patterns. During operation, Hallmark generates .hallmark/preflight.json to cache pre-flight scan results and .hallmark/log.json to track previous macrostructure selections for diversification enforcement.

How Hallmark Works: The Design Flow

Hallmark follows a rigorous seven-step process defined in SKILL.md to ensure quality output.

1. Pre-Flight Project Scan

Hallmark begins by reading existing project files including package.json, tailwind.config.*, and design.md to preserve the project's existing palette, fonts, and motion libraries. This scan populates .hallmark/preflight.json for faster subsequent runs.

2. Three-Question Prompt

Before generating any code, Hallmark asks the user for Audience, Use case, and Tone (or infers them from context). This constraint prevents generic outputs by establishing specific design parameters upfront.

3. Macrostructure Selection

Hallmark selects one of 21 named page structures (macrostructures) such as "Marquee Hero" or "Bento Grid". The system obeys diversification rules that prevent consecutive runs from reusing the same structure, tracked in .hallmark/log.json.

4. Theme Application

The skill applies either one of twenty pre-defined catalog themes or a custom theme when the brief explicitly requests a bespoke palette. This step ensures visual consistency with the project's established design language.

5. Ruleset Loading

To maintain token discipline, Hallmark loads only the necessary reference files from skills/hallmark/references/ on demand: the selected macrostructure, chosen theme, typography rules, colour palettes, layout grids, motion libraries, and anti-pattern lists. This selective loading minimizes context window usage.

6. Preview and Slop-Testing

Hallmark displays a concise markdown preview showing the selected macrostructure, theme, enrichment, sections, and motion plan. It then executes 57 slop-test gates plus a pre-emit self-critique. Any failure triggers an automatic revision pass before proceeding to emission.

7. Code Emission with Traceability

Final HTML and CSS output is stamped with a comment recording the macrostructure, theme, and slop-test scores. This ensures traceability for future runs and maintains accountability in the design generation process.

Supported Verbs and Commands

Hallmark responds to four distinct verbs that determine its operational mode.

Default Design Flow

When invoked without a specific verb, Hallmark executes the default "design a new UI" flow, building interfaces from scratch using the seven-step process outlined above.

Audit Mode

The hallmark audit <target> command analyzes existing code and returns a ranked punch-list of anti-patterns without modifying files. This mode scans components or pages against the 57 slop-test gates to identify AI-generation artifacts and design inconsistencies.

Redesign Mode

hallmark redesign <target> [--mood <name>] re-designs the visual layer while preserving routes, copy, and information architecture unless a full rebuild is explicitly requested. The optional --mood flag applies specific theme variations during the redesign process.

Study Mode

hallmark study <screenshot | URL> extracts the "DNA" from a reference design—identifying macrostructure, type-pairing, and colour anchors—and optionally emits a portable design.md file. This allows Hallmark to learn from existing high-quality designs and apply those patterns to new projects.

Practical Usage Examples

Install Hallmark using the Node package executor to add it to your host assistant's skill directory.

npx skills add nutlope/hallmark

Generate a new landing page for a product using the default design flow.

hallmark build my-awesome-app

Audit an existing React component for anti-patterns without making edits.

hallmark audit ./src/components/Header.jsx

Redesign an existing page while preserving content and routes, applying a specific mood.

hallmark redesign ./src/pages/home.html --mood modern-minimal

Study a live website to extract its design DNA and generate a reference document.

hallmark study https://example.com

Alternatively, study a local screenshot file.

hallmark study ./screenshots/hero.png

Each command prints a concise preview showing macrostructure, theme, enrichment, sections, motion, and slop-test scores before emitting final code, allowing confirmation or redirection of the output.

Summary

• Hallmark is a design skill for AI coding assistants (Claude Code, Cursor, Codex) hosted in Nutlope/hallmark that generates UI code designed to look handcrafted rather than AI-generated.
• The system enforces 57 slop-test gates and anti-pattern rules defined in skills/hallmark/SKILL.md to prevent generic LLM defaults.
• It supports four verbs: audit, redesign, study, and the default design flow, each serving distinct UI generation or analysis purposes.
• Hallmark operates through a seven-step process including pre-flight scanning, three-question prompting, macrostructure selection from 21 options, and theme application from 20 catalog themes.
• Output is fully-qualified HTML and CSS stamped with traceability comments recording generation parameters and quality scores.

Frequently Asked Questions

What is Hallmark and what does it do in AI-assisted coding?

Hallmark is a design skill package for AI coding assistants that generates user-interface code specifically engineered to look handcrafted rather than AI-generated. It encodes anti-AI-slop design rules, runs 57 quality gates, and selects from 21 macrostructures and 20 themes to produce HTML and CSS that respects existing project palettes and typography. Unlike standard code generation, it refuses to fall back to generic LLM defaults.

How do I install Hallmark for Claude Code or Cursor?

Install Hallmark using the Node package executor command npx skills add nutlope/hallmark, which adds the skill to your host assistant's skill directory. The package.json in the repository lists supported harnesses including Claude Code, Cursor, and Codex. Once installed, the skill becomes available as a command-line tool within your AI assistant's environment.

What are the main commands available in Hallmark?

Hallmark supports four primary verbs: the default command for building new UIs from scratch, audit for analyzing existing code and returning ranked anti-pattern lists, redesign for visual layer updates while preserving content architecture, and study for extracting design DNA from screenshots or URLs. Each command follows the same pre-flight scanning and slop-testing protocols defined in skills/hallmark/SKILL.md.

How does Hallmark prevent AI-generated code from looking generic?

Hallmark prevents generic outputs through token discipline and slop-test gates. It loads only necessary reference files from skills/hallmark/references/ to maintain context efficiency, applies a three-question prompt (Audience, Use case, Tone) to constrain outputs, and runs 57 automated tests plus a pre-emit self-critique. Any test failure triggers automatic revision, ensuring the final HTML and CSS reflects intentional design choices rather than training data defaults.

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