Understanding Hallmark’s 8-State Component Discipline for Robust State Management

Hallmark enforces a strict 8-state component discipline requiring every interactive UI element to implement Default, Hover, :focus-visible, Active, Disabled, Loading, Error, and Success states to ensure predictable behavior across all user interactions.

The 8-state component discipline is a core architectural constraint in the Hallmark repository that standardizes how interactive components handle user input and system conditions. According to the skills/hallmark/SKILL.md specification, this discipline is mandatory—not advisory—and every component must ship with implementations covering all eight states before being deemed production-ready.

The Eight Required States

Hallmark mandates that every interactive component provide visual and functional implementations for the following eight states:

1. Default – The normal, resting appearance of the element.
2. Hover – Visual feedback when the cursor is positioned over the element.
3. :focus-visible – Keyboard focus state that respects accessibility guidelines (a11y-friendly).
4. Active – Visual state while the element is being pressed or activated.
5. Disabled – Appearance when the element is unavailable for interaction.
6. Loading – Indicator shown during asynchronous operations.
7. Error – Feedback when an operation fails.
8. Success – Confirmation when an operation completes successfully.

This checklist is documented in skills/hallmark/references/interaction-and-states.md, and developers must verify compliance against these eight criteria before submitting components.

Implementation Requirements

The discipline is enforced through strict code review policies defined in skills/hallmark/SKILL.md.

Compliance is mandatory. The specification explicitly states that the 8-state checklist is not advisory—components missing any state implementation will fail review. This ensures consistent UI/UX across the entire site, full accessibility support via the :focus-visible requirement, and predictable error handling with dedicated Error and Success states.

The 8-State Demo Wrapper

To facilitate development and testing, Hallmark introduces an 8-state demo wrapper convention. Developers create a preview file (named <ComponentName>.preview.html or <ComponentName>.preview.tsx) that renders the component in all eight states stacked vertically with labels.

This wrapper serves as a built-in visual test case, allowing developers to verify state implementations at a glance. The demo page is strictly for development and must be removed before shipping the final build.

// MyButton.preview.tsx – 8‑state demo wrapper
import { MyButton } from "./MyButton";

export default function Preview() {
  return (
    <div style={{ display: "flex", flexDirection: "column", gap: "1rem" }}>
      <section>
        <h4>Default</h4>
        <MyButton>Submit</MyButton>
      </section>

      <section>
        <h4>Hover</h4>
        <MyButton className="hover">Submit</MyButton>
      </section>

      <section>
        <h4>:focus-visible</h4>
        <MyButton className="focus-visible">Submit</MyButton>
      </section>

      <section>
        <h4>Active</h4>
        <MyButton className="active">Submit</MyButton>
      </section>

      <section>
        <h4>Disabled</h4>
        <MyButton disabled>Submit</MyButton>
      </section>

      <section>
        <h4>Loading</h4>
        <MyButton loading>Submit</MyButton>
      </section>

      <section>
        <h4>Error</h4>
        <MyButton error>Submit</MyButton>
      </section>

      <section>
        <h4>Success</h4>
        <MyButton success>Submit</MyButton>
      </section>
    </div>
  );
}

Render the preview using npx serve . or by opening the HTML file to perform a quick visual sanity-check. Once verified, delete the preview file—only the component’s core code remains in production.

State Styling Utilities

The project provides CSS utilities in site/js/main.js and related stylesheets to handle state-related classes consistently:

/* Interaction utilities – used by the demo wrapper */
.hover:hover { opacity: 0.9; }
.focus-visible:focus-visible { outline: 2px solid var(--brand); }
.active:active { transform: translateY(1px); }
.loading { pointer-events: none; opacity: 0.6; }
.error { border-color: var(--error); }
.success { border-color: var(--success); }

Key Source Files

The 8-state component discipline is defined and enforced across these specific files in the Hallmark repository:

• skills/hallmark/SKILL.md – Primary specification document stating the mandatory nature of the 8-state discipline and demo wrapper requirements.
• skills/hallmark/references/interaction-and-states.md – Detailed reference checklist enumerating the eight required states with implementation guidelines.
• site/js/main.js – Core UI scripts that apply state-related classes (e.g., hover, focus-visible) to interactive elements.
• site/_tests/ – Directory containing visual test pages that frequently utilize the 8-state wrapper for validation.

Summary

• Hallmark requires 8 specific states for every interactive component: Default, Hover, :focus-visible, Active, Disabled, Loading, Error, and Success.
• Compliance is mandatory according to skills/hallmark/SKILL.md—the checklist is not optional.
• Preview files (.preview.tsx or .preview.html) render all eight states vertically for rapid visual testing during development.
• Accessibility is prioritized through the required :focus-visible state implementation.
• Demo wrappers are development-only artifacts that must be removed before production deployment.

Frequently Asked Questions

What are the 8 states required in Hallmark's component discipline?

The eight states are Default (normal appearance), Hover (cursor over), :focus-visible (keyboard focus), Active (being pressed), Disabled (unavailable), Loading (async operation), Error (operation failure), and Success (operation completion). Each state must be implemented in every interactive component according to skills/hallmark/references/interaction-and-states.md.

Is the 8-state discipline mandatory or optional?

The discipline is strictly mandatory. According to the Hallmark source code in skills/hallmark/SKILL.md, the 8-state checklist is explicitly marked as "not advisory," meaning components missing any state will fail production review requirements.

How do I test all 8 states during development?

Create an 8-state demo wrapper file named <ComponentName>.preview.tsx (or .html) that renders your component in all eight states stacked vertically with labels. Render this file locally to verify visual implementation, then delete it before shipping—the wrapper is strictly for development validation.

Where is the 8-state discipline documented in the codebase?

The primary specification lives in skills/hallmark/SKILL.md, while the detailed state checklist is maintained in skills/hallmark/references/interaction-and-states.md. Core implementation utilities reside in site/js/main.js, and example implementations can be found in the site/_tests/ directory.

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