nyc-planning-style-guide

<!doctype html> <html class="no-js" lang="en"> <head> <meta charset="utf-8" /> <meta http-equiv="x-ua-compatible" content="ie=edge"> <meta name="viewport" content="width=device-width, initial-scale=1.0"> <title>NYC Planning Digital Style Guide</title> <link rel="stylesheet" href="https://use.fontawesome.com/releases/v5.8.2/css/all.css" integrity="sha384-oS3vJWv+0UjzBfQzYUhtDYW+Pj2yciDJxpsK1OYPAYjqT085Qq/1cq5FLXAZQ7Ay" crossorigin="anonymous"> <link rel="stylesheet" href="../assets/css/nyc-planning.css"> <style> .header-logo { max-height: 4.5rem; } .code-example code { display: block; padding: 1rem; overflow-x: scroll; margin-bottom: 1.5rem; } .is-stuck{ max-height: 100vh; overflow: auto; } .code-example + .callout, .code-example + table { margin-top: calc(-1px - 1.5rem); } section + section { margin-top: 3rem; padding-top: 3rem; border-top: 1px solid #d3d5d9; } section h4 { margin-top: 1.5rem; } section .code-example + h4 { margin-top: 0; } .callout.clear { background-color: transparent; border-color: transparent; } .color-swatch { list-style: none; margin: 0; padding: 2.5rem 0.75rem 0.75rem; line-height: 1.4; } </style> </head> <body id="top"> <header class="xlarge-padding-top large-padding-bottom bg-white-smoke"> <div class="grid-container"> <div class="grid-x text-center medium-text-left align-middle"> <div class="cell medium-shrink"> <img class="header-logo medium-margin-right medium-margin-bottom" src="https://raw.githubusercontent.com/NYCPlanning/dcp-logo/master/dcp_logo_772.png" alt="NYC Planning" /> </div> <div class="cell medium-auto"> <h1 class="no-margin">Digital Style Guide</h1> <p class="medium-margin-bottom">Standards, Code Snippets, & Assets</p> </div> <p class="cell medium-shrink no-margin show-for-medium"> <a href="https://github.com/NYCPlanning/nyc-planning-style-guide"> <i class="fab fa-github fa-2x small-margin text-light-gray"></i> 1.0.7 </a> </p> </div> </div> </header> <div id="main-content" class="grid-container"> <div class="grid-x grid-margin-x"> <div class="medium-8 large-9 cell medium-order-2 large-padding-top large-padding-bottom"> <h1 id="accessibility" class="large-margin-bottom">Accessibility</h1> <section> <p class="large-margin-bottom">Be sure to follow best practices to make our products more accessible:</p> <div class="grid-x grid-margin-x"> <div class="cell large-7"> <ul> <li><p><strong>Structure documents properly.</strong> Use the right HTML tags when marking up navigation, lists, links, controls, etc.</p></li> <li><p><strong>Label everything.</strong> Every control or form element must have a text label. You can use the visibility classes to hide labels visually while maintaining accessibility. Use `alt` attributes on images to describe them.</p></li> <li><p><strong>Don't rely on solely visual cues.</strong> Content should make sense even if it's being read by a screen reader. Content with color-based labeling should also have text-based ways of being identified.</p></li> <li><p><strong>Make all content navigable regardless of device.</strong> All components should work with keyboards, mice, and touch screens. If content is primarily accessed via an interactive map, it should also be accessible via text search or some other non-map method.</p></li> </ul> </div> <div class="cell large-5"> <h5 class="small-margin-bottom">Resources</h5> <ul class="text-small"> <li><a href="https://www.w3.org/TR/UNDERSTANDING-WCAG20/">WCAG 2.0 Guide</a></li> <li><a href="https://developer.mozilla.org/en-US/docs/Web/Accessibility">MDN accessibility documentation</a></li> <li><a href="https://www.w3.org/WAI/intro/accessibility.php">w3.org Introduction to Accessibility</a></li> <li><a href="https://www.section508.gov/">Section 508 government requirements</a></li> <li><a href="http://webaim.org/">WebAIM certification and training</a></li> <li><a href="http://a11yproject.com/checklist.html">Web Accessibility Checklist</a></li> </ul> <h5 class="small-margin-bottom">Tools</h5> <ul class="text-small"> <li><a href="https://tenon.io/index.php">Tenon accessibility checker</a></li> <li><a href="http://wave.webaim.org">WAVE Chrome plugin - free accessibility checker</a></li> <li><a href="http://webaim.org/resources/contrastchecker">Color Contrast Checker</a></li> <li><a href="http://www.chromevox.com">ChromeVox screen reader plugin for Chrome</a></li> <li><a href="http://www.freedomscientific.com/Products/Blindness/Jaws">JAWS screen reader for Windows</a></li> <li><a href="http://www.nvaccess.org/download/">NVDA screen reader for Windows - Free</a></li> </ul> </div> </div> </section> <section> <h3 id="contrast">Contrast <sup><a href="#contrast" class="silver"><i class="fas fa-link"></i></a></sup></h3> <p>For users with low vision, proper typographic contrast is important. Both size and color matter. Text colors should stand out from background colors. Use the <a href="https://webaim.org/resources/contrastchecker/">Color Contrast Checker <i class="fas fa-external-link-alt"></i></a> to choose accessible colors. The contrast ratio should at least be 1:4.5 for normal text and 3:1 for large text.</p> </section> <section> <h3 id="screen-readers">Screen readers <sup><a href="#screen-readers" class="silver"><i class="fas fa-link"></i></a></sup></h3> <p>Adding <code>display: none</code> to an element will prevent screen readers from reading it. There are better ways to hide content while still making it accessible to screen readers.</p> <h4 id="show-for-screen-readers-only">Show for Screen Readers Only</h4> <p>To visually hide content, while still allowing assistive technology to read it, add the <code>.show-for-sr</code> class.</p> <div class="code-example"><pre><code class="html hljs"><span class="hljs-tag"><<span class="hljs-title">p</span> <span class="hljs-attribute">class</span>=<span class="hljs-value">"show-for-sr"</span>></span>This paragraph can only be read by a screen reader.<span class="hljs-tag"></<span class="hljs-title">p</span>></span> <span class="hljs-tag"><<span class="hljs-title">p</span>></span>There's a paragraph above this one, but you can't see it.<span class="hljs-tag"></<span class="hljs-title">p</span>></span></code></pre></div><div class="callout"> <p class="show-for-sr">This paragraph can only be read by a screen reader.</p> <p>There's a paragraph above this one, but you can't see it.</p> </div> <h4 id="hide-for-screen-readers-only">Hide for Screen Readers Only</h4> <p>To hide text from assistive technology, while still keeping it visible, add the attribute <code>aria-hidden="true"</code>. This doesn't affect how the element looks, but screen readers will skip over it.</p> <div class="code-example"><pre><code class="html hljs"><span class="hljs-tag"><<span class="hljs-title">p</span> <span class="hljs-attribute">aria-hidden</span>=<span class="hljs-value">"true"</span>></span>This text can be seen, but won't be read by a screen reader.<span class="hljs-tag"></<span class="hljs-title">p</span>></span></code></pre></div><div class="callout"> <p aria-hidden="true">This text can be seen, but won't be read by a screen reader.</p> </div> <p><em>Note: It's usually not a good idea to hide content from screen readers, but <code>aria-hidden</code> is best used to mask purely visual elements of a page. Try to avoid purely decorative text and images.</em></p> <h4 id="skip-links">Skip links</h4> <p>In a product with a lot of navigation, a screen reader has to read through the entire navigation to get to the content. This can be remedied by adding a skip link before the navigation, which takes the user to the main content.</p> <p>The <code>.show-on-focus</code> class hides an element, except when it has focus. Adding <code>tabindex</code> to the target element makes it focusable—a negative value (e.g. <code>tabindex="-1"</code>) means the element is focusable, but not reachable via sequential keyboard navigation; <code>tabindex="0"</code> means the element is focusable in sequential keyboard navigation.</p> <div class="code-example"><pre><code class="html hljs"><span class="hljs-tag"><<span class="hljs-title">a</span> <span class="hljs-attribute">class</span>=<span class="hljs-value">"show-on-focus"</span> <span class="hljs-attribute">href</span>=<span class="hljs-value">"#main-content"</span>></span>Skip to content<span class="hljs-tag"></<span class="hljs-title">a</span>></span> <span class="hljs-tag"><<span class="hljs-title">header</span> <span class="hljs-attribute">id</span>=<span class="hljs-value">"header"</span> <span class="hljs-attribute">role</span>=<span class="hljs-value">"banner"</span>></span> <span class="hljs-comment"></span> <span class="hljs-tag"></<span class="hljs-title">header</span>></span> <span class="hljs-tag"><<span class="hljs-title">main</span> <span class="hljs-attribute">id</span>=<span class="hljs-value">"main-content"</span> <span class="hljs-attribute">role</span>=<span class="hljs-value">"main"</span> <span class="hljs-attribute">tabindex</span>=<span class="hljs-value">"0"</span>></span>...<span class="hljs-tag"></<span class="hljs-title">main</span>></span></code></pre></div></section> <section> <h3 id="focus-styles">Focus styles <sup><a href="#focus-styles" class="silver"><i class="fas fa-link"></i></a></sup></h3> <h4 id="-never-remove-css-outlines"><i class="fas fa-exclamation-triangle text-gold"></i> Never remove CSS outlines!</h4> <p>It is tempting to use <code>:focus { outline: none; }</code> to removing outlines in CSS. But this creates issues for people navigating via keyboard, removing any visible indication of focus. Methods like <code>onfocus="blur()"</code> are even worse, preventing users from interacting with elements at all.</p> <p>Instead, use the <a href="https://github.com/ten1seven/what-input">what-input</a> library, which detects the user's current input device and adjusts the CSS accordingly. It let's us disable outlines for mouse users, but not for keyboard users.</p> <ul> <li>TODO: explain how to include what-input if not using Foundation JS...</li> </ul> <p><em>Note: Custom Sass components can use the <code>@include disable-mouse-outline;</code> at-rule to add what-input styles.</em></p> </section> </div> <div class="medium-4 large-3 cell medium-order-1" data-sticky-container> <div class="sticky large-padding-top large-padding-bottom" data-sticky data-margin-top="0" data-anchor="main-content">  <ul class="no-bullet" data-smooth-scroll data-animation-easing="swing"> <li> <a href="/" class="text-weight-bold display-inline-block ">Overview</a> <ul class="medium-margin-bottom text-small"> </ul> </li> <li> <a href="/getting-started" class="text-weight-bold display-inline-block ">Getting Started</a> <ul class="medium-margin-bottom text-small"> </ul> </li> <li> <a href="/logo" class="text-weight-bold display-inline-block ">Logo</a> <ul class="medium-margin-bottom text-small"> </ul> </li> <li> <a href="/color" class="text-weight-bold display-inline-block ">Color</a> <ul class="medium-margin-bottom text-small"> </ul> </li> <li> <a href="/icons" class="text-weight-bold display-inline-block ">Icons</a> <ul class="medium-margin-bottom text-small"> </ul> </li> <li> <a href="/typography" class="text-weight-bold display-inline-block ">Typography</a> <ul class="medium-margin-bottom text-small"> </ul> </li> <li> <a href="/forms" class="text-weight-bold display-inline-block ">Forms</a> <ul class="medium-margin-bottom text-small"> </ul> </li> <li> <a href="/navigation" class="text-weight-bold display-inline-block ">Navigation</a> <ul class="medium-margin-bottom text-small"> </ul> </li> <li> <a href="/accessibility" class="text-weight-bold display-inline-block active">Accessibility</a> <ul class="medium-margin-bottom text-small"> <li><a href="#contrast">Contrast</a></li> <li><a href="#screen-readers">Screen readers</a></li> <li><a href="#focus-styles">Focus styles</a></li> </ul> </li> <li> <a href="/layout" class="text-weight-bold display-inline-block ">Layout</a> <ul class="medium-margin-bottom text-small"> </ul> </li> <li> <a href="/maps" class="text-weight-bold display-inline-block ">Maps</a> <ul class="medium-margin-bottom text-small"> </ul> </li> <li> <a href="/voice-and-language" class="text-weight-bold display-inline-block ">Voice & Language</a> <ul class="medium-margin-bottom text-small"> </ul> </li> </ul> </div> </div> </div> </div> <script src="../assets/js/nyc-planning.js"></script> </body> </html>