How `hallmark redesign` Maintains Information Architecture: A Technical Deep-Dive

Hallmark's redesign command preserves your page's information architecture by keeping sections, content order, and core copy intact while swapping only the visual structural fingerprint.

When redesigning a website, the risk of breaking your content hierarchy is real. The hallmark CLI solves this by treating information architecture (IA) as immutable during its redesign operation. This article examines exactly how the tool enforces this preservation, using the actual implementation from the Nutlope/hallmark repository.

What Information Architecture Means in Hallmark

In the Hallmark system, information architecture refers to three specific elements:

• Which sections exist on a page
• The rough order of those sections
• The hierarchy of headings and content blocks

According to [redesign.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md), the verb "preserves the information architecture (which sections exist, in roughly what order)" as a non-negotiable rule. This separation of concerns—content structure versus visual presentation—is the foundation of Hallmark's non-destructive approach.

The Five Mechanisms of IA Preservation

Preserve Existing Sections and Order

The redesign process starts by cataloging your current page structure. Every heading, sub-heading, and major content block is recorded before any transformation occurs. This inventory becomes a constraint that the new design must satisfy.

The system reads sections from your source HTML (such as [site/index.html](https://github.com/Nutlope/hallmark/blob/main/site/index.html)), notes their sequence, and ensures the output maintains that same flow even as visual treatments change.

Keep Copy Intent Intact

Beyond structure, Hallmark preserves the actual content. The [redesign.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md) specification states that redesign must "preserve the copy intent, factual claims, product names, and primary message."

This means:

• Original copy is moved verbatim unless you explicitly request a rewrite
• Product names and factual claims remain unchanged
• Primary messaging stays consistent

The text travels to its new structural container without alteration.

Respect Brand Constraints

While visual style transforms, brand fundamentals remain locked. Hallmark draws from either:

• The existing [tokens.css](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) for color, typography, and spacing variables
• A project-level design.md for custom design system rules

This ensures visual consistency across your site even as individual pages receive new macrostructures.

Swap Only the Structural Fingerprint

The actual "redesign" happens by selecting a different combination of the six axes defined in [structure.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/structure.md):

Axis	Controls
Section-heading placement	Where headers appear within sections
Body composition	How content is arranged within containers
Divider language	Visual separators between sections
Button voice	CTA styling and microcopy patterns
Image treatment	How visuals are framed and displayed
Reveal pattern	Scroll and load animations

A structural fingerprint is the specific combination of choices across these six axes. Redesign picks a new fingerprint that differs from the original, creating visual freshness without touching IA.

Apply Macrostructure-Driven Variation

Rather than manual axis selection, Hallmark typically chooses a macrostructure—a named bundle of axis choices. The [macrostructures.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md) file defines 21 options including:

• Bento Grid: Card-based, modular layouts
• Long Document: Editorial, scroll-driven reading
• Marquee Hero: Cinematic, motion-heavy introductions

When you run hallmark redesign, the system applies your selected or auto-chosen macrostructure atop the preserved IA, delivering cohesive new layouts without rearranging content.

Running hallmark redesign

Here are the practical commands that implement these preservation rules:

# Basic redesign: preserves IA, picks new fingerprint automatically

hallmark redesign ./site/index.html

# Influence the new fingerprint with a mood hint

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

# Multi-page redesign: builds shared design system first

hallmark redesign ./site/ --scope multi

Each execution follows this internal flow:

1. Read target file(s) and list existing sections
2. Preserve section order and copy content
3. Select new macrostructure or structural fingerprint
4. Apply new headings placement, image treatments, button styles, etc.
5. Output revised HTML/CSS with tracking comment:

<!-- Hallmark · macrostructure: Bento Grid · fingerprint: 0x3A7F -->

How IA Preservation Appears in Source Files

The commitment to information architecture maintenance is documented across multiple reference files:

• [structure.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/structure.md): Defines the six axes that constitute a fingerprint—separate from content hierarchy
• [macrostructures.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures.md): Bundles axis choices into named layouts that don't affect section ordering
• [redesign.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md): Explicitly forbids IA modifications in the verb specification
• [site/index.html](https://github.com/Nutlope/hallmark/blob/main/site/index.html): Demonstrates preserved IA (hero → examples → skills → anti-patterns) across redesigns
• [tokens.css](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css): Maintains consistent design variables regardless of structural changes

Summary

• Information architecture is locked: sections, order, and copy hierarchy remain unchanged during hallmark redesign
• Visual structure is fluid: the six axes and macrostructures provide unlimited layout variation
• Content travels intact: copy intent, factual claims, and primary messaging survive the transformation
• Brand stays consistent: tokens and design system rules persist across all redesign variations
• Implementation is transparent: tracking comments in output files document which macrostructure was applied

Frequently Asked Questions

What exactly does "information architecture" mean in Hallmark?

Information architecture in Hallmark refers specifically to the organizational structure of your page: which sections exist, their relative order, and the hierarchy of headings within them. It does not include visual styling, layout grids, or animation patterns. The [redesign.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md) specification treats IA as immutable while allowing complete freedom in the visual domain.

Can I force Hallmark to reorder my sections during redesign?

No. The redesign verb explicitly forbids IA modifications. If you need structural reorganization, you would use a different verb or manual editing. The tool's architecture separates "what the page says" from "how it looks"—redesign only handles the latter. For content reordering, consider preprocessing your HTML or using Hallmark's lower-level API verbs.

How does Hallmark ensure my brand colors and fonts persist?

The system reads from [tokens.css](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css) or a project-level design.md before applying any new macrostructure. These design tokens define your color palette, type scale, spacing system, and other brand fundamentals. The redesign applies new structural patterns while respecting these constraints, ensuring visual consistency even as layout patterns change dramatically.

What's the difference between a structural fingerprint and a macrostructure?

A structural fingerprint is the specific combination of choices across all six axes defined in [structure.md](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/structure.md)—essentially a complete description of how a page is visually constructed. A macrostructure is a named preset (like Bento Grid or Long Document) that bundles a coherent set of axis choices. Macrostructures provide 21 high-level starting points; fingerprints represent the full combinatorial space of possible designs.

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