Why the 8-State Component Checklist Is Mandatory in Hallmark
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, 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, which defines the expected visual treatment and accessibility contracts for the complete set【interaction-and-states.md#L5-L16】:
- Default – The resting state of the component
- Hover – Mouse/touch interaction preview
- Focus-Visible – Keyboard navigation indicator with proper focus rings
- Active/Pressed – The moment of interaction activation
- Disabled – Non-interactive state with appropriate visual dimming
- Loading – Async operation in progress with spinner or skeleton
- Error – Validation or system failure indication
- 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 or .preview.tsx—allows reviewers to verify compliance with a single glance before the wrapper is discarded【SKILL.md#L101-L104】.
HTML Preview Wrapper Example
<!-- MyButton.preview.html -->
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="UTF-8">
<title>MyButton – 8-State Demo</title>
<link rel="stylesheet" href="../styles.css">
</head>
<body>
<section>
<h2>Default</h2>
<button class="my-button">Press me</button>
</section>
<section>
<h2>Hover</h2>
<button class="my-button demo-hover">Press me</button>
</section>
<section>
<h2>Focus-Visible</h2>
<button class="my-button demo-focus">Press me</button>
</section>
<section>
<h2>Active / Pressed</h2>
<button class="my-button demo-active">Press me</button>
</section>
<section>
<h2>Disabled</h2>
<button class="my-button" disabled>Press me</button>
</section>
<section>
<h2>Loading</h2>
<button class="my-button demo-loading">Press me</button>
</section>
<section>
<h2>Error</h2>
<button class="my-button demo-error">Press me</button>
</section>
<section>
<h2>Success</h2>
<button class="my-button demo-success">Press me</button>
</section>
</body>
</html>
Corresponding CSS Implementation
.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. - 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, 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【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 or .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 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.
Have a question about this repo?
These articles cover the highlights, but your codebase questions are specific. Give your agent direct access to the source. Share this with your agent to get started:
curl -s "https://instagit.com/install.md" 
Maintain an open-source project? Get it listed too →