The 8-State Checklist for Hallmark UI Components: A Complete Implementation Guide

Hallmark enforces an eight-state checklist for every interactive element to guarantee consistent visual language, accessibility, and deterministic behavior across all components.

The Hallmark design system requires developers to account for every possible user interaction state. This systematic approach, defined in skills/hallmark/references/interaction-and-states.md and implemented in site/css/components.css, eliminates ambiguity in component behavior and ensures WCAG-compliant experiences.

What Is the Hallmark 8-State Checklist?

The checklist mandates that every interactive element must explicitly handle eight distinct states. Each state requires specific visual treatment, accessibility attributes, and behavioral guarantees.

| # | State | Trigger | Core Implementation |

|---|-------|---------|---------------------| | 1 | Default | Element at rest | Base styling with border: 1px solid var(--color-rule-2) | | 2 | Hover | Pointer over element | background: var(--color-paper-2); transform: translateY(-1px) | | 3 | Focus | Keyboard/programmatic focus | :focus-visible with outline: 2px solid var(--color-focus) | | 4 | Active/Pressed | Mouse-down or key-press | transform: translateY(1px) with darker background | | 5 | Disabled | Non-interactive element | opacity: 0.55; cursor: not-allowed; aria-disabled="true" | | 6 | Loading | Background operation in progress | Inline spinner with preserved label readability | | 7 | Error | Validation or request failure | border-color: var(--color-error) with aria-invalid="true" | | 8 | Success | Operation completed | border-color: var(--color-success) with check indicator |

Default State: The Foundation

The Default state establishes the baseline visual identity. In site/css/components.css, the .btn class defines this foundation:

.btn {
  display: inline-flex;
  align-items: center;
  gap: var(--space-sm);
  padding: var(--space-sm) var(--space-lg);
  font-family: var(--font-label);
  font-size: var(--text-sm);
  font-weight: 500;
  color: var(--color-ink);
  background: transparent;
  border: var(--rule-fine) solid var(--color-ink);
  border-radius: var(--radius-pill, 0);
  min-height: 44px;
  transition:
    transform 100ms var(--ease-out),
    background-color var(--dur-micro) var(--ease-out),
    color var(--dur-micro) var(--ease-out),
    border-color var(--dur-micro) var(--ease-out);
}

The min-height: 44px ensures touch-target compliance. Border width remains constant across all states to prevent layout shift.

Hover State: Pointer-Aware Enhancement

The Hover state applies only on devices that support hover. Hallmark uses a defensive media query pattern in site/css/components.css at line 9:

@media (hover: hover) and (pointer: fine) {
  .btn:hover {
    background: var(--color-ink);
    color: var(--color-paper);
    transform: translateY(-1px);
  }
}

This prevents sticky hover states on touch devices. The translateY(-1px) creates subtle lift without affecting document flow.

Focus State: Keyboard Accessibility

The Focus state uses :focus-visible to show rings only for keyboard navigation, per the guidelines in interaction-and-states.md at line 21:

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

The outline-offset creates breathing room between the element and its focus indicator. This satisfies WCAG 2.2 focus appearance requirements.

Active/Pressed State: Immediate Feedback

The Active state provides instant feedback during interaction:

.btn:active {
  transform: translateY(1px);
}

The downward translation visually simulates physical depression. This state is typically brief but critical for perceived responsiveness.

Disabled State: Clear Non-Interactivity

The Disabled state appears in site/css/components.css at line 13 with multiple redundant indicators:

.btn[disabled],
.btn[aria-disabled="true"] {
  opacity: 0.55;
  cursor: not-allowed;
}

Dual attribute targeting ([disabled] and [aria-disabled]) handles both native form controls and custom elements. The reduced opacity provides sufficient contrast while signaling inactivity.

Loading State: Progress Without Blocking

The Loading state maintains element structure while indicating background operation:

.btn[data-state="loading"] {
  background: var(--color-paper-2);
  color: var(--color-muted);
}

