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.
Base
base/body.scss:4A 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:
colorfont-familyfont-sizeline-height
-
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
Modifier: ds-base--inverse
Applies an inverse color and background-color
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>Typography
base/typography.scss:4The 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:
Typography
base/typography.scss:4The 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-displayds-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">
@@ -68,8 +68,8 @@ Heading 6
</p>Alert
components/Alert/Alert.scss:3Alerts keep users informed of important and sometimes time-sensitive changes.
Alert
components/Alert/Alert.scss:3Alerts 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
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
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
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
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.
Status heading
Link textCode 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>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/AlertA react component
This is an example of a React Alert component.Code snippet
<Alert heading="A react component">
+</div>React
components/Alert/AlertA 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
| Name | Type | Default | Description |
heading | string | ||
role | 'alert', 'alertdialog' | ARIA | |
variation | 'error', 'warn', 'success' |
Badge
components/Badge/BadgeBadges draw attention to new or important content.
Code snippet
<span class="ds-c-badge">New</span>
-<span class="ds-c-badge ds-u-fill--error">Due: December 31, 2018</span>Code snippet
<Badge>
+ Alpha status: The design system is under active development and working towards a 1.0 release. prototypeBadge
components/Badge/Badge Badges draw attention to new or important content.
New
+Due: December 31, 2018Code snippet
<span class="ds-c-badge">New</span>
+<span class="ds-c-badge ds-u-fill--error">Due: December 31, 2018</span>
TodayCode snippet
<Badge>
Today
-</Badge>
Props
Name Type Default Description
Props
| Name | Type | Default | Description |
Button
components/Button/Button.scss:4Use buttons to signal actions.
Button
components/Button/Button.scss:4Use buttons to signal actions.
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
Modifier: ds-c-button--primary
The primary call-to-action
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
Modifier: ds-c-button--transparent
A button closer to resembling an anchor element
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
Modifier: ds-c-button--danger
Indicates an action is destructive or dangerous
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
Modifier: ds-c-button--success
Indicates a positive or successful action
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
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
viewBoxwith values that are multiples of8(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/ButtonThe Button component accepts its text as children (AKA inner HTML), which
+</button>
Button inline with field
components/Button/Button.scss:240The 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/ButtonThe 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
| Name | Type | Default | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
className | string | Additional classes to be added to the root button element. +</div> Props
| |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
size | 'small', 'big' | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
type | 'button', 'submit' | 'button' | Button | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
variation | 'primary', 'danger', 'success', 'transparent' |
Checkbox & Radio
components/ChoiceList/Choice.scss:18Components
components/_index.scss:1Component class names follow the format: ds-c-[BLOCK]__[ELEMENT]--[MODIFIER]
Components
components/_index.scss:1Component 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.
List
components/List/List.scss:4-
+
- List item 1
- List item 2 -
List
components/List/List.scss:4Code snippet
<ul class="ds-c-list">
+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)
Modifier: ds-c-list--bare
Unstyled list (no margin, padding or list-style)
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>Select
components/ChoiceList/Select.scss:3A select field allows users to select one option from a list.
Select
components/ChoiceList/Select.scss:3A 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/SelectA Select component can be used to render an HTML select menu.
+</div>
React - <Select>
components/ChoiceList/SelectA 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
| Name | Type | Default | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
className | string | Additional classes to be added to the root | |||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
defaultValue | string | Sets the initial Props
React - |
React - <ChoiceList>
components/ChoiceList/ChoiceListA 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.
Code snippet
<div>
+Code snippet
<div>
<ChoiceList
choices={[
{
@@ -207,22 +207,22 @@
name="select_choices_field_inverse"
/>
</div>
-</div>Props
| Name | Type | Default | Description | ||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||||
choicesRequired | arrayOf[{checked, defaultChecked, disabled, label, value}] | The list of choices to be rendered. The number of choices you pass in may +</div> Props
|