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:

# 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:

[@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:

# Contrast

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

Compare a dark heading with a pale one.

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

[@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.
`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:

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

Omitting type uses the authoring Source's type. Ordinary Source links and Graph already use the shared type presentation. Map edits update affected live views.

The site's documentation vocabulary is a complete example.