# How Hallmark Integrates with Other Services: A Complete Technical Guide

> Learn how Hallmark integrates with external services via API calls and installation hooks. This technical guide details Hallmark's connectivity for LLM coding assistants.

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

---

**Hallmark integrates with external services through client-side API calls, design-time API recommendations, and skill-based installation hooks for LLM coding assistants like Claude Code, Cursor, and Codex.**

The **Hallmark** design skill by Nutlope operates as a purely static client-side system. Rather than running server-side middleware, it leverages lightweight browser fetches, documented third-party API patterns, and skill packaging to connect with GitHub, Brandfetch, icon CDNs, and LLM tooling environments. This article examines each integration point with specific file references and code examples drawn from the `nutlope/hallmark` source repository.

---

## GitHub API Integration for Live Star Counts

Hallmark displays a live star count badge for the `nutlope/hallmark` repository on its public site. This integration demonstrates how the skill handles external data without a backend.

In [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) (lines 712-720), the JavaScript performs a direct `fetch` to the GitHub REST API:

```javascript
const REPO = "nutlope/hallmark";
fetch(`https://api.github.com/repos/${REPO}`, {
  headers: { Accept: "application/vnd.github+json" }
})
  .then(r => r.ok ? r.json() : null)
  .then(d => {
    if (d && typeof d.stargazers_count === "number") {
      const n = d.stargazers_count;
      starEl.textContent = n >= 1000 ? (n / 1000).toFixed(1) + "k" : String(n);
      localStorage.setItem(
        "hallmark-star-count:" + REPO,
        JSON.stringify({ n, t: Date.now() })
      );
    }
  })
  .catch(() => {/* keep cached or placeholder value */});

```

The implementation follows a **stale-while-revalidate caching strategy**:

- Data persists in `localStorage` with a one-hour TTL
- Failed requests fall back silently to cached or placeholder values
- No server-side proxy is required, keeping the architecture fully static

---

## Brandfetch API for Brand Asset Automation

While Hallmark itself does not embed direct Brandfetch calls, the skill provides **design-time guidance** for integrating this paid API. Located in [`skills/hallmark/references/assets.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/assets.md) (lines 99-100), the reference documentation specifies how developers can auto-populate brand data when building CMS forms or design systems.

The recommended integration pattern:

```javascript
fetch("https://api.brandfetch.io/v2/company?domain=vercel.com", {
  headers: { Authorization: `Bearer YOUR_BRANDFETCH_KEY` }
})
  .then(r => r.json())
  .then(data => {
    console.log(data.logo);      // SVG logo URL
    console.log(data.colors);    // Primary colour palette
    console.log(data.fonts);     // Recommended fonts
  });

```

This is a **design-time recommendation** rather than runtime code. The skill expects the consuming developer or LLM to implement the actual call based on the documented endpoint structure.

---

## Simple Icons CDN for Zero-Install Iconography

For icon integration without package dependencies, Hallmark references the **Simple Icons CDN**. The [`assets.md`](https://github.com/Nutlope/hallmark/blob/main/assets.md) file (lines 111-115) shows markup patterns for direct SVG inclusion:

```html
<img
  src="https://cdn.simpleicons.org/github/181717"
  alt="GitHub"
  width="24"
  height="24"
/>

```

This approach enables brand logo display with **zero build-time or runtime overhead** — no npm installs, no bundler configuration, and no JavaScript execution required.

---

## External API UI Patterns: The Distil Example

Hallmark's example gallery includes a landing page for **Distil**, a content-extraction API. While the implementation in `cobalt-01` remains static HTML/CSS, it demonstrates how Hallmark structures UI for external API services:

- Treat the API documentation as a **design brief**
- Generate matching typography, color schemes, and component hierarchies
- Produce static pages that can be wired to live API endpoints by the developer

This pattern shows how Hallmark **integrates with service concepts** even when no live data connection exists in the demo itself.

---

## LLM Coding Assistant Integration: Claude Code, Cursor, and Codex

The most significant integration architecture involves **skill-based distribution** to AI-powered coding environments. Hallmark is packaged as a portable skill that installs into three major tools.

**Automated installation via npx:**

```bash
npx skills add nutlope/hallmark

```

**Manual installation paths:**

| Tool | Destination Path |
|------|-----------------|
| Claude Code | `~/.claude/skills/hallmark/` |
| Cursor | `.cursor/rules/hallmark.mdc` |
| Codex | `~/.codex/skills/hallmark/` |

The [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) file serves as the **integration contract**. When copied to the appropriate directory, the host tool reads this rule-set to:

- Enforce Hallmark's four-verb methodology (Compile, Analyse, Judge, Improve)
- Provide macro-structure and theme conventions
- Apply the "slop-test" logic for evaluating design quality

This mechanism transforms Hallmark from a static site into an **embedded design advisor** within the developer's IDE.

---

## Summary

- **GitHub API**: Client-side fetch with `localStorage` caching in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js)
- **Brandfetch**: Design-time API documentation in [`skills/hallmark/references/assets.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/assets.md) for brand asset automation
- **Simple Icons CDN**: Zero-dependency icon loading via direct CDN URLs
- **External API UI**: Static design patterns for services like Distil, ready for developer wiring
- **LLM Tools**: Skill-based installation into Claude Code, Cursor, and Codex through [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) consumption

---

## Frequently Asked Questions

### How does Hallmark handle API authentication for external services?

Hallmark does not manage secrets or authentication flows. The GitHub star count uses unauthenticated public API endpoints. For services like Brandfetch, the skill documents the required header format but expects the consuming developer to provide their own API key and implement proper credential handling.

### Can Hallmark integrate with proprietary or internal APIs?

Yes. Because Hallmark generates static UI based on design briefs rather than executing fixed integrations, it can adapt to any API structure. Developers describe their internal API's data shapes and authentication patterns, and Hallmark produces matching page structures through its Compile verb.

### What happens if the GitHub API rate-limits the star count request?

The implementation in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) silently catches fetch failures and preserves any previously cached value from `localStorage`. If no cached value exists, the badge displays a placeholder. No user-facing error state interrupts the page experience.

### Does installing Hallmark as a skill require internet access?

No. Once the skill files are copied to `~/.claude/skills/`, `.cursor/rules/`, or `~/.codex/skills/`, the integration operates entirely offline. The LLM tool reads the local [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) and reference files without external network calls.