feat(docs): add core input component pages (batch A)

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',
 };

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)

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)

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)

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)

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)

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)