> ## Documentation Index
> Fetch the complete documentation index at: https://docs.graphy.dev/llms.txt
> Use this file to discover all available pages before exploring further.

# Annotations & emphasis

Graphy gives you three composable tools for directing attention, all piped into the [spec](/sdk-next/concepts/how-a-chart-is-built) alongside your geoms and scales.

## Three ways to draw attention

| Tool                | Builder        | What it does                                                                                    |
| ------------------- | -------------- | ----------------------------------------------------------------------------------------------- |
| **Highlights**      | `highlight()`  | De-emphasise everything that *doesn't* match a predicate, so the matched observations stand out |
| **Reference lines** | `geom.rule()`  | Draw a constant line — a goal, threshold, or baseline — that the scale grows to fit             |
| **Annotations**     | `annotation.*` | Layer callouts on top of the plot: difference arrows, shaded regions, text, arrows, and more    |

Each is a spec feature, so it composes left-to-right in `pipe` like any geom or scale, and re-resolves on every compile — annotations track the data they're pinned to, and rules extend the axis domain.

```tsx theme={null}
pipe(
  createSpec({ x: 'month', y: 'revenue', color: 'region' }),
  geom.line(),
  scale.x.discrete(),
  scale.y(),
  scale.color.palette(),
  highlight({ variable: 'region', eq: 'EU' }), // emphasis
  geom.rule({ aes: { y: { value: 2500 } }, params: { label: 'Target' } }), // reference line
  annotation.shape({
    region: { anchorType: 'panel', x: 0.75, y: 0, width: 0.25, height: 1 },
    fillColor: '#e15759',
    fillOpacity: 0.1,
  }) // callout
);
```

<CardGroup cols={3}>
  <Card title="Highlights" icon="highlighter" href="/sdk-next/emphasis/highlights">
    Predicate-driven emphasis: pick observations, series, or a whole x-slice.
  </Card>

  <Card title="Reference lines" icon="ruler-horizontal" href="/sdk-next/emphasis/reference-lines">
    Goal lines, thresholds, and baselines with `geom.rule()`.
  </Card>

  <Card title="Annotations" icon="comment" href="/sdk-next/emphasis/annotations">
    Difference arrows, shaded regions, text, and pinned dots.
  </Card>
</CardGroup>

## Highlight vs. annotation vs. reference line

They overlap in spirit but differ in mechanism:

* Reach for a **highlight** when the emphasis is *about the data* — "show me the EU series," "dim everything below target." The predicate selects real observations, so it survives data changes and re-sorts.
* Reach for a **reference line** when you're marking a *constant value* the data should be read against — a sales goal, a capacity ceiling, a zero baseline.
* Reach for an **annotation** when you're adding a *layer the data doesn't contain* — a label explaining a spike, an arrow between two points, a shaded "forecast" band.