# gribouille-skill

Gist to go with <https://dailydrop.hrbrmstr.dev/2026/05/17/bonus-drop-116-2026-05-17-grammar-of-graphics-native-in-typst/>.

A Claude Code / OpenCode skill for generating [gribouille](https://m.canouil.dev/gribouille) charts in [Typst](https://typst.app), plus a working example.

## What's here

| File | Purpose |
|------|---------|
| `drop.typ` | Standalone example — a scatter plot of sensor fleet activity (log-log scales, annotations, size encoding) |
| `gribouille-skill/SKILL.md` | The agent skill definition with idiomatic gribouille patterns, anti-patterns, and a quick-reference |
| `gribouille-skill/references/geom-table.md` | Full parameter reference for geoms |
| `gribouille-skill/references/scale-table.md` | Full parameter reference for scales |

## Using the skill

The skill implements Wilkinson's Grammar of Graphics (same mental model as ggplot2 / plotnine) compiled natively in Typst.

### Quick start

1. Install gribouille from Typst Universe or clone it locally.
2. Clone `https://github.com/mcanouil/gribouille` into the directory where your doc is (until it's in the Universe)
3. Import the library:
   ```typst
   #import "./gribouille/lib.typ":*
   ```
4. Build a plot:
   ```typst
   #plot(
     data: penguins,
     mapping: aes(x: "flipper-len", y: "body-mass", colour: "species"),
     layers: (geom-point(size: 2pt),),
     theme: theme-minimal(),
     width: 12cm, height: 9cm,
   )
   ```

### Supported chart types

Scatter, line, area, bar, histogram, boxplot, heatmap, faceted small-multiples, multi-panel compositions, and more. See `gribouille-skill/SKILL.md` for the full chart-type decision table.

### Key conventions

- Column names in `aes()` must be **quoted strings**: `aes(x: "flipper-len")`.
- Always include `width:` and `height:` — gribouille has no default size.
- Use `as-factor("col")` for numeric-looking categorical strings.
- Use `typst("markup")` inside `labs()` when you need rich text.

## Example: `drop.typ`

`drop.typ` reads `src_ip_last1h.csv` and renders a log-log scatter of source-IP activity:

- **x**: total sessions (`scale-x-log10`)
- **y**: unique destination ports (`scale-y-log10`)
- **size**: number of unique sensors (`scale-size-area`)
- **annotation**: callout label for the dominant IP

Compile with:
```bash
typst compile drop.typ
```

## Resources

- [gribouille docs](https://m.canouil.dev/gribouille)
- [Typst docs](https://typst.app/docs)

## License

MIT