Design rule¶
Component selection hierarchy: (1) MyST built-ins for portable document structures; (2) existing typed SSR directives for wa-button, wa-card, wa-callout, and wa-icon (via {icon}/{fa}); (3) {anywidget} for interactive demonstrations or components without a typed directive; (4) reuse existing atomic components for composite patterns. A component demo may compose these primitives; do not add duplicate component frameworks or claim that a client-only widget has Lit SSR.
Component selection policy¶
| Author intent | Prefer | Web Awesome only when |
|---|---|---|
| Note, warning, hint, status prose | MyST {note}, {warning}, {admonition} | The callout is part of interactive app UI. |
| Static information tile | MyST {card} | Media slots and Web Awesome component behavior are required. |
| Responsive editorial grouping | MyST {grid}, {grid-item} | A runtime layout control is needed. |
| Alternative explanations or code samples | MyST {tab-set} / {tab-item} | Tabs are application controls with state and custom events. |
| Image/caption | MyST Markdown image or {figure} | Zoom, comparison, carousel, or motion controls are needed. |
| Links/paragraph/code tables | Native Markdown, roles, code fences | No Web Awesome replacement. |
| Static Web Awesome buttons, cards, callouts and icons | Typed {wa-button}, {wa-card}, {wa-callout} directives, {icon}/{fa} roles | Use the existing Lit SSR/DSD path instead of a widget for an ordinary static instance. |
| Interactive forms, menus, dialogs, toasts, sliders or bound state | Web Awesome in {anywidget} | Use the browser-hosted demo when a typed directive is unavailable or event/state handling is necessary. |
| Reused explanatory fragments | MyST {include} or {embed} | Reuse custom element atoms inside an interactive preview. |
| Executable research outputs | Jupyter notebook + MyST cross-references | Output must have a custom control. |
Documentation page contract¶
Follow the upstream Tab Group example: name, tag, version/availability, concise description, working example, usage variants, API (imports, slots, attributes/properties, events, CSS properties and parts, dependencies, SSR), accessibility, and source references. Distinguish confirmed APIs from planned enhancements; missing sections must not be invented. Individual atomic pages such as wa-tab link to their parent group without duplicating the entire parent API.
Each component page should include: a descriptive heading with the actual tag, official documentation and GitHub source links (with MyST’s transformer), an optional relevant background citation (not a mandatory generic Wikipedia definition), a Core/Pro availability marker, a live preview if licensed, a full copyable HTML snippet, a short MyST alternative where applicable, real example media with provenance, and inter-component dependencies.
Portable MyST layout first¶
No JavaScript or additional plugin API is needed for this card.
Use native MyST tabs for editorial explanations and snippet alternatives. The inner directive below is example source, shielded by a four-backtick code fence; the outer directives have distinct 5/4-colon delimiters.
:::{note}
Use this for publication notes.
:::<wa-tab-group active="media">
<wa-tab panel="media">Media</wa-tab>
<wa-tab-panel name="media">Interactive content</wa-tab-panel>
</wa-tab-group>Typed SSR/DSD and browser widgets have separate roles. Prefer this supported typed primitive for a server-rendered call to action:
:::{wa-button}
:variant: brand
:href: https://my.softcloud.dev/
Open SoftCloud
:::Use a widget for an interactive form or a live demonstration requiring browser-side state. Every widget preview must also publish static, semantic content and a complete source example outside the widget. This remains available when JavaScript is disabled or when scripts load but component initialization fails. A <noscript> message is not sufficient.
Browser-only component preview host: {anywidget}¶
The existing widgets/webawesome-demo.mjs consumes structured JSON and creates allowlisted DOM elements using document.createElement and document.createTextNode. The model is data, never raw or trusted HTML; it must reject event-handler attributes and non-HTTPS/dangerous URL schemes. Runtime assets and component modules are self-hosted, and the loader must not be duplicated. The showcase:filename.ext token below is demo-only data, not an HTML URL. The existing widget resolves it relative to its module URL to the self-hosted static/showcase assets for both root and prefixed deployments. In reusable HTML snippets, use ./images/filename.ext and replace it with the consuming application’s path. For published images use MyST relative image references; in reusable HTML examples use an application-supplied relative asset URL.
Static fallback:
. This image remains a normal MyST publication asset even if the widget import fails.
Example reusable atomic composition:
Copyable media markup and provenance¶
For standalone HTML, substitute a file shipped with the consuming application; ./images/rocket.jpg is a documented placeholder path, not a promise that the file exists in every deployment:
<img src="./images/rocket.jpg" alt="Falcon 9 rocket launch">Native documentation media and provenance¶
Use real self-hosted images with descriptive alt text, source credit and explicit licensing; prefer the shared Showcase media assets over text placeholders and externally hosted stock imagery. The actual sample photographs are reproducible inputs to screenshots and visual regression tests. The only allowlisted remote showcase media are https://shoelace.style/assets/images/walk.gif (animated-image example) and https://interactive-examples.mdn.mozilla.net/media/cc0-videos/flower.mp4 (native video example). CI must reject other remote media dependencies unless reviewed and added to this allowlist. The static reference and the copyable HTML example must remain readable independently of the widget’s lifecycle. Never present Pro components as executable without an installed Pro runtime.
Build and SSR boundaries¶
MyST parses Markdown, grids, cards, tabs, notes, and anywidget directives in locale-specific builds.
Existing staging copies
assets/static/showcasetostatic/showcaseunder the assembled HTML output; the widget resolvesshowcase:tokens without using domain-root URLs. Anywidget resolves local component modules from the self-hosted Web Awesome distribution.The existing Lit/parse5 post-processing pass handles the four typed Web Awesome SSR primitives; keep this contract stable and do not add SSR to all 90 catalog components.
Translation sources stay English-first; translations and narration must be regenerated through the existing per-locale workflows without translating JSON keys or HTML attribute names.
Verify the generated HTML for valid MyST layouts, loaded media, tab and carousel keyboard navigation, nonempty
alttext, expected local asset paths, and no console/network failures.
Practical composition recipes¶
The practical pattern library adapts the marketing, application UI, and ecommerce categories shown in Tailwind Plus into original MyST-first patterns. It does not copy proprietary Tailwind Plus component source and does not add a CSS framework; its examples deliberately combine real credited media, native editorial layouts, and the existing Web Awesome anywidget primitives.
Migration and acceptance plan¶
Source-of-truth versions: package.json for Web Awesome, requirements.lock for MyST/Jupyter Book, and components/catalog.json for component counts. This avoids stale numbers in prose. Status indicates implementation observed in source, not a claim that the deployed site has passed all gates.
| Phase | Status | Deliverable | Measurable acceptance |
|---|---|---|---|
| P0 | Implemented; rendered regression pending | Bundle and credit real media, with live anywidget examples. | Every local media URL resolves in a built site; the manifest records credit/license for every file; rendered examples contain real images. |
| P1 | Implemented; regression pending | Use MyST native notes, tabs, cards and grids for documentation prose. | Catalog status blocks use native directives, no duplicate layout API, no escaped example fences in output. |
| P2 | In progress | Generate version-matched API sections from the installed Web Awesome Custom Elements Manifest (CEM), with explicit Core/Pro/source-only boundaries. | Every supported Core tag has a CEM-matched attributes/events/slots/CSS-parts section or a documented manifest gap; generated sections are checked for drift in CI. |
| P3 | Partial | Strict locale builds, accessibility, link checking, browser, visual, and no-JS checks. | All enabled locales pass jupyter book build --html --strict; axe reports zero serious/critical violations on tested routes; link checks have zero broken required links; asset and no-JS tests pass; remote media requests are restricted to the documented GIF and MDN MP4 allowlist. |
No-JavaScript requirements¶
Client-only {anywidget} previews may not render without JavaScript. Every preview page must preserve readable text and a copyable source example outside the widget, plus a static semantic fallback where essential content would otherwise be unavailable. The existing typed SSR primitives retain their own tested DSD/no-JS path. The rendered HTML, not just Markdown source, must be checked for code fence leakage and for static alternatives when widget imports fail.
Not in scope¶
No copying proprietary Web Awesome Pro code, not turning Markdown paragraphs into custom elements, no new client framework, no fake SSR for anywidget, no dynamic download of media during deterministic build.