How to Use the Redesign Verb in Hallmark Without Breaking Existing Code

The hallmark redesign command applies non-destructive transformations to your UI by editing files in-place or adding new components while requiring explicit confirmation before deleting any existing production code.

The redesign verb in Hallmark reshapes visual and interaction layers according to strict safety protocols defined in the Nutlope/hallmark source code. Whether you are updating a single landing page or refactoring an entire application, the implementation in skills/hallmark/references/verbs/redesign.md ensures that existing routes, component hierarchies, and business logic remain intact unless you explicitly grant permission for removal.

Automatic Scope Detection

The verb begins by analyzing your target to determine whether to invoke single-page or multi-page rules.

Multi-page triggers include directory paths, glob patterns, multiple files specified in the brief, or natural language phrases such as "the whole site". When Hallmark detects any of these signals, it enters the multi-page redesign flow and treats your project as a unified application.

Single-page mode activates when you target an individual file and none of the multi-page indicators are present. This distinction is critical because each mode follows different preservation rules and output formats.

Non-Destructive Safety Guarantees

According to the implementation in skills/hallmark/references/verbs/redesign.md, the verb adheres to a strict non-destructive contract:

• Never delete existing route files, component directories, or page trees by default
• Perform in-place edits on named files or add new components/tokens that wire through existing routes
• Pause for confirmation if the redesign requires removing many components or collapsing application structure, displaying the specific files affected before proceeding

This safety layer ensures that running the redesign verb against production codebases carries minimal risk of data loss.

Multi-Page Redesign Workflow

When scope detection identifies a multi-page project, Hallmark executes a four-phase workflow that centralizes design decisions:

1. Project Audit and Design System Creation

Hallmark first lists each page file, catalogs existing design assets such as tokens.css or Tailwind configurations, and reads previous entries from .hallmark/log.json. It then generates a design.md file at your project root, which serves as the single source of truth for theme, typography, spacing, motion, and macro-structure families.

2. Consistent Page Transformation

When redesigning each page, Hallmark reads design.md first to apply locked theme values and select macro-structures from declared families. Each modified file receives a comment stamp such as /* Hallmark · genre: modern-minimal */ to signal that the page belongs to a managed design system.

The diversification rule is inverted for multi-page contexts: all pages share identical themes, colors, and typography, with only macro-structure permitted to vary across the application.

3. Audit Logging

Upon completion, Hallmark writes a single entry with "scope": "app" to .hallmark/log.json, creating a versioned history that supports rollback and compliance auditing.

Single-Page Redesign Workflow

Single-page mode prioritizes surgical precision over system-wide consistency:

Preserved elements include your copy intent, information architecture, brand colors/fonts, and primary action hierarchy.

Replaced elements encompass the structural fingerprint, component voice, reveal pattern, and visual rhythm, drawn from combinations defined in skills/hallmark/references/structure.md.

You may optionally pass --mood <name> to shift the tone, which maps to entries in skills/hallmark/references/typography.md and structure.md to adjust typographic treatment without altering your content.

Handling Project-Level Design Systems

If your repository already contains a design.md file at the project root, Hallmark supersedes the single-page rules and automatically follows multi-page conventions. This ensures that individual page redesigns remain consistent with your established design system, reading the centralized theme configuration before applying any changes.

Practical Examples

Redesign a Single File

hallmark redesign ./site/examples/custom-01/index.html

This command detects a single file, preserves existing copy and brand tokens, selects a new structural fingerprint from structure.md, and returns updated HTML/CSS with a genre comment stamp.

Redesign Multiple Pages with Mood

hallmark redesign ./site/examples --mood luxury

Hallmark detects the directory, prompts for confirmation to create design.md and redesign all pages, then applies the "luxury" mood mapping from typography.md while logging a single entry to .hallmark/log.json.

Explicit Deletion Scenarios

If you specify flags that would trigger file removal, Hallmark stops execution and displays the complete list of files targeted for deletion, requiring explicit y/n confirmation before proceeding.

Summary

• Scope awareness automatically selects single-page or multi-page workflows based on your target path
• Non-destructive defaults prevent deletion of production files without explicit confirmation
• Centralized design systems via design.md ensure consistency across multi-page applications
• Audit trails in .hallmark/log.json provide versioned history for rollbacks
• Genre stamps in modified files prevent accidental drift from established design patterns

Frequently Asked Questions

Will the redesign verb delete my existing React components or route files?

No. According to the non-destructive implementation rule in skills/hallmark/references/verbs/redesign.md, Hallmark never deletes existing route files, component directories, or page trees by default. If a redesign would require significant component removal, the CLI stops and asks for explicit confirmation before proceeding.

What happens if I run redesign on a project directory instead of a single file?

Hallmark enters the multi-page redesign flow, audits the entire project, creates a root-level design.md file, and applies consistent theming across all pages while allowing macro-structure variations. The diversification rule is inverted in this mode, ensuring unified colors and typography across the application.

How does Hallmark maintain design consistency across multiple pages?

The tool generates a design.md file that acts as the single source of truth for theme, typography, spacing, and motion. All pages reference this file during redesign, and each modified file receives a comment stamp like /* Hallmark · genre: modern-minimal */ to mark it as part of the design system.

Can I customize the visual style without rewriting my content?

Yes. Use the --mood <name> flag to map your content to different aesthetic treatments defined in skills/hallmark/references/typography.md and structure.md. In single-page mode, Hallmark preserves your copy intent, information architecture, and brand colors while replacing only the structural fingerprint and visual rhythm.

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