From a0774cfec06a19c0874631613778ad05130867ad Mon Sep 17 00:00:00 2001 From: Sawyer Hollenshead Date: Sat, 3 Jun 2017 21:00:39 -0400 Subject: [PATCH] Docs: Add Guidelines (#68) * Nested Guidelines pages * Fix sort order of generated nav items * Update Getting Started page * Update Code conventions page * Add naming convention image * Update BEM syntax copy * Add credit links * Build documentation * Add Internationalization docs * Add Grid guidance Resolves https://jira.cms.gov/browse/HDSG-70 * Build docs --- docs/base/index.html | 14 +-- docs/base/typography/index.html | 16 +-- docs/components/alert/index.html | 36 +++--- docs/components/badge/index.html | 12 +- docs/components/button/index.html | 60 +++++----- docs/components/choice/index.html | 56 ++++----- docs/components/index.html | 8 +- docs/components/list/index.html | 12 +- docs/components/select/index.html | 48 ++++---- docs/components/table/index.html | 12 +- docs/components/tabs/index.html | 44 +++---- docs/components/text-field/index.html | 40 +++---- docs/components/vertical-nav/index.html | 14 +-- docs/core-concepts/index.html | 82 ------------- docs/guidelines/code-conventions/index.html | 73 +++++++++++ docs/guidelines/grid/index.html | 32 +++++ docs/guidelines/i18n/index.html | 32 +++++ docs/guidelines/responsive/index.html | 66 ++++++++++ docs/index.html | 89 ++++++++++---- docs/public/images/naming-convention.svg | 20 ++++ docs/public/scripts/index.js | 12 +- docs/public/styles/docs.css | 2 +- docs/responsive/index.html | 66 ---------- docs/utilities/background-color/index.html | 8 +- docs/utilities/border-radius/index.html | 10 +- docs/utilities/border/index.html | 8 +- docs/utilities/clearfix/index.html | 6 +- docs/utilities/color/index.html | 18 ++- docs/utilities/float/index.html | 16 +-- docs/utilities/font-family/index.html | 10 +- docs/utilities/font-size/index.html | 16 +-- docs/utilities/font-style/index.html | 10 +- docs/utilities/font-weight/index.html | 10 +- docs/utilities/index.html | 12 +- docs/utilities/line-height/index.html | 12 +- docs/utilities/margin/index.html | 14 +-- docs/utilities/measure/index.html | 12 +- docs/utilities/overflow/index.html | 6 +- docs/utilities/padding/index.html | 14 +-- docs/utilities/text-align/index.html | 16 +-- docs/utilities/text-decoration/index.html | 24 ++++ docs/utilities/text-transform/index.html | 12 +- docs/utilities/truncate/index.html | 10 +- docs/utilities/vertical-align/index.html | 12 +- docs/utilities/visibility/index.html | 24 ++-- packages/core/dist/components/Alert/Alert.css | 2 +- .../core/dist/components/Button/Button.css | 2 +- .../dist/components/ChoiceList/Choice.css | 2 +- packages/core/dist/index.css | 2 +- packages/core/dist/utilities/color.css | 2 +- packages/core/dist/utilities/index.css | 2 +- .../core/dist/utilities/text-decoration.css | 1 + .../docs/src/images/naming-convention.svg | 20 ++++ packages/docs/src/pages/core-concepts.md | 62 ---------- .../src/pages/guidelines/code-conventions.md | 46 +++++++ packages/docs/src/pages/guidelines/grid.md | 17 +++ packages/docs/src/pages/guidelines/i18n.md | 21 ++++ .../src/pages/{ => guidelines}/responsive.md | 0 packages/docs/src/pages/index.md | 113 ++++++++++++++---- packages/docs/src/scripts/components/Nav.jsx | 9 +- .../docs/src/scripts/components/NavItem.jsx | 16 ++- .../gulp/docs/__tests__/createRoutes.test.js | 73 +++++++++++ .../__tests__/processMarkdownPage.test.js | 12 +- tools/gulp/docs/convertMarkdownPages.js | 60 ++++++++-- tools/gulp/docs/createRoutes.js | 64 ++++++++++ tools/gulp/docs/docs.js | 20 +--- tools/gulp/docs/generatePage.js | 12 +- tools/gulp/docs/nestSections.js | 2 +- tools/gulp/docs/processMarkdownPage.js | 12 +- 69 files changed, 1071 insertions(+), 627 deletions(-) delete mode 100644 docs/core-concepts/index.html create mode 100644 docs/guidelines/code-conventions/index.html create mode 100644 docs/guidelines/grid/index.html create mode 100644 docs/guidelines/i18n/index.html create mode 100644 docs/guidelines/responsive/index.html create mode 100644 docs/public/images/naming-convention.svg delete mode 100644 docs/responsive/index.html create mode 100644 docs/utilities/text-decoration/index.html create mode 100644 packages/core/dist/utilities/text-decoration.css create mode 100644 packages/docs/src/images/naming-convention.svg delete mode 100644 packages/docs/src/pages/core-concepts.md create mode 100644 packages/docs/src/pages/guidelines/code-conventions.md create mode 100644 packages/docs/src/pages/guidelines/grid.md create mode 100644 packages/docs/src/pages/guidelines/i18n.md rename packages/docs/src/pages/{ => guidelines}/responsive.md (100%) create mode 100644 tools/gulp/docs/__tests__/createRoutes.test.js create mode 100644 tools/gulp/docs/createRoutes.js diff --git a/docs/base/index.html b/docs/base/index.html index f5571590f9..d436197e74 100644 --- a/docs/base/index.html +++ b/docs/base/index.html @@ -1,5 +1,5 @@ - + @@ -10,26 +10,26 @@
-
Alpha status: The design system is under active development and working towards a 1.0 release.

Base

base/body.scss:4

A base layer of styling can be applied to an area of your site by adding the ds-base class. If you're implementing the design system on a new site, you would likely want to apply this class to the <body> element. On existing sites this might not be feasible and introduce unintended side effects. In which case, you could apply the ds-base class to an element which scopes the styling to its decendants.

+
Alpha status: The design system is under active development and working towards a 1.0 release.

Base

base/body.scss:4

A base layer of styling can be applied to an area of your site by adding the ds-base class. If you're implementing the design system on a new site, you would likely want to apply this class to the <body> element. On existing sites this might not be feasible and introduce unintended side effects. In which case, you could apply the ds-base class to an element which scopes the styling to its decendants.

Specifically, the base styling sets the following properties:

  • color
  • font-family
  • font-size
  • line-height
    • -
+
We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America. -
Code snippet
<div class="ds-base ds-u-padding--2">
+
Code snippet
<div class="ds-base ds-u-padding--2">
  We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.
-</div>

Modifier: ds-base--inverse

Applies an inverse color and background-color

+</div>

Modifier: ds-base--inverse

Applies an inverse color and background-color

We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America. -
Code snippet
<div class="ds-base ds-base--inverse ds-u-padding--2">
+
Code snippet
<div class="ds-base ds-base--inverse ds-u-padding--2">
  We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.
 </div>
diff --git a/docs/base/typography/index.html b/docs/base/typography/index.html index dfd1522e6d..1d1fb1f001 100644 --- a/docs/base/typography/index.html +++ b/docs/base/typography/index.html @@ -1,5 +1,5 @@ - + @@ -10,7 +10,7 @@
-
Alpha status: The design system is under active development and working towards a 1.0 release.

Typography

base/typography.scss:4
Usage

The design system does not style base HTML text elements (like h1, h2, p, etc) and you should instead use one of the base class names to apply type styling. The base typography classes are:

+
Alpha status: The design system is under active development and working towards a 1.0 release.

Typography

base/typography.scss:4
Usage

The design system does not style base HTML text elements (like h1, h2, p, etc) and you should instead use one of the base class names to apply type styling. The base typography classes are:

  • ds-display
  • ds-title
    • @@ -18,7 +18,7 @@
  • ds-text--[modifier]

See the examples below to see how each of these can be used.

-

Utility classes can also be used to change type features like font size, color, weight, and style.

Lead paragraph. We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.

+

Utility classes can also be used to change type features like font size, color, weight, and style.

Lead paragraph. We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.

Body paragraph. We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.

Display

We the People of the United States, in Order to form a more perfect Union

@@ -35,7 +35,7 @@

Heading 4

Heading 5

We the People of the United States, in Order to form a more perfect Union

Heading 6

-

We the People of the United States, in Order to form a more perfect Union

Code snippet
<p class="ds-text--lead"><strong>Lead paragraph.</strong> We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.</p>
+  
We the People of the United States, in Order to form a more perfect Union
Code snippet
<p class="ds-text--lead"><strong>Lead paragraph.</strong> We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.</p>
 <p class="ds-text"><strong>Body paragraph.</strong> We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.</p>
 <h1 class="ds-display">Display</h1>
   <p class="ds-text ds-u-color--muted">We the People of the United States, in Order to form a more perfect Union</p>
@@ -52,15 +52,15 @@ 
Heading 6

 <h1 class="ds-h5">Heading 5</h1>
   <p class="ds-text ds-u-color--muted">We the People of the United States, in Order to form a more perfect Union</p>
 <h1 class="ds-h6">Heading 6</h1>
-  <p class="ds-text ds-u-color--muted">We the People of the United States, in Order to form a more perfect Union</p>

Responsive

+ <p class="ds-text ds-u-color--muted">We the People of the United States, in Order to form a more perfect Union</p>

Responsive

Responsive typography can be accomplished by using the responsive prefixed font size utility class. Since the base typography margins and line height is measured in em units, they'll automatically adjust as you change the font size.

You likely don't need to do this for type that is already small, like ds-text, ds-h6, and ds-h5

-

Resize your browser to see each breakpoint in action:

+

Resize your browser to see each breakpoint in action:

Responsive heading

We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America. -

Code snippet
<h2 class="ds-h4 ds-u-sm-font-size--h3 ds-u-md-font-size--h2 ds-u-lg-font-size--h1">
+
Code snippet
<h2 class="ds-h4 ds-u-sm-font-size--h3 ds-u-md-font-size--h2 ds-u-lg-font-size--h1">
   Responsive heading
 </h2>
 <p class="ds-text ds-u-font-size--small ds-u-md-font-size--base ds-u-lg-font-size--lead">
@@ -69,7 +69,7 @@ 
Heading 6
diff --git a/docs/components/alert/index.html b/docs/components/alert/index.html index 9fa8f52d02..d66e2e0d6b 100644 --- a/docs/components/alert/index.html +++ b/docs/components/alert/index.html @@ -1,5 +1,5 @@ - + @@ -10,47 +10,47 @@
-
Alpha status: The design system is under active development and working towards a 1.0 release.
prototype

Alert

components/Alert/Alert.scss:3

US Web Design Standard

UsageGuidance

Alerts keep users informed of important and sometimes time-sensitive changes.

+
Alpha status: The design system is under active development and working towards a 1.0 release.
prototype

Alert

components/Alert/Alert.scss:3

US Web Design Standard

UsageGuidance

Alerts keep users informed of important and sometimes time-sensitive changes.

Status heading

Lorem ipsum dolor sit link text, consectetur adipiscing elit, sed do eiusmod.

-
Code snippet
<div class="ds-c-alert">
+
Code snippet
<div class="ds-c-alert">
   <div class="ds-c-alert__body">
     <h3 class="ds-c-alert__heading">Status heading</h3>
     <p class="ds-c-alert__text">Lorem ipsum dolor sit <a href="http://example.com">link text</a>, consectetur adipiscing elit, sed do eiusmod.</p>
   </div>
-</div>

Modifier: ds-c-alert--error

Error message

+</div>

Modifier: ds-c-alert--error

Error message

Status heading

Lorem ipsum dolor sit link text, consectetur adipiscing elit, sed do eiusmod.

-
Code snippet
<div class="ds-c-alert ds-c-alert--error">
+
Code snippet
<div class="ds-c-alert ds-c-alert--error">
   <div class="ds-c-alert__body">
     <h3 class="ds-c-alert__heading">Status heading</h3>
     <p class="ds-c-alert__text">Lorem ipsum dolor sit <a href="http://example.com">link text</a>, consectetur adipiscing elit, sed do eiusmod.</p>
   </div>
-</div>

Modifier: ds-c-alert--warn

Warning message

+</div>

Modifier: ds-c-alert--warn

Warning message

Status heading

Lorem ipsum dolor sit link text, consectetur adipiscing elit, sed do eiusmod.

-
Code snippet
<div class="ds-c-alert ds-c-alert--warn">
+
Code snippet
<div class="ds-c-alert ds-c-alert--warn">
   <div class="ds-c-alert__body">
     <h3 class="ds-c-alert__heading">Status heading</h3>
     <p class="ds-c-alert__text">Lorem ipsum dolor sit <a href="http://example.com">link text</a>, consectetur adipiscing elit, sed do eiusmod.</p>
   </div>
-</div>

Modifier: ds-c-alert--success

Success message

+</div>

Modifier: ds-c-alert--success

Success message

Status heading

Lorem ipsum dolor sit link text, consectetur adipiscing elit, sed do eiusmod.

-
Code snippet
<div class="ds-c-alert ds-c-alert--success">
+
Code snippet
<div class="ds-c-alert ds-c-alert--success">
   <div class="ds-c-alert__body">
     <h3 class="ds-c-alert__heading">Status heading</h3>
     <p class="ds-c-alert__text">Lorem ipsum dolor sit <a href="http://example.com">link text</a>, consectetur adipiscing elit, sed do eiusmod.</p>
   </div>
-</div>

Other patterns

+</div>

Other patterns

We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.

@@ -70,7 +70,7 @@

Status heading

Link text
-
Code snippet
<div class="ds-c-alert">
+
Code snippet
<div class="ds-c-alert">
   <div class="ds-c-alert__body">
     <p class="ds-c-alert__text">We the People of the United States, in Order to form a more perfect Union, establish Justice, insure domestic Tranquility, provide for the common defence, promote the general Welfare, and secure the Blessings of Liberty to ourselves and our Posterity, do ordain and establish this Constitution for the United States of America.</p>
   </div>
@@ -90,24 +90,24 @@ 
Status heading

     </ul>
     <a href="http://example.com">Link text</a>
   </div>
-</div>
+</div>

Status heading

Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod.

-
Code snippet
<div class="ds-base--inverse ds-u-padding--2">
+
Code snippet
<div class="ds-base--inverse ds-u-padding--2">
   <div class="ds-c-alert">
     <div class="ds-c-alert__body">
       <h3 class="ds-c-alert__heading">Status heading</h3>
       <p class="ds-c-alert__text">Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod.</p>
     </div>
   </div>
-</div>

React

components/Alert/Alert

A react component

This is an example of a React Alert component.
Code snippet
<Alert heading="A react component">
+</div>

React

components/Alert/Alert

A react component

This is an example of a React Alert component.
Code snippet
<Alert heading="A react component">
   This is an example of a React Alert component.
-</Alert>

Props

NameTypeDefaultDescription
headingstring
role'alert', 'alertdialog'

ARIA role

-
variation'error', 'warn', 'success'
diff --git a/docs/components/badge/index.html b/docs/components/badge/index.html index f4bc0d49f0..91bfdd4c2a 100644 --- a/docs/components/badge/index.html +++ b/docs/components/badge/index.html @@ -1,5 +1,5 @@ - + @@ -10,15 +10,15 @@
-
Alpha status: The design system is under active development and working towards a 1.0 release.
prototype

Badge

components/Badge/Badge

Badges draw attention to new or important content.

New -Due: December 31, 2018
Code snippet
<span class="ds-c-badge">New</span>
-<span class="ds-c-badge ds-u-fill--error">Due: December 31, 2018</span>
Today
Code snippet
<Badge>
+      
Alpha status: The design system is under active development and working towards a 1.0 release.
prototype
Badge
components/Badge/Badge
Badges draw attention to new or important content.
New
+Due: December 31, 2018
Code snippet
<span class="ds-c-badge">New</span>
+<span class="ds-c-badge ds-u-fill--error">Due: December 31, 2018</span>
Today
Code snippet
<Badge>
   Today
-</Badge>
Props
NameTypeDefaultDescription

+</Badge>

Props

NameTypeDefaultDescription
diff --git a/docs/components/button/index.html b/docs/components/button/index.html index 6143d1a182..5b46ce8eeb 100644 --- a/docs/components/button/index.html +++ b/docs/components/button/index.html @@ -1,5 +1,5 @@ - + @@ -10,56 +10,56 @@
-
Alpha status: The design system is under active development and working towards a 1.0 release.
prototype

Button

components/Button/Button.scss:4
UsageGuidance

Use buttons to signal actions.

Link +
Alpha status: The design system is under active development and working towards a 1.0 release.
prototype

Button

components/Button/Button.scss:4
UsageGuidance

Use buttons to signal actions.

Link -
Code snippet
<a href="http://example.com" class="ds-c-button">Link</a>
+
Code snippet
<a href="http://example.com" class="ds-c-button">Link</a>
 <button type="button" class="ds-c-button ds-c-button--small">Button</button>
 <button type="button" class="ds-c-button">Button</button>
-<button type="button" class="ds-c-button ds-c-button--big">Button</button>

Modifier: ds-c-button--primary

The primary call-to-action

Link +<button type="button" class="ds-c-button ds-c-button--big">Button</button>

Modifier: ds-c-button--primary

The primary call-to-action

Link -
Code snippet
<a href="http://example.com" class="ds-c-button ds-c-button--primary">Link</a>
+
Code snippet
<a href="http://example.com" class="ds-c-button ds-c-button--primary">Link</a>
 <button type="button" class="ds-c-button ds-c-button--primary ds-c-button--small">Button</button>
 <button type="button" class="ds-c-button ds-c-button--primary">Button</button>
-<button type="button" class="ds-c-button ds-c-button--primary ds-c-button--big">Button</button>

Modifier: ds-c-button--transparent

A button closer to resembling an anchor element

Link +<button type="button" class="ds-c-button ds-c-button--primary ds-c-button--big">Button</button>

Modifier: ds-c-button--transparent

A button closer to resembling an anchor element

Link -
Code snippet
<a href="http://example.com" class="ds-c-button ds-c-button--transparent">Link</a>
+
Code snippet
<a href="http://example.com" class="ds-c-button ds-c-button--transparent">Link</a>
 <button type="button" class="ds-c-button ds-c-button--transparent ds-c-button--small">Button</button>
 <button type="button" class="ds-c-button ds-c-button--transparent">Button</button>
-<button type="button" class="ds-c-button ds-c-button--transparent ds-c-button--big">Button</button>

Modifier: ds-c-button--danger

Indicates an action is destructive or dangerous

Link +<button type="button" class="ds-c-button ds-c-button--transparent ds-c-button--big">Button</button>

Modifier: ds-c-button--danger

Indicates an action is destructive or dangerous

Link -
Code snippet
<a href="http://example.com" class="ds-c-button ds-c-button--danger">Link</a>
+
Code snippet
<a href="http://example.com" class="ds-c-button ds-c-button--danger">Link</a>
 <button type="button" class="ds-c-button ds-c-button--danger ds-c-button--small">Button</button>
 <button type="button" class="ds-c-button ds-c-button--danger">Button</button>
-<button type="button" class="ds-c-button ds-c-button--danger ds-c-button--big">Button</button>

Modifier: ds-c-button--success

Indicates a positive or successful action

Link +<button type="button" class="ds-c-button ds-c-button--danger ds-c-button--big">Button</button>

Modifier: ds-c-button--success

Indicates a positive or successful action

Link -
Code snippet
<a href="http://example.com" class="ds-c-button ds-c-button--success">Link</a>
+
Code snippet
<a href="http://example.com" class="ds-c-button ds-c-button--success">Link</a>
 <button type="button" class="ds-c-button ds-c-button--success ds-c-button--small">Button</button>
 <button type="button" class="ds-c-button ds-c-button--success">Button</button>
-<button type="button" class="ds-c-button ds-c-button--success ds-c-button--big">Button</button>

Disabled button

-
Code snippet
<button class="ds-c-button ds-c-button--disabled">Button</button>
-<input disabled type="submit" class="ds-c-button" />

Inverse theme

+<button type="button" class="ds-c-button ds-c-button--success ds-c-button--big">Button</button>

Disabled button

+
Code snippet
<button class="ds-c-button ds-c-button--disabled">Button</button>
+<input disabled type="submit" class="ds-c-button" />

Inverse theme

-
Code snippet
<div class="ds-base--inverse ds-u-padding--2">
+
Code snippet
<div class="ds-base--inverse ds-u-padding--2">
   <button class="ds-c-button ds-c-button--inverse">Button</button>
   <button class="ds-c-button ds-c-button--transparent-inverse">Button</button>
   <button class="ds-c-button ds-c-button--primary">Button</button>
   <button class="ds-c-button ds-c-button--danger">Button</button>
   <button class="ds-c-button ds-c-button--success">Button</button>
   <button class="ds-c-button ds-c-button--disabled-inverse">Button</button>
-</div>

Button icons

components/Button/Button.scss:212
    +</div>

Button icons

components/Button/Button.scss:212
  • Add an inline SVG icon and it will become the same color as the button text. For the crispest icon rendering, ensure the icon has a square viewBox with values that are multiples of 8 (ie. 24x24).
  • Use the margin utility class to add spacing between the icon and button text.
    • -
Code snippet
<button class="ds-c-button">
+
Code snippet
<button class="ds-c-button">
   <svg class="ds-u-margin-right--1" xmlns="http://www.w3.org/2000/svg" aria-hidden="true" viewBox="0 0 24 24">
     <use xlink:href="/design-system/public/images/symbols.svg#download"></use>
   </svg>Left icon
@@ -83,14 +83,16 @@
 </button>
 <button class="ds-c-button ds-c-button--outline">
   No icon
-</button>

React

components/Button/Button

The Button component accepts its text as children (AKA inner HTML), which +</button>

Button inline with field

components/Button/Button.scss:240

The button is the same height as a single-line text field.

+
Code snippet
<input type="text" class="ds-c-field ds-u-display--inline-block" />
+<button class="ds-c-button">Submit</button>

React

components/Button/Button

The Button component accepts its text as children (AKA inner HTML), which means you can also pass in HTML or custom components. This gives you a lot of flexibility and supports a variety of advanced use cases. The most common use case would be passing in an SVG icon along with the text.

In addition to the supported props listed, you can also pass in additional props, which will be passed to the rendered root component. For example, you could pass in a target prop to pass to the rendered anchor element.

-
Code snippet
<div>
+
Code snippet
<div>
   <Button>
     React button
   </Button>
@@ -102,17 +104,17 @@
   >
     React anchor button
   </Button>
-</div>

Props

NameTypeDefaultDescription
classNamestring

Additional classes to be added to the root button element. +</div>

Props

NameTypeDefaultDescription
classNamestring

Additional classes to be added to the root button element. Useful for adding utility classes.

-
componentelement, func

When provided, this will render the passed in component. This is useful when +

componentelement, func

When provided, this will render the passed in component. This is useful when integrating with React Router's <Link> or using your own custom component.

-
disabledbool
hrefstring

When provided the root component will render as an <a> element +

disabledbool
hrefstring

When provided the root component will render as an <a> element rather than button.

-
inversebool

Applies the inverse theme styling

-
onClickfunc

Returns the SyntheticEvent. +

inversebool

Applies the inverse theme styling

+
onClickfunc

Returns the SyntheticEvent. Not called when the button is disabled.

-
size'small', 'big'
type'button', 'submit''button'

Button type attribute

-
variation'primary', 'danger', 'success', 'transparent'
size'small', 'big'
type'button', 'submit''button'

Button type attribute

+
variation'primary', 'danger', 'success', 'transparent'
diff --git a/docs/components/choice/index.html b/docs/components/choice/index.html index 8e988550e7..4622333bad 100644 --- a/docs/components/choice/index.html +++ b/docs/components/choice/index.html @@ -1,5 +1,5 @@ - + @@ -10,7 +10,7 @@
-
Alpha status: The design system is under active development and working towards a 1.0 release.
prototype

Checkbox & Radio

components/ChoiceList/Choice.scss:18

US Web Design Standard

UsageGuidance

Checkbox

components/ChoiceList/Choice.scss:28

Checkboxes allow users to select one or more options from a visible list.

+
Alpha status: The design system is under active development and working towards a 1.0 release.
prototype

Checkbox & Radio

components/ChoiceList/Choice.scss:18

US Web Design Standard

UsageGuidance

Checkbox

components/ChoiceList/Choice.scss:28

Checkboxes allow users to select one or more options from a visible list.

Historical figures Select all that apply @@ -34,7 +34,7 @@
-
Code snippet
<fieldset class="ds-c-fieldset ds-u-margin-top--0">
+
Code snippet
<fieldset class="ds-c-fieldset ds-u-margin-top--0">
   <legend class="ds-c-label">Historical figures</legend>
   <span class="ds-c-field__hint">Select all that apply</span>
   <input class="ds-c-choice" id="truth-1" type="checkbox" name="historical-figures-1" value="truth" checked>
@@ -58,7 +58,7 @@
     <input class="ds-c-choice ds-c-choice--inverse" id="carver-2" type="checkbox" name="historical-figures-2" disabled>
     <label for="carver-2">George Washington Carver</label>
   </fieldset>
-</div>

Radio option

components/ChoiceList/Choice.scss:63
+</div>

Radio option

components/ChoiceList/Choice.scss:63
Select a historical figure @@ -77,7 +77,7 @@
-
Code snippet
<fieldset class="ds-c-fieldset ds-u-margin-top--0">
+
Code snippet
<fieldset class="ds-c-fieldset ds-u-margin-top--0">
   <legend class="ds-c-label">Select a historical figure</legend>
   <input class="ds-c-choice" id="truth-3" type="radio" name="historical-figures-3" value="truth" checked>
   <label for="truth-3">Sojourner Truth</label>
@@ -96,11 +96,11 @@
     <input class="ds-c-choice ds-c-choice--inverse" id="washington-4" type="radio" name="historical-figures-4" value="washington">
     <label for="washington-4">Booker T. Washington</label>
   </fieldset>
-</div>

React - <Choice>

components/ChoiceList/Choice

A Choice component can be used to render a checkbox or radio button. +</div>

React - <Choice>

components/ChoiceList/Choice

A Choice component can be used to render a checkbox or radio button. Any undocumented props that you pass to this component will be passed to the input element, so you can use this to set additional attributes if necessary.

-
Code snippet
<div>
+
Code snippet
<div>
   <Choice
     defaultChecked
     name="checkbox_choice"
@@ -136,25 +136,25 @@
   >
     Radio B
   </Choice>
-</div>

Props

NameTypeDefaultDescription
checkedbool

Setting this prop will render a read-only field and require an onChange +</div>

Props

NameTypeDefaultDescription
checkedbool

Setting this prop will render a read-only field and require an onChange event handler if you'd want to check its checked stated. Use defaultChecked if you want the field to be mutable.

-
classNamestring

Additional classes to be added to the root div element.

-
defaultCheckedbool

Sets the initial checked state and allows the user to check/uncheck the +

classNamestring

Additional classes to be added to the root div element.

+
defaultCheckedbool

Sets the initial checked state and allows the user to check/uncheck the field without also requiring an onChange event handler.

-
idstring

A unique ID to be used for the input field, as well as the label's +

idstring

A unique ID to be used for the input field, as well as the label's for attribute. A unique ID will be generated if one isn't provided.

-
inversedbool

Applies the "inverse" UI theme

-
name

Required

string

The input name attribute

-
onBlurfunc
onChangefunc
type'checkbox', 'radio''checkbox'
value

Required

number, string

The input value attribute

-

React - <ChoiceList>

components/ChoiceList/ChoiceList

A ChoiceList component can be used to render a select menu, radio +

inversedbool

Applies the "inverse" UI theme

+
name

Required

string

The input name attribute

+
onBlurfunc
onChangefunc
type'checkbox', 'radio''checkbox'
value

Required

number, string

The input value attribute

+

React - <ChoiceList>

components/ChoiceList/ChoiceList

A ChoiceList component can be used to render a select menu, radio button group, or checkbox group, and their corresponding label or legend.

You can manually pass in the type prop, but the real power of this component is unleashed when you let it determine the type of fields for you. It takes into account accessibility and usability best practices, so you can pass in an array of choices and let it determine whether the choices should be presented as radio buttons, checkboxes, or a select menu.

-
Radio example
Checkbox exampleExample error message
Code snippet
<div>
+
Radio example
Checkbox exampleExample error message
Code snippet
<div>
   <ChoiceList
     choices={[
       {
@@ -290,22 +290,22 @@
       name="select_choices_field_inverse"
     />
   </div>
-</div>

Props

NameTypeDefaultDescription
choices

Required

arrayOf[{checked, defaultChecked, disabled, label, value}]

The list of choices to be rendered. The number of choices you pass in may +</div>

Props

NameTypeDefaultDescription
choices

Required

arrayOf[{checked, defaultChecked, disabled, label, value}]

The list of choices to be rendered. The number of choices you pass in may affect the type of field(s) rendered. See type for more info.

-
classNamestring

Additional classes to be added to the root element.

-
disabledbool

Disables the entire field.

-
errorMessagestring
hintnode

Hint text

-
inversedbool

Applies the "inverse" UI theme

-
label

Required

node

The label for the entire list of choices

-
labelClassNamestring

Additional classes to be added to the FormLabel.

-
multiplebool

Allows the user to select multiple choices. Setting this to true results +

classNamestring

Additional classes to be added to the root element.

+
disabledbool

Disables the entire field.

+
errorMessagestring
hintnode

Hint text

+
inversedbool

Applies the "inverse" UI theme

+
label

Required

node

The label for the entire list of choices

+
labelClassNamestring

Additional classes to be added to the FormLabel.

+
multiplebool

Allows the user to select multiple choices. Setting this to true results in a list of checkbox fields to be rendered.

-
name

Required

string
onBlurfunc
onChangefunc
type'checkbox', 'radio', 'select'

You can manually set the type if you prefer things to be less magical. +

name

Required

string
onBlurfunc
onChangefunc
type'checkbox', 'radio', 'select'

You can manually set the type if you prefer things to be less magical. Otherwise, the type will be inferred by the other props, based on what's best for accessibility and usability. If multiple is true, then checkbox fields will be rendered. If less than 10 choices are passed in, then radio buttons will be rendered.

-
diff --git a/docs/components/index.html b/docs/components/index.html index 266dde5207..3b45d44c57 100644 --- a/docs/components/index.html +++ b/docs/components/index.html @@ -1,5 +1,5 @@ - + @@ -10,12 +10,12 @@
-
Alpha status: The design system is under active development and working towards a 1.0 release.

Components

components/_index.scss:1

Component class names follow the format: ds-c-[BLOCK]__[ELEMENT]--[MODIFIER]

+
Alpha status: The design system is under active development and working towards a 1.0 release.

Components

components/_index.scss:1

Component class names follow the format: ds-c-[BLOCK]__[ELEMENT]--[MODIFIER]

Components are designed, self-contained UI elements. In most cases a component will also have a corresponding React component.

diff --git a/docs/components/list/index.html b/docs/components/list/index.html index 7c8b7735f4..566ec186f2 100644 --- a/docs/components/list/index.html +++ b/docs/components/list/index.html @@ -1,5 +1,5 @@ - + @@ -10,23 +10,23 @@
-
Alpha status: The design system is under active development and working towards a 1.0 release.
prototype

List

components/List/List.scss:4
Code snippet
<ul class="ds-c-list">
   <li>List item 1</li>
   <li>List item 2</li>
-</ul>

Modifier: ds-c-list--bare

Unstyled list (no margin, padding or list-style)

    +</ul>

Modifier: ds-c-list--bare

Unstyled list (no margin, padding or list-style)

  • List item 1
  • List item 2
    • -
Code snippet
<ul class="ds-c-list ds-c-list--bare">
+
Code snippet
<ul class="ds-c-list ds-c-list--bare">
   <li>List item 1</li>
   <li>List item 2</li>
 </ul>
diff --git a/docs/components/select/index.html b/docs/components/select/index.html index 437f8a938e..0889aad2b9 100644 --- a/docs/components/select/index.html +++ b/docs/components/select/index.html @@ -1,5 +1,5 @@ - + @@ -10,7 +10,7 @@
-
Alpha status: The design system is under active development and working towards a 1.0 release.
prototype

Select

components/ChoiceList/Select.scss:3

US Web Design Standard

UsageGuidance

A select field allows users to select one option from a list.

+
Alpha status: The design system is under active development and working towards a 1.0 release.
prototype

Select

components/ChoiceList/Select.scss:3

US Web Design Standard

UsageGuidance

A select field allows users to select one option from a list.

-
Code snippet
<label class="ds-c-label ds-u-margin-top--0" for="options">Field label</label>
+
Code snippet
<label class="ds-c-label ds-u-margin-top--0" for="options">Field label</label>
 <select class="ds-c-field ds-c-field--select" name="options" id="options">
   <option value="value1">Option A</option>
   <option value="value2">Option B</option>
@@ -36,11 +36,11 @@
     <option value="value2">Option B</option>
     <option value="value3">Option C</option>
   </select>
-</div>

React - <Select>

components/ChoiceList/Select

A Select component can be used to render an HTML select menu. +</div>

React - <Select>

components/ChoiceList/Select

A Select component can be used to render an HTML select menu. Any undocumented props that you pass to this component will be passed to the select element, so you can use this to set additional attributes if necessary.

-
Code snippet
<Select
+
Code snippet
<Select
   defaultValue="2"
   name="select-demo"
 >
@@ -53,25 +53,25 @@
   <option value="3">
     Option 3
   </option>
-</Select>

Props

NameTypeDefaultDescription
classNamestring

Additional classes to be added to the root select element.

-
defaultValuestring

Sets the initial selected state and allows the user to select a different +</Select>

Props

NameTypeDefaultDescription
classNamestring

Additional classes to be added to the root select element.

+
defaultValuestring

Sets the initial selected state and allows the user to select a different option without also requiring an onChange event handler.

-
disabledbool
idstring

A unique ID to be used for the select field. A unique ID will be generated +

disabledbool
idstring

A unique ID to be used for the select field. A unique ID will be generated if one isn't provided.

-
inversedbool

Applies the "inverse" UI theme

-
multiplecustom

Setting this prop to true will result in an error message due to +

inversedbool

Applies the "inverse" UI theme

+
multiplecustom

Setting this prop to true will result in an error message due to accessibility concerns. See the usability guidelines for more info.

-
name

Required

string
onBlurfunc
onChangefunc
valuestring

Setting this prop will render a read-only field and require an onChange +

name

Required

string
onBlurfunc
onChangefunc
valuestring

Setting this prop will render a read-only field and require an onChange event handler if you'd want to change its selected stated. Use defaultValue if you want the field to be mutable.

-

React - <ChoiceList>

components/ChoiceList/ChoiceList

A ChoiceList component can be used to render a select menu, radio +

React - <ChoiceList>

components/ChoiceList/ChoiceList

A ChoiceList component can be used to render a select menu, radio button group, or checkbox group, and their corresponding label or legend.

You can manually pass in the type prop, but the real power of this component is unleashed when you let it determine the type of fields for you. It takes into account accessibility and usability best practices, so you can pass in an array of choices and let it determine whether the choices should be presented as radio buttons, checkboxes, or a select menu.

-
Radio example
Checkbox exampleExample error message
Code snippet
<div>
+
Radio example
Checkbox exampleExample error message
Code snippet
<div>
   <ChoiceList
     choices={[
       {
@@ -207,22 +207,22 @@
       name="select_choices_field_inverse"
     />
   </div>
-</div>

Props

NameTypeDefaultDescription
choices

Required

arrayOf[{checked, defaultChecked, disabled, label, value}]

The list of choices to be rendered. The number of choices you pass in may +</div>

Props

NameTypeDefaultDescription
choices

Required

arrayOf[{checked, defaultChecked, disabled, label, value}]

The list of choices to be rendered. The number of choices you pass in may affect the type of field(s) rendered. See type for more info.

-
classNamestring

Additional classes to be added to the root element.

-
disabledbool

Disables the entire field.

-
errorMessagestring
hintnode

Hint text

-
inversedbool

Applies the "inverse" UI theme

-
label

Required

node

The label for the entire list of choices

-
labelClassNamestring

Additional classes to be added to the FormLabel.

-
multiplebool

Allows the user to select multiple choices. Setting this to true results +

classNamestring

Additional classes to be added to the root element.

+
disabledbool

Disables the entire field.

+
errorMessagestring
hintnode

Hint text

+
inversedbool

Applies the "inverse" UI theme

+
label

Required

node

The label for the entire list of choices

+
labelClassNamestring

Additional classes to be added to the FormLabel.

+
multiplebool

Allows the user to select multiple choices. Setting this to true results in a list of checkbox fields to be rendered.

-
name

Required

string
onBlurfunc
onChangefunc
type'checkbox', 'radio', 'select'

You can manually set the type if you prefer things to be less magical. +

name

Required

string
onBlurfunc
onChangefunc
type'checkbox', 'radio', 'select'

You can manually set the type if you prefer things to be less magical. Otherwise, the type will be inferred by the other props, based on what's best for accessibility and usability. If multiple is true, then checkbox fields will be rendered. If less than 10 choices are passed in, then radio buttons will be rendered.

-