# How Hallmark Redesign Works: A Deep Dive Into the Two-Phase Workflow and Preservation Rules

> Discover how Hallmark redesign works with its two-phase workflow. Learn how it preserves copy intent, information architecture, brand assets, and primary actions for a seamless visual structure.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: deep-dive
- Published: 2026-08-15

---

**Hallmark redesign executes a strict two-phase workflow that detects whether the target is a single page or multi-page application, then applies a fresh visual structure while preserving copy intent, information architecture, brand assets, and primary actions.**

Hallmark redesign is the core verb in the `Nutlope/hallmark` repository responsible for giving existing web pages or entire sites a fresh visual structure without destroying the underlying product narrative. Unlike traditional refactoring tools that might rewrite logic or routes, this command focuses exclusively on the *look and feel* while safeguarding code integrity and brand consistency. The process is governed by specification documents located in [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md) that define exactly what gets transformed and what remains untouched.

## Scope Detection: Single-Page vs. Multi-Page

Hallmark redesign begins with **scope detection** to determine whether to treat the target as a single-page or multi-page operation. According to the verb documentation in `skills/hallmark/references/verbs/redesign.md#L15-L28`, the decision follows strict rules:

- **Multi-page** mode triggers when the target is a directory, a glob pattern, or the user explicitly mentions "the whole site"
- **Single-page** mode is the default when none of those signals appear, targeting individual component files

This detection happens before any file processing and dictates whether Hallmark will generate a shared [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) system or perform an isolated visual refresh.

## The Multi-Page Redesign Flow

When Hallmark redesign detects a multi-page target, it executes a five-step workflow designed to create a cohesive design system across the entire application.

### Step 1: Project Reading and Asset Gathering

Hallmark walks the target directory to list every page file and gathers existing design assets. As specified in `skills/hallmark/references/verbs/redesign.md#L37-L43`, this includes:

- [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) files containing CSS custom properties
- Tailwind configuration files
- Logo and brand asset directories

**What is preserved:** The existing brand colors, typefaces, copy, and information architecture remain intact during this discovery phase.

### Step 2: Creating the design.md Source of Truth

