How the Hallmark Redesign Verb Works: Scope, Safety Checks, and Execution Flow

The hallmark redesign verb performs a structural reset by rebuilding the visual layout and interaction layer of a page or entire application while preserving existing content, information architecture, and any locked design system defined in a project-level design.md file.

The hallmark redesign verb is the primary structural transformation command in the Hallmark open-source repository. It enables developers to regenerate UI components and visual layouts without losing underlying copy or information architecture (IA). According to the source code in skills/hallmark/references/verbs/redesign.md, this operation supports both single-file transformations and multi-page application redesigns while respecting existing design constraints.

Scope Determination: Single Page vs. Multi-Page

When invoked, Hallmark first determines the target scope by analyzing the command arguments. This decision drives the execution flow defined in skills/hallmark/references/verbs/redesign.md (lines 17-27).

Single-page redesigns target specific component files (e.g., ./src/pages/hero.tsx). Hallmark rewrites the target file by generating a new macro-structure—creating a fresh component hierarchy, layout rhythm, and CSS tokens—while preserving the page's existing copy and IA. The operation outputs a new index.html and companion style.css as documented in site/_tests/verbs/redesign/README.md (line 8).

Multi-page redesigns trigger when the --multi-page flag is used. In this mode, Hallmark creates or updates a design.md file at the repository root, capturing the new design system for all pages (redesign.md lines 47-52). A single log entry is written to .hallmark/log.json with "scope": "app" (redesign.md line 218).

Design System Compliance and Locked Constraints

Before executing any visual changes, Hallmark checks for a project-level design.md or DESIGN.md at the repository root. If this file exists, it is treated as a locked design system for the entire application. The redesign verb respects these constraints rather than creating a divergent structure, as specified in skills/hallmark/SKILL.md (line 153).

This ensures that organizational branding, color palettes, and typography scales remain consistent across redesign operations unless the user explicitly opts out or removes the lock file.

Mood, Genre, and Visual Tone Mapping

The redesign verb supports optional flags that influence the visual output without altering content. The --mood <name> parameter maps to tone definitions in typography and structure references, applying specific aesthetic characteristics to the generated layout.

For genre transformations—such as converting an editorial page into a modern SaaS hero section—Hallmark loads the appropriate genre file from the genres/ folder and applies its rule overlay (redesign.md lines 258-259). This allows for dramatic visual shifts while maintaining the underlying information hierarchy.

Execution Flow and Generated Artifacts

The redesign process follows a disciplined execution path:

1. Content Preservation: Hallmark extracts existing copy and IA from the target file.
2. Structure Generation: It creates a new macro-structure with updated component hierarchy and interaction patterns.
3. Asset Production: For single-page operations, it generates fresh index.html and style.css files.
4. System Documentation: For multi-page operations, it updates the root design.md to reflect the new system-wide standards.

After completion, Hallmark appends a note to the operation log indicating the changes and includes a flag (studied: no · context: redesign) that downstream verbs like audit can read to verify the new macro-structure was intentional (site/_tests/verbs/redesign/notes.md lines 62-66).

Safety Checks and User Confirmation

The redesign verb includes built-in safeguards against destructive changes. If the operation would require removing numerous components, collapsing routes, or drastically altering the application's structure, Hallmark pauses execution and requests explicit user confirmation (redesign.md lines 11-12).

This prevents accidental architectural changes that could break routing or remove critical functionality while still allowing intentional structural resets when confirmed.

Practical Usage Examples

Run the redesign verb from your terminal using the following patterns:

# Redesign a single page (default behavior)

hallmark redesign ./src/pages/hero.tsx

# Redesign with a specific mood mapping

hallmark redesign ./src/pages/hero.tsx --mood luxury

# Multi-page redesign with system-wide design.md creation

hallmark redesign --multi-page

After executing hallmark redesign ./src/pages/hero.tsx, the system produces a fresh index.html and style.css that retain the original copy but feature a new layout, component hierarchy, and interaction patterns. The accompanying log entry in .hallmark/log.json records the operation for future audits.

Summary

• The hallmark redesign verb rebuilds visual layouts while preserving content and information architecture.
• Scope determination occurs first, distinguishing between single-page file rewrites and multi-page system updates.
• Design system locks in design.md at the repository root constrain the redesign to existing organizational standards.
• Mood and genre flags (e.g., --mood luxury) map to specific aesthetic rules without altering content structure.
• Safety checks pause execution for confirmation when detecting potentially destructive structural changes.
• Audit trails in .hallmark/log.json and operation notes enable downstream verbs to verify intentional redesigns.

Frequently Asked Questions

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

Single-page redesigns target specific component files and generate fresh index.html and style.css outputs while preserving the original copy. Multi-page redesigns use the --multi-page flag to create or update a root-level design.md file that establishes a locked design system for the entire application, logging the operation with "scope": "app" in .hallmark/log.json.

How does Hallmark prevent redesigns from breaking existing design systems?

Hallmark checks for a design.md or DESIGN.md file at the repository root before executing changes. If present, this file acts as a locked design system that constrains the redesign operation, ensuring the new visual layout respects existing color palettes, typography, and component patterns rather than creating divergent styles.

What happens if a redesign would remove too many components or collapse routes?

The redesign verb includes safety checks that trigger when the operation would drastically alter application structure, remove numerous components, or collapse routes. When detected, Hallmark pauses execution and requests explicit user confirmation before proceeding, preventing accidental destructive changes while allowing intentional structural resets.

Can I change the visual style without altering the content structure?

Yes. Use the --mood <name> flag to apply specific aesthetic characteristics without changing the underlying information architecture. For more dramatic visual shifts, such as converting an editorial layout to a SaaS hero section, Hallmark supports genre transformations by loading rule overlays from the genres/ folder, preserving your content while completely rebuilding the visual presentation.

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