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

> Learn how to contribute to the Hallmark project. Fork the repo, edit reference files, add tests, and submit a pull request easily. No build step or JS framework needed.

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

---

**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`](https://github.com/Nutlope/hallmark/blob/main/package.json) | Declares the skill package, entry point, and supported harnesses | [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) |
| [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) | The **skill manifest** read by AI coding assistants | [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) & [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) | Live demo harness at `https://www.usehallmark.com` | [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/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:

1. **Fork the repository** on GitHub
2. **Clone your fork** locally
3. **Run the development server** with `npm run serve` (serves at `http://localhost:4173`)
4. **Make your changes**—add themes, macro-structures, or component recipes
5. **Add a test page** under `site/_tests/` for visual verification
6. **Test in the demo**—press `T` to cycle themes and confirm your change renders
7. **Commit and push** with a clear message
8. **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:

```markdown
<!-- 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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md)

### Updating SKILL.md

Expose new verbs or reference paths by editing [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md):

```markdown

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

```html
<!-- 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:

```bash

# 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/README.md) | Project overview and quick-install instructions |
| [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) | NPM metadata and `serve` script |
| [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) & [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) | Demo harness with theme cycling |
| [`ROADMAP.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.