Problem/Motivation
As it is now, Styleguide by default shows the HTML tags <figure> and <figcaption> in isolation (as if they were inline tags, like <strong>) and with text:
$items['figcaption'] = array(
'title' => $this->t('Figcaption'),
'content' => [
'#type' => 'inline_template',
'#template' => '{{ pre }} <figcaption>{{ figcaption }}</figcaption> {{ post }}.',
'#context' => [
'pre' => $this->generator->words(3, 'ucfirst'),
'figcaption' => $this->generator->words(3),
'post' => $this->generator->words(4),
],
],
);
$items['figure'] = array(
'title' => $this->t('Figure'),
'content' => [
'#type' => 'inline_template',
'#template' => '{{ pre }} <figure>{{ figure }}</figure> {{ post }}.',
'#context' => [
'pre' => $this->generator->words(3, 'ucfirst'),
'figure' => $this->generator->words(3),
'post' => $this->generator->words(4),
],
],
);
I think this is not the best outcome, since those tags are required to be used together and <figure> is used to hold an image-like element, not text.
For reference, MDN states that
"The HTML or Figure Caption element represents a caption or legend describing the rest of the contents of its parent element." (https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figcaption)
And;
Usually a is an image, illustration, diagram, code snippet, etc., that is referenced in the main flow of a document, but that can be moved to another part of the document or to an appendix without affecting the main flow.(link)
As a result, the Styleguide is failing to provide with an accurate representation of the HTML element as it will be used in real code.
Proposed resolution
Merge both figure and figcaption under a single element, since they can't be found in isolation and <figcaption> is always the child of a <figure>.
Change the content of <figure> to include an image instead of text.