How to Contribute to the Hallmark Project: A Complete Guide for New Contributors

Contributing to the Hallmark project requires only a text editor and Node.js, as the codebase consists entirely of static Markdown references and HTML/CSS test pages with zero runtime dependencies.

Hallmark is a design skill for Claude Code, Cursor, and Codex that generates UI pages with a handcrafted, non-AI aesthetic. If you want to contribute to the Hallmark project, you'll work with a deliberately lightweight, file-centric architecture maintained in the Nutlope/hallmark repository. The entire skill operates through static assets, making it accessible to designers and developers who prefer working with pure HTML, CSS, and Markdown.

Understanding Hallmark's Lightweight Architecture

Before you contribute to the Hallmark project, familiarize yourself with its minimal component structure. The architecture avoids build pipelines and JavaScript frameworks, relying instead on declarative Markdown files and static HTML demos.

Core Components

The repository is organized into distinct layers that separate skill logic from presentation:

• package.json – Declares the npm package metadata, entry points, and supported AI harnesses (Claude Code, Cursor, Codex). It also provides the serve script for local preview at http://localhost:4173.

• skills/hallmark/SKILL.md – The skill manifest that instructs AI assistants how to load and invoke Hallmark. This file defines entry points, reference file locations, and available verbs (CLI commands).

• skills/hallmark/references/ – A knowledge base of Markdown files describing macro-structures, themes, verbs, component recipes, and custom-theme logic. The skill draws from these files when generating pages.

• site/_tests/ – Self-contained HTML and CSS examples generated for each brief. Each folder contains a complete, browser-runnable page that serves as both documentation and visual regression testing.

• site/index.html & site/js/main.js – The demo harness powering the live site at https://www.usehallmark.com. This interface loads random examples and cycles through 20 themes when you press the T key.

How to Contribute to the Hallmark Project

Contributions typically involve extending the design system rather than modifying runtime code. Because Hallmark generates static HTML pages by selecting macro-structures, applying themes, and running "slop-test" heuristics, most changes require editing data files rather than JavaScript logic.

Setting Up Your Development Environment

You need minimal tooling to begin:

1. Fork the Nutlope/hallmark repository on GitHub.

2. Clone your fork locally.

3. Install dependencies (optional but recommended):

   npm install

4. Start the development server:

   npm run serve

   This serves the site folder at http://localhost:4173 using Python's simple HTTP server.

Adding New Themes and Macro-Structures

The primary way to contribute to the Hallmark project is by expanding the reference data under skills/hallmark/references/:

• New themes: Create Markdown files defining color palettes (using oklch color notation) and typography stacks.
• Macro-structures: Add templates defining page layouts and component arrangements.
• Component recipes: Document reusable UI patterns with specific CSS implementation details.

After adding reference files, update skills/hallmark/SKILL.md to expose any new verbs or reference paths so AI assistants can discover them.

Creating Test Pages

Every visual change requires a corresponding test page in site/_tests/:

1. Create a new folder under site/_tests/ named after your feature (e.g., site/_tests/new-theme/).
2. Add an index.html file that imports the relevant CSS and demonstrates the components.
3. Ensure the page is self-contained and opens directly in a browser without a build step.

These test pages allow reviewers to verify visual quality instantly and provide the content for the live demo's random page loader.

Contribution Workflow

Follow this structured process when submitting changes:

1. Fork and clone the repository to your local machine.

2. Run the development server using npm run serve and verify the site loads at http://localhost:4173.

3. Make your changes:

   • Edit Markdown files in skills/hallmark/references/ for theme or structure updates.
   • Modify skills/hallmark/SKILL.md if adding new commands.
   • Create HTML/CSS test pages in site/_tests/ for visual verification.

4. Test visually:

   • Open the local demo.
   • Press T to cycle through themes and confirm your additions render correctly.
   • Verify static files open directly without server-side processing.

5. Commit with clear, descriptive messages referencing the specific files changed (e.g., "Add cyberpunk theme to references and test suite").

6. Push to your fork and open a Pull Request against the main branch.

7. Review process: Maintainers will verify your Markdown reference updates, inspect the static test page for visual quality, and ensure the change integrates with the existing 20-theme rotation.

Practical Code Examples

Use these snippets when implementing specific contribution types.

Adding a New Theme

Create a Markdown file under skills/hallmark/references/custom-theme.md (or copy an existing theme file):

<!-- skills/hallmark/references/custom-theme.md -->

# Cyberpunk Neon

## Colour palette

- `--primary: oklch(70% 0.2 320deg);`
- `--background: oklch(15% 0.05 260deg);`
- `--accent: oklch(80% 0.15 120deg);`

## Typography

- Heading: "Space Grotesk", weight 700
- Body: "Inter", weight 400

Reference this file in skills/hallmark/SKILL.md to make it available to the AI harnesses.

Registering a New Verb

Extend skills/hallmark/SKILL.md with command documentation:

## `hallmark export <target>`

Export the generated HTML/CSS as a zip file for downstream consumption.
Arguments:
- `<target>`: Destination path for the archive

Creating a Test Page

Add a minimal HTML page under site/_tests/:

<!-- site/_tests/cyberpunk-demo/index.html -->
<!doctype html>
<html lang="en">
<head>
  <meta charset="utf-8">
  <title>Cyberpunk Theme Test</title>
  <link rel="stylesheet" href="../../styles/cyberpunk.css">
</head>
<body>
  <header class="hero">Neon Future</header>
  <section class="content">
    <article class="card">Test component</article>
  </section>
</body>
</html>

Running the Local Demo

Verify your changes immediately:

npm run serve

# Navigate to http://localhost:4173

# Press T to cycle through themes including your new addition

Summary

• Hallmark is static-only: Contributions involve Markdown, HTML, and CSS in skills/hallmark/references/ and site/_tests/—no JavaScript build steps or runtime dependencies required.
• Key files: Modify skills/hallmark/SKILL.md for command definitions, add themes to skills/hallmark/references/, and create visual tests in site/_tests/.
• Zero-install workflow: Use npm run serve to preview at localhost:4173 and press T to cycle themes.
• Review requirements: Every visual change needs a corresponding test page in site/_tests/ for manual inspection and demo integration.

Frequently Asked Questions

What skills do I need to contribute to Hallmark?

You need familiarity with Markdown, HTML, and CSS. Understanding oklch color notation and modern CSS typography helps for theme contributions, but no JavaScript framework knowledge is required. The codebase is intentionally limited to static assets so designers can contribute without learning complex build tools.

Do I need to write JavaScript to contribute?

No. Hallmark is pure HTML/CSS with no runtime dependencies. The only JavaScript in the repository lives in site/js/main.js and handles the demo site's theme cycling (the T key functionality). Most contributions involve editing Markdown reference files or adding static HTML test pages.

How do I test my changes locally?

Run npm run serve from the repository root to start a static server at http://localhost:4173. This command, defined in package.json, serves the site folder. Open the URL in your browser and press T to cycle through all 20 themes and verify your additions appear correctly. Each test page in site/_tests/ can also be opened directly as a standalone HTML file.

Where can I find ideas for contributions?

Check ROADMAP.md in the repository root for planned features and open issues. Common contribution areas include adding new macro-structures (page layout templates), expanding the theme catalog with unique color palettes, or improving component recipes in skills/hallmark/references/. The project welcomes visual design improvements and new "slop-test" heuristics that help generated pages feel more handcrafted.

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