How to Troubleshoot Hallmark Output Failing Slop-Test Gates: A Complete Guide to the 57-Gate Validation

Run hallmarkslop locally to identify specific failing gate numbers, then apply targeted CSS fixes using design tokens and layout rules defined in skills/hallmark/references/slop-test.md until all 57 gates pass.

Hallmark, the open-source page generator from Nutlope/hallmark, validates every output against a rigorous 57-gate slop-test to eliminate AI-generated layout slop and visual inconsistencies. When your output fails these validation gates, the page is rejected until you resolve the underlying issues according to the source specifications. Understanding how to interpret gate failures and apply the correct fixes ensures your generated pages meet production quality standards.

Understanding the 57-Gate Validation

The slop-test is a comprehensive validation suite defined in skills/hallmark/references/slop-test.md that checks generated HTML/CSS for specific anti-patterns. Gates are ordered logically from layout-safety (gates 34-36) through visual structure (38-39), contrast (40-41), navigation patterns (42-45), and mobile-responsiveness (50-57). Fixing failures in this sequence matters because later gates often depend on corrections made to earlier ones.

Running the Slop Test Locally

While Hallmark executes the slop-test automatically during generation, you can run it manually to isolate specific failures:

hallmark <brief-json> | hallmarkslop

The CLI outputs the specific gate numbers that failed (for example, 34, 49, 57), which serve as your diagnostic checklist for troubleshooting.

Critical Gate Failures and Fixes

Gate 34: Eliminate Horizontal Scroll

Gate 34 triggers when content causes horizontal scrolling on any viewport between 320px and 1920px. According to skills/hallmark/references/layout-and-space.md, you must use clip rather than hidden to preserve sticky positioning support:

html, body {
  overflow-x: clip;  /* NOT hidden */
}

Gate 48: Enforce Token Discipline

This gate fails when you use hardcoded hex codes or RGB values instead of CSS custom properties. All colors must reference tokens defined in site/css/base.css or site/css/tokens.css:

/* Fails Gate 48 */
.button { background: #ff7a00; }

/* Passes Gate 48 */
.button { background: var(--color-accent); }

Gate 49: Prevent Two-Line Clickable Text

Navigation links and buttons must never wrap to two lines at any viewport width. Apply white-space: nowrap to ensure compliance:

.nav-link,
.cta-button {
  white-space: nowrap;
}

If text is too long, abbreviate labels or move excess items into an overflow menu using hidden=until-found.

Gate 57: Resolve Sticky Element Conflicts

When multiple elements use position: sticky, they cannot share the same top: 0 value. Define a banner height token and stagger the positions:

:root { --banner-height: 56px; }

nav { 
  position: sticky; 
  top: 0; 
  z-index: 300; 
}

.toc { 
  position: sticky; 
  top: var(--banner-height); 
  z-index: 200; 
}

Gates 40-41: Maintain Contrast Thresholds

These gates enforce WCAG/APCA contrast requirements for text, icons, and focus rings. Focus-visible styles must not change layout dimensions:

button:focus-visible,
a:focus-visible {
  outline: 2px solid var(--color-focus);
  outline-offset: 1px;
}

Avoid border-width changes that trigger reflow, as this violates the Input-state gate specifications.

Required CSS Stamp Format

Hallmark requires a metadata stamp at the top of generated CSS files to track compliance status:

/* Hallmark · macrostructure: hero-enriched · contrast: pass (40–41) · nav: N3 · footer: Ft4 · slop: pass (42–45) */

Essential Reference Files

• skills/hallmark/references/slop-test.md – Complete 57-gate specification with failure definitions
• skills/hallmark/references/layout-and-space.md – Overflow, spacing tokens, and edge-clipping rules (gates 34-36)
• site/css/base.css – Color and spacing token definitions required for Gate 48 compliance
• site/css/tokens.css – Global design token variables
• site/_tests/ – Example implementations that pass all gates

Summary

• Execute hallmarkslop locally to identify specific failing gate numbers before attempting fixes
• Address layout-safety gates (34-36) before tackling mobile-responsiveness issues (50-57)
• Replace all hardcoded color values with var(--color-...) and spacing with var(--space-...) tokens
• Use overflow-x: clip on html and body to fix Gate 34 without breaking sticky positioning
• Include the mandatory CSS compliance stamp documenting macrostructure, contrast, and navigation patterns

Frequently Asked Questions

What is the Hallmark slop-test?

The slop-test is a 57-gate validation suite in the Nutlope/hallmark repository that checks generated HTML/CSS for AI-specific anti-patterns including horizontal overflow, missing focus states, hardcoded values, and repetitive macrostructures. Every generated page must pass all gates before being accepted as valid output.

How do I run the Hallmark slop-test locally?

Pipe your Hallmark JSON output to the hallmarkslop CLI tool using the command hallmark <brief-json> | hallmarkslop. This outputs the specific gate numbers that failed, allowing you to consult skills/hallmark/references/slop-test.md for targeted remediation steps.

Why does my output fail Gate 48 (Token Discipline)?

Gate 48 fails when CSS uses hardcoded hex codes, RGB values, or other literal color definitions instead of referencing the design system tokens. All colors must use variables like var(--color-accent) defined in site/css/base.css or site/css/tokens.css to ensure consistency across generated pages.

How do I fix Gate 34 horizontal scroll violations?

Add overflow-x: clip (not hidden) to both html and body elements in your global stylesheet. This prevents horizontal overflow while preserving support for sticky positioning, as required by the layout specifications in skills/hallmark/references/layout-and-space.md.

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