# Nutlope/hallmark Project Structure: Key Components of the Root Folder Explained

> Explore the Nutlope/hallmark project structure. Understand the 10 key root folder components for installing, running, and deploying this AI design skill.

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

---

**The Nutlope/hallmark repository root contains 10 essential components—configuration files, documentation, skill definitions, and a static demo site—that enable installation, execution, and deployment of this AI-powered design skill.**

The **Nutlope/hallmark** project is an open-source design skill for AI coding assistants. Understanding its root folder structure is essential for contributors, integrators, and developers who want to extend or deploy the skill. This guide breaks down each component with direct references to source files.

## Core Configuration Files

### package.json: npm Metadata and Scripts

The [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) file defines the package name, version, entry point, and supported harnesses. It also includes a lightweight development server for local demo testing.

```json
// From package.json
{
  "name": "hallmark",
  "version": "1.0.0",
  "scripts": {
    "serve": "npx serve site -p 4173"
  }
}

```

Run the local server with:

```bash
npm run serve

# Opens at http://localhost:4173

```

### vercel.json: Deployment Configuration

The [`vercel.json`](https://github.com/Nutlope/hallmark/blob/main/vercel.json) file configures Vercel deployments for the live demo at `usehallmark.com`. It handles routing and build settings for the static site.

## Documentation and Legal Files

### README.md: Project Overview and Installation

[`README.md`](https://github.com/Nutlope/hallmark/blob/main/README.md) provides the high-level introduction, explains the **four hallmark verbs** (`build`, `audit`, `redesign`, `study`), displays example screenshots, and gives the install command:

```bash
npx skills add nutlope/hallmark

```

### LICENSE: MIT License

The `LICENSE` file contains the MIT license text governing reuse and distribution.

### ROADMAP.md: Future Development Plans

[`ROADMAP.md`](https://github.com/Nutlope/hallmark/blob/main/ROADMAP.md) outlines upcoming features and the long-term vision for the skill's capabilities.

## The Skill Implementation: skills/hallmark/

The `skills/hallmark/` folder is the **heart of the project**. It contains everything AI assistants consume when the skill is invoked.

### SKILL.md: Core Rule Set

[`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) defines the behavioral rules that drive Claude Code, Cursor, and Codex when processing design tasks.

### references/: Design Reference Library

The `skills/hallmark/references/` subdirectory holds detailed documentation on:

- **Themes** — predefined visual systems
- **Typography** — font pairing and scale guidelines
- **Macros** — reusable design patterns

These files are parsed by AI harnesses to ground their output in consistent design principles.

## Demo and Testing: site/

The `site/` folder powers the production demo. It contains:

| Subfolder | Contents |
|-----------|----------|
| [`index.html`](https://github.com/Nutlope/hallmark/blob/main/index.html) | Landing page with interactive examples |
| Global CSS/JS | Styling and behavior for the live preview |
| `site/_tests/` | Example pages demonstrating skill outputs |

The site is deployed via Vercel and reachable at `usehallmark.com`.

## Supplementary Documentation: docs/

The `docs/` folder contains extended guides:

- [`docs/recipes.md`](https://github.com/Nutlope/hallmark/blob/main/docs/recipes.md) — Practical walkthroughs for common use cases
- [`docs/study-examples.md`](https://github.com/Nutlope/hallmark/blob/main/docs/study-examples.md) — Sample outputs from the `study` verb for design DNA extraction
- Additional slide decks and reference materials

## Version Control: .gitignore

The `.gitignore` file excludes `node_modules/`, build artifacts, and environment files from commits.

## Summary

- **Configuration**: [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json) and [`vercel.json`](https://github.com/Nutlope/hallmark/blob/main/vercel.json) handle metadata and deployment
- **Documentation**: [`README.md`](https://github.com/Nutlope/hallmark/blob/main/README.md), [`ROADMAP.md`](https://github.com/Nutlope/hallmark/blob/main/ROADMAP.md), and `docs/` provide usage guidance
- **Skill core**: [`skills/hallmark/SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/skills/hallmark/SKILL.md) and `references/` define AI behavior
- **Demo site**: `site/` serves the live preview with test examples
- **Legal**: `LICENSE` permits open reuse under MIT terms

## Frequently Asked Questions

### What is the purpose of the skills/hallmark/ folder?

The `skills/hallmark/` folder contains the rule set and reference materials that AI coding assistants consume. The [`SKILL.md`](https://github.com/Nutlope/hallmark/blob/main/SKILL.md) file defines behavior, while `references/` provides design system documentation for themes, typography, and macros.

### How do I run the hallmark demo locally?

Execute `npm run serve` from the root directory. This starts a server on port 4173 using the script defined in [`package.json`](https://github.com/Nutlope/hallmark/blob/main/package.json), serving the static files from the `site/` folder.

### What are the four hallmark verbs?

According to [`README.md`](https://github.com/Nutlope/hallmark/blob/main/README.md), the four verbs are: **build** (create from brief), **audit** (review existing code), **redesign** (refresh while preserving structure), and **study** (extract design DNA from screenshots or URLs).

### Where can I find examples of hallmark outputs?

Example pages live in `site/_tests/`, and detailed study outputs are documented in [`docs/study-examples.md`](https://github.com/Nutlope/hallmark/blob/main/docs/study-examples.md). These demonstrate real-world results from each verb.