The Release That Ate the Card System

Summary

This release started as a visual cleanup and ended as a full system alignment: cards, tokens, changelogs, governance—and a hard-earned reminder that WordPress will happily turn HTML comments into paragraphs when left unsupervised.

What shipped wasn’t just UI. It was a release discipline that can survive humans, platforms, and AI.

What Actually Changed

At the surface level:

• Legacy pink-card components were migrated to the canonical st-card (light variant).
• Radius rules were standardized across cards, tags, code blocks, and hero imagery.
• Gradients were locked to canonical Sugartown hex values.
• Tag styling and hover behavior were unified across cards and posts.

Under the hood:

• Card internals were restructured so headers pin to the top, footers pin to the bottom, and content flexes predictably.
• Media alignment was corrected (including a single rogue SVG that refused to behave).
• A subtle WordPress behavior—serializing comments into tags—was identified and neutralized before it could quietly break layouts again.

The Governance Pivot

Midway through the work, it became clear that the hard part wasn’t CSS—it was ensuring the system could explain itself later without folklore.

This release forced a separation between intent and reality:

• The PRD defines what the system is trying to become.
• The release documents what actually shipped.

That distinction is now explicit—and enforced.

How to Read a PRD vs a Release

The PRD describes intent.

• Aspirational and forward-looking
• Semantic-versioned to track evolving constraints and north-star architecture
• Defines canonical standards, not deployment facts

The Release describes reality.

• Factual and backward-looking
• Calendar-versioned ( vYYYY.MM.DD )
• Records only what shipped and is now true in production

If something exists only in the PRD, it is a goal. If it exists only in a release, it is a fact. When it appears in both, it becomes a standard.

What This Enabled

• A locked, calendar-based release versioning rule
• CHANGELOG.md as the single source of truth
• A formal Release Assistant with pass/fail lint rules
• Automatic rejection of malformed or speculative release entries

The system now documents how it changes, not just that it changed.

Artifacts Linked

• Release Governance Workflow: release-governance-yyyy-mm-dd-workflow
• Design System PRD: sugartown_design_system_PRD.md
• CHANGELOG.md: Imported automatically on publish
• st-card (light): Canonical card primitive moving forward

Why This Matters

This release closed the loop between:

• Design intent
• Code behavior
• Documentation
• Historical record

Future releases will be faster—not because less care is taken, but because the system now remembers how to care.