# What Is the 8‑State Component Discipline in Hallmark?

> Explore Hallmark's 8-state component discipline. Learn how this strict UI requirement ensures consistent interaction states for default, hover, focus, active, disabled, loading, error, and success.

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

---

**Hallmark enforces a strict 8‑state component discipline that requires every interactive UI element to implement and visually demonstrate eight specific interaction states: default, hover, `:focus-visible`, active, disabled, loading, error, and success.**

The `Nutlope/hallmark` repository defines a rigorous UI component architecture where consistency and accessibility are enforced through code. At the center of this system lies the **8‑state component discipline**, a mandatory protocol documented in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) that dictates exactly how interactive components must behave across their entire lifecycle. Unlike optional guidelines, this rule requires contributors to ship production code handling every state variation, alongside preview files that demonstrate all eight states simultaneously.

## The Eight Required Interaction States

Every interactive component in Hallmark must account for the following eight discrete states, each requiring distinct visual treatment and behavioral logic:

1. **default** – The resting appearance when no user interaction is occurring.
2. **hover** – Visual feedback when a pointer device is positioned over the element.
3. **`:focus-visible`** – The keyboard focus indicator that appears when navigating via Tab key, distinct from mouse-initiated focus.
4. **active** – The pressed or activated state during user interaction (e.g., while a mouse button is held down).
5. **disabled** – The non-interactive state preventing all user input.
6. **loading** – Visual indication that an asynchronous operation is in progress.
7. **error** – Feedback state when an operation or validation fails.
8. **success** – Confirmation state when an operation completes successfully.

According to the [[`interaction-and-states.md`](https://github.com/Nutlope/hallmark/blob/main/interaction-and-states.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/interaction-and-states.md) reference file, each state requires specific CSS classes, ARIA attributes, and visual guidelines to ensure accessibility compliance.

## Mandatory Compliance and Preview Requirements

The 8‑state discipline is **mandatory**, not advisory. As stated in [[`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), "Every interactive component MUST ship code for **all 8 states**." To verify compliance, Hallmark requires a dedicated preview file for each component.

Contributors must create a preview wrapper—either `<ComponentName>.preview.html` or `<ComponentName>.preview.tsx`—that renders the component stacked in all eight states. Each state must be clearly labeled, enabling reviewers to verify full coverage in a single glance. These preview implementations are strictly for development and review purposes and are excluded from production builds.

## Implementation Example

Below is a TypeScript React example demonstrating how a `Button` component implements the required preview wrapper to display all eight states:

```typescript
// src/components/Button.preview.tsx
import { Button } from "./Button";

export default function ButtonPreview() {
  return (
    <div style={{ display: "grid", gap: "1rem" }}>
      {/* 1. default */}
      <Button>Default</Button>

      {/* 2. hover – simulated via class for preview */}
      <Button className="hover">Hover</Button>

      {/* 3. focus-visible */}
      <Button className="focus-visible">Focus‑Visible</Button>

      {/* 4. active */}
      <Button className="active">Active</Button>

      {/* 5. disabled */}
      <Button disabled>Disabled</Button>

      {/* 6. loading */}
      <Button loading>Loading</Button>

      {/* 7. error */}
      <Button status="error">Error</Button>

      {/* 8. success */}
      <Button status="success">Success</Button>
    </div>
  );
}

```

This stacked visualization allows designers and developers to audit the component's appearance across all required interaction modes without manually triggering each state individually.

## Source Files and References

The 8‑state component discipline is formally defined in two key locations within the repository:

- **[[`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)** – The high-level specification introducing the mandatory 8‑state rule.
- **[[`interaction-and-states.md`](https://github.com/Nutlope/hallmark/blob/main/interaction-and-states.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/interaction-and-states.md)** – The detailed reference checklist enumerating state requirements, naming conventions, and accessibility standards.

Additionally, component-specific preview files (e.g., [`Button.preview.tsx`](https://github.com/Nutlope/hallmark/blob/main/Button.preview.tsx)) serve as the practical implementation of this discipline, demonstrating how individual components satisfy the eight‑state requirement.

## Summary

- Hallmark requires **every interactive component** to implement eight specific states: default, hover, `:focus-visible`, active, disabled, loading, error, and success.
- Compliance is **mandatory** and enforced through code review according to [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md).
- Components must include a **preview file** ([`.preview.tsx`](https://github.com/Nutlope/hallmark/blob/main/.preview.tsx) or [`.preview.html`](https://github.com/Nutlope/hallmark/blob/main/.preview.html)) displaying all eight states in a stacked, labeled format.
- Preview files are development‑only artifacts and do not ship to production.
- The discipline is documented in [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) and detailed in [`interaction-and-states.md`](https://github.com/Nutlope/hallmark/blob/main/interaction-and-states.md).

## Frequently Asked Questions

### Is the 8‑state component discipline optional in Hallmark?

No. According to the [[`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) specification, every interactive component **must** ship code for all eight states. This is a strict requirement, not a suggestion or optional enhancement.

### What files are required to demonstrate the 8 states?

Each component requires a preview wrapper file named `<ComponentName>.preview.tsx` or `<ComponentName>.preview.html`. This file must render the component in all eight states simultaneously in a stacked layout with clear labels, allowing reviewers to verify state coverage visually.

### Do preview files ship to production?

No. The preview wrappers are development and review tools only. As specified in the Hallmark component guidelines, these demonstration files are excluded from production bundles and exist solely to validate the 8‑state implementation before merge.

### How does Hallmark ensure accessibility across these states?

The [[`interaction-and-states.md`](https://github.com/Nutlope/hallmark/blob/main/interaction-and-states.md)](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/interaction-and-states.md) reference file defines specific ARIA attributes, keyboard navigation patterns, and focus management requirements for each state. The `:focus-visible` state specifically ensures keyboard users receive visible focus indicators distinct from mouse interactions, meeting WCAG accessibility standards.