Miscellaneous content fixes + add a test for content

src/main/resources/io/jenkins/plugins/designlibrary/AppBar/index.properties

@@ -1,9 +1,9 @@
 topAppBar=Top app bar
 topAppBar.description=Top app bar provides the page heading as well as important actions.
-topAppBar.do.1=Place your most important actions in the top app bar
-topAppBar.do.2=Show a count subtitle if it explicitly relates to your page
-topAppBar.dont.1=Avoid showing more than four actions at once, relegate less used actions to an overflow menu
-topAppBar.dont.2=Avoid showing a count subtitle if it could relate to multiple things on your page
+topAppBar.do.1=Place your most important actions in the top app bar.
+topAppBar.do.2=Show a count subtitle if it explicitly relates to your page.
+topAppBar.dont.1=Avoid showing more than four actions at once, relegate less used actions to an overflow menu.
+topAppBar.dont.2=Avoid showing a count subtitle if it could relate to multiple things on your page.
 
 bottomAppBar=Bottom app bar
 bottomAppBar.description=Bottom app bars are great for forms, they provide important actions for the current page, such as "Save" and "Apply". Bottom app bars stick to the bottom of the screen so that they''re always present.

src/main/resources/io/jenkins/plugins/designlibrary/Buttons/index.properties

@@ -11,10 +11,10 @@ tertiary=Tertiary
 tertiary.description=Tertiary buttons should be used for buttons which have minimal interaction or for those where a background creates too much visual clutter.
 
 symbol=Symbol
-symbol.description=Buttons can include symbols and they''ll be automatically sized to fit correctly.
+symbol.description=Buttons can include symbols, and they''ll be automatically sized to fit correctly.
 
 copy=Copy
-copy.description=A small button to copy text into a clipboard.
+copy.description=A small button to copy text into the user''s clipboard.
 
 help=Help
 help.description=The button should always be in the top right of a page, last in the row of components, or in an overflow menu.

src/main/resources/io/jenkins/plugins/designlibrary/Cards/index.properties

@@ -1,8 +1,8 @@
-do.1=Keep your card glanceable, let the user expand your card for more information
-do.2=Make your cards scalable to different screen sizes
-do.3=Do use hierarchy and symbols to add visual context
-dont.1=Don''t add unnecessary visual elements that clutter the card
-dont.2=Don''t have too many actions on one card
+do.1=Keep your card glanceable, let the user expand your card for more information.
+do.2=Make your cards scalable to different screen sizes.
+do.3=Do use hierarchy and symbols to add visual context.
+dont.1=Don''t add unnecessary visual elements that clutter the card.
+dont.2=Don''t have too many actions on one card.
 creating-a-card.title=Creating a card
 creating-a-card.description=Cards are designed to automatically expand and fill the available space within their container, making them flexible and easy to use in different layouts. \n\nSince Jenkins doesn''t currently have a built-in grid system, you''ll need to create your own if you want to arrange multiple cards in a grid-like structure. You can do this by utilizing Flexbox or Grid to manage the positioning and spacing of your cards within the parent container.
 setting-actions-on-a-card.title=Setting actions on a card

src/main/resources/io/jenkins/plugins/designlibrary/Layouts/index.jelly

@@ -66,9 +66,7 @@
         </s:dos-donts>
       </s:section>
 
-      <s:section title="${%Usage}">
-        <p class="jdl-paragraph">The 'two-column' layout is default, so you don't need to do anything to use it.</p>
-
+      <s:section title="${%Usage}" description="The 'two-column' layout is default, so you don't need to do anything to use it.">
         <s:code file="twoColumn.jelly" previewable="true" />
 
         <p class="jdl-paragraph">

src/main/resources/io/jenkins/plugins/designlibrary/Layouts/index.properties

@@ -1,9 +1,9 @@
-two-column.do.1=Include a title on your sidebar that best encapsulates its child pages
-two-column.do.2=Ensure all child pages share the same sidebar for consistency
-two-column.do.3=Buttons should only relate to/manipulate their parent column
-two-column.do.4=One (and only one) sidebar item should be in its selected state at a time
-two-column.dont.1=Don''t include hierarchical navigation in your sidebar, such as "Back to Dashboard" or "Up"
-two-column.dont.2=Don''t include actions or external pages in your sidebar, these belong in the top app bar
+two-column.do.1=Include a title on your sidebar that best encapsulates its child pages.
+two-column.do.2=Ensure all child pages share the same sidebar for consistency.
+two-column.do.3=Buttons should only relate to/manipulate their parent column.
+two-column.do.4=One (and only one) sidebar item should be in its selected state at a time.
+two-column.dont.1=Don''t include hierarchical navigation in your sidebar, such as "Back to Dashboard" or "Up".
+two-column.dont.2=Don''t include actions or external pages in your sidebar, these belong in the top app bar.
 
-one-column.do.1=Use the "one-column" layout if your page doesn''t need a sidebar
-one-column.dont.1=Avoid sprawling content, use tabs if your page is lengthy and can be separated into clearly labelled sections
+one-column.do.1=Use the "one-column" layout if your page doesn''t need a sidebar.
+one-column.dont.1=Avoid sprawling content, use tabs if your page is lengthy and can be separated into clearly labelled sections.

