Skip to main content

Layout

Our layout system ensures consistency, clarity, and usability across all interfaces. These guidelines establish standardized patterns for organizing content and interface elements.

Form​

Forms are fundamental building blocks of our application. They should be clear, efficient, and follow consistent patterns to reduce cognitive load and improve user experience.

Design Principles​

  • Predictable structure: Consistent vertical hierarchy helps users scan and complete forms efficiently
  • Clear communication: Every element serves a purpose in guiding users toward successful completion
  • Minimal cognitive load: Use established patterns and clear visual hierarchy
  • Accessible by default: Follow semantic HTML and proper labeling conventions

Vertical Layout Guidelines​

All form elements follow a consistent top-to-bottom hierarchy:

Label → Description → Input → Validation/Hint

This predictable order allows users to quickly understand what information is needed and how to provide it correctly.

Spacing Guidelines​

Use consistent spacing to create clear relationships between form elements:

  • 4px gap (gap-y-1) between all adjacent form elements:
    • Label to Description
    • Description to Input
    • Input to Validation/Hint

This tight, consistent spacing groups related elements while maintaining clear separation between form fields.

Typography Guidelines​

Follow our established typography system for form elements:

Label​

  • Style: Body emphasized (text-xs font-semibold text-emphasis)
  • Purpose: Clearly identify what information is required
  • Example: "Job name:", "Resource type:", "Environment variables:"

Description​

  • Style: Body (text-xs font-normal text-secondary)
  • Purpose: Provide additional context or instructions
  • Example: "Choose a descriptive name for your automation job"

Validation/Hint​

  • Style: Caption (text-2xs font-normal text-hint)
  • Purpose: Guide users with requirements or feedback
  • Example: "Required field", "Must be at least 8 characters", "Optional field"

Writing Guidelines​

Descriptions​

  • Keep descriptions concise and actionable
  • Focus on the outcome or benefit, not the technical process
  • Use sentence case and avoid unnecessary punctuation
  • Example: ✅ "Choose the Python version for your script execution" vs ❌ "This dropdown allows you to select which Python version will be used when executing your script."

Helper Text and Hints​

  • Be specific about requirements upfront
  • Use positive language when possible
  • Provide examples for complex inputs
  • Example: ✅ "Use lowercase letters, numbers, and hyphens only" vs ❌ "Invalid characters not allowed"

Tooltip Usage​

Use tooltips sparingly for additional context that would otherwise clutter the interface:

  • Complex terminology or concepts that need definition
  • Background information that helps with decision-making
  • Links to relevant documentation or resources

Don't use tooltips for:

  • Essential information needed to complete the form
  • Error messages or validation feedback
  • Basic instructions that should be in the description

Visual Example​

Form layout pattern showing proper hierarchy and spacing - Light theme

Implementation Notes​

  • Always include proper semantic HTML (<label>, <input>, etc.)
  • Associate labels with inputs using for attributes or wrapping
  • Maintain consistent spacing using Tailwind's gap-y-1 utility
  • Test form layouts across different viewport sizes
  • Ensure sufficient color contrast for all text elements