How Hallmark Handles Existing Global Stylesheets Like Tailwind

Hallmark treats pre-existing global stylesheets as append-only, injecting design tokens below Tailwind directives while placing new imports at the top of the file to preserve existing CSS architectures.

When working with the Nutlope/hallmark repository, understanding how the tool interacts with established styling infrastructure is essential for maintaining consistency. Hallmark specifically targets global stylesheets—such as app/globals.css, src/index.css, or src/styles/global.css—and applies a strict append-only policy codified in skills/hallmark/references/contract.md to ensure zero disruption to Tailwind workflows or custom CSS setups.

The Append-Only Output Contract

Hallmark operates under a formal output contract that mandates it never overwrites existing global stylesheets unless explicitly requested. During the pre-flight analysis step, the tool scans the current file structure and applies additive modifications only. This contract ensures that existing @import statements, custom CSS rules, and third-party dependencies remain intact and functional.

According to skills/hallmark/SKILL.md, this behavior is automatic and applied universally unless the user specifically signals intent for a full takeover.

Preserving Tailwind Directives

When Hallmark detects Tailwind directives—@tailwind base, @tailwind components, or @tailwind utilities—it leaves these statements in their exact original positions. The tool recognizes these directives as critical infrastructure and avoids inserting tokens between them, which could break the Tailwind processing pipeline.

For example, given an existing globals.css file:

@tailwind base;
@tailwind components;
@tailwind utilities;

Hallmark maintains this block unchanged, ensuring Tailwind's layers process in the correct order.

Injecting Tokens Below Tailwind Directives

After preserving existing directives, Hallmark appends its :root custom-property block below the Tailwind directives. This placement ensures that Tailwind's base, components, and utilities layers process before Hallmark's semantic tokens, preventing specificity conflicts.

/* Existing Tailwind entry – preserved */
@tailwind base;
@tailwind components;
@tailwind utilities;

/* Hallmark‑generated tokens – appended */
:root {
  --color-primary: oklch(var(--background));
  --color-secondary: oklch(var(--foreground));
  /* …other semantic tokens… */
}

This strategy maintains the cascade order while providing CSS variables that can reference Tailwind's theme values.

Managing Import Statement Hierarchy

Hallmark places any new @import statements required for its operation—such as @import "tokens.css"—at the very top of the file. This respects CSS parsing rules, which require @import statements to appear before all other at-rules and style rules (except @charset).

The placement logic follows this strict hierarchy:

1. New Hallmark imports at the absolute top
2. Preserved existing content (Tailwind directives and custom CSS)
3. Hallmark-generated tokens appended at the bottom

Reusing Existing Token Names

Rather than creating parallel token ecosystems, Hallmark maps its semantic roles onto existing CSS custom properties when available. If a project already defines --background, --foreground, or utilizes Tailwind's @theme block, Hallmark detects these during pre-flight analysis and references them instead of generating conflicting definitions.

Consider this existing Tailwind configuration:

// tailwind.config.js (original)
module.exports = {
  theme: {
    extend: {
      colors: {
        background: 'var(--background)',
        foreground: 'var(--foreground)',
      },
    },
  },
};

Hallmark adds its semantic tokens without duplicating these color definitions, creating a single source of truth for design values while avoiding namespace collisions.

Explicit Rewrite vs. Append Mode

By default, Hallmark operates in append mode to prevent accidental data loss. A complete overwrite of the global stylesheet only occurs when the user explicitly requests a takeover through configuration flags or CLI options.

// Pseudo-code representing Hallmark's internal logic
if (userRequestedFullRewrite) {
  // Overwrite the entire globals.css
} else {
  // Append Hallmark tokens as shown above
}

This conditional logic ensures that teams must actively consent before Hallmark modifies existing file contents beyond appending tokens.

Summary

Hallmark integrates with existing global stylesheets through a conservative, append-only strategy defined in its output contract:

• Preserves Tailwind directives: Maintains @tailwind statements in their original positions without interruption
• Appends tokens safely: Injects :root variables below existing CSS layers to maintain cascade order
• Respects import hierarchy: Places new @import statements at the file's top per CSS specification requirements
• Reuses existing tokens: Maps semantic roles to pre-existing --background and --foreground variables rather than duplicating them
• Requires explicit consent: Only performs full rewrites when explicitly requested by the user

Frequently Asked Questions

Will Hallmark overwrite my existing Tailwind configuration?

No. According to skills/hallmark/references/contract.md, Hallmark preserves existing Tailwind setups in both tailwind.config.js and global stylesheets. It appends design tokens rather than replacing content, ensuring your theme.extend values and @tailwind directives remain untouched and functional.

How does Hallmark handle CSS import statements?

Hallmark places any required new imports—such as @import "tokens.css"—at the very top of the file, above all other rules. This complies with CSS specifications that require @import to precede other at-rules, while your existing imports remain in their original positions below.

What happens if my project already has CSS custom properties defined?

Hallmark detects existing CSS custom properties like --background or --foreground during its pre-flight analysis as documented in skills/hallmark/SKILL.md. It maps its semantic token requirements onto these existing variables rather than creating duplicates, maintaining consistency with your current design system.

Can I force Hallmark to replace my entire stylesheet?

Yes, but only through explicit user action. Hallmark defaults to append-only mode to prevent accidental data loss. You must specifically request a full rewrite via configuration options before the tool will overwrite existing global stylesheets like app/globals.css or src/index.css.

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