# Why the 8-State Component Checklist Is Mandatory in Hallmark
> Discover why Hallmark requires the 8-state component checklist to prevent incomplete AI-generated interfaces. Ensure full interaction states for superior UI/UX.
- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: best-practices
- Published: 2026-07-13
---
**Hallmark enforces the 8-state checklist as a mandatory requirement—not an advisory suggestion—to eliminate the incomplete, "AI-generated" look common in interfaces that only implement default and hover states.**
The **8-state component checklist** is a strict, non-negotiable requirement in the Nutlope/hallmark repository. Unlike typical design systems that treat comprehensive state coverage as optional, Hallmark mandates that every interactive component must ship code for all eight distinct states to ensure production-ready accessibility and visual consistency.
## The Philosophy Behind Mandatory State Coverage
Most AI-generated interfaces implement only the **default** and **hover** states, leaving the rest of the interaction spectrum undefined. This shortcut creates accessibility gaps, inconsistent user experiences, and broken layouts when components encounter real-world usage patterns like keyboard focus, disabled states, or loading indicators.
### Codified in SKILL.md
According to the Hallmark source code, the requirement is absolute. In [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), the rule-set explicitly declares: *"Every interactive component **MUST** ship code for **all 8 states** … The 8-state checklist … is **mandatory**, not advisory"*【SKILL.md#L79-L80】. This contractual language removes any ambiguity—partial implementations are not accepted.
## The Eight States Defined
The detailed specification for each state lives in [`skills/hallmark/references/interaction-and-states.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/interaction-and-states.md), which defines the expected visual treatment and accessibility contracts for the complete set【interaction-and-states.md#L5-L16】:
1. **Default** – The resting state of the component
2. **Hover** – Mouse/touch interaction preview
3. **Focus-Visible** – Keyboard navigation indicator with proper focus rings
4. **Active/Pressed** – The moment of interaction activation
5. **Disabled** – Non-interactive state with appropriate visual dimming
6. **Loading** – Async operation in progress with spinner or skeleton
7. **Error** – Validation or system failure indication
8. **Success** – Completion confirmation and positive feedback
## Why Mandatory Coverage Matters
Requiring the full set of states guarantees four critical quality attributes:
- **Complete accessibility** – Focus-visible rings, proper ARIA attributes, and keyboard-only interactions are always present, not post-hoc additions.
- **Layout stability** – Geometric consistency is maintained across states; border widths and padding remain constant, preventing unexpected shifts.
- **Consistent visual language** – Every component follows the same visual grammar, eliminating the "almost-right" look that betrays AI-generated output.
- **Robustness across devices** – Touch targets, loading spinners, and error handling behave correctly on both desktop and mobile contexts.
## The 8-State Demo Wrapper Workflow
To streamline verification, Hallmark introduces an **8-state demo wrapper** that renders the component in all eight states stacked vertically and labeled. This wrapper—typically named [`ComponentName.preview.html`](https://github.com/Nutlope/hallmark/blob/main/ComponentName.preview.html) or [`.preview.tsx`](https://github.com/Nutlope/hallmark/blob/main/.preview.tsx)—allows reviewers to verify compliance with a single glance before the wrapper is discarded【SKILL.md#L101-L104】.
### HTML Preview Wrapper Example
```html
MyButton – 8-State Demo
Default
Hover
Focus-Visible
Active / Pressed
Disabled
Loading
Error
Success
```
### Corresponding CSS Implementation
```css
.my-button { /* Default */ }
.my-button.demo-hover:hover { /* Hover styling */ }
.my-button.demo-focus:focus-visible { /* Focus-visible styling */ }
.my-button.demo-active:active { /* Active styling */ }
.my-button[disabled] { /* Disabled styling */ }
.my-button.demo-loading { /* Loading spinner */ }
.my-button.demo-error { /* Error border & icon */ }
.my-button.demo-success { /* Success checkmark */ }
```
Running the preview wrapper lets designers and developers confirm that all eight states render according to the specification before the component merges into production.
## Summary
- The **8-state component checklist** is mandatory in Hallmark to prevent the incomplete aesthetic typical of AI-generated interfaces.
- All eight states—Default, Hover, Focus-Visible, Active, Disabled, Loading, Error, and Success—must be implemented according to [`skills/hallmark/references/interaction-and-states.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/interaction-and-states.md).
- Mandatory compliance ensures complete accessibility, layout stability, consistent visual language, and cross-device robustness.
- The **8-state demo wrapper** pattern provides a rapid verification mechanism before code review.
## Frequently Asked Questions
### What happens if a component doesn't implement all 8 states in Hallmark?
The component will fail compliance review. According to [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), the requirement uses mandatory language ("MUST"), meaning submissions lacking any of the eight states are rejected until complete coverage is implemented.
### Which file contains the detailed specification for each state?
The detailed definitions, visual treatments, and accessibility contracts for the eight states are documented in [`skills/hallmark/references/interaction-and-states.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/interaction-and-states.md)【interaction-and-states.md#L5-L16】. This file serves as the canonical reference for state behavior.
### How do I verify that my component meets the 8-state requirement?
Create an **8-state demo wrapper** (e.g., [`ComponentName.preview.html`](https://github.com/Nutlope/hallmark/blob/main/ComponentName.preview.html) or [`.preview.tsx`](https://github.com/Nutlope/hallmark/blob/main/.preview.tsx)) that renders your component in all eight states stacked vertically. This allows reviewers to verify compliance visually before the wrapper is removed from the final build【SKILL.md#L101-L104】.
### Are there exceptions to the 8-state rule for simple components?
No. The rule-set in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) applies to **every interactive component** without exception. Even simple buttons must handle all states including Loading, Error, and Success to maintain the system's accessibility and quality standards.