docs(UX-1487): Update documentation for consistency (#380)

thelukewalton · web-flow · commit 422cb9a7fc9e · 2025-08-18T10:48:35.000+01:00
diff --git a/packages/zeta_flutter/lib/src/components/avatar_rail/avatar_rail.dart b/packages/zeta_flutter/lib/src/components/avatar_rail/avatar_rail.dart
@@ -3,7 +3,7 @@ import 'package:flutter/material.dart';
 
 import '../../../zeta_flutter.dart';
 
-/// A stateless widget that represents an avatar rail in the Zeta application.
+/// A rail containing 0 or more Avatars that can be scrolled horizontally.
 ///
 /// The `ZetaAvatarRail` widget is used to display a horizontal rail of avatars,
 /// typically used for navigation or selection purposes within the application.
diff --git a/packages/zeta_flutter/lib/src/components/button_group/button_group.dart b/packages/zeta_flutter/lib/src/components/button_group/button_group.dart
@@ -3,7 +3,7 @@ import 'package:flutter/material.dart';
 
 import '../../../zeta_flutter.dart';
 
-/// Zeta Button Group
+/// Button groups are used to group related buttons together. They can be used to create a toolbar or a set of related actions.
 ///
 /// Figma: https://www.figma.com/design/JesXQFLaPJLc1BdBM4sisI/%F0%9F%A6%93-ZDS---Components?node-id=229-45&node-type=canvas&m=dev
 ///
diff --git a/packages/zeta_flutter/lib/src/components/buttons/button.dart b/packages/zeta_flutter/lib/src/components/buttons/button.dart
@@ -5,7 +5,7 @@ import '../../../zeta_flutter.dart';
 
 import 'button_style.dart';
 
-/// Zeta Button
+/// Buttons are used to trigger actions.
 ///
 /// Figma: https://www.figma.com/file/JesXQFLaPJLc1BdBM4sisI/%F0%9F%A6%93-ZDS---Components?node-id=23126-110945
 ///
diff --git a/packages/zeta_flutter/lib/src/components/buttons/icon_button.dart b/packages/zeta_flutter/lib/src/components/buttons/icon_button.dart
@@ -5,7 +5,7 @@ import '../../../zeta_flutter.dart';
 
 import 'button_style.dart';
 
-/// Component [ZetaIconButton]
+/// Icon buttons are used to trigger actions with an icon.
 ///
 /// Figma: https://www.figma.com/file/JesXQFLaPJLc1BdBM4sisI/%F0%9F%A6%93-ZDS---Components?node-id=23126-110314
 ///
diff --git a/packages/zeta_flutter/lib/src/components/buttons/tile_button.dart b/packages/zeta_flutter/lib/src/components/buttons/tile_button.dart
@@ -3,7 +3,7 @@ import 'package:flutter/material.dart';
 import '../../../zeta_flutter.dart';
 import 'button_style.dart';
 
-/// Zeta Button
+/// A large, tappable button with an icon stacked above a label. Ideal for grid layouts, dashboards, or mobile interfaces where quick, visually distinct actions are needed.
 ///
 /// Figma: https://www.figma.com/design/JesXQFLaPJLc1BdBM4sisI/%F0%9F%A6%93-ZDS---Components?node-id=37677-15824&t=BkdCAAhFjNXxpwfK-4
 ///
diff --git a/packages/zeta_flutter/lib/src/components/chat_item/chat_item.dart b/packages/zeta_flutter/lib/src/components/chat_item/chat_item.dart
@@ -4,7 +4,7 @@ import 'package:flutter_slidable/flutter_slidable.dart';
 import 'package:intl/intl.dart';
 import '../../../zeta_flutter.dart';
 
-/// Chat item widget that can be dragged to reveal contextual actions.
+/// The chat list items and chat lists are used in communication feeds and contact lists.
 ///
 /// Figma: https://www.figma.com/design/JesXQFLaPJLc1BdBM4sisI/%F0%9F%A6%93-ZDS---Components?node-id=24828-46282&node-type=canvas&m=dev
 ///
diff --git a/packages/zeta_flutter/lib/src/components/chips/assist_chip.dart b/packages/zeta_flutter/lib/src/components/chips/assist_chip.dart
@@ -2,6 +2,8 @@ import 'package:flutter/material.dart';
 
 import '../../../zeta_flutter.dart';
 
+/// Chips that are clickable, selectable and draggable.
+///
 /// Leading widget should typically be an icon.
 ///
 /// These chips use [Draggable] and can be dragged around the screen and placed in new locations using [DragTarget].
diff --git a/packages/zeta_flutter/lib/src/components/chips/filter_chip.dart b/packages/zeta_flutter/lib/src/components/chips/filter_chip.dart
@@ -2,6 +2,8 @@ import 'package:flutter/material.dart';
 
 import '../../../zeta_flutter.dart';
 
+/// Chips that are used to filter content, that are clickable, selectable and draggable. They have a default and active state.
+///
 /// Filter chips have 2 togglable states, representing selected and not selected.
 ///
 /// The chips are commonly used within a [ZetaFilterSelection].
diff --git a/packages/zeta_flutter/lib/src/components/chips/input_chip.dart b/packages/zeta_flutter/lib/src/components/chips/input_chip.dart
@@ -1,6 +1,6 @@
 import '../../../zeta_flutter.dart';
 
-/// Zeta Input Chip typically is used to associate some content or action with a user.
+/// A chip used to show input data, typically used to associate some content or action with a user.
 ///
 /// Leading widget should typically be a [ZetaAvatar].
 ///
diff --git a/packages/zeta_flutter/lib/src/components/chips/status_chip.dart b/packages/zeta_flutter/lib/src/components/chips/status_chip.dart
@@ -3,7 +3,8 @@ import 'package:flutter/material.dart';
 
 import '../../../zeta_flutter.dart';
 
-/// The [ZetaStatusChip] is a chip that displays a status/label.
+/// A chip that looks like a label.
+///
 /// It can be dragged around the screen and placed in new locations using [DragTarget].
 ///
 /// Figma: https://www.figma.com/file/JesXQFLaPJLc1BdBM4sisI/%F0%9F%A6%93-ZDS---Components?node-id=21265-2159
diff --git a/packages/zeta_flutter/lib/src/components/comms_button/comms_button.dart b/packages/zeta_flutter/lib/src/components/comms_button/comms_button.dart
@@ -21,8 +21,7 @@ enum ZetaCommsButtonType {
   warning,
 }
 
-/// Comms button component.
-/// This component is used to display a button for communication action. Answer, reject, mute, hold, speaker, etc.
+/// Round buttons used for communication actions like call, video, mute, etc.
 ///
 /// Use the constructors to create preconfigured comms buttons.
 ///
diff --git a/packages/zeta_flutter/lib/src/components/date_input/date_input.dart b/packages/zeta_flutter/lib/src/components/date_input/date_input.dart
@@ -9,7 +9,7 @@ import '../../../zeta_flutter.dart';
 import '../buttons/input_icon_button.dart';
 import '../text_input/internal_text_input.dart';
 
-/// A form field used to input dates.
+/// A text input field for entering dates.
 ///
 /// Can be used and validated the same way as a [TextFormField].
 ///
diff --git a/packages/zeta_flutter/lib/src/components/dialog/dialog.dart b/packages/zeta_flutter/lib/src/components/dialog/dialog.dart
@@ -51,7 +51,7 @@ Future<bool?> showZetaDialog(
       ),
     );
 
