# How to Contribute to the Nutlope/hallmark Project: A Complete Guide for Developers

> Learn how to contribute to the Nutlope/hallmark project with this comprehensive guide. Fork the repo, install, test, and submit your PR.

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

---

**Fork the repository, install dependencies with `npm install`, run `npm run serve` to preview changes locally, modify files in `skills/hallmark/`, `site/`, or `docs/`, ensure the 58-gate slop-test passes, and submit a PR with a conventional commit message.**

Hallmark is an open-source design skill for AI-coding assistants like Claude Code and Cursor that enforces strict anti-AI-slop guidelines. If you want to contribute to the Nutlope/hallmark project, you’ll work with JSON, Markdown, and static web assets to refine the generation rules or improve the demo site. This guide covers the exact workflow, file structure, and submission requirements used by the maintainers.

## Prerequisites and Repository Setup

Start by forking the repository on GitHub and cloning your fork locally. The project is primarily composed of Markdown and JSON files, so you do not need a complex build toolchain. However, a local server is required to preview the demo site.

Navigate to the project root and install the minimal development dependencies:

```bash
cd hallmark
npm run serve

```

This command starts a local HTTP server at `http://localhost:4173`, as defined in [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) at lines 32–35. You can now view the site and verify any visual changes in real time.

## The Three Contribution Areas

Hallmark organizes contributions into three distinct domains. Each area has specific conventions you must follow to ensure the pull request passes review.

### Core Skill Logic (`skills/hallmark/`)

This directory contains the **SKILL.md** entry point and the `references/` library that encodes macrostructures, themes, genre rules, and slop-test gates. When contributing here, you modify design constraints that AI assistants use to generate UI.

To add a new macrostructure, create a Markdown file in `skills/hallmark/references/macrostructures/` following this format:

```markdown
---
name: Bento Grid
description: Grid-based layout with modular cards, suitable for SaaS dashboards.
genre: modern-minimal
---
/* Hallmark · macrostructure: Bento Grid · theme: Coral · nav: N5 · footer: Ft2 */

```

### Demo Site (`site/`)

The live demo at `https://www.usehallmark.com` is built from static files in `site/`. Contributions here involve HTML, CSS, and JavaScript updates to [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html), `site/css/*.css`, or [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js).

All CSS must remain token-based. Use `var(--color-…)` references rather than hard-coded values. For example, when updating [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css):

```css
:root {
  --color-paper: oklch(95% 0.02 210);
  --color-accent: oklch(55% 0.12 210); /* updated to match new “Coral” theme */
  --font-display: var(--font-sans);
}

```

### Documentation (`docs/`)

Human-focused guides live in [`README.md`](https://github.com/Nutlope/hallmark/blob/main/README.md), [`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md), and [`docs/study-examples.md`](https://github.com/Nutlope/hallmark/blob/main/docs/study-examples.md). Improve explanations, add usage examples, or update screenshots to help new users understand the design discipline.

## Local Development Workflow

After starting the local server with `npm run serve`, make your changes in the appropriate directory. Since the repository is pure JSON and Markdown for the skill logic, you can edit reference files directly without a compilation step.

When modifying the demo site, refresh your browser at `localhost:4173` to verify visual updates. Ensure that any new CSS variables are defined in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) and that you haven’t introduced hard-coded color values that violate the token-based architecture.

## Testing Your Changes with the Slop-Test

Hallmark enforces quality through a **58-gate slop-test** that runs automatically when the skill is invoked. Before submitting your contribution, verify that your changes satisfy these gates.

While the test triggers automatically during skill execution, you can manually run relevant reference files through the [`slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/slop-test.md) logic to check compliance. The CI pipeline will run the full slop-test suite against your PR, and any failures must be addressed before merging.

## Commit and Pull Request Guidelines

Use **conventional commit messages** to categorize your changes:

- `feat: add “Bento Grid” macrostructure`
- `fix: correct token name in tokens.css`
- `docs: update contribution guide with npm install step`

When opening a Pull Request against the `main` branch, reference the affected files in `skills/hallmark/references/` or `site/` and explain how your change respects Hallmark’s design discipline. For example: *“Adds new theme ‘Aurora’ with cool-hue axis to satisfy diversification rule.”*

Maintainers will review the code, verify the slop-test passes, and confirm the demo site still builds correctly. Once approved, the PR merges and the live site updates automatically after the next deployment.

## Key Files Reference

- [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) – Core skill entry point describing verbs and safety rails
- `skills/hallmark/references/` – Library of macrostructures, themes, genres, and slop-test gates
- [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) – Live demo page showcasing generated Hallmark pages
- [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) – Central token definition file for all generated CSS
- [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) – Project metadata and the `serve` script configuration
- [`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md) – Human-readable usage examples for contributors

## Summary

- **Fork and clone** the Nutlope/hallmark repository to begin contributing.
- **Run `npm run serve`** from the project root to start a local server at `localhost:4173`.
- **Edit in three areas**: skill logic (`skills/hallmark/`), demo site (`site/`), or documentation (`docs/`).
- **Follow token-based CSS** conventions when updating the demo site styles.
- **Verify the 58-gate slop-test** passes before submitting your PR.
- **Use conventional commits** (`feat:`, `fix:`, `docs:`) and reference specific files in your PR description.

## Frequently Asked Questions

### Do I need to install Node.js to contribute to Hallmark?

You only need Node.js if you plan to preview the demo site locally using `npm run serve`. The core skill logic consists of Markdown and JSON files that you can edit without any runtime dependencies. However, running the local server is recommended to verify visual changes before submitting a PR.

### What is the 58-gate slop-test in Hallmark?

The 58-gate slop-test is an automated quality assurance suite that validates generated designs against anti-AI-slop guidelines. It runs automatically when the Hallmark skill is invoked and checks that outputs meet the design discipline encoded in the reference files. All contributions must pass this test before merging into the main branch.

### Can I add new design themes to the Hallmark skill?

Yes, you can add new themes by creating or modifying files in `skills/hallmark/references/`. Include a short description, genre classification, and any structural tokens required by the skill. Ensure the new theme integrates with the existing token system in [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) and satisfies the diversification rules enforced by the slop-test.

### How do I preview my changes before submitting a PR?

Execute `npm run serve` in the project root to start a local HTTP server at `http://localhost:4173`. This serves the static demo site located in the `site/` directory, allowing you to verify HTML, CSS, and JavaScript changes in your browser before committing them.