How Security Is Handled in Nutlope/Hallmark: A Defense-in-Depth Approach

Nutlope/hallmark implements a zero-trust security model that enforces token-only styling, prevents secret leakage, and preserves existing CSP configurations through append-only CSS injection.

The Nutlope/hallmark repository treats security as a first-class design constraint by eliminating inline style values and external script dependencies. By mandating that all visual data flows through CSS custom properties stored in tokens.css, the project ensures that sensitive information cannot accidentally leak through design tokens. Every security mechanism is codified in the skill's reference documents and enforced automatically during the build process.

Token Discipline and Locked Tokens

Hallmark’s primary security surface is its token-only architecture. All colour, spacing, font-size, and other design values must be stored as named CSS custom properties in tokens.css (or the equivalent DTCG tokens.json). Inline values such as #ff5733, oklch(...), or raw font-family strings are rejected at build time via the "mid-render token improvisation" anti-pattern check documented in skills/hallmark/references/anti-patterns.md.

Once a theme is selected (Step 2.6 in skills/hallmark/SKILL.md), the "locked tokens" gate enforces that every CSS rule must reference a token. Any stray raw value causes the build to fail and prompts the author to lift the value into the token block first. This prevents accidental leakage of secret values (e.g., API keys that might be encoded in a colour) and guarantees a single source of truth for every token.

/* ✅ Correct – token reference */
body { background: var(--color-paper); }

/* ❌ Forbidden – raw colour value */
body { background: #ff5733; }   /* Build fails: “mid‑render token improvisation” */

Append-Only Global Stylesheet Handling

When a project already contains a global stylesheet (e.g., app/globals.css), Hallmark never overwrites existing @import or @tailwind directives. According to skills/hallmark/references/contract.md, the skill only appends its own :root token block below them, keeping the existing build pipeline intact. This append-only policy avoids accidental removal of security-related directives such as CSP meta tags or content-security policies defined by the host project.

Safe External Resource Fetching

Hallmark only fetches public URLs in URL mode and explicitly refuses to read pages that require authentication, contain SPA shells, or otherwise hide the design intent. As documented in skills/hallmark/references/study.md under the "junk-or-blocked-check" section, this restriction protects against inadvertent exposure of private sites or credentials during the design extraction phase.

No Secret Leakage Policy

The skill adheres to a strict no-secret policy defined in the repository’s system-instructions (Security rule 1). Hallmark never reads or writes environment variables, API keys, or other secrets. All generated artefacts (tokens.css, tokens.json, design.md) contain only design data; no runtime credentials are ever emitted.

// No secret handling – Hallmark never touches process.env or similar
export const secure = () => {/* intentionally empty */};

CORS and CSP Safety in Generated Markup

Hallmark’s example pages (site/index.html, site/examples/**/index.html) demonstrate secure loading patterns. They load stylesheets via relative URLs (<link rel="stylesheet" href="css/tokens.css">) and do not embed remote scripts or inline styles that could trigger CSP violations. This references line 59 of site/index.html and establishes the recommended practice for downstream projects to avoid cross-origin resource risks.

<!-- ✅ Safe import of Hallmark tokens -->
<link rel="stylesheet" href="css/tokens.css" />

Summary

• Token-only styling enforced via the "locked tokens" gate prevents raw value injection and secret encoding in CSS
• Append-only CSS injection preserves existing CSP directives and security headers in host projects
• Public URL restriction blocks fetching of authenticated or private resources during design extraction
• Zero secret handling ensures environment variables and API keys are never accessed, read, or emitted in generated artefacts

Frequently Asked Questions

Does Hallmark access my environment variables or API keys?

No. According to Security rule 1 in the repository’s system-instructions, Hallmark never reads or writes environment variables, API keys, or other secrets. All generated artefacts contain only design data, with no runtime credentials ever emitted.

What happens if I try to use an inline color value instead of a token?

The build fails with a "mid-render token improvisation" error. As documented in skills/hallmark/references/anti-patterns.md and enforced by the locked tokens gate in skills/hallmark/SKILL.md, every CSS rule must reference a token from tokens.css or tokens.json. Raw values are rejected automatically.

Will Hallmark overwrite my existing CSS or security headers?

No. Per skills/hallmark/references/contract.md, Hallmark uses an append-only policy when injecting tokens into existing global stylesheets. It only adds its :root token block below existing @import or @tailwind directives, preserving your existing CSP meta tags and security configurations.

Can Hallmark fetch content from password-protected websites?

No. As specified in skills/hallmark/references/study.md, the skill explicitly refuses to read pages that require authentication, contain SPA shells, or otherwise hide the design intent. This prevents inadvertent exposure of private sites or credentials during the extraction process.

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