How to Customize Hallmark's Component Library for Your Project

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 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. Individual component files such as h1-marquee.md, h2-split-diptych.md, f1-bento-grid.md, n5-floating-pill.md, and 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. 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).

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:

<!-- 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) into your project as src/styles/tokens.css. Edit the CSS custom properties to match your brand:

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

According to 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. 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. 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 to map Hallmark tokens:

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 and styles.css into your main stylesheet.

Common Customization Scenarios

• Change brand colors: Update --color-primary, --color-background, and related tokens in tokens.css.
• Swap navigation style: Replace your current nav with a different N* archetype (e.g., n5-floating-pill.md) and include the matching JavaScript from script.js.
• Adjust spacing scale: Modify --space-sm, --space-md, and --space-lg values in 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) in your hero section HTML.

Summary

• Hallmark organizes UI elements into ~50 archetypes documented in component-cookbook.md and stored in skills/hallmark/references/components/.
• Visual customization happens primarily through CSS custom properties in tokens.css, not by editing component markup directly.
• Interactive behaviors are modular and copied from example scripts like 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). Include a minimal HTML sketch, CSS snippet, and "use when" description. Register it in 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 and the component CSS snippets into any build pipeline or vanilla HTML project. The runtime JavaScript in 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, 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) 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.

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