How to Contribute to the Hallmark Project: A Complete Guide for Designers and Developers

Contributing to the Hallmark project involves forking the repository, extending Markdown reference files in skills/hallmark/references/, adding static test pages to site/_tests/, and submitting a pull request with your HTML/CSS changes.

Hallmark is a design skill for Claude Code, Cursor, and Codex that generates UI pages mimicking handcrafted design rather than generic AI output. Learning how to contribute to the Hallmark project is straightforward because its architecture is deliberately lightweight and file-centric, requiring no complex build pipelines or runtime dependencies.

Understanding the Hallmark Architecture

Before making changes, familiarize yourself with the repository structure. Hallmark operates as a static asset collection that AI coding assistants consume to generate themed HTML pages.

Component	Purpose	Location
package.json	Declares the skill package, entry point, and supported harnesses (Claude Code, Cursor, Codex). Also contains the serve script for local preview.	Root directory
skills/hallmark/SKILL.md	The skill manifest that defines entry points, reference file locations, and available harnesses.	skills/hallmark/SKILL.md
`skills/hallmark/references/``	Knowledge base containing Markdown files describing macro-structures, themes, verbs, and component recipes.	skills/hallmark/references/
site/_tests/	Self-contained HTML + CSS examples serving as both documentation and visual tests. Each folder contains a complete, browsable page.	site/_tests/
site/index.html & site/js/main.js	The demo harness powering the live site at https://www.usehallmark.com, cycling through themes with the T key.	site/ directory

The skill works by picking a macro-structure, applying a theme, running "slop-test" heuristics to eliminate poor outputs, and emitting static HTML. According to the Nutlope/hallmark source code, contributions are sandboxed to these static assets, keeping CI fast and the codebase accessible.

Step-by-Step Contribution Workflow

Follow this workflow to ensure your contribution aligns with the project's file-centric philosophy.

1. Fork the repository on GitHub using the Fork button in the top-right corner.

2. Clone your fork locally:

   git clone https://github.com/YOUR_USERNAME/hallmark.git
   cd hallmark

3. Start the development server to preview changes:

   npm run serve

   This serves the site folder at http://localhost:4173 using the simple static server defined in package.json.

4. Make your changes by editing files in skills/hallmark/references/ or adding new macro-structures.

5. Add a corresponding test page under site/_tests/ containing self-contained HTML and CSS that demonstrates your change.

6. Verify visually by opening http://localhost:4173 and pressing the T key to cycle through themes, confirming your addition renders correctly.

7. Commit with a clear message describing the visual or functional change.

8. Push to your fork and open a Pull Request against the main branch.

Reviewers will examine your Markdown reference updates, inspect the static test page, and verify the overall visual quality matches Hallmark's handcrafted aesthetic.

Adding New Themes and Features

Most contributions involve extending the reference data. Here are practical patterns for common contribution types.

Creating a New Theme

Themes define color palettes and typography. Create a Markdown file under skills/hallmark/references/ following the existing naming convention:

<!-- 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 the new theme in SKILL.md if it requires specific activation logic.

Registering a New Verb

To add CLI commands that the AI assistants can invoke, extend skills/hallmark/SKILL.md with a new command block:

## `hallmark export <target>`

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

This exposes the functionality to Claude Code, Cursor, and Codex according to the skill manifest specification.

Adding Component Recipes

Component recipes live in the references/ folder as Markdown files describing specific UI patterns (navigation bars, hero sections, card grids). When adding a new recipe, include:

• The HTML structure template
• Required CSS classes
• Accessibility considerations
• Responsive behavior notes

Testing Your Changes Locally

Because Hallmark uses pure HTML/CSS with no runtime dependencies, testing requires only a web browser.

To verify a new theme:

1. Create a test folder under site/_tests/my-theme/.
2. Add an index.html file that imports your CSS and renders sample components:

<!-- 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">Sample content</section>
</body>
</html>

3. Run npm run serve and navigate to http://localhost:4173/_tests/my-theme/.
4. Inspect the rendering at various viewport sizes to ensure the design feels handcrafted rather than templated.

The demo harness at site/index.html and the theme cycler in site/js/main.js provide immediate visual feedback, reducing review cycle time.

Summary

• Hallmark is a file-centric design skill for AI coding assistants, stored in the Nutlope/hallmark repository.
• Core contributions modify Markdown files in skills/hallmark/references/ and add static test pages to site/_tests/.
• The SKILL.md manifest controls how Claude Code, Cursor, and Codex load and execute the skill.
• Local development requires only npm run serve to test changes at localhost:4173.
• Use the T key in the browser to cycle themes and verify visual quality before submitting pull requests.

Frequently Asked Questions

Do I need to know JavaScript to contribute to Hallmark?

No. Hallmark contributions are limited to static assets only—Markdown, HTML, and CSS. You can add themes, macro-structures, or component recipes without writing JavaScript or understanding complex build pipelines. The architecture is designed so contributors focus on design decisions rather than code complexity.

Where should I place new component recipes?

Place component recipes as Markdown files in skills/hallmark/references/. Follow the existing file naming conventions and include structured sections describing the HTML template, CSS classes, and usage context. The skill manifest at skills/hallmark/SKILL.md points to this folder as the knowledge base source.

How do I test my theme before submitting a Pull Request?

Create a self-contained test page under site/_tests/ with your theme's CSS linked in the HTML <head>. Run npm run serve to start the local server, visit http://localhost:4173, and press T to cycle through available themes. Your new theme should appear in the rotation if properly registered in the references folder.

What makes a good Hallmark contribution?

Effective contributions add reference data that helps the AI generate handcrafted-looking results rather than generic templates. Focus on specific macro-structures (unique page layouts), distinctive color palettes using OKLCH color notation, or component recipes with careful typography spacing. Each addition should include a corresponding test page in site/_tests/ so reviewers can evaluate the visual output instantly.

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