# How to Contribute to the Hallmark Project: A Complete Guide for New Contributors > Learn how to contribute to the Hallmark project with this complete guide. Start contributing to Hallmark today with just a text editor and Node.js. No dependencies required. - Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark) - Tags: how-to-guide - Published: 2026-07-28 --- **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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](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`. 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): ```bash npm install ``` 4. **Start the development server**: ```bash 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md) (or copy an existing theme file): ```markdown # 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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) to make it available to the AI harnesses. ### Registering a New Verb Extend [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) with command documentation: ```markdown ## `hallmark export ` Export the generated HTML/CSS as a zip file for downstream consumption. Arguments: - ``: Destination path for the archive ``` ### Creating a Test Page Add a minimal HTML page under `site/_tests/`: ```html Cyberpunk Theme Test
Neon Future
Test component
``` ### Running the Local Demo Verify your changes immediately: ```bash 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.