# How Hallmark Handles Existing Global Stylesheets Like Tailwind

> Discover how Hallmark integrates existing global stylesheets like Tailwind. Learn its append-only approach to inject design tokens below Tailwind directives, preserving your CSS architecture.

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

---

**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`](https://github.com/Nutlope/hallmark/blob/main/app/globals.css), [`src/index.css`](https://github.com/Nutlope/hallmark/blob/main/src/index.css), or [`src/styles/global.css`](https://github.com/Nutlope/hallmark/blob/main/src/styles/global.css)—and applies a strict **append-only policy** codified in [`skills/hallmark/references/contract.md`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/globals.css) file:

```css
@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.

```css
/* 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:

```js
// 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.

```js
// 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`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/contract.md), Hallmark preserves existing Tailwind setups in both [`tailwind.config.js`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/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`](https://github.com/Nutlope/hallmark/blob/main/app/globals.css) or [`src/index.css`](https://github.com/Nutlope/hallmark/blob/main/src/index.css).