Add usage guide for list component

.github/skills/component-ideation/SKILL.md

@@ -0,0 +1,241 @@
+---
+name: component-ideation
+description: 'Create or update component ideation documents for Siemens Industrial Experience docs. Use when researching a component from its implementation branch, Figma specification, Siemens Element, IX design-system knowledge, and external design systems, then structuring the result into Anatomy, When to use, Options, Behavior in context, Statuses, and Other Dos and Don’ts.'
+argument-hint: 'Which component should be researched? Provide its docs folder, implementation branch or pull request, Figma component URL, and Element URL when available.'
+---
+
+# Component ideation
+
+Use this skill to create a reusable, source-backed `ideation.md` for a component under `docs/components/<component>/`.
+
+The purpose is to collect product, design, interaction, accessibility, and implementation evidence before writing the final usage guide. Keep the result useful for Siemens and non-Siemens audiences. Separate confirmed behavior from recommendations and unresolved questions.
+
+## Required inputs
+
+Ask for or identify these inputs before researching:
+
+- Component name and repository docs folder
+- Implementation branch, pull request, or source path
+- Figma component URL with a node ID
+- Siemens Element component URL, if a related component exists
+- IX design-system knowledge category or search topic
+
+When a source is unavailable, record that limitation in the document and continue with the remaining sources. Do not invent missing properties or behavior.
+
+## Source-gathering workflow
+
+### 1. Inspect the repository
+
+Read the target component folder and nearby component documentation to learn the local terminology and file conventions. Check the component overview, code examples, generated API references, related components, and any existing guide.
+
+From the implementation branch or pull request, collect:
+
+- Public properties, types, defaults, and inheritance behavior
+- Events and event payloads
+- Slots and their intended content
+- Built-in keyboard, pointer, touch, focus, screen-reader, responsive, and overflow behavior
+- Built-in states and constraints
+- Component names and source file paths
+
+Treat the code as authoritative for implemented behavior. Do not turn internal implementation details into public guidance unless they affect how authors use the component.
+
+### 2. Inspect Figma
+
+Use the Figma MCP for the supplied component URL. Extract the node ID and file key from the URL. Read the design context first when available; use metadata as a fallback for anatomy and option discovery if the design-context call is unavailable.
+
+Collect:
+
+- Anatomy and reading order
+- Component dimensions, sizing rules, spacing, and alignment
+- Variants and option names
+- Visible states and interaction examples
+- Slot or content patterns
+- Overflow, responsive, touch, keyboard, and screen-reader annotations
+- Figma-specific recommendations, warnings, and open notes
+
+If Figma reports that no layer is selected or returns only metadata, state that limitation explicitly. Do not describe invisible visual details as confirmed facts.
+
+### 3. Inspect Siemens Element
+
+Read the related Element page and collect its purpose, when-to-use guidance, alternatives, best practices, responsive behavior, and accessibility implications. Use Element as a sister-system comparison, not as proof of IX implementation behavior.
+
+### 4. Search IX design-system knowledge
+
+Use the available IX design-system search and browse tools. Search the relevant component category and, when useful, guidelines, patterns, accessibility, tokens, and quality topics.
+
+Collect recommendations about:
+
+- Component choice and alternatives
+- Content and layout
+- Interaction and focus
+- Responsive behavior and overflow
+- Accessibility and localization
+- Reuse of existing IX components and tokens
+
+Prefer specific, relevant results over a broad catalogue dump. Record the category or query used so the final references remain traceable.
+
+### 5. Compare external design systems
+
+Use two or three established design systems with strong, relevant guidance. Good defaults include Material 3, Carbon, Fluent, Spectrum, Atlassian, or PatternFly. Fetch their usage guidance rather than relying on component names alone.
+
+Compare:
+
+- Intended use and boundaries
+- Anatomy and density
+- Selection and actions
+- Keyboard and screen-reader behavior
+- Overflow and responsive rules
+- Guidance for tables, trees, grids, and other alternatives
+
+Use comparisons to identify converging principles and useful questions. Do not copy another system’s API or terminology into IX guidance.
+
+## Output location and frontmatter
+
+Create or update:
+
+`docs/components/<component>/ideation.md`
+
+Use frontmatter that matches the docs repository, for example:
+
+```yaml
+---
+title: 'Component name - ideation'
+description: 'Research and design notes for the component.'
+---
+```
+
+## Required document structure
+
+Use this exact order:
+
+1. `## 1. Anatomy`
+2. `## 2. When to use`
+3. `## 3. Options`
+4. `## 4. Behavior in context`
+5. `## 5. Statuses`
+6. `## 6. Other Dos and Don’ts`
+7. `## References`
+
+The document may have a short title and introduction before section 1. Keep all references at the end of the file. Do not add a separate references section earlier in the document.
+
+### 1. Anatomy
+
+Describe the visible and semantic parts in reading order. Include:
+
+- Container and sizing behavior
+- Leading, primary, supporting, status, and trailing content
+- Slots and custom content
+- Dividers, separators, grouping, or hierarchy
+- Semantic roles when confirmed by code
+
+End the section with these subsections, in this order:
+
+```markdown
+**Additional information**
+
+- Supporting facts, source limitations, or useful related context
+
+**Open discussion points**
+
+- ▶️ Question or decision that still needs confirmation
+```
+
+### 2. When to use
+
+Explain when the component is appropriate and when to choose an alternative. Cover likely alternatives such as tables, grids, trees, event lists, card lists, menus, or native HTML where relevant.
+
+Include practical guidance for single-column content, complexity, placement, scanning, and operational context. Keep recommendations useful outside Siemens as well.
+
+End with `**Additional information**`, then `**Open discussion points**`; every open question must begin with `▶️`.
+
+### 3. Options
+
+List all public options found in the code API and all meaningful options found in Figma. For each option, include the readable name, technical property where useful, supported values, default, and usage recommendation.
+
+Also include:
+
+- Events and payloads when they affect author decisions
+- Slots and content patterns
+- Inherited defaults and item-level overrides
+- Recommendations and best practices from IX, Element, and external systems
+- Token, density, and action limits only when supported by evidence
+
+Do not omit an API property simply because it is not shown in Figma. Label implementation-only or advanced options clearly.
+
+End with `**Additional information**`, then `**Open discussion points**`; every open question must begin with `▶️`.
+
+### 4. Behavior in context
+
+Describe built-in behavior in practical usage terms. Cover the subsections that apply:
+
+- Interaction
+- Keyboard navigation
+- Pointer and touch behavior
+- Screen readers and accessible input
+- Focus management
+- Responsive behavior
+- Overflow, wrapping, truncation, tooltips, and scrolling
+- Alignment and placement
+- Selection, activation, actions, drag and drop, or other component-specific workflows
+
+Distinguish implemented behavior from author responsibility. Avoid duplicating the generated API reference without explaining how the behavior affects usage.
+
+End with `**Additional information**`, then `**Open discussion points**`; every open question must begin with `▶️`.
+
+### 5. Statuses
+
+List all relevant visual and semantic states, such as:
+
+- Default
+- Hover
+- Focus
+- Active or pressed
+- Selected
+- Disabled
+- Loading
+- Error or validation
+- Open or expanded
+- Dragging or reorder target
+- Overflow or scrollable
+- Empty
+
+Only include states supported by the component or clearly relevant to its surrounding workflow. Describe what changes and what remains actionable in each state. Include both code-confirmed states and Figma-documented states, labeling uncertainty.
+
+End with `**Additional information**`, then `**Open discussion points**`; every open question must begin with `▶️`.
+
+### 6. Other Dos and Don’ts
+
+Use concise imperative bullets. Keep dos first and don’ts second. Start every bullet with `Do` or `Don’t`. Keep each bullet to one sentence and no more than five dos and five don’ts.
+
+Recommendations should cover content clarity, consistency, accessibility, responsive use, interaction boundaries, and choosing a better alternative when appropriate.
+
+End with `**Additional information**`, then `**Open discussion points**`; every open question must begin with `▶️`.
+
+## Evidence and writing rules
+
+- Prefer source-backed statements and name the source in the surrounding text when the distinction matters
+- Use “The branch implements…” for code facts, “The Figma specification shows…” for design evidence, and “We recommend…” for proposed guidance
+- Keep implementation properties complete under Options, but keep the rest of the document decision-oriented
+- Do not merge speculative recommendations into confirmed API behavior
+- Use suggestion-oriented language that works for Siemens and other teams
+- Treat Siemens-specific product habits as examples or context, not universal requirements
+- Prefer existing IX components, tokens, icons, and accessibility patterns
+- Do not create new component APIs, slots, states, or limits from comparison systems
+- Keep terminology consistent with nearby docs and the source component
+- Use relative links for local component alternatives and direct links for external references
+- Avoid duplicated content across sections; place API details in Options and usage consequences in Behavior in context
+- Use ASCII by default when creating the file, except where the repository’s established prose uses typographic punctuation
+
+## Validation checklist
+
+Before finishing:
+
+1. Confirm the file exists under the intended component folder.
+2. Check frontmatter delimiters and the presence of `title` and `description`.
+3. Confirm the six requested sections appear in the required order.
+4. Confirm every section ends with additional information followed by open discussion points.
+5. Confirm every open discussion point begins with `▶️`.
+6. Confirm References is the final section.
+7. Set the component path before running the check, then use a quoted variable: `component=list; git diff --check -- "docs/components/${component}/ideation.md"`.
+8. Run repository diagnostics for the file when available.
+9. Run the docs build. If the build is blocked by repository credentials, missing generated artifacts, or another unrelated environment problem, report the exact blocker and run the narrowest available direct documentation build.

