# How to Set Up a Development Environment for Hallmark

> Quickly set up your Hallmark development environment. Clone the repository and run npm run serve for a local HTTP server. Node.js and Python 3 required.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: getting-started
- Published: 2026-07-26

---

**To set up a development environment for Hallmark, clone the repository, ensure you have Node.js ≥ 14 and Python 3 installed, then run `npm run serve` to start a local HTTP server on port 4173.**

Hallmark is a design skill distributed as a static HTML and CSS site alongside markdown-based rule files for AI coding assistants like Claude Code, Cursor, and Codex. This guide walks you through configuring your local environment to modify the skill definitions, reference materials, and generated design examples tracked in the `Nutlope/hallmark` repository.

## Prerequisites

Before cloning the repository, verify your system meets these minimal requirements:

- **Node.js ≥ 14** – Required to execute the `npx skills add nutlope/hallmark` installation command referenced in the project documentation.
- **Python 3** – Powers the local preview server via `python -m http.server` as defined in [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json).
- **Git** – Needed to clone the repository and version control your changes.
- **A code editor** – For editing markdown reference files, CSS variables in `site/css/`, and HTML templates.

## Repository Architecture

Understanding the file structure helps you navigate the codebase effectively:

- **[`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json)** – Declares the skill entry point at [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) and defines the `serve` script that launches the development server (lines 33‑34).
- **[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)** – The core manifest AI assistants read to understand available verbs and capabilities.
- **`skills/hallmark/references/`** – Contains markdown knowledge bases for typographic rules, colour palettes, macro-structures, and themes.
- **`site/`** – Houses the live demo ([`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html)) and fully rendered example pages under `site/_tests/` (such as `09-slow-pour`).
- **`site/css/`** – Stores global CSS tokens and component styles imported by all generated pages.

## Step-by-Step Setup

Follow these commands to get the local server running:

1. **Clone the repository:**

```bash
git clone https://github.com/Nutlope/hallmark.git
cd hallmark

```

2. **Install the skill (optional):**

If you are testing the skill integration with an AI assistant, run the install command documented in [`README.md`](https://github.com/Nutlope/hallmark/blob/main/README.md):

```bash
npx skills add nutlope/hallmark

```

3. **Start the development server:**

```bash
npm run serve

```

This executes `python -m http.server --directory site 4173`, starting a server at `http://localhost:4173`.

4. **View examples:**

Navigate to `http://localhost:4173/site/_tests/` to browse generated design examples, or open a specific test page like `http://localhost:4173/site/_tests/09-slow-pour/index.html`.

*Alternative:* If you prefer not to use npm, start the server manually with:

```bash
python3 -m http.server --directory site 4173

```

## Development Workflows

### Adding a New Theme

Create a markdown file in `skills/hallmark/references/themes/` (for example, [`my-theme.md`](https://github.com/Nutlope/hallmark/blob/main/my-theme.md)). To apply it, reference the theme name in a CSS comment within any new HTML page’s `<style>` block:

```css
/* Hallmark · macrostructure: Marquee Hero · theme: My-Theme */

```

The page automatically imports variables from [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css), applying your new theme definitions.

### Extending the Skill with a New Verb

Add a verb definition under `skills/hallmark/references/verbs/`, then expose it to AI assistants by updating [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md):

```markdown
| `hallmark myverb <target>` | Description of what the verb does |

```

### Running Tests Locally

All generated design pages live in `site/_tests/`. Since these are static HTML files, no test runner is required—simply open the directory index in your browser at `http://localhost:4173/site/_tests/` to visually verify rendering.

## Summary

- Hallmark requires only **Node.js ≥ 14**, **Python 3**, and **Git** for local development.
- The `npm run serve` command (defined in [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) lines 33‑34) launches a Python HTTP server on **port 4173**.
- Edit skill logic in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) and reference materials under `skills/hallmark/references/`.
- Preview static examples in `site/_tests/` via the local server to validate design changes immediately.

## Frequently Asked Questions

### Can I run the Hallmark development server without installing Node.js?

Yes. While `npm run serve` requires Node.js to execute the package script, you can run the underlying Python command directly: `python3 -m http.server --directory site 4173`. This starts the same server on port 4173 without any Node dependencies, though you will need Node if you intend to install the skill via `npx`.

### Where do I add new design rules or themes?

Add new markdown files to `skills/hallmark/references/`. Create theme-specific files under `skills/hallmark/references/themes/` and typography rules under `skills/hallmark/references/typography/`. The [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) file automatically includes these references when AI assistants load the skill.

### How do I view the generated test examples?

Open `http://localhost:4173/site/_tests/` in your browser after running `npm run serve`. Each subdirectory (such as `09-slow-pour`) contains a complete, self-contained HTML page demonstrating a specific macro-structure and theme combination.

### What is the purpose of the CSS comment at the top of example pages?

The CSS comment encodes metadata in the format `/* Hallmark · macrostructure: [Name] · theme: [Theme] */`. This tells the AI assistant which reference files to apply when regenerating or modifying the design, ensuring consistency with the defined tokens and layout rules.