How to Troubleshoot Common Hallmark Issues: A 10-Step Diagnostic Guide

To troubleshoot common Hallmark issues, systematically verify your macrostructure selection, eight-state compliance, focus-ring implementation, border-width invariance, and token contracts, then re-run hallmark audit <target> to confirm slop-test gates pass.

Hallmark is a design skill that generates self-contained HTML + CSS pages with strict aesthetic and accessibility discipline. Because output is driven by hard-coded rules rather than loose templates, most problems trace to violations of these rules. This guide walks through the architectural checkpoints defined in the Nutlope/hallmark source code to diagnose visual glitches, accessibility failures, and slop-test gate errors.

Verify Macrostructure Selection

Every Hallmark page declares its macrostructure via a CSS comment (e.g., /* macro: hero-custom-04 */). This declaration determines heading placement, image treatment, and button phrasing.

• Check skills/hallmark/references/macrostructures.md for valid macrostructure options
• Mismatches between declared macrostructure and actual markup cause layout or copy inconsistencies

The macrostructure serves as the single source of truth for page shape. If your hero section renders incorrectly, confirm the macrostructure comment matches your intended layout pattern.

Inspect Eight-State Compliance

Hallmark enforces state discipline on every interactive element. Each button, link, and form field requires eight defined states:

1. default
2. hover
3. focus
4. active
5. disabled
6. loading
7. error
8. success

Missing CSS rules or aria- attributes trigger slop-test failures and broken UI behavior. Reference skills/hallmark/references/interaction-and-states.md for the complete state checklist.

Validate Focus Ring and Accessibility

Every focusable element must display a visible focus ring via :focus-visible. Never use outline: none without a replacement.

For form fields, verify these ARIA attributes:

• aria-invalid — indicates validation errors
• aria-describedby — links to error message containers
• aria-required — marks mandatory fields

Lack of focus rings or missing ARIA attributes constitute common accessibility audit failures according to the interaction-and-states specification.

Enforce Border-Width Invariance

Border width must remain constant (typically 1px) across all states. Search your CSS for rules that modify border-width on :focus or :error.

Anti-pattern to avoid:

/* Bad — causes layout shift */
.btn:focus {
  border: 2px solid var(--color-focus);
}

Correct implementation:

.input {
  border: 1px solid var(--color-rule-2);   /* constant 1px */
  outline: 2px solid transparent;          /* reserve slot for focus */
  outline-offset: 1px;
}

.input:focus-visible {
  outline-color: var(--color-focus);       /* no border-width change */
}

Changing border width creates layout shift, a tell-tale sign of low-quality UI that Hallmark's slop-test gates flag.

Stabilize Error vs. Helper Text

Error messages must replace helper text in the same container — never display simultaneously. Ensure the helper container has stable height via min-height: 1lh.

Simultaneous error + helper text causes vertical jumps. The stable-height rule prevents this motion as specified in interaction-and-states.md.

Audit Contrast Discipline

Run contrast audits on every color pair using these thresholds:

Element	Minimum APCA Lc
Body text	≥ 60
Large text/icons	≥ 45

Pay special attention to surface flips where dark backgrounds apply without text color inversion. Hallmark's slop-test gates 40-41 enforce contrast; failures appear as "text on a flipped surface" or "button text on accent fill."

Verify Hit-Target Size

Every touch-reachable element must meet the 44 × 44 px minimum. Expand clickable areas using:

• Padding increases
• Invisible ::before overlays

Targets smaller than 44px cause usability complaints and violate Hallmark requirements.

Confirm Token Contract Compliance

Each theme must define --color-accent-ink. Any rule setting background: var(--color-accent) must also set color: var(--color-accent-ink).

Required pattern:

.hero {
  background: var(--color-accent);
  color: var(--color-accent-ink);  /* Mandatory per token contract */
}

Search site/css/ for missing color declarations. Missing accent-ink produces unreadable text on light accent backgrounds, flagged by slop-test gates.

Check Modal and Overlay Positioning

For <dialog> elements or custom overlays, use centered positioning:

.modal {
  position: fixed;
  inset: 0;
  margin: auto;
}

Avoid stray margin-top or transforms that push dialogs to corners. Mis-positioned modals break user flow and trigger the "modals stuck in the corner" ban.

Validate Custom Theme Fallbacks

When using custom themes, confirm:

• custom-theme.md protocol is followed
• Missing assets fallback to placeholder SVGs as described in assets.md

Hallmark does not ship binaries; assets must degrade gracefully per imagery-kit.md.

Run Diagnostic Commands

After applying fixes, verify resolution:

# Regenerate affected pages

hallmark redesign <target>

# Run full audit

hallmark audit <target>

Both commands execute slop-test gates. Passing output confirms your troubleshooting resolved the underlying rule violations.

Summary

• Macrostructure comments determine page shape — verify they match your markup
• Eight states are mandatory for every interactive element
• Focus rings must be visible; never disable outline without replacement
• Border width stays constant; use outline for focus states
• Error and helper text share containers with stable min-height
• Contrast ratios meet APCA thresholds, especially on surface flips
• Touch targets measure at least 44 × 44 px
• Token contracts require accent-ink wherever accent backgrounds appear
• Modals center via inset: 0 with margin: auto
• Custom themes follow documented protocols with SVG fallbacks

Frequently Asked Questions

What is the Hallmark slop-test?

The slop-test is Hallmark's automated quality gate system that validates generated HTML and CSS against the project's rule-set. It checks for accessibility violations, layout instability, contrast failures, and state discipline errors. Run it via hallmark audit <target> to identify specific gate numbers that failed.

Where do I find the macrostructure options for my page?

Macrostructure definitions live in skills/hallmark/references/macrostructures.md. Each macrostructure (e.g., hero-custom-04) specifies heading placement, image treatment, and button phrasing. Match your page's intended layout to the correct macrostructure comment in your CSS.

Why does my focus ring disappear on some elements?

Missing focus rings typically result from outline: none without a :focus-visible replacement. Check site/css/components.css for the affected selector and add the outline pattern shown in this guide. Also verify the element is focusable (buttons, links, and form inputs by default; custom elements need tabindex).

How do I fix "accent-ink" slop-test failures?

Search your CSS for any rule setting background: var(--color-accent) without a corresponding color: var(--color-accent-ink). Add the missing color declaration to ensure text remains readable against accent backgrounds. The token contract is enforced in gates 40-41 of the slop-test.

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