Merge pull request #22 from CMSgov/staging

Rearrange detailed component guidance

packages/core/src/components/ChoiceList/Choice.scss

@@ -42,17 +42,6 @@ Checkbox
 
 Checkboxes allow users to select one or more options from a visible list.
 
-## Usability
-
-### When to use
-- When a user can select any number of choices from a set list.
-- When a user needs to choose “yes” or “no” on only one option (use a stand-alone checkbox). For example, to toggle a setting on or off.
-- When users need to see all the available options at a glance.
-
-### When to consider something different
-- If there are too many options to display on a mobile screen.
-- If a user can only select one option from a list (use `radio` buttons instead).
-
 Markup:
 <h3 class="ds-c-label ds-u-margin-top--0">Historical figures</h3>
 <span class="ds-c-field__hint">Select all that apply</span>
@@ -86,21 +75,26 @@ Style guide: components.checkbox-radio.checkbox
 */
 
 /*
-Radio option
-
-@uswds https://standards.usa.gov/components/form-controls/#radio-buttons
+---
 
 ## Usability
 
 ### When to use
+- When a user can select any number of choices from a set list.
+- When a user needs to choose “yes” or “no” on only one option (use a stand-alone checkbox). For example, to toggle a setting on or off.
+- When users need to see all the available options at a glance.
 
-- When users need to select only one option out of a set of mutually exclusive choices.
-- When the number of available options can fit onto a mobile screen.
+### When to consider something different
+- If there are too many options to display on a mobile screen.
+- If a user can only select one option from a list (use `radio` buttons instead).
 
-### When to consider something else
-- Consider checkboxes if users need to select more than one option or if there is only one item to select.
-- Consider a dropdown if you don’t have enough space to list out all available options.
-- If users should be able to select zero of the options.
+Style guide: components.checkbox-radio.checkbox-details
+*/
+
+/*
+Radio option
+
+@uswds https://standards.usa.gov/components/form-controls/#radio-buttons
 
 Markup:
 <h3 class="ds-c-label ds-u-margin-top--0">Select a historical figure</h3>
@@ -129,6 +123,24 @@ Markup:
 Style guide: components.checkbox-radio.radio
 */
 
+/*
+---
+
+## Usability
+
+### When to use
+
+- When users need to select only one option out of a set of mutually exclusive choices.
+- When the number of available options can fit onto a mobile screen.
+
+### When to consider something else
+- Consider checkboxes if users need to select more than one option or if there is only one item to select.
+- Consider a dropdown if you don’t have enough space to list out all available options.
+- If users should be able to select zero of the options.
+
+Style guide: components.checkbox-radio.radio-details
+*/
+
 // Hide the default browser checkbox/radio button since we'll
 // create our own custom version
 .ds-c-choice {

packages/core/src/components/TextField/TextField.scss

@@ -10,32 +10,6 @@ Text field
 
 A text field can be an `input` or `textarea` HTML element.
 
-## Accessibility
-
-- Display form controls in the same order in HTML as they appear on screen. Do not use CSS to rearrange the form controls. Screen readers narrate forms in the order they appear in the HTML.
-- Visually align validation messages with the input fields, so people using screen magnifiers can read them quickly.
-- Group each set of thematically related controls in a fieldset element. Use the legend element to offer a label within each one. The fieldset and legend elements make it easier for screen reader users to navigate the form.
-- Use a single legend for fieldset (this is required). One example of a common use of fieldset and legend is a question with radio button options for answers. The question text and radio buttons are wrapped in a fieldset, with the question itself being inside the legend tag.
-- Embed multiple fieldsets and legends for more complex forms.x
-- Keep your form blocks in a vertical pattern. This approach is ideal, from an accessibility standpoint, because of limited vision that makes it hard to scan from right to left.
-
-## Usability
-
-### Guidance
-
-- The length of the text input provides a hint to users as to how much text to write. Do not require users to write paragraphs of text into a single-line `input` box; use a `textarea` instead.
-- Text inputs are among the easiest type of input for desktop users but are more difficult for mobile users.
-- Only show error messages or stylings after a user has interacted with a particular field.
-- Avoid using placeholder text that appears within a text field before a user starts typing. If placeholder text is no longer visible after a user clicks into the field, users will no longer have that text available when they need to review their entries. (People who have cognitive or visual disabilities have additional problems with placeholder text.)
-
-## Theming
-
-The following Sass variables can be overridden to theme a field: `$color-focus`, `$color-focus-inverse`, `$focus-shadow`, `$focus-shadow-inverse`, `$input-border-color`, `$input-border-color-inverse`, `$input-border-radius`, `$input-line-height`, `$input-border-width`, `$input-padding`
-
-## Further reading
-
-- ["Placeholders in Form Fields Are Harmful"](https://www.nngroup.com/articles/form-design-placeholders/)
-
 Markup:
 <label class="ds-c-label ds-u-margin-top--0" for="input-firstname">
   First name
@@ -122,3 +96,35 @@ Style guide: components.text-field.inverse
 .ds-c-field--success {
   border: 3px solid $color-success-light;
 }
+
+/*
+---
+
+## Accessibility
+
+- Display form controls in the same order in HTML as they appear on screen. Do not use CSS to rearrange the form controls. Screen readers narrate forms in the order they appear in the HTML.
+- Visually align validation messages with the input fields, so people using screen magnifiers can read them quickly.
+- Group each set of thematically related controls in a fieldset element. Use the legend element to offer a label within each one. The fieldset and legend elements make it easier for screen reader users to navigate the form.
+- Use a single legend for fieldset (this is required). One example of a common use of fieldset and legend is a question with radio button options for answers. The question text and radio buttons are wrapped in a fieldset, with the question itself being inside the legend tag.
+- Embed multiple fieldsets and legends for more complex forms.x
+- Keep your form blocks in a vertical pattern. This approach is ideal, from an accessibility standpoint, because of limited vision that makes it hard to scan from right to left.
+
+## Usability
+
+### Guidance
+
+- The length of the text input provides a hint to users as to how much text to write. Do not require users to write paragraphs of text into a single-line `input` box; use a `textarea` instead.
+- Text inputs are among the easiest type of input for desktop users but are more difficult for mobile users.
+- Only show error messages or stylings after a user has interacted with a particular field.
+- Avoid using placeholder text that appears within a text field before a user starts typing. If placeholder text is no longer visible after a user clicks into the field, users will no longer have that text available when they need to review their entries. (People who have cognitive or visual disabilities have additional problems with placeholder text.)
+
+## Theming
+
+The following Sass variables can be overridden to theme a field: `$color-focus`, `$color-focus-inverse`, `$focus-shadow`, `$focus-shadow-inverse`, `$input-border-color`, `$input-border-color-inverse`, `$input-border-radius`, `$input-line-height`, `$input-border-width`, `$input-padding`
+
+## Further reading
+
+- ["Placeholders in Form Fields Are Harmful"](https://www.nngroup.com/articles/form-design-placeholders/)
+
+Style guide: components.text-field.details
+*/

tools/gulp/docs/index.js

@@ -87,7 +87,7 @@ module.exports = (gulp, shared) => {
       'Copying fonts from core package into "public" directory'
     );
 
-    return gulp.src('packages/core/dist/**/fonts/*')
+    return gulp.src('packages/core/src/**/fonts/*')
       .pipe(gulp.dest(`${docs}/build/public`));
   });