document the UI elements and how to style them

1 files changed, 63 insertions, 0 deletions

diff --git a/docs/modules/ROOT/pages/style-guide.adoc b/docs/modules/ROOT/pages/style-guide.adoc
index 11e5831..fc69f67 100644
--- a/docs/modules/ROOT/pages/style-guide.adoc
+++ b/docs/modules/ROOT/pages/style-guide.adoc
@@ -5,6 +5,7 @@ endif::[]
 // Settings:
 :idprefix:
 :idseparator: -
+:experimental:
 
 When creating a UI theme for Antora, there are certain elements in the UI that require support from the CSS to work correctly.
 This list includes elements in the shell (i.e., frame) and in the document content.
@@ -87,3 +88,65 @@ Here's how it might appear:
 
 * [ ] todo
 * [*] done!
+
+=== UI Elements
+
+Asciidoctor supports three UI element representations out of the box, which are made from corresponding inline UI macros.
+
+* keybinding (kbd macro)
+* button (btn macro)
+* menu (menu macro)
+
+The UI elements are output using semantic HTML elements, so they inherit some default styling from the browser.
+However, to look proper, they require some additional styling.
+
+==== Keybinding
+
+A keybinding can be a single key (`+kbd:[F11]+`) or a sequence of keys (`+kbd:[Ctrl+F]`).
+Here's the HTML that's generated for these two forms.
+
+[source,html]
+----
+<kbd>F11</kbd>
+<span class="keyseq"><kbd>Ctrl</kbd>+<kbd>F</kbd></span>
+----
+
+Here's how these might appear:
+
+[%hardbreaks]
+kbd:[F11]
+kbd:[Ctrl+F]
+
+==== Button
+
+A button is meant to represent an on-screen button (`+btn:[Save]+`).
+However, it should not appear like an actual button as that could confuse the reader into thinking it's interactive.
+Therefore, a button is rendered as a bold text by default:
+
+[source,html]
+----
+<b class="button">Save</b>
+----
+
+Traditionally, a button reference is styled by surrounding the text with square brackets, as shown here:
+
+btn:[Save]
+
+==== Menu
+
+A menu can be a top-level menu reference (`+menu:File[]+`) or a nested selection (`+menu:File[Save]+`).
+Here's the HTML that's generated for these two forms.
+
+[source,html]
+----
+<b class="menuref">File</b>
+<span class="menuseq"><b class="menu">File</b>&#160;<b class="caret">&#8250;</b> <b class="menuitem">Save</b></span>
+----
+
+This might be rendered as:
+
+[%hardbreaks]
+menu:File[]
+menu:File[Save]
+
+The default styling applied to a menu reference is usually sufficient.