how-to-guide

How to Contribute to the Hallmark Project: A Complete Guide for Open-Source Contributors

August 3, 2026 Nutlope/hallmark ↗

Contributing to Hallmark involves forking the repository, editing Markdown reference files in skills/hallmark/references/, adding a test page under site/_tests/, and submitting a pull request—no build step or JavaScript framework required.

Hallmark is a design skill for Claude Code, Cursor, and Codex that generates UI pages with a handcrafted, non-AI aesthetic. Its architecture is deliberately lightweight and file-centric, making contributions straightforward even for developers new to the codebase. This guide walks through exactly how to contribute to the Hallmark project based on the actual source structure in Nutlope/hallmark.

Understanding Hallmark's Core Architecture

Before diving into how to contribute to the Hallmark project, you need to understand its minimal, static-first design.

Component	Role	Source
`package.json`	Declares the skill package, entry point, and supported harnesses	`package.json`
`skills/hallmark/SKILL.md`	The skill manifest read by AI coding assistants	`skills/hallmark/SKILL.md`
`skills/hallmark/references/`	Markdown knowledge base for themes, macro-structures, and component recipes	`skills/hallmark/references/`
`site/_tests/`	Self-contained HTML + CSS examples for visual testing	`site/_tests/`
`site/index.html` & `site/js/main.js`	Live demo harness at `https://www.usehallmark.com`	`site/index.html`

Hallmark operates by selecting a macro-structure, applying a theme, running "slop-test" heuristics, and emitting static HTML. Because it uses pure HTML/CSS with zero runtime dependencies, contributions stay sandboxed to static assets.

Hallmark Contribution Workflow: 8 Steps

Follow this proven workflow when you contribute to the Hallmark project:

Fork the repository on GitHub
Clone your fork locally
Run the development server with npm run serve (serves at http://localhost:4173)
Make your changes—add themes, macro-structures, or component recipes
Add a test page under site/_tests/ for visual verification
Test in the demo—press T to cycle themes and confirm your change renders
Commit and push with a clear message
Open a Pull Request against main for review

Reviewers will examine your Markdown reference updates, the static test page, and overall visual quality. No JavaScript runtime or server-side code is required.

Three Ways to Contribute to Hallmark

Most contributions fall into one of three categories: extending reference data, updating the skill manifest, or adding test coverage.

Extending Reference Data

New macro-structures, themes, and component recipes live as Markdown files in skills/hallmark/references/. Here's how to add a new theme:

<!-- skills/hallmark/references/custom-theme.md -->

# My New Theme

## Colour palette

- `--primary: oklch(60% 0.15 260deg);`
- `--background: oklch(95% 0.02 30deg);`

## Typography

- Heading: "Inter", weight 700
- Body: "Merriweather", weight 400

Reference file: skills/hallmark/references/custom-theme.md

Updating SKILL.md

Expose new verbs or reference paths by editing skills/hallmark/SKILL.md:


## `hallmark export <target>`

Export the generated HTML/CSS as a zip file for downstream consumption.

This tells Claude Code, Cursor, and Codex how to invoke your new functionality.

Adding Test Pages

Create a self-contained example under site/_tests/:

<!-- site/_tests/my-theme/index.html -->
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>My Theme Demo</title>
  <link rel="stylesheet" href="../../styles/my-theme.css">
</head>
<body>
  <header class="hero">My New Theme Hero</header>
  <section class="content">…</section>
</body>
</html>

Local Development Commands

After any change, verify your contribution with these commands:


# Start the static server (defined in package.json scripts.serve)

npm run serve

# Server runs at http://localhost:4173

# Open browser, then press T to cycle through 20 themes

The serve script in package.json launches a simple Python-based static server—no complex build pipeline to configure.

Why This Model Works for Contributors

Hallmark's contribution experience prioritizes speed and simplicity:

Zero-install distribution: Users add the skill via npx skills add nutlope/hallmark; contributors need only npm and Python
Static assets only: Edit Markdown and CSS directly—no compilation step
Immediate visual feedback: The live demo shows change effects instantly, reducing review cycles

Key Files for Hallmark Contributors

File	Purpose
`README.md`	Project overview and quick-install instructions
`package.json`	NPM metadata and `serve` script
`skills/hallmark/SKILL.md`	Skill manifest for AI assistant integration
`skills/hallmark/references/`	Core knowledge base (themes, structures, recipes)
`site/_tests/`	Visual test examples
`site/index.html` & `site/js/main.js`	Demo harness with theme cycling
`ROADMAP.md`	Future directions and open contribution opportunities

Summary

To contribute to the Hallmark project effectively:

Fork, clone, and run npm run serve for local development
Extend skills/hallmark/references/ with new themes, macro-structures, or recipes
Update SKILL.md when adding new verbs or capabilities
Always add a test page in site/_tests/ for visual verification
Submit clean pull requests with clear commit messages

The static-only architecture means you focus on design decisions, not build tooling.

Frequently Asked Questions

What programming languages do I need to know to contribute to Hallmark?

You need Markdown for reference files, HTML/CSS for test pages, and basic JavaScript only if modifying the demo harness. The site/js/main.js file handles theme cycling with vanilla JS—no framework knowledge required. Python is used internally by the serve script, but you don't write any Python code.

Can I contribute a new theme without touching JavaScript?

Yes. Themes are pure Markdown files in skills/hallmark/references/ that define CSS custom properties and typography. The skill consumes these declarations and generates the actual CSS. Your test page in site/_tests/ imports the generated stylesheet—no JavaScript needed.

How does Hallmark verify that contributions work correctly?

The site/_tests/ directory serves as both documentation and test suite. Each folder contains a complete, self-contained HTML page that renders in any browser. Reviewers open these files directly to verify visual quality. The CI checks that pages render without errors, keeping the pipeline fast due to zero runtime dependencies.

Where can I find ideas for what to contribute?

Check ROADMAP.md in the repository root for planned features and open issues. Common contribution opportunities include: new macro-structures (page layouts), additional themes in the 20-theme rotation, component recipes for recurring UI patterns, and "slop-test" heuristics to catch AI-generated visual artifacts.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:

curl -s "https://instagit.com/install.md"

Add to your MCP client configuration:

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

Ask your agent:

"Use Instagit MCP to understand how Nutlope/hallmark works."

Works with

Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →