This document describes the visual system, layout constraints, asset pipeline, and GRUB-specific decisions behind the SinLess theme. For build instructions, see DEVELOPMENT.md. For live installation and recovery, see INSTALL.md.
SinLess is designed to feel hostile and cyberpunk without sacrificing the one thing a bootloader must always preserve: readability.
The visual priorities are:
- Keep boot entries readable under firmware-level rendering constraints.
- Preserve the hooded biohazard character as the dominant identity.
- Use toxic green as an accent rather than flooding the entire screen.
- Maintain clear separation between branding, menu, timeout, and character.
- Use only features supported by the installed GRUB theme engine.
- Keep expensive visual effects in the build pipeline, not the bootloader.
The primary layout is authored for 1920×1080. GRUB theme components use percentage-based geometry so the composition scales with the selected graphics mode. GRUB is not a browser and does not provide true responsive layout, so the percentages are deliberately conservative.
The background uses desktop-image-scale-method: "stretch" to ensure complete
screen coverage. Critical text remains inside the left-side safe area, where the
background is darkest and least detailed.
The current geometry in theme/sinless/theme.txt is summarized below.
| Element | Left | Top | Width | Height | Purpose |
|---|---|---|---|---|---|
| SinLess logo box | 12% | 8% | 36% | 9% | Centered over the menu frame |
| Multiboot branding box | 12% | 18% | 36% | 3% | Centered over the menu frame |
| Menu frame | 4% | 26% | 52% | 50% | Visual container for entries |
| Boot menu | 8% | 30% | 43% | 39% | Text-safe entry region |
| Navigation hint 1 | 7% | 77% | 43% | 3% | Selection instructions |
| Navigation hint 2 | 7% | 81% | 43% | 3% | Boot instructions |
| Timeout label | 9% | 85% | 42% | 3% | Native GRUB seconds remaining |
| Progress bar | 9% | 89% | 42% | 4% | Native timeout progress |
| Version label | 77% | 94% | 20% | 4% | Bottom-right generated version |
| Hooded character | 52% | 10% | 48% | 81% | Foreground identity layer |
The boot-menu text ends at 51% of the screen width. The character begins at 52%, leaving a deliberate boundary between readable menu text and the character while still allowing the character to overlap the menu frame.
GRUB has limited image compositing capabilities, so most full-screen effects are
combined during scripts/build.sh.
The effective composition is:
- Authored background
- Green grunge
- Fine noise
- Left and right circuitry
- Particle splatter
- Vignette
- Branding
- Build-composited menu glow and frame
- Native boot-menu widget and text
- Navigation and timeout widgets
- Build-composited character glow and character
- Generated version label
Only the final assets needed by GRUB are copied into dist/sinless/. Heavy
full-screen overlay sources remain in the canonical source tree and are consumed
by the build.
GRUB image siblings do not always behave like a conventional HTML-style stacking
context. The declaration order in theme.txt has been verified against a real
GRUB framebuffer. Do not reorder the version and character image declarations
without rebuilding and visually testing the preview.
The canonical character is:
theme/sinless/assets/characters/hooded-character.png
There is intentionally no separate hooded-character-foreground.png. The
character is a high-resolution transparent PNG with solid white tooth faces and
black tooth separators.
assets/overlays/character-glow.png is generated around the exact alpha
silhouette. The build composites the glow beneath the character into one true
RGBA deployment image. This avoids GRUB renderer problems with indexed PNGs and
multiple live transparency layers.
The glow should remain a restrained edge halo. It must not become a solid neon outline or wash out the hood texture.
The menu frame is stored at:
theme/sinless/assets/menu/menu-frame.png
Its source glow is stored separately as assets/overlays/menu-frame-glow.png.
The build composites both into the deployed frame. The character is allowed to
pass visually in front of the frame, but the boot-menu text region never enters
the character bounds.
GRUB selected-item styling uses a nine-slice pixmap set under:
theme/sinless/assets/menu/selected/
The naming convention is required by GRUB:
selected_c.png selected_n.png selected_s.png
selected_e.png selected_w.png selected_ne.png
selected_nw.png selected_se.png selected_sw.png
The selected row uses a bright green surface with dark text for maximum contrast.
The timeout label and bar both use GRUB's reserved __timeout__ identifier.
GRUB supplies the live seconds value to:
Booting default entry in %d seconds
The label is a separate component above the progress bar. The bar itself has an empty text property so text never overlaps the fill.
The progress frame and fill live under assets/progress/. The fill contains
transparent internal padding and no external glow. Combined with:
highlight_overlay = "false"
this keeps every fill pixel inside the frame while the frame remains visible on
top. The fill is controlled by GRUB's actual timeout and must never be replaced
with a hardcoded duration in theme.txt.
The interface uses Share Tech Mono in GRUB PFF2 format:
theme/sinless/fonts/share-tech-mono-24.pf2
GRUB loads bitmap fonts by their internal name. Theme declarations therefore use:
Share Tech Mono Regular 24
The generated version label is an image because GRUB cannot bind an arbitrary configuration value to a theme label at runtime.
Canonical icons live under:
theme/sinless/assets/icons/
GRUB resolves icons from menu-entry classes such as ubuntu, windows,
gnu-linux, uefi-firmware, firmware, grub-terminal, and fallback.
The GRUB graphics menu hardcodes an icons/ lookup beside theme.txt; it does
not expose a configurable nested icon path. The build therefore creates this
deploy-only relative link:
dist/sinless/icons -> assets/icons
The canonical icon files are not duplicated in the source tree.
The canonical version setting is:
theme/sinless/config/version.txt
The build generates:
assets/generated/version/version-label.png
The visible final state is:
>| VERSION 1.0
GRUB 2.12 has no general animation timer, mutable theme label, or frame sequencer. A perpetual blinking cursor, one-shot typewriter animation, and a countdown delayed until that animation completes cannot be implemented honestly inside the theme engine. The static final label is the supported fallback.
The core palette is intentionally small:
| Role | Color |
|---|---|
| Base background | #020402 |
| Primary toxic green | #63FF00 |
| Progress fill | #58E600 |
| Primary text | #E6FFE7 |
| Dark selected text | #061006 |
| Dark progress background | #071007 |
Avoid adding bright colors behind text. Decorative green should be strongest at frame edges, character edges, and the outer background.
- No PNG may exist directly under
theme/sinless/. - Canonical PNGs belong under
theme/sinless/assets/. - Generated version assets belong under
assets/generated/version/. - Source overlays must be consumed by the build or removed.
- Do not add scanlines by default.
- Prefer true RGBA PNGs for GRUB-facing transparency.
- Do not add a second foreground-character copy.
dist/is generated output and must not be edited manually.
The preview must be checked at minimum at 1920×1080. Confirm that:
- All six expected preview entries are visible.
- Branding is centered over the menu frame.
- The character overlaps the frame without covering entry text.
- Teeth are solid white and separators remain black.
- The countdown is above the bar.
- Progress fill remains entirely inside the frame at partial and full states.
- The version label remains visible in the bottom-right corner.
- No transparent image renders as an opaque rectangle.
Use ./scripts/preview.sh --window for interactive inspection. The preview ISO
is isolated and does not modify the installed bootloader.