Hallmark generates (or updates) a single [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) (or [`DESIGN.md`](https://github.com/Nutlope/hallmark/blob/main/DESIGN.md)) file at the project root. This file becomes the **single source of truth** for all subsequent page redesigns, as documented in `skills/hallmark/references/verbs/redesign.md#L45-L55`.

The file locks in:
- Genre and macrostructure families
- Theme palette and color tokens
- Typography scale and font pairings
- Spacing systems and motion guidelines
- Micro-interaction patterns and CTA voice
- Per-page allowances and restrictions

**What is preserved:** All design tokens, the chosen macrostructure families, and the overall visual language become locked for the entire application.

### Step 3: Per-Page Redesign with Locked Systems

For each page in the target directory, Hallmark reads [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) first, then selects a macrostructure from the appropriate family defined in [`skills/hallmark/references/structure.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/structure.md). It applies the locked theme, typography, and spacing while injecting a CSS comment stamp containing design metadata, as noted in `skills/hallmark/references/verbs/redesign.md#L11-L18`.

```css
/* Hallmark · genre: modern-minimal · macrostructure: Long Document · design-system: design.md */

```

**What is preserved:** The copy intent, information architecture, brand palette, and primary actions remain unchanged; only the visual rhythm, component voice, reveal pattern, and structural fingerprint transform.

### Step 4: The Inverted Diversification Rule

Across pages of the same product, Hallmark inverts the normal diversification rule. According to `skills/hallmark/references/verbs/redesign.md#L20-L24`, the goal becomes **consistency** rather than variety. Theme, accent colors, and type-pairings stay identical across all pages; only the macrostructure may differ based on content needs.

**What is preserved:** This guarantees a cohesive design system where users experience unified branding regardless of which page they visit.

### Step 5: Controlled Amendments to design.md

If a specific page requires visual treatment that the current system does not allow, Hallmark updates [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) itself—adding per-page variants or extending the token system—rather than applying local overrides. This procedure, described in `skills/hallmark/references/verbs/redesign.md#L26-L28`, ensures the single source of truth remains authoritative.

**What is preserved:** The integrity of the design system documentation while allowing controlled extensions.

## The Single-Page Redesign Flow

When the target is a single component or file, Hallmark redesign follows a streamlined process that preserves core content while refreshing the visual presentation.

**Preserved elements:**
- **Copy intent and factual claims** – The literal wording appearing in the UI or explicitly requested by the user (`skills/hallmark/references/verbs/redesign.md#L36-L41`)
- **Information architecture** – Existing sections and their hierarchical order
- **Brand assets** – Colors, fonts, and brand identifiers already present in the codebase
- **Primary action** – The main CTA driving the user flow

**Replaced elements:**
- **Structural fingerprint** – A new macrostructure chosen from [`structure.md`](https://github.com/Nutlope/hallmark/blob/main/structure.md) that differs from the original layout (`skills/hallmark/references/verbs/redesign.md#L44-L46`)
- **Component voice and visual rhythm** – Button styles, divider language, image treatment, reveal patterns, and padding values

You can optionally supply a mood flag to influence the aesthetic direction:

```bash
hallmark redesign ./site/examples/najm/index.html --mood luxury

```

When a mood is provided, Hallmark maps it to a tone defined in [`skills/hallmark/references/typography.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/typography.md) and [`skills/hallmark/references/structure.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/structure.md), adjusting spacing and font selections accordingly (`skills/hallmark/references/verbs/redesign.md#L54-L57`).

## Non-Destructive Implementation Guarantees

Hallmark redesign operates under strict non-destructive rules documented in `skills/hallmark/references/verbs/redesign.md#L5-L12`. The system **never deletes** production routes, component directories, or existing logic unless the user explicitly approves a full rebuild.

Key preservation guarantees include:
- **Copy, IA, brand, and primary CTA** remain constant for both single-page and multi-page operations
- **Design assets** such as [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css), Tailwind configs, and logos are reused rather than regenerated
- **Code integrity** is maintained; only the visual "skin" changes while underlying functionality persists

## Practical Examples

### Redesigning a Single Page

```bash
hallmark redesign ./site/examples/wayfare/index.html

```

This command detects a single-page target, preserves the existing copy and layout hierarchy, selects a new macrostructure from [`structure.md`](https://github.com/Nutlope/hallmark/blob/main/structure.md) (such as "Long Document"), and applies the project's theme with a metadata stamp.

### Redesigning an Entire Application

```bash
hallmark redesign ./site/_tests/

```

This triggers multi-page mode, generating [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) at the repository root to define a unified theme and macrostructure families, then iterates over every page under `_tests/` while preserving each page's unique copy and information architecture.

## Summary

- Hallmark redesign uses **scope detection** to choose between single-page and multi-page workflows, as defined in the verb specification.
- **Multi-page redesigns** create a central [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file that acts as a locked design system, ensuring consistency across all pages while preserving copy and IA.
- **Single-page redesigns** refresh visual rhythm and structural fingerprint while safeguarding brand assets, copy intent, and primary CTAs.
- The process follows an **inverted diversification rule** for multi-page sites, prioritizing consistency over variety.
- Hallmark operates under **non-destructive implementation rules**, never deleting production routes or logic without explicit approval.

## Frequently Asked Questions

### What files does Hallmark redesign modify during a multi-page operation?

Hallmark redesign generates a [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file at the project root to serve as the single source of truth, then modifies individual page files to apply the locked design system. It reads from [`skills/hallmark/references/structure.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/structure.md) and [`skills/hallmark/references/typography.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/typography.md) but does not alter these reference files. Existing assets like [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) are read and reused but not overwritten.

### How does Hallmark redesign handle brand colors and fonts?

The system preserves existing brand colors, typefaces, and design tokens during the initial project reading phase. In multi-page mode, these assets get locked into [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) and applied consistently across all pages. For single-page redesigns, any colors or fonts already present in the target file are maintained while the surrounding visual structure changes.

### Can I customize the visual style during a Hallmark redesign?

Yes, you can supply a `--mood` flag (such as `--mood luxury`) when running the command. Hallmark maps this mood to specific tones defined in [`skills/hallmark/references/typography.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/typography.md) and [`skills/hallmark/references/structure.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/structure.md), adjusting spacing, font weights, and structural selections accordingly without altering the core copy or information architecture.

### What happens if one page needs a different design treatment than the others?

Rather than applying a local override, Hallmark redesign updates the central [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file to accommodate the new requirement—such as adding per-page variants or extending the token system. This maintains the authority of the single source of truth while allowing the design system to evolve to meet specific page needs.