[@layout]: ../docs.layout.md

# Maps and type vocabulary

A Map gives your Source types shared labels, descriptions, icons, and colors.
Types still come from filenames such as `contrast.lesson.md`; a Map describes
how those types appear in links, previews, and graphs.

---

## Define and activate a Map

Create `paths/course.map.md` with one type definition per Block:

````md
# Course vocabulary

---

# Lesson

A short explanation with an activity to try.

```yaml
type: lesson
icon: clipboard-list
color: blue
```

---

# Exercise

A task to practice what you learned.

```yaml
type: exercise
icon: pencil
color: emerald
```
````

Activate it from the root `paths/index.md`:

```md
[@map Course vocabulary]: ./course.map.md
```

The reference must name one exact `.map.md` file. Only the root route Source
installs Maps, and the Map must be readable everywhere that root is readable.
Opening the Map itself shows a rendered preview beside each definition.

---

## See the vocabulary on a lesson

Create `paths/contrast.lesson.md`:

```md
# Contrast

<x-map-type type="lesson" />

Compare a dark heading with a pale one.
```

After the Map activation in `paths/index.md`, add:

```md
[@link.card](./contrast.lesson.md)
```

Run `bun run dev`. The home card shows Contrast with the Lesson label and blue
clipboard-list icon. Open `/contrast.lesson` to see the same type explicitly.
Change the Lesson label or color in the Map and save; both consumers update.

---

## Type presentation

| Field | Meaning |
| --- | --- |
| `type` | Lowercase type identifier, such as `lesson` or `exercise`. |
| `label` | Display name; defaults to the Block's heading. |
| `description` | Explanation; defaults to the Block's derived description. |
| `icon` | An icon name from the [Core catalog](../site/ui.reference.md#icon-catalog). |
| `color` | A named accent from the palette below. |

Colors are `slate`, `blue`, `violet`, `purple`, `emerald`, `teal`, `cyan`,
`yellow`, `amber`, `orange`, `red`, and `rose`. They adapt to light and dark
schemes. `bun run pmx lint` reports unknown fields, colors, and icons, and
duplicate types within a Map.

Multiple root Map references compose in authored order; later definitions
replace the fields they supply. Authored fields override the type's Plugin
presentation. A Map changes presentation; a Plugin supplies validation and behavior.

---

## Show a type explicitly

Where a type label helps readers, use:

```md
<x-map-type type="lesson" />
```

Omitting `type` uses the authoring Source's type. Ordinary Source links and
[Graph](../site/graph.reference.md) already use the shared type presentation.
Map edits update affected live views.

The site's [documentation vocabulary](../docs.map.md) is a complete example.