-/// The Zeta Dialog component.
+/// A popup dialog used to convey a message to the user.
 ///
 /// Figma: https://www.figma.com/design/JesXQFLaPJLc1BdBM4sisI/%F0%9F%A6%93-ZDS---Components?node-id=23954-93337&node-type=frame&m=dev
 ///
diff --git a/packages/zeta_flutter/lib/src/components/dropdown/dropdown.dart b/packages/zeta_flutter/lib/src/components/dropdown/dropdown.dart
@@ -53,7 +53,7 @@ class ZetaDropdownItem<T> {
   final Widget? icon;
 }
 
-/// Class for [ZetaDropdown]
+/// Dropdown menus allow users to select an option from a list that appears when the menu is clicked or tapped.
 ///
 /// Figma: https://www.figma.com/file/JesXQFLaPJLc1BdBM4sisI/%F0%9F%A6%93-ZDS---Components?node-id=22391-10146
 ///
diff --git a/packages/zeta_flutter/lib/src/components/fabs/fab.dart b/packages/zeta_flutter/lib/src/components/fabs/fab.dart
@@ -91,7 +91,7 @@ enum ZetaFabSize {
       }[this]!;
 }
 
-/// Zeta Floating Action Button Component.
+/// Floating Action Buttons are used to trigger the primary action on a screen. They are circular buttons that float above the content.
 ///
 /// Figma: https://www.figma.com/file/JesXQFLaPJLc1BdBM4sisI/%F0%9F%A6%93-ZDS---Components?node-id=21816-4283&m=dev
 ///
