AI Component Specific Rules

This library is focused on AI chat interfaces. All components should be designed with AI use cases in mind.

Spartan UI Components (Preferred)

IMPORTANT: When building UI for this project, prefer using Spartan UI components from @angular-ai-kit/spartan-ui/*.

Spartan UI provides accessible, well-designed primitives that integrate seamlessly with our Tailwind-based styling system.

Available Spartan UI Libraries

Usage Pattern

import { HlmButton } from '@angular-ai-kit/spartan-ui/button';
import { HlmButtonGroupImports } from '@angular-ai-kit/spartan-ui/button-group';
import { HlmIcon } from '@angular-ai-kit/spartan-ui/icon';
import { HlmInputGroupImports } from '@angular-ai-kit/spartan-ui/input-group';

@Component({
  selector: 'ai-chat-input',
  imports: [HlmButtonGroupImports, HlmInputGroupImports, HlmButton, HlmIcon],
  template: `
    <div hlmInputGroup>
      <textarea
        hlmInputGroupTextarea
        placeholder="Send a message..."
      ></textarea>
      <div hlmInputGroupAddon align="inline-end">
        <button hlmInputGroupButton size="icon-sm">
          <ng-icon hlm name="lucideArrowUp" size="sm" />
        </button>
      </div>
    </div>
  `,
})
export class ChatInputComponent {}

When to Use Spartan UI

• •Form inputs (use hlmInput, hlmInputGroup, hlmField)
• •Buttons and actions (use hlmBtn, hlmButtonGroup)
• •Dropdowns and menus (use hlmDropdownMenu, hlmPopover)
• •Avatars (use hlmAvatar)
• •Badges and labels (use hlmBadge)
• •Loading states (use hlmSpinner)
• •Empty states (use hlmEmpty)
• •List items (use hlmItem)

When to Build Custom

• •Spartan doesn't have an equivalent component
• •Need highly specialized AI-specific behavior
• •Performance-critical streaming components

Chat Components

Message Styling

User Messages:

• •Display in a card/bubble with background styling
• •Align to the right side
• •Include edit and copy functionality

AI/Assistant Responses:

• •Display as plain text (no card or wrapper)
• •Align to the left side
• •Support markdown rendering with syntax highlighting
• •Include action buttons: copy, regenerate, thumbs up/down

Message Bubbles (User)

• •Display with card styling (bg-card, border, rounded corners)
• •Include copy and edit functionality
• •Show timestamps (optional, configurable)

AI Response

• •Plain text display - no card, border, or wrapper styling
• •Full markdown support (GFM)
• •Code blocks with syntax highlighting and copy buttons
• •Support streaming text display with typing cursor
• •Action buttons appear on hover

Message Lists

• •Auto-scroll to latest message
• •Support virtual scrolling for long conversations
• •Group messages by date/time
• •Handle loading states between messages

Chat Containers

• •Manage conversation state
• •Handle message submission
• •Support regeneration of responses
• •Provide clear error states

Input Components

Message Input

• •Support keyboard shortcuts:
  • •Enter to submit
  • •Shift+Enter for new line
  • •Escape to clear/cancel
• •Include loading/disabled states during AI response
• •Auto-resize textarea as content grows
• •Character/token count display (optional)
• •Validate inputs when appropriate
• •Provide clear visual feedback

Prompt Suggestions

• •Display suggested prompts/starters
• •Handle click to populate input
• •Support customizable suggestions

Display Components

Markdown Rendering

• •Support full markdown syntax
• •Code blocks with syntax highlighting
• •Copy-to-clipboard for code blocks
• •Handle long content (scrolling, truncation)
• •Support tables, lists, blockquotes

Code Blocks

• •Syntax highlighting for common languages
• •Language label display
• •Copy button
• •Line numbers (optional)
• •Word wrap handling

Streaming Text

• •Character-by-character or word-by-word reveal
• •Cursor/caret animation
• •Smooth transitions
• •Pause/resume capability

Control Components

Action Buttons

• •Copy message content
• •Regenerate response
• •Edit message
• •Delete message
• •Thumbs up/down feedback

State Indicators

• •Loading spinners
• •Typing indicators
• •Connection status
• •Error states with retry options

Common Patterns

Loading States

// Always provide loading feedback
@if (isLoading()) {
  <ai-typing-indicator />
} @else {
  <ai-message-content [content]="message().content" />
}

Error Handling

// Graceful error states with retry
@if (error()) {
  <ai-error-message
    [error]="error()"
    (retry)="handleRetry()"
  />
}

Empty States

// Welcoming empty state with suggestions
@if (messages().length === 0) {
  <ai-empty-state
    [suggestions]="promptSuggestions"
    (selectPrompt)="handlePromptSelect($event)"
  />
}

Streaming Support

// Support for streaming responses
message = input.required<ChatMessage>();
isStreaming = input(false);

// Show cursor while streaming
@if (isStreaming()) {
  <span class="typing-cursor">cursor</span>
}

Accessibility for AI Components

Screen Reader Announcements

• •Announce new messages with aria-live
• •Announce loading/streaming states
• •Announce errors clearly

Keyboard Navigation

• •Navigate between messages with arrow keys
• •Focus management when new messages arrive
• •Escape to cancel ongoing operations

Visual Indicators

• •Clear distinction between user/assistant messages
• •Loading states visible to all users
• •Error states with clear instructions

Performance Considerations

Message Lists

• •Virtual scrolling for 100+ messages
• •Lazy load older messages
• •Debounce scroll events
• •Efficient re-renders with trackBy

Streaming

• •Batch DOM updates during streaming
• •Use requestAnimationFrame for smooth animations
• •Avoid layout thrashing

Memory Management

• •Clean up subscriptions on destroy
• •Limit stored message history
• •Clear streaming buffers when complete