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

> Learn how to contribute to the Nutlope/hallmark project. Fork the repo, make changes, run the slop-test, and submit your pull request.

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

---

**Fork the Nutlope/hallmark repository, modify the skill definitions or demo site, verify your changes pass the 58-gate slop-test, and submit a pull request using conventional commit formats.**

Hallmark is an open-source design skill for AI-coding assistants (Claude Code, Cursor, Codex) that enforces strict anti-AI-slop guidelines through a collection of reference files. The repository stores the core skill logic, a static demo site, and documentation that contributors can extend to improve AI-generated design quality. Contributing to this project primarily involves editing Markdown reference files, updating the HTML/CSS demo interface, or refining project documentation.

## Setting Up Your Local Development Environment

Start by forking the repository on GitHub and cloning your fork to your local machine. While the repository is composed of JSON and Markdown files, you must serve the demo site locally to verify visual changes before submitting.

Navigate to the project root and start the development server:

```bash
cd hallmark
npm run serve

```

This command launches 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【/cache/repos/github.com/Nutlope/hallmark/main/package.json#L32-L35】. Use this local instance to preview any modifications to the demo site or documentation styling.

## Contribution Areas

The codebase is organized into three distinct zones where you can contribute based on your expertise. Each area serves a specific function in the Hallmark ecosystem.

### Skill Definitions in `skills/hallmark/`

The `skills/hallmark/` directory contains the core skill definition in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) and the public reference files under `references/` that encode macro-structures, themes, genre rules, and slop-test gates. To extend this area, add or adjust reference files within subdirectories like `references/macrostructures/` or `references/themes/`.

Maintain the established Markdown format: include YAML frontmatter with `name`, `description`, and `genre` fields, followed by structural tokens that the skill loads at runtime. These files directly influence how AI assistants generate UI designs according to Hallmark's discipline.

### Demo Site in `site/`

The `site/` directory houses the HTML, CSS, and JavaScript that power the live demo at `https://www.usehallmark.com`. Key files include [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html), [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css), and [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js).

When modifying the demo site, ensure all CSS remains **token-based** using `var(--color-…)` references rather than hard-coded color values. The [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) file serves as the central token definition that must be used by all generated CSS.

### Documentation in `docs/`

Human-focused documentation resides in `docs/` (including [`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)) alongside the root [`README.md`](https://github.com/Nutlope/hallmark/blob/main/README.md). Contributions here involve improving explanations, adding new usage examples, or updating screenshots to reflect the current design system.

## The Contribution Workflow

After setting up your environment and selecting a contribution area, follow the standardized workflow to ensure your changes meet Hallmark's quality gates.

### Making Changes and Testing

Edit the relevant files in your chosen area. Before committing, run the **58-gate slop-test** locally to verify compliance. While the skill triggers this test automatically during invocation, you can manually validate reference files against the [`slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/slop-test.md) logic to ensure they satisfy Hallmark's anti-pattern detection rules.

### Commit Message Conventions

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

- `feat:` for new macrostructures, themes, or capabilities
- `fix:` for corrections to token names, logic errors, or bugs
- `docs:` for documentation updates and README improvements

Example messages:

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

```

### Submitting Your Pull Request

Commit your changes with a clear message following the conventions above, then push to your fork. Open a Pull Request against the upstream `main` branch. In your PR description, reference the affected reference files (e.g., [`skills/hallmark/references/macrostructures/12-bento-grid.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures/12-bento-grid.md)) and explain how the change respects Hallmark's design discipline.

Maintainers will run the full slop-test and verify the demo site still builds. Address any CI failures before your PR can be merged. Once approved, the changes deploy automatically to the live demo site.

## Practical Code Examples

### Adding a New Macrostructure

Create a file in `skills/hallmark/references/macrostructures/` following the established naming convention:

```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 */

```

### Updating Design Tokens

Modify [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) to adjust the color system using OKLCH color space:

```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 Updates

When improving the contribution guide in [`README.md`](https://github.com/Nutlope/hallmark/blob/main/README.md):

```markdown

## Contributing

1. Fork the repo and clone your fork.
2. Run `npm run serve` to preview the demo locally.
3. Make your changes in the `skills/hallmark/references/` or `site/` directories.
4. Submit a PR – ensure the Hallmark slop-test passes before merging.

```

## Key Files and Architecture

Understanding these critical files helps you navigate the codebase effectively:

- **[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)**: Core skill entry point describing verbs and safety rails according to the AI skill specification.
- **`skills/hallmark/references/`**: Library of macrostructures, themes, genres, anti-patterns, and the 58-gate slop-test logic.
- **[`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html)**: Live demo page that showcases generated Hallmark pages and serves as the visual testbed.
- **[`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css)**: Central token definition file that enforces the design system's color and typography standards.
- **[`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json)**: Project metadata and the `serve` script for local testing at lines 32-35【/cache/repos/github.com/Nutlope/hallmark/main/package.json#L32-L35】.
- **[`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md)**: Human-readable examples of Hallmark usage patterns for contributors and users.

## Summary

- Fork and clone the Nutlope/hallmark repository, then run `npm run serve` to start a local server at `localhost:4173` defined in [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json).
- Contribute to three main areas: `skills/hallmark/` for skill logic and reference files, `site/` for the demo interface, or `docs/` for documentation.
- Reference files must include proper YAML frontmatter and structural tokens to pass the slop-test validation.
- Use conventional commit prefixes (`feat:`, `fix:`, `docs:`) and reference specific file paths in your PR description.
- Verify all changes pass the 58-gate slop-test before submitting to ensure compliance with anti-AI-slop guidelines.

## Frequently Asked Questions

### What is the Hallmark slop-test?

The slop-test is a 58-gate validation system implemented in the Hallmark skill that checks generated designs against anti-patterns commonly found in AI-generated content. According to the repository's reference files in `skills/hallmark/references/`, this test automatically runs when the skill is invoked to ensure all outputs maintain human-quality design standards. Contributors should verify their reference file changes against this logic before submitting pull requests.

### Do I need to know React or Node.js to contribute?

No. While the demo site uses HTML, CSS, and JavaScript, the core contribution areas rely primarily on Markdown and JSON editing within the `skills/hallmark/references/` directory. The `npm run serve` command (defined in [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) lines 32-35【/cache/repos/github.com/Nutlope/hallmark/main/package.json#L32-L35】) simply starts a static file server for local preview, requiring no complex build steps or React knowledge for most contributions.

### How do I test my changes locally?

Start the local development server by running `npm run serve` from the project root, which launches a server at `http://localhost:4173` as configured in [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json). This allows you to preview demo site changes immediately. For reference file modifications, manually validate your Markdown against the [`slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/slop-test.md) logic to ensure compliance with the 58 quality gates before committing.

### What commit message format should I use?

Hallmark follows conventional commit conventions with specific prefixes: use `feat:` for new features like macrostructures or themes, `fix:` for bug corrections in tokens or logic, and `docs:` for documentation improvements. Each commit message should clearly describe what changed and why, such as `feat: add Aurora theme with cool-hue diversification` or `fix: resolve token naming conflict in tokens.css`.