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

> Learn how to report a bug in Hallmark effectively. Follow our guide to create a detailed GitHub Issue using the bug_report.md template for quick resolution.

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

---

**Report bugs in Hallmark by opening a GitHub Issue using the repository's [`bug_report.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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)](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`](https://github.com/Nutlope/hallmark/blob/main/package.json) or the site footer display. Example: `hallmark@1.4.2`.
- **Relevant CSS custom properties** — Copy definitions from [`site/css/variables.css`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js), such as `initFloatingNav()` for navigation issues or the `IntersectionObserver` logic for scroll-triggered 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"
  }
}

```

## 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js)** — Core runtime where interactive bugs originate; contains `initFloatingNav()` and observer patterns
- **[`site/css/variables.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/variables.css)** — Source of truth for design tokens affecting component rendering
- **[`skills/hallmark/references/interaction-and-states.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/interaction-and-states.md)** — Official specification for expected behaviors
- **`site/_tests/`** — Existing test patterns for regression coverage

```js
// 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`](https://github.com/Nutlope/hallmark/blob/main/bug_report.md) template at [`/.github/ISSUE_TEMPLATE/bug_report.md`](https://github.com/Nutlope/hallmark/blob/main//.github/ISSUE_TEMPLATE/bug_report.md)
- **Provide minimal HTML reproductions** with exact version numbers from [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json)
- **Reference specific files**: [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) for JS bugs, [`site/css/variables.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/variables.css) for styling issues
- **Cite 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) 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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js).

### Does Hallmark accept security vulnerability reports through public issues?

No. For security issues, check [`CONTRIBUTING.md`](https://github.com/Nutlope/hallmark/blob/main/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.