Adding Design Manual content guidelines, corresponding updates to footer

_config.yml

@@ -125,6 +125,20 @@ secondarynav:
   internal: true
   category: Brand guidelines
 
+# Content guidelines
+- text: Design Manual structure
+  url: content-guidelines/content-guidelines.html
+  internal: true
+  category: Content guidelines
+- text: General content guidelines
+  url: content-guidelines/general-content-guidelines.html
+  internal: true
+  category: Content guidelines
+- text: For page components section
+  url: content-guidelines/page-components.html
+  internal: true
+  category: Content guidelines
+
 
 # Global elements
 - text: Browse page

_includes/footer.html

@@ -2,6 +2,8 @@
     <div class="wrapper footer-container">
 
         <section class="footer-section footer-links">
+            <h4>For visitors</h4>
+
             <ul>
                 <li>
                     <a href="http://www.consumerfinance.gov/">consumerfinance.gov</a>
@@ -23,6 +25,17 @@
             </ul>
         </section>
 
+        <section class="footer-section footer-links">
+            <h4>For contributors</h4>
+
+            <ul>
+                <li>
+                    <a href="../design-manual/content-guidelines/content-guidelines.html">How to write Design Manual pages</a>
+                </li>
+
+            </ul>
+        </section>
+
         <section class="footer-section footer-oss">
             <h4>Open source</h4>
             <p>
@@ -39,17 +52,5 @@ <h4>Open source</h4>
             </p>
         </section>
 
-        <section class="footer-section footer-standards">
-            <h4>A note about our standards</h4>
-            <p>
-                These standards reflect our latest thinking and are just beginning to
-                be incorporated into the CFPB's most recent projects.
-                See these standards in practice in
-                <a href="http://www.consumerfinance.gov/eregulations/">eRegs</a>,
-                <a href="http://www.consumerfinance.gov/complaint/">Consumer Response</a>, and
-                <a href="http://www.consumerfinance.gov/hmda">HMDA</a>.
-            </p>
-        </section>
-
     </div>
 </footer>

content-guidelines/content-guidelines.md

@@ -0,0 +1,36 @@
+---
+layout: page
+title: Design Manual structure
+category: Content guidelines
+---
+
+<div class="content-67 content-first"> 
+### This guide helps define the organization and written styles of the design manual pages. 
+</div>
+
+#### Design Manual structure
+
+All topics within the Design Manual should fall under one of these categories/content types: 
+
+* Brand guidelines
+* Global elements
+* [Page components](page-components.html)
+* Best practices
+
+
+##### Brand guidelines
+
+Topics under brand guidelines touch on CFPB-specific design and branding elements, such as color, typography, and illustration styles. These are things that fall under the umbrella of visual language.
+
+##### Global elements 
+
+Topics under global elements encompass structural elements that are used to create the foundation of the webpage as well as elements that appear on every page. This includes things like rules on navigation, the grid, specific page types, or page introductions.   
+
+##### Page components
+
+Page components are individual UI elements that can be “placed” on a page.
+
+##### Best practices
+
+Best practices are longer-form content pages that detail recommended practices and guiding principles around a specific topic. They focus on conveying tips, strategies, and advice for designing effective, accessible, and user-centered products. These can be broader topics for general best practices and don’t have to be specific to CFPB only.
+

content-guidelines/general-content-guidelines.md

