How to Use `hallmark redesign` to Rebuild Existing Pages

hallmark redesign is a command-line verb that regenerates the visual structure of existing HTML pages while preserving content, information architecture, and brand tokens, supporting both single-page refreshes and multi-page theme updates.

The hallmark redesign verb in the Nutlope/hallmark repository provides a non-destructive way to rebuild existing web pages. It analyzes your current HTML and CSS, selects new macro-structures from a predefined catalog, and outputs redesigned markup that maintains your original copy and routing logic.

How the Redesign Flow Works

Scope Detection and Flow Selection

Hallmark first determines whether you are targeting a single page or multiple pages by examining the path you provide. According to the specification in skills/hallmark/references/verbs/redesign.md, if you pass a directory path or glob pattern (e.g., ./site/), Hallmark triggers a multi-page redesign. If you pass a single file (e.g., ./index.html), it runs a single-page redesign.

Single-Page Redesign Process

When targeting one HTML file, Hallmark reads the existing page and selects a different macro-structure from the catalog defined in skills/hallmark/references/structure.md. It swaps component voices—such as buttons, dividers, and image treatments—changes the reveal pattern, and tweaks visual rhythm. This process never touches routing, data fetching, or server-side code unless you explicitly approve a full rebuild.

Multi-Page Redesign Process

When targeting a directory, Hallmark creates or updates a project-level design.md file at the repository root. This file becomes the single source of truth for theme, typography, spacing, motion, and micro-interactions. All pages then reference this design system and only vary in macro-structure or component archetypes.

Output and Design Stamping

After processing, Hallmark returns newly-generated HTML and CSS with a stamped comment recording the design choices. For example:

<!-- Hallmark · genre: modern‑minimal · macrostructure: marquee‑hero · design-system: design.md · designed-as-app -->

This fingerprint enables future Hallmark runs to detect "slop" (inconsistent design) across your codebase.

Running Your First Redesign

Install the Skill

Add Hallmark to your project once using:

npx skills add nutlope/hallmark

Redesign a Single Page

Target a specific HTML file to refresh its visual layout while preserving content:

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

Hallmark will output a confirmation list showing exactly which files it intends to modify, then wait for your approval before proceeding.

Redesign an Entire Site

Target a directory to apply a unified design system across all pages:

hallmark redesign ./site

This command walks the directory, lists every page, generates or updates design.md, and applies locked theme variables (such as --color-paper and --font-display) across all files.

Apply Mood-Based Tones

Use the optional --mood flag to guide the visual tone. Hallmark maps the mood to definitions in skills/hallmark/references/typography.md and skills/hallmark/references/structure.md:

hallmark redesign ./site/examples/wayfare/index.html --mood luxury

Valid moods include luxury and playful, each selecting specific font families, weights, and spacing rhythms.

Safety and Non-Destructive Changes

Hallmark follows a strict non-destructive rule defined in lines 5–13 of skills/hallmark/references/verbs/redesign.md. It never deletes route files or component directories without explicit consent. Before making changes, it displays a prompt similar to:

I will modify:
  - site/examples/wayfare/index.html
No files will be deleted unless you confirm.
Proceed? (y/n)

You must reply y to allow the operation to continue.

Key Configuration Files

Understanding these reference files helps you predict how hallmark redesign will transform your pages:

• skills/hallmark/references/verbs/redesign.md — The complete specification for the redesign verb, including single- vs multi-page logic, mood handling, and output formats.

• design.md (generated) — The project-wide design system file created at your repository root during multi-page redesigns. It locks theme variables, typography scales, and motion settings.

• skills/hallmark/references/structure.md — The catalog of available macro-structures, including marquee-hero, long-document, and app-workbench. Hallmark selects from these when restructuring pages.

• skills/hallmark/references/typography.md — Defines typographic "tones" and maps mood names to specific font families, weights, and tracking values.

Summary

• hallmark redesign rebuilds existing pages by swapping macro-structures and visual styles while preserving your original content and information architecture.
• Single-page redesigns target individual files and select new layouts from structure.md, while multi-page redesigns generate a root-level design.md to unify themes across directories.
• The --mood flag adjusts tone by referencing typography.md, supporting options like luxury and playful.
• Hallmark operates non-destructively, requiring explicit confirmation before modifying or deleting files, as specified in the redesign verb documentation.

Frequently Asked Questions

What is the difference between single-page and multi-page redesign?

A single-page redesign targets one HTML file and selects a new macro-structure from the catalog without creating shared theme files. A multi-page redesign targets a directory, generates or updates a root-level design.md file, and applies consistent theme variables across all discovered pages.

How does the --mood flag affect the output?

The --mood flag maps to specific typographic and structural tones defined in skills/hallmark/references/typography.md and skills/hallmark/references/structure.md. For example, --mood luxury selects refined font weights and spacious layouts, while --mood playful uses looser tracking and more whimsical macro-structures.

Will hallmark redesign delete my existing files?

No. Hallmark follows a non-destructive rule that prevents deletion of route files or component directories without your explicit approval. Lines 5–13 of skills/hallmark/references/verbs/redesign.md mandate that Hallmark list all intended modifications and wait for confirmation before proceeding.

Where are the design choices recorded after a redesign?

Each redesigned page receives a stamped comment in its HTML or CSS containing the design fingerprint, including genre, macro-structure, and design-system reference. For example: <!-- Hallmark · genre: modern‑minimal · macrostructure: marquee‑hero · design-system: design.md -->. This stamp enables future Hallmark runs to detect design inconsistencies.

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