docs(many): add required field examples and * required field note to form component docs

INSTUI-4944

Author: ToMESSKa

docs/guides/form-errors.md docs/guides/forms.mddocs/guides/form-errors.md renamed to docs/guides/forms.md

@@ -1,11 +1,35 @@
 ---
-title: Form Errors
+title: Forms
 category: Guides
 order: 4
 relevantForAI: true
 ---
 
-# Adding Error Messages to Form Components
+## Required Fields
+
+InstUI form components display an asterisk (`*`) next to labels when the `isRequired` (or `required`) prop is set. Whenever a form contains required fields, you **must include a note** explaining what the asterisk means — typically "Fields marked with an asterisk (\*) are required."
+
+> **Exception:** You can omit this note when the form's purpose is entirely self-evident — for example, a standard login screen where it is obvious that both the email and password fields are required.
+
+```ts
+---
+type: example
+---
+const RequiredFieldsExample = () => {
+  return (
+    <FormFieldGroup description="Contact Information" rowSpacing="small" layout="stacked">
+      <Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>
+      <TextInput renderLabel="Full Name" isRequired />
+      <TextInput renderLabel="Email Address" isRequired />
+      <TextInput renderLabel="Phone Number" />
+    </FormFieldGroup>
+  )
+}
+
+render(<RequiredFieldsExample />)
+```
+
+## Error Messages
 
 InstUI offers a range of form elements and all of them have a similar API to handle error/hint/success messages. These components use the `messages` prop with the following type definition:
 
@@ -86,6 +110,8 @@ const Example = () => {
       </CheckboxGroup>
       <div style={{display: 'flex', gap: '2rem', marginTop: '3rem', flexDirection: 'column'}}>
 
+        {isRequired && <Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>}
+
         <TextInput renderLabel="TextInput" messages={messages} isRequired={isRequired}/>
 
         <NumberInput renderLabel="NumberInput" messages={messages} isRequired={isRequired}/>
@@ -138,6 +164,11 @@ const Example = () => {
           invalidDateTimeMessage="Invalid date!"
           prevMonthLabel="Previous month"
           nextMonthLabel="Next month"
+          screenReaderLabels={{
+            calendarIcon: 'Open calendar',
+            prevMonthButton: 'Previous month',
+            nextMonthButton: 'Next month'
+          }}
           defaultValue="2018-01-18T13:30"
           layout="columns"
           isRequired={isRequired}
@@ -152,6 +183,11 @@ const Example = () => {
           invalidDateTimeMessage="Invalid date!"
           prevMonthLabel="Previous month"
           nextMonthLabel="Next month"
+          screenReaderLabels={{
+            calendarIcon: 'Open calendar',
+            prevMonthButton: 'Previous month',
+            nextMonthButton: 'Next month'
+          }}
           defaultValue="2018-01-18T13:30"
           layout="stacked"
           isRequired={isRequired}

packages/__docs__/buildScripts/ai-accessible-documentation/summaries-for-llms-file.json

@@ -433,7 +433,7 @@
     "summary": "Comprehensive focus management system for dialogs, modals, and popovers. Uses Dialog component with FocusRegion and FocusRegionManager to trap focus, handle escape keys, and manage screen reader accessibility."
   },
   {
-    "title": "form-errors",
+    "title": "forms",
     "summary": "InstUI form components use a `messages` prop for error/hint/success messages. Required fields now show an asterisk automatically. Examples provided for various form components like TextInput, Checkbox, and DateTimeInput."
   },
   {

packages/ui-checkbox/src/Checkbox/v1/README.md

@@ -162,6 +162,20 @@ type: example
 />
 ```
 
+### Required Fields
+
+Whenever a `Checkbox` is required, you must include a note explaining what the asterisk means — typically "Fields marked with an asterisk (\*) are required."
+
+```js
+---
+type: example
+---
+<FormFieldGroup description="Terms" rowSpacing="small" layout="stacked">
+  <Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>
+  <Checkbox label="I agree to the terms and conditions" value="terms" isRequired />
+</FormFieldGroup>
+```
+
 ### Guidelines
 
 ```js

packages/ui-checkbox/src/Checkbox/v2/README.md

@@ -166,6 +166,20 @@ type: example
 
 The underlying `<input>` has a `data-checked` attribute (`"true"`, `"false"`, or `"mixed"` when indeterminate) that can be queried from the DOM to read the current state.
 
+### Required Fields
+
+Whenever a `Checkbox` is required, you must include a note explaining what the asterisk means — typically "Fields marked with an asterisk (\*) are required."
+
+```js
+---
+type: example
+---
+<FormFieldGroup description="Terms" rowSpacing="small" layout="stacked">
+  <Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>
+  <Checkbox label="I agree to the terms and conditions" value="terms" isRequired />
+</FormFieldGroup>
+```
+
 ### Guidelines
 
 ```js

packages/ui-color-picker/src/ColorPicker/v1/README.md

@@ -201,6 +201,7 @@ type: example
 
     return (
       <View as="div">
+        {isRequired && <Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>}
         <ColorPicker
           onChange={(val) => setValue(val)}
           value={value}

packages/ui-color-picker/src/ColorPicker/v2/README.md

@@ -201,6 +201,7 @@ type: example
 
     return (
       <View as="div">
+        {isRequired && <Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>}
         <ColorPicker
           onChange={(val) => setValue(val)}
           value={value}

packages/ui-date-time-input/src/DateTimeInput/v1/README.md

@@ -82,6 +82,7 @@ type: example
           <br />
           {text}
         </div>
+        <Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>
         <div style={{ height: '14rem' }}>
           <DateTimeInput
             description={

packages/ui-form-field/src/FormFieldGroup/v1/README.md

@@ -100,6 +100,26 @@ type: example
   </FormFieldGroup>
 ```
 
+### Required Fields
+
+Whenever a `FormFieldGroup` contains required fields, you must include a note explaining what the asterisk means — typically "Fields marked with an asterisk (\*) are required."
+
+```js
+---
+type: example
+---
+<FormFieldGroup
+  description="Contact Information"
+  rowSpacing="small"
+  layout="stacked"
+>
+  <Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>
+  <TextInput renderLabel="Full Name" isRequired />
+  <TextInput renderLabel="Email Address" isRequired />
+  <TextInput renderLabel="Phone Number" />
+</FormFieldGroup>
+```
+
 ### Guidelines
 
 ```js

packages/ui-form-field/src/FormFieldGroup/v2/README.md

@@ -100,6 +100,26 @@ type: example
   </FormFieldGroup>
 ```
 
+### Required Fields
+
+Whenever a `FormFieldGroup` contains required fields, you must include a note explaining what the asterisk means — typically "Fields marked with an asterisk (\*) are required."
+
+```js
+---
+type: example
+---
+<FormFieldGroup
+  description="Contact Information"
+  rowSpacing="small"
+  layout="stacked"
+>
+  <Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>
+  <TextInput renderLabel="Full Name" isRequired />
+  <TextInput renderLabel="Email Address" isRequired />
+  <TextInput renderLabel="Phone Number" />
+</FormFieldGroup>
+```
+
 ### Guidelines
 
 ```js

packages/ui-number-input/src/NumberInput/v1/README.md

@@ -125,6 +125,7 @@ const Example = () => {
         label="Inline display"
         onChange={toggleInline}
       />
+      <Text>Fields marked with an asterisk <span aria-hidden="true">(*)</span> are required.</Text>
       <NumberInput
         renderLabel={`How old are you? (${MIN}-${MAX})`}
         display={inline ? 'inline-block' : null}