diff --git a/.env.pullrequest b/.env.pullrequest new file mode 100644 index 000000000..584225b35 --- /dev/null +++ b/.env.pullrequest @@ -0,0 +1,3 @@ +DOCS_BRANCH='main' +DOCS_BRANCH_TYPE='pull request' # Check if the branch is a pull request +DOCS_PR_NUMBER='2569' diff --git a/.github/skills/sdd/SKILL.md b/.github/skills/sdd/SKILL.md new file mode 100644 index 000000000..85a7ac626 --- /dev/null +++ b/.github/skills/sdd/SKILL.md @@ -0,0 +1,277 @@ +--- +name: sdd +description: >- + Spec-Driven Development for Siemens IX: turns user-provided issue or tracking text + into spec.md, plan.md, and tasks.md (GitHub spec-kit style, size-aware, no tracker integration). + Use when the user asks for SDD, spec-kit planning, or structured feature docs from issue text + (e.g. IX-1234 plus pasted description). Outputs live under .sdd/{tracking-id}/. +argument-hint: 'Tracking/issue id (e.g. IX-3896) and pasted title, description, acceptance criteria' +user-invocable: true +--- + +# Spec-Driven Development (IX) + +## Overview + +Transform **user-provided issue or tracking text** (no tracker integration required) into structured specifications following **GitHub spec-kit methodology**: clear separation, progressive disclosure, minimal duplication. + +**When to use**: User wants SDD / spec planning for an IX change and supplies (or will supply) a tracking/issue identifier plus title, description, and acceptance criteria as plain text. + +## Required input (no tracker integration) + +Before Phase 1, confirm you have: + +1. **Tracking/issue identifier** (e.g. `IX-3896`, issue number, ticket key) — if missing, ask once; if still missing, derive a short folder slug from the title (lowercase, hyphens, max ~40 chars). +2. **Issue title** (summary line). +3. **Description** — user story, context, bullets, links as pasted. +4. **Acceptance criteria** — pasted AC block or checklist from the issue/tracking source. + +If the user only pastes prose without clear AC, extract implied AC into the spec and add a **Clarifications** note listing assumptions. + +**Do not** call tracker APIs or assume an MCP; treat the chat message as the source of truth. + +## Key principles + +1. **Separation**: `spec.md` (WHAT), `plan.md` (HOW), `tasks.md` (DO) — no duplication. +2. **Tech-agnostic specs**: Requirements do not name Stencil/React/etc. +3. **Size-aware output**: XS compact; L fuller (see below). +4. **Line limits**: Each artifact file under 500 lines. +5. **Progressive disclosure**: Read spec → plan → tasks when implementing. + +## Workflow phases + +``` +Pasted issue text → Specify → Review → Clarify → Review → Plan → Review → Tasks → Review → Implement + ↓ ↓ ↓ ↓ + spec.md spec.md plan.md tasks.md +``` + +**Mandatory phase gates**: + +After creating or updating each artifact, stop and ask the user to review the created file before continuing: + +1. After `spec.md`: ask whether to continue to planning or revise the spec. +2. After updated `spec.md` clarifications: ask whether to continue to planning or revise the clarified spec. +3. After `plan.md`: ask whether to continue to task breakdown or revise the plan. +4. After `tasks.md`: ask whether to implement, revise tasks, or stop at handoff. + +Do **not** proceed to the next phase automatically after writing an artifact. If the runtime provides an `ask_user` tool, use it for these phase gates instead of asking in plain text. + +If the XS strategy omits `spec.md` or `tasks.md`, skip only the omitted file's review gate; still stop after the merged `plan.md` and ask the user to review it before implementation. + +### Phase 1: Specify (requirements) + +Create `spec.md` from the pasted issue only (optional: spawn a read-only explore subagent for codebase context **after** spec is drafted if gaps exist — do not block spec on repo-wide search). + +**Output path**: `.sdd/{TRACKING_ID}/spec.md` (use the agreed tracking/issue identifier or slug for `{TRACKING_ID}`). + +**Review gate**: After writing `spec.md`, stop and ask the user to review `.sdd/{TRACKING_ID}/spec.md`. Continue only when the user approves moving to planning; otherwise revise `spec.md` first. + +**Frontmatter**: + +```yaml +--- +tracking_id: {ID or slug} +feature: {TITLE} +date: {ISO date} +status: ready-for-planning +source: user-pasted-issue +--- +``` + +**Body template** (adapt length to size tier): + +```markdown +# Feature Spec: {TITLE} + +## User input (from issue) +{2–5 lines summarizing pasted description — no copy-paste dump of entire ticket} + +## User scenarios and testing + +### US1 [P1] - {Scenario} +**As** {role} +**I want** {goal} +**So that** {benefit} + +**Acceptance scenarios:** +**Given** {context} +**When** {action} +**Then** {outcome} + +**Edge cases:** {if any} + +## Requirements + +### Functional requirements +**FR-001**: {requirement} +**FR-002**: {requirement} + +### Key entities +{Only if data or domain models matter} + +## Success criteria +**SC-001**: {measurable outcome} +**SC-002**: {measurable outcome} + +## Assumptions +{Scope boundaries, dependencies on other IX areas} +``` + +**Size guide (spec.md only)**: + +- XS: ~40 lines +- S: ~80 lines +- M: ~100 lines +- L: ~150 lines + +### Phase 2: Clarify (optional) + +If requirements are ambiguous, ask targeted questions in chat; when answered, append to `spec.md`: + +```markdown +## Clarifications + +**Q1**: … +**A**: … +``` + +**Review gate**: After adding clarifications, stop and ask the user to review the updated `.sdd/{TRACKING_ID}/spec.md`. Continue only when the user approves moving to planning; otherwise revise `spec.md` first. + +### Phase 3: Plan (technical approach) + +**Output**: `.sdd/{TRACKING_ID}/plan.md` + +1. Read `spec.md`. +2. Align with IX repo: skim `CONTRIBUTING.md` and relevant package/component paths touched; follow existing patterns in the monorepo. +3. Record technical decisions with short rationale; **do not** repeat requirements from `spec.md` — reference them (`See spec.md US1`). + +**Plan frontmatter**: + +```yaml +--- +tracking_id: {ID or slug} +phase: plan +created: {ISO date} +depends_on: [] +--- +``` + +**Sections**: Summary, Technical context (language, packages, tests), Architecture (decisions with alternatives rejected), Implementation structure, Risks and mitigations, Deployment strategy only if non-trivial. + +**Review gate**: After writing `plan.md`, stop and ask the user to review `.sdd/{TRACKING_ID}/plan.md`. Continue only when the user approves creating tasks; otherwise revise `plan.md` first. + +**Size guide (plan.md)**: + +- XS: merge spec + plan into a **single** `plan.md` only (~80 lines total) — skip separate `spec.md` only when doing XS merge (see XS strategy below). +- S: ~120 lines +- M: ~150 lines +- L: ~200 lines + +### Phase 4: Tasks (implementation steps) + +**Output**: `.sdd/{TRACKING_ID}/tasks.md` + +Ordered steps; each task: id, file path in repo, action, optional snippet, dependencies. Mark parallelizable tasks with `[P]`. Do not repeat plan rationale. + +**Review gate**: After writing `tasks.md`, stop and ask the user to review `.sdd/{TRACKING_ID}/tasks.md`. Implement only if the user explicitly approves implementation; otherwise revise `tasks.md` or stop at handoff. + +**Size guide (tasks.md)**: + +- XS: omit `tasks.md` (implement from merged plan). +- S: ~100 lines +- M: ~150 lines +- L: ~200 lines + +### Phase 5: Research (optional) + +Create `research.md` only for unusual dependency or API verification — not for routine Stencil/Playwright usage. + +**Output**: `.sdd/{TRACKING_ID}/research.md` (<300 lines). + +## XS output strategy + +For **XS** (<~2h) work: + +- Produce **one** file: `.sdd/{TRACKING_ID}/plan.md` (~80 lines) that merges concise requirements + approach + minimal task list + validation checklist. +- Omit separate `spec.md` / `tasks.md` unless the user explicitly wants full spec-kit layout. +- Stop after writing the merged `plan.md` and ask the user to review it before implementation. + +## S / M / L output strategy + +| Tier | Outputs | Approx. total lines | +|------|---------|---------------------| +| S | spec.md + plan.md + tasks.md | ~300 | +| M | spec.md + plan.md + tasks.md | ~400 | +| L | spec.md + plan.md + tasks.md (+ optional research.md) | ~600 | + +Classify size from pasted story points, AC count, and breadth (single component vs cross-package). + +## Anti-duplication rules + +Before each paragraph: + +1. Already in `spec.md`? → Link, do not repeat. +2. Technical decision? → `plan.md` only. +3. Implementation step? → `tasks.md` only. +4. Obvious to an IX maintainer? → Skip (standard monorepo test commands, changeset rules — point to existing skills if needed). +5. Project-wide rule? → Reference `CONTRIBUTING.md` or the relevant package README. + +**Cross-reference pattern**: + +```markdown +See spec.md US1 for acceptance criteria. +See plan.md Architecture for rationale. +``` + +## File layout + +```text +.sdd/{TRACKING_ID}/ +├── spec.md # Requirements (tech-agnostic) +├── plan.md # Technical approach +├── tasks.md # Implementation steps +└── research.md # Optional tech verification +``` + +Do **not** generate `narrative.md` or standalone `alternatives.md` — keep decisions inline in `plan.md`. + +## Context management + +- **Main chat**: clarify scope, write `plan.md` / `tasks.md`, discuss trade-offs. +- **Read-only exploration**: large codebase search to ground `plan.md` paths — use sparingly after `spec.md` exists. + +## Implementation handoff + +When artifacts are ready: + +```text +Specification complete for {TRACKING_ID}. + +Files: +- spec.md — requirements +- plan.md — technical approach +- tasks.md — steps (if created) + +Next: implement a task, all tasks in order, or revise the plan — say which you prefer. +``` + +## Quality checklist + +**spec.md**: Tech-agnostic; Given/When/Then where applicable; numbered FRs; measurable success criteria; <500 lines. + +**plan.md**: No requirement duplication; decisions with 1–2 line rationale; references spec; IX-realistic paths; <500 lines. + +**tasks.md**: Exact repo paths; dependency order; `[P]` for parallel; no decision essays; <500 lines. + +**Overall**: No cross-file duplication; size tier matches work; each file has one job. + +## IX-specific notes + +- Prefer paths under `packages/core`, `packages/angular`, `packages/react`, `packages/documentation`, etc., as appropriate — discover real paths from the tree, do not invent directories. +- Testing and release hygiene: use existing project skills (component tests, Storybook a11y, changesets) when the user’s workflow requires them; do not restate full skill bodies here. + +## References + +- [GitHub spec-kit](https://github.com/github/spec-kit) +- Project skill definition: `.github/skills/sdd/SKILL.md` — this repo skill uses pasted issue/tracking text and `.sdd/…` for generated artifacts. diff --git a/docs/components/ai-message/code.mdx b/docs/components/ai-message/code.mdx new file mode 100644 index 000000000..2869f7b05 --- /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..58a727f05 --- /dev/null +++ b/docs/components/ai-message/guide.md @@ -0,0 +1,37 @@ +--- +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. We usually structure longer answers with a short lead sentence followed by lists, short paragraphs or other lightweight content blocks. +- **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, e.g. with [chips](../chip). Only show sources when they are real and inspectable. + +## 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 structure longer responses into short paragraphs or lists so users can scan them quickly +- Do show clear [loading indicators](../spinner/) while the assistant is processing +- Do show sources or evidence when the response refers to external or retrieved information +- Don't overuse actions by focusing only on the few actions users commonly need after reading, e.g. copy, feedback, regenerate +- Don’t present speculative or low-confidence output as if it were verified fact + +## Related + +- [Chat](../chat) +- [User message](../user-message) +- [Chat input](../chat-input) diff --git a/docs/components/ai-message/index.mdx b/docs/components/ai-message/index.mdx new file mode 100644 index 000000000..1c544ae65 --- /dev/null +++ b/docs/components/ai-message/index.mdx @@ -0,0 +1,6 @@ +--- +doc-type: "tabs" +description: 'Used to display a single response generated by the AI in a conversational chats' +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..39dba715b --- /dev/null +++ b/docs/components/chat-attachment/code.mdx @@ -0,0 +1,15 @@ +--- +doc-type: 'tab-item' +description: 'Code examples and API documentation for AI message' +--- + +import ChatAttachmentPlayground from '@site/docs/autogenerated/playground/chat-user-message.mdx'; +import PropsApi from '@site/docs/autogenerated/api/ix-chat-prompt-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..bf942041f --- /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 add to a chat prompt. We recommend using them in [chat inputs](../chat-input) while users compose a message and in [user messages](../user-message) after submission to preserve the full request context. + +![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 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. +- **Tooltip:** By default, the tooltip shows the file name in case of truncation. Override it to show additional information, e.g. for previews or file size. + +## 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 shows the full file name on hover. + +## 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 submitted attachments visible in user messages so conversation context stays traceable +- 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 submission + +## 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..2f58a3d8f --- /dev/null +++ b/docs/components/chat-attachment/index.mdx @@ -0,0 +1,6 @@ +--- +doc-type: "tabs" +description: 'Used to display a single attachment' +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..5386ac5fc --- /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..dc0f9d989 --- /dev/null +++ b/docs/components/chat-input/guide.md @@ -0,0 +1,62 @@ +--- +doc-type: 'tab-item' +description: 'Usage guide for chat input' +--- + +# Chat input - Usage + +Chat inputs help users compose and send short conversational messages in chat experiences. 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 questions +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…” +- **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, include a short visible disclaimer near the input. +- **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 slot: If the follow-up 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 + +![Anatomy component](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7940-7020&t=mrtbkWj76QJhvNLI-11) + +## States + +Chat inputs have six 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 labels and helper text explicit instead of relying on placeholder text only +- Do keep action labels verb-based and specific so users understand the outcome +- Do show attachment or action context before send so users can review what they submit +- Do keep AI disclaimers concise and tied to AI generation contexts +- Don’t allow sending empty input +- Don’t rely on color alone to communicate validation errors +- Don’t hide essential guidance only in tooltips +- Don’t use AI disclaimer content in non-AI messaging contexts + +## Related + +- [Chat](../chat) +- [AI message](../ai-message) +- [User message](../user-message) +- [Textarea](../textarea) diff --git a/docs/components/chat-input/index.mdx b/docs/components/chat-input/index.mdx new file mode 100644 index 000000000..0d26dd85a --- /dev/null +++ b/docs/components/chat-input/index.mdx @@ -0,0 +1,6 @@ +--- +doc-type: "tabs" +description: 'Used to compose and submit messages, attachments and follow-up actions in a conversational AI thread' +title: 'Chat input' +deprecated: +--- diff --git a/docs/components/chat/code.mdx b/docs/components/chat/code.mdx new file mode 100644 index 000000000..ac4f10092 --- /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..846cc1eb5 --- /dev/null +++ b/docs/components/chat/guide.md @@ -0,0 +1,33 @@ +--- +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 composing and sending prompts, [user messages](../user-message) that record what users submitted and [AI messages](../ai-message) that display the assistant's 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) + +## Dos and Don’ts + +- Do use chats for conversational experiences that require users to read, review and act on messages in a thread +- Do enable auto-scroll when users are already at the latest message, not when they are reading older messages + +## 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 + +## 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) (can be accessed exclusively by Siemens AG employees) diff --git a/docs/components/chat/index.mdx b/docs/components/chat/index.mdx new file mode 100644 index 000000000..c379a7265 --- /dev/null +++ b/docs/components/chat/index.mdx @@ -0,0 +1,6 @@ +--- +doc-type: "tabs" +description: 'Chat component for building conversational chatbot experiences' +title: 'Chat' +deprecated: +--- diff --git a/docs/components/overview.md b/docs/components/overview.md index b6ec2c5ad..7439a6a74 100644 --- a/docs/components/overview.md +++ b/docs/components/overview.md @@ -18,47 +18,52 @@ import { CategoryButton } from '@site/src/components/CategoryButton'; -![](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=5186-249&t=gkh6VNlJun96I6Ac-4) +![Application frame](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=5186-249&t=gkh6VNlJun96I6Ac-4) -![](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=5186-259&t=gkh6VNlJun96I6Ac-4) +![Navigation and hierarchy](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=5186-259&t=gkh6VNlJun96I6Ac-4) -![](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=5186-269&t=gkh6VNlJun96I6Ac-4) +![Containers and layouts](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=5186-269&t=gkh6VNlJun96I6Ac-4) -![](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=5186-283&t=gkh6VNlJun96I6Ac-4) +![Forms](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=5186-283&t=gkh6VNlJun96I6Ac-4) -![](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=5186-298&t=gkh6VNlJun96I6Ac-11) +![Input fields and selections](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=5186-298&t=gkh6VNlJun96I6Ac-11) -![](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=5186-305&t=gkh6VNlJun96I6Ac-11) +![Buttons and actions](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=5186-305&t=gkh6VNlJun96I6Ac-11) -![](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=5186-332&t=gkh6VNlJun96I6Ac-11) +![System feedback and status](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=5186-332&t=gkh6VNlJun96I6Ac-11) -![](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=5186-370&t=gkh6VNlJun96I6Ac-11) +![Data display](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=5186-370&t=gkh6VNlJun96I6Ac-11) + + +![Chat](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7974-3280&t=HrpSIFfB7yjzt741-4) -![](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=5186-387&t=gkh6VNlJun96I6Ac-11) +![Charts](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=5186-387&t=gkh6VNlJun96I6Ac-11) @@ -169,6 +174,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..2f60af125 --- /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..94eba7634 --- /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 keep the right context. + +![User message anatomy](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=7959-1370&t=8Rj3ErabF16Vm3lH-4) + +1. Attachments +2. Message +3. Actions + +## Options + +- **Attachments:** If users submit files together with a prompt, show those [attachments](../chat-attachment) directly with the message so the request stays understandable later in the thread. +- **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 submitted prompt visible as the main record of what users asked. +- **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. +- **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, edit or more actions +- Do keep the original message wording and attachments visible so users can review what they submitted + +## 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..ebb6088ac --- /dev/null +++ b/docs/components/user-message/index.mdx @@ -0,0 +1,6 @@ +--- +doc-type: "tabs" +description: 'Used to display a single message authored by the user in a chat thread, e.g. conversational AI' +title: 'User message' +deprecated: +--- diff --git a/sidebars.ts b/sidebars.ts index 7355dd90b..46cebf921 100644 --- a/sidebars.ts +++ b/sidebars.ts @@ -1129,6 +1129,85 @@ const sidebars: SidebarsConfig = { type: 'category', className: 'doc-sidebar-item-bold', + label: 'Chat', + items: [ + createTabItem({ + id: 'components/chat/index', + label: 'Chat', + items: [ + { + id: 'components/chat/guide', + label: 'Usage', + }, + { + id: 'components/chat/code', + label: 'Code', + }, + ], + }), + createTabItem({ + id: 'components/chat-input/index', + label: 'Chat input', + items: [ + { + id: 'components/chat-input/guide', + label: 'Usage', + }, + { + id: 'components/chat-input/code', + label: 'Code', + }, + ], + }), + createTabItem({ + id: 'components/user-message/index', + label: 'User message', + items: [ + { + id: 'components/user-message/guide', + label: 'Usage', + }, + { + id: 'components/user-message/code', + label: 'Code', + }, + ], + }), + createTabItem({ + id: 'components/ai-message/index', + label: 'AI message', + items: [ + { + id: 'components/ai-message/guide', + label: 'Usage', + }, + { + id: 'components/ai-message/code', + label: 'Code', + }, + ], + }), + createTabItem({ + id: 'components/chat-attachment/index', + label: 'Chat attachment', + items: [ + { + id: 'components/chat-attachment/guide', + label: 'Usage', + }, + { + id: 'components/chat-attachment/code', + label: 'Code', + }, + ], + }), + ], + collapsed: true, + }, + { + type: 'category', + className: 'doc-sidebar-item-bold', + label: 'Charts', items: [ { diff --git a/static/figma/wEptRgAezDU1z80Cn3eZ0o_7940_2809.png b/static/figma/wEptRgAezDU1z80Cn3eZ0o_7940_2809.png new file mode 100644 index 000000000..1302a8721 Binary files /dev/null and b/static/figma/wEptRgAezDU1z80Cn3eZ0o_7940_2809.png differ diff --git a/static/figma/wEptRgAezDU1z80Cn3eZ0o_7940_7020.png b/static/figma/wEptRgAezDU1z80Cn3eZ0o_7940_7020.png new file mode 100644 index 000000000..8d29a8b80 Binary files /dev/null and b/static/figma/wEptRgAezDU1z80Cn3eZ0o_7940_7020.png differ diff --git a/static/figma/wEptRgAezDU1z80Cn3eZ0o_7940_7427.png b/static/figma/wEptRgAezDU1z80Cn3eZ0o_7940_7427.png new file mode 100644 index 000000000..e91a8f6a0 Binary files /dev/null and b/static/figma/wEptRgAezDU1z80Cn3eZ0o_7940_7427.png differ diff --git a/static/figma/wEptRgAezDU1z80Cn3eZ0o_7959_1370.png b/static/figma/wEptRgAezDU1z80Cn3eZ0o_7959_1370.png new file mode 100644 index 000000000..efbf54259 Binary files /dev/null and b/static/figma/wEptRgAezDU1z80Cn3eZ0o_7959_1370.png differ diff --git a/static/figma/wEptRgAezDU1z80Cn3eZ0o_7959_520.png b/static/figma/wEptRgAezDU1z80Cn3eZ0o_7959_520.png new file mode 100644 index 000000000..b7d75d6ea Binary files /dev/null and b/static/figma/wEptRgAezDU1z80Cn3eZ0o_7959_520.png differ diff --git a/static/figma/wEptRgAezDU1z80Cn3eZ0o_7962_804.png b/static/figma/wEptRgAezDU1z80Cn3eZ0o_7962_804.png new file mode 100644 index 000000000..abbb8b66c Binary files /dev/null and b/static/figma/wEptRgAezDU1z80Cn3eZ0o_7962_804.png differ diff --git a/static/figma/wEptRgAezDU1z80Cn3eZ0o_7970_230.png b/static/figma/wEptRgAezDU1z80Cn3eZ0o_7970_230.png new file mode 100644 index 000000000..ddf854eaf Binary files /dev/null and b/static/figma/wEptRgAezDU1z80Cn3eZ0o_7970_230.png differ diff --git a/static/figma/wEptRgAezDU1z80Cn3eZ0o_7974_3280.png b/static/figma/wEptRgAezDU1z80Cn3eZ0o_7974_3280.png new file mode 100644 index 000000000..a8c9ebbae Binary files /dev/null and b/static/figma/wEptRgAezDU1z80Cn3eZ0o_7974_3280.png differ