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

> Explore Hallmark's 8-state component discipline for robust state management. Ensure predictable UI behavior with Default, Hover, Focus, Active, Disabled, Loading, Error, and Success states. Learn more!

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: deep-dive
- Published: 2026-07-20

---

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

```tsx
// 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`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) and related stylesheets to handle state-related classes consistently:

```css
/* 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/interaction-and-states.md)** – Detailed reference checklist enumerating the eight required states with implementation guidelines.
- **[`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)—the checklist is not optional.
- **Preview files** ([`.preview.tsx`](https://github.com/Nutlope/hallmark/blob/main/.preview.tsx) or [`.preview.html`](https://github.com/Nutlope/hallmark/blob/main/.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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)**, while the detailed state checklist is maintained in **[`skills/hallmark/references/interaction-and-states.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/interaction-and-states.md)**. Core implementation utilities reside in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js), and example implementations can be found in the `site/_tests/` directory.