How Hallmark Integrates with Next.js, Vue, Svelte, and Vanilla HTML

Hallmark automatically detects your frontend framework by scanning package.json for dependencies like next, vue, or svelte, then generates a universal tokens.css file and injects framework-specific imports to wire up the design system.

Hallmark is a design skill from the Nutlope/hallmark repository that functions as a framework-agnostic styling layer. According to the source code in skills/hallmark/SKILL.md, the tool performs a pre-flight inspection of your codebase to determine the build environment, then adapts its output format to match the conventions of your specific stack.

Framework Detection Mechanism

Hallmark determines which integration path to use by reading the Framework signal defined at line 158 of SKILL.md. The detection logic scans package.json for specific package names:

• Next.js: Presence of next
• Vue: Presence of vue
• Svelte/SvelteKit: Presence of svelte or @sveltejs/kit
• Vanilla HTML: Default fallback when no framework packages are detected

This inspection occurs during the pre-flight scan phase, where Hallmark analyzes existing configuration files, tailwind.config.* patterns, and HTML structure before deciding on a macrostructure and theme.

Framework-Specific Integration Patterns

Next.js Integration

When Hallmark detects the next dependency, it configures typography using next/font (or @fontsource packages) and emits CSS variables compatible with static export builds.

The skill creates a tokens.css file at the project root and ensures it is imported into the global stylesheet. For font loading, Hallmark generates imports that leverage Next.js’s built-in font optimization:

// globals.css - Auto-generated import
@import "./tokens.css";

// Font configuration example
import { GeistSans } from 'next/font/google';
const geist = GeistSans({ subsets: ['latin'] });

The generated pages are self-contained HTML and CSS compatible with next export, with all design tokens living in the centralized tokens.css file.

Vue Integration

For Vue projects, Hallmark detects the vue package and injects an @import statement into the root component’s style block. If the project uses a CSS preprocessor like SCSS, Hallmark outputs the tokens in the matching format.

<!-- src/App.vue - Hallmark injects the following -->
<style>
@import "./tokens.css";
</style>

This approach ensures the design token variables are available across all single-file components without modifying JavaScript logic.

Svelte and SvelteKit Integration

When svelte or @sveltejs/kit appears in dependencies, Hallmark targets the root layout component. It inserts a standard ES module import for the token file and handles font loading via the <svelte:head> tag.

<!-- src/routes/+layout.svelte - Auto-generated import -->
<script>
  import "../tokens.css";
</script>

This injection point guarantees that design tokens are available to all routes in a SvelteKit application or throughout a Svelte component tree.

Vanilla HTML Integration

In the absence of any framework detection, Hallmark defaults to plain HTML generation. It creates or updates an index.html file (or site/index.html) to include a standard stylesheet link.

<!-- index.html - Hallmark adds the link tag -->
<link rel="stylesheet" href="tokens.css">

All macro-structure classes, theme variables, and font declarations live in the external tokens.css file, keeping the markup clean and framework-free.

The tokens.css Architecture

Regardless of framework, Hallmark always emits a tokens.css file at the project root, as specified at line 464 of SKILL.md. This file contains the complete design system specification:

• --color-* palette variables
• --font-* typography scales
• --space-* spacing units
• --text-* type sizing
• --ease-* and --dur-* animation curves
• --rule-* layout constraints
• --radius-* corner values

This centralized approach ensures that switching frameworks or running Hallmark multiple times on different targets produces consistent visual output while maintaining framework-idiomatic import patterns.

Implementation Workflow

The integration process follows a consistent four-step pattern across all environments:

1. Add the skill: Run npx skills add nutlope/hallmark to copy SKILL.md and the references/ folder into your editor’s skill directory (referenced in README.md at line 94).

2. Execute Hallmark: Run hallmark or hallmark redesign <target>. The tool performs the pre-flight scan (described at SKILL.md#L45) to detect frameworks, analyze existing Tailwind configurations, and select a theme.

3. Generate tokens: Hallmark writes tokens.css containing all design tokens to the project root.

4. Inject imports: Based on the framework detected in package.json, Hallmark modifies the appropriate entry point—whether a Vue SFC style block, SvelteKit layout file, Next.js global CSS, or plain HTML—to import the design tokens.

Hallmark also maintains a .hallmark/log.json file (as noted at SKILL.md#L461) that records the macrostructure and theme used during the last run, enabling diversification logic to avoid repeating identical designs on subsequent executions.

Summary

• Hallmark detects frameworks by scanning package.json for specific package names like next, vue, or svelte, defaulting to vanilla HTML when none are found.
• The tool always generates a tokens.css file at the project root containing comprehensive design tokens for colors, typography, spacing, and animation.
• Framework integration occurs through idiomatic import methods: @import in Vue style blocks, ES modules in SvelteKit layouts, next/font in Next.js, and <link> tags in vanilla HTML.
• The .hallmark/log.json file tracks previous design choices to ensure visual diversity across multiple runs.

Frequently Asked Questions

How does Hallmark detect which framework I'm using?

Hallmark reads your package.json file and searches for specific dependency names. According to skills/hallmark/SKILL.md at line 158, it looks for next to identify Next.js, vue for Vue projects, and svelte or @sveltejs/kit for Svelte environments. If no matching packages are found, it assumes a vanilla HTML project.

What file does Hallmark always generate regardless of framework?

Hallmark always produces a tokens.css file at the project root. As documented at line 464 of SKILL.md, this file contains all design system variables including color palettes, font stacks, spacing scales, and animation timing functions, ensuring consistent tokens across all supported frameworks.

Does Hallmark support CSS preprocessors like SCSS?

Yes. When Hallmark detects a Vue project using SCSS or similar preprocessors, it adapts the token output format to match. The skill inspects existing style configurations during the pre-flight scan and emits tokens in the appropriate syntax for the detected preprocessor environment.

Where does Hallmark record previous design choices?

Hallmark maintains a .hallmark/log.json file that tracks the macrostructure, theme, and token set used during the last execution. As noted in the source code at SKILL.md#L461, this log enables the skill to diversify its output on subsequent runs, avoiding repetitive designs when re-run on the same codebase.

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