@@ -0,0 +1,79 @@
+---
+layout: page
+title: General content guidelines
+category: Content guidelines
+published: true
+---
+
+- [Structure](#structure)
+- [Formatting content](#formatting)
+- [Language](#language)
+- [Dynamic content](#dynamic-content)
+{: class="toc"}
+
+<div class="content-67 content-first">
+
+These guidelines apply to structuring and writing all design manual pages, to ensure consistent information presentation and style. 
+{: class="lead-in"}
+</div>
+
+<h2 id="structure">Structure</h2>
+
+<div class="content-67 content-first">
+
+Most design manual pages consist of a definition or overview of the topic of the page, plus some number of subsections giving detailed information about it. When structuring a page, follow these guidelines:
+
+* All sub-headers within the pages should be coded as jump/anchor links, to allow for easy deep linking from other design manual pages.
+* Only include sections/sub-sections that pertain to the specific item you are defining.
+* The structure outlined for a page type may not align with every single item; use your discretion to add different sections as necessary to convey the needed design information.
+
+</div>
+
+<h2 id="formatting">Formatting content</h2>
+
+<div class="content-67 content-first"> 
+Present components of behavior, styling, use cases, etc as bullet points, to allow readers to skim content easily. Include an image or a live code example of those components as needed.
+
+Example: 
+* Background lightbox: Gray 80% #75787b, 70% opacity
+* Font: Avenir Next Regular
+* Padding: 30px
+
+### Code examples
+
+Design manual pages should demonstrate content visually along with explanation text. When possible, include a live code example of the design manual item. If live code is not practical, use images to show an example or illustrate a concept.
+
+### Image links
+
+Sometimes it may be appropriate to include a small version of an image on the page, with a link to a larger version that shows more detail. When including a link to a larger version of an image, include explicit link text, and make both the image itself and the text link to the larger version.
+
+</div>
+
+
+<h2 id="language">Language</h2>
+
+<div class="content-67 content-first"> 
+
+#### Capitalization
+Headers and sub-headers will use sentence case
+
+Example: “Use case” not “Use Case” 
+
+#### Plural vs singular
+Use plural case to describe components, unless referring to a specific instance of that component when singular reference should be used
+
+Example: 
+* “Modals can be effective for communicating a warning or alert outside the main web page.” 
+* “When a modal opens, set the focus to the first element users need to interact with.” 
+
+</div>
+
+<h2 id="dynamic-content">Dynamic content</h2>
+
+<div class="content-67 content-first"> 
+Use dynamic content, or shortcut references to data used site-wide, to simplify the process of documenting standards. Rather than writing out the hex number for a brand palette color, you could use a dynamic content reference to automatically pull that hex number into your design manual page. This eliminates the need to copy and paste the same content again and again or update many separate pages if standards change over time. 
+
+Dynamic content is defined centrally within Jekyll includes or data files and can be pulled into other design manual pages. The include file or data file can be updated once, and all the places that use dynamic content will automatically update.
+
+Currently, dynamic content is used to specify color data (color name and hex #) on component pages. Detailed instructions for using the color data is located on [the github wiki](https://github.com/cfpb/design-manual/wiki/Using-data-files).
+</div> 

content-guidelines/page-components.md

@@ -0,0 +1,94 @@
+---
+layout: page
+title: For page components section
+category: Content guidelines
+published: true
+---
+
+- [Structure](#structure)
+- [Imagery](#imagery)
+- [Language](#language)
+- [Dynamic content](#dynamic-content)
+{: class="toc"}
+
+<div class="content-67 content-first">
+
+Use the following as a guideline for creating the sub-sections on a design manual page. 
+{: class="lead-in"}
+
+
+* All sub-headers within the pages should be coded as jump/anchor links, to allow for easy deep linking from other design manual pages. 
+* Only include sections/sub-sections that pertain to the specific item you are defining. 
+* This structure may not align with every single item; use your discretion to add different sections as necessary to convey the needed design information.
+
+
+</div>
+
+<h2 id="structure">Structure</h2>
+
+<div class="content-67 content-first">
+
+#### Title (h1)
+
+#### Definition
+A brief (2-3 sentence) description of what the item is and generally what it is used for.
+
+#### Use case(s) (h2)
+
+Explain why and when that element should and should not be used.
+
+* Include default/most common use cases
+* Include variations on use cases, if applicable 
+* If the element should only be used in a few specific circumstances, simply explain the acceptable use cases rather than detail the instances where it should not be used (the majority)
+* Include examples, where possible
+* Include an image of the default version
+
+#### Behavior (h2)
+
+Explain the details of any interactions involved with that item.
+
+* **Creating accessible behaviors**—sub-section dedicated to development and design considerations in order to make those behaviors 508 compliant and accessible
+* **Small-screen behavior**—include a sub-section (if necessary) that details any behaviors that are different on a smaller screen
+
+* **Responsive**—describe component behavior as it scales to smaller screens (i.e., how content stacks, in what order it should appear, etc.)
+
+#### Content guidelines (h2) 
+Guidance for creating content associated with that component, including instructions around content goals, best practices around writing headlines/links (if applicable) and approximate length/word count maximums
+
+#### Style (h2)
+Create different sub-sections for defaults and variations on style, include different states for each as needed (onstate, hover state, etc.). If the component is comprised of several different areas, break out the styles for each area separately to make it easier to digest. 
+
+* Small-screen style—include a sub-section (if necessary) that details any styles that are different on a smaller screen
+
+Styles should be as detailed as necessary to create the component, including things like font, color, padding, etc. Per FEWD preference, put them in alpha order. If dynamic content has been defined for a property such as color, use the appropriate [data file](https://github.com/cfpb/design-manual/wiki/Using-data-files) or include file to reference the property.
+
+For example: 
+
+* Alignment: centered horizontally and vertically on top of lightbox
+* Background: White #ffffff
+* Background lightbox: Gray-80 #75787b, 70% opacity
+* Color: Black #101820
+* Font: Avenir Next Regular
+* Padding: 30px
+* Text size body: 16px
+* Text size header: 22px
+* Top border: 3px CFPB Green #20aa3f
+
+Include an example of the style (preferably a coded example, or if not, an image) 
+
+
+#### Code (h2) 
+Include live coded examples from Capital Framework as available, and links to resources to learn more about the live components
+
+#### Print (h2) 
+Include any print-specific styles or guidelines when necessary
+
+</div>
+
+<h2 id="imagery">Imagery</h2>
+
+<div class="content-67 content-first"> 
+* Include an image with use case to show a default example of the component 
+* When possible, use a live coded example in place of an image
+* Image width should be no more than 50% of content area
+</div>

src/static/css/footer.less

@@ -46,7 +46,7 @@
     padding-top: 2em;
     padding-bottom: 2em;
   }
-  
+
   .footer-links ul {
     list-style: none;
     padding-left: 0;
@@ -73,21 +73,21 @@
 
   }
 
-} 
+}
 
 /* Move to 25-75 columns when link fits (800px) */
 @media only screen and (min-width: 50em) {
 
   .footer-links {
-    .grid_column(3);
+    .grid_column(1, 5);
   }
 
   .footer-oss {
-    .grid_column(5);
+    .grid_column(3, 10);
   }
 
   .footer-standards {
-    .grid_column(4);
+    .grid_column(3, 10);
   }
-  
-} 
+
+}