Skip to article frontmatterSkip to article content
Site not loading correctly?

This may be due to an incorrect BASE_URL configuration. See the MyST Documentation for reference.

Web Awesome & Font Awesome Reference & Showcase

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.

✓ 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 IntentRecommended ComponentAllowed Variants / OptionsPrimary Use Case
System Status & Feedback<wa-callout>brand, neutral, success, warning, dangerOperational status, warnings, configuration caveats, test outcomes
Command & Navigation<wa-button>brand, neutral, success, warning, dangerTerminal actions, documentation links, script triggers, downloads
Structured Surface / Entity<wa-card>outlined, filled, accent, filled-outlined, plainServer node specs, service dashboards, media previews, metric summaries
Semantic Iconography<wa-icon> / Font Awesomesolid, 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

UI.callout_text(
    text,
    title=...,
    variant=...,
)
```{wa-callout} Title
:variant: brand
Content...
```

Button

UI.button(
    label,
    href=...,
    variant=...,
)
```{wa-button} https://link
:variant: brand
Button Label
```

Card

UI.card_text(
    text,
    header=...,
    appearance=...,
)
```{wa-card} Card Header
:appearance: filled-outlined
Content...
```

Icon

UI.icon(
    name,
    family=...,
    variant=...,
)
{fa}`solid server`
{icon}`rocket`
Loading...

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) and target (_blank, _self; automatically enforces rel="noopener noreferrer").

Documentation Home Portal

Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...
Loading...

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).

Loading...
Loading...
Loading...
Loading...
Loading...

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.

Host Specification

SoftCloud cluster hosts execute Linux and FreeBSD kernels with unified directory authentication and ZFS storage pools.

FreeIPA Kerberos SSO Enabled
Loading...
Loading...

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 server or {fa} brands github

  • MyST Web Awesome Icon Role: {icon} rocket

  • Python UI Helper: UI.icon("server", family="classic", variant="solid", label="Compute Server") or UI.icon_grid(items)

Inline examples in Markdown:

  • Server:

  • Terminal:

  • GitHub:

  • Rocket:

Cloud & Infrastructure Icons (Font Awesome Free 6.5.2 Solid):
Loading...
DevOps & Developer Tooling Icons:
Loading...
Security, Identity & Status Indicators:
Loading...
Open Source Ecosystem Brands:
Loading...

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 FamilyCSS Variable PatternExample ValueDescription
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.

Loading...

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:

  1. Build-Time Transformation (scripts/lit-ssr-transform.mjs): During site compilation, HTML placeholders produced by MyST directives and Jupyter notebook outputs are parsed using parse5. The component render model generates custom elements and attaches <template shadowroot="open" shadowrootmode="open"> containing the server-rendered template.

  2. 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.

  3. 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-light classes to the <html> root element.

  • Design tokens automatically remap contrast ratios, backgrounds, and text shades for optimal readability.

Loading...

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:

Loading...

6.2 Maintenance & Incident Action Banner

A high-priority alert callout paired with interactive action buttons:

View Live Migration Runbook

Loading...
Loading...
✓ Web Awesome & Font Awesome computational reference and showcase executed successfully.