diff --git a/packages/zeta_flutter/lib/src/components/filter_selection/filter_selection.dart b/packages/zeta_flutter/lib/src/components/filter_selection/filter_selection.dart
@@ -3,7 +3,7 @@ import 'package:flutter/material.dart';
 
 import '../../../zeta_flutter.dart';
 
-/// Component [ZetaFilterSelection]
+/// A bar containing Filter Chips.
 ///
 /// Figma: https://www.figma.com/design/JesXQFLaPJLc1BdBM4sisI/%F0%9F%A6%93-ZDS---Components?node-id=24607-737&node-type=canvas&m=dev
 ///
diff --git a/packages/zeta_flutter/lib/src/components/list_item/list_item.dart b/packages/zeta_flutter/lib/src/components/list_item/list_item.dart
@@ -50,7 +50,7 @@ class ZetaList extends ZetaStatelessWidget {
   }
 }
 
-/// A single row that typically contains some text as well as a leading or trailing widgets.
+/// An item in a list comprised of a single row, typically containing some text as well as leading or trailing widgets.
 ///
 /// To create list items with a [ZetaSwitch], [ZetaCheckbox], or [ZetaRadio], use the [ZetaListItem.toggle], [ZetaListItem.checkbox] or the [ZetaListItem.radio] named constructors respectively.
 ///
diff --git a/packages/zeta_flutter/lib/src/components/pagination/pagination.dart b/packages/zeta_flutter/lib/src/components/pagination/pagination.dart
@@ -14,7 +14,7 @@ enum ZetaPaginationType {
   dropdown,
 }
 
-/// Pagination is used to switch between pages.
+/// Buttons or a dropdown for navigating between pages.
 ///
 /// Figma: https://www.figma.com/design/JesXQFLaPJLc1BdBM4sisI/%F0%9F%A6%93-ZDS---Components?node-id=229-24&node-type=canvas&m=dev
 ///
diff --git a/packages/zeta_flutter/lib/src/components/password/password_input.dart b/packages/zeta_flutter/lib/src/components/password/password_input.dart
@@ -5,7 +5,7 @@ import '../../../zeta_flutter.dart';
 
 import '../text_input/internal_text_input.dart';
 
-/// Zeta Password Input
+/// A text input field for entering passwords.
 ///
 /// Figma: https://www.figma.com/design/JesXQFLaPJLc1BdBM4sisI/%F0%9F%A6%93-ZDS---Components?node-id=948-13002&node-type=canvas&m=dev
 ///
diff --git a/packages/zeta_flutter/lib/src/components/phone_input/phone_input.dart b/packages/zeta_flutter/lib/src/components/phone_input/phone_input.dart
@@ -7,7 +7,7 @@ import '../../../zeta_flutter.dart';
 
 import '../text_input/internal_text_input.dart';
 
-/// ZetaPhoneInput allows entering phone numbers.
+/// A text input field for entering phone numbers.
 ///
 /// Figma: https://www.figma.com/design/JesXQFLaPJLc1BdBM4sisI/%F0%9F%A6%93-ZDS---Components?node-id=916-10934&node-type=canvas&m=dev
 ///
diff --git a/packages/zeta_flutter/lib/src/components/range_selector/range_selector.dart b/packages/zeta_flutter/lib/src/components/range_selector/range_selector.dart
@@ -4,6 +4,8 @@ import 'package:flutter/services.dart';
 
 import '../../../zeta_flutter.dart';
 
+/// Used for selecting values in a numerical range.
+///
 /// The [ZetaRangeSelector] is a customizable range selector widget that
 /// allows users to select a range of values within a specified minimum
 /// and maximum range. It provides a visual representation of the selected
diff --git a/packages/zeta_flutter/lib/src/components/screen_header_bar/screen_header_bar.dart b/packages/zeta_flutter/lib/src/components/screen_header_bar/screen_header_bar.dart
@@ -4,7 +4,7 @@ import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 import '../../../zeta_flutter.dart';
 
