docs(getting-started): provide optional global styles

.env.production

@@ -1,4 +1,4 @@
-IX_REPO_BRANCH='@siemens/ix@5.1.0'
+IX_REPO_BRANCH='main'
 IX_REPO_TYPE='branch' # For pull requests use "pull request" as value
 IX_REPO_PR=''
 

docs/components/ai-message/code.mdx

@@ -0,0 +1,15 @@
+---
+doc-type: 'tab-item'
+description: 'Code examples and API documentation for AI message.'
+---
+
+import ChatAiMessagePlayground from '@site/docs/autogenerated/playground/chat-ai-message.mdx';
+import PropsApi from '@site/docs/autogenerated/api/ix-chat-ai-message/api.mdx';
+
+# AI message - Code
+
+## Basic
+
+<ChatAiMessagePlayground height="24rem" />
+
+<PropsApi />

docs/components/ai-message/guide.md

@@ -0,0 +1,36 @@
+---
+doc-type: 'tab-item'
+description: 'Usage guide for AI message.'
+---
+
+# AI message - Usage
+
+AI messages display a single assistant response inside a conversational thread. We recommend using them for answers users need to read, review and act on.
+
+![AI message anatomy](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7959-520&t=8Rj3ErabF16Vm3lH-4)
+
+1. Content
+2. Actions
+
+## Options
+
+- **Content:** Keep the response easy to scan by structuring it (see [content guidelines](../../guidelines/conversational-design/overview.md)).
+- **Actions:** Add only message-level actions that users expect after reading, e.g. copy, rate response quality or regenerate. We recommend using subtle tertiary [icon buttons](../icon-button) so actions stay available without competing with the answer.
+- **Sources:** If the response is grounded in files, web results or internal data, expose that provenance close to the message content. Only display if there are dedicated sources to show.
+
+## Behavior in context
+
+- **Responsiveness:** AI messages use from 45 to 80% of the chat's container width, depending on the viewport width.
+
+## Dos and Don’ts
+
+- Do show clear [loading indicators](../spinner/) while the assistant is generating responses (see [wording guidelines](../../guidelines/conversational-design/essentials/wording-terms.mdx#response-progress-indicator))
+- Do use the same actions for each AI message for consistency, but not more than 4 to avoid overloading users, e.g. copy, feedback, regenerate
+- Do add thumbs up or down actions only if you are aligned with data protection guidelines
+
+## Related
+
+- [Chat](../chat)
+- [User message](../user-message)
+- [Chat input](../chat-input)
+- [Conversational design guidelines](../../guidelines/conversational-design/overview.md)

docs/components/ai-message/index.mdx

@@ -0,0 +1,6 @@
+---
+doc-type: "tabs"
+description: 'AI messages display a single response generated by AI in a conversational chat experience.'
+title: 'AI message'
+deprecated:
+---

docs/components/chat-attachment/code.mdx

@@ -0,0 +1,15 @@
+---
+doc-type: 'tab-item'
+description: 'Code examples and API documentation for chat attachment.'
+---
+
+import ChatAttachmentPlayground from '@site/docs/autogenerated/playground/chat-user-message.mdx';
+import PropsApi from '@site/docs/autogenerated/api/ix-chat-attachment/api.mdx';
+
+# Chat attachment - Code
+
+## Basic
+
+<ChatAttachmentPlayground height="24rem" />
+
+<PropsApi />

docs/components/chat-attachment/guide.md

@@ -0,0 +1,46 @@
+---
+doc-type: 'tab-item'
+description: 'Usage guide for chat attachment.'
+---
+
+# Chat attachment - Usage
+
+Chat attachments display files that users have uploaded to a chat prompt. It is typically displayed when users are writing in the chat input [chat inputs](../chat-input) and in all sent [user messages](../user-message/).
+
+![Chat attachment anatomy](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7970-230&t=HrpSIFfB7yjzt741-4)
+
+1. File icon
+2. File name
+3. Remove button
+
+## Options
+
+- **File icon:** Show a recognizable file-type [icon](../../icons/icon-library) so users can identify attachments quickly, e.g. `pdf-document`.
+- **File name:** Show the file name including the file extension.
+- **Remove button:** Show remove buttons in a [chat input](../chat-input/) and hide it once an attachment is part of a submitted [message](../user-message/).
+- **Preview supported:** Use only for supported files to show e.g. thumbnails.
+
+## Behavior in context
+
+- **Chat input context:** If attachments exceed the chat input's width, they overflow into a scrollable horizontal list.
+- **User message context:** If attachments exceed the user message container's width, a more button is visible.
+- **Text overflow:** If an attachment exceeds `20rem`, the file name is truncated at the end while preserving the file extension. A tooltip is shown on hover to display the full file name.
+
+## States
+
+Chat attachments have six states: default, hover, active, loading, focused and error.
+
+Chat attachments follow the [chip](../chip) interaction model, including hover, active and focused behavior. In an error state, attachments stay visible and show clear feedback so users can retry or remove files.
+
+## Dos and Don’ts
+
+- Do keep attachments visible in user messages so attachments stay traceable within context
+- Don’t hide the remove action while users are still composing a prompt in the [chat input](../chat-input/)
+- Don’t detach attachments from their related [user message](../user-message/) after sending
+
+## Related
+
+- [Chat](../chat)
+- [Chat input](../chat-input)
+- [Chip](../chip)
+- [User message](../user-message)

docs/components/chat-attachment/index.mdx

@@ -0,0 +1,6 @@
+---
+doc-type: "tabs"
+description: 'Chat attachments are used to display a single attachment in chat experiences.'
+title: 'Chat attachment'
+deprecated:
+---

docs/components/chat-input/code.mdx

@@ -0,0 +1,15 @@
+---
+doc-type: 'tab-item'
+description: 'Code examples and API documentation for chat input.'
+---
+
+import ChatInputPlayground from '@site/docs/autogenerated/playground/chat-input.mdx';
+import PropsApi from '@site/docs/autogenerated/api/ix-chat-input/api.mdx';
+
+# Chat input - Code
+
+## Basic
+
+<ChatInputPlayground height="20rem" />
+
+<PropsApi />

docs/components/chat-input/guide.md

@@ -0,0 +1,59 @@
+---
+doc-type: 'tab-item'
+description: 'Usage guide for chat input.'
+---
+
+# Chat input - Usage
+
+In chat inputs users write and send messages . We recommend using them for quick, iterative exchanges, not for multi-step data entries.
+
+![Anatomy component](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7940-7427&t=mrtbkWj76QJhvNLI-11)
+
+1. Follow-up prompts
+2. Attachments
+3. Textarea
+4. Start slot for secondary actions
+5. Disclaimer
+6. End slot for alternative input methods
+7. Send button
+
+## Options
+
+- **Placeholder:** Use clear, contextual prompts, e.g. “Enter a command, question or topic…” (see [writing guidelines](../../guidelines/conversational-design/essentials/wording-terms)).
+- **Follow-up slot:** Optionally include a slot for follow-up questions. We typically use tertiary outline [buttons](../button) or [icon buttons](../icon-button) for that purpose.
+- **Attachment slot:** Optionally include a slot for [attachments](../chat-attachment/).
+- **Start slot:** Add secondary actions. We recommend using tertiary outline [icon buttons](../icon-button) and trying to stick to one action. If you have more than one action, use [dropdown buttons](../dropdown-button/).
+- **End slot:** Use this slot to add alternative input methods, e.g. voice input.
+- **Disclaimer:** In AI contexts, we recommend including a visible disclaimer under the input instead of under each [AI message](../ai-message/). For Siemens AG products, find legal disclaimers [here](https://code.siemens.com/siemens-ix/ix-brand-theme/-/blob/main/apps/documentation/src/pages/legal-disclaimers-copilots.md).
+- **Character limit:** Set soft and hard character limits that either warn users or prevent further input.
+
+## Behavior in context
+
+- **Interaction:** Keep the input compact at start and let it grow to multiline while users type
+- **Overflow:**
+  - On the follow-up actions: If the actions exceed max width, they break into multiple lines
+  - On the input: If the input reaches max height, the input shows a vertical scroll
+  - On the attachments: If the attachments reach max width, they show a horizontal scroll
+
+![Overflow behavior](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7940-7020&t=mrtbkWj76QJhvNLI-11)
+
+## States
+
+Chat inputs have four states: default, hover, focused and processing.
+
+![States](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7940-2809&t=mrtbkWj76QJhvNLI-4)
+
+## Dos and Don’ts
+
+- Do keep action labels verb-based and specific so users understand the outcome (see [guidelines for Siemens AG employees](https://www.figma.com/design/lqjt9c5IzzwQ4eJ4nqG7Kv/AI-Terminology?node-id=1-9&t=d5UkOPKJfj9qDmYM-1))
+- Don’t allow users to send empty input
+- Don’t rely on color alone to communicate validation errors
+- Don’t place AI disclaimers away from user input and messages
+
+## Related
+
+- [Chat](../chat)
+- [AI message](../ai-message)
+- [User message](../user-message)
+- [Textarea](../textarea)
+- [Conversational design guidelines](../../guidelines/conversational-design/getting-started)

docs/components/chat-input/index.mdx

@@ -0,0 +1,6 @@
+---
+doc-type: "tabs"
+description: 'Chat inputs are used to write messages with attachments in a chat experience.'
+title: 'Chat input'
+deprecated:
+---

docs/components/chat/code.mdx

@@ -0,0 +1,15 @@
+---
+doc-type: 'tab-item'
+description: 'Code examples and API documentation for chat.'
+---
+
+import ChatPlayground from '@site/docs/autogenerated/playground/chat.mdx';
+import PropsApi from '@site/docs/autogenerated/api/ix-chat/api.mdx';
+
+# Chat - Code
+
+## Basic
+
+<ChatPlayground height="40rem" />
+
+<PropsApi />

docs/components/chat/guide.md

@@ -0,0 +1,35 @@
+---
+doc-type: 'tab-item'
+description: 'Usage guide for chat.'
+---
+
+# Chat - Usage
+
+Chats are the outer containers that bring together the three building blocks of a conversational thread: [Chat input](../chat-input) at the bottom for writing and sending prompts, [user messages](../user-message) that show what users submitted and [AI messages](../ai-message) that display AI responses.
+
+![Chat anatomy](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7962-804&t=8Rj3ErabF16Vm3lH-4)
+
+1. [User message](../user-message)
+2. [AI message](../ai-message)
+3. [Chat input](../chat-input)
+
+## Behavior in context
+
+- **Placement:** We recommend placing the chat either in the main content or in panes depending on the user goals:
+  - [Main content](../content): Use when the chat is the main focus of the experience, e.g. standalone or workspace copilots
+  - [Panes](../panes): Use when the chat is a secondary feature, e.g. for contextual help
+- **Responsiveness:** Chats will resize to a max-width of `45rem`.
+
+## Dos and Don’ts
+
+- Do enable auto-scroll when users are reading the current response, not when they are reading previous responses
+- Don't add limits to how many messages are visible, instead always display full chat sessions
+
+## Related
+
+- [Chat input](../chat-input)
+- [User message](../user-message)
+- [AI message](../ai-message)
+- [Conversational design guidelines](../../guidelines/conversational-design/getting-started)
+- [SDL AI UX Guidelines](https://www.figma.com/design/KbgPxj7qLgngXkJfnDM4Ty/SDL-AI-UX-Guidelines?t=Kv2aR7JVmhNYuR1S-0) (Siemens AG internal resource)
+

docs/components/chat/index.mdx

@@ -0,0 +1,6 @@
+---
+doc-type: "tabs"
+description: 'Chats are layout components for building conversational chatbot experiences.'
+title: 'Chat'
+deprecated:
+---

docs/components/custom-field/code.mdx

@@ -9,12 +9,16 @@ import PropsApi from '@site/docs/autogenerated/api/ix-custom-field/api.mdx';
 
 # Custom field - Code
 
-With the help of `ix-custom-field` you are able to create form fields that can host any component / markup, while still having access to all validation states as well as ascociated explanatory texts like `helper-text`, `valid-text`, `info-text`, `warning-text` or `invalid-text`.
+With the help of `ix-custom-field` you are able to create form fields that can host any component / markup, while still having access to all validation states as well as associated explanatory texts like `helper-text`, `valid-text`, `info-text`, `warning-text` or `invalid-text`.
 The component will check if any of its children has one of these classes set:
 `ix-valid, ix-info, ix-warning or ix-invalid`
 If this is the case the custom field will display the corresponding text.
 
-Custom fields can be used to migrate from the existing input validation (native inputs) to the new validation / froms concept.
+Custom fields can be used to migrate from the existing input validation (native inputs) to the new validation / forms concept.
+
+:::info Legacy native input styles
+The validation example uses the legacy `.ix-form-control` class. Import `@siemens/ix/css/legacy.css` while migrating existing native inputs. For new applications, prefer the dedicated form components or provide application-specific styles for custom native controls.
+:::
 
 ## Basic
 

docs/components/html-grid/code.mdx

@@ -8,6 +8,12 @@ import HtmlTableStripedPlayground from '@site/docs/autogenerated/playground/html
 
 # HTML table - Code
 
+The default stylesheet includes the `.ix-table` and `.ix-table-striped` classes used by these examples. If you load the foundation and a theme separately instead, import the utility stylesheet once in your application:
+
+```css
+@import '@siemens/ix/css/utilities.css';
+```
+
 ## Basic
 
 <HtmlTablePlayground height="12rem" />

docs/components/key-value-list/code.mdx

@@ -12,6 +12,10 @@ import KeyValueListStripedPlayground from '@site/docs/autogenerated/playground/k
 
 # Key value list - Code
 
+:::info Legacy native input styles
+The custom value example uses the legacy `.ix-form-control` class. Import `@siemens/ix/css/legacy.css` while migrating existing native inputs. For new applications, prefer an input component or provide application-specific styles for the slotted native control.
+:::
+
 ## Basic
 
 <KeyValueListPlayground height="12rem" />

docs/components/key-value/code.mdx

@@ -12,6 +12,10 @@ import KeyValueWithLabelLeftPlayground from '@site/docs/autogenerated/playground
 
 # Key value - Code
 
+:::info Legacy native input styles
+The custom value example uses the legacy `.ix-form-control` class. Import `@siemens/ix/css/legacy.css` while migrating existing native inputs. For new applications, prefer an input component or provide application-specific styles for the slotted native control.
+:::
+
 ## Basic
 
 <KeyValuePlayground height="16rem" />