Design System

Primary Button

Use for the main action on a page. There should only be one primary button per section.

Secondary Button

Use for secondary actions that support the primary action.

Destructive Button

Use for destructive actions like delete or remove. Always confirm before executing.

Button Sizes

Buttons come in different sizes to fit various contexts and layouts.

Buttons with Icons

Add icons to provide visual context and improve scannability.

When to use

• To trigger an action or navigate to a new page
• When the action is a primary goal of the user
• In forms to submit or reset data

Best practices

• Use clear, action-oriented labels (e.g., "Save changes" not "Submit")
• Place primary buttons on the right in forms
• Limit primary buttons to one per section
• Always confirm destructive actions

Text Input

Standard text input field for single-line text entry.

Input Validation States

Show validation feedback with visual indicators and error messages.

Textarea

Multi-line text input for longer content like comments or descriptions.

Textarea Validation

Textarea with validation states and feedback.

Label

Labels provide accessible names for form controls. Always associate labels with inputs.

Accessibility

• Always use labels with form controls and associate them with htmlFor/id
• Provide clear error messages that explain how to fix issues
• Use appropriate input types (email, tel, url, etc.) for better mobile keyboards
• Include helper text for complex requirements or formatting

Validation

• Validate on blur to provide immediate feedback without being intrusive
• Use clear visual indicators (color, icons) for validation states
• Show success states sparingly - absence of errors is usually sufficient
• Disable submit buttons until required fields are valid

User Experience

• Keep forms as short as possible - only ask for necessary information
• Group related fields together with clear section headings
• Use placeholder text as examples, not as labels
• Maintain focus state visibility for keyboard navigation

Select Dropdown

Standard dropdown for selecting a single option from a list.

Select with Default Value

Set a default selected option using defaultValue.

Disabled Select

Disable the select when it should not be interactive.

Combobox

Searchable dropdown that combines an input with a dropdown list. Ideal for large lists with filtering.

Switch Toggle

Binary toggle for on/off states. Commonly used in settings and preferences.

Disabled Switch

Disable switches when they should not be interactive.

Switch in Settings

Real-world example of using switches in a settings panel.

Checkbox

Checkboxes allow users to select multiple options from a list.

Radio Group

Radio buttons allow users to select a single option from a list.

Slider

Sliders allow users to select a numeric value within a range.

Select Dropdown

• Use for lists with 5+ options where space is limited
• Always include clear placeholder text
• Group related options using SelectGroup when appropriate
• Consider using radio buttons for 2-4 options instead

Combobox

• Use for large lists (10+ items) that benefit from search/filtering
• Perfect for country selectors, city pickers, or tag selection
• Provides better UX than Select for long lists
• Ensure the search is performant and filters as user types

Checkbox

• Use for multiple selections where users can pick zero or more options
• Always pair with a descriptive label using htmlFor
• Group related checkboxes together visually
• Use for accepting terms, enabling features, or filtering content

Radio Group

• Use for single choice selections with 2-4 visible options
• Always have one option selected (use defaultValue)
• Best for mutually exclusive options like plan selection or preferences
• For 5+ options, consider using a Select dropdown instead

Switch Toggle

• Use for binary on/off settings that take effect immediately
• Always pair with a descriptive label
• Consider adding helper text for complex settings
• Group related switches together in settings panels

Slider

• Use for selecting numeric values within a defined range
• Display the current value in the label for clarity
• Set appropriate min, max, and step values
• Use range sliders for selecting a range (e.g., price filters)

Design System Consistency

• All components use focus-visible for keyboard navigation focus rings
• Consistent disabled state: opacity-70, gray background, gray border
• Ceibo brand colors for active/checked states
• All components follow the same 2px border and border radius standards

Accessibility

• Always use Label components with htmlFor attribute
• Provide clear feedback for disabled states
• Ensure keyboard navigation works properly (Tab, Space, Arrow keys)
• Use aria-label for components without visible labels
• Group related options with fieldset and legend when appropriate

Date Picker

Select a single date from a calendar. Opens in a popover for clean UI integration.

Date Range Picker

Select a date range with start and end dates. Perfect for booking flows, filtering, and scheduling.

Date Picker with Presets

Quick date selection with preset options like Today, Tomorrow, and Next Week. Improves UX for common date choices.

Disabled Date Pickers

Examples of disabled date pickers and date validation patterns.

When to Use

• Booking dates for reservations, appointments, or travel
• Scheduling events or setting deadlines
• Filtering data by date or date range
• Date-based form inputs (birth date, expiration date, etc.)
• Any scenario where visual calendar selection improves UX

Accessibility

