How Hallmark Identifies Microinteraction Libraries to Prevent Animation Slop

Hallmark identifies microinteraction libraries by scanning generated HTML and CSS against a curated list of forbidden signatures defined in skills/hallmark/references/microinteractions.md, aborting the build when disallowed patterns like transition-all or bouncy easing curves are detected.

The Nutlope/hallmark repository treats micro-interactions as a first-class design concern. To prevent generated pages from falling back to generic, AI-generated motion, the system uses static analysis to identify microinteraction libraries and their output signatures. This ensures only Hallmark-approved, theme-consistent animations survive to production.

The Detection Pipeline

Hallmark’s detection strategy relies on signature matching rather than package name inspection. The system compares rendered output against a meticulously maintained blacklist of animation anti-patterns.

The Reference File of Banned Signatures

At the core of the detection system lies skills/hallmark/references/microinteractions.md. This markdown file enumerates every micro-interaction pattern considered "slop"—the exact CSS class names, property values, and JavaScript-generated animation constructs that must not appear in final output.

The reference file contains specific signatures such as:

• transition: all declarations
• Universal hover lifts (hover: scale-105)
• Bouncy overshoot curves (cubic-bezier(0.34, 1.56, 0.64, 1))
• Autogenerated @keyframes blocks
• Custom cursor images

Regex-Based Static Analysis

When Hallmark finishes rendering a page, a slop-test script reads the reference file and compiles detection rules into regular expressions. The script executes these regexes against the page's HTML, inline styles, and linked CSS.

// Slop-test snippet (simplified)
import fs from 'fs';
const ref = fs.readFileSync(
  './skills/hallmark/references/microinteractions.md', 'utf8'
);

// Build regexes from the "named tells" table in the markdown
const banned = [
  /transition\s*:\s*all\b/,                         // 1. transition-all
  /hover:\s*scale-105/,                             // 2. universal hover lift
  /cubic-bezier\(\s*0\.34\s*,\s*1\.56\s*,\s*0\.64\s*,\s*1\s*\)/, // 3. bouncy overshoot
  /@keyframes\s+.+\{[^}]*\}/,                       // 4. custom keyframes
  /cursor\s*:\s*url\(.+\.png\)/,                    // 8. custom cursors
];

function hasBadMicroInteraction(html) {
  return banned.some(rx => rx.test(html));
}

// Called after the page is assembled
if (hasBadMicroInteraction(document.documentElement.outerHTML)) {
  console.error('Hallmark slop-test failed: disallowed micro-interaction detected');
  // abort build / return error to AI
}

If any pattern matches, the page fails the slop-test and Hallmark aborts the build.

Theme-Aware Enforcement

Hallmark respects a duration-scale table defined in the same markdown file. When a theme's scale is set to 0× (such as the Terminal or Newsprint themes), any detection of animation triggers a hard removal of the animation property. For themes with non-zero scales, detection results in regeneration of the primitive using Hallmark's own timing tokens (e.g., --ease-out).

This ensures that even when animations are permitted, they follow the design system's constraints rather than arbitrary library defaults.

Integration with the Build Process

The detection logic integrates directly into Hallmark's rendering pipeline to catch violations regardless of their source.

CI Pipeline Integration

The slop-test runner executes as part of the skill's CI pipeline, called from the main entry point in site/js/main.js. This script applies the theme, assembles the page, and triggers validation before the page reaches the client. Even if a developer manually injects a library such as Framer Motion or react-spring, the generated CSS and JavaScript signatures are caught and rejected.

Feedback Loop for AI Assistants

When the system identifies microinteraction libraries or their output signatures, it reports the exact violation back to the AI assistant. For example, the error might specify "transition-all detected in .card". The assistant then rewrites the component using Hallmark's micro-interaction recipes, which are documented in the same microinteractions.md file under the Recipes section.

Hallmark-Approved Animation Primitives

Instead of third-party libraries, Hallmark provides curated animation patterns using native CSS with design tokens:

<!-- CTA hover lift – Hallmark recipe -->
<button class="btn btn-primary"
        style="transition: transform 150ms var(--ease-out), background 150ms var(--ease-out);">
  Install
</button>

<style>
  .btn-primary:hover {
    transform: translateY(-1.5px);
    background: var(--color-ink);
    color: var(--color-paper);
  }
</style>

These primitives guarantee theme consistency while maintaining the performance benefits of native CSS transitions.

Summary

• Hallmark identifies microinteraction libraries by matching their output signatures against a curated blacklist in skills/hallmark/references/microinteractions.md.
• A slop-test runner compiles regex patterns from the reference file and validates generated HTML/CSS before deployment.
• Theme-aware enforcement applies different rules based on the duration-scale setting (0× themes trigger hard removal; others trigger regeneration).
• The detection logic executes from site/js/main.js after theme application but before client delivery.
• Violations abort the build and provide specific feedback to AI assistants, who then implement Hallmark-approved recipes instead.

Frequently Asked Questions

How does Hallmark catch microinteraction libraries if they are minified or obfuscated?

Hallmark detects the output signatures of these libraries rather than inspecting package names or source code. The slop-test scans the final rendered HTML and CSS for specific patterns like cubic-bezier(0.34, 1.56, 0.64, 1) or transition: all, which remain consistent even in minified bundles. This signature-based approach catches Framer Motion, react-spring, or any custom animation code that emits the forbidden CSS constructs.

What happens when Hallmark detects a forbidden microinteraction pattern?

When the slop-test identifies a banned signature, it immediately aborts the build and returns a specific error message indicating which pattern was found and where. For example, it might report "transition-all detected in .card". The AI assistant then receives this feedback and must rewrite the component using Hallmark's approved micro-interaction recipes before the build can succeed.

Can developers override the microinteraction detection in Hallmark?

No. The detection logic runs as a mandatory step in the CI pipeline after the theme is applied in site/js/main.js. There is no configuration flag to disable the slop-test, ensuring that all production pages maintain the design system's animation standards. The only way to pass the test is to remove the offending library output and replace it with Hallmark's native primitives.

Where does Hallmark store its approved animation patterns?

Hallmark documents both the banned signatures and the approved replacement recipes in skills/hallmark/references/microinteractions.md. This file contains the regex patterns for detection alongside CSS examples showing how to implement hover lifts, focus states, and other micro-interactions using Hallmark's design tokens like --ease-out and --color-ink.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}