# Visual Representation of the Nutlope/hallmark Directory Structure

> Explore the Nutlope/hallmark directory structure visually. Understand how source code is organized into site, skills hallmarked, and docs folders for clear separation of assets.

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

---

**The Nutlope/hallmark repository groups its source into three primary folders—`site/`, `skills/hallmark/`, and `docs/`—that separate the static demo, the AI skill definition, and the usage documentation.**

The `Nutlope/hallmark` project is a lightweight design-skill package installable into Claude Code, Cursor, or Codex. Understanding its directory structure lets you quickly locate the static website source, the markdown references that power design verbs, and the recipe guides that demonstrate real-world usage. Below is a complete visual breakdown of the folder hierarchy and an explanation of how each part contributes to the whole.

## Visual Overview of the Nutlope/hallmark Directory Structure

The root level keeps metadata minimal. Alongside [`README.md`](https://github.com/Nutlope/hallmark/blob/main/README.md), `LICENSE`, and [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json), the repository uses three purpose-built directories to isolate runtime demos from skill logic and human-facing documentation.

```text
.
├── README.md
├── LICENSE
├── package.json
├── site/
│   ├── index.html
│   ├── js/
│   │   └── main.js
│   ├── css/
│   │   ├── base.css
│   │   ├── components.css
│   │   ├── sections.css
│   │   └── tokens.css
│   ├── examples/
│   │   ├── grid-01/
│   │   │   ├── index.html
│   │   │   └── styles.css
│   │   └── custom-02/
│   │       ├── index.html
│   │       ├── styles.css
│   │       └── script.js
│   └── OG-hallmark.png
├── skills/
│   └── hallmark/
│       ├── SKILL.md
│       └── references/
│           ├── verbs/
│           │   ├── audit.md
│           │   └── redesign.md
│           ├── components/
│           │   └── t1-pull-quote-with-marginalia.md
│           ├── genres/
│           │   └── modern-minimal.md
│           └── custom-theme.md
└── docs/
    ├── recipes.md
    ├── study-examples.md
    ├── talk-slides.md
    └── screenshots/
        ├── hero-hum-07.jpg
        └── hero-cobalt-01.jpg

```

### Root-Level Configuration Files

The top-level files provide standard project metadata. [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) contains the minimal npm metadata used by the `npx skills add` installer, while [`README.md`](https://github.com/Nutlope/hallmark/blob/main/README.md) supplies the project overview and quick-start instructions. `LICENSE` holds the MIT license text.

### `site/` — Static Demo Website

The `site/` folder powers the live demo at `https://www.usehallmark.com`. It is a self-contained collection of HTML, CSS, and vanilla JavaScript that showcases generated pages and theme examples. Every page’s macrostructure is encoded as a comment inside its CSS file, starting with [`site/css/base.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/base.css). The [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) file handles theme switching and UI interactions, while the `examples/` subdirectory contains standalone pages such as [`grid-01/index.html`](https://github.com/Nutlope/hallmark/blob/main/grid-01/index.html) and [`custom-02/index.html`](https://github.com/Nutlope/hallmark/blob/main/custom-02/index.html) that demonstrate specific layout patterns.

### `skills/hallmark/` — AI Skill Definitions

This directory is the core intelligence consumed by Claude Code, Cursor, and Codex. [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) is the entry point that defines the skill, while the `references/` subdirectory organizes markdown guides by category. Verbs live under `skills/hallmark/references/verbs/` (e.g., [`audit.md`](https://github.com/Nutlope/hallmark/blob/main/audit.md) and [`redesign.md`](https://github.com/Nutlope/hallmark/blob/main/redesign.md)), component patterns live under `skills/hallmark/references/components/` (e.g., [`t1-pull-quote-with-marginalia.md`](https://github.com/Nutlope/hallmark/blob/main/t1-pull-quote-with-marginalia.md)), and genre guides such as [`modern-minimal.md`](https://github.com/Nutlope/hallmark/blob/main/modern-minimal.md) live under `skills/hallmark/references/genres/`. The [`custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/custom-theme.md) file provides the detailed workflow for creating a completely custom design.

### `docs/` — Documentation and Screenshots

Higher-level guides and visual assets live here. [`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md) provides worked examples that illustrate how to invoke the skill’s verbs. [`docs/study-examples.md`](https://github.com/Nutlope/hallmark/blob/main/docs/study-examples.md) contains sample study-mode inputs and expected DNA extraction outputs. [`docs/talk-slides.md`](https://github.com/Nutlope/hallmark/blob/main/docs/talk-slides.md) holds presentation material, and `docs/screenshots/` stores hero images such as `hero-hum-07.jpg` and `hero-cobalt-01.jpg` used by the live demo.

## How `site/`, `skills/`, and `docs/` Work Together

The repository architecture is deliberately modular. The static demo in `site/` visualizes the design system described by the markdown references in `skills/hallmark/references/`. When you run a command like `hallmark audit path/to/project`, the tool reads the reference files under [`skills/hallmark/references/verbs/audit.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/verbs/audit.md) to decide which macrostructure, theme, and component patterns to apply. The `docs/` folder then provides the human-readable recipes and screenshot assets that explain those outputs to end users.

## Practical Commands for Navigating the Repository

Developers typically interact with the project in three ways: installing the skill, running a design verb, or serving the demo locally.

1. **Install the skill into Claude Code, Cursor, or Codex**

   ```bash
   npx skills add nutlope/hallmark
   ```

   This command copies [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) and the `references/` markdown files to the appropriate location.

2. **Run a verb against a target**

   ```bash
   hallmark audit path/to/project
   hallmark redesign path/to/brief
   hallmark study https://example.com
   ```

   Each verb reads the reference files under `skills/hallmark/references/` to determine the correct design logic.

3. **Serve the live demo locally**

   ```bash
   npm install -g serve
   serve site
   ```

   Opening `http://localhost:5000` displays the same pages you see at `https://www.usehallmark.com`, allowing you to inspect the generated HTML and CSS directly.

## Essential Files to Bookmark

If you want to dive straight into the source, these files are the most informative:

- **[`README.md`](https://github.com/Nutlope/hallmark/blob/main/README.md)** — High-level project description, live-demo link, and installation instructions.
- **[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md)** — The core skill definition consumed by AI editors.
- **[`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html)** — Entry point for the static website.
- **[`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js)** — Powers theme switching and UI interactions.
- **[`site/css/base.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/base.css)** — Contains macrostructure comments and core design tokens.
- **[`skills/hallmark/references/custom-theme.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/references/custom-theme.md)** — Guide for the “Custom NEW” workflow.
- **[`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md)** — Worked examples illustrating verb invocations.
- **[`docs/study-examples.md`](https://github.com/Nutlope/hallmark/blob/main/docs/study-examples.md)** — Sample study-mode inputs and expected outputs.

## Summary

- The `Nutlope/hallmark` repository separates its runtime demo, AI skill logic, and human documentation into three top-level directories: `site/`, `skills/hallmark/`, and `docs/`.
- The `site/` directory holds the self-contained HTML, CSS, and JavaScript that power the live demo at `usehallmark.com`.
- The `skills/hallmark/` directory supplies [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) and a rich library of categorized markdown references that drive the audit, redesign, and study verbs.
- The `docs/` directory contains recipes, study examples, talk slides, and screenshot assets for reference and learning.

## Frequently Asked Questions

### What is the purpose of the `skills/hallmark/` directory?

The `skills/hallmark/` directory contains the [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) entry point and the `references/` library that Claude Code, Cursor, and Codex read to perform design audits, redesigns, and studies. It functions as the brain of the project, providing the structured guidance that AI agents use to analyze and generate designs.

### How do I run the Hallmark demo site on my local machine?

Navigate to the cloned repository and run `serve site` after installing the `serve` package globally. This hosts the static files found in `site/` at `http://localhost:5000`, letting you inspect [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html), [`site/css/base.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/base.css), and the example pages directly in your browser.

### Which file defines the design tokens and macrostructure?

[`site/css/base.css`](https://github.com/Nutlope/hallmark/blob/main/site/css/base.css) encodes the macrostructure comments and core design tokens that drive the visual layout of every generated page. The JavaScript in [`site/js/main.js`](https://github.com/Nutlope/hallmark/blob/main/site/js/main.js) consumes these tokens to handle theme switching.

### Can I use Hallmark without installing it into an AI editor?

Yes. The `site/` folder is a self-contained static website; you can open [`site/index.html`](https://github.com/Nutlope/hallmark/blob/main/site/index.html) directly in a browser or serve it with any static file server without ever touching the AI skill files under `skills/hallmark/`.