How Hallmark's `redesign` Verb Preserves Information Architecture While Rebuilding the Visual Layer

Hallmark's redesign verb replaces only the visual and interaction layers of a webpage—typography, color, layout, and motion—while leaving the underlying information architecture intact, including content hierarchy, routing, and copy.

Hallmark is an open-source AI design tool that treats web pages as structured documents with separable concerns. Its redesign verb demonstrates how generative design can refresh aesthetics without disrupting the semantic foundation of a site. This article examines the specific mechanisms that ensure information architecture preservation during a visual overhaul.

What the redesign Verb Actually Changes

When you invoke hallmark redesign <target>, the tool performs a scoped transformation. According to skills/hallmark/SKILL.md (lines 27-30), the verb inspects the target's copy and IA—the DOM structure, routing table, and component ownership—then rebuilds the macro-structure and visual fingerprint while preserving those core elements.

The redesign touches:

• Layout rhythm and spatial relationships
• Typography pairings and type scale
• Color anchors and visual tokens
• Motion and interaction patterns

It explicitly does not touch:

• Literal copy (the text content)
• Page hierarchy and navigation structure
• Route definitions and URL schemes
• Component ownership (which component renders which content)

Single-Page vs. Multi-Page Redesign Flows

Single-Page In-Place Redesign

For individual pages, the redesign verb works directly on existing files. As specified in skills/hallmark/references/verbs/redesign.md (lines 17-31), it rewrites index.html and style.css but never removes or rewires existing routes or component files.

hallmark redesign ./site/examples/hum-07/index.html

This command refreshes the visual presentation of hum-07 while keeping every heading, paragraph, and link in exactly the same semantic position.

Multi-Page Design System Lock

For broader applications, the verb creates or updates a design.md file that locks the design system across the project. The skills/hallmark/references/design-md.md specification (lines 36-41) clarifies that this locked system only influences visual tokens, not page hierarchy.

hallmark redesign --multi-page ./my-app

Even with a project-wide redesign, the information architecture remains stable because design.md governs aesthetic variables—spacing scales, color themes, animation curves—not structural decisions.

The Audit Step: Confirming IA Before Visual Change

Before any redesign executes, Hallmark runs an audit that validates the existing information flow. The test notes in site/_tests/verbs/redesign/notes.md (lines 7-13) document this process: the audit confirms that copy and information flow are satisfactory, allowing the redesign to concentrate on rhythm, component voice, and layout.

This creates a clean separation of concerns:

1. Audit phase — Validates IA integrity
2. Design phase — Generates new visual layers

The redesign never triggers when the audit detects structural problems with content hierarchy.

Token-Based Styling: The Visual Swap Mechanism

Hallmark stores all visual decisions in tokens.css. During a redesign, it performs a token swap—replacing type pairings, color anchors, and motion values while keeping the semantic classes that anchor the IA.

This architecture, described in SKILL.md (lines 27-30), enables a complete visual transformation without reclassifying elements. A .hero class remains .hero; only its font-family, color, and padding values change.

Safety Checks: Preventing Accidental IA Breaks

The redesign verb includes explicit guardrails. Per skills/hallmark/references/verbs/redesign.md (lines 11-14), if a redesign would require:

• Removing many components
• Collapsing routes
• Otherwise breaking the IA

Hallmark pauses and requests explicit user confirmation before proceeding. This prevents "creative" AI decisions from restructuring a site's information architecture without oversight.

Driving the Visual Fingerprint with Mood

You can influence the redesign's aesthetic direction through the --mood flag:

hallmark redesign ./site/examples/tally/app.js --mood luxury

This parameter shapes the visual token selection—perhaps deeper shadows, serif type, restrained color—without altering the page's semantic structure or content flow.

Summary

• Scope limitation — redesign targets visual layers only, enforced by specification in SKILL.md and redesign.md
• File-level safety — Single-page redesigns rewrite index.html and style.css without touching routes or components
• System-level consistency — Multi-page redesigns use design.md for visual tokens, never for structural changes
• Pre-execution validation — Audits confirm IA integrity before any visual work begins
• Token architecture — tokens.css enables visual swaps while semantic classes preserve IA anchors
• Explicit confirmation — Destructive structural changes trigger user approval, preventing accidental IA loss

Frequently Asked Questions

What exactly qualifies as "information architecture" in Hallmark's redesign context?

Information architecture encompasses the hierarchy of content, copy text, routing structure, and brand semantics that organize how users navigate and understand a page. In Hallmark's implementation, this maps to DOM structure, the routing table, and component ownership—aspects the redesign verb explicitly preserves according to skills/hallmark/SKILL.md.

Can a redesign accidentally change my page's URL structure or navigation?

No. The specification in skills/hallmark/references/verbs/redesign.md (lines 17-31) states that single-page redesigns never remove or rewires existing routes. For multi-page applications, the design.md file governs visual tokens exclusively, leaving routing decisions untouched.

How does Hallmark prevent the AI from hallucinating new content during a redesign?

Two mechanisms enforce this: the audit step that precedes redesign validates existing copy and information flow (site/_tests/verbs/redesign/notes.md, lines 7-13), and the token-based styling system swaps only visual values while preserving semantic class names. Additionally, if proposed changes would significantly alter component structure, Hallmark requires user confirmation (redesign.md, lines 11-14).

What happens if I run redesign on a multi-page application without the --multi-page flag?

Without --multi-page, Hallmark treats the target as a single page and performs an in-place redesign of that specific file's index.html and style.css. This may create visual inconsistency across your application. The --multi-page flag generates or updates design.md to ensure coherent visual tokens project-wide while still preserving each page's individual information architecture.

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