How to Set Up a Development Environment for Hallmark

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.
• 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 – Declares the skill entry point at skills/hallmark/SKILL.md and defines the serve script that launches the development server (lines 33‑34).
• 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) 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:

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:

npx skills add nutlope/hallmark

3. Start the development server:

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:

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). To apply it, reference the theme name in a CSS comment within any new HTML page’s <style> block:

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

The page automatically imports variables from 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:

| `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 lines 33‑34) launches a Python HTTP server on port 4173.
• Edit skill logic in 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 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.

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