start a style guide; document the checklist

1 files changed, 54 insertions, 0 deletions

diff --git a/docs/modules/ROOT/pages/style-guide.adoc b/docs/modules/ROOT/pages/style-guide.adoc
new file mode 100644
index 0000000..6eef7ea
--- /dev/null
+++ b/docs/modules/ROOT/pages/style-guide.adoc
@@ -0,0 +1,54 @@
+= Style Guide
+ifndef::env-site,env-github[]
+include::_attributes.adoc[]
+endif::[]
+// Settings:
+:idprefix:
+:idseparator: -
+
+When creating a UI theme for Antora, there are certain elements in UI that require the support for CSS to work correctly.
+This list includes elements in the shell (i.e., frame) and in the document content.
+This document identifies these UI elements.
+
+== UI Shell
+
+TODO
+
+== Document Content
+
+The HTML in the main content area is generated from AsciiDoc using Asciidoctor.
+AsciiDoc has numerous content elements that require assistance from CSS to render properly.
+
+=== Checklists
+
+A checklist is an unordered list with items that are prefixed with a checkbox marker (checked or unchecked).
+Here's an example of AsciiDoc source that produces a checklist:
+
+[source,asciidoc]
+----
+* [ ] todo
+* [x] done!
+----
+
+If font-based icons are enabled (i.e., `icons=font`), the checkbox gets inserted as the first element of the paragraph element that contains the list item text.
+
+[source,html]
+----
+<div class="ulist checklist">
+<ul class="checklist">
+<li>
+<p><i class="fa fa-square-o"> todo</p>
+</li>
+<li>
+<p><i class="fa fa-check-square-o"> done!</p>
+</li>
+</ul>
+</div>
+----
+
+The recommended approach is to hide the list markers (i.e., `list-style: none`), then add a checkbox glyph on the icon element using either a background image or a before pseudo element.
+
+Here's how it might appear:
+
+* [ ] todo
+* [*] done!