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

> Learn how to report a bug in Hallmark using GitHub Issues. Follow our guide to create effective bug reports with a minimal reproduction, version, and system details for faster resolution.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: how-to-guide
- Published: 2026-07-28

---

**To report a bug in Hallmark, open a GitHub Issue using the repository's bug report template at [`/.github/ISSUE_TEMPLATE/bug_report.md`](https://github.com/Nutlope/hallmark/blob/main//.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`](https://github.com/Nutlope/hallmark/blob/main//.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`](https://github.com/Nutlope/hallmark/blob/main/package.json).

For CSS-related bugs, copy the relevant custom property definitions from [`site/css/variables.css`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js), such as the `initFloatingNav` function or IntersectionObserver logic for micro-interactions.

```html
<!-- 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>

```

```json
// 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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

```javascript
// 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`](https://github.com/Nutlope/hallmark/blob/main//.github/ISSUE_TEMPLATE/bug_report.md) when opening GitHub Issues
- Provide a minimal HTML reproduction and specify your Hallmark version from [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json)
- Reference [`skills/hallmark/references/interaction-and-states.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main//.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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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.