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

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 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 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 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 (or 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 first, then selects a macrostructure from the appropriate family defined in 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.

/* 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 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 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:

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 and 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, 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

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 (such as "Long Document"), and applies the project's theme with a metadata stamp.

Redesigning an Entire Application

hallmark redesign ./site/_tests/

This triggers multi-page mode, generating 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 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 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 and skills/hallmark/references/typography.md but does not alter these reference files. Existing assets like 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 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 and 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 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.

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