How to Integrate Hallmark into Existing Projects: A Complete Setup Guide

Integrate Hallmark into existing projects by running npx skills add nutlope/hallmark to install the design skill, then invoke commands like hallmark, hallmark audit, or hallmark redesign to generate anti-AI-slop UI components that respect your current design system.

Hallmark is a design skill for Claude Code, Cursor, and Codex-based AI coding assistants that generates fully-styled pages following strict anti-AI-slop design principles. When you integrate Hallmark into existing projects, it preserves your current design tokens and Tailwind configuration while applying deterministic visual rules from the skills/hallmark/SKILL.md specification.

Installing the Hallmark Skill

The fastest way to integrate Hallmark into your workflow is through the npx skills CLI. This command pulls the skill definition from the Nutlope/hallmark repository and registers it for your current environment.

Run the following in your terminal:

npx skills add nutlope/hallmark

This one-liner reads the SKILL.md file and configures the skill based on which AI assistant you are using. The installation is idempotent and can be run once per environment or project.

AI Assistant Configuration Paths

After installation, Hallmark writes its skill files to assistant-specific directories. Knowing these paths helps you verify installation or manually edit rules.

Claude Code

For Claude Code, the skill installs to:

~/.claude/skills/hallmark/

Cursor

Cursor receives the skill as a rules file at:

.cursor/rules/hallmark.mdc

This file contains the body of SKILL.md without front-matter, allowing Cursor's agent to reference the design system directly.

Codex

Codex supports both personal and project-scoped installation:

• Personal: ~/.codex/skills/hallmark/
• Project-scoped: .codex/skills/hallmark/

Core Commands and Usage Patterns

Once installed, you invoke Hallmark through four primary verbs defined in skills/hallmark/SKILL.md. Each command targets different stages of the design lifecycle.

Generate New UI

The default command builds a new interface using the full design flow:

hallmark

This executes the complete pipeline from genre detection to the 58-gate slop-test, generating HTML/CSS with token-based color and font references.

Audit Existing Code

To score existing code against anti-patterns without making changes:

hallmark audit ./src/pages/about.html

This command analyzes your target file against the visual ruleset and reports compliance issues.

Redesign with Mood Preservation

Rebuild the visual layer while preserving routes, copy, and information architecture:

hallmark redesign ./src/components/Button.tsx --mood modern-minimal

Available mood options include editorial, modern-minimal, atmospheric, and playful, as defined in the genre references.

Study External References

Extract design DNA from screenshots or live URLs:

hallmark study https://example.com

This locks the visual characteristics of a reference into your project's design context.

The Hallmark Design Pipeline

When you run the default hallmark command, the skill follows a deterministic seven-stage pipeline documented in skills/hallmark/SKILL.md.

1. Pre-flight scan – Reads existing package.json, Tailwind configuration, and design tokens to preserve your current system.
2. Genre detection – Selects from four genres (editorial, modern-minimal, atmospheric, playful) based on brief signals.
3. Macrostructure selection – Chooses from 21 named macrostructures (e.g., Marquee Hero, Bento Grid) while respecting diversification rules from references/macrostructures.md.
4. Theme route – Selects either a catalog theme or custom theme if the brief requests a bespoke palette.
5. Enrichment decision – Determines whether hero enrichment (illustration, video, or Lottie) is required.
6. Preview – Emits a concise markdown preview of the planned output before generating code.
7. Build and slop-test – Produces HTML/CSS using tokens from site/css/tokens.css and validates against 58 anti-slop gates.

Practical Examples and Recipes

The repository includes docs/recipes.md containing ready-to-copy prompts for common scenarios. These examples demonstrate how to integrate Hallmark into existing projects for specific use cases like landing pages, component libraries, and design audits.

Example workflow for a landing page redesign:

# Audit current implementation

hallmark audit ./src/index.html

# Study a competitor's design

hallmark study https://competitor.com

# Redesign with specific mood

hallmark redesign ./src/index.html --mood playful

Summary

• Install Hallmark across Claude Code, Cursor, or Codex using npx skills add nutlope/hallmark.
• Skill files install to assistant-specific paths like ~/.claude/skills/hallmark/ or .cursor/rules/hallmark.mdc.
• Four primary verbs control the workflow: hallmark, hallmark audit, hallmark redesign, and hallmark study.
• The design pipeline preserves existing tokens from package.json and Tailwind config while applying 21 macrostructures and 58-gate slop-testing.
• Reference docs/recipes.md for production-ready prompts and references/macrostructures.md for layout options.

Frequently Asked Questions

Can I use Hallmark with multiple AI assistants simultaneously?

Yes. You can install the skill in Claude Code, Cursor, and Codex environments on the same machine. Each assistant maintains its own copy of the skill files in their respective directories (e.g., ~/.claude/skills/hallmark/ and .cursor/rules/hallmark.mdc), allowing you to use Hallmark's design system across different AI coding tools without conflicts.

Does Hallmark overwrite my existing Tailwind configuration?

No. During the pre-flight scan stage, Hallmark reads your existing package.json, Tailwind config, and CSS tokens to preserve your current design system. The generated code references these existing tokens rather than replacing them, ensuring the output integrates cleanly with your established styling conventions.

What are the 58 gates in the slop-test?

The 58-gate slop-test is a validation layer defined in skills/hallmark/SKILL.md that checks generated code against common AI design anti-patterns. These gates verify proper visual hierarchy, spacing consistency, typography scale adherence, and token usage from site/css/tokens.css before finalizing output, preventing generic "AI slop" aesthetics.

How do I customize the mood or genre for my project?

Use the --mood flag with the redesign verb to specify one of four genres: editorial, modern-minimal, atmospheric, or playful. For example, hallmark redesign ./src/index.html --mood editorial applies the editorial genre's specific tokens and constraints from references/genres/editorial.md while preserving your existing routes and content structure.

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