docs: date input ux description

packages/documentation/docs/controls/_date-input_code.mdx

@@ -0,0 +1,44 @@
+import Playground from '@site/src/components/PlaygroundV2';
+import Props from '@site/docs/auto-generated/ix-date-input/props.md';
+import Events from '@site/docs/auto-generated/ix-date-input/events.md';
+import Tags from '@site/docs/auto-generated/ix-date-input/tags.md';
+
+# Date input
+
+<Tags />
+
+## Examples
+
+### Basic
+
+<Playground name="date-input" height="28rem" examplesByName></Playground>
+
+### Disabled
+
+<Playground name="date-input-disabled" examplesByName></Playground>
+
+### Label
+
+<Playground name="date-input-label" height="28rem" examplesByName></Playground>
+
+### Readonly
+
+<Playground name="date-input-readonly" examplesByName></Playground>
+
+### Validation
+
+<Playground
+  name="date-input-validation"
+  height="40rem"
+  examplesByName
+></Playground>
+
+## API
+
+### Properties
+
+<Props />
+
+### Events
+
+<Events />

packages/documentation/docs/controls/_date-input_styleguide.mdx

@@ -0,0 +1,69 @@
+The date input component enables users to enter and select a date in a standardized format. We typically use this component in forms, calendars, and scheduling tools to ensure consistent and accurate date entries.
+
+![Date input overview](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3629-6200&t=ADQCetGKOEH1WG2r-4)
+1. Label
+2. Required field indicator
+3. Current value
+4. Calendar icon button
+5. Input field
+6. Date dropdown
+7. Month and year selection
+8. Weekdays
+9. Week numbers 
+10. Indicator for current day
+11. Indicator for selected day
+
+## Options
+
+- **Label**: See [form field](./forms/forms-field.md)
+- **Value**: See [form field](./forms/forms-field.md)
+- **Required**: See [form field](./forms/forms-field.md)
+- **Helper text**: See [form field](./forms/forms-field.md)
+- **Feedback text**: See [form field](./forms/forms-field.md)
+- **Show text as tooltip**: See [form field](./forms/forms-field.md)
+- **Placeholder**: See [form field](./forms/forms-field.md). We typically use a placeholder to show an example date format to assist users when the field is empty.
+- **Error message**: Feedback text when date is not parsable. We typically use this to inform users that the entered date format is incorrect and guide them to enter a valid date.
+- **Format**: Specify the date format, default ‘yyyy/LL/dd’. We typically use this to ensure that dates are entered in a consistent and recognizable format, leveraging the Luxon JavaScript library for parsing and formatting.
+
+## Behavior in context
+
+- **Interaction**:
+  - Click or focus opens date picker.
+  - Use mouse or keyboard arrows to navigate to desired date.
+  - Selecting a date in date picker with mouse click or enter closes the date picker.
+  - Typing a date into input field with valid format closes the date picker.
+  - Escape key closes the date picker.
+- **Validation**:
+  - Use feedback text for validation types valid, info, warning and invalid.
+  - Invalid feedback automatically provided if entered date in not parsable.
+  - Refer to the [validation](./forms/forms-validation.md) chapter for detailed guidelines.
+- **Overflow**: The input field should be wide enough to display the full date without truncation.
+- **Alignment**: Date inputs are always aligned to the left.
+
+## States
+
+Date input has five states: Default, hover, disabled, read-only and focused.
+
+![Date input states](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Pattern-Illustrations?node-id=3989-2545&t=ADQCetGKOEH1WG2r-4)
+
+
+## Dos and Don’ts
+
+- Do use consistent date formats: Ensure the date format is uniform throughout the application to avoid confusion
+- Do use separate inputs for date ranges: Provide distinct input fields for the start and end dates to make it easier for users to enter and understand date ranges
+- Do provide clear instructions: Clearly indicate the required date format to users. For example, “Please enter the date in yyyy-MM-dd format”
+- Do handle time zones: If time zones are relevant, ensure that the date input accounts for them and is clearly labeled
+- Do consider localization: Adapt date formats to the local conventions of your users if your application is used internationally
+- Don't use ambiguous formats: Do not use date formats that can be easily misinterpreted, such as 09/08/2006 without clear context
+- Don't allow free text without validation: Avoid allowing users to enter dates as free text without any validation or formatting guidance
+
+## Related patterns
+
+- [Date dropdown](./date-dropdown.md)
+- [Date picker](./date-picker.md)
+- [Date time picker](./date-picker.md)
+- [Forms field](./forms/forms-field.md)
+- [Validation](./forms/forms-validation.md)
+- [Dropdown](./dropdown.md)
+- [Input](input.mdx)
+- [Select](select.mdx)

packages/documentation/docs/controls/date-input.mdx

@@ -1,44 +1,8 @@
-import Playground from '@site/src/components/PlaygroundV2';
-import Props from '@site/docs/auto-generated/ix-date-input/props.md';
-import Events from '@site/docs/auto-generated/ix-date-input/events.md';
-import Tags from '@site/docs/auto-generated/ix-date-input/tags.md';
+import DocsTabs from '@site/src/components/DocsTabs';
 
-# Date input
-
-<Tags />
-
-## Examples
-
-### Basic
-
-<Playground name="date-input" height="28rem" examplesByName></Playground>
-
-### Disabled
-
-<Playground name="date-input-disabled" examplesByName></Playground>
-
-### Label
-
-<Playground name="date-input-label" height="28rem" examplesByName></Playground>
+import DocsUx from './\_date-input_styleguide.mdx'
+import DocsCode from './\_date-input_code.mdx'
 
-### Readonly
-
-<Playground name="date-input-readonly" examplesByName></Playground>
-
-### Validation
-
-<Playground
-  name="date-input-validation"
-  height="40rem"
-  examplesByName
-></Playground>
-
-## API
-
-### Properties
-
-<Props />
-
-### Events
+# Date input
 
-<Events />
+<DocsTabs styleguide={DocsUx} code={DocsCode} />