How to Deploy Nutlope/Hallmark Applications: Complete Setup Guide

Deploy Nutlope/hallmark by installing the AI skill via npx skills add nutlope/hallmark and serving the static site/ directory on any static hosting provider such as Vercel, Netlify, or GitHub Pages.

Nutlope/hallmark is a design skill for AI-coding assistants that enforces strict design-system disciplines including type pairing, OKLCH colour tokens, and motion. Deploying the application requires two distinct steps: registering the skill in your Claude Code, Cursor, or Codex harness, and hosting the pre-built static assets located in the site/ directory.

Install the Skill in Your AI Harness

The Hallmark skill is defined in package.json with specific entry points and harness targets. Registration copies the skill files into your local AI assistant's configuration directory.

Skill Configuration

The skill metadata is declared in the root package.json:

{
  "skill": {
    "entry": "skills/hallmark/SKILL.md",
    "references": "skills/hallmark/references",
    "harnesses": ["claude-code","cursor","codex"]
  },
  "scripts": { "serve": "python3 -m http.server --directory site 4173" }
}

The skills/hallmark/SKILL.md file contains the full command syntax for the four verbs (build, audit, redesign, study) and the design-system disciplines that Hallmark enforces.

Harness-Specific Installation Paths

Run the installation command:

npx skills add nutlope/hallmark

This command installs the skill into the following locations based on your active harness:

Harness	Destination Path
Claude Code	~/.claude/skills/hallmark/
Cursor	.cursor/rules/hallmark.mdc
Codex	~/.codex/skills/hallmark/

The installer overwrites existing files when you reinstall, ensuring the latest design rules are available for subsequent AI calls.

Run the Static Site Locally

Hallmark ships a self-contained static site in the site/ directory. The entry point is site/index.html, which imports design tokens from site/css/tokens.css and component styles from site/css/base.css, components.css, and sections.css.

Start the Development Server

The package.json includes a serve script that launches a Python HTTP server:

npm run serve

This executes python3 -m http.server --directory site 4173, binding to port 4173. Open http://localhost:4173 to view the UI gallery, install panel, and live examples such as the Wayfare travel-booking demo at site/examples/wayfare/.

Deploy to Production Static Hosting

Because the site consists of pure static assets with no build step, you can copy the entire site/ folder to any static-hosting platform.

Deploy to Vercel

Use the Vercel CLI to deploy the site/ directory directly:

npm i -g vercel
vercel ./site --prod

The CLI auto-detects the static output and serves site/index.html as the entry point.

Deploy to Netlify

You can drag-and-drop the site/ folder into the Netlify dashboard UI, or bind your Git repository and set the publish directory to site/ in your site settings.

Deploy to GitHub Pages

Push the static files to a gh-pages branch:

git checkout -b gh-pages
git rm -r .
cp -r site/* .
git add .
git commit -m "Publish Hallmark site"
git push -u origin gh-pages

Enable GitHub Pages in your repository settings and select the gh-pages branch as the source.

Deploy to AWS S3

Sync the site/ folder to an S3 bucket and configure CloudFront distribution:

aws s3 sync site/ s3://my-bucket/

Ensure your S3 bucket policy allows public read access to the static assets.

Update the Skill

When you modify the skill—such as adding new macrostructures or updating the token palette in site/css/tokens.css—reinstall it using the same command:

npx skills add nutlope/hallmark

The installer overwrites the previous version in the harness directory, applying your changes immediately.

Summary

• Install the skill using npx skills add nutlope/hallmark to register it in Claude Code, Cursor, or Codex harnesses at their respective config paths.
• Serve locally by running npm run serve, which starts a Python HTTP server on port 4173 serving the site/ directory.
• Deploy anywhere by uploading the static site/ folder to Vercel, Netlify, GitHub Pages, or AWS S3 without requiring a build step.
• Update by reinstalling with the same npx command to overwrite existing skill files in ~/.claude/skills/hallmark/, .cursor/rules/hallmark.mdc, or ~/.codex/skills/hallmark/.

Frequently Asked Questions

What files are required to deploy the Hallmark site?

You must deploy the entire site/ directory, including site/index.html, site/css/tokens.css, site/css/base.css, site/css/components.css, and site/css/sections.css. These files contain the OKLCH token definitions and component styles required to render the design system correctly.

Which AI harnesses support the Hallmark skill?

The skill supports three harnesses as defined in package.json: Claude Code, Cursor, and Codex. Each harness stores the skill files in different locations—~/.claude/skills/hallmark/, .cursor/rules/hallmark.mdc, and ~/.codex/skills/hallmark/ respectively.

How do I preview the Hallmark design system locally?

Run npm run serve to execute the Python HTTP server configured in package.json. This serves the static assets from the site/ directory on http://localhost:4173, allowing you to preview the UI gallery and example builds like the Wayfare travel-booking interface.

Can I use a custom port for the local development server?

The default script in package.json hardcodes port 4173 via python3 -m http.server --directory site 4173. To use a different port, modify the serve script in package.json or run the Python command manually with your desired port number.

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