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

To report a bug in Hallmark, open a GitHub Issue using the repository's bug report template at /.github/ISSUE_TEMPLATE/bug_report.md and include a minimal reproduction, your Hallmark version, and details about your operating system and browser.

Hallmark is an open-source design system and static-site framework built on HTML, CSS custom properties, and a lightweight JavaScript runtime. When you encounter unexpected behavior—whether in the CSS variable system, component markup, or JavaScript interactions—following the project's structured reporting process ensures maintainers can diagnose and resolve issues efficiently.

Opening a GitHub Issue

All bugs must be filed through the repository's Issues tab. Hallmark provides a dedicated issue template stored at /.github/ISSUE_TEMPLATE/bug_report.md that guides you through the required information. This template ensures you provide the architectural context maintainers need to triage problems quickly.

The repository uses a GitHub Actions workflow that automatically applies the bug label to new issues created with this template. If you have triage permissions, you can also manually add the needs-triage label to flag issues requiring urgent review.

Providing a Minimal Reproduction

Because Hallmark is statically rendered, the most reliable way to demonstrate a bug is supplying a minimal HTML page or live demo link that exhibits the failure. Include the exact Hallmark version you are using—displayed in the site footer and recorded in package.json.

For CSS-related bugs, copy the relevant custom property definitions from site/css/variables.css or your imported theme file, along with the triggering markup. When reporting JavaScript behavior, identify the code path in site/js/main.js, such as the initFloatingNav function or IntersectionObserver logic for 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"
  }
}

Describing Expected vs. Actual Behavior

Clearly state what you expected Hallmark to do versus what actually occurred. For example: "the button should keep its full-width edge shadow" versus "the shadow collapses to a thin line."

Reference the style guide at skills/hallmark/references/interaction-and-states.md when describing visual expectations. This document defines the interaction patterns and accessibility requirements for components, helping maintainers verify regressions against the intended design system behavior.

Including Technical Context

Your bug report should contain specific environmental details that affect rendering:

• Operating system and browser version (Hallmark's CSS depends on modern layout engines)
• Build command used (npm run build or npm run dev)
• Any custom theme you are extending from skills/hallmark/references/themes/*

This context is crucial because Hallmark's architecture spans multiple layers—CSS custom properties, static HTML generation, and the JavaScript runtime in site/js/main.js.

Following Up and Contributing Fixes

After submitting, maintainers may request additional details or a pull request. If you plan to fix the bug yourself, follow the contribution workflow outlined in CONTRIBUTING.md:

1. Fork the repository
2. Create a branch named bugfix/<short-descriptive-name>
3. Run the test suite with npm test and ensure all existing tests pass
4. Add or update tests in site/_tests/ to capture the regression
5. Submit a Pull Request referencing the issue number

// Example snippet from site/js/main.js that may be relevant
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 bug report template at /.github/ISSUE_TEMPLATE/bug_report.md when opening GitHub Issues
• Provide a minimal HTML reproduction and specify your Hallmark version from package.json
• Reference skills/hallmark/references/interaction-and-states.md for expected behavior definitions
• Include OS, browser version, and build commands for environmental context
• Submit PRs using the bugfix/<name> branch format and extend tests in site/_tests/

Frequently Asked Questions

Where is the bug report template located in the Hallmark repository?

The bug report template is stored at /.github/ISSUE_TEMPLATE/bug_report.md in the Hallmark repository. This template structures your report to ensure you include minimal reproduction steps, version information, and technical context that the maintainers need to diagnose issues efficiently.

What information is required when reporting a bug in Hallmark?

You must provide your Hallmark version (found in package.json or the site footer), a minimal reproduction (HTML page or demo link), your operating system and browser version, the build command used (npm run build or npm run dev), and a clear description of expected versus actual behavior. Referencing the style guide at skills/hallmark/references/interaction-and-states.md helps clarify visual expectations.

How do I report a CSS-related bug in Hallmark?

For CSS bugs, include the relevant custom property definitions from site/css/variables.css or your theme file, along with the HTML markup that triggers the issue. Because Hallmark relies heavily on CSS custom properties for theming, providing these variable definitions allows maintainers to reproduce layout or styling failures accurately.

Can I submit a bug fix directly without creating an issue first?

While you can submit a pull request directly, Hallmark's workflow recommends filing an issue first using the bug report template. If you proceed directly to a PR, ensure you create a branch named bugfix/<short-descriptive-name>, run npm test to verify existing tests pass, and add regression tests in site/_tests/ before submitting.

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