Devlog #5: Cover Redesign & Grid System

Redesigning the devlog cover images with a unified grid system and tackling an elusive XML parsing error that had me stumped.

Published: May 27, 2025

When your devlog covers start looking like a design system from 2003, it’s time for a complete overhaul. Here’s how I built a unified grid system and solved a maddening XML parsing error.

The Problem: Visual Chaos

Looking at my existing devlog covers was like watching a design evolution in reverse. Each cover had its own unique layout, inconsistent styling, and worst of all - graphics that overlapped with titles. Some had modern gradients, others looked like they were designed for early 2000s web standards.

The breaking point came when I realized that my covers told no coherent visual story. A reader jumping between devlogs would experience jarring design shifts that undermined the professional image I wanted to project.

The Solution: Grid System Architecture

Instead of tweaking individual covers, I decided to build a proper design system from the ground up. The key insight was treating each cover like a dashboard with distinct content zones.

Four-Quadrant Layout

I established a consistent 4-quadrant system that allocates specific areas for different types of content:

• Top-Left (520×150): Primary feature showcase - the hero element
• Top-Right (300×150): Secondary supporting element
• Bottom-Left (300×150): Supporting detail or process step
• Bottom-Right (520×150): Detailed breakdown or technical specs

This asymmetrical layout creates visual hierarchy while ensuring I never run out of space for content. The larger quadrants (520px wide) handle complex diagrams, while the smaller ones (300px) work perfectly for focused elements.

Sacred Text Zones

The most important design decision was establishing “sacred zones” for text that would never be violated by graphics:

<!-- Before: Inconsistent layouts -->
<svg width="1200" height="630">
  <!-- Random positioning, overlapping elements -->
  <text x="600" y="500">Title overlaps with graphics</text>
</svg>

<!-- After: Grid system -->
<svg width="1200" height="630" viewBox="0 0 1200 630">
  <!-- Content quadrants: y=60 to y=400 -->
  <rect x="60" y="60" width="520" height="150" rx="12"/>
  <rect x="620" y="60" width="300" height="150" rx="12"/>
  
  <!-- Fixed text areas: y=420+ -->
  <text x="600" y="450">Title never overlaps</text>
</svg>

By constraining all content to the top 340px of the image (y=60 to y=400), I guarantee that titles, subtitles, and status indicators always have clean, unobstructed space.

The Maddening XML Mystery

Just as I was putting the finishing touches on my beautiful new covers, I hit a wall: xmlParseEntityRef: no name. The error was cryptic, the line numbers were confusing, and the covers that looked perfect in browsers were apparently malformed XML.

The Culprit: Unescaped Ampersands

The problem was embarrassingly simple: unescaped ampersands in my SVG text content. XML parsers expect all ampersands to be properly escaped as & unless they’re part of a valid entity reference.

<!-- Problem: Unescaped ampersands -->
<text>$ cd signals-and-systems && npm install</text>
<text>S&S</text>

<!-- Solution: Proper XML escaping -->
<text>$ cd signals-and-systems &amp;&amp; npm install</text>
<text>S&amp;S</text>

The errors were appearing in:

• Terminal commands: && needed to become &&
• Brand abbreviations: S&S needed to become S&S

What made this particularly frustrating was that browsers are forgiving - they rendered the “malformed” XML perfectly fine. But proper XML validation tools (and build processes) are more strict about following the specification.

Implementation: Template-Driven Design

To ensure consistency across all future covers, I created a documented template system with clear guidelines for each content zone.

Cover Template

The cover-template.svg file serves as both a reference and a starting point for new covers. It includes:

• Visible grid lines showing exact quadrant boundaries
• Dimension labels for each content zone
• Example status indicators and text positioning
• Gradient definitions that can be reused

Testing Infrastructure

I built a simple HTML test page (test-covers.html) that displays all covers side-by-side with their grid specifications. This makes it easy to spot inconsistencies and validate that the system works across different content types.

Results: Professional Cohesion

The transformation was dramatic. Instead of four disparate cover designs, I now have a cohesive visual system that:

• Scales consistently: Content fits predictably within defined zones
• Maintains hierarchy: Asymmetrical quadrants create natural reading flow
• Prevents conflicts: Graphics never interfere with text legibility
• Enables rapid iteration: New covers follow the established template

Each cover now tells its story through the grid system - Devlog 1 showcases terminal commands and project structure, Devlog 2 highlights interactive components and privacy flows, Devlog 3 demonstrates migration patterns and benefits.

Lessons Learned

Design Systems Pay Dividends

The upfront investment in creating a proper grid system and template pays off immediately. Instead of designing each cover from scratch, I can focus on content organization within proven constraints.

XML Validation Matters

Even when browsers are forgiving, proper XML validation prevents subtle bugs in build processes and ensures compatibility across different tools and platforms.

Build Testing Early

Creating a test page for visual validation made it easy to iterate on the design system and catch issues before they made it to production.

JELL

Innovator, Educator & Technologist

GitHub LinkedIn

JELL is an innovator, educator, and technologist exploring the confluence of AI, higher education, and ethical technology. Through Signals & Systems, JELL shares insights, experiments, and reflections on building meaningful digital experiences, and other random things.

More about JELL →