How `hallmark redesign` Preserves Information Architecture During Visual Changes

hallmark redesign preserves information architecture by strictly separating structure from style: it locks the section order, copy, and content hierarchy while only replacing visual properties like layout, colors, and component styling.

The hallmark command-line tool (from Nutlope/hallmark) implements a systematic redesign workflow that treats information architecture as immutable. When you run a visual refresh, built-in safeguards ensure your page's logical flow, headings, and key messaging stay intact even as the UI receives a complete makeover.

The Core Principle: Structure vs. Style Separation

Hallmark's redesign philosophy rests on a single immutable rule: information architecture is sacred, visual presentation is flexible. This distinction is encoded directly in the rewrite rules found in skills/hallmark/references/verbs/redesign.md (lines 36–42), where the system explicitly mandates preserving "copy intent, factual claims, product names, and section order" while allowing the "visual fingerprint" to change.

This separation enables teams to refresh stale designs without risking user confusion or broken content flows.

Four Mechanisms That Protect Information Architecture

Scope Detection Distinguishes Page Contexts

Before any rewrite begins, Hallmark determines whether you're redesigning a single page or multiple pages. For single-page runs, it inspects the target file's existing sections and copy to establish a baseline. This scoping step—defined in redesign.md § Single‑page flow (lines 36–42)—prevents the system from making assumptions that could disturb local hierarchies.

Copy and Structure Lockdown

The "Preserve Copy & Structure" rule is the backbone of architectural stability. Hallmark:

• Retains original copy intent and factual claims
• Preserves product names and proper nouns
• Maintains exact section order
• Only modifies layout, component voice, reveal patterns, and visual rhythm

This rule appears in redesign.md under What to preserve (lines 36–42) and is enforced across every rewrite operation.

Design System Enforcement via design.md

When a design.md file exists at the project root, Hallmark treats it as a locked design system. The system reads this file first and constrains all redesigns to its defined parameters.

From redesign.md Project‑level check (lines 60–61), this ensures:

• Consistent theme variables (colors, typography)
• Fixed macro‑structure families that dictate page templates
• Hierarchy-preserving variations only

Stamp Logging for Traceability

Every output file receives a comment stamp recording the design rules applied. Example from redesign.md Redesign each page (line 17):

/* Hallmark · genre: modern‑minimal · macrostructure: Marquee‑Hero */

These stamps make future runs aware of what changed and what must stay constant, creating an audit trail for architectural decisions.

Concrete Example: Preserving Section Order

Consider a marketing page hero component. Original markup:

export default function Hero() {
  return (
    <section>
      <h1>{title}</h1>      {/* 1️⃣ Title – must stay first */}
      <p>{subtitle}</p>    {/* 2️⃣ Subtitle – second */}
      <CTA />               {/* 3️⃣ Primary call‑to‑action – third */}
    </section>
  )
}

After hallmark redesign applies a visual refresh:

/* Hallmark · genre: modern‑minimal · macrostructure: Marquee‑Hero */
export default function Hero() {
  return (
    <section className="hero bg-paper text-ink">
      <h1 className="display-lg">{title}</h1>
      <p className="body-md">{subtitle}</p>
      <CTA className="primary accent-bg" />
    </section>
  )
}

The hierarchy (h1 → p → CTA) remains identical. Only CSS classes, color values, and spacing utilities change.

Locked Design System in Practice

A generated design.md file acts as the single source of truth:

{
  "theme": {
    "color-paper": "oklch(0.95 0.03 210)",
    "color-ink":   "oklch(0.2 0.03 210)",
    "color-accent": "oklch(0.6 0.15 250)"
  },
  "typography": {
    "display": "Geist, 600",
    "body":    "Geist, 400"
  },
  "macrostructure": {
    "marketing": "Marquee Hero",
    "app":       "Workbench",
    "content":   "Long Document"
  }
}

All pages reference this file. During redesign, macro‑structure families are selected from predefined options, guaranteeing consistent section ordering across the entire site.

Key Source Files

File	Role in Preserving Architecture
skills/hallmark/references/verbs/redesign.md	Defines the complete redesign workflow, including "preserve copy & structure" rules
design.md (generated by Hallmark)	Locked design system: theme, typography, and macro‑structure families
site/index.html	Example page showing original information hierarchy
site/js/main.js	Interactive component logic—Hallmark never rewrites this, preserving functional architecture

Summary

• hallmark redesign enforces structure-style separation through explicit rules in redesign.md
• Scope detection establishes context before any changes occur
• Copy and section order lockdown prevents accidental hierarchy disruption
• design.md design system provides cross-page consistency for macro‑structures
• Stamp logging creates traceable records of what changed and what persisted

Frequently Asked Questions

What happens if my original page has poor information architecture?

Hallmark preserves whatever hierarchy exists—it does not improve or restructure poorly organized content. The tool assumes your source architecture is intentional. For structural overhauls, you would need to manually reorganize sections before running hallmark redesign.

Can I override the structure preservation rules?

No. The "preserve copy & structure" directives in redesign.md are core to Hallmark's redesign verb. If you need structural changes, use a different workflow or edit files directly. The tool intentionally prevents accidental architectural drift during visual refreshes.

How does Hallmark handle interactive components?

Hallmark leaves JavaScript logic untouched. Files like site/js/main.js retain their original functionality—the system only modifies visual presentation layers (HTML structure, CSS classes, and associated styling). This preserves both information architecture and functional behavior.

Does the design.md file work across multiple projects?

Each design.md is scoped to its project root where Hallmark discovers it. The file auto-generates based on that specific codebase's patterns. For multi-project consistency, you would manually replicate the design.md structure and values across repositories.

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