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

> Learn how to contribute to the Hallmark project. Fork the repo, add skills, static tests, and submit your HTML/CSS changes via pull request to the Nutlope/hallmark repository.

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

---

**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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)** | The **skill manifest** that defines entry points, reference file locations, and available harnesses. | [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](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)** | 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:
   ```bash
   git clone https://github.com/YOUR_USERNAME/hallmark.git
   cd hallmark
   ```

3. **Start the development server** to preview changes:
   ```bash
   npm run serve
   ```

   This serves the `site` folder at `http://localhost:4173` using the simple static server defined in [`package.json`](https://github.com/Nutlope/hallmark/blob/main/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:

```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 the new theme in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) with a new command block:

```markdown

## `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`](https://github.com/Nutlope/hallmark/blob/main/index.html) file that imports your CSS and renders sample components:

```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">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`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) and the theme cycler in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.