docs/components/generic-list/code.mdx → docs/components/list/code.mdx

@@ -14,25 +14,25 @@ import GenericListDraggablePlayground from '@site/docs/autogenerated/playground/
 import GenericListActionOnHoverPlayground from '@site/docs/autogenerated/playground/generic-list-action-on-hover.mdx';
 import GenericListCustomContentPlayground from '@site/docs/autogenerated/playground/generic-list-custom-content.mdx';
 
-# Generic List - Code
+# List - Code
 
 ## Variants
 
 <GenericListVariantsPlayground height="29rem" />
 
-## Additional Options
+## Additional options
 
 <GenericListAdditionalOptionsPlayground height="12rem" />
 
 ## Draggable
 
 <GenericListDraggablePlayground />
 
-## Action On Hover
+## Action on hover
 
 <GenericListActionOnHoverPlayground />
 
-## Custom Content
+## Custom content
 
 <GenericListCustomContentPlayground height="16rem" />
 

docs/components/list/guide.md

@@ -0,0 +1,98 @@
+---
+doc-type: 'tab-item'
+description: 'Usage guide for the ix-list and ix-list-item'
+---
+
+# List - Usage
+
+Use lists when users need to scan related items vertically and might need to select or reorder them. Lists work well in [cards](../card/), [modals](../modal/), [panes](../panes/) and similar layouts.
+
+
+![List anatomy](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=8309-10950&t=xnc4u6vlAsTkE0Uc-11)
+
+1. Drag indicator
+2. Checkbox
+3. Content with icon, label and status badge
+4. Actions
+5. Divider
+6. Separator
+
+Keep lists focused on one item type. Use a divider to distinguish items within lists. Use a separator to create space between groups of items. Keep these two patterns distinct so users can understand both item boundaries and group boundaries at a glance.
+
+## Variants
+
+- **Ghost (default):** Use when the surrounding surface already groups the list visually, e.g. in a card or modal
+- **Filled:** Use when list items need a distinct background to stand out from the surrounding surface
+- **Outline:** Use when placed within a grouping surface e.g. cards, but with stronger boundaries than the ghost variant provides
+
+Use one variant consistently within a list. When one item needs emphasis, use its content or status rather than mixing item variants.
+
+## Options
+
+### List item
+
+- **Checkbox:** Use a checkbox when users select items independently of activating the item.
+- **Icon:** Use a meaningful icon and provide a descriptive accessible name when the icon carries information.
+- **Label:** Keep the primary title short and specific so items remain easy to scan.
+- **Description:** Add supporting information only when it helps users identify or act on the item.
+- **Selected:** Use selected state when an item is currently chosen or active.
+- **Content:** Use the built-in icon, label and description properties for all common list item layouts. Alternatively, create your own custom layout, e.g. notifications or events.
+- **Action content:** Place controls that do not activate the item in the trailing action area. We recommend to use up to four icon buttons or up to two text buttons.
+
+### List
+
+- **Dividers:** Use dividers between direct list items, primarily with the ghost variant.
+- **Item gap:** Control the gap between items. We recommend `none` for a continuous list, `sm` (default) or `md` for light separation between items, or `lg` when groups need stronger visual distinction.
+- **Selection:** Allow selecting an item in the list.
+- **Action on hover:** Show supplementary actions only when the list item is hovered or focused to keep the list uncluttered. Use this approach only if they are also accessible elsewhere in the workflow, e.g. to enable shortcuts for actions available in a detail view.
+- **Action alignment:** Center-align actions vertically for single-line items. Top-align them (`start`) when descriptions or custom content create taller items.
+- **Reordering:** Enable dragging only when item order has meaning.
+  - **Dynamic behavior:** The drop target is indicated by the other items moving. Use for short lists or if users should only reorder items roughly, e.g. to quickly prioritize work items.
+  - **Separator behavior:** The drop target is indicated by a separator. Use for long, scrollable lists or where users need to place items between specific items, e.g. to define the exact position of work items in a queue.
+
+![List examples](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=8338-10306&t=wY8oAkKcZaMecojj-11)
+
+## Behavior in context
+
+- **Interaction:** The primary item surface supports activation with Enter or Space. Arrow keys move between enabled, visible items, while Home and End move to the first and last item.
+  - **Focus:** The list uses roving focus so only the active enabled item enters the tab sequence. Tab moves through available control groups and then out of the list. Arrow right enters the primary or action controls, while arrow left moves within the active control group.
+  - **Actions:** The action area can remain visible or appear on hover and focus according to the action visibility setting.
+  - **Reordering:** Start pointer dragging from the drag indicator. Disabled and hidden items cannot be reordered. For keyboard input, use Space or Enter to start, the arrow keys to move, Space or Enter to drop and Escape to cancel.
+- **Placement:** Keep the list within the layout container that gives it context, e.g. [cards](../card/), [modals](../modal/) or [panes](../panes/). Use a separate list when the purpose or item type changes. Separate list groups may sit side by side in a larger grid, but individual items remain vertically arranged.
+  - **Overflow:** List width fills its parent. Items grow with their content in height. Make scrolling discoverable with a scrollbar when the list has constrained height.
+  - **Loading more content:** Pagination and lazy loading are outside the component’s scope and need to be added by the application.
+
+## States
+
+List items have these states: Default, hover, active, focused, dragging and disabled.
+
+![List states](https://www.figma.com/design/wEptRgAezDU1z80Cn3eZ0o/iX-Documentation-illustrations?node-id=8309-32187)
+
+## Dos and Don’ts
+
+<div class="dos-and-donts">
+  <div class="dos">
+    <ul aria-label="Recommended practices">
+      <li>Do keep one consistent item type, alignment, and spacing model within a list</li>
+      <li>Do keep essential actions visible and keyboard accessible</li>
+      <li>Do provide an empty state or spinner when a list has no content or is loading</li>
+      <li>Do provide accessible names and logical reading order when using custom content</li>
+    </ul>
+  </div>
+  <div class="donts">
+    <ul aria-label="Practices to avoid">
+      <li>Don’t use lists for multi-column data comparison, sorting, filtering, or dense editing, use [grids](../grid) or [tables](../html-grid) instead</li>
+      <li>Don’t mix list item variants to highlight individual items</li>
+      <li>Don’t make pointer dragging the only way to reorder items on touch devices</li>
+    </ul>
+  </div>
+</div>
+
+## Related
+
+- [Grid](../grid)
+- [Tree](../tree)
+- [Event list](../event-list)
+- [Card list](../card-list)
+- [Group](../group)
+- [Tooltip](../tooltip)

docs/components/list/index.mdx

@@ -0,0 +1,5 @@
+---
+doc-type: 'tabs'
+description: 'Lists display collections of related items with flexible content and interactions.'
+title: 'List'
+---