• Always pair date pickers with descriptive labels using htmlFor
• Keyboard navigation: Tab to focus, Space/Enter to open, Arrow keys to navigate dates
• Screen readers announce selected dates and disabled states
• Focus is automatically moved to calendar when opened (initialFocus)
• Popover can be closed with Escape key

Date Validation

• Use disablePastDates for future-only selections (bookings, deadlines)
• Use disabledDates function for custom logic (weekends, holidays, blackout dates)
• Combine multiple validation rules for complex scenarios
• Provide clear error messages when date selection fails validation
• Consider min/max date ranges for constrained selections

Formatting & Display

• Display format: PPP ("April 29, 2023") for user-friendly reading
• API format: Use yyyy-MM-dd for backend communication
• Consider locale-specific formats for international users
• Show placeholder text when no date is selected
• For ranges, display both dates with clear separator (dash or "to")

UX Patterns

• Auto-close: Single picker closes on selection, range picker on both dates selected
• Presets: Offer common selections (Today, Tomorrow, This Week) for faster input
• Visual feedback: Today is highlighted in light sage, selected in full sage
• Range selection: Show visual connection between start and end dates
• Keep popover aligned with trigger button (align="start")

Component Variants

• DatePicker: Use for single date selection (appointments, deadlines)
• DateRangePicker: Use for start/end date pairs (bookings, reports, filters)
• DatePickerWithPresets: Use when common dates are frequently selected
• Choose the variant that best matches your user's mental model

Design System Consistency

• Matches input height (h-10) and border style (2px ceibo-sage) across forms
• Uses Ceibo brand colors for selected states (ceibo-sage)
• Consistent focus ring styling with other form components
• Disabled state follows system-wide opacity and cursor patterns

Badge

Small labels for displaying status, categories, or counts. Available in multiple variants for different meanings.

Badge Usage Examples

Common patterns for using badges in real-world scenarios.

Alert Component

Call attention to important information with contextual feedback messages. Always include an icon and descriptive title.

Card Component

Flexible container for grouping related content and actions together.

Card with Footer Actions

Add a footer to cards when action buttons are needed.

Table Component

Display data in rows and columns. Use for structured data like user lists, reports, or dashboards.

Badges

• Use semantic variants (success, warning, destructive) for status indicators
• Keep badge text short - 1-2 words maximum
• Use outline variant for category tags that don't need emphasis
• Place badges next to the content they describe, not floating alone

Alerts

• Always include both a title and description for clarity
• Use appropriate icons that match the alert variant
• Reserve destructive alerts for actual errors, not warnings
• Consider dismissible alerts for non-critical information

Cards

• Use cards to group related content and create visual hierarchy
• Keep card titles concise and descriptive
• Place primary actions in the footer, secondary in the header
• Maintain consistent card sizing within the same view

Tables

• Always include clear column headers
• Right-align numeric data and actions columns
• Use font-medium for the primary identifier column
• Consider pagination for tables with more than 10-15 rows
• Make row actions consistent across all rows

Tabs

Organize content into tabbed sections. Perfect for settings panels, dashboards, and multi-step forms.

Pagination

Navigate through multiple pages of content. Essential for tables, lists, and search results.

Pagination with Ellipsis

For larger page counts, use ellipsis to condense pagination controls while showing first, last, and nearby pages.

Tabs

• Use tabs for content that can be organized into distinct categories
• Keep tab labels short and descriptive (1-2 words)
• Limit tabs to 4-6 options to avoid overcrowding
• Always set a default tab with defaultValue
• Tabs should be mutually exclusive - only one active at a time

Pagination

• Show pagination when content exceeds 10-20 items
• Always include Previous/Next buttons for easy navigation
• Highlight the current page clearly with isActive
• Use ellipsis for 7+ pages to keep the UI clean
• Consider showing total page count (e.g., "Page 2 of 10")

Accessibility

• Tabs must be keyboard navigable (arrow keys)
• Pagination links should have descriptive aria-labels
• Indicate current/active states clearly for screen readers
• Disable Previous on first page and Next on last page

Dialog

Modal windows that interrupt the user workflow for important information or forms. Requires explicit user action to dismiss.

Alert Dialog

Critical confirmation dialogs for destructive or irreversible actions. Use for deletions, data loss warnings, or major changes.

Sheet (Side Panel)

Slide-in panels from the edges of the screen. Perfect for navigation menus, settings panels, or supplementary content.

Popover

Contextual overlays that appear near their trigger element. Use for date pickers, color pickers, or additional options that don't need full modal focus.

Dropdown Menu

Contextual menus with lists of actions or navigation options. Perfect for user menus, table row actions, or contextual operations.

Dialog vs Alert Dialog

• Dialog: General purpose modals for forms, content, confirmations
• Alert Dialog: Critical confirmations for destructive actions only
• Always provide clear Cancel and Confirm actions in Alert Dialogs
• Use Alert Dialogs sparingly - only for truly important decisions