-/// A screen header bar that contains a back button, title and an optional action button.
+/// A header bar for screens, typically containing the title and actions.
 ///
 /// Figma: https://www.figma.com/design/JesXQFLaPJLc1BdBM4sisI/%F0%9F%A6%93-ZDS---Components?node-id=24601-6781&node-type=canvas&m=dev
 ///
diff --git a/packages/zeta_flutter/lib/src/components/search_bar/search_bar.dart b/packages/zeta_flutter/lib/src/components/search_bar/search_bar.dart
@@ -5,7 +5,7 @@ import '../../../zeta_flutter.dart';
 import '../buttons/input_icon_button.dart';
 import '../text_input/internal_text_input.dart';
 
-/// ZetaSearchBar provides input field for searching.
+/// A text input field for entering search queries.
 ///
 /// Figma: https://www.figma.com/design/JesXQFLaPJLc1BdBM4sisI/%F0%9F%A6%93-ZDS---Components?node-id=875-17463&node-type=canvas&m=dev
 ///
diff --git a/packages/zeta_flutter/lib/src/components/segmented_control/segmented_control.dart b/packages/zeta_flutter/lib/src/components/segmented_control/segmented_control.dart
@@ -5,9 +5,7 @@ import 'package:flutter/physics.dart';
 import 'package:flutter/rendering.dart';
 import '../../../zeta_flutter.dart';
 
-/// A segmented control is a linear set of two or more segments, each of which
-/// functions as a mutually exclusive button. Like buttons, segments can contain
-/// text or images. Segmented controls are often used to display different views.
+/// A segmented control is a linear set of two or more segments, each of which functions as a mutually exclusive button. Like buttons, segments can contain text or images. Segmented controls are often used to display different views.
 ///
 /// Figma: https://www.figma.com/design/JesXQFLaPJLc1BdBM4sisI/%F0%9F%A6%93-ZDS---Components?node-id=1046-20148&node-type=canvas&m=dev
 ///
diff --git a/packages/zeta_flutter/lib/src/components/select_input/select_input.dart b/packages/zeta_flutter/lib/src/components/select_input/select_input.dart
@@ -8,7 +8,7 @@ import '../buttons/input_icon_button.dart';
 import '../dropdown/dropdown_controller.dart';
 import '../text_input/internal_text_input.dart';
 
-/// Class for [ZetaSelectInput].
+/// A text input field for selecting from a list of options.
 ///
 /// Figma: https://www.figma.com/design/JesXQFLaPJLc1BdBM4sisI/%F0%9F%A6%93-ZDS---Components?node-id=229-39&node-type=canvas&m=dev
 ///
diff --git a/packages/zeta_flutter/lib/src/components/slider/slider.dart b/packages/zeta_flutter/lib/src/components/slider/slider.dart
@@ -5,7 +5,7 @@ import '../../../zeta_flutter.dart';
 
 // TODO(UX-1355): Create slider input field.
 
-/// Slider component with customized styling.
+/// Sliders allow users to make selections from a range of values.
 ///
 /// Figma: https://www.figma.com/design/JesXQFLaPJLc1BdBM4sisI/%F0%9F%A6%93-ZDS---Components?node-id=875-11860&node-type=canvas&m=dev
 ///
diff --git a/packages/zeta_flutter/lib/src/components/snack_bar/snack_bar.dart b/packages/zeta_flutter/lib/src/components/snack_bar/snack_bar.dart
@@ -29,8 +29,9 @@ enum ZetaSnackBarType {
   view,
 }
 
-/// A lightweight message with an optional action which briefly displays at the
-/// bottom of the screen.
+/// Snackbars provide brief messages about app processes at the bottom of the screen.
+///
+/// Contextual snackbars provide brief messages in relation to an action that has been taken by the user.
 ///
 /// Different styles can be applied to [ZetaSnackBar] with [ZetaSnackBarType].
 ///
diff --git a/packages/zeta_flutter/lib/src/components/stepper/stepper.dart b/packages/zeta_flutter/lib/src/components/stepper/stepper.dart
@@ -2,8 +2,9 @@ import 'package:flutter/foundation.dart';
 import 'package:flutter/material.dart';
 import '../../../zeta_flutter.dart';
 
