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

> Troubleshoot common Hallmark issues with this 10-step diagnostic guide. Systematically verify macrostructure selection, compliance, focus-ring, and border-width for seamless integration. Run hallmark audit to confirm slop-test ...

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

---

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

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

```

**Correct implementation:**

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

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

```css
.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`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md) protocol is followed
- 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 per [`imagery-kit.md`](https://github.com/Nutlope/hallmark/blob/main/imagery-kit.md).

## Run Diagnostic Commands

After applying fixes, verify resolution:

```bash

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