Sheet (Side Panel)

• Use right sheets for settings, edit forms, and detailed information
• Use left sheets for navigation menus and primary navigation
• Use top/bottom sheets for mobile-friendly interfaces
• Include a clear close button or allow backdrop click to dismiss
• Keep sheet content focused - don't overload with too much information

Popover

• Use for lightweight, non-critical content and quick actions
• Position popovers near their trigger element for context
• Keep popover content concise - no more than 2-3 form fields
• Auto-dismiss when clicking outside or pressing Escape
• Don't nest popovers within other popovers

Dropdown Menu

• Use for contextual actions and navigation options
• Group related items with separators
• Limit menu items to 7-10 options for usability
• Use clear, action-oriented labels (verbs)
• Place destructive actions at the bottom, separated
• Add icons to improve scannability and recognition

Accessibility

• All overlays must be keyboard accessible (Tab, Enter, Escape)
• Focus should trap inside modals (Dialog, Alert Dialog)
• Provide clear focus indicators for all interactive elements
• Use proper ARIA attributes (handled by components)
• Ensure sufficient color contrast for all text

Toast Notifications

Brief, non-intrusive messages that appear temporarily to provide feedback about operations. Auto-dismiss after a few seconds.

Tooltip

Contextual information that appears on hover or focus. Perfect for explaining icons, providing additional details, or clarifying actions.

Progress Bar

Visual indicator showing task completion percentage. Use for file uploads, form submissions, or any determinate loading state.

Skeleton Loaders

Placeholder components that mimic the layout of content while it loads. Better UX than spinners for known layouts.

Separator

Visual divider for organizing content into distinct sections. Use horizontal separators between content blocks.

Toast Notifications

• Use for confirming actions (save, delete, update)
• Keep messages brief and actionable (max 2 lines)
• Auto-dismiss success toasts after 3-5 seconds
• Keep error toasts visible until user dismisses
• Don't use toasts for critical information

Tooltips

• Keep tooltip text concise (1-2 short sentences)
• Use for explaining icons, abbreviations, or disabled states
• Always wrap app with TooltipProvider
• Don't put critical information in tooltips
• Ensure tooltips are accessible via keyboard (focus state)

Progress Bars

• Use for operations with known duration or progress
• Always show percentage or status text with the bar
• Update progress smoothly, not in large jumps
• Consider indeterminate loading for unknown durations

Skeleton Loaders

• Use for initial content loading, not user actions
• Match skeleton shape to actual content layout
• Prefer skeletons over spinners for better perceived performance
• Show skeletons immediately, don't delay

Loading Sizes

Choose a size based on the context - small for inline loading, default for content areas, large for full-page loading.

Color Variants

Different color variants to match your UI theme or background. Use white variant on dark backgrounds.

Loading in Buttons

Show loading state in buttons during async operations like form submissions or API calls.

Full Page Loading

Use large loading indicator centered on the page for initial page loads or major content changes.

When to Use

• Initial page or component loading
• Async operations like form submissions or data fetching
• File uploads or downloads in progress
• Content that takes more than 300ms to load

Choosing Size

• Small: Inline loading, buttons, small components
• Default: Cards, lists, content areas
• Large: Full page loading, major content sections

Best Practices

• Always show loading states for operations taking longer than 300ms
• Pair with descriptive text ("Loading...", "Saving...")
• Disable interactive elements while loading to prevent double-submissions
• Use skeleton loaders for complex layouts instead of spinners
• Consider progress bars for operations with known duration
• Match loading indicator color to your UI theme

Info Notification

Use for general information and neutral messages that don't require urgent action.

Success Notification

Display successful operations like saved changes, completed actions, or confirmed submissions.

Warning Notification

Alert users to potential issues or actions that need attention, but aren't critical errors.

Error Notification

Show critical errors that require immediate attention or prevent the user from continuing.

All Notification Variants

Overview of all notification types. Choose the appropriate variant based on message severity and context.

When to Use

• Form submission results (success or error)
• System status updates and announcements
• Background task completion notifications
• Session warnings or connection issues

Choosing the Right Variant

• Info: Neutral messages, feature announcements, tips
• Success: Completed actions, saved changes, confirmed submissions
• Warning: Attention needed, non-critical issues, quota warnings
• Error: Failed operations, validation errors, connection problems

Best Practices

• Keep titles short and descriptive (2-4 words)
• Provide actionable descriptions with clear next steps
• Always make notifications dismissible with onClose
• Don't show multiple notifications of the same type simultaneously
• Consider auto-dismissing success notifications after 3-5 seconds
• Keep error and warning notifications visible until user dismisses them