Annotations & Footnotes
GospeLib's annotation system combines a rich doctrinal highlight taxonomy with a layered rendering approach, supporting scholarly footnotes and personal notes without visual clutter.
Annotation Layer Architecture
Four visual layers render independently. When multiple layers overlap on the same verse, they compose visually:
| Layer | Visual Treatment | Z-Order | Purpose |
|---|---|---|---|
| Wash | Background fill at 0.18 opacity | Bottom | Default highlight — fills behind the text |
| Underline | Colored underline below text baseline | Above wash | Alternative highlight mode — text stays uncolored |
| Text | Text color changes to highlight color | Above underline | Strong emphasis — entire verse appears in highlight color |
| Outline | Colored 1.5px border around verse block | Top | Box/outline mode — subtle structural call-out |
Layer Compositing
When two different doctrinal colors overlap on the same passage:
- Washes blend — the visual intersection creates a third color, signaling a doctrinal intersection (e.g., Yellow + Purple → warm mauve, meaning Atonement + Priesthood)
- Underlines stack — multiple underlines appear at slightly offset positions
- Text mode — last-applied color wins (the user can reorder)
- Outline — multiple outlines nest
Margin Indicators
When a verse has annotations, a small indicator appears in the left margin:
| Indicator | Meaning |
|---|---|
| Colored dot | Highlight applied (color matches the highlight) |
| Pencil icon | Personal note attached |
| Chain link | Cross-references linked |
| Multiple dots | Multiple overlapping annotations |
Margin indicators are tappable — opening the relevant annotation panel.
Highlight Color Picker
The highlight color picker appears as part of the floating toolbar or standalone from the study toolbar.
Layout
Two rows of color swatches:
Row 1 — Doctrinal Colors (8 colors): See Colors: Doctrinal Color Taxonomy for the full list. Each swatch shows the color at full opacity with the doctrinal label below.
Row 2 — Personal Colors (4 pastel colors): See Colors: Personal Highlight Colors. Labeled "My Colors."
Below the color rows:
| Control | Function |
|---|---|
| Mode selector | Toggle between Wash / Underline / Text / Outline |
| Eraser | Remove highlight from selected passage |
| Expand | Open full annotation details panel |
Long-Press Color Swatch
Long-pressing any doctrinal color swatch reveals the doctrinal domain description and a "Customize mapping" link to remap the color to a different theme.
Note Cards
When a user attaches a personal note to a verse, the note renders as a card:
Note Card Anatomy
| Element | Styling |
|---|---|
| Container | Paper surface, radius.lg (12px), elevation 2 |
| Background | tan-50 — subtly warmer than page |
| Leading accent | 3px left border in the verse's highlight color |
| Header | Verse reference + timestamp in font.size.sm |
| Body | User text in font.family.scripture (Gentium Plus) |
| Footer | Edit / Delete / Share actions |
Note cards appear inline below the annotated verse in study mode, or collected in the note panel.
Footnote System
Footnote Display Modes
Four modes controlling when and how footnotes appear:
| Mode | Behavior | Audience |
|---|---|---|
| A — Hidden | No footnote indicators | Casual reading |
| B — Indicators Only | Superscript letters appear; tap to expand | Default |
| C — Tooltip | Hover/long-press previews content inline | Study |
| D — Expanded | All footnotes visible below each verse | Deep study |
Footnote Types
Each footnote type has distinct visual coding:
| Type | Badge Color | Icon | Content |
|---|---|---|---|
| Cross-reference | color.semantic.crossReference | Chain link | Link to related passage |
| JST | Purple | Scroll | Joseph Smith Translation alternate reading |
| Hebrew/Greek | Gold | H/G badge | Original language clarification |
| Topical Guide | Green | Topic bubble | Link to topical guide entry |
| Bible Dictionary | Blue | Book | Link to Bible Dictionary entry |
| Commentary | Gray | Quote | Scholarly commentary excerpt |
Footnote Card Anatomy
When a footnote is expanded (modes C or D):
| Element | Styling |
|---|---|
| Container | Chrome surface, elevation 1, radius.md (8px) |
| Type badge | Colored pill with icon + type label |
| Content | Footnote text in font.size.sm |
| Action | "Go to passage" for cross-refs, "See full entry" for TG/BD |
| Dismiss | Tap outside or swipe away |
Annotation Data Model
Annotations are stored per-user and synced across devices:
- Highlights: passage range + color + mode (wash/underline/text/outline)
- Notes: passage range + rich text + optional highlight binding
- Bookmarks: passage point + optional label + optional collection assignment
- Tags: user-defined labels that can be applied to any annotation
Related Pages
- Colors — doctrinal taxonomy and personal color palettes
- Reader Experience — gesture suite and action ring
- Study Tools — study journal and collections
- Loading & Empty States — error states for sync failures