How to Report a Bug in Hallmark: A Complete Guide to Filling GitHub Issues

Report bugs in Hallmark by opening a GitHub Issue using the repository's bug_report.md template and providing a minimal HTML reproduction, version details, and clear expected vs. actual behavior.

Hallmark is an open-source design system and static-site framework built on HTML, CSS custom properties, and a lightweight JavaScript runtime. Knowing how to report a bug in Hallmark correctly helps maintainers triage and fix issues faster—whether the problem stems from the CSS variable system, component markup, or interaction layer in site/js/main.js.

Where to File Bug Reports

All bugs must be submitted through the GitHub Issues tab in the Nutlope/hallmark repository. The project uses a structured issue template located at [/.github/ISSUE_TEMPLATE/bug_report.md](https://github.com/Nutlope/hallmark/blob/main/.github/ISSUE_TEMPLATE/bug_report.md) to ensure reports contain consistent, actionable information.

When you click "New Issue" and select the bug report option, the template auto-populates with required sections. Fill each section completely—partial reports often stall in triage.

Provide a Minimal Reproduction

Hallmark's static architecture means bugs are most reliably reproduced with a minimal HTML page or live demo link. This approach eliminates variables from build pipelines and custom themes.

Your reproduction should include:

• Exact Hallmark version — Check your package.json or the site footer display. Example: hallmark@1.4.2.
• Relevant CSS custom properties — Copy definitions from site/css/variables.css or your imported theme file if the bug involves styling.
• Suspected JavaScript code path — Reference functions in site/js/main.js, such as initFloatingNav() for navigation issues or the IntersectionObserver logic for scroll-triggered micro-interactions.

<!-- Minimal reproduction of a button-shadow bug -->
<link rel="stylesheet" href="https://cdn.jsdelivr.net/npm/hallmark@1.4.2/dist/hallmark.css">
<button class="btn-primary">Click me</button>

<script src="https://cdn.jsdelivr.net/npm/hallmark@1.4.2/dist/hallmark.js"></script>
<script>
  // No additional JS required – the bug appears on load
</script>

// package.json excerpt showing the Hallmark version
{
  "name": "my-hallmark-site",
  "dependencies": {
    "hallmark": "^1.4.2"
  }
}

Describe Expected vs. Actual Behavior

Clearly separate what you expected from what actually happened. For example: "The button should maintain its full-width edge shadow per the interaction guidelines, but the shadow collapses to a thin line on hover."

Reference specific sections of the style guide at skills/hallmark/references/interaction-and-states.md when describing expected behavior. This document defines visual and accessibility standards for components, giving maintainers a concrete reference to verify regressions.

Include Contextual Environment Details

Hallmark's CSS relies heavily on modern layout engines, so environment specifics matter:

Detail	Why It's Needed
Operating system	Rendering differences between macOS, Windows, and Linux
Browser version	CSS custom properties and IntersectionObserver vary by engine
Build command	npm run build vs. npm run dev produces different asset pipelines
Custom theme	Extensions in skills/hallmark/references/themes/* may override defaults

Label and Submit Your Issue

After submission, a GitHub Actions workflow automatically applies the bug label. If you have repository permissions, manually add needs-triage to signal urgency. Avoid editing the auto-generated label section—this can disrupt the automation.

Follow Up and Contribute Fixes

Maintainers may request additional details or invite you to submit a PR. To fix the bug yourself:

1. Fork the repository
2. Create a branch: git checkout -b bugfix/short-descriptive-name
3. Run the test suite: npm test
4. Add or update tests in site/_tests/ to capture the regression
5. Submit a Pull Request referencing the issue number: Fixes #123

Key Files for Debugging

Understanding these source files accelerates both reporting and fixing:

• site/js/main.js — Core runtime where interactive bugs originate; contains initFloatingNav() and observer patterns
• site/css/variables.css — Source of truth for design tokens affecting component rendering
• skills/hallmark/references/interaction-and-states.md — Official specification for expected behaviors
• site/_tests/ — Existing test patterns for regression coverage

// Example: Relevant snippet from site/js/main.js for navigation bugs
function initFloatingNav() {
  const nav = document.querySelector('.floating-nav')
  if (!nav) return
  // Hallmark uses IntersectionObserver for sticky behaviour
  const observer = new IntersectionObserver(([e]) => {
    nav.classList.toggle('is-stuck', !e.isIntersecting)
  })
  observer.observe(nav)
}

Summary

• Use the GitHub Issues tab with the bug_report.md template at /.github/ISSUE_TEMPLATE/bug_report.md
• Provide minimal HTML reproductions with exact version numbers from package.json
• Reference specific files: site/js/main.js for JS bugs, site/css/variables.css for styling issues
• Cite the style guide at skills/hallmark/references/interaction-and-states.md for expected behavior
• Include environment details: OS, browser, build command, and any custom themes
• Run npm test before submitting PRs; add tests in site/_tests/ to prevent regressions

Frequently Asked Questions

What should I do if I can't reproduce the bug consistently?

Document the conditions where it does occur—specific pages, viewport sizes, or interaction sequences. Include your package.json dependencies and any browser console errors. The maintainers can often infer race conditions or observer timing issues from partial patterns, especially if you reference the IntersectionObserver logic in site/js/main.js.

Does Hallmark accept security vulnerability reports through public issues?

No. For security issues, check CONTRIBUTING.md or the repository's security policy for private disclosure channels. Public issues expose vulnerabilities before patches are available.

How do I report a bug in a custom theme I've built?

File the issue against your own theme repository first. If the bug stems from Hallmark's core variables or JS runtime, reproduce it with the base theme before submitting to Nutlope/hallmark. Include both your theme's override file and the minimal reproduction without it.

What happens after I submit a bug report?

An automated workflow adds the bug label. Maintainers typically respond within a few days requesting clarification or assigning priority. High-impact bugs affecting core components like navigation or accessibility receive needs-triage labels and faster turnaround.

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