.btn[data-state="loading"]::after {
  content: "";
  display: inline-block;
  width: 1rem;
  height: 1rem;
  border: 2px solid var(--color-muted);
  border-top-color: transparent;
  border-radius: 50%;
  animation: spin 0.6s linear infinite;
}

The spinner uses a CSS pseudo-element to avoid DOM manipulation. The element remains focusable and screen-reader accessible via aria-live announcements.

Error State: Validation Failure

The Error state, documented in interaction-and-states.md at line 15, requires multiple perceivable signals:

.btn[data-state="error"] {
  border-color: var(--color-error);
  color: var(--color-error);
}

Color change alone is insufficient—production implementations add icons and aria-invalid="true" for screen reader users.

Success State: Completion Confirmation

The Success state provides positive feedback with automatic dismissal:

.btn[data-state="success"] {
  border-color: var(--color-success);
  color: var(--color-success);
}

The auto-dismiss pattern (typically 1500ms) prevents persistent success states from confusing subsequent interactions.

Core Principles Behind the Checklist

Hallmark's 8-state checklist enforces four mandatory principles:

• No layout shift — Border widths and dimensions remain constant across all states
• Dual signaling — Every state combines color with at least one additional indicator (icon, outline, motion, or text)
• Reduced-motion respect — Transitions collapse to opacity fades ≤150ms when prefers-reduced-motion: reduce is active
• ARIA synchronization — State changes propagate to aria-disabled, aria-invalid, and aria-live attributes

Complete Implementation Example

This HTML/CSS/JavaScript trio demonstrates full 8-state lifecycle management:

<button
  class="btn"
  id="demo-btn"
  aria-live="polite"
  data-state="default">
  Submit
</button>

const btn = document.getElementById('demo-btn');

function setState(state) {
  btn.dataset.state = state;
  btn.disabled = state === 'disabled' || state === 'loading';
  btn.setAttribute('aria-disabled', state === 'disabled');
  btn.setAttribute('aria-invalid', state === 'error');
}

btn.addEventListener('click', () => {
  setState('loading');
  setTimeout(() => {
    Math.random() > 0.5 ? setState('success') : setState('error');
    setTimeout(() => setState('default'), 1500);
  }, 1200);
});

The setState function centralizes state synchronization across HTML attributes, ARIA properties, and disabled state.

Where the Checklist Is Defined

File	Purpose
skills/hallmark/references/interaction-and-states.md	Canonical definition of the eight-state model and accessibility rules
site/css/components.css	Production CSS implementing all states for buttons, inputs, and components
site/js/main.js	Runtime state transition handling and data-state attribute management
site/_tests/	Visual regression tests verifying state appearance across themes

Summary

• Hallmark's 8-state checklist mandates explicit handling of Default, Hover, Focus, Active, Disabled, Loading, Error, and Success states
• The checklist originates in interaction-and-states.md and is implemented in site/css/components.css
• No layout shift and dual signaling are non-negotiable requirements
• All states must respect prefers-reduced-motion and maintain ARIA attribute synchronization
• The data-state attribute pattern enables clean JavaScript state management

Frequently Asked Questions

What happens if a component doesn't implement all eight states?

Incomplete implementation violates Hallmark's design system contract. Missing states create accessibility gaps (undefined focus behavior) and inconsistent user experiences (unexpected disabled styling). The test suite in site/_tests/ catches missing states during CI.

Why does Hallmark use :focus-visible instead of :focus?

:focus-visible (line 21 of interaction-and-states.md) shows focus rings only for keyboard navigation, eliminating the "focus halo" on mouse clicks that users find visually distracting. This follows the CSS :focus-visible specification and modern browser defaults.

How does the loading state maintain accessibility?

The loading state preserves the element's focusability and uses aria-live="polite" on the container to announce state changes. The spinner is decorative (no alt text), while the button label remains readable. Screen readers announce "Submit, loading" via the living region pattern.

Can states be combined, like loading + disabled?

No—Hallmark enforces mutually exclusive states via the single data-state attribute. This prevents contradictory visual signals (a disabled-looking loading button). Sequential states are preferred: loading transitions to success or error, then auto-dismisses to default.

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