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

> Integrate Hallmark with CI pipelines and design workflows by consuming its deterministic design fingerprints from log.json. Enforce diversification rules and sync design tokens seamlessly.

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

---

**You can integrate Hallmark with other tools by reading the [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/macrostructures.md) and [`component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/component-cookbook.md).
3.  Writes a stamp to [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) – Skill manifest declaring the three public verbs.
- [`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md) – Implements the audit workflow, produces [`.hallmark/audit.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/audit.json).
- [`skills/hallmark/references/verbs/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/study.md) – Extracts DNA from references, can emit [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md).
- [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md) – Writes the final stamp to [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json).
- [`skills/hallmark/references/slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md) – Defines diversification rules for preventing design stagnation.
- [`skills/hallmark/references/microinteractions.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) that style-guide generators can import.

### CI/CD Gating

Parse [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/microinteractions.md).

## Practical Implementation Examples

The following runnable scripts demonstrate how to integrate Hallmark with other tools using the [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.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:

```javascript
// 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:

```javascript
// 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) file. You can read this in a Figma plugin to sync theme values:

```typescript
// 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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/audit.json) or [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) to abort builds or enforce diversification rules from [`slop-test.md`](https://github.com/Nutlope/hallmark/blob/main/slop-test.md).
- **Cross-tool workflows** export the log to [`tokens.json`](https://github.com/Nutlope/hallmark/blob/main/tokens.json) or [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md), allowing Figma plugins, Storybook, and style generators to consume Hallmark's design decisions.
- **Reference files** like [`microinteractions.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) and [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md)?

[`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md). Your scripts should read [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.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.