I have some tips / information based on trial and error that I think could help extend this section a little bit.

Firstly, in this part, you say:

'If you were adding a new action icon it would go in /usr/share/icons/hicolor/scalable/actions'

However, this is only good if you're using default icons, and is no good if you have a theme set that's not hicolor.

A better way (to the best of my knowledge) to explain using symbolic icons would be that it will look for an svg matching the
specified svg name, in the currently set theme, so if you have for example a custon svg you want for a button, and your theme is Yaru, you would copy your svg to /usr/share/icons/Yaru/scalable/actions, than reference its name.

You can also replace a button other than a header bar one with an image with set_icon_name.
Adwaita has 'Adw.ButtonContent for adding an icon next to a label, which may also be worth looking into adding if interested.
I hope this was helpful.