AI-Human Interaction (Pajamas Design System)

Source: GitLab Pajamas Design System (page last updated) · 2026-07-13

Design AI to be collaborative, not autonomous. AI should suggest and assist while users remain in control. Respect human judgment by ensuring AI acknowledges uncertainty and defers to user expertise when appropriate. Consider not just what the AI can do, but where and how users encounter AI assistance in their existing tasks. This includes direct conversation with agents, automated flows triggered by their actions, or contextual suggestions within their existing tasks.

Build trust gradually. Start with small helpful actions and expand capabilities as users gain confidence with the system. Use non-threatening visual language that makes AI agents and flows feel like supportive teammates rather than autonomous systems taking control. Consider if the problem could be addressed with pre-defined rules (if this, then that) before adding AI.

To understand the risk of an AI-powered feature, assess the probability of error and impact of that error, where impact is a comparison of potential cost and benefits. Costs can be financial, emotional, reputational, opportunity, time, compliance, or others.

In GitLab, an example of a low risk situation is an agent providing explanations about GitLab features or helping debug configuration issues. The potential cost is low, as the user typically reviews and validates information before acting on it.

An example of a medium risk situation is a flow that automatically assigns labels or milestones to work items based on content analysis. If incorrect, the cost is primarily time spent correcting the assignments.

An example of a high risk situation is a flow that automatically creates merge requests with security fixes. While this helps users resolve vulnerabilities faster, incorrect changes could introduce new security issues or break functionality. The potential cost increases in high-risk applications, such as critical infrastructure.

You must include a disclaimer to inform the user that the feature is powered by AI. This is a legal requirement in some regions and by certain third-party AI services.

Flag AI-generated content with the disclaimer <Verb> by AI. For example: Generated by AI or Summarized by AI.

Use clear, simple language to explain what the system is doing and how it arrived at its recommendations.

Provide natural language interaction options when appropriate and allow users to interact with AI conversationally when they prefer this method of communication.

Clearly distinguish between agents and flows and help users understand when they're engaging with conversational agents for iterative problem-solving versus automated flows that execute specific tasks.

GitLab's AI features are designed around collaborative decision-making, where AI suggests and assists while users maintain final authority over their work. AI acknowledges its limitations and defers to user expertise when appropriate. Users can interact conversationally with AI when they prefer natural language, and they have full control over their automated processes, such as viewing, pausing, canceling, or modifying running flows as needed.

When your system is not certain of the user's intent or has low confidence, make sure there is a path forward that does not rely on AI. Explain why the system was not able to provide a recommendation. Errors are also opportunities to learn more about your user's mental models and improve the system's ability to make recommendations. Consider designing a feedback mechanism that presents as a cue for adjustment rather than an error state.

When agents cannot understand requests or flows encounter errors, provide clear explanations and alternative paths forward. Agent conversations should gracefully handle misunderstandings, while flows should offer users the ability to retry, manually intervene, or fall back to manual processes.

GitLab AI features primarily use third-person voice following GitLab standards. For example, Use GitLab Duo to find vulnerabilities in your application, Ask Amazon Q to upgrade Java, or Troubleshoot your pipeline.

Exception for conversational agents: When users directly interact with any agent (GitLab Duo Chat, Amazon Q, or custom agents), the agent's responses use first person to maintain a natural conversational experience:

Interaction Type: How do users engage with AI assistance?

Agent Source: What type of AI system is providing assistance?

Interactivity: How does the system surface AI to engage with the user?