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

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:

cd hallmark
npm run serve

This command starts a local HTTP server at http://localhost:4173, as defined in 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:

---
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, site/css/*.css, or 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:

: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, docs/recipes.md, and 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 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 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 – Core skill entry point describing verbs and safety rails
• skills/hallmark/references/ – Library of macrostructures, themes, genres, and slop-test gates
• site/index.html – Live demo page showcasing generated Hallmark pages
• site/css/tokens.css – Central token definition file for all generated CSS
• package.json – Project metadata and the serve script configuration
• 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 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.

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