# How to Customize Hallmark's Component Library for Your Project

> Easily customize Hallmark's component library for your project. Select archetypes, copy definitions, and override CSS custom properties to match your brand. Get started now.

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

---

**TLDR:** Hallmark's component library can be customized by selecting archetypes from the component cookbook, copying their HTML/CSS definitions from the `components/` directory, and overriding the CSS custom properties in [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) to match your brand identity.

Hallmark is an open-source design system built around a **component cookbook** of roughly fifty reusable UI archetypes. According to the Nutlope/hallmark repository, each component is defined as a Markdown file containing minimal HTML sketches and CSS snippets that consume a central token system. Customizing the library involves picking specific archetypes, adjusting design tokens, and wiring interactive behavior through a minimal JavaScript runtime.

## Understanding Hallmark's Architecture

Hallmark separates concerns into four distinct layers. This separation allows you to swap visual styles without rebuilding components or change layouts without touching JavaScript.

### The Component Catalogue

The **component catalogue** defines roughly fifty reusable UI archetypes spanning hero blocks, feature grids, navigation bars, and footers. Each archetype lives as a Markdown description in `skills/hallmark/references/components/` and is indexed in [`skills/hallmark/references/component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/component-cookbook.md). Individual component files such as [`h1-marquee.md`](https://github.com/Nutlope/hallmark/blob/main/h1-marquee.md), [`h2-split-diptych.md`](https://github.com/Nutlope/hallmark/blob/main/h2-split-diptych.md), [`f1-bento-grid.md`](https://github.com/Nutlope/hallmark/blob/main/f1-bento-grid.md), [`n5-floating-pill.md`](https://github.com/Nutlope/hallmark/blob/main/n5-floating-pill.md), and [`ft2-inline-rule-single-line.md`](https://github.com/Nutlope/hallmark/blob/main/ft2-inline-rule-single-line.md) contain minimal HTML sketches and CSS snippets that describe the component's structure and intended use.

### The Token System

Design decisions are centralized in a **token system** implemented as CSS custom properties. Variables such as `--space-md`, `--color-brand`, and typography scales are defined in `site/examples/<theme>/tokens.css`. These tokens drive color, spacing, type, and motion across all components, allowing global style changes without modifying individual component files.

### Styling and Runtime Layers

Base styling consumes the tokens through Tailwind or vanilla CSS in `site/examples/<theme>/styles.css`. Interactive behaviors—such as sticky navigation, floating pills, and scroll-linked animations—are handled by minimal JavaScript in `site/examples/<theme>/script.js`.

## Step-by-Step Customization Workflow

### 1. Select Component Archetypes

Browse the master index at [`skills/hallmark/references/component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/component-cookbook.md). Each entry includes a "use when" description, differentiation guidance ("don't confuse with"), and a link to its detailed Markdown file. For example, to implement a split hero layout, select **H2 · Split diptych** ([`components/h2-split-diptych.md`](https://github.com/Nutlope/hallmark/blob/main/components/h2-split-diptych.md)).

### 2. Copy Component Definitions

Each component Markdown file contains a minimal DOM sketch and CSS snippet. Copy these into your project's HTML or templating files:

```html
<!-- Example structure from h2-split-diptych.md -->
<section class="hero-split">
  <div class="diptych-panel">...</div>
  <div class="diptych-panel">...</div>
</section>

```

Adjust class names or token references to fit your existing naming conventions.

### 3. Customize Design Tokens

Duplicate the token file from an example theme (e.g., [`site/examples/lumen-01/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/site/examples/lumen-01/tokens.css)) into your project as [`src/styles/tokens.css`](https://github.com/Nutlope/hallmark/blob/main/src/styles/tokens.css). Edit the CSS custom properties to match your brand:

```css
:root {
  --color-primary: #3b82f6;
  --color-background: #0f172a;
  --space-md: 1.5rem;
}

```

According to [`skills/hallmark/references/export-formats.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/export-formats.md), append the `:root` token block after existing `@import` statements in your stylesheet, ensuring you never overwrite existing `@tailwind` directives.

### 4. Implement Interactive Behavior

For components requiring JavaScript (floating navigation, sticky scroll stacks), copy the relevant fragments from an example script such as [`site/examples/custom-03/script.js`](https://github.com/Nutlope/hallmark/blob/main/site/examples/custom-03/script.js). Ensure the script runs after DOM ready and that CSS class references match your custom markup.

### 5. Validate in the Component Playground

Before production deployment, test component combinations using the **Component Playground** macrostructure at [`skills/hallmark/references/macrostructures/21-component-playground.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/macrostructures/21-component-playground.md). This sandbox allows you to drop multiple component snippets on a single page to verify visual harmony and responsive behavior.

### 6. Integrate with Your Build Pipeline

For Tailwind projects, extend your [`tailwind.config.js`](https://github.com/Nutlope/hallmark/blob/main/tailwind.config.js) to map Hallmark tokens:

```javascript
module.exports = {
  theme: {
    extend: {
      colors: {
        brand: 'var(--color-brand)',
        primary: 'var(--color-primary)',
      },
      spacing: {
        md: 'var(--space-md)',
      }
    }
  }
}

```

For non-Tailwind setups, import the compiled [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) and [`styles.css`](https://github.com/Nutlope/hallmark/blob/main/styles.css) into your main stylesheet.

## Common Customization Scenarios

- **Change brand colors:** Update `--color-primary`, `--color-background`, and related tokens in [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css).
- **Swap navigation style:** Replace your current nav with a different `N*` archetype (e.g., [`n5-floating-pill.md`](https://github.com/Nutlope/hallmark/blob/main/n5-floating-pill.md)) and include the matching JavaScript from [`script.js`](https://github.com/Nutlope/hallmark/blob/main/script.js).
- **Adjust spacing scale:** Modify `--space-sm`, `--space-md`, and `--space-lg` values in [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) to compress or expand the layout rhythm.
- **Replace the hero block:** Swap the current `H*` component with another archetype (e.g., [`h4-stat-led.md`](https://github.com/Nutlope/hallmark/blob/main/h4-stat-led.md)) in your hero section HTML.

## Summary

- Hallmark organizes UI elements into ~50 archetypes documented in [`component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/component-cookbook.md) and stored in `skills/hallmark/references/components/`.
- Visual customization happens primarily through CSS custom properties in [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css), not by editing component markup directly.
- Interactive behaviors are modular and copied from example scripts like [`site/examples/custom-03/script.js`](https://github.com/Nutlope/hallmark/blob/main/site/examples/custom-03/script.js).
- The **Component Playground** macrostructure provides a sandbox for testing component combinations before production.
- Integration requires appending token imports after existing stylesheet directives to avoid conflicts with existing Tailwind configurations.

## Frequently Asked Questions

### How do I add a new component that isn't in the cookbook?

Create a new Markdown file in `skills/hallmark/references/components/` following the established naming convention (e.g., [`h5-custom-hero.md`](https://github.com/Nutlope/hallmark/blob/main/h5-custom-hero.md)). Include a minimal HTML sketch, CSS snippet, and "use when" description. Register it in [`component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/component-cookbook.md) to maintain the index and ensure other developers can discover your addition.

### Can I use Hallmark components without Tailwind CSS?

Yes. While Hallmark provides Tailwind-compatible examples, the component definitions use standard CSS custom properties. Import [`tokens.css`](https://github.com/Nutlope/hallmark/blob/main/tokens.css) and the component CSS snippets into any build pipeline or vanilla HTML project. The runtime JavaScript in [`script.js`](https://github.com/Nutlope/hallmark/blob/main/script.js) has no Tailwind dependencies and relies only on standard DOM APIs.

### What is the correct order for importing Hallmark tokens into an existing project?

According to [`skills/hallmark/references/export-formats.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/export-formats.md), place the `@import "tokens.css"` statement after existing `@tailwind` directives but before component-specific styles. This ensures your design tokens override defaults without breaking existing utility classes or specificity chains.

### How do I preserve customizations when updating Hallmark?

Maintain your custom tokens in a separate file (e.g., [`tokens-custom.css`](https://github.com/Nutlope/hallmark/blob/main/tokens-custom.css)) that imports the base Hallmark tokens and overrides specific variables. Keep copied component markup in your project's component directory rather than editing files in `node_modules` or the Hallmark source tree, allowing you to update the core library without merge conflicts.