diff --git a/.env.production b/.env.production
index 5a404a70b..444091b70 100644
--- a/.env.production
+++ b/.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=''
diff --git a/docs/components/ai-message/code.mdx b/docs/components/ai-message/code.mdx
new file mode 100644
index 000000000..b7895f30c
--- /dev/null
+++ b/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
+
+
+
+
diff --git a/docs/components/ai-message/guide.md b/docs/components/ai-message/guide.md
new file mode 100644
index 000000000..9391db2bd
--- /dev/null
+++ b/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.
+
+
+
+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)
diff --git a/docs/components/ai-message/index.mdx b/docs/components/ai-message/index.mdx
new file mode 100644
index 000000000..f64efa929
--- /dev/null
+++ b/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:
+---
diff --git a/docs/components/chat-attachment/code.mdx b/docs/components/chat-attachment/code.mdx
new file mode 100644
index 000000000..8fd0d1b6d
--- /dev/null
+++ b/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
+
+
+
+
diff --git a/docs/components/chat-attachment/guide.md b/docs/components/chat-attachment/guide.md
new file mode 100644
index 000000000..945f27a85
--- /dev/null
+++ b/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/).
+
+
+
+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)
diff --git a/docs/components/chat-attachment/index.mdx b/docs/components/chat-attachment/index.mdx
new file mode 100644
index 000000000..07c2dae32
--- /dev/null
+++ b/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:
+---
diff --git a/docs/components/chat-input/code.mdx b/docs/components/chat-input/code.mdx
new file mode 100644
index 000000000..12637b878
--- /dev/null
+++ b/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
+
+
+
+
diff --git a/docs/components/chat-input/guide.md b/docs/components/chat-input/guide.md
new file mode 100644
index 000000000..1214a8433
--- /dev/null
+++ b/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.
+
+
+
+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
+
+
+
+## States
+
+Chat inputs have four states: default, hover, focused and processing.
+
+
+
+## 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)
diff --git a/docs/components/chat-input/index.mdx b/docs/components/chat-input/index.mdx
new file mode 100644
index 000000000..79482932f
--- /dev/null
+++ b/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:
+---
diff --git a/docs/components/chat/code.mdx b/docs/components/chat/code.mdx
new file mode 100644
index 000000000..b7e383fbe
--- /dev/null
+++ b/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
+
+
+
+
diff --git a/docs/components/chat/guide.md b/docs/components/chat/guide.md
new file mode 100644
index 000000000..af5b43a50
--- /dev/null
+++ b/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.
+
+
+
+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)
+
diff --git a/docs/components/chat/index.mdx b/docs/components/chat/index.mdx
new file mode 100644
index 000000000..04494db3f
--- /dev/null
+++ b/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:
+---
diff --git a/docs/components/custom-field/code.mdx b/docs/components/custom-field/code.mdx
index ced8573f3..b2e2f90fa 100644
--- a/docs/components/custom-field/code.mdx
+++ b/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
diff --git a/docs/components/html-grid/code.mdx b/docs/components/html-grid/code.mdx
index a826f429b..f014fa5fa 100644
--- a/docs/components/html-grid/code.mdx
+++ b/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
diff --git a/docs/components/key-value-list/code.mdx b/docs/components/key-value-list/code.mdx
index 8f33de976..a2153fa60 100644
--- a/docs/components/key-value-list/code.mdx
+++ b/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
diff --git a/docs/components/key-value/code.mdx b/docs/components/key-value/code.mdx
index 5d8adb539..3ca445c23 100644
--- a/docs/components/key-value/code.mdx
+++ b/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
diff --git a/docs/components/overview.md b/docs/components/overview.md
index 5ddd13d35..82872272b 100644
--- a/docs/components/overview.md
+++ b/docs/components/overview.md
@@ -18,47 +18,52 @@ import { CategoryButton } from '@site/src/components/CategoryButton';
-
+
-
+
-
+
-
+
-
+
-
+
-
+
-
+
+
+
+
-
+
@@ -171,6 +176,16 @@ import { CategoryButton } from '@site/src/components/CategoryButton';
| [Key value list](./key-value-list/index.mdx) | Key value lists organize and list a series of key value pairs. |
| [KPI](./kpi/index.mdx) | KPIs display measured values together with a status indicator to help users interpret data. |
+## Chat
+
+| Component | Description |
+| :--------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------- |
+| [Chat](./chat/index.mdx) | Chat component for building conversational chatbot experiences. |
+| [Chat input](./chat-input/index.mdx) | Chat inputs are used to compose and submit messages, attachments and follow-up actions in a conversational AI thread. |
+| [User message](./user-message/index.mdx) | User messages display messages authored by the user in a chat thread. |
+| [AI message](./ai-message/index.mdx) | AI messages display responses generated by the AI in a conversational chats. |
+| [Chat attachment](./chat-attachment/index.mdx) | Chat attachments are files attached on chat inputs and user messages. |
+
## Charts
| Component | Description |
diff --git a/docs/components/user-message/code.mdx b/docs/components/user-message/code.mdx
new file mode 100644
index 000000000..a9625a7bc
--- /dev/null
+++ b/docs/components/user-message/code.mdx
@@ -0,0 +1,14 @@
+---
+doc-type: 'tab-item'
+description: 'Code examples and API documentation for user message.'
+---
+
+import ChatUserMessagePlayground from '@site/docs/autogenerated/playground/chat-user-message.mdx';
+import PropsApi from '@site/docs/autogenerated/api/ix-chat-user-message/api.mdx';
+
+# User message - Code
+## Basic
+
+
+
+
diff --git a/docs/components/user-message/guide.md b/docs/components/user-message/guide.md
new file mode 100644
index 000000000..1ce4405ad
--- /dev/null
+++ b/docs/components/user-message/guide.md
@@ -0,0 +1,38 @@
+---
+doc-type: 'tab-item'
+description: 'Usage guide for user message.'
+---
+
+# User message - Usage
+
+User messages display a single prompt submitted by users in a conversational thread. We recommend using them to preserve what users asked, attached or edited so follow-up answers maintain context.
+
+
+
+1. Attachments
+2. Message
+3. Actions
+
+## Options
+
+- **Attachments:** When users attach files with their prompts, show those [attachments](../chat-attachment) with the message to maintain context even after multiple turns in the conversation.
+- **Message:** Show the original user input as the main message content without alterations.
+- **Actions:** Add only the few actions users need for their own prompt, e.g. copy, edit or open a compact overflow menu. We recommend using subtle tertiary [icon buttons](../icon-button) so actions stay secondary to the message.
+
+## Behavior in context
+
+- **Interaction:** User messages keep the sent prompts visible as a chat history of user input.
+- **Actions:** Message actions are only shown when users hover over the message with a mouse, tap the message on touch devices or reach the message with the `Tab` key (for Siemens AG see the [AI UX terminology guide](https://www.figma.com/design/lqjt9c5IzzwQ4eJ4nqG7Kv/AI-Terminology?node-id=1-9&t=8g9VIGSar5B6wwtC-1) on labelling actions).
+- **Placement:** User messages are always placed on the right side of the [chat](../chat/) to visually distinguish them from [AI messages](../ai-message) on the left side.
+- **Responsiveness:** User messages take from 45 to 80% of the chat's container width, depending on the viewport width.
+
+## Dos and Don’ts
+
+- Do offer only the few actions users need after sending, e.g. copy or edit
+- Do keep the messages and attachments visible as a continuous chat
+
+## Related
+
+- [Chat](../chat)
+- [AI message](../ai-message)
+- [Chat input](../chat-input)
diff --git a/docs/components/user-message/index.mdx b/docs/components/user-message/index.mdx
new file mode 100644
index 000000000..623f3f728
--- /dev/null
+++ b/docs/components/user-message/index.mdx
@@ -0,0 +1,6 @@
+---
+doc-type: "tabs"
+description: 'User messages display a single message authored by the user in a chat thread, e.g. conversational AI.'
+title: 'User message'
+deprecated:
+---
diff --git a/docs/home/installation/angular.md b/docs/home/installation/angular.md
index 61b9b743b..92306890a 100644
--- a/docs/home/installation/angular.md
+++ b/docs/home/installation/angular.md
@@ -51,9 +51,11 @@ Install `@siemens/ix`, `@siemens/ix-angular` and `@siemens/ix-icons` using a pac
Import the design system styling in your global stylesheet (e.g.: `src/styles.scss`):
```css
-@import '@siemens/ix/dist/siemens-ix/siemens-ix.css';
+@import '@siemens/ix/css/default.css';
```
+The default stylesheet includes the Classic theme, foundation and common utilities for button groups, links, table classes and typography. Foundation applies the SiemensSans Pro font stack to `[data-ix-theme]` and sets body typography, text color, background and document-wide scrollbar styles. The default stylesheet does not include a reset, body margin reset, the complete utility layer or legacy native form styles. See [Global styles](/docs/styles/global-styles) for the optional entry points.
+
Set the `data-ix-theme` attribute of the `` tag to the theme of choice (e.g. `classic`) and the corresponding `data-ix-color-schema` attribute to the value `light`, `dark` or `system` to set the color scheme. `system` will automatically apply the color scheme of the users’ operating system.
```html
diff --git a/docs/home/installation/blazor.md b/docs/home/installation/blazor.md
index 3adb3371e..e6090e54c 100644
--- a/docs/home/installation/blazor.md
+++ b/docs/home/installation/blazor.md
@@ -64,3 +64,5 @@ Add required `CSS` and `Javascript` packages into the `index.html` file.