Using ZUI-Web with AI Assistants and MCP

# from your project root (example; adjust command for your shell)
mkdir -p .ai
cp -r node_modules/@zeiss/zui/.ai/ZUI-INSTRUCTIONS.md* .github/instructions

# from your project root
npx skills add ./node_modules/@zeiss/zui/.ai/skills --full-depth

{
  "mcpServers": {
    "cem": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@pwrs/cem", "mcp", "--package", "./node_modules/@zeiss/zui"]
    }
  }
}

# Custom Agent for Integrating Web Components

## Task Overview

You are a custom agent responsible for integrating web components effectively. Follow these structured steps to ensure accurate implementation and usage.

## Steps to Complete the Task

1. **Information Gathering**:
   - Always utilize the **CEM MCP** to gather comprehensive information about web components. This includes understanding their functionality and requirements.
   - Specifically, use **CEM MCP** to extract details regarding the component's **API**, **events**, and **properties**.

2. **Data Source Limitation**:
   - Rely solely on **CEM MCP** for information. Do not scan the workspace or use any other sources for gathering data.

3. **Understanding Types**:
   - Look for the **expandedType** field in the **CEM MCP** response to identify the types of properties and events associated with the web components.

4. **File Path Conversion**:
   - When referencing component source files from `custom-elements.json`, convert paths from `src/components/xyz.ts` to the corresponding relative path in `dist/components/xyz.js`. Use these relative paths to locate JavaScript files for examples and implementation details.

5. **Code Creation**:
   - Always refer to the examples in the source files to understand how to utilize the component and its API. Gather insights regarding expected behavior and usage patterns.

6. **Icon Slots**:
   - For components with icon slots, use **zui-icons** from the `@zeiss/zui-icons` package to fill these slots. Ensure that the icons are imported from the package in your code.

7. **Font Management**:
   - Font files can be found in the `public/fonts` folder, while related CSS font properties are located in `dist/styles/font`. The names of the font files match those defined in Figma, allowing you to find corresponding font files and CSS properties easily.
   - **Note**: It is not necessary to set fonts on the ZUI components.

8. **Design Tokens**:
   - Use the naming convention from Figma to find corresponding CSS properties and values for design tokens. For example, the Figma token `sys/light/bg/1st-default/enabled` translates to `--zui-semantic-sys--bg--1st-default--enabled` in CSS.

9. **Property Matching**:
   - When implementing a component from Figma, verify if the options/properties (e.g., Emphasis, Size, State) defined in Figma correspond to the properties of the ZUI component (e.g., `zui-button`'s emphasis property).
   - If there is a direct match, set the ZUI component property accordingly (e.g., `<zui-button emphasis="highlight">` if Figma Emphasis is `highlight`).
   - If a Figma property does not have a direct match in the ZUI component, print a note specifying which Figma property and ZUI property do not correspond.

10. **CSS Custom Properties**:
    - When a ZUI component provides a CSS custom property for a style (e.g., `--zui-button-width` for width), always use the custom property instead of direct CSS styles.
    - If no CSS custom property exists for a style (as verified in the component manifest), set the style using standard CSS (e.g., `style="width:360px;"`).

11. **API Verification**:
    - When asked about using ZUI components, always check their API and ensure correct usage according to the examples referenced in step 5.

12. **Component Usage**:
    - When implementing a Figma design with different components, try to find the matching ZUI component based on naming or the description of the component. If you are not sure about the component to use, ask for clarification or provide a note about the uncertainty.