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.

Practical UI Patterns: MyST + Web Awesome

This is a pattern library for building publication pages and interactive examples. It draws on the categories in Tailwind Plus UI Blocks (marketing sections, application UI, and e-commerce patterns), not on proprietary Tailwind Plus markup or code. The components below are original SoftCloud examples; they run on the existing MyST / Web Awesome stack without introducing a Tailwind dependency.

1. Marketing hero and feature story

A landing page needs a strong hierarchy, real imagery, a descriptive call to action, and responsive layout; it does not need a JavaScript component to position content. Use a native MyST grid and a normal link.

Publish reproducible infrastructure research

Document architecture, publish computational evidence, and maintain multilingual reference material in a deterministic build.

Explore the component catalog · Review the publishing platform

Research in context
Falcon 9 carrying the DSCOVR spacecraft into flight

Credit: SpaceX / DSCOVR launch photograph (distributed through scikit-image). License: public-domain designation recorded in the media manifest; original rights confirmation remains pending.

Why MyST: portable reading order, working Markdown links, normal image fallback, and responsive columns without custom components. A Web Awesome <wa-carousel> is appropriate only if multiple slides and navigation are actually necessary.

2. Bento-like capability grid

Tailwind Plus catalogs bento grids, feature sections, and statistics layouts. A MyST grid with cards expresses the same information architecture while remaining suitable for other MyST outputs.

Reproducibility

Lock dependencies, verify build inputs, and preserve source provenance.

Architecture reference

Interactive controls

Use Web Awesome wa-button, wa-dialog, wa-copy-button, and form controls through the self-hosted widget integration.

Button · Copy Button

Actual media

Images, comparisons, and carousels use real, credited media. Ordinary figures remain native MyST.

Real-media gallery

Do not use utility classes as a substitute for semantic elements or use decorative badges for data that should be text. A dense application bento may add project-scoped CSS once the native layout becomes insufficient.

3. Application UI: an actionable operations tile

A dashboard can combine a native explanatory card with a Web Awesome action, without converting the entire documentation page to web components.

Diagnostics reference

This example is a demonstration, not a live infrastructure status. The button copies a reproducible diagnostic command. Static fallback: Open SoftCloud and the copyable command kubectl get nodes -o wide remain available if component imports fail.

Atomic reuse: wa-button provides navigation; wa-copy-button handles clipboard interaction. The MyST {card} above provides the document context. Never register a second button, card, or copy-button implementation for the same need.

4. Documentation tabs versus application tabs

Use native MyST tabs for alternative explanations and code listings.

Shell
API
kubectl get nodes -o wide

Use a Web Awesome <wa-tab-group> for application state, custom tab placement, dynamic panel selection, or event-driven interaction. The Tab Group, Tab, and Tab Panel pages demonstrate that interaction with actual photographs. Do not restyle MyST documentation tabs as Web Awesome just because the visual treatment is similar.

5. Photo cards, galleries, and comparison views

Media is part of a realistic component recipe, not a text-only placeholder.

Space exploration
Hubble eXtreme Deep Field showing distant galaxies

Credit: NASA / Hubble eXtreme Deep Field. License: public domain (media manifest). Use native MyST cards and images for editorial content.

Coffee and texture
White porcelain coffee cup photographed on a wooden table

Credit: Rachel Michetti / Pikolo Espresso Bar. License: CC0 (media manifest). Use image captions and alternate text even in promotional layouts.

For interaction, use Carousel for controlled slides, Comparison for a draggable synchronized split, Zoomable Frame for a bounded page preview, and Animated Image for motion playback controls. These are not MyST card replacements.

6. Tailwind utility classes as an optional supplement

An application that already compiles Tailwind may use its utility vocabulary for responsive spacing, widths, and alignment, while leaving behavior to Web Awesome. This snippet is a conceptual frontend integration example, not executed by this Jupyter Book site:

<section class="mx-auto grid max-w-6xl grid-cols-1 gap-6 p-6 lg:grid-cols-3">
  <article class="rounded-xl border p-6">
    <h2 class="text-xl font-semibold">Reproducible builds</h2>
    <p>Validate configuration before publishing.</p>
    <wa-button variant="brand" href="/architecture">Architecture</wa-button>
  </article>
</section>

Do not add a Tailwind runtime solely for these examples. Without a separately built Tailwind stylesheet, utility classes in that block have no styling effect. Where the output must remain portable to PDF, print, JATS, or non-HTML MyST renderers, prefer MyST’s native structural directives. When custom CSS is necessary, use scoped classes and Web Awesome design tokens rather than relying on undocumented internal Shadow DOM.

Component selection matrix

Tailwind-style patternMyST-first implementationAdd Web Awesome when
Hero, features, bento, logo cloud, statisticsHeadings, grid, cards, imagesAn action, carousel, or dynamic display is required
FAQ, notice, release notesAdmonition, heading, list, native tabsDetails need stateful disclosure or application-specific behavior
Pricing or feature comparison{list-table}, Pipe Tables, {grid} + SSR {wa-card}, {wa-button}User-selectable configuration (wa-slider, wa-switch, wa-radio-group) affects the content
Application dashboardGrid, tables, figures, cardsFilters, tabs, sorting, dialogs, copy actions, or forms are required
Gallery / media storyImages, figures, captions, gridControlled carousel, comparison slider, or pan/zoom behavior is required
Forms / application shellNarrative structure in MySTActual controls, validation, and events must execute in the browser

Accessibility and verification

Every recipe must remain understandable with JavaScript unavailable (static text and images survive); use real, provenance-recorded media; give interactive controls discernible labels; preserve keyboard focus and logical reading order; test responsive widths and reduced-motion behavior where relevant; and validate local asset URLs under both root and prefixed deployments. The Web Awesome {anywidget} previews hydrate on the client; they are not automatically Lit SSR output.

Further reading: Authoring standard, Migration plan, Real-media sources, Tailwind Plus categories, and MyST grid/card/tab syntax.