Feature/docs (#50)

* Redesign docs * Adjust h2 line-height * Consistent name refering * Reduce masthead loading flash * Update to same docs as core-components * Publish correct folder
nrkno · Jul 16, 2018 · 61e2a14 · 61e2a14
1 parent 32222a2
commit 61e2a14
Show file tree

Hide file tree

Showing 12 changed files with 594 additions and 3,417 deletions.
diff --git a/.stylemark.yml b/.stylemark.yml
diff --git a/lib/a11y.md b/lib/a11y.md
diff --git a/lib/docs.css b/lib/docs.css
diff --git a/lib/docs.js b/lib/docs.js
@@ -37,8 +37,8 @@ Object.keys(GROUPS).forEach(function (type) {
 
 // Render icon-grid
 document.querySelector('.docs-icons').innerHTML = Object.keys(GROUPS).map(function (type) {
-  return '<h2 data-icon style="margin:3em 0 1em;width:100%">' + type +
-    '<div style="margin:1em 0;border-bottom:1px solid currentColor;opacity:.2"></div></h2>' +
+  return '<h3 data-icon class="nrk-xs-12of12">' + type +
+    '<div style="margin:1em 0;border-bottom:1px solid currentColor;opacity:.1"></div></h3>' +
     GROUPS[type].sort().join('')
 }).join('')
 
@@ -47,7 +47,7 @@ document.addEventListener('input', function (event) {
   var element = event.target
   var value = element.value
   var label = element.previousElementSibling
-  var icons = document.getElementById('icons')
+  var icons = document.querySelector('.docs-icons')
 
   if (element.name === 'color') {
     icons.style.color = label.textContent = value

diff --git a/lib/docs.md b/lib/docs.md
@@ -1,48 +1,117 @@
----
-name: Core Icons
-category: Introduction
----
+# Core Icons
 
-<link rel="stylesheet" href="docs.css">
+## Icon and logo kit providing a consistent and predictable user experience across platforms and NRK services
 
-> `core-icons` exposes a set of standard NRK icons. Icons scale based `font-size`, and gives sharpest rendering with font sizes divisible with 10. E.g: `svg { font-size: 10px }`. Insert the code below into the `<body>` of your page to use icons as [svg symbols](https://css-tricks.com/svg-symbol-good-choice-icons/).
-
-<a class="nrk-button" href="https://github.com/nrkno/core-icons">View on Github</a>
-<a class="nrk-button" href="https://github.com/nrkno/core-icons/archive/master.zip">Download icons</a>
+---
 
-## Use from static.nrk.no *- recommended*
+## Installation
+[Download the full kit](https://github.com/nrkno/core-icons/archive/master.zip) for sketching, [individual SVGs](#icons) for Android, [PDFs](#icons)
+for iOS. As [SVG symbols](https://css-tricks.com/svg-symbol-good-choice-icons/) can not can load cross domain, or from external file and in IE (9,10,11), `@nrk/core-icons` provides a cacheable, cross-domain [Javascript API](#javascript-api) and [React API](#react-api). All icons follow [BEM naming conventions](http://getbem.com/) and are prefixed with `nrk-` to play nice with existing code.
 
+```bash
+npm install @nrk/core-icons --save  # Use from NPM
+```
 ```html
+<!-- Use from static.nrk.no: insert just before </body> -->
 <script async src="https://static.nrk.no/core-icons/latest/core-icons.min.js"></script>
 ```
 
-## Use from NPM *- gives access to [Javascript API](/#javascript)*
-```bash
-npm install @nrk/core-icons --save
-```
-``` js
-import coreIcons from '@nrk/core-icons'    // Vanilla JS
-import CoreIcon from '@nrk/core-icons/jsx' // ...or React/Preact compatible JSX
+---
+
+## Scaling
+
+All icons are produced for sharpest rendering at `15×15`, `30×30` etc., but not all *logos* are the same dimensions. Therefore, `@nrk/core-icons` provides scaling based on `font-size`. When used on web, scale the icons by using font sizes divisible with `10`:
+
+✅ Do | 🚫 Don't
+:-- | :--
+`svg { font-size: 10px }` | `svg { width: 30px; height: 30px }`
+
+---
+
+## Icons
+
+<label class="nrk-button">
+  <span class="nrk-sr">Filter icons</span>
+  <input type="text" name="search" placeholder="Type to search" class="nrk-unset">
+</label><label class="nrk-button">
+  <span>Choose color</span>
+  <input type="color" name="color" class="nrk-sr" value="#000000">
+</label>
+<div class="docs-icons nrk-grid" style="padding:0 7vw;margin:0 -7vw;transition:.2s"></div>
+<script src="pdfkit-and-blob-stream.js"></script>
+<script src="core-icons.min.js"></script>
+<script src="docs.js"></script>
+
+---
+
+## Accessibility
+
+Modern versions of assistive technologies will announce SVG content, but there is still a lot of differences between browsers. To avoid confusion, use the following conventions:
+
+<div class="nrk-grid">
+  <div class="nrk-xs-12of12 nrk-md-4of12" style="padding-right:15px">
+    <div class="doc-demo">
+      <a href="https://nrk.no/">
+        Gå til nrk.no
+        <svg aria-hidden="true" width="30" height="15"><use xlink:href="#nrk-arrow-right-long" /></svg>
+      </a>
+    </div>
+    <h3>Icon used as decoration</h3>
+    Use the <code>aria-hidden="true"</code> attribute to hide the icon from screen readers while keeping it visually perceivable.
+  </div>
+  <div class="nrk-xs-12of12 nrk-md-4of12" style="padding-right:15px">
+    <div class="doc-demo">
+      <a aria-label="Gå til nrk.no" href="https://nrk.no/">
+        <svg aria-hidden="true" width="3.5em" height="1em"><use xlink:href="#nrk-logo-nrk" /></svg>
+      </a>
+    </div>
+    <h3>Clickable icon</h3>
+    Add screen reader content to the clickable element (<code>button</code> or <code>a</code>) with <code>aria-label="…"</code>, and hide the icon from screen readers with <code>aria-hidden="true"</code>
+  </div>
+  <div class="nrk-xs-12of12 nrk-md-4of12" style="padding-right:15px">
+    <div class="doc-demo">
+      <span role="img" aria-label="Terningkast seks">
+        <span class="nrk-sr">Terningkast seks</span>
+        <svg aria-hidden="true" style="width:1.5em;height:1.5em;vertical-align:middle"><use xlink:href="#nrk-dice-6--active" /></svg>
+      </span>
+      Fantastisk!
+    </div>
+    <h3>Non-clickable icon</h3>
+    Hide the icon from screen readers with <code>aria-hidden="true"</code>, and add screen reader content to a wrapper with <code>role="img" aria-label="…"</code>, as well as inside a <code>.nrk-sr</code>.
+  </div>
+</div>
+
+---
+
+## Javascript API
+
+`@nrk/core-icons` provides a javascript API. You can either access it directly from `window.coreIcons` (when included as a `<script>` tag), or import as a NPM module:
+
+```js
+import coreIcons from '@nrk/core-icons'
+
+coreIcons()               // => returns Array of all icons: [{id, width, height, body, sprite, symbol, svg}]
+coreIcons('nrk-logo-nrk') // => returns Object {id, width, height, body, sprite, symbol, svg}
+
+// Where:
+// id     = {String} icon id
+// width  = {Number} original pixel width
+// height = {Number} original pixel height
+// body   = {String} HTML content of <svg>
+// sprite = {String} HTML <svg> tag with <use> for sprite usage
+// symbol = {String} HTML <symbol> tag. Usefull when generating a sprite
+// svg    = {String} HTML the actual <svg>
 ```
 
-## FAQ
+---
 
-<details>
-<summary>Can I load a subset of icons?</summary>
-One of the missions of having a shared icon set, is to provide a consistent and predictable coding environment across platforms and products. Please include the full [`core-icons.min.js`](https://static.nrk.no/core-icons/latest/core-icons.min.js), even though your product currently is not using all icons.
-</details>
+## React API
 
-<details>
-<summary>How can I request a new icon?</summary>
-Please [see if your icon request already exists](https://github.com/nrkno/core-icons/issues?q=is%3Aissue+is%3Aopen+Icon+request), and add a +1 reaction if found. For [new icon requests](https://github.com/nrkno/core-icons/issues/new?title=Icon%20Request:%20&labels=enhancement), describe how you plan to use the icon and subjects to be covered. Icon requests are processed by the NRK Design Forum.
-</details>
+`@nrk/core-icons` provides a React/Preact API. You can access it as a NPM module:
 
-<details>
-<summary>Why loading icons as a javascript-file?</summary>
-SVG symbols are [great for styling and accessibility](https://css-tricks.com/svg-symbol-good-choice-icons/), but can not load cross domain, or from external file and in IE (9,10,11). Javascript provides us a cacheable, cross-domain method load the icons, without adding extra overhead to each html-file.
-</details>
+```jsx
+import CoreIcon from '@nrk/core-icons/jsx'
 
-<details>
-<summary>What is the naming convention?</summary>
-All icons are prefixed with nrk- to play nice with existing code. Furthermore, we follow [BEM name conventions](http://getbem.com/), so all related icons are scopes equally (i.e. `nrk-logo-` or `nrk-media-`), and postfixed with modifiers for states (i.e. `--active`)
-</details>
+<CoreIcon id='nrk-logo-nrk' />                          // Render a NRK logo
+<CoreIcon id='nrk-logo-nrk' style={{color: 'red'}} />   // Additional props will be used for attributes
+```
diff --git a/lib/icons.md b/lib/icons.md
diff --git a/lib/index.html b/lib/index.html
@@ -0,0 +1,105 @@
+<!doctype html>
+<html>
+<head>
+  <meta charset="utf-8"/>
+  <meta name="viewport" content="width=device-width, initial-scale=1">
+  <meta http-equiv="X-UA-Compatible" content="IE=edge">
+  <title>Core Components</title>
+  <link rel="stylesheet" href="https://static.nrk.no/core-css/major/1/core-css.min.css">
+  <link rel="stylesheet" href="https://static.nrk.no/core-fonts/major/2/core-fonts.min.css">
+  <style>
+    html { font: 100%/1.6 'LFT Etica',sans-serif; color: #26292a; scroll-behavior: smooth; -webkit-font-smoothing: antialiased }
+    pre, code { overflow: auto; background: #f0f5fe } pre { padding: 1em }
+    a { color: #0059b3 }
+
+    .doc-menu ul { list-style: none; margin: 0; padding: 0 30px; font-size: 14px; line-height: 30px }
+    .doc-menu ul ul a { overflow: hidden; max-height: 30px; animation: fadeIn .5s backwards }
+    .doc-menu a { display: block; color: inherit; text-decoration: none }
+    .doc-menu img { float: right; width: 16px; height: 30px }
+
+    .doc-main:empty { min-height: 9000px; opacity: 0 } /* Allow remember scroll position */
+    .doc-main { overflow: hidden; padding: 4rem 7vw; transition: 1s }
+    .doc-main p { max-width: 700px; margin-top: 0; font-size: 1.1rem }
+    .doc-main h1 { font-weight: 300; font-size: 3rem; line-height: 1; margin: 0 }
+    .doc-main h2 { font-weight: 300; font-size: 1.5em; line-height: 1.5; margin: .5em 0; max-width: 650px }
+    .doc-main h3 { font-weight: 600; font-size: 12px; margin: 2em 0 .5em; text-transform: uppercase }
+    .doc-main hr { border: 0; border-top: 1px solid #eee; margin: 4rem -7vw; width: calc(100% + 14vw) }
+    .doc-main ul { padding-left: 25px; list-style: url("data:image/svg+xml,%3Csvg width='25' height='10' viewBox='0 0 7 10' xmlns='http://www.w3.org/2000/svg'%3E%3Cpath d='M1 1l4 4-4 4' stroke='%23ccc' stroke-width='2' fill='none'/%3E%3C/svg%3E") }
+    .doc-main td code:only-child { display: block; padding: 1em; margin-right: 1em}
+    .doc-main th { font-weight: 600; font-size: 12px }
+    .doc-main table { width: 100% }
+
+    .doc-demo { background: #f0f5fe; padding: 1rem; margin: 1rem 0 }
+    .doc-demo summary { cursor: pointer; padding: 5px 1rem; font-weight: 600; font-size: 12px; border-top: 2px solid #fff }
+    .doc-demo details { margin: 1rem -1rem -1rem }
+    .doc-demo ul { list-style: none }
+
+    @keyframes fadeIn { from { max-height: 0 } }
+    @media(min-width:700px) {
+      .doc-menu { float: left; box-sizing: border-box; position: sticky; top: 0; padding: 70px 0; width: 270px; min-height: 100vh; border-right: 1px solid #eee }
+    }
+  </style>
+</head>
+<body>
+  <script src="https://static.nrk.no/core-masthead/major/1/core-masthead.html.js"></script>
+  <div class="doc-menu">
+    <ul>
+      <li><a href="?docs.md">Core Icons</a></li>
+      <li><br><a href="https://github.com/nrkno/core-icons"><img src="https://cdn.jsdelivr.net/npm/simple-icons@latest/icons/github.svg"> View on Github</a></li>
+      <li><a href="https://github.com/nrkno/core-icons/releases"><img src="https://rawgit.com/nrkno/core-icons/master/lib/nrk-poll.svg"> View changelog</a></li>
+      <li><a href="https://github.com/nrkno/core-icons/issues/new?title=Icon%20Request:%20&labels=enhancement"><img src="https://rawgit.com/nrkno/core-icons/master/lib/nrk-plus.svg"> Request new icon</a></li>
+    </ul>
+  </div>
+  <main class="doc-main"></main>
+  <script src="https://unpkg.com/react@16/umd/react.production.min.js"></script>
+  <script src="https://unpkg.com/react-dom@16/umd/react-dom.production.min.js"></script>
+  <script src="https://unpkg.com/code-prettify/loader/run_prettify.js"></script>
+  <script src="https://unpkg.com/@babel/standalone/babel.min.js"></script>
+  <script src="https://unpkg.com/marked/marked.min.js"></script>
+  <script defer>
+    (function(){
+      var file = location.search || document.querySelector('.doc-menu a').search
+      var link = document.querySelector('.doc-menu a[href*="' + file + '"]')
+      var main = document.querySelector('.doc-main')
+      var ajax = new XMLHttpRequest()
+      var mark = new marked.Renderer()
+
+      mark.code = code
+      ajax.onload = function () {
+        main.innerHTML = marked(ajax.responseText, {renderer: mark, gfm: true})
+        exec(main.querySelectorAll('script'), link && function () {
+          var toc = [].slice.call(document.querySelectorAll('h2[id]'), 1) // Skip first h2
+          link.style.fontWeight = 600
+          link.insertAdjacentHTML('afterend', '<ul><li>' + toc.map(function (h2) {
+            if (h2.id === location.hash.slice(1)) h2.scrollIntoView(), h2.focus() // Scroll to hash
+            return h2.outerHTML.replace('id="', 'href="#').replace(/h2/g, 'a') // Swap h2 to a
+          }).join('</li><li>') + '</li></ul>')
+        })
+      }
+      ajax.open('GET', file.slice(1), true)
+      ajax.send()
+
+      function code (code, lang) {
+        var raw = code.replace(/<!--\s*demo\s*-->\n*/i, '')
+        var esc = raw.replace(/&/g, '&amp;').replace(/"/g, '&quot;').replace(/'/g, '&#39;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+        var pre = '<pre><code>' + PR.prettyPrintOne(esc, lang) + '</code></pre>'
+        return raw === code ? pre : '<div class="doc-demo">' + raw + '<details><summary>CODE</summary>' + pre + '</details></div>'
+      }
+
+      function exec (scripts, callback) {
+        setTimeout(function () {
+          var source = scripts[0]
+          var target = document.createElement('script')
+          var onload = function () { exec([].slice.call(scripts, 1), callback) }
+
+          if (!source) return callback && callback()
+          else if (source.src) target.src = source.src, target.onload = onload
+          else target.appendChild(document.createTextNode(Babel.transform(source.textContent, {presets: ['es2015', 'react']}).code))
+          source.parentNode.replaceChild(target, source) // Replacing html with node causes script eval
+          if (!source.src) onload() // Inline script is loaded instantly
+        }, 16) // Let parser finish before next script eval
+      }
+    })()
+  </script>
+</body>
+</html>