This notebook serves as the interactive reference and live component showcase for Web Awesome 3.14.0 and Font Awesome Free 6.5.2 within the SoftCloud architecture.
SoftCloud integrates Web Awesome via authentic Lit SSR Declarative Shadow DOM (DSD). Components are rendered statically on the server during the build, minimizing cumulative layout shift (Page CLS <= 0.1, Component CLS <= 0.01) and hydrating seamlessly in the browser. Authors can create components either programmatically in Python notebooks using the softcloud_ui.UI API or declaratively in MyST Markdown using native directives and roles.
import sys
from pathlib import Path
from IPython.display import display, HTML
# Locate repository root and import assets/python/softcloud_ui
root = Path.cwd().resolve()
while root.name and root.name != 'soft-cloud-dev':
if (root / 'assets' / 'python').is_dir():
break
root = root.parent
py_dir = root / 'assets' / 'python'
if str(py_dir) not in sys.path:
sys.path.insert(0, str(py_dir))
from softcloud_ui import UI, TrustedHTML
print("✓ SoftCloud UI API & Web Awesome Lit SSR runtime initialized.")✓ SoftCloud UI API & Web Awesome Lit SSR runtime initialized.
1. Choosing Components by User Intent (choosing-components)¶
When designing interactive technical documentation or laboratory notes, choose components based on user intent rather than visual styling alone:
| User Intent | Recommended Component | Allowed Variants / Options | Primary Use Case |
|---|---|---|---|
| System Status & Feedback | <wa-callout> | brand, neutral, success, warning, danger | Operational status, warnings, configuration caveats, test outcomes |
| Command & Navigation | <wa-button> | brand, neutral, success, warning, danger | Terminal actions, documentation links, script triggers, downloads |
| Structured Surface / Entity | <wa-card> | outlined, filled, accent, filled-outlined, plain | Server node specs, service dashboards, media previews, metric summaries |
| Semantic Iconography | <wa-icon> / Font Awesome | solid, regular, brands (FA 6.5.2) | Infrastructure icons, code symbols, security badges, brand logos |
Interface Parity: Python API vs. MyST Directives¶
Authors can author the exact same component using either Python or MyST Markdown:
Component | Python Notebook API | MyST Markdown Syntax |
|---|---|---|
Callout | | |
Button | | |
Card | | |
Icon | | |
Choose components based on author intent: callouts for alerts, buttons for actions, cards for surfaces, and icons for semantic cues.
# Python API Callout verification
display(UI.callout_text(
"All Web Awesome components in this notebook are transformed with authentic Lit Declarative "
"Shadow DOM (DSD). They render immediately before client JavaScript executes, ensuring minimal layout shift (Component CLS <= 0.01).",
title="SSR Architecture Active",
variant="brand",
appearance="filled-outlined"
))2. Web Awesome Core Component Reference (components/)¶
SoftCloud provides first-class SSR support for four core Web Awesome custom elements. Below are their specifications, allowed attributes, and interactive showcases.
2.1 Buttons (<wa-button>)¶
Buttons trigger actions or navigate to resources. They support distinct semantic variants, surface appearances, sizes, and shape modifications:
Variants:
brand(primary theme action),neutral(secondary action),success(confirmation/positive action),warning(cautionary action),danger(destructive action).Appearances:
filled(high contrast, default),accent,outlined(subtle border),filled-outlined,plain(ghost/flat button).Sizes:
xs,s,m(medium / default),l,xl. Compact size tokens ensure zero runtime console deprecations.Shapes & Modifiers:
pill(fully rounded caps),circle(equal aspect icon button),disabled(inaccessible state),loading(spinner state),caret(dropdown indicator).Navigation:
href(validated link URL) andtarget(_blank,_self; automatically enforcesrel="noopener noreferrer").
Documentation Home Portal
# Button variants showcase
variants = ["brand", "neutral", "success", "warning", "danger"]
for var in variants:
display(UI.button(f"{var.capitalize()} Action", variant=var, size="m"))# Button sizes, appearances, and pill modifiers
display(UI.button("Small Outlined", variant="brand", appearance="outlined", size="s"))
display(UI.button("Medium Filled Pill", variant="brand", pill=True, size="m"))
display(UI.button("Large Success Action", variant="success", size="l"))
display(UI.button("External Documentation", href="https://my.softcloud.dev/", variant="neutral", target="_blank"))2.2 Callouts (<wa-callout>)¶
Callouts highlight important notes, warnings, prerequisites, and status updates inline within prose or computational workflows:
Variants:
brand: General announcements, feature updates, architectural highlights.neutral: General notes, contextual background, tips.success: Completed operations, verified tests, system readiness.warning: Deprecations, prerequisites, resource constraints.danger: Critical errors, failure modes, security warnings.
Appearances:
accent,filled,outlined,filled-outlined,plain.Title Slot: Accessible header text announcing the callout purpose (rendered in default content slot).
All node telemetry, security policies, and health probes pass continuously with minimal layout shift.
# Callout variants showcase via Python UI helper
display(UI.callout_text(
"Production clusters use immutable OS images booted over ZFS root pools.",
title="Architecture Notice",
variant="brand",
appearance="filled-outlined"
))
display(UI.callout_text(
"All unit, integration, and security test suites completed with 100% pass rate.",
title="Verification Passed",
variant="success",
appearance="filled-outlined"
))
display(UI.callout_text(
"Rolling node restart requires migrating active KVM guests before draining.",
title="Maintenance Prerequisite",
variant="warning",
appearance="filled-outlined"
))
display(UI.callout_text(
"Authentication failure: kerberos ticket expired. Renew credentials via kinit.",
title="Security Alert",
variant="danger",
appearance="filled-outlined"
))
display(UI.callout_text(
"Configuration parameters can be tuned in /etc/softcloud/cluster.conf.",
title="Operational Tip",
variant="neutral",
appearance="filled-outlined"
))2.3 Cards (<wa-card>)¶
Cards are flexible, structured containers for grouping related information, system nodes, metrics, or media:
Appearances:
outlined(default, subtle 1px border),accent,filled,filled-outlined,plain.Named Slots:
header: Title or top action bar.media: Visual media (image or diagram) placed flush against top edge.default: Body content (paragraphs, metric lists, code).footer: Action buttons, metadata, or timestamps.
SoftCloud cluster hosts execute Linux and FreeBSD kernels with unified directory authentication and ZFS storage pools.
# Card with header, structured body, and footer via Python UI helper
display(UI.card_text(
"SoftCloud nodes run FreeBSD and Rocky Linux kernels with unified FreeIPA authentication. "
"Telemetry is collected at 5-second intervals via OpenTelemetry collectors.",
header="Compute Node: node-01.softcloud.dev",
footer="Status: Healthy | CPU: 12% | Memory: 4.2 / 32 GB",
appearance="filled-outlined"
))# Card composed with TrustedHTML including nested status badges
card_html = """
<div style="display: flex; justify-content: space-between; align-items: center; margin-bottom: 0.75rem;">
<span style="font-weight: 600; font-size: 1.1rem;">Cluster Storage Pool (ZFS)</span>
<span class="sc-wa-telemetry-status online">ONLINE</span>
</div>
<p style="margin: 0 0 0.75rem 0; color: var(--wa-color-text-quiet, #64748b);">Pool <code>tank-nvme</code>: 8x 3.84TB NVMe SSDs in RAIDZ2. Scrub completed with zero checksum errors.</p>
<div class="sc-wa-telemetry">
Capacity: 18.2 TB / 30.7 TB (59% allocated) • Free: 12.5 TB
</div>
"""
display(UI.card_trusted_html(
TrustedHTML(card_html),
header="Storage Telemetry",
appearance="outlined"
))3. Font Awesome 6.5.2 Icon Reference & Showcase¶
SoftCloud includes Font Awesome Free 6.5.2 self-hosted locally under vendor/fontawesome/. This provides over 2,000 vector icons across three core styles:
solid(fas): High-contrast filled icons for infrastructure, actions, hardware, and system status.regular(far): Outlined icons for subtle indicators and secondary UI controls.brands(fab): Authentic brand and technology marks for open-source software, cloud platforms, and operating systems.
Icon Roles & Syntax¶
Icons can be embedded in MyST Markdown or invoked via Python:
MyST Font Awesome Role:
{fa}solid serveror{fa}brands githubMyST Web Awesome Icon Role:
{icon}rocketPython UI Helper:
UI.icon("server", family="classic", variant="solid", label="Compute Server")orUI.icon_grid(items)
Inline examples in Markdown:
Server:
Terminal:
GitHub:
Rocket:
# Cloud & Systems Architecture Icons
cloud_icons = [
("server", "Compute Server"),
("cloud", "Cloud Network"),
("database", "Database Instance"),
("network-wired", "Ethernet / LAN"),
("cubes", "Container Cluster"),
("hard-drive", "ZFS Storage Pool"),
("microchip", "CPU Cores"),
("sitemap", "Network Topology"),
]
print("Cloud & Infrastructure Icons (Font Awesome Free 6.5.2 Solid):")
display(UI.icon_grid(cloud_icons, family="classic", variant="solid"))
Cloud & Infrastructure Icons (Font Awesome Free 6.5.2 Solid):
# DevOps, Code & Terminal Icons
devops_icons = [
("terminal", "CLI / Terminal"),
("code", "Source Code"),
("code-branch", "Git Branch"),
("laptop-code", "Development Workstation"),
("box-open", "Package Release"),
("gears", "System Configuration"),
("wrench", "Maintenance Tool"),
("file-code", "Script / Manifest"),
]
print("DevOps & Developer Tooling Icons:")
display(UI.icon_grid(devops_icons, family="classic", variant="solid"))
DevOps & Developer Tooling Icons:
# Security, Authentication & Status Icons
sec_icons = [
("shield-halved", "Firewall / Bastion"),
("lock", "TLS / SSL Encrypted"),
("key", "SSH / API Key"),
("user-shield", "FreeIPA Identity"),
("fingerprint", "Biometric Auth"),
("vault", "Secrets Vault"),
("circle-check", "Check Passed"),
("triangle-exclamation", "Alert / Caution"),
]
print("Security, Identity & Status Indicators:")
display(UI.icon_grid(sec_icons, family="classic", variant="solid"))
Security, Identity & Status Indicators:
# Open Source, OS & Brand Icons (brands style)
brand_icons = [
("github", "GitHub"),
("linux", "Linux"),
("python", "Python"),
("docker", "Docker"),
("rust", "Rust"),
("freebsd", "FreeBSD"),
("git-alt", "Git"),
("markdown", "MyST Markdown"),
]
print("Open Source Ecosystem Brands:")
display(UI.icon_grid(brand_icons, family="brands"))
Open Source Ecosystem Brands:
4. Design Tokens & CSS Utilities Reference (tokens/, utilities/)¶
Web Awesome is built on a design token architecture. CSS custom properties allow consistent spacing, color grading, shadows, and responsive typography across all components.
4.1 Design Token Reference¶
| Token Family | CSS Variable Pattern | Example Value | Description |
|---|---|---|---|
| Brand Colors | --wa-color-brand-{05-95} | var(--wa-color-brand-60) | Primary accent hue for interactive elements and brand accents |
| Neutral Grays | --wa-color-gray-{05-95} | var(--wa-color-gray-20) | Static neutral ramp (05 darkest to 95 lightest); use --wa-color-surface-* for theme-adaptive surfaces |
| Surfaces & Borders | --wa-color-surface-{default|raised|lowered|border} | var(--wa-color-surface-raised) | Theme-adaptive card backgrounds, surfaces, and structural borders |
| Semantic Colors | --wa-color-{success|warning|danger}-{60} | var(--wa-color-success-60) | State indicators for health, warnings, and errors |
| Text Contrast | --wa-color-text-{normal|quiet|link} | var(--wa-color-text-normal) | Accessible theme-adaptive text contrast hierarchy |
| Spacing Scale | --wa-space-{3xs|2xs|xs|s|m|l|xl|2xl|3xl} | var(--wa-space-m) (1.0rem) | Consistent margin, padding, and layout gap scale |
| Border Radius | --wa-border-radius-{s|m|l|pill|circle|square} | var(--wa-border-radius-m) (0.375rem) | Container corner rounding |
| Elevation / Shadow | --wa-shadow-{s|m|l} | var(--wa-shadow-m) | Depth layers for cards, menus, and overlays |
4.2 Utility CSS Classes¶
Web Awesome provides lightweight utility classes in styles/webawesome.css:
Typography:
.wa-color-text-quiet: Subdued secondary text for timestamps, descriptions, and labels..wa-color-text-normal: Standard body copy contrast..wa-color-text-link: Hyperlink accent text color..wa-prose: Typographic formatting wrapper for markdown articles.
Accessibility:
.wa-visually-hidden: Hides content visually while remaining fully accessible to screen readers.
Rounding Utilities:
.wa-border-radius-s,.wa-border-radius-m,.wa-border-radius-l,.wa-border-radius-pill.
# Demonstrating Web Awesome design tokens and utilities in custom markup
token_demo_html = """
<div style="border: 1px solid var(--wa-color-surface-border, #e4e5e9); border-radius: var(--wa-border-radius-l, 0.75rem); padding: var(--wa-space-l, 1.5rem); background: var(--wa-color-surface-raised, #ffffff); color: var(--wa-color-text-normal, #1b1d26); box-shadow: var(--wa-shadow-s, 0 1px 2px rgba(0, 0, 0, 0.08));">
<div style="display: flex; gap: var(--wa-space-s, 0.75rem); align-items: center; margin-bottom: var(--wa-space-xs, 0.5rem);">
<span aria-hidden="true" style="display: inline-block; width: 0.75rem; height: 0.75rem; border-radius: 9999px; background: var(--wa-color-brand-60, #2563eb);"></span>
<span class="wa-color-text-normal wa-font-weight-bold" style="font-size: 1.1rem; color: var(--wa-color-text-normal, #1b1d26);">Web Awesome Token Architecture</span>
</div>
<p class="wa-color-text-normal" style="margin: 0 0 var(--wa-space-s, 0.75rem) 0; color: var(--wa-color-text-normal, #1b1d26);">
Tokens provide consistent spacing (<code>--wa-space-*</code>), colors (<code>--wa-color-*</code>), and depth (<code>--wa-shadow-*</code>) that dynamically adapt between light and dark modes.
</p>
<div style="display: flex; gap: var(--wa-space-m, 1rem); flex-wrap: wrap;">
<span class="wa-color-text-quiet" style="font-size: 0.85rem; color: var(--wa-color-text-quiet, #545868);">• Border Radius: <code>var(--wa-border-radius-l)</code></span>
<span class="wa-color-text-quiet" style="font-size: 0.85rem; color: var(--wa-color-text-quiet, #545868);">• Spacing: <code>var(--wa-space-l)</code></span>
<span class="wa-color-text-quiet" style="font-size: 0.85rem; color: var(--wa-color-text-quiet, #545868);">• Shadow: <code>var(--wa-shadow-s)</code></span>
</div>
</div>
"""
display(UI.card_trusted_html(TrustedHTML(token_demo_html), appearance="plain"))5. Usage Patterns, Themes & Architecture (usage, themes)¶
5.1 Lit SSR & Declarative Shadow DOM (DSD) Lifecycle¶
In SoftCloud, Web Awesome web components follow a modern three-stage lifecycle:
Build-Time Transformation (
scripts/lit-ssr-transform.mjs): During site compilation, HTML placeholders produced by MyST directives and Jupyter notebook outputs are parsed usingparse5. The component render model generates custom elements and attaches<template shadowroot="open" shadowrootmode="open">containing the server-rendered template.Instant Paint (Page CLS <= 0.1, Component CLS <= 0.01): The browser immediately renders the component internals via native Declarative Shadow DOM before client-side scripts download or execute. There is no cumulative layout shift or flash of unstyled content.
Seamless Hydration (
webawesome.ssr-loader.js): The SSR autoloader adopts the existing shadow root without destroying or re-rendering the DOM tree, attaching event listeners and reactivity in place.
5.2 Theme Synchronization¶
SoftCloud’s softcloud-theme.js automatically coordinates theme state:
Matches MyST book-theme light and dark mode toggles.
Applies
.wa-dark/.wa-lightclasses to the<html>root element.Design tokens automatically remap contrast ratios, backgrounds, and text shades for optimal readability.
Theme synchronization operates synchronously via softcloud-theme.js without client hydration mismatch.
display(UI.callout_text(
"Theme synchronization operates synchronously via softcloud-theme.js. "
"Toggling between light and dark mode updates both MyST CSS variables and Web Awesome design tokens simultaneously.",
title="Theme Synchronization Operational",
variant="brand",
appearance="filled-outlined"
))6. Real-World Composite Showcase¶
Below are real-world composite UI patterns commonly used in SoftCloud laboratory and systems documentation.
6.1 Cluster Node Specification Card¶
A complete specification card combining icons, data metrics, status tags, and action buttons:
node_spec_html = """
<div style="display: flex; flex-direction: column; gap: 1rem;">
<div style="display: flex; justify-content: space-between; align-items: center; border-bottom: 1px solid var(--wa-color-surface-border, #e4e5e9); padding-bottom: 0.75rem;">
<div>
<div style="font-weight: 700; font-size: 1.2rem;">node-prod-04.infra.softcloud.dev</div>
<div class="wa-color-text-quiet" style="font-size: 0.85rem;">Rocky Linux 9.4 (Blue Onyx) • Kernel 5.14.0-427</div>
</div>
<span class="sc-wa-telemetry-status online">
ONLINE • HEALTHY
</span>
</div>
<div style="display: grid; grid-template-columns: repeat(auto-fit, minmax(180px, 1fr)); gap: 1rem;">
<div class="sc-wa-telemetry">
<div class="wa-color-text-quiet" style="font-size: 0.8rem; text-transform: uppercase;">Compute</div>
<div style="font-weight: 700; font-size: 1.1rem; margin-top: 0.2rem;">64 vCPUs (AMD EPYC)</div>
<div class="wa-color-text-quiet" style="font-size: 0.8rem;">Load: 0.42, 0.38, 0.35</div>
</div>
<div class="sc-wa-telemetry">
<div class="wa-color-text-quiet" style="font-size: 0.8rem; text-transform: uppercase;">Memory</div>
<div style="font-weight: 700; font-size: 1.1rem; margin-top: 0.2rem;">256 GB ECC DDR5</div>
<div class="wa-color-text-quiet" style="font-size: 0.8rem;">Allocated: 64.5 GB (25%)</div>
</div>
<div class="sc-wa-telemetry">
<div class="wa-color-text-quiet" style="font-size: 0.8rem; text-transform: uppercase;">Network</div>
<div style="font-weight: 700; font-size: 1.1rem; margin-top: 0.2rem;">2x 25 GbE LACP</div>
<div class="wa-color-text-quiet" style="font-size: 0.8rem;">RX: 1.2 Gbps • TX: 850 Mbps</div>
</div>
</div>
</div>
"""
display(UI.card_trusted_html(
TrustedHTML(node_spec_html),
header="System Telemetry & Resource Monitor",
footer="Last telemetry refresh: 10 seconds ago via FreeIPA SSO",
appearance="filled-outlined"
))6.2 Maintenance & Incident Action Banner¶
A high-priority alert callout paired with interactive action buttons:
Scheduled kernel live-patching will commence at 02:00 UTC. Workloads on node-prod-04 will be live-migrated to standby capacity automatically.
View Live Migration Runbook
display(UI.callout_text(
"Scheduled kernel live-patching will commence at 02:00 UTC. "
"Workloads on node-prod-04 will be live-migrated to standby capacity automatically.",
title="Scheduled Infrastructure Maintenance",
variant="warning",
appearance="filled-outlined"
))
display(UI.button("View Live Migration Runbook", href="https://my.softcloud.dev/", variant="brand", size="m"))print("✓ Web Awesome & Font Awesome computational reference and showcase executed successfully.")✓ Web Awesome & Font Awesome computational reference and showcase executed successfully.