docs: Clean up section on UI definitions

docs: Clean up section on UI definitions

The current documentation is narrative, but it lacks examples and proper
formatting, which makes it harder to read and visually scan.

Let's split off paragraphs and sections, so they can be easily linkend,
and add a few examples for each description.