SFDigitalServices
diff --git a/‎.eleventy.js
+1-14 b/‎.eleventy.js
+1-14
diff --git a/‎.eslintrc.js
+8-2 b/‎.eslintrc.js
+8-2
diff --git a/‎.github/workflows/ci.yml
+2-1 b/‎.github/workflows/ci.yml
+2-1
diff --git a/‎.markdownlint.yml
+15 b/‎.markdownlint.yml
+15
diff --git a/‎.stylelintrc.js
+23 b/‎.stylelintrc.js
+23
diff --git a/‎docs/_data/eleventyComputed.js
+4-2 b/‎docs/_data/eleventyComputed.js
+4-2
diff --git a/‎docs/_data/examples.js
-1 b/‎docs/_data/examples.js
-1
diff --git a/‎docs/_data/package.js
+1-1 b/‎docs/_data/package.js
+1-1
diff --git a/‎docs/_data/utilities.js
+41 b/‎docs/_data/utilities.js
+41
diff --git a/‎docs/_includes/toc.njk
+1-1 b/‎docs/_includes/toc.njk
+1-1
diff --git a/‎docs/components/buttons.md
+160-8 b/‎docs/components/buttons.md
+160-8
@@ -11,20 +11,6 @@ const toc = require('./lib/eleventy/toc')
 const { environment } = require('./lib/nunjucks')
 
 module.exports = config => {
-  if (dev) {
-    const throttle = 100
-    const reloadOnChange = require('./lib/eleventy/reload')
-    reloadOnChange(__filename, [
-      'lib/**/*.js',
-      // we need to watch these ones explicitly because they
-      // change how examples and color swatches are rendered
-      'docs/_includes/{example,macros}.njk'
-    ], throttle)
-
-    // throttle subsequent rebuilds
-    config.setWatchThrottleWaitTime(throttle)
-  }
-
   config.addPlugin(navigation)
   config.addPlugin(remark, remarkConfig)
   config.addPlugin(toc, {
@@ -38,6 +24,7 @@ module.exports = config => {
   config.setUseGitIgnore(false)
   config.addWatchTarget('./dist')
   config.addPassthroughCopy('dist')
+  config.addPassthroughCopy('docs/static')
 
   return {
     dir: {
 
@@ -1,14 +1,20 @@
 module.exports = {
   parser: '@babel/eslint-parser',
-  plugins: ['sfgov'],
+  plugins: [
+    'sfgov',
+    'unicorn'
+  ],
   extends: [
     'plugin:sfgov/recommended'
   ],
   rules: {
+    'unicorn/expiring-todo-comments': ['error', {
+      allowWarningComments: true
+    }]
   },
   overrides: [
     {
-      files: ['src/js/*.js', 'src/icons/index.js'],
+      files: ['src/**/*.js'],
       env: {
         browser: true
       },
 
@@ -10,8 +10,9 @@ jobs:
         with:
           node-version: 14
           cache: npm
-
       - run: npm ci
+
+      - uses: xt0rted/markdownlint-problem-matcher@v1
       - run: npm run lint
 
       # this sets NODE_ENV=production for all of the build scripts
 
@@ -0,0 +1,15 @@
+default: false
+heading-increment: true
+heading-style: atx
+first-heading-h1: { level: 2 }
+front-matter:
+  required_keys:
+    - title
+line-length: false
+links: true
+list-indent: true
+no-bare-urls: false
+no-empty: true
+ul-indent: { indent: 2, start_indented: false }
+ul-style: consistent
+whitespace: true
@@ -0,0 +1,23 @@
+module.exports = {
+  extends: [
+    'stylelint-config-standard'
+  ],
+  plugins: [
+    './lib/stylelint/expiring-todo-comments'
+  ],
+  rules: {
+    'at-rule-no-unknown': [true, {
+      ignoreAtRules: [
+        'apply',
+        'layer',
+        'responsive',
+        'screen',
+        'tailwind',
+        'variants'
+      ]
+    }],
+    'local/expiring-todo-comments': [true, {
+    }],
+    'string-quotes': 'single'
+  }
+}
@@ -44,6 +44,8 @@ function getLastCommitFromGit (path) {
 }
 
 async function getLastCommitFromGitHub (path) {
+  if (process.env.NODE_ENV === 'development') return null
+
   const args = { ...context, path, sha: branch, per_page: 1 }
 
   // console.info('getting last commit from github:', args)
@@ -53,7 +55,7 @@ async function getLastCommitFromGitHub (path) {
     res = await github.rest.repos.listCommits(args)
     commits = res.data
   } catch (error) {
-    console.warn('error loading commits for "%s"', path, error)
+    console.warn('error loading commits for "%s"', path)
     gitMetaCache.set(path, null)
     return null
   }
@@ -71,7 +73,7 @@ async function getLastCommitFromGitHub (path) {
     // console.info('caching git meta for "%s"', path, meta)
     return meta
   } else {
-    console.warn('unable to get commit for "%s"', path, res)
+    console.warn('unable to get commit for "%s"', path)
     return null
   }
 }
 
@@ -32,6 +32,5 @@ async function getExamples () {
     })
   }
 
-
   return examples
 }
@@ -30,6 +30,6 @@ async function getPublishedStatusVersion () {
       console.warn('no published version status for %s', sha, statuses)
     }
   } catch (error) {
-    console.warn('unable to get published version status:', error)
+    console.warn('unable to get published version status:', error.message)
   }
 }
@@ -0,0 +1,41 @@
+const postcss = require('postcss')
+const { readFileSync } = require('fs')
+
+const UTILITY_SELECTOR_PATTERN = /^\.[-:\w]+$/
+
+module.exports = function getUtilities () {
+  const css = readFileSync('dist/css/utilities.css', 'utf8')
+  const root = postcss.parse(css)
+  /** @type [postcss.Declaration] */
+  const decls = []
+  root.walkRules(rule => {
+    if (UTILITY_SELECTOR_PATTERN.test(rule.selector)) {
+      rule.walkDecls((decl, index) => {
+        decls.push(decl)
+      })
+    }
+  })
+
+  return {
+    decls,
+    byClassname: Object.fromEntries(
+      decls.map(decl => [
+        decl.parent.selector.substring(1),
+        decl
+      ])
+    ),
+    byProperty: groupBy(
+      decls,
+      decl => decl.prop
+    )
+  }
+}
+
+function groupBy (list /** @type [any] */, keyFunction /** type Function */) {
+  return list.reduce((map, d, i) => {
+    const key = keyFunction(d, i)
+    if (key in map) map[key].push(d)
+    else map[key] = [d]
+    return map
+  }, {})
+}
@@ -1,5 +1,5 @@
 <nav
-  class="sticky top-0 pl-16 py-4 border-0 border-l-2 border-solid border-slate"
+  class="sticky top-0 pl-16 py-4 bg-white border-0 border-l-2 border-solid border-slate"
   aria-hidden="true"
 >
   {% if title %}
 
@@ -1,38 +1,190 @@
 ---
 title: Buttons
 ---
+Use buttons for major actions.
 
-## Link buttons
+Buttons draw more attention than a simple text link. Because of their larger surface and color, they are visually more findable and easier to click or tap.
 
-This is some text about link buttons. We should explain why we want links to
-look like buttons.
+## When to use
+
+Use a button when an action has more weight or significance. Examples:
+
+* There is a clear primary action people should take
+* Highlighting a suggested action in a page section
+* A significant or destructive action will be applied and users need to be aware
+
+If the action should not be prompted, a text link may be a better option.
+
+## Types of buttons
+
+### Primary button
+
+This is the most common type of button. Use these to direct people to a clear primary action. To call out that these buttons are actionable, they are action blue (`{{ tokens.colors.action }}`).
+
+```html
+<button class="btn">
+  Do something
+</button>
+```
+
+Try not to have more than 1 primary button on a page. Multiple primary buttons puts more cognitive load on people. It takes them more time and effort to figure out what to do.
+
+### Inverse button
+
+On some backgrounds, the primary button color will not have sufficient contrast. In this case, use inverse buttons, which have a white fill.
+
+```html wrapper_class="bg-blue-dark p-20"
+<div class="bg-blue-dark">
+  <button class="btn btn-inverse">
+    Do something
+  </button>
+</div>
+```
+
+### Secondary button
+
+```html
+<button class="btn btn-secondary">
+  Do something
+</button>
+```
+
+Secondary buttons don’t have as much visual weight because they are outlined instead of solid. Use these if your button is not an important action on the page.
+
+Pair it side-by-side with a primary button to prompt toward the primary button’s action.
+
+```html id="buttons-side-by-side"
+<div class="flex gap-20">
+  <button class="btn btn-secondary">
+    Cancel
+  </button>
+  <button class="btn">
+    Continue
+  </button>
+</div>
+```
+
+## Variations
+
+### Block buttons
+
+Block buttons stretch to fill the width of the screen or area instead of having a set width. They are often used on mobile layouts.
+
+```html
+<div class="bg-blue-1 p-20 text-slate text-body">
+  <div>COVID-19 vaccination appointments available only for San Francisco Health Network patients.</div>
+  <button class="btn btn-block my-20">
+    Check for availability
+  </button>
+  <div class="text-center">
+    Or call <a href="tel:1234567890" class="text-action">123-456-7890</a>
+  </div>
+</div>
+```
+
+### Icons
+
+Icons can be on the left or right of the text in a button. Do not use more than one icon in a button.
+
+```html
+<div class="flex justify-around items-center gap-16 title-xs">
+  <a href="#" class="btn btn-secondary flex gap-8">
+    <sfgov-icon symbol="arrow-left"></sfgov-icon>
+    <span>Previous</span>
+  </a>
+  <a href="#" class="text-action">1</a>
+  <span>...</span>
+  <a href="#" class="text-action">8</a>
+  <a href="#" class="text-action">9</a>
+  <span>10</span>
+  <a href="#" class="text-action">11</a>
+  <a href="#" class="btn btn-secondary flex gap-8">
+    <span>Next</span>
+    <sfgov-icon symbol="arrow-right"></sfgov-icon>
+  </a>
+</div>
+```
+
+Icons should reinforce the meaning of the button’s text. In rare cases, an icon can be used without text. Only do this if the icon is extremely universally understood, such as an arrow or search magnifying glass. [Read more about icons](/foundations/icons/)
+
+## Appearance
+
+<img alt="" src="/static/images/button-specs.png" class="w-full">
+
+Buttons have:
+* corner radius of 8px
+* 8px padding on the top and bottom
+* 20px padding left and right, but can be variable on block buttons
+* Body Bold text
+
+## Usage
+
+### Alignment
+
+Buttons are typically left aligned with other content, not centered. For exceptions, see <a href="#block-buttons">block buttons</a>.
+
+| <img class="w-1/1" alt="Left aligned button with left aligned text" src="/static/images/alignment-correct.png"> | <img class="w-1/1" alt="Center aligned button with left aligned text" src="/static/images/alignment-incorrect.png"> |
+| ----------- | ----------- |
+| Yes      | No       |
+| Button is left aligned with other content | Button is centered |
+
+### Arrangement of multiple buttons
+
+For 2 or more button options, place them side by side instead of on top of one another if possible. This reduces the chance of accidentally clicking the wrong one and avoids alignment issues.
+
+| <div class="flex gap-20"><button class="btn btn-secondary">Cancel</button><button class="btn">Continue</button></div> | <div><button class="btn btn-secondary mb-20">Cancel</button><br><button class="btn mb-20">Continue</button></div> |
+| ----------- | ----------- |
+| Yes      | No       |
+| Choices are side by side | Choices are stacked |
+
+### Writing button text
+
+Button text should ideally be less than 15 characters. A maximum of 25 characters is OK if necessary.
+
+Refer to the [button text library](https://sfgovdt.jira.com/wiki/spaces/SFGOV/pages/3221651460/Button+text+library) for common button uses.
+
+Long button text is less legible, less impactful, and sometimes can even cause wrapping.
+
+| <button class="btn mb-48">Apply now</button> | <button class="btn mb-48">Apply now for your Small Business Grant</button> |
+| ----------- | ----------- |
+| Yes      | No       |
+| Button text is short | Button text is very long |
+
+| <button class="btn mb-20">Apply now</button> | <button class="btn mb-20">Apply now for your<br>Small Business Grant</button> |
+| ----------- | ----------- |
+| Yes      | No       |
+| Button text fits on one line | Button text wraps to fit |
+
+## HTML implementation
+
+Buttons styles can be applied to both HTML links (`<a>` elements) and interactive buttons (`<button>`).
+
+### Link buttons
 
-### Inline link
 ```html
 <a class="btn" href="#">
   This is a link
 </a>
 ```
 
 ### Block link
+
 ```html
 <a class="btn btn-block" href="#">
   This is a block link
 </a>
 ```
 
-## HTML buttons
-
-This is some text about actual styling actual `<button>` elements.
+### HTML buttons
 
-### Inline button
 ```html
 <button class="btn">
   This is a button
 </button>
 ```
 
 ### Block button
+
 ```html
 <button class="btn btn-block">
   This is a block button
Original file line number	Diff line number	Diff line change
`@@ -44,6 +44,8 @@ function getLastCommitFromGit (path) {`
`44`	`44`	`}`
`45`	`45`
`46`	`46`	`async function getLastCommitFromGitHub (path) {`
	`47`	`+ if (process.env.NODE_ENV === 'development') return null`
	`48`	`+`
`47`	`49`	`const args = { ...context, path, sha: branch, per_page: 1 }`
`48`	`50`
`49`	`51`	`// console.info('getting last commit from github:', args)`
`@@ -53,7 +55,7 @@ async function getLastCommitFromGitHub (path) {`
`53`	`55`	`res = await github.rest.repos.listCommits(args)`
`54`	`56`	`commits = res.data`
`55`	`57`	`} catch (error) {`
`56`		`- console.warn('error loading commits for "%s"', path, error)`
	`58`	`+ console.warn('error loading commits for "%s"', path)`
`57`	`59`	`gitMetaCache.set(path, null)`
`58`	`60`	`return null`
`59`	`61`	`}`
`@@ -71,7 +73,7 @@ async function getLastCommitFromGitHub (path) {`
`71`	`73`	`// console.info('caching git meta for "%s"', path, meta)`
`72`	`74`	`return meta`
`73`	`75`	`} else {`
`74`		`- console.warn('unable to get commit for "%s"', path, res)`
	`76`	`+ console.warn('unable to get commit for "%s"', path)`
`75`	`77`	`return null`
`76`	`78`	`}`
`77`	`79`	`}`
Original file line number	Diff line number	Diff line change
`@@ -32,6 +32,5 @@ async function getExamples () {`
`32`	`32`	`})`
`33`	`33`	`}`
`34`	`34`
`35`		`-`
`36`	`35`	`return examples`
`37`	`36`	`}`
Original file line number	Diff line number	Diff line change
`@@ -30,6 +30,6 @@ async function getPublishedStatusVersion () {`
`30`	`30`	`console.warn('no published version status for %s', sha, statuses)`
`31`	`31`	`}`
`32`	`32`	`} catch (error) {`
`33`		`- console.warn('unable to get published version status:', error)`
	`33`	`+ console.warn('unable to get published version status:', error.message)`
`34`	`34`	`}`
`35`	`35`	`}`
Original file line number	Diff line number	Diff line change
`@@ -1,5 +1,5 @@`
`1`	`1`	`<nav`
`2`		`- class="sticky top-0 pl-16 py-4 border-0 border-l-2 border-solid border-slate"`
	`2`	`+ class="sticky top-0 pl-16 py-4 bg-white border-0 border-l-2 border-solid border-slate"`
`3`	`3`	`aria-hidden="true"`
`4`	`4`	`>`
`5`	`5`	`{% if title %}`