UI Configuration

Potato provides extensive configuration options for customizing the user interface. These settings allow administrators to control the appearance, behavior, and functionality of the annotation interface.

Configuration Structure

All UI configuration options are defined in the ui section of your configuration file:

ui:
  # UI configuration options go here

Instance Height Control

Control the maximum height of the instance text display area to keep annotation options visible for long texts.

ui:
  max_instance_height: 300  # 300 pixels maximum height

Benefits:

• Long text instances no longer push annotation options out of view
• Annotation options remain in a predictable location
• Scrollable text area for long content

Label Colors

Configure custom colors for labels across all annotation types.

Global Label Colors

Define colors for labels across all schemas:

ui:
  label_colors:
    sentiment:
      positive: "#22C55E"      # Green
      negative: "#EF4444"      # Red
      neutral: "#9CA3AF"       # Gray
    emotion:
      happy: "rgba(34, 197, 94, 0.8)"
      sad: "rgba(59, 130, 246, 0.8)"

Inline Label Colors

Define colors directly on each label:

annotation_schemes:
  - annotation_type: radio
    name: sentiment
    labels:
      - name: positive
        color: "#22C55E"
        tooltip: "Positive sentiment"
      - name: negative
        color: "#EF4444"

Span-Specific Colors (Legacy)

The original span-only color configuration:

ui:
  spans:
    span_colors:
      sentiment:
        positive: "(220, 252, 231)"  # RGB format
        negative: "(254, 226, 226)"

Color Format Support

All color options support multiple formats:

• Hex: "#FF8000" or "#F80"
• RGB: "(255, 128, 0)" or "rgb(255, 128, 0)"
• RGBA: "rgba(255, 128, 0, 0.8)"
• Named: "red", "blue", "green"

Default Colors

If no custom color is specified, Potato assigns colors based on label names:

Interface Display Options

Control the visibility and functionality of interface elements:

ui:
  show_progress: true        # Show progress indicators
  show_instructions: true    # Show instruction panels
  allow_navigation: true     # Allow navigation between instances
  allow_editing: true        # Allow editing of annotations

Task Layout Customization

Potato automatically generates HTML layouts based on your configuration.

Auto-Generated Layouts

When you run Potato, it generates a layout file at:

{task_dir}/annotation_layouts/annotation_layout.html

This file is regenerated when your config changes.

Custom Task Layouts

For more control, provide a custom HTML file:

task_layout: "my_custom_layout.html"

Creating a Custom Layout:

1. Start from the generated layout as a template
2. Modify HTML, add custom elements
3. Reference your file in the config

For detailed guidance on creating sophisticated custom layouts with CSS grid, color-coded options, and section styling, see the Layout Customization guide.

Layout Structure Requirements

Custom layouts must include certain elements:

CSS Classes Reference

Form Structure:

• .annotation-form - Main form container
• .annotation-form-header - Header with name and AI buttons
• .annotation-form-body - Body with input options
• .annotation-name - Schema name display
• .annotation-desc - Description text

Input Options:

• .shadcn-radio-option - Radio button option
• .shadcn-checkbox-option - Checkbox option
• .shadcn-span-option - Span annotation option

Site Directory Configuration

Custom Templates

site_dir: "custom_templates"  # Use custom templates
# OR
site_dir: "default"           # Use built-in templates

Custom JavaScript

Inject custom JavaScript code:

customjs: "http://localhost:8080/custom.js"
customjs_hostname: "localhost:8080"

Complete Example

annotation_task_name: "UI Configuration Example"
 
# Annotation schemes with inline colors
annotation_schemes:
  - annotation_type: radio
    name: sentiment
    description: "What is the overall sentiment?"
    labels:
      - name: positive
        color: "#22C55E"
        tooltip: "Positive sentiment"
        key_value: p
      - name: negative
        color: "#EF4444"
        tooltip: "Negative sentiment"
        key_value: n
      - name: neutral
        color: "#9CA3AF"
        key_value: u
 
# UI Configuration
ui:
  max_instance_height: 400
 
  label_colors:
    sentiment:
      positive: "rgba(34, 197, 94, 0.8)"
      negative: "rgba(239, 68, 68, 0.8)"
      neutral: "rgba(156, 163, 175, 0.8)"
 
  show_progress: true
  show_instructions: true
  allow_navigation: true
  allow_editing: true
 
site_dir: "default"

Browser Compatibility

All UI configuration options work across modern browsers:

• Chrome/Edge: Full support with custom scrollbar styling
• Firefox: Full support with standard scrollbar
• Safari: Full support with standard scrollbar
• Mobile: Responsive design with touch-friendly interactions

Best Practices

1. Test Your Configuration: Always test UI changes with your specific data
2. Consider Accessibility: Ensure color choices provide sufficient contrast
3. Mobile Responsiveness: Test configurations on mobile devices
4. Performance: Large custom JavaScript files may impact loading times

Troubleshooting

Colors Not Appearing

Ensure RGB format uses parentheses and spaces: "(255, 128, 0)"

Height Limit Not Working

Check that max_instance_height is a positive integer.

Custom Templates Not Loading

Verify site_dir path exists and contains valid templates.

Further Reading

• Layout Customization - Custom HTML templates and CSS
• Instance Display - Configure content display
• Annotation Schemes - Schema configuration
• Productivity Features - Keyboard shortcuts and tooltips
• AI Support - AI assistant configuration

For implementation details, see the source documentation.