how-to-guide

How to Use Hallmark for Design System Creation: A Token-First Workflow

July 31, 2026 Nutlope/hallmark ↗

Hallmark is a self-contained design skill that extracts visual DNA from any URL or screenshot and converts it into a token-driven design system using OKLCH color values, portable Markdown specifications, and CSS custom properties.

Nutlope/hallmark provides a CLI-based workflow that transforms visual references into reusable, version-controlled design systems. When you use Hallmark for design system creation, you move from raw inspiration to production-ready CSS tokens without manual color picking or inconsistent font stacks.

Extract Visual DNA with the Study Verb

The workflow begins by feeding Hallmark a live URL or screenshot to analyze. This initiates the study verb, which extracts the visual "DNA" of the target design.

Run the study command against any public URL:

hallmark study https://example.com

According to the implementation in [SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) at step 2.6 ("Theme route – studied-DNA"), this process captures:

Macrostructure and layout archetypes
Color values in OKLCH format for perceptual uniformity
Font pairings and typography scales
Visual patterns and component relationships

The output is a diagnostic report that maps the extracted aesthetics to Hallmark's token architecture.

Lock the Design System into design.md

Once Hallmark extracts the DNA, you must lock the system to create a portable specification. This generates a design.md file that serves as the single source of truth for your project.

Trigger the lock by running:

hallmark design-md

Or instruct Hallmark to "lock the system" after a study session completes.

The generation logic lives in [references/design-md.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md). This file documents the complete rule-set for serializing color palettes, typography scales, spacing systems, and component patterns into a version-controlled Markdown format that any developer can reference.

Consume the Token Stylesheet

With the design system locked, you import the central token file into your frontend. Hallmark provides a comprehensive CSS file containing all 20 catalog themes plus custom-theme scaffolding.

Add the stylesheet and theme attribute to your HTML:

<!doctype html>
<html data-theme="cobalt">
<head>
  <meta charset="utf-8">
  <link rel="stylesheet" href="site/css/tokens.css">
  <title>My Project</title>
</head>
<body>
  <header class="hero">…</header>
</body>
</html>

The [site/css/tokens.css](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) file contains:

OKLCH color variables for perceptually uniform palettes
Font stack definitions using var(--font-display) and var(--font-body)
Theme-specific overrides activated via the data-theme attribute
Spacing, radius, and elevation tokens

Reference these tokens in your component CSS:

.button {
  background: var(--color-accent);
  color: var(--color-accent-ink);
  font-family: var(--font-display);
  border-radius: var(--radius-pill);
}

Toggle themes at runtime using JavaScript:

document.querySelector('#themeToggle').addEventListener('click', () => {
  const html = document.documentElement;
  const currentTheme = html.dataset.theme;
  html.dataset.theme = currentTheme === 'cobalt' ? 'midnight' : 'cobalt';
});

Build Custom Brand Themes

When your brief requires a unique look or specific brand colors, Hallmark bypasses the catalog themes to generate a bespoke system. This occurs when the input contains a custom-theme signal, such as specific hex codes or unique font requirements.

The custom palette logic uses OKLCH color spaces to generate harmonious derivatives and free-font pairings. This implementation is defined in [references/custom-theme.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md), which handles the translation of brand constraints into token-compatible values.

Validate Quality with the Slop-Test

Before finalizing the system, Hallmark runs a 58-gate slop-test to enforce quality standards and prevent AI-generated anti-patterns. This validation checks:

Token usage consistency (no inline colors)
Typography purity (no mixed font stacks)
Responsive breakpoint compliance
Constraint adherence from [references/anti-patterns.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/anti-patterns.md)

The test suite is documented in [references/slop-test.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md) and executes automatically after generation to ensure the design system meets production standards.

Enforce Diversification Across Iterations

Hallmark records every generation in .hallmark/log.json to prevent repetitive outputs. This project-memory file stores recent macrostructure and theme choices, enforcing the Theme-diversification rule defined in [SKILL.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md).

When you iterate on a project, Hallmark consults this log to guarantee that successive builds differ in paper-band layout, display-style treatment, or accent-hue selection, ensuring visual variety while maintaining systemic consistency.

Summary

Hallmark converts URLs and screenshots into token-driven design systems through a structured study-and-lock workflow.
Run hallmark study to extract OKLCH colors, font pairings, and macrostructure from any visual reference.
Execute hallmark design-md to generate a portable design.md specification file.
Import site/css/tokens.css and set data-theme attributes to activate themes in HTML.
Create bespoke themes via the logic in references/custom-theme.md when brand-specific requirements exist.
Pass the 58-gate slop-test to validate token usage and eliminate anti-patterns before production.

Frequently Asked Questions

How do I extract design tokens from an existing website?

Use the hallmark study command followed by the target URL. Hallmark analyzes the visual DNA—including OKLCH color values, typography pairings, and layout macrostructure—and outputs a diagnostic report mapping these to token-compatible values as defined in SKILL.md step 2.6.

What file contains all the color and font tokens?

The [site/css/tokens.css](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) file contains the complete token definitions for all 20 catalog themes plus custom-theme scaffolding. It uses CSS custom properties for OKLCH colors (var(--color-accent)), font stacks (var(--font-display)), and spacing values.

How does Hallmark prevent repetitive design outputs?

Hallmark maintains a .hallmark/log.json file that records previous macrostructure and theme selections. Before generating new designs, it consults this log to enforce diversification rules, ensuring successive runs vary in paper-band layout, display styles, or accent hues while maintaining systemic coherence.

What is the slop-test and when does it run?

The slop-test is a 58-gate quality validation defined in [references/slop-test.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md). It automatically executes after generation to verify token usage consistency, typography purity, and compliance with anti-patterns documented in references/anti-patterns.md, blocking low-quality outputs from reaching production.

Have a question about this repo?

These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:

Share the following with your agent to get started:

curl -s "https://instagit.com/install.md"

Add to your MCP client configuration:

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

Ask your agent:

"Use Instagit MCP to understand how Nutlope/hallmark works."

Works with

Claude Codex Cursor VS Code OpenClaw Any MCP Client

Maintain an open-source project? Get it listed too →