# How to Use the `hallmark redesign` Command: Complete Guide to Visual Restructuring

> Master the hallmark redesign command to visually restructure pages while keeping your content, IA, and brand intact. Learn how to use this powerful tool with our complete guide.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-08-07

---

**The `hallmark redesign` command rebuilds pages with fresh visual structures while preserving copy, information architecture, and brand identity.**

The `hallmark redesign` command is one of four primary verbs in the Hallmark AI design system. It intelligently detects whether you're targeting a single file or entire directory, then applies non‑destructive visual transformations based on documented architectural rules. This guide covers scope detection, single‑page and multi‑page flows, and practical usage patterns.

## What `hallmark redesign` Does

Hallmark's redesign verb follows a clear philosophy: **throw out the structure, keep copy + IA + brand, rebuild with a different fingerprint**. According to the [README.md](https://github.com/Nutlope/hallmark/blob/main/README.md#L22-L24), this makes it distinct from other verbs like `polish` or `refactor`.

The complete verb specification lives in [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md). This file defines scope detection logic, multi‑page versus single‑page flows, non‑destructive safeguards, and exact implementation steps.

### Core Principles

- **Non‑destructive by default** – No route files, component directories, or production assets are deleted without explicit user confirmation (lines 5‑13)
- **Preserve what matters** – Copy, information architecture, and brand identity always survive
- **Replace what changes** – Macrostructure and component voice are regenerated fresh

## Single‑Page vs. Multi‑Page Detection

Hallmark's first step is always **scope detection** (lines 15‑28). The target path determines which pipeline runs:

| Target Type | Pipeline | Output |
|-------------|----------|--------|
| Single file (e.g., [`hero.tsx`](https://github.com/Nutlope/hallmark/blob/main/hero.tsx)) | Single‑page flow | Redesigned component with new macrostructure |
| Directory or glob (e.g., `./src/pages/`) | Multi‑page flow | Updated [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) system file + redesigned pages |

### Single‑Page Flow Details

When Hallmark detects a single file:

1. **Preserves** – Copy, IA, and brand colours from the file and surrounding [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css)
2. **Replaces** – Macrostructure (selected from [`structure.md`](https://github.com/Nutlope/hallmark/blob/main/structure.md)) and component voice
3. **Returns** – Updated file with explanation of changes

Optional **mood parameter** guides tone selection:

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

```

Available moods shape the redesign's personality without altering core content.

### Multi‑Page Flow Details

When Hallmark detects a directory:

1. Creates or updates [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) at project root
2. [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) becomes single source of truth for themes, colour palettes, typography, spacing, motion, and CTA voice (lines 31‑66)
3. Each page is redesigned using this system, with per‑page macrostructure variation still allowed

The [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) template follows [`skills/hallmark/references/design-md.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md) for canonical layout structure.

## Practical Command Examples

```bash

# Redesign a single component file

hallmark redesign ./src/pages/hero.tsx

# Redesign an entire route directory

hallmark redesign ./src/pages/

# Redesign with explicit mood guidance

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

```

## Understanding the Output

Hallmark returns two things after any redesign:

1. **Updated files** – Modified source code with new visual structure
2. **Explanation note** – Describes the new fingerprint, why it's better, and any confirmed deletions (lines 62‑69)

Example output explanation: *"Switched from Marquee Hero to Long Document; removed the previous fade‑in reveal; kept the brand teal palette."*

## Key Reference Files

Understanding these source files deepens your control over redesign outcomes:

| File | Purpose | Location |
|------|---------|----------|
| [`redesign.md`](https://github.com/Nutlope/hallmark/blob/main/redesign.md) | Complete verb specification with architectural rules and flowcharts | [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md) |
| [`structure.md`](https://github.com/Nutlope/hallmark/blob/main/structure.md) | Catalog of available macrostructure fingerprints | [`skills/hallmark/references/structure.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/structure.md) |
| [`design-md.md`](https://github.com/Nutlope/hallmark/blob/main/design-md.md) | Template for generated [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) system files | [`skills/hallmark/references/design-md.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/design-md.md) |
| [`README.md`](https://github.com/Nutlope/hallmark/blob/main/README.md) | High‑level verb overview | Repository root |

Real‑world output examples live in `site/_tests/` for inspection.

## Summary

- **`hallmark redesign`** rebuilds visual structure while protecting content and brand identity
- **Scope detection** automatically chooses single‑page or multi‑page pipeline based on target path
- **Single‑page flow** swaps macrostructure and voice for individual components; accepts `--mood` parameter
- **Multi‑page flow** creates [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) system file for consistent theming across entire directories
- **Non‑destructive rules** prevent data loss; deletions require explicit confirmation
- Reference [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md) for complete implementation details

## Frequently Asked Questions

### What is the difference between `hallmark redesign` and `hallmark polish`?

`hallmark redesign` replaces visual structure entirely—macrostructure, layout patterns, and component voice—while keeping copy and brand identity intact. `hallmark polish` (as described in the README) makes smaller refinements to existing structures without fundamental rearchitecture. Redesign is for when you need a fresh visual fingerprint; polish is for incremental improvements.

### Does `hallmark redesign` delete my existing files?

No. The command follows a **non‑destructive implementation rule** (lines 5‑13 in [`redesign.md`](https://github.com/Nutlope/hallmark/blob/main/redesign.md)). Route files, component directories, and production assets remain untouched unless you explicitly confirm deletion. Hallmark modifies structure and styling in‑place rather than removing and recreating files.

### What should I put in the `--mood` parameter?

The `--mood` flag accepts descriptive terms that guide tone selection for the redesigned output. Examples include `luxury`, `playful`, `minimal`, or `corporate`. The mood influences component voice and aesthetic choices without constraining the macrostructure possibilities drawn from [`structure.md`](https://github.com/Nutlope/hallmark/blob/main/structure.md). Mood is optional—omit it for neutral redesigns.

### Where does the multi‑page [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) file get created?

Hallmark places [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) at your **project root** when running multi‑page redesigns. This file becomes the single source of truth for themes, colour palettes, typography, spacing, motion, and CTA voice across all redesigned pages. Per‑page variations in macrostructure are still permitted while maintaining system‑wide consistency.