From 174cd8235a202d1fbc8584ef6864418b68c0beb5 Mon Sep 17 00:00:00 2001 From: Heather Barranco Date: Tue, 21 Jul 2026 14:40:48 -0400 Subject: [PATCH] feat(docs): add core input component pages (batch A) Ports Button, Checkbox, Combobox, Date picker, Text input, and Toggle switch from the stale content-guidelines-docs branch (#766) as the first of several small batches, since all six have exact-match component coverage in both Zeroheight and apollo-wind already. Co-Authored-By: Claude Sonnet 5 --- apps/apollo-docs/app/components/_meta.ts | 6 ++ .../app/components/button/page.mdx | 76 ++++++++++++++++++ .../app/components/checkbox/page.mdx | 46 +++++++++++ .../app/components/combobox/page.mdx | 38 +++++++++ .../app/components/date-picker/page.mdx | 55 +++++++++++++ .../app/components/text-input/page.mdx | 80 +++++++++++++++++++ .../app/components/toggle-switch/page.mdx | 51 ++++++++++++ 7 files changed, 352 insertions(+) create mode 100644 apps/apollo-docs/app/components/button/page.mdx create mode 100644 apps/apollo-docs/app/components/checkbox/page.mdx create mode 100644 apps/apollo-docs/app/components/combobox/page.mdx create mode 100644 apps/apollo-docs/app/components/date-picker/page.mdx create mode 100644 apps/apollo-docs/app/components/text-input/page.mdx create mode 100644 apps/apollo-docs/app/components/toggle-switch/page.mdx diff --git a/apps/apollo-docs/app/components/_meta.ts b/apps/apollo-docs/app/components/_meta.ts index fbc24b235..f300ac121 100644 --- a/apps/apollo-docs/app/components/_meta.ts +++ b/apps/apollo-docs/app/components/_meta.ts @@ -1,3 +1,9 @@ export default { overview: 'Overview', + button: 'Button', + checkbox: 'Checkbox', + combobox: 'Combobox', + 'date-picker': 'Date picker', + 'text-input': 'Text input', + 'toggle-switch': 'Toggle switch', }; diff --git a/apps/apollo-docs/app/components/button/page.mdx b/apps/apollo-docs/app/components/button/page.mdx new file mode 100644 index 000000000..379089603 --- /dev/null +++ b/apps/apollo-docs/app/components/button/page.mdx @@ -0,0 +1,76 @@ +# Button + +Buttons are clickable items used to perform an action. + +## Usage + +Buttons should be used in situations where users might need to: + +- Submit a form +- Begin a new task +- Trigger a new UI element to appear on the page +- Specify a new or next step in a process + +## Anatomy + +Buttons consist of a text label, icon, container, or a combination of these elements. + +| Element | Description | +|---|---| +| **Button label** | Relies on an active verb that encourages the user to take action | +| **Button container** | The visual boundary of the button | + +## Appearance + +### Action styles + +Button has four core action types: + +| Style | Usage | +|---|---| +| **Primary (Contained)** | For the principal call to action on the page. High contrast; use sparingly — ideally one per page. | +| **Secondary (Outlined)** | For secondary actions. Less contrasted; good for layouts with multiple buttons. Always used in conjunction with a primary button. | +| **Tertiary** | For the least prominent actions, often used alongside primary and secondary buttons (e.g., *Cancel* in a multi-step flow). | +| **Destructive** | For actions that could have destructive effects on the user's data (e.g., delete or remove). | + +### Button vs. link + +Buttons enable users to perform an action (submit, add, save, open a modal). Text links enable users to navigate to other locations. Don't use them interchangeably. + +### Buttons with icons + +- Use 16px icons within buttons +- Icons must be directly related to the action +- Icons must match the text color value +- Don't use icons for decoration + +## Size + +- **40px** (tall): the most commonly used height +- **32px** (small): for contexts where a smaller button is more appropriate + +Default width is defined by text length; minimum width is 120px. + +## Placement + +Most common usage is in forms, panels, and dialogs, aligned to the bottom right. The primary button is on the right when paired. + +## States + +Buttons communicate five states: enabled, hover, press, focus, and disabled. + +A focus indicator appears around a button when navigated via keyboard. Focus states do not appear on disabled buttons. + +## Guidelines + +- Use clear, straightforward verbs to describe the implied action +- When possible, use verb + noun construction (e.g., *Save project*) +- Don't use "Click here" or "Go to somewhere" — use specific labels instead +- Avoid multiple primary buttons on a page +- Use sentence-case capitalization for button labels +- Avoid disabled buttons in forms — use validation and errors to show what needs to be done instead + +## Related + +- [Icon button](/components/icon-button) +- [Link](/components/link) diff --git a/apps/apollo-docs/app/components/checkbox/page.mdx b/apps/apollo-docs/app/components/checkbox/page.mdx new file mode 100644 index 000000000..14ed5c4f1 --- /dev/null +++ b/apps/apollo-docs/app/components/checkbox/page.mdx @@ -0,0 +1,46 @@ +# Checkbox + +A checkbox is an input control that allows a user to select one or more options from a number of choices. + +## Usage + +Checkboxes are used for multiple choices, not for mutually exclusive choices. Each checkbox works independently from other checkboxes in the list; checking an additional box doesn't affect any other selections. + +Use checkboxes: + +- For binary choices (single choice options) +- For providing multiple selectable choices + +## Anatomy + +| Element | Description | +|---|---| +| **Checkbox input** | The input control indicating the appropriate state. Unselected by default. | +| **Checkbox label** | Describes the information you want to select or unselect | +| **Group label** | (Optional) Used when there is a group of checkboxes | + +## Appearance + +### Orientation and label placement + +Checkbox labels are positioned to the right of their inputs. Groups can be laid out vertically or horizontally depending on the use case. + +### Wrapping + +Long labels may wrap to a second line — this is preferable to truncation. Text should wrap beneath the checkbox so the control and label are top-aligned. + +## States + +Checkbox interaction states: enabled, hover, focus, press, and disabled. + +Checkbox selection states: **checked**, **unchecked**, and **indeterminate**. + +## Guidelines + +- Keep checkbox labels short and descriptive +- All checkbox labels are written in sentence case without punctuation + +## Related + +- [Radio button](/components/radio-button) +- [Toggle switch](/components/toggle-switch) diff --git a/apps/apollo-docs/app/components/combobox/page.mdx b/apps/apollo-docs/app/components/combobox/page.mdx new file mode 100644 index 000000000..b21de735c --- /dev/null +++ b/apps/apollo-docs/app/components/combobox/page.mdx @@ -0,0 +1,38 @@ +# Combobox + +A combobox combines a text field and a dropdown, giving people a way to select an option from a list or enter their own text. + +## Usage + +A combobox combines the features of a dropdown and a text field. It allows users to select an option from a list of choices by clicking a dropdown arrow, revealing available options. Additionally, users can manually input text into the associated text field. + +The autocomplete feature enhances text input by predicting and suggesting possible completions or matches, reducing the amount of typing needed. + +Use a combobox when: + +- Users may need to choose from predefined options or enter custom text +- You need search or filter functionality in a form field + +If users only need to select from a fixed list with no free-text entry, use a [Dropdown](/components/dropdown) instead. + +## Anatomy + +| Element | Description | +|---|---| +| **Field label** | Describes the purpose of the input | +| **Input text** | The user's typed value | +| **Input field** | The text input container | +| **Menu item** | An individual selectable option | +| **Menu** | The dropdown list of options | + +## Accessibility + +When a user is focused on a combobox, the listbox opens. When a user makes a selection, the listbox closes so the selected option can be registered to screen readers. + +Built with consideration for the [ARIA combobox pattern](https://www.w3.org/WAI/ARIA/apg/patterns/combobox/). + +## Related + +- [Dropdown](/components/dropdown) +- [List](/components/list) +- [Menu](/components/menu) diff --git a/apps/apollo-docs/app/components/date-picker/page.mdx b/apps/apollo-docs/app/components/date-picker/page.mdx new file mode 100644 index 000000000..8ab2fd943 --- /dev/null +++ b/apps/apollo-docs/app/components/date-picker/page.mdx @@ -0,0 +1,55 @@ +# Date picker + +The date picker component allows users to select date and/or time from a visual calendar or dropdown. + +## Usage + +Date pickers are used when users need to select a date, time, or both from a structured UI. Common use cases include setting deadlines, scheduling events, filtering data ranges, or capturing form inputs with temporal values. + +## Anatomy + +The date picker component combines a text input with a popup calendar menu. + +| Element | Description | +|---|---| +| **Label** | Describes the purpose of the field | +| **Text input** | An input field where the user can manually type a date | +| **Calendar button** | Opens the calendar popup menu | +| **Year selector** | Allows switching between years | +| **Month navigation** | Previous and next month arrow buttons | +| **Calendar menu** | Shows days within the defined month and year | + +## Variants + +### Date picker + +A standalone input field that, when clicked, opens a calendar popup for date selection. Use for forms or when users need to select dates by day or year. + +### Time picker + +A standalone input field that, when clicked, opens a dropdown list of time options (e.g., hourly or half-hourly). Use when time-based information is required. + +### Date picker group + +A combined view of both the date picker and time picker components, placed side by side for selecting date and time in one interaction. Use in forms and horizontal layouts. + +## Do's and don'ts + +**Do:** +- Use labels and placeholders to indicate required input formats +- Provide keyboard and screen reader accessibility +- Use clear validation for incorrect or incomplete inputs +- Pre-populate with logical default values when appropriate (e.g., current date) +- Allow manual text input if your use case supports it + +**Don't:** +- Show both the date and time picker unless both are needed +- Use a calendar-only view for selecting far-future or past years — use a year selector +- Rely solely on placeholder text to describe the expected input +- Overload the dropdown with too many time options; limit to common intervals + +## Accessibility + +- **Label:** Communicates the purpose of the date field. If the date is for a specific purpose (e.g., start date), include that in the label. (WCAG 2.4.6) +- **Keyboard:** The date picker must be fully operable via keyboard for users who rely on assistive technology. (WCAG 2.1.1) +- **Error text:** Provide meaningful error messages that explain the required format, not just "Invalid date." (WCAG 3.3.3) diff --git a/apps/apollo-docs/app/components/text-input/page.mdx b/apps/apollo-docs/app/components/text-input/page.mdx new file mode 100644 index 000000000..2514e28aa --- /dev/null +++ b/apps/apollo-docs/app/components/text-input/page.mdx @@ -0,0 +1,80 @@ +# Text input + +Text input is an interactive field that allows users to enter any combination of letters, numbers, or symbols. + +## Usage + +Use text input when users need to enter freeform text or data. It is the right choice when: + +- **The response is unpredictable.** You can't predict a user's answer, and there may be wide variability. +- **Input simplicity matters.** Using another input type (e.g., a date picker) would make answering more difficult. +- **Users may paste content.** When users want to paste a response directly into the field. + +## Anatomy + +| Element | Description | +|---|---| +| **Label** | Text that informs the user about the content they need to enter | +| **Field** | The container in which a user enters data | +| **Value** | The content the user has typed into the field | +| **Helper text** | (Optional) Provides instructions or format guidance below the field | + +## Appearance + +### Labeling + +Input labels appear above the field. Always provide a visible label — do not use placeholder text as a substitute for a label. + +### Placeholder and helper text + +- **Placeholder text** can provide an example or hint inside the field, but should not contain essential information. It disappears when the user starts typing. +- **Helper text** appears below the field and should be used for format requirements, character counts, or critical completion instructions. Use it sparingly. + +## States + +| State | Description | +|---|---| +| **Enabled** | Default state; field is ready for input | +| **Hover** | Cursor is over the field | +| **Focus** | Field has keyboard focus | +| **Active** | User is actively typing | +| **Filled** | Field contains a value | +| **Error** | Validation has failed; error message explains the issue | +| **Disabled** | Field is not interactive; not focusable by keyboard | +| **Read-only** | Value is visible but cannot be edited; remains keyboard-focusable so users can copy the value | + +Error messages should explain why the value is invalid and guide the user toward a valid value. + +## Size + +| Size | Height | Best for | +|---|---|---| +| **Tall** | 40px | Default size; use when in doubt | +| **Small** | 32px | High-density forms or complex, long forms | + +Use a consistent field height when pairing form components on the same page. + +## Guidelines + +- Keep input labels brief; use placeholder or helper text to add explanatory context +- Do not remove field borders +- Do not use more than two sentences in helper text or error text +- Read-only fields should not be marked as required, since users cannot edit them + +## Accessibility + +- Read-only components remain navigable by keyboard so users can review and copy values; disabled components are not keyboard-accessible +- Placeholder text must be associated with an `aria-label` for assistive technologies + +## Content + +- Avoid using placeholder text for essential information — combine it with a label if used +- Do not use punctuation at the end of labels +- Omit the period from placeholder text +- Use sentence case for labels (except product names and proper nouns) + +## Related + +- [Combobox](/components/combobox) +- [Dropdown](/components/dropdown) +- [Rich-text editor](/components/rich-text-editor) diff --git a/apps/apollo-docs/app/components/toggle-switch/page.mdx b/apps/apollo-docs/app/components/toggle-switch/page.mdx new file mode 100644 index 000000000..2e9b0aa0a --- /dev/null +++ b/apps/apollo-docs/app/components/toggle-switch/page.mdx @@ -0,0 +1,51 @@ +# Toggle switch + +A toggle switch allows users to choose between two mutually exclusive options. They are commonly used to toggle a single option on or off. + +## Usage + +Toggle switches are digital on/off controls. They should provide immediate results — the change takes effect without requiring an additional save or submit action. + +Use a toggle switch when: + +- There are only two mutually exclusive options +- The change should take effect immediately, without a separate submit action + +For a set of mutually exclusive options that require an additional step to apply (e.g., pressing Save), use a [Radio button](/components/radio-button) instead. For multiple selections requiring additional steps, use a [Checkbox](/components/checkbox). + +## Anatomy + +| Element | Description | +|---|---| +| **Toggle switch** | The sliding control that indicates on or off state | +| **Label** | (Optional) Text describing what the switch controls | + +## States + +| State | Description | +|---|---| +| **On** | The feature or setting is enabled | +| **Off** | The feature or setting is disabled | +| **Disabled** | The switch is present but not interactive | +| **Focus** | The switch has keyboard focus | + +Each state is also available with an editable label (on with label, off with label, etc.). + +## Guidelines + +- Switches must always be set to either on or off — there is no indeterminate state +- Always provide a label or clear surrounding context +- Standalone switches should only be used when their connection to other components is clear +- Do not use a toggle switch when the change requires confirmation or additional steps before taking effect + +## Content + +- Be clear and precise in describing what the switch turns on or off +- Do not frame the label as a question +- The label should not change when the switch state changes +- Use sentence case with no punctuation + +## Related + +- [Checkbox](/components/checkbox) +- [Radio button](/components/radio-button)