chore: update form docs #4349
Open
chore: update form docs #4349
+151
−403
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
|
|
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
|
dosubot
bot
added
the
size:L
github-actions
bot
added
Type: Documentation
|
View your CI Pipeline Execution ↗ for commit d999a96
☁️ Nx Cloud last updated this comment at |
|
View your CI Pipeline Execution ↗ for commit 63c6faf.
☁️ Nx Cloud last updated this comment at |
|
Size Change: 0 B Total Size: 1.13 MB ℹ️ View Unchanged
|
Paste
|
||||||||||||||||||||||||||||
| Project |
Paste
|
| Branch Review |
docs/form-layout
|
| Run status |
|
| Run duration | 04m 15s |
| Commit |
|
| Committer | “nora |
| View all properties for this run ↗︎ | |
| Test results | |
|---|---|
Failures
|
0
|
Flaky
|
0
|
Pending
|
0
|
Skipped
|
0
|
Passing
|
69
|
| View all changes introduced in this branch ↗︎ | |
|
This pull request is automatically built and testable in CodeSandbox. To see build info of the built libraries, click here or the icon next to each commit SHA. Latest deployment of this branch, based on commit d999a96:
|
nkrantz
force-pushed
the
docs/form-layout
branch
from
63c6faf to
be42b0d
Compare
dosubot
bot
added
size:XL
nkrantz
force-pushed
the
docs/form-layout
branch
from
ffeaaf7 to
d999a96
Compare
PixeledCode
approved these changes
Jul 31, 2025
serifluous
reviewed
Jul 31, 2025
| @@ -107,8 +111,7 @@ A checkbox is always displayed next to a visible label. | |||
|
|
|||
| ### Checkbox with help text | |||
|
|
|||
| In cases where the checkbox requires additional context, you can display this information as help text below the checkbox control and label. This can help keep checkbox labels concise. In order to maintain styling consistency, be sure to use the `helpText` prop here instead of using the Help Text component. | |||
|
|
|||
| Use Checkbox with Help Text in cases where the checkbox requires additional context. In order to maintain styling consistency, be sure to use the `helpText` prop here instead of using the Help Text component. | |||
There was a problem hiding this comment.
Suggested change
| Use Checkbox with Help Text in cases where the checkbox requires additional context. In order to maintain styling consistency, be sure to use the `helpText` prop here instead of using the Help Text component. | |
| Use Checkbox with help text in cases where the checkbox requires additional context. In order to maintain styling consistency, be sure to use the `helpText` prop here instead of using the Help Text component. |
serifluous
reviewed
Jul 31, 2025
| - The label may be visually hidden or provided via `aria-label` on the group component if the entire form is just a single checkbox group with no other form elements. The grouping should be visually implicit, but a description still needs to be provided for assistive technology. | ||
| - Checkbox Group must have a group legend that describes the collection. The label should be visible. However if the entire form is just a single checkbox group with no other form elements, it may be visually hidden or provided via `aria-label` on the group component. The grouping should be visually implicit, but a description still needs to be provided for assistive technology. | ||
| - Checkbox must have a visible label. | ||
| - When displaying additional content based on checking a checkbox, be sure that the new content appears after the checkbox so that it is naturally discoverable by assistive technology users. | ||
|
|
There was a problem hiding this comment.
chore: Remove the sections below ("Checkbox" and "Accessibility") since they repeat what's above it.
serifluous
reviewed
Jul 31, 2025
| @@ -117,17 +120,29 @@ In cases where the checkbox requires additional context, you can display this in | |||
|
|
|||
| ### Required checkbox | |||
There was a problem hiding this comment.
Suggested change
| ### Required checkbox | |
| ### Required Checkbox |
serifluous
reviewed
Jul 31, 2025
| </LivePreview> | ||
|
|
||
| ## Checkbox Group examples | ||
|
|
||
| ### Basic checkbox group |
There was a problem hiding this comment.
Suggested change
| ### Basic checkbox group | |
| ### Basic Checkbox Group |
serifluous
reviewed
Jul 31, 2025
| @@ -145,7 +160,7 @@ Multiple checkboxes and their labels are grouped together with a common group co | |||
|
|
|||
| ### Checkbox group with help text | |||
There was a problem hiding this comment.
Suggested change
| ### Checkbox group with help text | |
| ### Checkbox Group with help text |
serifluous
reviewed
Jul 31, 2025
| @@ -145,7 +160,7 @@ Multiple checkboxes and their labels are grouped together with a common group co | |||
|
|
|||
| ### Checkbox group with help text | |||
|
|
|||
| You can provide additional information about the group with the use of help text. Help text can appear after the group label but before the first group member. Each item in the group may also provide their own, individual help text. | |||
| Use help text to give more context about a Checkbox group. In order to maintain styling consistency, be sure to use the helpText prop here instead of using the Help Text component. Individual checkboxes can also include their own help text if needed. | |||
There was a problem hiding this comment.
Suggested change
| Use help text to give more context about a Checkbox group. In order to maintain styling consistency, be sure to use the helpText prop here instead of using the Help Text component. Individual checkboxes can also include their own help text if needed. | |
| Use help text to give more context about a Checkbox group. In order to maintain styling consistency, be sure to use the `helpText` prop here instead of using the Help Text component. Individual checkboxes can also include their own help text if needed. |
serifluous
reviewed
Jul 31, 2025
| </Checkbox> | ||
| </CheckboxGroup>`} | ||
| </LivePreview> | ||
|
|
||
| ### Checkbox group with an inline error | ||
| ### Checkbox group with an error |
There was a problem hiding this comment.
Suggested change
| ### Checkbox group with an error | |
| ### Checkbox Group with an error |
serifluous
reviewed
Jul 31, 2025
|
|
||
| Use the Form component to arrange a layout of form elements with preset spacing. | ||
| The Form component renders an HTML form element and comes with default behavior from the browser ([learn more about HTML form elements](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/form)). Form elements are displayed vertically by default, but also support horizontal and 2-column layouts. | ||
| Use the Form Layout component to arrange a layout of form elements with preset spacing. Refer to our [form pattern](/patterns/form) for additional guidance on types of forms and common form fields. |
There was a problem hiding this comment.
Suggested change
| Use the Form Layout component to arrange a layout of form elements with preset spacing. Refer to our [form pattern](/patterns/form) for additional guidance on types of forms and common form fields. | |
| Use the Form Layout component to arrange a layout of form elements with preset spacing. Refer to our [Form pattern](/patterns/form) for additional guidance on types of forms and common form fields. |
serifluous
reviewed
Jul 31, 2025
| If the input has any associated help text, the input should also use the <InlineCode>aria-describedby</InlineCode>{' '} | ||
| prop that equals the <InlineCode>id</InlineCode> of the help text. This ensures screen readers know the help text | ||
| ties directly to the input. | ||
| Check accessibility for each form element component—for example, follow [Time Picker accessibility guidelines](https://paste.twilio.design/components/time-picker#accessibility). You can also refer to the [WCAG Forms Tutorial](https://www.w3.org/WAI/tutorials/forms/) for more details. |
There was a problem hiding this comment.
chore: Need to use the Anchor component here
serifluous
reviewed
Jul 31, 2025
| ### Sections | ||
|
|
||
| Use sections to group related content or steps within a Form. A section is separated using a [Separator](/components/separator), with `$space-90` above and below it. | ||
| ### Form Layouts with sections |
There was a problem hiding this comment.
Suggested change
| ### Form Layouts with sections | |
| ### Form Layout with sections |
serifluous
reviewed
Jul 31, 2025
| The Form component ensures there is adequate spacing between form elements so users know which label belongs to which input. Typically, 50-75% of the height of a form element helps create this adequate spacing, so we’ve chosen to use `$space-80` between all form elements. | ||
|
|
||
| #### Single column vs. multiple columns | ||
| Designing a good form requires making decisions about composition, sequence, form elements, content, and feedback. Use the [form pattern](/patterns/form) for further guidance on form order and organization. |
There was a problem hiding this comment.
Suggested change
| Designing a good form requires making decisions about composition, sequence, form elements, content, and feedback. Use the [form pattern](/patterns/form) for further guidance on form order and organization. | |
| Designing a good form requires making decisions about composition, sequence, form elements, content, and feedback. Use the [Form pattern](/patterns/form) for further guidance on form order and organization. |
serifluous
reviewed
Jul 31, 2025
|
|
||
| ### Composing a form | ||
| <DetailText>Do keep all the form elements left aligned. Avoid adding any left padding to the form fields or form actions.</DetailText> |
There was a problem hiding this comment.
Suggested change
| <DetailText>Do keep all the form elements left aligned. Avoid adding any left padding to the form fields or form actions.</DetailText> | |
| <DetailText marginTop='space0'>Keep all form elements left-aligned. Avoid adding any left padding to the form fields or form actions.</DetailText> |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
Uh oh!
There was an error while loading. Please reload this page.