# How to Use Hallmark for Design System Creation: A Token-First Workflow
> Learn to create a design system with Hallmark. Extract visual DNA from URLs or screenshots to generate tokens, Markdown specs, and CSS custom properties for a token-first workflow.
- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-07-31
---
**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:
```bash
hallmark study https://example.com
```
According to the implementation in [[`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) file that serves as the single source of truth for your project.
Trigger the lock by running:
```bash
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/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:
```html
My Project…
```
The [[`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/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:
```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:
```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/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/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/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`](https://github.com/Nutlope/hallmark/blob/main/.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/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`](https://github.com/Nutlope/hallmark/blob/main/design.md) specification file.
- Import **[`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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)](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`](https://github.com/Nutlope/hallmark/blob/main/.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/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`](https://github.com/Nutlope/hallmark/blob/main/references/anti-patterns.md), blocking low-quality outputs from reaching production.