src/main/resources/io/jenkins/plugins/designlibrary/Menu/index.properties

@@ -1,5 +1,5 @@
-do.1=Use overflow buttons to avoid overcomplicating your page
-dont.1=Avoid moving important, commonly used actions to menus
-do.2=Use overflow buttons to offer quick access to a subpage''s actions
-dont.2=Don''t overcomplicate your menus, avoid using more than one level of submenus
-do.3=Use color to emphasise differences between actions
+do.1=Use overflow buttons to avoid overcomplicating your page.
+dont.1=Avoid moving important, commonly used actions to menus.
+do.2=Use overflow buttons to offer quick access to a subpage''s actions.
+dont.2=Don''t overcomplicate your menus, avoid using more than one level of submenus.
+do.3=Use color to emphasise differences between actions.

src/main/resources/io/jenkins/plugins/designlibrary/Progress/index.jelly

@@ -17,7 +17,7 @@
       </s:group>
     </s:section>
 
-    <s:section title="Progress bar" description="${%progressAnimation.description}">
+    <s:section title="Progress animation" description="${%progressAnimation.description}">
       <s:group>
         <s:preview>
           <l:progressAnimation />

src/main/resources/io/jenkins/plugins/designlibrary/Symbols/index.properties

@@ -2,12 +2,12 @@ leadParagraph=Symbols are intended to be used everywhere a traditional icon woul
 Symbols are scalable, support different weights and adapt to the user''s theme.
 do=Do
 dont=Don''t
-do.1=Symbols should be used to help a user recognise what a task does at a glance
+do.1=Symbols should be used to help a user recognise what a task does at a glance.
 do.2=They should be recognisable and relevant, e.g.\u0020
-do.2Continued=\u0020for locked resources
-do.3=Use a tooltip on the symbol if there isn''t any accompanying text
-dont.1=Don''t use custom symbols that aren''t consistent with Jenkins
-dont.2=Don''t add symbols to headings, they just create visual clutter
+do.2Continued=\u0020for locked resources.
+do.3=Use a tooltip on the symbol if there isn''t any accompanying text.
+dont.1=Don''t use custom symbols that aren''t consistent with Jenkins.
+dont.2=Don''t add symbols to headings, they just create visual clutter.
 usage.title=Using Symbols
 usage.1=Using symbols in your view is simple. Use the existing <code>icon</code> component and set the <code>src</code> value to the symbol you want, prefixed with <code>"symbol-"</code>.
 usage.2=Symbols can also display tooltips:

src/main/resources/scss/pages/_spacing.scss

@@ -17,7 +17,7 @@
     position: relative;
     display: flex;
     background: color-mix(in srgb, var(--text-color-secondary) 2.5%, transparent);
-    border: var(--jdl-border);
+    border: var(--jdl-border-translucent);
     border-radius: 4px;
     transition: background var(--standard-transition);
 

src/test/java/ContentTest.java

@@ -0,0 +1,56 @@
+import static org.assertj.core.api.Assertions.assertThat;
+import static org.junit.jupiter.api.TestInstance.Lifecycle.PER_CLASS;
+
+import io.jenkins.plugins.designlibrary.UISample;
+import java.util.List;
+import java.util.stream.Stream;
+import org.htmlunit.html.DomNode;
+import org.junit.jupiter.api.BeforeAll;
+import org.junit.jupiter.api.TestInstance;
+import org.junit.jupiter.params.ParameterizedTest;
+import org.junit.jupiter.params.provider.MethodSource;
+import org.jvnet.hudson.test.JenkinsRule;
+import org.jvnet.hudson.test.junit.jupiter.WithJenkins;
+
+@WithJenkins
+@TestInstance(PER_CLASS)
+class ContentTest {
+
+    private JenkinsRule jenkins;
+
+    private List<UISample> samples;
+
+    @BeforeAll
+    void beforeAll(JenkinsRule jenkins) {
+        this.jenkins = jenkins;
+        this.samples = jenkins.getInstance().getExtensionList(UISample.class);
+    }
+
+    /**
+     * Validate that descriptive elements end with a full stop or a colon
+     */
+    @ParameterizedTest
+    @MethodSource("getPages")
+    void validContent(String url) throws Exception {
+        try (var webClient = jenkins.createWebClient().withJavaScriptEnabled(false)) {
+            // We get a bunch of spam in our logs about missing CSS, let's ignore that
+            webClient.getOptions().setPrintContentOnFailingStatusCode(false);
+            webClient.getOptions().setThrowExceptionOnFailingStatusCode(false);
+
+            var page = webClient.goTo(url);
+            var links = page.querySelectorAll(".jdl-section__description, .jdl-dos-donts td").stream()
+                    .map(DomNode::getTextContent)
+                    .toList();
+
+            links.forEach(e -> assertThat(e)
+                    .satisfiesAnyOf(listParam -> assertThat(listParam).endsWith("."), listParam -> assertThat(listParam)
+                            .endsWith(":")));
+        }
+    }
+
+    private Stream<String> getPages() {
+        Stream<String> homePage = Stream.of("design-library");
+        Stream<String> otherItems = samples.stream().map(e -> "design-library/" + e.getUrlName());
+        return Stream.concat(homePage, otherItems);
+    }
+}