docs(date-picker): improve docs

docs/src/pages/components/DatePicker.svx

@@ -7,11 +7,7 @@ components: ["DatePicker", "DatePickerInput", "DatePickerSkeleton"]
   import Preview from "../../components/Preview.svelte";
 </script>
 
-Carbon uses the zero dependency [flatpickr](https://github.com/flatpickr/flatpickr) library for its underlying calendar implementation.
-
-Set `datePickerType` to `"single"` or `"range"` for the calendar functionality.
-
-Specify [flatpickr options](https://flatpickr.js.org/options/) through the `flatpickrProps` prop.
+`DatePicker` lets users select a date or date range using a calendar interface. It uses the [flatpickr](https://github.com/flatpickr/flatpickr) library for its calendar implementation.
 
 <InlineNotification svx-ignore lowContrast title="Note:" kind="info" hideCloseButton>
   <div class="body-short-01">
@@ -21,25 +17,27 @@ Specify [flatpickr options](https://flatpickr.js.org/options/) through the `flat
 
 ## Single
 
-By default, the `flatpickr` option `static` is set to `true` so that the calendar is positioned inside the wrapper and next to the input element. This is required for the calendar position to work inside a [Modal](/components/Modal).
-
-Set `flatpickrProps.static` to `false` to opt out of this behavior.
+Set `datePickerType` to `"single"` for single date selection.
 
 <FileSource src="/framed/DatePicker/DatePickerSingle" />
 
 ## Range
 
-Set `datePickerType` to `"range"` for the range variant.
+Set `datePickerType` to `"range"` to enable date range selection.
 
 <FileSource src="/framed/DatePicker/DatePickerRange" />
 
 ## DatePicker in a modal
 
+The calendar is positioned inside the wrapper by default (`flatpickrProps.static: true`). This ensures proper positioning within a [Modal](/components/Modal).
+
+Set `flatpickrProps.static` to `false` to position the calendar outside the wrapper.
+
 <FileSource src="/framed/DatePicker/DatePickerModal" />
 
 ## Simple
 
-By default, the "simple" date picker does not have a dropdown calendar.
+Create a simple date picker without a dropdown calendar.
 
 <DatePicker>
   <DatePickerInput labelText="Date of birth" placeholder="mm/dd/yyyy" />
@@ -47,52 +45,70 @@ By default, the "simple" date picker does not have a dropdown calendar.
 
 ## With helper text
 
+Add helper text to provide additional context or formatting instructions.
+
 <DatePicker>
   <DatePickerInput labelText="Date of birth" helperText="Example: 01/12/1990" placeholder="mm/dd/yyyy" />
 </DatePicker>
 
 ## Hidden label
 
+Hide the label while maintaining accessibility.
+
 <DatePicker>
   <DatePickerInput hideLabel labelText="Date of birth" placeholder="mm/dd/yyyy" />
 </DatePicker>
 
 ## Light variant
 
+Use the light variant for light backgrounds.
+
 <DatePicker light>
   <DatePickerInput labelText="Date of birth" placeholder="mm/dd/yyyy" />
 </DatePicker>
 
 ## Extra-large size
 
+Use the extra-large size for more prominent date pickers.
+
 <DatePicker>
   <DatePickerInput size="xl" labelText="Date of birth" placeholder="mm/dd/yyyy" />
 </DatePicker>
 
 ## Small size
 
+Use the small size for compact date pickers.
+
 <DatePicker>
   <DatePickerInput size="sm" labelText="Date of birth" placeholder="mm/dd/yyyy" />
 </DatePicker>
 
 ## Invalid state
 
+Show an invalid state when the input value is not valid.
+
 <DatePicker>
   <DatePickerInput invalid invalidText="Invalid date" labelText="Date of birth" placeholder="mm/dd/yyyy" />
 </DatePicker>
 
 ## Warning state
 
+Show a warning state to indicate potential issues with the input.
+
 <DatePicker>
   <DatePickerInput warn warnText="This info will not be stored" labelText="Date of birth" placeholder="mm/dd/yyyy" />
 </DatePicker>
 
 ## Disabled state
 
+Disable the date picker to prevent user interaction.
+
 <DatePicker>
   <DatePickerInput disabled labelText="Date of birth" placeholder="mm/dd/yyyy" />
 </DatePicker>
 
 ## Skeleton
 
+Show a loading state with the skeleton component.
+
 <DatePickerSkeleton />