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

> Troubleshoot common Hallmark issues with this 10-step guide. Fix visual glitches, access failures, and slop-test errors by verifying macrostructure selection and token contracts.

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

---

**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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md) protocol and ensure missing assets fallback to placeholder SVGs as described in [`assets.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/site/css/components.css):

```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`](https://github.com/Nutlope/hallmark/blob/main/interaction-and-states.md).

### Preventing Layout Shift on Inputs

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

```css
.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`](https://github.com/Nutlope/hallmark/blob/main/interaction-and-states.md).

### Respecting the Accent-Ink Token Contract

Always pair accent backgrounds with accent-ink colors:

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

```

Reference: Token contract requirements are outlined in [`interaction-and-states.md`](https://github.com/Nutlope/hallmark/blob/main/interaction-and-states.md).

## Key Files for Debugging

Keep these reference paths accessible when troubleshooting:

- [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) – Defines core verbs, slop-test gates, and macrostructure handling
- [`skills/hallmark/references/interaction-and-states.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/interaction-and-states.md) – Exhaustive checklist for UI states and accessibility
- [`skills/hallmark/references/responsive.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/responsive.md) – Guidelines for typography and button wrapping issues
- `site/css/*` – Concrete CSS implementation where visual bugs manifest
- [`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.