-/// Zeta stepper widget that displays progress through a sequence of
-/// steps. Steppers are particularly useful in the case of forms where one step
+/// Steppers convey progress through numbered steps.
+///
+/// Steppers are particularly useful in the case of forms where one step
 /// requires the completion of another one, or where multiple steps need to be
 /// completed in order to submit the whole form.
 ///
diff --git a/packages/zeta_flutter/lib/src/components/stepper_input/stepper_input.dart b/packages/zeta_flutter/lib/src/components/stepper_input/stepper_input.dart
@@ -13,9 +13,7 @@ enum ZetaStepperInputSize {
   large,
 }
 
-/// A stepper input, also called numeric stepper, is a common UI element that
-/// allows users to input a number or value simply by clicking the plus and
-/// minus buttons.
+/// A stepper input, also called numeric stepper, is a common UI element that allows users to input a number or value simply by clicking the plus and minus buttons.
 ///
 /// Figma: https://www.figma.com/design/JesXQFLaPJLc1BdBM4sisI/%F0%9F%A6%93-ZDS---Components?node-id=229-47&node-type=canvas&m=dev
 ///
diff --git a/packages/zeta_flutter/lib/src/components/switch/zeta_switch.dart b/packages/zeta_flutter/lib/src/components/switch/zeta_switch.dart
@@ -21,9 +21,7 @@ enum ZetaSwitchType {
   ios,
 }
 
-/// Zeta Switch.
-///
-/// Switch can turn an option on or off.
+/// Switches toggle the state of a single item ON or OFF.
 ///
 /// Switch has styles for Android, iOS and Web.
 ///
diff --git a/packages/zeta_flutter/lib/src/components/system_banner/system_banner.dart b/packages/zeta_flutter/lib/src/components/system_banner/system_banner.dart
@@ -17,8 +17,7 @@ enum ZetaSystemBannerStatus {
   negative,
 }
 
-/// A banner displays an important, succinct message, and provides action for users to address.
-/// It draws the attention to the message by displaying it at the top in various colors.
+/// A banner displays an important, succinct message, and provides action for users to address. It draws the attention to the message by displaying it at the top in various colors.
 ///
 /// To display on screen use `ScaffoldMessenger.of(context).showMaterialBanner(ZetaSystemBanner())`. This will display the banner at the top of the page, below the AppBar.
 ///
diff --git a/packages/zeta_flutter/lib/src/components/tabs/tab.dart b/packages/zeta_flutter/lib/src/components/tabs/tab.dart
@@ -1,6 +1,8 @@
 import 'package:flutter/material.dart';
 import '../../../zeta_flutter.dart';
 
+/// Tabs are used to show different views or sections of content within the same context.
+///
 /// Defines how the bounds of the selected tab indicator are computed.
 /// Intended to be used with [ZetaTabBar].
 ///
diff --git a/packages/zeta_flutter/lib/src/components/tabs/tab_bar.dart b/packages/zeta_flutter/lib/src/components/tabs/tab_bar.dart
@@ -1,7 +1,7 @@
 import 'package:flutter/material.dart';
 import '../../../zeta_flutter.dart';
 
-/// A Zeta Design primary tab bar.
+/// Tabs are used to show different views or sections of content within the same context.
 ///
 /// Figma: https://www.figma.com/design/JesXQFLaPJLc1BdBM4sisI/%F0%9F%A6%93-ZDS---Components?node-id=229-18&node-type=canvas&m=dev
 ///
diff --git a/packages/zeta_flutter/lib/src/components/text_input/text_input.dart b/packages/zeta_flutter/lib/src/components/text_input/text_input.dart
@@ -9,7 +9,7 @@ import 'internal_text_input.dart';
 // TODO(UX-895): Text Input connected left
 // TODO(UX-1360): Text Input disabled bug
 
-/// Text inputs allow the user to enter text.
+/// A text input field for entering text.
 ///
 /// To show error messages on the text input, use the [validator]. The string returned from this function will be displayed as the error message.
 /// Error messages can also be managed outside the text input by setting [errorText].
diff --git a/packages/zeta_flutter/lib/src/components/time_input/time_input.dart b/packages/zeta_flutter/lib/src/components/time_input/time_input.dart
@@ -11,7 +11,7 @@ import '../text_input/internal_text_input.dart';
 const _maxHrValue = 23;
 const _max12HrValue = 12;
 
-/// A form field used to input time.
+/// A text input field for entering times.
 ///
 /// Can be used and validated the same way as a [TextFormField].
 ///
