# Nutlope/hallmark Project Structure: A Deep Dive Into the 3 Core Components

> Explore the Nutlope/hallmark project structure. Understand the three core components: site, skills, and runtime-generated .hallmark/ for AI skill definition and system state.

- Repository: [Hassan El Mghari/hallmark](https://github.com/Nutlope/hallmark)
- Tags: deep-dive
- Published: 2026-08-10

---

**The Nutlope/hallmark repository consists of three primary components:** the `site/` directory for the public demo and documentation, the `skills/hallmark/` directory containing the AI skill definition and verb specifications, and the runtime-generated `.hallmark/` directory for persistent design-system state and caching.

The hallmark project is an AI-powered UI skill platform that enables Claude-based agents to generate, audit, and redesign web interfaces through natural language commands. Understanding its project structure is essential for contributors, integrators, and developers who want to extend the platform or debug its behavior. This article examines each component through the lens of the actual source code, referencing specific files and their responsibilities as implemented in the Nutlope/hallmark repository.

## The Three Pillars of the Hallmark Architecture

The hallmark project organizes its functionality around three interconnected pillars. Each pillar serves a distinct purpose in the skill's lifecycle from demonstration to execution to state persistence.

| Component | Purpose | Location |
|-----------|---------|----------|
| `site/` | Static website for demos, installation instructions, and interactive UI | `site/` |
| `skills/hallmark/` | Skill definition consumed by Claude-based agents | `skills/hallmark/` |
| `.hallmark/` | Runtime cache and log files for design-system decisions | Generated at runtime |

Supporting materials in `docs/` and [`ROADMAP.md`](https://github.com/Nutlope/hallmark/blob/main/ROADMAP.md) provide human-readable documentation, but these three pillars constitute the executable architecture.

## Component 1: The `site/` Directory (Public Front-End)

The `site/` directory hosts the public-facing demonstration of hallmark capabilities. This static website allows potential users to explore the skill without local installation.

### HTML Entry Point and Demo Interface

The file [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) serves as the primary entry point. It contains:

- A banner linking to the GitHub repository
- A theme selector for previewing different visual treatments
- Pre-written hallmark prompts showcasing command patterns

Lines 247–334 of [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) expose example commands such as:

```bash
hallmark build a landing page for a small-batch honey farm

```

These prompts demonstrate how users interact with the skill's natural language interface.

### Styling and Visual Language

The CSS architecture spans multiple files:

- [`site/css/base.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/base.css) – foundational styles
- [`site/css/components.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/components.css) – UI component definitions

The component stylesheet includes hallmark-specific selectors, notably `[data-variant="hallmark"]` (lines 1262–1324), which applies distinctive styling to hallmark-generated outputs.

### Client-Side Logic and Interactivity

The file [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) handles:

- **Theme persistence**: Uses `STORAGE_KEY = "hallmark-theme"` (line 65) to save user preferences across sessions
- **Installation workflow**: Implements a copy-to-clipboard feature for the installation command `npx skills add nutlope/hallmark` (lines 840–906)

This component transforms abstract skill capabilities into tangible, interactive demonstrations.

## Component 2: The `skills/hallmark/` Directory (AI Skill Definition)

The `skills/hallmark/` directory contains the machine-readable specifications that Claude-based agents parse to execute hallmark commands. This is the core intellectual property of the project.

### SKILL.md: The Canonical Manifest

The file [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) serves as the authoritative source of truth for agent behavior. It specifies:

- **Three core verbs**: `audit`, `redesign`, and `study`
- **Behavior constraints** for each verb
- **Output format specifications**
- The "slop test" for detecting AI-generated anti-patterns
- **Diversification rules** preventing repetitive outputs
- The [`design.md`](https://github.com/Nutlope/hallmark/blob/main/design.md) lockfile mechanism for preserving design decisions

Lines 2–153 of [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) define the complete verb specification that agents use to route user requests.

### Reference Documentation Architecture

The subdirectory `skills/hallmark/references/` contains granular documentation for every aspect of the skill's internal language:

| Reference File | Contents |
|----------------|----------|
| [`verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/verbs/redesign.md) | Multi-page redesign workflow and state management |
| [`verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/verbs/audit.md) | Anti-pattern detection logic and ranking |
| [`verbs/study.md`](https://github.com/Nutlope/hallmark/blob/main/verbs/study.md) | URL-based DNA extraction methodology |
| [`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md) | Theme axis recording in [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) (lines 210–240) |
| [`component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/component-cookbook.md) | Reusable UI blocks (Bento grids, product-card grids, etc.) |

These files are **read-only at runtime**. The hallmark agent consults them to determine which macro-structure, theme, and enrichment parameters to apply.

### Component Cookbook and Reusable Patterns

The [`references/component-cookbook.md`](https://github.com/Nutlope/hallmark/blob/main/references/component-cookbook.md) enumerates composable UI blocks that hallmark assembles during builds. This modular approach enables the skill to construct varied interfaces from a constrained but expressive vocabulary of patterns.

## Component 3: The `.hallmark/` Directory (Persistent State)

Unlike the previous components, `.hallmark/` is **generated at runtime** and excluded from version control. It serves as the memory layer that makes hallmark intelligent across multiple invocations.

### Log File: [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json)

Every hallmark run appends a structured entry to [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json):

```json
{
  "date": "YYYY-MM-DD",
  "macrostructure": "<name>",
  "theme": "<name>",
  "enrichment": "<E# name or 'none'>",

  "brief": "<one-line summary>"
}

```

This log enables two critical capabilities:

1. **Diversification**: Prevents consecutive builds from reusing identical navigation or footer archetypes
2. **Consistency preservation**: Allows the `redesign` verb to read previous selections and maintain visual coherence

Lines 298–346 of [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) document how the log file drives these behaviors.

### Preflight Cache: [`.hallmark/preflight.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/preflight.json)

The preflight file stores expensive computation results, particularly from URL-mode study operations. When a user runs `hallmark study https://example.com`, the extracted design DNA gets cached here. Subsequent runs reuse this data unless the user explicitly forces a refresh (lines 177–191).

## Practical Workflow Integration

Understanding how components interact clarifies the hallmark execution model.

### Installation Flow

```bash
npx skills add nutlope/hallmark

```

This command (exposed via the copy-to-clipboard feature in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js)) registers the skill with the local Claude environment.

### Build Execution

```bash
hallmark build "a landing page for a small-batch honey farm" modern-minimal

```

The agent parses [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) to:
1. Map `build` to the internal `hallmark default` flow
2. Select an appropriate macro-structure
3. Apply the `modern-minimal` theme if available in the theme registry
4. Write a new entry to [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json)
5. Return generated HTML/CSS

### Audit and Study Operations

```bash
hallmark audit ./hero.tsx
hallmark study https://example.com/brand-landing

```

The `audit` verb consults [`references/anti-patterns.md`](https://github.com/Nutlope/hallmark/blob/main/references/anti-patterns.md) (lines 3–7) to produce ranked improvement recommendations. The `study` verb extracts and caches design DNA to [`.hallmark/preflight.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/preflight.json) per [`references/study.md`](https://github.com/Nutlope/hallmark/blob/main/references/study.md) (lines 3–30).

## Key Files for Deep Reference

| File | Role |
|------|------|
| [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) | Demo landing and installation instructions |
| [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) | Theme persistence and install-command UI |
| [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) | Verb manifest and execution rules |
| [`skills/hallmark/references/verbs/redesign.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/redesign.md) | Multi-page redesign specification |
| [`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md) | Anti-pattern audit logic |
| [`skills/hallmark/references/verbs/study.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/study.md) | URL study and DNA extraction |
| [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) | Generated design-system log |
| [`docs/README.md`](https://github.com/Nutlope/hallmark/blob/main/docs/README.md) | Project overview and roadmap |
| [`ROADMAP.md`](https://github.com/Nutlope/hallmark/blob/main/ROADMAP.md) | Future development plans |

## Summary

- **The `site/` directory** provides public demonstration and installation pathways through [`index.html`](https://github.com/Nutlope/hallmark/blob/main/index.html), component CSS, and [`main.js`](https://github.com/Nutlope/hallmark/blob/main/main.js) with theme persistence.

- **The `skills/hallmark/` directory** encodes agent behavior through [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) and granular reference documentation, defining how `audit`, `redesign`, and `study` verbs execute.

- **The `.hallmark/` directory** persists state across runs via [`log.json`](https://github.com/Nutlope/hallmark/blob/main/log.json) (design-system history) and [`preflight.json`](https://github.com/Nutlope/hallmark/blob/main/preflight.json) (computation caching), enabling diversification and consistency.

- **Cross-component integration** occurs through the skill manifest: [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) references files in `site/` for examples and writes to `.hallmark/` for state management.

## Frequently Asked Questions

### What makes the `skills/hallmark/` directory different from typical source code?

The `skills/hallmark/` directory contains **declarative specifications** rather than imperative code. Files like [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) are parsed by Claude-based agents at runtime to determine behavior. This architecture separates *what the skill does* from *how the AI implements it*, allowing the same specification to evolve with underlying model capabilities.

### Why does hallmark need a `.hallmark/` log file instead of being stateless?

The [`.hallmark/log.json`](https://github.com/Nutlope/hallmark/blob/main/.hallmark/log.json) file enables **diversification rules** that prevent repetitive outputs and **consistency preservation** across redesign operations. Without this state, the `redesign` verb could not respect previous macro-structure or theme selections, and consecutive builds might produce visually identical navigation patterns.

### How does the `site/` directory relate to the actual skill execution?

The `site/` directory operates independently of skill execution but serves critical ecosystem functions: it demonstrates capabilities to prospective users, provides installation instructions, and hosts interactive examples. The [`main.js`](https://github.com/Nutlope/hallmark/blob/main/main.js) file coordinates with the skill definition by surfacing the identical installation command (`npx skills add nutlope/hallmark`) that [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) assumes.

### Where are the hallmark verbs actually implemented?

The verb implementations reside in the **Claude agent runtime**, not in this repository. The `skills/hallmark/` directory provides the *specification* that the agent consumes. Files like [`references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/references/verbs/audit.md) describe what constitutes an anti-pattern and how to rank findings, but the actual parsing and analysis occurs within the AI system interpreting these documents.