<divclass="ds-c-alert"><divclass="ds-c-alert__body"><h3class="ds-c-alert__heading">Status heading</h3>
- <pclass="ds-c-alert__text">Lorem ipsum dolor sit <ahref="http://example.com">link text</a>, consectetur adipiscing elit, sed do eiusmod.</p>
+ <pclass="ds-c-alert__text">Lorem ipsum dolor sit <ahref="javascript:void(0);">link text</a>, consectetur adipiscing elit, sed do eiusmod.</p></div>
-</div>
<divclass="ds-c-alert ds-c-alert--error"><divclass="ds-c-alert__body"><h3class="ds-c-alert__heading">Status heading</h3>
- <pclass="ds-c-alert__text">Lorem ipsum dolor sit <ahref="http://example.com">link text</a>, consectetur adipiscing elit, sed do eiusmod.</p>
+ <pclass="ds-c-alert__text">Lorem ipsum dolor sit <ahref="javascript:void(0);">link text</a>, consectetur adipiscing elit, sed do eiusmod.</p></div>
-</div>
<divclass="ds-c-alert ds-c-alert--warn"><divclass="ds-c-alert__body"><h3class="ds-c-alert__heading">Status heading</h3>
- <pclass="ds-c-alert__text">Lorem ipsum dolor sit <ahref="http://example.com">link text</a>, consectetur adipiscing elit, sed do eiusmod.</p>
+ <pclass="ds-c-alert__text">Lorem ipsum dolor sit <ahref="javascript:void(0);">link text</a>, consectetur adipiscing elit, sed do eiusmod.</p></div>
-</div>
<divclass="ds-c-alert ds-c-alert--success"><divclass="ds-c-alert__body"><h3class="ds-c-alert__heading">Status heading</h3>
- <pclass="ds-c-alert__text">Lorem ipsum dolor sit <ahref="http://example.com">link text</a>, consectetur adipiscing elit, sed do eiusmod.</p>
+ <pclass="ds-c-alert__text">Lorem ipsum dolor sit <ahref="javascript:void(0);">link text</a>, consectetur adipiscing elit, sed do eiusmod.</p></div>
-</div>
<divclass="ds-c-alert">
- <divclass="ds-c-alert__body">
- <pclass="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>
Additional examples
Alerts support various types and lengths of content, including lists and links. You can use the measure utility to maintain a legible line length.
<divclass="ds-c-alert">
+ <divclass="ds-c-alert__body ds-u-measure--wide">
+ <pclass="ds-c-alert__text">We the People of the United States</p></div></div><divclass="ds-c-alert ds-u-margin-top--2">
- <divclass="ds-c-alert__body">
- <pclass="ds-c-alert__text">We the People of the United States</p>
+ <divclass="ds-c-alert__body ds-u-measure--wide">
+ <pclass="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></div><divclass="ds-c-alert ds-u-margin-top--2">
- <divclass="ds-c-alert__body">
+ <divclass="ds-c-alert__body ds-u-measure--wide"><h3class="ds-c-alert__heading">Status heading</h3><pclass="ds-c-alert__text">We the People of the United States, in Order to form a more perfect Union</p><ulclass="ds-c-list"><li>Alert list item</li><li>Alert list item</li></ul>
- <ahref="http://example.com">Link text</a>
- </div>
-</div>
<Alertheading="Areactcomponent">
This is an example of a React Alert component.
-</Alert>
Props
Name
Type
Default
Description
heading
string
role
'alert', 'alertdialog'
ARIA role
-
variation
'error', 'warn', 'success'
When to use
+</Alert>
Props
Name
Type
Default
Description
heading
string
role
'alert', 'alertdialog'
ARIA role
+
variation
'error', 'warn', 'success'
When to use
As a validation message that alerts someone that they just did something that needs to be corrected or as confirmation that a task was completed successfully.
As a callout or notification for important or timely information. This includes errors, warnings, and general information.
@@ -84,17 +84,20 @@
Guidance
Accessibility
-
Use the ARIA role="alert" to inform assistive technologies of a time-sensitive and important message that is not interactive. If the message is interactive, use the alertdialog role instead.
+
Use the ARIA role="alert" to inform assistive technologies of a time-sensitive and important message that is not interactive. If the message is interactive, use the role="alertdialog" instead.
+
Consider putting the alert inside a div with aria-live="polite" and aria-relevant="additions removals". These ARIA attributes ensure screen readers will announce alerts that have been added or updated dynamically.
Do not visually hide alert messages on the page and then make them visible when they are needed. Users of older assistive technologies may still be able to perceive the alert messages even if they are not currently applicable.
+
Alerts should give users adequate time to review and comprehend the provided information. Avoid hiding alerts using a timer.
+
Include a mechanism like a button to dismiss alerts where appropriate.
To draw attention to new, important content on a page that might otherwise be missed.
To filter results with one or more tags.
@@ -44,11 +51,11 @@
Accessibility
Future research
Further usability testing should be done to ensure badges aren't being confused with buttons. Further iteration can be done with sizing and colors if there is confusion.
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.
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.
Additional classes to be added to the root button element.
+</div>
Props
Name
Type
Default
Description
className
string
Additional classes to be added to the root button element.
Useful for adding utility classes.
-
component
element, func
When provided, this will render the passed in component. This is useful when
+
component
element, 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.
-
disabled
bool
href
string
When provided the root component will render as an <a> element
+
disabled
bool
href
string
When provided the root component will render as an <a> element
rather than button.
Use buttons for the most important actions you want users to take on your site, such as "Download," "Sign up," or "Apply."
@@ -116,6 +123,7 @@
Accessibility
Buttons should display a visible focus state when users tab to them.
Create a button with a button or a element to retain the native click functionality. Avoid using <div> or <img> tags to create buttons. Screen readers don't automatically know either is a usable button.
When styling links to look like buttons, remember that screen readers handle links slightly differently than they do buttons. Pressing the Space key triggers a button, but pressing the Enter key triggers a link.
+
Dimmed or unavailable buttons should have the disabled attribute applied. This removes native click and keypress events from the button. It also prevents automated scanners from logging a low contrast error. Finally, it announces the button as "dimmed" or "disabled" to screen readers, offering users additional context.
<fieldsetclass="ds-c-fieldset ds-u-margin-top--0"><legendclass="ds-c-label">Historical figures</legend><spanclass="ds-c-field__hint">Select all that apply</span><inputclass="ds-c-choice"id="truth-1"type="checkbox"name="historical-figures-1"value="truth"checked>
@@ -52,65 +59,13 @@
<inputclass="ds-c-choice ds-c-choice--inverse"id="washington-4"type="radio"name="historical-figures-4"value="washington"><labelfor="washington-4">Booker T. Washington</label></fieldset>
-</div>
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.
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.
-
className
string
Additional classes to be added to the root div element.
-
defaultChecked
bool
Sets the initial checked state and allows the user to check/uncheck the
-field without also requiring an onChange event handler.
-
id
string
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.
A ChoiceList component can be used to render a select menu, radio
button group, or checkbox group.
-
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 what type of field would be best for
-the user.
-
Code snippet
<div>
+
By default the component determines the type of field for you, taking
+into account accessibility and usability best practices. So, you can pass in
+an array of choices and let it determine what type of field would be best for
+the user, or alternatively you can manually pass in the type prop.
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.
-
className
string
Additional classes to be added to the root element.
-
disabled
bool
Disables the entire field.
-
errorMessage
string
hint
node
Hint text
-
inversed
bool
Applies the "inverse" UI theme
-
label
Required
node
The label for the entire list of choices
-
labelClassName
string
Additional classes to be added to the FormLabel.
-
multiple
bool
Allows the user to select multiple choices. Setting this to true results
+
className
string
Additional classes to be added to the root element.
+
disabled
bool
Disables the entire field.
+
errorMessage
string
hint
node
Additional hint text to display
+
inversed
bool
Applies the "inverse" UI theme
+
label
Required
node
Label for the field
+
labelClassName
string
Additional classes to be added to the FormLabel.
+
multiple
bool
Allows the user to select multiple choices. Setting this to true results
in a list of checkbox fields to be rendered.
-
name
Required
string
onBlur
func
onChange
func
type
'checkbox', 'radio', 'select'
You can manually set the type if you prefer things to be less magical.
+
name
Required
string
The field's name attribute
+
onBlur
func
onChange
func
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.
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.
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.
-
-
-
-
-
\ No newline at end of file
diff --git a/docs/components/list/index.html b/docs/components/list/index.html
index 6eb36529fc..4bdecaadd3 100644
--- a/docs/components/list/index.html
+++ b/docs/components/list/index.html
@@ -2,32 +2,39 @@
- List - CMS.gov Design System
+ List - CMSGov Design System
+
-
+
+
+
+
+
Use an ordered list when you need to display text in some ranking, hierarchy, or series of steps.
Use unordered lists to display text in no specific order.
@@ -41,14 +48,18 @@
Guidance
Use sentence case and begin lists with a capital letter.
Use punctuation appropriate to the text. Do not leave sentences without periods.
+
Accessibility
+
+
When a list has a heading, consider adding an id attribute to the heading element, and an aria-labelledby attribute to the list element. Screen readers will then announce the heading text when users navigate to the list.
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.
Additional classes to be added to the root select element.
-
defaultValue
string
Sets the initial selected state and allows the user to select a different
-option without also requiring an onChange event handler.
-
disabled
bool
id
string
A unique ID to be used for the select field. A unique ID will be generated
-if one isn't provided.
-
inversed
bool
Applies the "inverse" UI theme
-
multiple
custom
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
onBlur
func
onChange
func
value
string
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.
A ChoiceList component can be used to render a select menu, radio
button group, or checkbox group.
-
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 what type of field would be best for
-the user.
-
Code snippet
<div>
+
By default the component determines the type of field for you, taking
+into account accessibility and usability best practices. So, you can pass in
+an array of choices and let it determine what type of field would be best for
+the user, or alternatively you can manually pass in the type prop.
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.
-
className
string
Additional classes to be added to the root element.
-
disabled
bool
Disables the entire field.
-
errorMessage
string
hint
node
Hint text
-
inversed
bool
Applies the "inverse" UI theme
-
label
Required
node
The label for the entire list of choices
-
labelClassName
string
Additional classes to be added to the FormLabel.
-
multiple
bool
Allows the user to select multiple choices. Setting this to true results
+
className
string
Additional classes to be added to the root element.
+
disabled
bool
Disables the entire field.
+
errorMessage
string
hint
node
Additional hint text to display
+
inversed
bool
Applies the "inverse" UI theme
+
label
Required
node
Label for the field
+
labelClassName
string
Additional classes to be added to the FormLabel.
+
multiple
bool
Allows the user to select multiple choices. Setting this to true results
in a list of checkbox fields to be rendered.
-
name
Required
string
onBlur
func
onChange
func
type
'checkbox', 'radio', 'select'
You can manually set the type if you prefer things to be less magical.
+
name
Required
string
The field's name attribute
+
onBlur
func
onChange
func
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.
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.
Additional classes to be added to the root select element.
+
defaultValue
string
Sets the initial selected state. Use this for an uncontrolled component;
+otherwise, use the selected property.
+
disabled
bool
id
string
A unique ID to be used for the select field. A unique ID will be generated
+if one isn't provided.
+
inversed
bool
Applies the "inverse" UI theme
+
multiple
custom
Setting this prop will result in a PropTypes error message due to
+accessibility concerns. Use checkboxes instead if you need to support multiple
+selections. See the Guidance tab for more info.
+
name
Required
string
The select field's name attribute
+
onBlur
func
onChange
func
value
string
Note: Setting this prop will render a read-only field. If the field should be
+mutable, use defaultValue. Otherwise, set either onChange or readOnly
+
When to use
-
Use sparingly โ only when a user needs to choose from about seven to 15 possible options and you have limited space to display the options.
+
Use sparingly โ only when a user needs to choose from about 7 to 15 possible options and you have limited space to display the options.
When to consider alternatives
-
If the list of options is short. Use radio or checkboxes buttons instead.
-
If the list of options is very long. Let users type the same information into a text input that suggests possible options instead. Long lists can sometimes be broken into multiple shorter lists by asking a few questions up-front to filter out options.
If the list of options is very long. Let users type the same information into a text input that suggests possible options instead. Long lists can sometimes be broken into multiple shorter lists by asking a few questions up-front to filter out options.
If you need to allow users to select more than one option at once. Users often donโt understand how to select multiple items from dropdowns. Use checkboxes instead.
If the data is highly familiar to users, such as the day, month, or year of their birth.
Skip navigation links allow users with screen readers to bypass long navigation lists. Make sure you include an id at the beginning of your main content and that it matches the skipnav link. Find more information here: webaim.org/techniques/skipnav
<aclass="ds-c-skip-nav"href="#main">Skip to main content</a>
+<ahref="javascript:void(0);">Navigation link</a>
+<mainid="main"class="ds-u-padding--4 ds-u-fill--gray-lightest"tabindex="0">
+ Main content
+</main>
Tabs are a secondary navigation pattern, allowing a user to view only the content they're interested in. They build upon a real world metaphor, and the selected state simulates a folder being physically in front of others in the group.
Tabs are a secondary navigation pattern, allowing a user to view only the content they're interested in. They build upon a real world metaphor, and the selected state simulates a folder being physically in front of others in the group.
A container component that manages the state of your tabs for you. For most
-cases, you'll want to use this component rather than the presentational
+</div>
Tabs is a container component that manages the state of your tabs for you.
+In most cases, you'll want to use this component rather than the presentational
components (Tab, TabPanel) on their own.
Additional classes to be added to the root tab element.
id
Required
string
A unique id, to be used on the rendered tab element.
-
href
string
You can optionally set the href attribute used for the tab. This can be
-useful if you want to use relative links rather than a URL hash (the default)
+
href
string
Sets the href attribute used for the tab. This can be useful if you want
+to use relative links rather than a URL hash (the default).
onClick
func
Called when the tab is clicked, with the following arguments:
SyntheticEvent,
id, panelId
-
panelId
Required
string
The id of the associated TabPanel. Used for the aria-controls attribute
-
selected
bool
false
When to use
+
panelId
Required
string
The id of the associated TabPanel. Used for the aria-controls attribute.
+
selected
bool
false
When to use
If you have sub-sections of a page, and there's the need to only show one sub-section at a time.
@@ -206,7 +215,7 @@
Guidance
Accessibility
-
Use an anchor link (a) to create the tabs. This allows you to link directly to a tab, and allows you to progressively enhance the page, retaining default browser behavior like opening links in a new window. Note: You'll need to implement the logic for selecting the correct tab based on the current URL.
+
Use an anchor link (a) to create the tabs. This allows you to link directly to a tab, and allows you to progressively enhance the page, retaining default browser behavior like opening links in a new window. Note: You'll need to implement the logic for selecting the correct tab based on the current URL.
Ensure the HTML markup includes the proper ARIA attributes:
Text fields allow people to enter any combination of letters, numbers, or symbols of their choosing (unless otherwise restricted). Text fields can span single or multiple lines.
Text fields allow users to enter any combination of letters, numbers, or symbols of their choosing (unless otherwise restricted). Text fields can span single or multiple lines.
<divclass="ds-base--inverse ds-u-padding--2">
- <labelclass="ds-c-label ds-u-margin-top--0"for="input-firstname-2">
- First name
- <spanclass="ds-c-field__hint ds-c-field__hint--inverse">Helpful hint text</span>
- </label>
+<textareaclass="ds-c-field"id="input-bio"name="bio"rows="5"></textarea>
+<labelclass="ds-c-label"for="input-id-num">
+ ID Number
+ <spanclass="ds-c-field__hint">
+ Example of a disabled field
+ </span>
+</label>
+<inputclass="ds-c-field ds-c-field--inverse"id="input-id-num"name="id-num"type="text"value="1234"disabled>
The TextField component affords a user to type text into a form.
-By default it renders a field for capturing a single line of text,
-but can be configured to support multiline text.
-
Code snippet
<div>
+ <labelclass="ds-c-label"for="input-id-num-2">
+ ID Number
+ <spanclass="ds-c-field__hint ds-c-field__hint--inverse">
+ Example of a disabled field
+ </span>
+ </label>
+ <inputclass="ds-c-field ds-c-field--inverse"id="input-id-num-2"name="id-num-2"type="text"value="1234"disabled>
+</div>
Current value of the text field. Use this for a controlled component where
-you are maintaining its current state; otherwise, use the defaultValue property
-
When to use
+</div>
Props
Name
Type
Default
Description
className
string
Additional classes to be added to the root div element
+
defaultValue
string
Sets the initial value. Use this for an uncontrolled component; otherwise,
+use the value property.
+
disabled
bool
errorMessage
string
fieldClassName
string
Additional classes to be added to the field element
+
hint
node
Additional hint text to display
+
inversed
bool
Applies the "inverse" UI theme
+
label
Required
node
Label for the input
+
labelClassName
string
Additional classes to be added to the label
+
multiline
bool
Whether or not the textfield is a multiline textfield
+
name
Required
string
onBlur
func
onChange
func
rows
number, string
Optionally specify the number of visible text lines for the field. Only
+applicable if this is a multiline field.
Note: Setting this prop will render a read-only field. If the field should be
+mutable, use defaultValue. Otherwise, set onChange or disabled.
+
When to use
If you canโt reasonably predict a userโs answer to a prompt and there might be wide variability in usersโ answers.
When using another type of input will make answering more difficult. For example, birthdays and other known dates are easier to type in than they are to select from a calendar picker.
@@ -107,7 +108,7 @@
When to consider alternatives
-
When users are choosing from a specific set of options. Consider checkboxes, radio buttons, or a select menu in these cases.
Aria label for the toggle button when the sub-navigation is collapsed
ariaExpandedStateButtonLabel
string
'Collapse sub-navigation'
Aria label for the toggle button when the sub-navigation is expanded
className
string
Additional classes to be added to the root element
defaultCollapsed
bool
false
Whether or not the item's sub-navigation is in a collapsed state by default
-
onClick
func
Called when the item is clicked, with the following arguments:
+
onClick
func
Called when the link is clicked, with the following arguments:
SyntheticEvent,
id, url.
This takes precedence over the VerticalNavonLinkClick prop
@@ -93,7 +100,7 @@
label
Required
node
Text to render for this nav item
url
string
A URL to navigate to if this item is a link
selected
bool
If this item is currently selected
-
When to use
+
When to use
To display a navigational hierarchy with one to three levels.
To display the โsub-navigationโ within a section of the website.
@@ -106,7 +113,7 @@
When to consider alternatives
Guidance
-
Indicate where a user is within the navigational hierarchy. Use the ds-c-vertical-nav__link--current modifier to show users which page they have navigated to.
+
Indicate where a user is within the navigational hierarchy. Use the ds-c-vertical-nav__label--current modifier to show users which page they have navigated to.
Keep the navigation links short and follow sentence case. They can be shorter derivatives of page titles themselves.
If the navigation hierarchy is too long, users may miss items at the bottom. If itโs too deep, users may miss items that require too many clicks. Usability test to find the right balance between breadth and depth.
@@ -115,6 +122,13 @@
Accessibility
Users should be able to tab through each link.
If you have nested menus that are collapsible, ensure the toggle button has its aria-controls and aria-expanded attributes set. This is done automatically for you
if you're using the React components.
+
If your navigation list is longer than 3 items, consider using a skip navigation link. This allows screen reader and keyboard users to skip to the main content area(s).
+
If a skip navigation link is not an option, consider using:
+
A valid, descriptive page header
+
Landmark regions like <header>, <nav>, <main>, <aside>, <footer>
Lorem ipsum dolor sit link text, consectetur adipiscing elit, sed do eiusmod.
+
Lorem ipsum dolor sit link text, consectetur adipiscing elit, sed do eiusmod.
-
+
+
+
\ No newline at end of file
diff --git a/docs/example/components.alert.ds-c-alert--success/index.html b/docs/example/components.alert.ds-c-alert--success/index.html
index 76ad97c015..92e8c1fd4b 100644
--- a/docs/example/components.alert.ds-c-alert--success/index.html
+++ b/docs/example/components.alert.ds-c-alert--success/index.html
@@ -2,13 +2,22 @@
+
Example: components.alert
+
+
+
-
+
+
Status heading
-
Lorem ipsum dolor sit link text, consectetur adipiscing elit, sed do eiusmod.
+
Lorem ipsum dolor sit link text, consectetur adipiscing elit, sed do eiusmod.
-
+
+
+
\ No newline at end of file
diff --git a/docs/example/components.alert.ds-c-alert--warn/index.html b/docs/example/components.alert.ds-c-alert--warn/index.html
index c4a92dbf57..b3dd26b557 100644
--- a/docs/example/components.alert.ds-c-alert--warn/index.html
+++ b/docs/example/components.alert.ds-c-alert--warn/index.html
@@ -2,13 +2,22 @@
+
Example: components.alert
+
+
+
-
+
+
Status heading
-
Lorem ipsum dolor sit link text, consectetur adipiscing elit, sed do eiusmod.
+
Lorem ipsum dolor sit link text, consectetur adipiscing elit, sed do eiusmod.
-
+
+
+
\ No newline at end of file
diff --git a/docs/example/components.alert.inverse/index.html b/docs/example/components.alert.inverse/index.html
deleted file mode 100644
index b7e3d7f97e..0000000000
--- a/docs/example/components.alert.inverse/index.html
+++ /dev/null
@@ -1,16 +0,0 @@
-
-
-
-
- Example: components.alert.inverse
-
-
-
-
-
-
Status heading
-
Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod.
-
-
-
-
\ No newline at end of file
diff --git a/docs/example/components.alert.variations/index.html b/docs/example/components.alert.variations/index.html
index f39a40b96b..5f32b91944 100644
--- a/docs/example/components.alert.variations/index.html
+++ b/docs/example/components.alert.variations/index.html
@@ -2,28 +2,37 @@
+
Example: components.alert.variations
+
+
+
-
-
-
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.
+
+
+
+
We the People of the United States
-
-
We the People of the United States
+
+
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
We the People of the United States, in Order to form a more perfect Union
+
+
\ No newline at end of file
diff --git a/docs/example/components.text-field.inverse/index.html b/docs/example/components.text-field.inverse/index.html
index 47375ac2b5..84e6166c2e 100644
--- a/docs/example/components.text-field.inverse/index.html
+++ b/docs/example/components.text-field.inverse/index.html
@@ -2,14 +2,18 @@
+
Example: components.text-field.inverse
+
+
+
-
-
+
+
+
+
+ ID Number
+
+ Example of a disabled field
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/example/components.text-field/index.html b/docs/example/components.text-field/index.html
index 129ce7b74e..4c3a50fb33 100644
--- a/docs/example/components.text-field/index.html
+++ b/docs/example/components.text-field/index.html
@@ -2,13 +2,17 @@
+
Example: components.text-field
+
+
+
-
- First name
- Helpful hint text
-
+
+ First nameLast name
@@ -18,8 +22,20 @@
Helpful hint text
-Username
-
+
+ Username
+ Example of a success field state
+
+
Bio
-
+
+
+ ID Number
+
+ Example of a disabled field
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/example/components.vertical-nav/index.html b/docs/example/components.vertical-nav/index.html
index 7b135afced..364180e0c0 100644
--- a/docs/example/components.vertical-nav/index.html
+++ b/docs/example/components.vertical-nav/index.html
@@ -2,37 +2,46 @@
+
Example: components.vertical-nav
+
+
+
-
-
+
+
+
\ No newline at end of file
diff --git a/docs/example/layout.grid.responsive/index.html b/docs/example/layout.grid.responsive/index.html
index 74600929b8..e4f80da7e4 100644
--- a/docs/example/layout.grid.responsive/index.html
+++ b/docs/example/layout.grid.responsive/index.html
@@ -2,10 +2,17 @@
+
Example: layout.grid.responsive
+
+
+
-
+
+
A
@@ -26,5 +33,7 @@
F
-
+
+
+
\ No newline at end of file
diff --git a/docs/example/patterns.documentation-page/index.html b/docs/example/patterns.documentation-page/index.html
index 35b8d430cf..c9e5d2a347 100644
--- a/docs/example/patterns.documentation-page/index.html
+++ b/docs/example/patterns.documentation-page/index.html
@@ -2,48 +2,56 @@
+
Example: patterns.documentation-page
+
+
+
-
+
+
+ Skip to main content
-
+
Page heading (h1)
The page heading communicates the main focus of the page. Make your page heading descriptive and keep it succinct.
Section heading (h2)
@@ -55,5 +63,7 @@
Subsection heading (h4)
Use the vertical navigation menu to help your users quickly skip to different sections of your page. The menu is best suited to displaying a hierarchy with one to three levels and, as we mentioned, to display the sub-navigation of a given page.
-
+
+
+
\ No newline at end of file
diff --git a/docs/example/style.base.ds-base--inverse/index.html b/docs/example/style.base.ds-base--inverse/index.html
index b30362ed70..0e00ba8e5b 100644
--- a/docs/example/style.base.ds-base--inverse/index.html
+++ b/docs/example/style.base.ds-base--inverse/index.html
@@ -2,10 +2,19 @@
+
Example: style.base
+
+
+
-
+
+
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.
-
+
+
+
\ No newline at end of file
diff --git a/docs/example/style.base/index.html b/docs/example/style.base/index.html
index 5979e3d918..3b366095c9 100644
--- a/docs/example/style.base/index.html
+++ b/docs/example/style.base/index.html
@@ -2,10 +2,19 @@
+
Example: style.base
+
+
+
-
+
+
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.
-
+
+
+
\ No newline at end of file
diff --git a/docs/example/style.color.background/index.html b/docs/example/style.color.background/index.html
new file mode 100644
index 0000000000..4105de5e56
--- /dev/null
+++ b/docs/example/style.color.background/index.html
@@ -0,0 +1,69 @@
+
+
+
+
+
+ Example: style.color.background
+
+
+
+
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/example/style.typography.responsive/index.html b/docs/example/style.typography.responsive/index.html
index a66f834d1c..d5cf28ea89 100644
--- a/docs/example/style.typography.responsive/index.html
+++ b/docs/example/style.typography.responsive/index.html
@@ -2,13 +2,25 @@
+
Example: style.typography.responsive
+
+
+
-
- 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.
-
+
+
+
Responsive heading
+
+ Responsive body 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.
+
+
Responsive subheading
+
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.
+
+
+
\ No newline at end of file
diff --git a/docs/example/style.typography/index.html b/docs/example/style.typography/index.html
index b37a39e1eb..73ac1bed8c 100644
--- a/docs/example/style.typography/index.html
+++ b/docs/example/style.typography/index.html
@@ -2,25 +2,51 @@
+
Example: style.typography
+
+
+
-
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
+
+
Display
+
+ 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.
+
Title
-
We the People of the United States, in Order to form a more perfect Union
+
+ 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.
+
Heading 1
-
We the People of the United States, in Order to form a more perfect Union
+
+ 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.
+
Heading 2
-
We the People of the United States, in Order to form a more perfect Union
+
+ 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.
+
Heading 3
-
We the People of the United States, in Order to form a more perfect Union
+
+ 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.
+
Heading 4
-
We the People of the United States, in Order to form a more perfect Union
+
+ 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.
+
Heading 5
-
We the People of the United States, in Order to form a more perfect Union
+
+ 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.
+
Heading 6
-
We the People of the United States, in Order to form a more perfect Union
+
+ Lead 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.
+
+
+ Body 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.
+
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.background-color/index.html b/docs/example/utilities.background-color/index.html
index 8dcf1c8e49..d6347b21fa 100644
--- a/docs/example/utilities.background-color/index.html
+++ b/docs/example/utilities.background-color/index.html
@@ -2,343 +2,352 @@
+
Example: utilities.background-color
+
+
+
-
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.border-radius/index.html b/docs/example/utilities.border-radius/index.html
index 3cd182e810..090dcffb9b 100644
--- a/docs/example/utilities.border-radius/index.html
+++ b/docs/example/utilities.border-radius/index.html
@@ -2,10 +2,22 @@
+
Example: utilities.border-radius
+
+
+
-
Round
-
Pill
-
+
+ ds-u-radius
+
+ds-u-radius--pill
+
+ds-u-radius--circle
+
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.border.color/index.html b/docs/example/utilities.border.color/index.html
new file mode 100644
index 0000000000..bd8cab4397
--- /dev/null
+++ b/docs/example/utilities.border.color/index.html
@@ -0,0 +1,68 @@
+
+
+
+
+
+ Example: utilities.border.color
+
+
+
+
+
+
+
+
+ ds-u-border--inverse
+
+
+
+
+ ds-u-border--error
+
+
+
+
+ ds-u-border--error-light
+
+
+
+
+ ds-u-border--error-lighter
+
+
+
+
+ ds-u-border--warn
+
+
+
+
+ ds-u-border--warn-light
+
+
+
+
+ ds-u-border--warn-lighter
+
+
+
+
+ ds-u-border--success
+
+
+
+
+ ds-u-border--success-light
+
+
+
+
+ ds-u-border--success-lighter
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.border/index.html b/docs/example/utilities.border/index.html
index 81dac9a366..c590c0d356 100644
--- a/docs/example/utilities.border/index.html
+++ b/docs/example/utilities.border/index.html
@@ -2,10 +2,17 @@
+
Example: utilities.border
+
+
+
+
ds-u-border--0
@@ -89,56 +96,7 @@
ds-u-border-top--2
-
Color
-
-
- ds-u-border--inverse
-
-
-
-
- ds-u-border--error
-
-
-
-
- ds-u-border--error-light
-
-
-
-
- ds-u-border--error-lighter
-
-
-
-
- ds-u-border--warn
-
-
-
-
- ds-u-border--warn-light
-
-
-
-
- ds-u-border--warn-lighter
-
-
-
-
- ds-u-border--success
-
-
-
-
- ds-u-border--success-light
-
-
-
-
- ds-u-border--success-lighter
-
-
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.clearfix/index.html b/docs/example/utilities.clearfix/index.html
new file mode 100644
index 0000000000..8f09d1711f
--- /dev/null
+++ b/docs/example/utilities.clearfix/index.html
@@ -0,0 +1,22 @@
+
+
+
+
+
+ Example: utilities.clearfix
+
+
+
+
+
+
+
+
+ Floated right
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.color/index.html b/docs/example/utilities.color/index.html
index 7ad67d6f6e..c29057ccd2 100644
--- a/docs/example/utilities.color/index.html
+++ b/docs/example/utilities.color/index.html
@@ -2,302 +2,311 @@
+
Example: utilities.color
+
+
+
-
-
- .ds-u-color--base
- on .ds-u-fill--white
-
-
-
-
- .ds-u-color--muted
- on .ds-u-fill--white
-
-
-
-
- .ds-u-color--black
- on .ds-u-fill--white
-
-
-
-
- .ds-u-color--primary
- on .ds-u-fill--white
-
-
-
-
- .ds-u-color--primary-darker
- on .ds-u-fill--white
-
-
-
-
- .ds-u-color--primary-darkest
- on .ds-u-fill--white
-
-
-
-
- .ds-u-color--gray
- on .ds-u-fill--white
-
-
-
-
- .ds-u-color--error
- on .ds-u-fill--white
-
-
-
-
- .ds-u-color--error-dark
- on .ds-u-fill--white
-
-
-
-
- .ds-u-color--success
- on .ds-u-fill--white
-
-
-
-
- .ds-u-color--base-inverse
- on .ds-u-fill--background-inverse
-
-
-
-
- .ds-u-color--muted-inverse
- on .ds-u-fill--background-inverse
-
-
-
-
- .ds-u-color--error-light
- on .ds-u-fill--background-inverse
-
-
-
-
- .ds-u-color--white
- on .ds-u-fill--base
-
-
-
-
- .ds-u-color--white
- on .ds-u-fill--gray-dark
-
-
-
-
- .ds-u-color--white
- on .ds-u-fill--gray
-
-
-
-
- .ds-u-color--white
- on .ds-u-fill--primary-darkest
-
-
-
-
- .ds-u-color--white
- on .ds-u-fill--primary-darker
-
-
-
-
- .ds-u-color--white
- on .ds-u-fill--primary
-
-
-
-
- .ds-u-color--white
- on .ds-u-fill--primary-alt-darkest
-
-
-
-
- .ds-u-color--base
- on .ds-u-fill--primary-alt-dark
-
-
-
-
- .ds-u-color--base
- on .ds-u-fill--primary-alt
-
-
-
-
- .ds-u-color--white
- on .ds-u-fill--green
-
-
-
-
- .ds-u-color--white
- on .ds-u-fill--success
-
-
-
-
- .ds-u-color--base
- on .ds-u-fill--green-light
-
-
-
-
- .ds-u-color--base
- on .ds-u-fill--success-light
-
-
-
-
- .ds-u-color--base
- on .ds-u-fill--gold
-
-
-
-
- .ds-u-color--base
- on .ds-u-fill--warn
-
-
-
-
- .ds-u-color--base
- on .ds-u-fill--gold-light
-
-
-
-
- .ds-u-color--base
- on .ds-u-fill--warn-light
-
-
-
-
- .ds-u-color--white
- on .ds-u-fill--secondary-darkest
-
-
-
-
- .ds-u-color--white
- on .ds-u-fill--error-darkest
-
-
-
-
- .ds-u-color--white
- on .ds-u-fill--secondary-dark
-
-
-
-
- .ds-u-color--white
- on .ds-u-fill--error-dark
-
-
-
-
- .ds-u-color--white
- on .ds-u-fill--secondary
-
-
-
-
- .ds-u-color--white
- on .ds-u-fill--error
-
-
-
-
- .ds-u-color--base
- on .ds-u-fill--gray-light
-
-
-
-
- .ds-u-color--base
- on .ds-u-fill--gray-lighter
-
-
-
-
- .ds-u-color--base
- on .ds-u-fill--primary-alt-lightest
-
-
-
-
- .ds-u-color--base
- on .ds-u-fill--green-lighter
-
-
-
-
- .ds-u-color--base
- on .ds-u-fill--success-lighter
-
-
-
-
- .ds-u-color--base
- on .ds-u-fill--green-lightest
-
-
-
-
- .ds-u-color--base
- on .ds-u-fill--success-lightest
-
-
-
-
- .ds-u-color--base
- on .ds-u-fill--gold-lighter
-
-
-
-
- .ds-u-color--base
- on .ds-u-fill--warn-lighter
-
-
-
-
- .ds-u-color--base
- on .ds-u-fill--gold-lightest
-
-
-
-
- .ds-u-color--base
- on .ds-u-fill--warn-lightest
-
-
-
-
- .ds-u-color--base
- on .ds-u-fill--secondary-lightest
-
-
-
-
- .ds-u-color--base
- on .ds-u-fill--error-lightest
-
-
+
+
+ ds-u-color--base
+
+ on
+ ds-u-fill--white
+
+
+ ds-u-color--muted
+
+ on
+ ds-u-fill--white
+
+
+ ds-u-color--black
+
+ on
+ ds-u-fill--white
+
+
+ ds-u-color--primary
+
+ on
+ ds-u-fill--white
+
+
+ ds-u-color--primary-darker
+
+ on
+ ds-u-fill--white
+
+
+ ds-u-color--primary-darkest
+
+ on
+ ds-u-fill--white
+
+
+ ds-u-color--gray
+
+ on
+ ds-u-fill--white
+
+
+ ds-u-color--error
+
+ on
+ ds-u-fill--white
+
+
+ ds-u-color--error-dark
+
+ on
+ ds-u-fill--white
+
+
+ ds-u-color--success
+
+ on
+ ds-u-fill--white
+
+
+ ds-u-color--base-inverse
+
+ on
+ ds-u-fill--background-inverse
+
+
+ ds-u-color--muted-inverse
+
+ on
+ ds-u-fill--background-inverse
+
+
+ ds-u-color--error-light
+
+ on
+ ds-u-fill--background-inverse
+
+
+ ds-u-color--white
+
+ on
+ ds-u-fill--base
+
+
+ ds-u-color--white
+
+ on
+ ds-u-fill--gray-dark
+
+
+ ds-u-color--white
+
+ on
+ ds-u-fill--gray
+
+
+ ds-u-color--white
+
+ on
+ ds-u-fill--primary-darkest
+
+
+ ds-u-color--white
+
+ on
+ ds-u-fill--primary-darker
+
+
+ ds-u-color--white
+
+ on
+ ds-u-fill--primary
+
+
+ ds-u-color--white
+
+ on
+ ds-u-fill--primary-alt-darkest
+
+
+ ds-u-color--base
+
+ on
+ ds-u-fill--primary-alt-dark
+
+
+ ds-u-color--base
+
+ on
+ ds-u-fill--primary-alt
+
+
+ ds-u-color--white
+
+ on
+ ds-u-fill--green
+
+
+ ds-u-color--white
+
+ on
+ ds-u-fill--success
+
+
+ ds-u-color--base
+
+ on
+ ds-u-fill--green-light
+
+
+ ds-u-color--base
+
+ on
+ ds-u-fill--success-light
+
+
+ ds-u-color--base
+
+ on
+ ds-u-fill--gold
+
+
+ ds-u-color--base
+
+ on
+ ds-u-fill--warn
+
+
+ ds-u-color--base
+
+ on
+ ds-u-fill--gold-light
+
+
+ ds-u-color--base
+
+ on
+ ds-u-fill--warn-light
+
+
+ ds-u-color--white
+
+ on
+ ds-u-fill--secondary-darkest
+
+
+ ds-u-color--white
+
+ on
+ ds-u-fill--error-darkest
+
+
+ ds-u-color--white
+
+ on
+ ds-u-fill--secondary-dark
+
+
+ ds-u-color--white
+
+ on
+ ds-u-fill--error-dark
+
+
+ ds-u-color--white
+
+ on
+ ds-u-fill--secondary
+
+
+ ds-u-color--white
+
+ on
+ ds-u-fill--error
+
+
+ ds-u-color--base
+
+ on
+ ds-u-fill--gray-light
+
+
+ ds-u-color--base
+
+ on
+ ds-u-fill--gray-lighter
+
+
+ ds-u-color--base
+
+ on
+ ds-u-fill--primary-alt-lightest
+
+
+ ds-u-color--base
+
+ on
+ ds-u-fill--green-lighter
+
+
+ ds-u-color--base
+
+ on
+ ds-u-fill--success-lighter
+
+
+ ds-u-color--base
+
+ on
+ ds-u-fill--green-lightest
+
+
+ ds-u-color--base
+
+ on
+ ds-u-fill--success-lightest
+
+
+ ds-u-color--base
+
+ on
+ ds-u-fill--gold-lighter
+
+
+ ds-u-color--base
+
+ on
+ ds-u-fill--warn-lighter
+
+
+ ds-u-color--base
+
+ on
+ ds-u-fill--gold-lightest
+
+
+ ds-u-color--base
+
+ on
+ ds-u-fill--warn-lightest
+
+
+ ds-u-color--base
+
+ on
+ ds-u-fill--secondary-lightest
+
+
+ ds-u-color--base
+
+ on
+ ds-u-fill--error-lightest
+
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.display-visibility.display/index.html b/docs/example/utilities.display-visibility.display/index.html
new file mode 100644
index 0000000000..6469b29176
--- /dev/null
+++ b/docs/example/utilities.display-visibility.display/index.html
@@ -0,0 +1,22 @@
+
+
+
+
+
+ Example: utilities.display-visibility.display
+
+
+
+
+
+
+
ds-u-display--block
+
ds-u-display--inline-block
+
ds-u-display--flex
+
ds-u-display--none
+
+
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.display-visibility.responsive/index.html b/docs/example/utilities.display-visibility.responsive/index.html
index 042a502f3c..659957a859 100644
--- a/docs/example/utilities.display-visibility.responsive/index.html
+++ b/docs/example/utilities.display-visibility.responsive/index.html
@@ -2,10 +2,17 @@
+
Example: utilities.display-visibility.responsive
+
+
+
+
Hidden on sm screens and larger
@@ -57,5 +64,7 @@
Visible on xl screens and larger
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.display-visibility.visibility/index.html b/docs/example/utilities.display-visibility.visibility/index.html
index 5a5f2a61b1..5ff3d362b7 100644
--- a/docs/example/utilities.display-visibility.visibility/index.html
+++ b/docs/example/utilities.display-visibility.visibility/index.html
@@ -2,10 +2,19 @@
+
Example: utilities.display-visibility.visibility
+
+
+
-I'm hidden
+
+ I'm hiddenI'm visible to screen readers only
-I'm visible
+I'm visible
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.flexbox.align-items/index.html b/docs/example/utilities.flexbox.align-items/index.html
index 447d765f24..4265542a89 100644
--- a/docs/example/utilities.flexbox.align-items/index.html
+++ b/docs/example/utilities.flexbox.align-items/index.html
@@ -2,40 +2,54 @@
+
Example: utilities.flexbox.align-items
+
+
+
-
+
+
-
+ ds-u-align-items--start
+
start
start
start
-
+ ds-u-align-items--end
+
end
end
end
-
+ ds-u-align-items--center
+
center
center
center
-
+ ds-u-align-items--baseline
+
baseline
baseline
baseline
-
+ ds-u-align-items--stretch
+
stretch
stretch
stretch
-
+
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.flexbox.flex-wrap/index.html b/docs/example/utilities.flexbox.flex-wrap/index.html
new file mode 100644
index 0000000000..6e0d8cea8f
--- /dev/null
+++ b/docs/example/utilities.flexbox.flex-wrap/index.html
@@ -0,0 +1,41 @@
+
+
+
+
+
+ Example: utilities.flexbox.flex-wrap
+
+
+
+
+
+
+
+
+ ds-u-flex-wrap--nowrap
+
+
nowrap element #1
+
nowrap element #2
+
nowrap element #3
+
+
+ ds-u-flex-wrap--wrap
+
+
wrap element #1
+
wrap element #2
+
wrap element #3
+
+
+ ds-u-flex-wrap--reverse
+
+
reverse element #1
+
reverse element #2
+
reverse element #3
+
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.flexbox.justify-content/index.html b/docs/example/utilities.flexbox.justify-content/index.html
index 9986371442..207f405342 100644
--- a/docs/example/utilities.flexbox.justify-content/index.html
+++ b/docs/example/utilities.flexbox.justify-content/index.html
@@ -2,40 +2,54 @@
+
Example: utilities.flexbox.justify-content
+
+
+
-
+
+
-
+ ds-u-justify-content--start
+
start
start
start
-
+ ds-u-justify-content--end
+
end
end
end
-
+ ds-u-justify-content--center
+
center
center
center
-
+ ds-u-justify-content--between
+
between
between
between
-
+ ds-u-justify-content--around
+
around
around
around
-
+
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.float.responsive/index.html b/docs/example/utilities.float.responsive/index.html
index 2ab6aa1e94..18d64d6f33 100644
--- a/docs/example/utilities.float.responsive/index.html
+++ b/docs/example/utilities.float.responsive/index.html
@@ -2,21 +2,30 @@
+
Example: utilities.float.responsive
+
+
+
-
- :)
+
+
+ Inline text
-
+
float: none
-
-
+
+
float: left
-
-
+
+
float: right
-
+
-
+
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.float/index.html b/docs/example/utilities.float/index.html
index 77aaaf8309..cab30fd4ed 100644
--- a/docs/example/utilities.float/index.html
+++ b/docs/example/utilities.float/index.html
@@ -2,22 +2,32 @@
+
Example: utilities.float
+
+
+
-
-
- float: left
-
+
+
+
+ ds-u-float--left
+
-
- float: right
-
+
+ ds-u-float--right
+
-
- float: none
-
-
+
+ ds-u-float--none
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.font-family/index.html b/docs/example/utilities.font-family/index.html
index 8fbf905dc5..eb759b42e1 100644
--- a/docs/example/utilities.font-family/index.html
+++ b/docs/example/utilities.font-family/index.html
@@ -2,9 +2,20 @@
+
Example: utilities.font-family
+
+
+
-
Bitter, Georgia, serif
-
Open Sans, Helvetica, sans-serif
+
+
ds-u-sans (default)
+
Open Sans, Helvetica, sans-serif
+
ds-u-serif
+
Bitter, Georgia, serif
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.font-size.responsive/index.html b/docs/example/utilities.font-size.responsive/index.html
index 1a82d4dd86..2506f13ae0 100644
--- a/docs/example/utilities.font-size.responsive/index.html
+++ b/docs/example/utilities.font-size.responsive/index.html
@@ -2,10 +2,19 @@
+
Example: utilities.font-size.responsive
+
+
+
-
+
+
We the People of the United States, in Order to form a more perfect Union
-
+
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.font-size/index.html b/docs/example/utilities.font-size/index.html
index 7a4cafaa9d..4a36c67fdc 100644
--- a/docs/example/utilities.font-size/index.html
+++ b/docs/example/utilities.font-size/index.html
@@ -2,17 +2,71 @@
+
Example: utilities.font-size
+
+
+
-
We the People of the United States
-
We the People of the United States
-
We the People of the United States
-
We the People of the United States
-
We the People of the United States
-
We the People of the United States
-
We the People of the United States
-
We the People of the United States
-
We the People of the United States
+
+
+
+ ds-u-font-size--display
+
+ We the People of the United States
+
+
+
+ ds-u-font-size--title
+
+ We the People of the United States
+
+
+
+ ds-u-font-size--h1
+
+ We the People of the United States
+
+
+
+ ds-u-font-size--h2
+
+ We the People of the United States
+
+
+
+ ds-u-font-size--h3
+
+ We the People of the United States
+
+
+
+ ds-u-font-size--h4
+
+ We the People of the United States
+
+
+
+ ds-u-font-size--lead
+
+ We the People of the United States
+
+
+
+ ds-u-font-size--base
+
+ We the People of the United States
+
+
+
+ ds-u-font-size--small
+
+ We the People of the United States
+
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.font-style/index.html b/docs/example/utilities.font-style/index.html
index 32c464f0c2..c341b94454 100644
--- a/docs/example/utilities.font-style/index.html
+++ b/docs/example/utilities.font-style/index.html
@@ -2,9 +2,20 @@
+
Example: utilities.font-style
+
+
+
-
We the People of the United States, in Order to form a more perfect Union
-
We the People of the United States, in Order to form a more perfect Union
+
+
ds-u-font-style--normal
+
We the People of the United States, in Order to form a more perfect Union
+
ds-u-font-style--italic
+
We the People of the United States, in Order to form a more perfect Union
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.font-weight/index.html b/docs/example/utilities.font-weight/index.html
index 740655f58f..abd1791152 100644
--- a/docs/example/utilities.font-weight/index.html
+++ b/docs/example/utilities.font-weight/index.html
@@ -2,10 +2,19 @@
+
Example: utilities.font-weight
+
+
+
-
Normal
-
Semibold
-
Bold
+
+
ds-u-font-weight--normal
+
ds-u-font-weight--semibold
+
ds-u-font-weight--bold
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.line-height/index.html b/docs/example/utilities.line-height/index.html
index f0aa60bcb8..863bf89824 100644
--- a/docs/example/utilities.line-height/index.html
+++ b/docs/example/utilities.line-height/index.html
@@ -2,11 +2,24 @@
+
Example: utilities.line-height
+
+
+
-
We the People of the United States, in Order to form a more perfect Union
-
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.
-
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.
-
We the People of the United States
+
+
ds-u-leading--lead
+
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.
+
ds-u-leading--base
+
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.
+
ds-u-leading--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.
+
ds-u-leading--reset
+
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.
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.margin.responsive/index.html b/docs/example/utilities.margin.responsive/index.html
index 21393120df..dd811bfa2c 100644
--- a/docs/example/utilities.margin.responsive/index.html
+++ b/docs/example/utilities.margin.responsive/index.html
@@ -2,12 +2,21 @@
+
Example: utilities.margin.responsive
+
+
+
-
+
+
Responsive margins
-
+
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.margin/index.html b/docs/example/utilities.margin/index.html
index 155e763e9a..c61945ddca 100644
--- a/docs/example/utilities.margin/index.html
+++ b/docs/example/utilities.margin/index.html
@@ -2,10 +2,17 @@
+
Example: utilities.margin
+
+
+
+
@@ -377,5 +384,7 @@
ds-u-margin-top--auto
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.measure/index.html b/docs/example/utilities.measure/index.html
index c9d649f627..93cc00b8d0 100644
--- a/docs/example/utilities.measure/index.html
+++ b/docs/example/utilities.measure/index.html
@@ -2,10 +2,22 @@
+
Example: utilities.measure
+
+
+
-
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.
-
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.
-
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.
+
+
ds-u-measure--narrow
+
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.
+
ds-u-measure--base
+
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.
+
ds-u-measure--wide
+
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.
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.overflow/index.html b/docs/example/utilities.overflow/index.html
new file mode 100644
index 0000000000..965a2e18a9
--- /dev/null
+++ b/docs/example/utilities.overflow/index.html
@@ -0,0 +1,30 @@
+
+
+
+
+
+ Example: utilities.overflow
+
+
+
+
+
+
+ ds-u-overflow--hidden
+
+
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.
+
+ ds-u-overflow--scroll
+
+
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.
+
+ ds-u-overflow--auto
+
+
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.
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.padding.responsive/index.html b/docs/example/utilities.padding.responsive/index.html
index bd607781b3..e0690d1a25 100644
--- a/docs/example/utilities.padding.responsive/index.html
+++ b/docs/example/utilities.padding.responsive/index.html
@@ -2,12 +2,21 @@
+
Example: utilities.padding.responsive
+
+
+
-
-
- Responsive padding
+
+
+
+ Responsive padding
-
+
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.padding/index.html b/docs/example/utilities.padding/index.html
index 92bbdde4b8..36ddc54cf0 100644
--- a/docs/example/utilities.padding/index.html
+++ b/docs/example/utilities.padding/index.html
@@ -2,232 +2,241 @@
+
Example: utilities.padding
+
+
+
-
- ds-u-padding--0
+
+
+ ds-u-padding--0
-
- ds-u-padding--1
+
+ ds-u-padding--1
-
- ds-u-padding--2
+
+ ds-u-padding--2
-
- ds-u-padding--3
+
+ ds-u-padding--3
-
- ds-u-padding--4
+
+ ds-u-padding--4
-
- ds-u-padding--5
+
+ ds-u-padding--5
-
- ds-u-padding--6
+
+ ds-u-padding--6
-
- ds-u-padding--7
+
+ ds-u-padding--7
-
- ds-u-padding-x--0
+
+ ds-u-padding-x--0
-
- ds-u-padding-x--1
+
+ ds-u-padding-x--1
-
- ds-u-padding-x--2
+
+ ds-u-padding-x--2
-
- ds-u-padding-x--3
+
+ ds-u-padding-x--3
-
- ds-u-padding-x--4
+
+ ds-u-padding-x--4
-
- ds-u-padding-x--5
+
+ ds-u-padding-x--5
-
- ds-u-padding-x--6
+
+ ds-u-padding-x--6
-
- ds-u-padding-x--7
+
+ ds-u-padding-x--7
-
- ds-u-padding-y--0
+
+ ds-u-padding-y--0
-
- ds-u-padding-y--1
+
+ ds-u-padding-y--1
-
- ds-u-padding-y--2
+
+ ds-u-padding-y--2
-
- ds-u-padding-y--3
+
+ ds-u-padding-y--3
-
- ds-u-padding-y--4
+
+ ds-u-padding-y--4
-
- ds-u-padding-y--5
+
+ ds-u-padding-y--5
-
- ds-u-padding-y--6
+
+ ds-u-padding-y--6
-
- ds-u-padding-y--7
+
+ ds-u-padding-y--7
-
- ds-u-padding-bottom--0
+
+ ds-u-padding-bottom--0
-
- ds-u-padding-bottom--1
+
+ ds-u-padding-bottom--1
-
- ds-u-padding-bottom--2
+
+ ds-u-padding-bottom--2
-
- ds-u-padding-bottom--3
+
+ ds-u-padding-bottom--3
-
- ds-u-padding-bottom--4
+
+ ds-u-padding-bottom--4
-
- ds-u-padding-bottom--5
+
+ ds-u-padding-bottom--5
-
- ds-u-padding-bottom--6
+
+ ds-u-padding-bottom--6
-
- ds-u-padding-bottom--7
+
+ ds-u-padding-bottom--7
-
- ds-u-padding-left--0
+
+ ds-u-padding-left--0
-
- ds-u-padding-left--1
+
+ ds-u-padding-left--1
-
- ds-u-padding-left--2
+
+ ds-u-padding-left--2
-
- ds-u-padding-left--3
+
+ ds-u-padding-left--3
-
- ds-u-padding-left--4
+
+ ds-u-padding-left--4
-
- ds-u-padding-left--5
+
+ ds-u-padding-left--5
-
- ds-u-padding-left--6
+
+ ds-u-padding-left--6
-
- ds-u-padding-left--7
+
+ ds-u-padding-left--7
-
- ds-u-padding-right--0
+
+ ds-u-padding-right--0
-
- ds-u-padding-right--1
+
+ ds-u-padding-right--1
-
- ds-u-padding-right--2
+
+ ds-u-padding-right--2
-
- ds-u-padding-right--3
+
+ ds-u-padding-right--3
-
- ds-u-padding-right--4
+
+ ds-u-padding-right--4
-
- ds-u-padding-right--5
+
+ ds-u-padding-right--5
-
- ds-u-padding-right--6
+
+ ds-u-padding-right--6
-
- ds-u-padding-right--7
+
+ ds-u-padding-right--7
-
- ds-u-padding-top--0
+
+ ds-u-padding-top--0
-
- ds-u-padding-top--1
+
+ ds-u-padding-top--1
-
- ds-u-padding-top--2
+
+ ds-u-padding-top--2
-
- ds-u-padding-top--3
+
+ ds-u-padding-top--3
-
- ds-u-padding-top--4
+
+ ds-u-padding-top--4
-
- ds-u-padding-top--5
+
+ ds-u-padding-top--5
-
- ds-u-padding-top--6
+
+ ds-u-padding-top--6
-
- ds-u-padding-top--7
+
+ ds-u-padding-top--7
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.text-align.responsive/index.html b/docs/example/utilities.text-align.responsive/index.html
index 3327a5804f..1799047151 100644
--- a/docs/example/utilities.text-align.responsive/index.html
+++ b/docs/example/utilities.text-align.responsive/index.html
@@ -2,10 +2,19 @@
+
Example: utilities.text-align.responsive
+
+
+
-
+
+
We the People of the United States
-
+
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.text-align/index.html b/docs/example/utilities.text-align/index.html
index fbecd5811c..d54dc3cd44 100644
--- a/docs/example/utilities.text-align/index.html
+++ b/docs/example/utilities.text-align/index.html
@@ -2,10 +2,28 @@
+
Example: utilities.text-align
+
+
+
-
Center
-
Left
-
Right
+
+
+ ds-u-text-align--center
+ Center
+
+
+ ds-u-text-align--left
+ Left
+
+
+ ds-u-text-align--right
+ Right
+
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.text-decoration/index.html b/docs/example/utilities.text-decoration/index.html
index 3bb81e6739..227e7dc376 100644
--- a/docs/example/utilities.text-decoration/index.html
+++ b/docs/example/utilities.text-decoration/index.html
@@ -2,9 +2,20 @@
+
Example: utilities.text-decoration
+
+
+
-
Underlined text
-Link text without underline
+
+ ds-u-text-decoration--underline
+Underlined text
+ds-u-text-decoration--none
+Link text without underline
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.text-transform/index.html b/docs/example/utilities.text-transform/index.html
index baf97da38c..b95f7be6bf 100644
--- a/docs/example/utilities.text-transform/index.html
+++ b/docs/example/utilities.text-transform/index.html
@@ -2,10 +2,22 @@
+
Example: utilities.text-transform
+
+
+
-
uppercase transform
-
Lowercase transform
-
capitalized transform
+
+ ds-u-text-transform--uppercase
+
We the People of the United States, in Order to form a more perfect Union
+ds-u-text-transform--lowercase
+
We the People of the United States, in Order to form a more perfect Union
+ds-u-text-transform--capitalize
+
We the People of the United States, in Order to form a more perfect Union
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.truncate/index.html b/docs/example/utilities.truncate/index.html
index 826611035d..43bc2c45f1 100644
--- a/docs/example/utilities.truncate/index.html
+++ b/docs/example/utilities.truncate/index.html
@@ -2,8 +2,19 @@
+
Example: utilities.truncate
+
+
+
-
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.
+
+
+ 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.
+
+
+
\ No newline at end of file
diff --git a/docs/example/utilities.vertical-align/index.html b/docs/example/utilities.vertical-align/index.html
index aab54d5869..a0efcabdfb 100644
--- a/docs/example/utilities.vertical-align/index.html
+++ b/docs/example/utilities.vertical-align/index.html
@@ -2,23 +2,41 @@
+
Example: utilities.vertical-align
+
+
+
-
+
+
-
A
-
Top alignment
+
A
+
+ ds-u-valign--top
+ Top alignment
+
-
B
-
Middle alignment
+
B
+
+ ds-u-valign--middle
+ Middle alignment
+
-
C
-
Bottom alignment
+
C
+
+ ds-u-valign--bottom
+ Bottom alignment
+
-
+
+
+
\ No newline at end of file
diff --git a/docs/example/utilities/index.html b/docs/example/utilities/index.html
index a4efce892b..d34dfcc910 100644
--- a/docs/example/utilities/index.html
+++ b/docs/example/utilities/index.html
@@ -2,10 +2,19 @@
+
Example: utilities
+
+
+
-
+
+
Hello world
-
+
+
+
\ No newline at end of file
diff --git a/docs/getting-started/index.html b/docs/getting-started/index.html
new file mode 100644
index 0000000000..f3d3680c51
--- /dev/null
+++ b/docs/getting-started/index.html
@@ -0,0 +1,115 @@
+
+
+
+
+ Getting started - CMSGov Design System
+
+
+
+
+
+
+
+
+
+
+
You can change the default paths by overriding the following Sass variables:
+
+
$font-path
+
$image-path
+
+
Usage
+
+
We offer two versions of design system assets: a minified + compiled version (located in a dist directory), and an un-minified + non-compiled version (located in a src directory). Use the minified version in production environments. Use the un-minified version in a development environment to debug in the browser, or if you'd like to manage the un-compiled files with your own build system.
+
Below are examples of the various ways you can reference the design system's styles and components:
+
Styles
+
Minified CSS
+
+
The easiest way to add the design system's styles to your site is by referencing its minified CSS.
+
+
Copy the design system's dist/css folder into a relevant place in your code base โ likely a directory where you keep third-party libraries. In the example below, our directory is css/vendor.
+
Add a <link> to the stylesheet in your site's <head>
If you're already using Sass to style your site, another way to include the design system's styles is by importing its un-minified Sass file.
+
+
First, make sure your build system is configured so that the node_modules directory is in the list of Sass includePaths.
+
Add the following to your Sass file:
@import'@cmsgov/design-system-core/src/index';
+
+
To override any of the design system's Sass variables, include the variable definitions before the line where the design system is imported. For example:
Once your page is loading the design system's CSS, you can then begin applying its styling to your pages. Below is an example of a project applying the base-level of styles and a utility class.
Components can also be imported using the shorter syntax below.
+
+
+
Performance note
+
+ This approach may result in a much larger file than you intend. Depending on what module bundler you use, all of the design system's React components may be included in the bundled file even if you didn't specifically import them. This can be avoided by enabling features like tree shaking in Webpack.
+
Additional examples of the design system in use can be viewed on GitHub. These projects demonstrate the various ways you can incorporate the design system into your development process and various use cases.
If you're having trouble installing or setting up the design system, or if you think you've found a bug, feel free to open an issue on GitHub.
+
Menu
+
+
+
+
+
\ No newline at end of file
diff --git a/docs/guidelines/code-conventions/index.html b/docs/guidelines/code-conventions/index.html
index a502932d54..969f2d4ee2 100644
--- a/docs/guidelines/code-conventions/index.html
+++ b/docs/guidelines/code-conventions/index.html
@@ -2,18 +2,22 @@
- Code conventions - CMS.gov Design System
+ Code conventions - CMSGov Design System
+
-
+
+
+
+
+
-
CMS.gov Design System
Code conventions
- The design system favors clarity over succinctness. This means the design system may be verbose, but it should deliver clarity and resilience in exchange. Keeping CSS legible and scalable means sacrificing a shorter syntax.
-
The design system favors clarity over succinctness. This means the design system may be verbose, but it should deliver clarity, predictability, and legibility in exchange.
+
CSS class naming convention
Namespace
To avoid conflicting with other libraries and existing code, the design system namespaces its CSS class names with ds-.
@@ -29,7 +33,7 @@
Prefix
l-
-
Indicates layout-related styles. These classes may be used in any number of unrelated contexts. Example: .ds-l-container
Following the namespace and prefix is a name conforming to BEM syntax.
Put all together, a CSS class can be broken down to these key parts: [NAMESPACE]-[PREFIX]-[BLOCK]__[ELEMENT]--[MODIFIER]
-
Block is a standalone entity that is meaningful on its own. For example: .ds-c-card, .ds-c-button
-
Element is a part of a block that has no standalone meaning and is semantically tied to its block, such as .ds-c-card__title
-
Modifier is a flag on a block or element and is used to change appearance or behavior. For example: .ds-c-button--primary, ds-u-color--primary, ds-u-margin--3
+
Block is a standalone entity that is meaningful on its own. For example: ds-c-card, ds-c-button
+
Element is a part of a block that has no standalone meaning and is semantically tied to its block, such as ds-c-card__title
+
Modifier is a flag on a block or element and is used to change appearance or behavior. For example: ds-c-button--primary, ds-u-color--base, ds-l-col--3
Below are some best practices your project should aim to follow in order to provide the most accessible and usable experience for your users. Additional guidance, specific to each form field, is provided in each component's guidance tab.
Best practices
@@ -30,8 +37,8 @@
Hint text
Place hint text within the field's <label> element.
Apply the ds-c-field__hint class to hint text.
-
Use hint text for supporting contextual help, this will always be shown.
-
Hint text should sit above a form field, and below the label text.
+
Use hint text for supporting contextual help, which will always be shown.
+
Hint text should sit above a form field and below the label text.
The design system's layout, utility, and typography classes are built with responsive web design in mind and is built to be mobile first. Use the prefixes sm, md, lg, and xl to quickly and easily adjust your layout and content for different screen sizes and devices. Further info and usage examples are available on the individual documentation pages.
Additional usage examples are available on the pages listed above.
+
Menu
diff --git a/docs/index.html b/docs/index.html
index 90c90cff20..a4b35d83ec 100644
--- a/docs/index.html
+++ b/docs/index.html
@@ -2,79 +2,44 @@
- Getting started - CMS.gov Design System
+ Introduction - CMSGov Design System
+
-
+
+
+
+
+
-
CMS.gov Design System
Getting started
The design system is a shared set of design and development resources for creating accessible and consistent websites. The design system includes things like principles, high-level guidelines (UX conventions, UI code conventions, etc), UI components, documentation, tools, resources, and more.
-
-
Installation
-
We suggest using a package manager like NPM or Yarn to install the design system package if you're working on a real world project. This way you can easily update the package when there's a new release.
-
npm install --save @cmsgov/design-system-core
or if you're using Yarn:
-
yarn add @cmsgov/design-system-core
You can also download a .zip of the design system directly from our GitHub repo.
-
Fonts and images
-
Copy the design system's fonts and images directories into the same directory as your site's CSS.
-
By default, the design system expects a file structure like this:
-
โโโ Your site's public assets directory/
- โโโ bundle.css
- โโโ fonts/
- โโโ images/
The design system is a set of open source design and front-end development resources for creating Section 508 compliant, responsive, and consistent websites. It builds on the U.S. Web Design Standards and extends it to support additional CSS and React components, utility classes, and a grid framework to allow teams to quickly prototype and build accessible, responsive, production-ready websites.
+
It is currently being applied to HealthCare.gov. It is open source and freely available to use by anyone.
Help create consistent, enjoyable, reliable, and Section 508 compliant websites.
+
Promote best practices for usability, accessibility, and responsive web design.
+
Empower teams and speed up design and development velocity.
+
Serve as a living source of truth for UI standards.
-
Usage
-
Below are examples of the various ways you can reference the design system's styles and React components:
-
Styles
-
Using the bundled CSS file
-
The easiest way to add the design system's styles to your site is by referencing its bundled CSS file.
-
-
Copy the design system's dist/css folder into a relevant place in your code base โ likely a directory where you keep third-party libraries. In the example below, our directory is css/vendor.
-
Add a <link> to the stylesheet in your site's <head>
Once your page is loading the design system's CSS, you can then begin adding its CSS class names to utilize the system. Below is an example of a project applying the base-level of styles and a utility class.
Components can also be imported using the shorter syntax below.
-
-
-
A note on performance
-
- This approach may result in a much larger file than you intend. Depending on what module bundler you use, all of the design system's React components may be included in the bundled file even if you didn't specifically import them. This can be avoided by enabling features like tree shaking in Webpack.
-
View example projects to see ways you can use the design system and incorporate it into your development process.
-
Credits
-
Our design system is a variation and extension of the U.S. Web Design Standards. Thank you to 18F and GSA for the hard work they put into the Standards. We're excited to contribute our learnings and progress.
-
+
In order to meet these goals we are:
+
+
Using the U.S. Web Design Standards components and visual design as a foundation. Read more about how we're applying the Standards in our GitHub Wiki.
+
Reducing the overall footprint of websites by writing scalable CSS.
+
Supporting rapid development with utility classes and easy-to-use components with best practices baked in.
+
Reducing the number of decisions needed when iterating on UI by providing a solid foundation of typography, layout, and color.
+
Distributing resources as NPM packages which can be easily installed, updated, and imported.
Flexbox grid supports modern browsers and Internet Explorer 10+. In older versions of Internet Explorer the grid columns will be stacked.
Default behavior
Columns without a set width will automatically layout with equal widths. For example, below are four instances of .ds-l-col which are each automatically 25% wide. The columns will automatically wrap when they don't fit a single row.
-
Column widths are set in percentages, so theyโre always responsive and will be sized relative to their parent row.
Flexbox grid supports modern browsers and Internet Explorer 10+. In older versions of Internet Explorer the grid columns will be stacked.
Default behavior
Columns without a set width will automatically layout with equal widths. For example, below are four instances of .ds-l-col which are each automatically 25% wide. The columns will automatically wrap when they don't fit a single row.
+
Column widths are set in percentages, so theyโre always responsive and will be sized relative to their parent row.
<sectionclass="ds-l-container preview__grid"><divclass="ds-l-row"><divclass="ds-l-col">
Auto
@@ -35,7 +42,7 @@
Browser support
Auto
</div></div>
-</section>
Specifying number of columns
Specify the number of columns (1-12) to span using .ds-l-col--* classes. These classes will span * columns. So, if you want two elements that each span half the row, you would use .ds-l-col--6
Specify the number of columns (1-12) to span using .ds-l-col--* classes. These classes will span * columns. So, if you want two elements that each span half the row, you would use .ds-l-col--6
Align columns horizontally or vertically using flexbox utility classes. To align columns horizontally, use the justify-content utility class. To align columns vertically, use the align-items utility class.
Align columns horizontally or vertically using flexbox utility classes. To align columns horizontally, use the justify-content utility class. To align columns vertically, use the align-items utility class.
The design system uses multiples of 8px for all spacing values: dimensions, padding, and margin. The primary goal behind this is to achieve a consistent vertical rhythm and to reduce the cognitive load of fiddling with different spacing options.
The design system uses multiples of 8px for all spacing values: dimensions, padding, and margins. The goal behind this is to achieve a consistent vertical rhythm and to reduce the cognitive load of fiddling with different spacing options.
Usage
-
Use the margin and padding utility classes to change the spacing of your design elements. These utility classes are named in a way that allows you to use the modifier to calculate the amount of spacing. For example, a margin utility class that adds 16px of spacing would be ds-u-margin--2. We can calculate this by looking at the class's modifier (2) and multiplying that by our multiple: 2 ร 8px = 16px
+
Use the margin and padding utility classes to change a UI's spacing. These utility classes are named in a way that allows you to use the modifier to calculate the amount of spacing. For example, a margin utility class that adds 16px of spacing would be ds-u-margin--2. We can calculate this by looking at the class's modifier (2) and multiplying that by our multiple: 2 ร 8px = 16px
+
If you've imported the design system's Sass file, you can also use the spacer Sass variables, which follow the format $spacer-* where * is a number between 1โ7 (i.e. $spacer-4)
A documentation page presents information on a certain theme, topic, or idea. People often arrive here after visiting the landing page or after searching for a specific piece of information, so documentation pages donโt need to provide as much contextualizing information as more introductory pages would.
A documentation page presents information on a certain theme, topic, or idea. People often arrive here after visiting the landing page or after searching for a specific piece of information, so documentation pages donโt need to provide as much contextualizing information as more introductory pages would.
<mainclass="ds-base ds-l-container">
+ <aclass="ds-c-skip-nav"href="#content">Skip to main content</a><divclass="ds-l-row"><asideclass="ds-u-margin-bottom--4 ds-u-md-margin-bottom--0 ds-l-md-col--4 ds-l-lg-col--3"><ulclass="ds-c-vertical-nav"><liclass="ds-c-vertical-nav__item">
- <aclass="ds-c-vertical-nav__link"href="javascript:void(0);">
+ <aclass="ds-c-vertical-nav__label"href="javascript:void(0);">
Page title
</a></li><liclass="ds-c-vertical-nav__item">
- <aclass="ds-c-vertical-nav__link ds-c-vertical-nav__link--current"href="javascript:void(0);">
+ <aclass="ds-c-vertical-nav__label ds-c-vertical-nav__label--current"href="javascript:void(0);">
Page heading (h1)
</a><ulclass="ds-c-vertical-nav__subnav"><liclass="ds-c-vertical-nav__item">
- <aclass="ds-c-vertical-nav__link"href="#section-heading-h2">
+ <aclass="ds-c-vertical-nav__label"href="#section-heading-h2">
Section heading (h2)
</a></li><liclass="ds-c-vertical-nav__item">
- <aclass="ds-c-vertical-nav__link"href="#section-heading-h3">
+ <aclass="ds-c-vertical-nav__label"href="#section-heading-h3">
Subsection heading (h3)
</a></li><liclass="ds-c-vertical-nav__item">
- <aclass="ds-c-vertical-nav__link"href="#section-heading-h4">
+ <aclass="ds-c-vertical-nav__label"href="#section-heading-h4">
Subsection heading (h4)
</a></li></ul></li><liclass="ds-c-vertical-nav__item">
- <aclass="ds-c-vertical-nav__link"href="javascript:void(0);">
+ <aclass="ds-c-vertical-nav__label"href="javascript:void(0);">
Page title
</a></li></ul></aside>
- <articleclass="ds-l-md-col--8 ds-l-lg-col--9">
+ <articleid="content"class="ds-l-md-col--8 ds-l-lg-col--9"><h1class="ds-h1">Page heading (h1)</h1><pclass="ds-text--lead">The page heading communicates the main focus of the page. Make your page heading descriptive and keep it succinct.</p><h2class="ds-h2"id="section-heading-h2">Section heading (h2)</h2>
@@ -60,7 +68,7 @@
<pclass="ds-text">Use the vertical navigation menu to help your users quickly skip to different sections of your page. The menu is best suited to displaying a hierarchy with one to three levels and, as we mentioned, to display the sub-navigation of a given page.</p></article></div>
-</main>
When to use
+</main>
When to use
If youโre presenting detailed information on a specific topic or theme that has already been contextualized by a landing page. Some topics that can be nicely represented on this type of page include guides or how-tos, technical documentation, and program descriptions โ in short, any subject that requires in-depth explanation.