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

Follow Hallmark's ten-point architectural checklist to resolve visual glitches, accessibility failures, and slop-test gate errors by verifying macrostructure selection, eight-state compliance, focus-ring visibility, and token contracts.

Hallmark is an open-source design-skill by Nutlope that generates self-contained HTML and CSS pages governed by a strict aesthetic discipline. Unlike template-based generators, Hallmark relies on a hard-coded rule-set enforced by slop-test gates, meaning most visual bugs, layout shifts, and accessibility failures stem from specific violations of these architectural constraints defined in the source code.

Understanding the Hallmark Rule-Set Architecture

Hallmark's source code in skills/hallmark/SKILL.md defines a rigid framework where every component must satisfy state discipline, contrast requirements, and structural contracts. When you encounter unexpected behavior, resist the urge to apply quick CSS hacks; instead, consult the reference files in skills/hallmark/references/ to identify which specific rule your markup violates. Always re-run the hallmark audit <target> command after each fix to verify that all slop-test gates pass.

The 10-Point Hallmark Troubleshooting Checklist

Follow these diagnostic steps in order to isolate and resolve issues efficiently.

1. Verify Macrostructure Selection

Check the page’s macrostructure comment in the CSS (e.g., /* macro: hero-custom-04 */). The chosen macrostructure serves as the single source of truth for heading placement, image treatment, and button phrasing. A mismatch between the declared macrostructure in skills/hallmark/references/macrostructures.md and the actual markup causes layout inconsistencies and copy errors.

2. Enforce Eight-State Compliance

Inspect every interactive element—buttons, links, and form fields—for the eight required states: default, hover, focus, active, disabled, loading, error, and success. Missing CSS rules or aria- attributes for any state will trigger slop-test failures and produce broken UI behavior, as documented in skills/hallmark/references/interaction-and-states.md.

3. Audit Focus-Ring Visibility

Ensure every focusable element implements :focus-visible with a visible ring and never uses outline: none without a replacement. Verify that form fields include aria-invalid, aria-describedby, and aria-required attributes where applicable. Missing focus indicators are a primary cause of accessibility audit failures according to the interaction states specification.

4. Maintain Border-Width Invariance

Confirm that border-width remains constant (typically 1px) across all states. Search your CSS for rules that alter border thickness on :focus or :error. Changing border dimensions creates layout shift, which the slop-test identifies as a low-quality UI violation.

5. Stabilize Error and Helper Text

Check that error messages replace helper text within the same container rather than appearing simultaneously. Ensure the helper container uses min-height: 1lh to maintain stable height. Simultaneous display of error and helper text causes vertical jumps, violating the stable-height rule in interaction-and-states.md.

6. Enforce Contrast Discipline

Run a contrast audit using APCA standards (Lc ≥ 60 for body text, ≥ 45 for large text/icons) on every color pair. Pay special attention to surface flips where dark backgrounds are applied without inverting text color. Hallmark's slop-test gates 40-41 explicitly ban "text on a flipped surface" and "button text on accent fill" violations.

7. Validate Hit-Target Sizes

Verify that every touch-reachable element meets the 44 × 44 px minimum requirement. Use padding or an invisible ::before overlay to expand clickable areas without altering visual dimensions. Targets smaller than 44 px trigger usability complaints and fail Hallmark's interaction standards.

8. Check the Token Contract

Each theme must define --color-accent-ink. Any rule setting background: var(--color-accent) must simultaneously set color: var(--color-accent-ink). Search site/css/ for missing color declarations, as omitting accent-ink produces unreadable text on light accent backgrounds.

9. Fix Modal and Overlay Positioning

For <dialog> elements or custom overlays, ensure centering via position: fixed; inset: 0; margin: auto;. Avoid stray margin-top or transforms that push dialogs to corners. Mis-positioned modals break user flow and violate the "modals stuck in the corner" ban.

10. Confirm Custom-Theme Fallbacks

If using a custom theme, verify adherence to the custom-theme.md protocol and ensure missing assets fallback to placeholder SVGs as described in assets.md. Hallmark does not ship binaries; assets must degrade gracefully.

Code Examples for Common Fixes

Restoring Focus Rings on Buttons

When a button lacks visible focus, add the :focus-visible pseudo-class in site/css/components.css:

.btn {
  border: 1px solid var(--color-rule-2);
  background: var(--color-accent);
  color: var(--color-accent-ink);
}

.btn:focus-visible {
  outline: 2px solid var(--color-focus);
  outline-offset: 2px;
}

Reference: Focus-ring rules are documented in interaction-and-states.md.

Preventing Layout Shift on Inputs

Use a transparent outline slot to reserve space for focus states without changing border width:

.input {
  border: 1px solid var(--color-rule-2);
  outline: 2px solid transparent;
  outline-offset: 1px;
}

.input:focus-visible {
  outline-color: var(--color-focus);
}

Reference: The "no-layout-shift" rule lives in interaction-and-states.md.

Respecting the Accent-Ink Token Contract

Always pair accent backgrounds with accent-ink colors:

.hero {
  background: var(--color-accent);
  color: var(--color-accent-ink);
}

Reference: Token contract requirements are outlined in interaction-and-states.md.

Key Files for Debugging

Keep these reference paths accessible when troubleshooting:

• skills/hallmark/SKILL.md – Defines core verbs, slop-test gates, and macrostructure handling
• skills/hallmark/references/interaction-and-states.md – Exhaustive checklist for UI states and accessibility
• skills/hallmark/references/responsive.md – Guidelines for typography and button wrapping issues
• site/css/* – Concrete CSS implementation where visual bugs manifest
• docs/recipes.md – Worked examples for pattern verification

Summary

• Hallmark issues trace back to violations of its hard-coded rule-set rather than template errors
• Always verify the macrostructure comment matches your actual markup
• Implement all eight interaction states to pass slop-test gates
• Maintain border-width invariance and stable text heights to prevent layout shift
• Enforce the token contract by pairing --color-accent with --color-accent-ink
• Run hallmark audit <target> after editing files in site/css/ to confirm fixes

Frequently Asked Questions

What is the Hallmark slop-test?

The slop-test is an automated quality gate defined in skills/hallmark/SKILL.md that checks for common UI anti-patterns like missing focus rings, insufficient contrast, and layout shifts. It runs during hallmark audit and hallmark redesign commands to enforce the rule-set.

Why does Hallmark enforce constant border widths?

Changing border widths between states (e.g., adding a thicker border on focus) causes layout shift, where the element pushes surrounding content. Hallmark bans this to ensure stable, high-quality interfaces that don't trigger visual instability during user interaction.

How do I fix "text on flipped surface" errors?

This error occurs when you apply a dark background (surface flip) without inverting the text color to maintain contrast. Check your APCA contrast ratios (Lc ≥ 60 for body text) and ensure you swap to an appropriate ink color when changing surface backgrounds.

Where should I edit CSS to fix Hallmark issues?

Edit the concrete CSS implementation files located under site/css/ in your project directory. After modifying these files, re-run hallmark redesign <target> or hallmark audit <target> to verify the slop-test gates pass.

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