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

> Troubleshoot Hallmark output failing slop-test gates with this complete guide. Identify issues, apply targeted fixes, and pass all 57 gates for seamless validation.

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

---

**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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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:

```bash
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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/layout-and-space.md), you must use `clip` rather than `hidden` to preserve sticky positioning support:

```css
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`](https://github.com/Nutlope/hallmark/blob/main/site/css/base.css) or [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/tokens.css):

```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:

```css
.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:

```css
: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:

```css
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:

```css
/* 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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/slop-test.md)** – Complete 57-gate specification with failure definitions
- **[`skills/hallmark/references/layout-and-space.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/layout-and-space.md)** – Overflow, spacing tokens, and edge-clipping rules (gates 34-36)
- **[`site/css/base.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/base.css)** – Color and spacing token definitions required for Gate 48 compliance
- **[`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/site/css/base.css) or [`site/css/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/layout-and-space.md).