Move all <figcaption> inside a properly closed <figure>. Also add it to our validator (#6141)

Co-authored-by: Tomas Roggero <tomasroggero@google.com>

.github/workflows/knowledge_graph.py

@@ -1,3 +1,4 @@
+from pprint import pprint
 from absl import app
 from absl import flags
 from gftools import knowledge_pb2
@@ -175,6 +176,12 @@ def _check_md_file_contents(repo_root: Path, md_file: Path, ast: List[MdValue])
         if re.search(' id="[^"]+"', text):
             print("INVALID ", _safe_relative_to(repo_root, md_file), "attr.id not allowed:", text)
             return False
+    f = open(md_file,"r")
+    content = "".join(f.readlines())
+    if re.search('</figcaption>(?!.*</figure>)', content, re.MULTILINE | re.DOTALL):
+        print("INVALID ", _safe_relative_to(repo_root, md_file), "Cannot have a <figcaption> outside of a <figure>")
+        return False
+    f.close()
     return True
 
 

cc-by-sa/knowledge/glossary/terms/abugidas_alphasyllabary/content.md

@@ -4,9 +4,10 @@ An abugida (often also referred to as an alphasyllabary) is a writing system tha
 
 ![Glyphs from a Syllabic script with Latin-specific pronunciation guides.](images/thumbnail.svg)
 
-</figure>
 <figcaption>A diagram depicting syllabics characters, which represent syllables within the Canadian Aboriginal Syllabics writing system scheme. A consonant is represented by a base form, with the vowel in a syllable being inflected depending on the orientation of the base symbol. In the above example, the first line shows the pure vowel series, with subsequent syllable series’ on lines two and three, made up of syllabic base characters across their four rotations.</figcaption>
 
+</figure>
+
 This is unlike an alphabet, where consonants and vowels are treated equally, and unlike a syllabary, where it’s impossible to split the symbols into individual elements. Examples of abugidas include the Brahmic scripts of India and the Canadian Aboriginal syllabics. 
 
 It’s technically possible to have an abugida that is not an alphasyllabary, and an alphasyllabary that is not an abugida. To explore the subtle and often debated nuances, please see [the “Abugida” article on Wikipedia](https://en.wikipedia.org/wiki/Abugida).

cc-by-sa/knowledge/glossary/terms/alphabet/content.md

@@ -4,9 +4,10 @@ An alphabet typically refers to a [writing system](/glossary/writing_system) in
 
 ![The Old and Modern English alphabet.](images/thumbnail.svg)
 
-</figure>
 <figcaption>Examples of the Old and Modern English alphabet.</figcaption>
 
+</figure>
+
 In common typological classifications, linguists principally differentiate alphabets from other types of writing systems such as [syllabaries](https://en.wikipedia.org/wiki/Syllabary), where graphical units represent syllables, and logographies, where graphical units represent entire words (or other meaningful, decomposable units of language, called morphemes). 
 
 In practice, however, writing systems frequently rely on more than one approach to represent language. For example, modern American English is written using both alphabetic letters and non-alphabetic symbols (e.g., 1, 2 , 3, @, &), many of which can be seen on standard computer keyboards.  

cc-by-sa/knowledge/glossary/terms/font_picker/content.md

@@ -6,4 +6,6 @@ The font picker is the part of a user interface that specifically allows the use
 
 <figcaption>On the left: A Font menu similar to the one in many design applications, with a dropdown for the typeface on the top, followed by a dropdown for weights and styles beneath. On the right: A pop-out sub-menu for weights and styles, as seen in Google Workspace apps.</figcaption>
 
+</figure>
+
 Depending on the software, the font picker may show the list of fonts with their names set in either the standard typeface for that UI, each in their own typeface, or a combination of a regular list augmented with a preview. Some apps, such as those in Adobe’s Creative Cloud and Microsoft Word, also have the ability to automatically update the selected text on the canvas, as the user scrolls through the list in the font picker.

cc-by-sa/knowledge/glossary/terms/interpolation/content.md

@@ -6,7 +6,8 @@ When a typeface has more than one axis of variation (for example, both weight an
 
 ![Four lowercase “a” characters, each shown in a different weight or width. One of them is highlighted to show that it was generate by a combination of the widest width and heaviest weight.](images/thumbnail.svg)
 
-</figure>
 <figcaption>A light master (top left), a bold master (top right), and a light extended master (bottom left) can be used to create a bold extended style (bottom right) thanks to vector addition.</figcaption>
 
+</figure>
+
 Interpolation and vector addition are tools type designers use to create a larger set of static fonts from fewer initial masters, and are also the mechanisms behind [variable fonts](https://fonts.google.com/knowledge/introducing_type/introducing_variable_fonts), working on-the-fly as the end user manipulates variable axes.

cc-by-sa/knowledge/glossary/terms/lockup/content.md

@@ -4,7 +4,8 @@ The fixed arrangement of two or more individual elements (e.g. a logomark togeth
 
 ![A fictional logo for a brand called Bespoké Poké, with the customized parts of the logo highlighted, along with guidelines that show how elements are aligned to each other.](images/thumbnail.svg)
 
-</figure>
 <figcaption>A logo for a fictional brand. Note the customized diacritics, highlighted here in blue—made more prominent to fit with the overall weight of the type—and the guidelines, highlighted here in red, to show alignments and spacing specific to this lockup.</figcaption>
 
+</figure>
+
 A lockup can even consist of *just* type. For instance, consider a logotype made up of two lines of text. The specific size of the type, the spacing between each line, and the overall position of the elements constitutes a lockup.

cc-by-sa/knowledge/glossary/terms/logo_logomark_logotype/content.md

@@ -4,9 +4,10 @@ A logo is a unique combination of elements—usually graphics and type—that cr
 
 ![A full logo on the left, followed by just its logomark in the center, then just a logotype (arranged differently to the main logo) on the right.](images/thumbnail.svg)
 
-</figure>
 <figcaption>1 shows the full logo: a unique lockup of the logomark and logotype for a fictional brand, created using a customized version of <a href="https://fonts.google.com/specimen/Anybody">Anybody</a>. 2 shows the isolated logomark, suitable for use on social media avatars. 3 shows a logotype with a different arrangement to the one in the main logo, intended to be used when the logomark is absent. Note that the customized diacritics remain—this is not merely the brand name typed out in that font.</figcaption>
 
+</figure>
+
 A logomark is the graphic element, symbol, or icon (for example, Nike’s Swoosh, Starbucks’ siren, or Apple’s apple) that represents the company or brand. 
 
 A logotype, which can also be known as a wordmark (although usually only if it’s made up of just one word), is a specific lockup of the brand’s name. It can be something as simple as a customized setting of a typeface (for instance, with custom kerning), an altered version that actually changes the  letterforms’ outlines, or a completely bespoke piece of lettering.

cc-by-sa/knowledge/glossary/terms/spacing/content.md

@@ -4,7 +4,8 @@ In type design, spacing refers to the act of setting the horizontal space around
 
 ![The word “axe” with the baseline and x-height shown, and the “x” character highlighted to demonstrate the horizontal spaces inside and outside the glyph.](images/thumbnail.svg)
 
-</figure>
 <figcaption>The blue box illustrates the internal spacing within the “x” glyph; the red boxes illustrate the external spacing. Note how the left and right values are intentionally unequal.</figcaption>
 
+</figure>
+
 When *setting* type, spacing can also refer to the act of making any typographic adjustment that affects space, such as [leading](/glossary/line_height_leading) (the vertical space between two lines of type), [tracking](/glossary/tracking_letter_spacing) (the overall horizontal spacing between glyphs in a block of text), or kerning (the specific horizontal spacing between two or more glyphs).

cc-by-sa/knowledge/glossary/terms/viewport/content.md

@@ -4,9 +4,10 @@ In responsive design, the viewport usually refers to the size of the browser win
 
 ![An abstract representation of a desktop computer, with a browser on screen that has its viewport area highlighted. To its right, a mobile phone and a tablet, with their viewport areas highlighted, too.](images/thumbnail.svg)
 
-</figure>
 <figcaption>The viewport size can be the same as the screen size, but only if viewed in full-screen, and only if there’s no other chrome. In most scenarios, the viewport is slightly smaller than the total available screen space.</figcaption>
 
+</figure>
+
 The horizontal and vertical dimensions of a viewport are more important than the overall screen size of the device, since that would also include any chrome and also assume that the website or app is always interacted with in fullscreen, which is not usually the case.
 
 In CSS, two relatively new units were introduced so that elements can be resized in relation to the viewport’s width and height respectively: vw and vh. For more information, please see [the “Viewport-relative units” section in the “Sizing Units” chapter of *Learn CSS!*](https://web.dev/learn/css/sizing/#viewport-relative-units) These units of measurement are in addition to the control offered by media queries, which allow for specific CSS rules to be applied when viewport size meets certain conditions. For more information, please see [the “Media queries” chapter of *Learn Responsive Design!*](https://web.dev/learn/design/media-queries/)

cc-by-sa/knowledge/modules/choosing_type/lessons/pairing_typefaces_based_on_their_construction_using_the_font_matrix/content.md

@@ -12,16 +12,18 @@ Before we dive into this different way of describing type, let’s see what’s
 
 ![The word “Ragstone“ shown in three different sans serif typefaces.](images/all-sans-serif.svg)
 
-</figure>
 <figcaption>These are all sans serif typefaces (Source Sans Pro, Helvetica, Outfit). Same genre, but they leave a quite different impression.</figcaption>
 
+</figure>
+
 <figure>
 
 ![The word “Ragstone“ shown in three different serif typefaces.](images/all-serif.svg)
 
-</figure>
 <figcaption>These serif typefaces share the same genre classification as well, and still they appear quite diverse (Alegreya, Bodoni Moda, Memphis).</figcaption>
 
+</figure>
+
 On the other hand, [historical classifications](/lesson/making_sense_of_typographic_classifications) can be more fine-grained, but require a little background knowledge. They can be confusing in their terminology and have plenty of regional variations. Focusing on details, such as the exact shape of serifs, which are not necessarily crucial to the overall impression of a typeface, makes them less practical. In fact, the historic approach can become less useful in an age where type designs mix influences from various periods of time.
 
 So how can we describe typefaces more accurately than with the genre classifications, but without being dependent on historic background knowledge? Kupferschmid approaches it with a three-layer system:
@@ -34,9 +36,10 @@ So how can we describe typefaces more accurately than with the genre classificat
 
 ![The lower case “a“ shown on three layers. The first layer is labeled skeleton (form model), showing the simple monolienar construction of the letter “a“. The second layer is labeled flesh (contrast and serifs) showing a bold striking lower case a with serifs. The third layer is labeled skin (finer differentiations) and shows the same letter with a grunge pattern on top.](images/font-matrix-layers.svg)
 
-</figure>
 <figcaption>A three-layer approach for describing typefaces based upon the work of Indra Kupferschmid.</figcaption>
 
+</figure>
+
 Let’s take a look at each individual layer to understand what it means and how it can help us choose and pair typefaces.
 
 ## Layer 1: Skeleton (form model)
@@ -53,45 +56,50 @@ Dynamic forms show open apertures, while the rational form model has closed aper
 
 ![A double-story lower case “a” displayed in three different form models in a serif typeface. The dynamic form model has an open aperture. In the rational form model the aperture is closed. The geometric single-story lower case a appears constructed with a circular shape.](images/form-model-serif.svg)
 
-</figure>
 <figcaption>The three different form models shown with serif typefaces.</figcaption>
 
+</figure>
+
 It’s easier to distinguish the form models with [contrast](/glossary/contrast) in serif typefaces. But you can still see them in sans serif shapes, too:
 
 <figure>
 
 ![A double-storey lower case “a” displayed in three different form models in a sans serif typeface. The dynamic form model has an open aperture. In the rational form model the aperture is closed. The geometric single-storey lowercase "a" appears constructed with a circular shape.](images/form-model-sans-serif.svg)
 
-</figure>
 <figcaption>The three different form models shown with sans serif typefaces.</figcaption>
 
+</figure>
+
 Let’s take a closer look at each form model and make it more obvious by setting a word. We’ll use the word “Ragstone” because it contains various letter shapes:
 
 <figure>
 
 ![A dynamic linear sans serif typeface showing the word “Ragstone”. The open apertures of the lower case a and the diagonal axis in the lower case o are shown.](images/dynamic--linear-sans.svg)
 
-</figure>
 <figcaption>The dynamic form model comes with open apertures of the “e,” “a,” and “s,” as well as the diagonally angled “o” (hard to see in sans serif, set in Source Sans Pro).</figcaption>
 
+</figure>
+
 Looking at the **dynamic form model,** you can see the open shapes, and a very subtle [diagonal axis](/glossary/axis_in_type_design). This all adds to the friendly, open, and approachable feeling that a dynamic typeface creates. [Kupferschmid associated the form models with certain adjectives](https://kupferschrift.de/cms/2012/03/on-classifications/). They can be helpful when picking a typeface that should follow a certain mood. Naturally, this mood might shift when there are serifs or no serifs, or other stylistic features, but it’s a good starting point.
 
 <figure>
 
 ![A rational linear sans serif typeface showing the word “Ragstone”. The closed apertures of the lower case a and the vertical axis in the lower case o are shown.](images/rational--linear-sans.svg)
 
-</figure>
 <figcaption>The shapes of the “e,” “a,” and “s” are rather closed, and the “o” shows vertical axis (again, not very obvious in sans serif), set in Helvetica.</figcaption>
 
+</figure>
+
 With a **rational** typeface, we can see that these apertures are closed, which then creates a more orderly, reserved, or serious feeling.
 
 <figure>
 
 ![A geometric linear sans serif typeface showing the word “Ragstone”. The constructed circular shapes of the lower case a, g, o and e are shown, also the cross shaped lower case t.](images/geometric--linear-sans.svg)
 
-</figure>
 <figcaption>Very constructed letter shapes, like the circular “o” and “e.” The “t” is a simple cross (set in Outfit).</figcaption>
 
+</figure>
+
 And with the **[geometric](/glossary/geometric) typefaces,** the apertures are not that relevant for determining the form model. Also, there is no obvious axis. It’s more about how constructed the letter shapes are. Like the circular “e,” “g,” “a,“ and “o,” or the simple “t.” This creates a clean, modern, and functional appearance.
 
 Now, knowing about these underlying form models should make it easier for you to pinpoint the differences between the three sans serif and serif typefaces from the beginning of the article, and take you one step closer towards to differentiating type.
@@ -100,9 +108,10 @@ Now, knowing about these underlying form models should make it easier for you to
 
 ![The word “Ragstone“ shown in three different sans serif typefaces next to each other in the first line, and three different serif typefaces in the second line. They are arranged in three columns labeled dynamic, rational and geometric.](images/all-serif-all-sans-serif--with-form-models.svg)
 
-</figure>
 <figcaption>Knowing about the different form models makes it easier to describe and distinguish the typefaces from before.</figcaption>
 
+</figure>
+
 ## Layer 2: Flesh (contrast and serifs)
 
 In the second layer, the flesh, we’re adding **contrast and serifs** to our descriptions. This will make the form model even clearer.
@@ -111,27 +120,30 @@ In the second layer, the flesh, we’re adding **contrast and serifs** to our de
 
 ![A dynamic contrasting serif typeface showing the word “Ragstone”. The open apertures of the lower case a and the diagonal stress in the lower case o are shown.](images/dynamic--contrasting-serif.svg)
 
-</figure>
 <figcaption>Describing Alegrya as a dynamic contrasting serif typeface.</figcaption>
 
+</figure>
+
 Before, the **dynamic form** was shown with no contrast (linear) and sans serif. Here, contrast and serifs were added. This changes the appearance, it suddenly seems more traditional, but still the same open apertures and diagonal stress from the skeleton remains. It’s just more visible with the flesh on top.
 
 <figure>
 
 ![A rational contrasting serif typeface showing the word “Ragstone”. The closed apertures of the lower case a and the vertical axis in the lower case o are shown.](images/rational--contrasting-serif.svg)
 
-</figure>
 <figcaption>Describing Bodoni Moda as a dynamic contrasting serif typeface.</figcaption>
 
+</figure>
+
 The rational linear sans serif from before turns into a **rational contrasting serif.**
 
 <figure>
 
 ![A geometric contrasting serif typeface showing the word “Ragstone”. The constructed circular shapes of the lower case g, o and e, and the circular bowl of the lower case “a” are displayed.](images/geometric--contrasting-serif.svg)
 
-</figure>
 <figcaption>Describing Candida as a geometric contrasting serif typeface.</figcaption>
 
+</figure>
+
 The geometric linear sans serif, becomes **contrasting with serif,** while still being geometric from its construction.
 
 ## Layer 3: Skin (finer details)
@@ -142,9 +154,10 @@ Kupferschmid includes finer differentiators in the top layer. The shape of the s
 
 ![A decorative rational contrasting serif typeface, with inline stokes, trifurcated serifs and thorns that create a spooky impression.](images/rational--contrasting-serif--addional-descriptors.svg)
 
-</figure>
 <figcaption>Describing all three layers of the display typeface Rye. You can still see the underlying first two layers, even though the third layer is taking the most attention.</figcaption>
 
+</figure>
+
 ## Using the font matrix for pairing type
 
 Now, when we arrange the first two layers in a grid, with the skeleton for the columns, and the flesh for the rows, the font matrix is revealed:
@@ -153,9 +166,10 @@ Now, when we arrange the first two layers in a grid, with the skeleton for the c
 
 ![The font matrix arranged in three columns and four rows. The three columns show the dynamic, rational and geometric form models. The rows show contrasting sans, contrasting serif, linear sans, and linear serif typefaces.](images/font-matrix.svg)
 
-</figure>
 <figcaption>Typefaces used (top to bottom) Dynamic: Minerva Modern, Alegreya, Source Sans Pro, and Bitter; Rational: Arya, Bodoni Moda, Helvetica, Zilla Slab; Geometric: Tenor Sans, Candida, Outfit, Memphis.</figcaption>
 
+</figure>
+
 Seeing the typefaces arranged in this way makes it obvious where the similarities and differences lie, and opens up three guidelines we can utilize to pair typefaces. Let’s explore each of those in turn.
 
 ### 1. Pair typefaces with similar form models
@@ -164,9 +178,10 @@ Seeing the typefaces arranged in this way makes it obvious where the similaritie
 
 ![The font matrix shown with the columns for the three form models highlighted.](images/font-matrix--pair-same-form-model.svg)
 
-</figure>
 <figcaption>Combine typefaces according to their form model.</figcaption>
 
+</figure>
+
 Typefaces from the same form model most likely will go together. Their construction is similar, but the layers added on top are different.
 
 ### 2. Pair typefaces with varying contrast and serifs
@@ -175,9 +190,10 @@ Typefaces from the same form model most likely will go together. Their construct
 
 ![The font matrix shown with a diagonal combination of a dynamic contrasting sans with a geometric linear serif typeface.](images/font-matrix--pair-contrasting.svg)
 
-</figure>
 <figcaption>Go for contrast with very different skeleton and flesh (diagonal combinations).</figcaption>
 
+</figure>
+
 Diagonal combinations create contrasting pairs. The typefaces are so different that they won’t get in the way of each other.
 
 ### 3. Avoid combinations with different form models, but the same contrast and serifs
@@ -186,9 +202,10 @@ Diagonal combinations create contrasting pairs. The typefaces are so different t
 
 ![The font matrix shown with the highlighted row of linear sans typefaces in the different form models.](images/font-matrix--pair-avoid-same-flesh.svg)
 
-</figure>
 <figcaption>Is it different or is it the same? Avoid combining typefaces from the same row.</figcaption>
 
+</figure>
+
 Combining typefaces from the same row will create an irritating result. This is because they’re similar on a superficial level (the flesh), but in their form model, they’re diverse.
 
 ## Look for form models everywhere
@@ -199,9 +216,10 @@ The most crucial part of this system is recognizing the form model underneath a
 
 ![A photo of three different street signs showing typefaces with the different form models.](images/look-for-form-models.jpg)
 
-</figure>
 <figcaption>Try to spot the form model in the wild! Left to right: dynamic, rational, and geometric.</figcaption>
 
+</figure>
+
 ## Combining typefaces step by step
 
 When it comes to combining typefaces, this is the process we recommend, using the ideas behind the font matrix:
@@ -220,36 +238,40 @@ Let’s put this into practice with an example. Let’s say my primary typeface
 
 ![The word “Ragstone” shown in the dynamic linear serif typeface bitter. It has a diagonal axis and open apertures.](images/combine-fonts-example-step-1-2.svg)
 
-</figure>
 <figcaption>Steps 1 and 2: The primary typeface is Bitter, used for body text. It’s a dynamic linear serif typeface.</figcaption>
 
+</figure>
+
 Now we look for a secondary typeface for inline code in the body text. Bitter does not come with a [monospaced](/glossary/monospaced) style. We want the secondary typeface to feel very similar to the primary choice, while being monospaced.
 
 <figure>
 
 ![On the left, the typeface “Bitter” is shown as the primary choice used for body text and labeled as “dynamic”. On the right side, the briefing for a secondary typeface used for inline code is written. The typeface should be dynamic linear, and monospaced.](images/combine-fonts-example-step-3-to-5.svg)
 
-</figure>
 <figcaption>Steps 3 to 5: We look for a secondary typeface for inline code that’s dynamic, linear and monospace.</figcaption>
 
+</figure>
+
 Let’s only browse the monospaced typefaces on Google Fonts and pick some candidates. When we take a look at our first selection and evaluate their form model, we see that Fira Sans might fit best to what we’re looking for.
 
 <figure>
 
 ![On the left, the dynamic typeface “Bitter” is shown. On the right there are three different monospace typefaces in a column as possible candidates. From top to bottom, they are the geometric ”Space Mono“, the rational “JetBrains Mono“, and the dynamic “Fira Code“.](images/combine-fonts-example-step-6.svg)
 
-</figure>
 <figcaption>Step 6: Our possible candidates and their form models.</figcaption>
 
+</figure>
+
 Let’s see how this looks in an actual sentence. As suggested, Fira Code works best. It seamlessly integrates and meets the conditions of our brief. Space Mono might work as well, if we were looking for a contrasting pair.
 
 <figure>
 
 ![Three times the sentence “In my opinion, font-family is the best declaration in CSS.“ set in the serif typeface Bitter. The word “font-family“ is set in three different mono space typefaces. The first line shows the rejected combination with “Space Mono” with very contrasting form models. The second line shows the rejected combination with “JetBrains Mono“, which is not different/same enough according to the form model. The third line shows the approved pairing with ”Fira Code“ which is most seamless.](images/combine-fonts-example-step-7.svg)
 
-</figure>
 <figcaption>Step 7: Evaluating our options in an actual sentence. Fira Code fits what we were looking for.</figcaption>
 
+</figure>
+
 ## Limitations of this system
 
 This is not a perfect system. Not every typeface fits into it, and you won’t be able to apply it in every scenario. The examples in this article are slightly more extreme, and soon you will find plenty of cases that are in between the different form models or the other layers. In this case, try to describe it as “quite dynamic,” or “semi-rational,” for example.
@@ -258,16 +280,18 @@ This is not a perfect system. Not every typeface fits into it, and you won’t b
 
 ![The quite rational, linear serif typeface “Roboto Slab” showing the word “Ragstone”. It shows a vertical axis and opened apertures.](images/roboto-slab--quite-rational.svg)
 
-</figure>
 <figcaption>From its form model, Roboto Slab does not meet all the criteria of an obvious rational typeface. But overall it still feels quite rational with its narrow proportions and vertical axis.</figcaption>
 
+</figure>
+
 <figure>
 
 ![Several typefaces shown that will fall out of the matrix.](images/exceptions-of-the-matrix.svg)
 
-</figure>
 <figcaption>When it comes to more striking display typefaces, script, handwritten, or blackletter, don’t spend too much energy training to put them into the matrix. They will most likely be very contrasting anyway.</figcaption>
 
+</figure>
+
 When applying it to your design, other factors come into play, depending on how close the combination is, such as a similar [x-height](/glossary/x_height), or a similar or different [width](/glossary/width). Also, you can improve a less-than-ideal combination by using different [weights](/glossary/weight) or [styles](/glossary/style).
 
 So see the font matrix as a guideline to make pairing decisions, but don’t drive yourself crazy. Even Indra Kupferschmid says that it is not binding and should not limit your creativity. It is one way—not the only way—and hopefully this will support you in finding _your_ way.