# How Hallmark Enforces the 8-State Component Checklist
> Learn how Hallmark enforces its 8-state component checklist using strict rule sets and preview wrapper verification, ensuring all interaction states are production ready.
- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: deep-dive
- Published: 2026-07-24
---
**Hallmark enforces a mandatory 8-state checklist through strict rule sets in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) and a preview wrapper verification pattern that requires developers to implement and visually verify all eight interaction states—default, hover, focus-visible, active, disabled, loading, error, and success—before any component enters production.**
Hallmark is an open-source skill repository (`Nutlope/hallmark`) designed to eliminate the visual shortcuts typical of AI-generated interfaces. The 8-state component checklist is not advisory but **mandatory**, ensuring every interactive element ships with complete accessibility coverage and production-ready robustness.
## Why the 8-State Checklist Is Mandatory
Most AI-generated UI implementations only cover default and hover states, leaving critical interaction gaps undefined. Hallmark’s philosophy treats this omission as a failure mode that produces broken layouts, accessibility violations, and inconsistent user experiences when components encounter real-world usage patterns.
According to the source code in [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), the rule is explicit: “Every interactive component **MUST** ship code for **all 8 states** … The 8‑state checklist … is **mandatory**, not advisory”【/cache/repos/github.com/Nutlope/hallmark/main/skills/hallmark/SKILL.md#L79-L80】. This strict requirement ensures that focus management, keyboard navigation, and state transitions are never left as implementation details.
## The Eight States Defined
The detailed specification in [`skills/hallmark/references/interaction-and-states.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/interaction-and-states.md) defines the eight required states and their accessibility contracts【/cache/repos/github.com/Nutlope/hallmark/main/skills/hallmark/references/interaction-and-states.md#L5-L16】:
- **Default** – The resting state of the component
- **Hover** – Mouse cursor interaction indication
- **Focus-Visible** – Keyboard navigation focus rings for accessibility
- **Active/Pressed** – Visual feedback during pointer activation
- **Disabled** – Inactive state with suppressed interactions
- **Loading** – Asynchronous operation in progress
- **Error** – Failed validation or operation state
- **Success** – Completed action confirmation
## The Preview Wrapper Verification Pattern
To streamline compliance verification, Hallmark introduces an **8-state demo wrapper** convention. Developers create a [`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) file that renders the component in all eight states stacked vertically with clear labels. This allows reviewers to verify compliance with a single glance before the wrapper is discarded【/cache/repos/github.com/Nutlope/hallmark/main/skills/hallmark/SKILL.md#L101-L104】.
```html
MyButton – 8‑State Demo
Default
Hover
Focus‑Visible
Active / Pressed
Disabled
Loading
Error
Success
```
The corresponding CSS implements state-specific styling to support the visual verification:
```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 */ }
```
## Enforcement Through Source Code Artifacts
Hallmark’s enforcement mechanism relies on two primary documentation artifacts:
- **[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)** – Contains the mandatory rule set declaring that every interactive component must implement all eight states, with explicit line references (79-80) codifying the requirement as a hard constraint rather than a suggestion.
- **[`skills/hallmark/references/interaction-and-states.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/interaction-and-states.md)** – Provides the detailed specification of each state, including expected visual treatments, ARIA attribute requirements, and accessibility contracts that must be satisfied (lines 5-16).
Real-world implementation examples, such as those found in the repository’s example components (e.g., [`site/examples/custom-03/script.js`](https://github.com/Nutlope/hallmark/blob/main/site/examples/custom-03/script.js)), demonstrate how these preview wrappers function in practice to validate state completeness.
## Benefits of Strict State Enforcement
By requiring the full set of states, Hallmark guarantees four critical quality attributes:
1. **Complete accessibility** – Focus-visible rings, proper ARIA attributes, and keyboard-only interactions are always present, never bolted on as afterthoughts.
2. **Layout stability** – No unexpected geometry shifts occur when components change state, as border-widths, padding, and dimensions remain constant across all eight variations.
3. **Consistent visual language** – Every component follows the same visual grammar, preventing the “almost-right” aesthetic that betrays AI-generated output.
4. **Robustness across devices** – Touch targets, loading spinners, and error handling behave correctly on both desktop and mobile contexts because they are explicitly defined rather than left undefined.
## Summary
- Hallmark enforces the **8-state component checklist** as a **mandatory** requirement, not an advisory guideline, to prevent AI-generated UI shortcuts.
- The eight states—**default, hover, focus-visible, active, disabled, loading, error, and success**—are defined in [`skills/hallmark/references/interaction-and-states.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/interaction-and-states.md).
- Compliance is verified through an **8-state preview wrapper** pattern ([`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 all states vertically for visual inspection.
- The mandatory rule is codified in **[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)** (lines 79-80) and ensures complete accessibility, layout stability, and cross-device robustness.
## Frequently Asked Questions
### What happens if a component doesn't implement all 8 states?
A component that lacks any of the required eight states fails the Hallmark skill validation. Because the requirement is mandatory according to [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md), incomplete components cannot pass review until the preview wrapper demonstrates all states rendering correctly with proper visual treatments and accessibility attributes.
### How does the preview wrapper work in practice?
Developers create a temporary [`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) file that imports their component and renders it eight times, once for each state, using CSS utility classes or props to simulate states like hover, focus, and loading. Reviewers verify compliance visually before the wrapper is discarded, ensuring the component meets Hallmark’s strict standards before merging.
### Why does Hallmark focus on preventing "AI-generated" looking UI?
AI-generated interfaces typically implement only default and hover states, leaving focus management, error handling, and disabled states undefined. This creates accessibility gaps and broken user experiences when real users encounter edge cases. Hallmark’s 8-state checklist eliminates these shortcuts, ensuring production-ready components that handle the full interaction spectrum gracefully.
### Are the 8 states applicable to non-interactive components?
The mandatory 8-state checklist applies specifically to **interactive components**—elements that users can click, tap, type into, or otherwise manipulate. Static display elements such as decorative images or plain text blocks are exempt, though Hallmark still recommends considering focus and error states for any element that might become interactive in future iterations.