How to Integrate Hallmark with Other Tools: CI Pipelines, Build Hooks, and Design Workflows

You can integrate Hallmark with other tools by reading the .hallmark/log.json file that every verb produces, which stores deterministic design fingerprints (macrostructure, theme, enrichment) that external scripts, CI pipelines, and plugins can consume to enforce diversification rules or sync design tokens.

Hallmark is a design-automation skill from the nutlope/hallmark repository that runs locally via command line. Because every verb persists its output to a predictable JSON file, you can integrate Hallmark with other tools by treating .hallmark/log.json as the integration surface between the design engine and your broader development workflow.

How Hallmark Exposes Integration Points

According to the source code in skills/hallmark/SKILL.md, Hallmark is structured around three public verbs: hallmark audit, hallmark redesign, and hallmark study. Each verb:

1. Reads a target (HTML, CSS, image, or URL).
2. Performs deterministic analysis using reference files like macrostructures.md and component-cookbook.md.
3. Writes a stamp to .hallmark/log.json, recording the chosen macrostructure, theme, and enrichment details.

This log file is the primary integration point. External tools can parse it to discover the current design fingerprint and make decisions—such as selecting complementary color palettes, rotating navigation components, or gating CI pipelines.

Key Architectural Files

The integration surface relies on these specific files:

• skills/hallmark/SKILL.md – Skill manifest declaring the three public verbs.
• skills/hallmark/references/verbs/audit.md – Implements the audit workflow, produces .hallmark/audit.json.
• skills/hallmark/references/verbs/study.md – Extracts DNA from references, can emit design.md.
• skills/hallmark/references/verbs/redesign.md – Writes the final stamp to .hallmark/log.json.
• skills/hallmark/references/slop-test.md – Defines diversification rules for preventing design stagnation.
• skills/hallmark/references/microinteractions.md – Source of motion-token defaults used by downstream tools.

Integration Patterns for External Tools

Because Hallmark’s output is deterministic and self-contained, you can integrate it using several patterns:

Pre-Build Hooks

Run hallmark audit on generated HTML/CSS before bundling. If the audit report contains anti-patterns, abort the build or trigger an automatic redesign.

Design-Pipeline Choreography

Chain hallmark study (to extract DNA from a reference URL) with hallmark redesign in a single script. Store the DNA as a portable design.md that style-guide generators can import.

CI/CD Gating

Parse .hallmark/log.json in a CI step to enforce that consecutive runs differ on at least one axis (macrostructure, theme, or enrichment). This prevents the "AI-feel" stagnation described in slop-test.md.

Cross-Tool Communication

Export the design fingerprint to JSON and feed it into downstream services like Figma plugins or Storybook addons to automatically sync color tokens, typography scales, or motion durations from microinteractions.md.

Practical Implementation Examples

The following runnable scripts demonstrate how to integrate Hallmark with other tools using the .hallmark/log.json contract.

Gating CI Pipelines with Audit Results

Use hallmark audit as a quality gate in your build process. The following Node.js script runs the audit verb and fails the pipeline if critical anti-patterns are detected:

// ci/hallmark-audit.js
const { execSync } = require('child_process');
const fs = require('fs');

// Run the audit on the built site
execSync('hallmark audit site/_tests/verbs/audit/input.html', { stdio: 'inherit' });

// Load the audit report (generated as .hallmark/audit.json)
const report = JSON.parse(fs.readFileSync('.hallmark/audit.json', 'utf8'));

// If any anti-pattern score exceeds the threshold, fail the pipeline
if (report.find(item => item.severity >= 3)) {
  console.error('Hallmark audit found critical anti-patterns – aborting build');
  process.exit(1);
}

This approach works with any CI system (GitHub Actions, GitLab CI, etc.) by executing the script as a pre-build step.

Chaining Study and Redesign for Design Tokens

Extract design DNA from a reference site and apply it to your project, then export the resulting tokens for other tools:

// scripts/hallmark-integrate.js
const { execSync } = require('child_process');
const fs = require('fs');

// Extract DNA from a public URL
execSync('hallmark study https://www.usehallmark.com/examples/hum-07/', { stdio: 'inherit' });

// Apply the DNA to the current project (default target is the repo root)
execSync('hallmark redesign . --mood modern-minimal', { stdio: 'inherit' });

// Load the newly written log entry
const log = JSON.parse(fs.readFileSync('.hallmark/log.json', 'utf8'))[0];

// Export design tokens for downstream tools
fs.writeFileSync(
  'tokens.json',
  JSON.stringify({
    theme: log.theme,
    macrostructure: log.macrostructure,
    enrichment: log.enrichment,
  }, null, 2)
);

The resulting tokens.json file can be consumed by Tailwind config generators, CSS variable importers, or any build tool in your stack.

Syncing Design DNA to Figma

When running hallmark study with the --export flag, Hallmark writes a portable design.md file. You can read this in a Figma plugin to sync theme values:

// figma-plugin/main.ts
import { readFileSync } from 'fs';

// Hallmark writes a portable design description at the repo root
const design = JSON.parse(readFileSync('design.md', 'utf8'));

// Apply colours and typography from Hallmark's DNA
figma.root.setPluginData('theme', design.theme);
figma.root.setPluginData('typeScale', design.typography);

This keeps your Figma libraries in sync with the deterministic choices recorded in the Hallmark log.

Summary

• Hallmark writes to .hallmark/log.json after every verb execution, creating a deterministic record of macrostructure, theme, and enrichment choices.
• Three verbs form the integration surface: hallmark audit for quality gates, hallmark study for DNA extraction, and hallmark redesign for applying patterns.
• CI/CD integration involves parsing .hallmark/audit.json or .hallmark/log.json to abort builds or enforce diversification rules from slop-test.md.
• Cross-tool workflows export the log to tokens.json or design.md, allowing Figma plugins, Storybook, and style generators to consume Hallmark's design decisions.
• Reference files like microinteractions.md provide motion tokens that downstream tools can access once the log establishes the current theme context.

Frequently Asked Questions

How do I install Hallmark to use it in my CI pipeline?

Install Hallmark globally by running npx skills add nutlope/hallmark. This makes the hallmark command available in any shell environment, including CI runners. Because the tool is self-contained and writes to local JSON files, it requires no persistent server or API keys.

What is the difference between .hallmark/log.json and design.md?

.hallmark/log.json is a JSON array that stores the runtime history of all Hallmark operations in the current project, including the most recent macrostructure and theme selections. design.md is a portable, human-readable export generated by hallmark study --export that contains extracted DNA from an external reference, intended for importing into other tools like Figma or Notion.

Can I use Hallmark with GitHub Actions?

Yes. Add a step that runs hallmark audit on your build output, then parse .hallmark/audit.json in a subsequent step. If the JSON contains entries with severity >= 3, exit with a non-zero status code to fail the workflow. This pattern enforces design quality gates without leaving the GitHub ecosystem.

Which file contains the diversification rules I should enforce in my scripts?

The diversification rules (also called "slop tests") are defined in skills/hallmark/references/slop-test.md. Your scripts should read .hallmark/log.json and compare consecutive entries against these rules to ensure that new designs differ from previous runs on at least one axis—preventing repetitive "AI slop" layouts.

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