Once UI Design System

Once UI is an open-source design system designed for indie creators, small teams, and startups. It provides an opinionated set of accessible React components paired with a flexible token system. The system is built to enable rapid development from idea to polished product by focusing on:

• Compact, expressive syntax: Minimal markup with smart defaults.
• Design consistency: A token system for color, spacing, typography, and motion.
• Agent-first foundation: Designed to be easily read, reasoned about, and extended by AI tools.

The Input component provides a text entry field with floating labels, validation support, and customizable styling. It is suitable for collecting user input in forms and supports various configurations like prefixes, suffixes, and loading states.

<Input
    id="input-1"
    label="Email"
    prefix={
      <Icon marginLeft="4" onBackground="neutral-weak" name="email" size="xs" />
    }
/>

The Mask component creates a customizable radial mask effect over its children. It is useful for creating spotlight, reveal, or fading effects. You can position the mask using coordinates, control its size with a radius, and enable interactive cursor tracking.

<Mask
    fill
    height={24}
    x={50}
    y={0}
    radius={33}>
    <Media fill src="/image.jpg" />
</Mask>

The Skeleton component is used to display loading placeholders for content that hasn't yet loaded. It helps maintain layout consistency and improves perceived performance by providing a visual cue during data loading states.

<Skeleton shape="circle" size="l" />
<Skeleton shape="line" delay={100} width="50%" size="xs" />
<Skeleton shape="line" delay={200} width="75%" size="s" />
<Skeleton shape="block" delay={300} minHeight="80" />

The DateRangeInput component includes the following capabilities:

• Dual Input Fields: Separate fields for start and end dates.
• Calendar Interface: A visual calendar for intuitive date range selection.
• Formatted Display: Automatically displays selected dates in a readable format.
• Custom Labels: Configurable labels for start and end date fields via startLabel and endLabel.
• Dropdown Integration: Uses DropdownWrapper for a clean UI experience.

The Line component is used to create horizontal or vertical divider lines with consistent styling. It is primarily used to visually separate content sections within an application.

<Column gap="24" fillWidth horizontal="center">
    <Line />
    <Text>Content between lines</Text>
    <Line />
</Column>

The DateRangePicker includes several built-in features:

• Dual calendar display: Option to show two months side by side.
• Range highlighting: Visual indication of the selected date range.
• Flexible sizing: Supports small, medium, and large size variants.
• Standalone component: Operates independently without requiring input fields.
• Customizable: Supports custom styling via className and style props.

The useResponsiveClasses hook is an internal utility used by Flex and Grid components to manage responsive CSS classes based on breakpoints. It monitors window resize events, compares the current width against defined breakpoints, and dynamically applies or removes CSS classes to ensure the layout matches the current viewport size.

Important: This is an internal hook. You should not use this hook directly in your application. Instead, use the Flex and Grid components with responsive props (e.g., m={{ direction: 'column' }}) to achieve responsive behavior.

// Instead of using the hook, use Flex with responsive props:
<Flex direction="row" m={{ direction: 'column' }}>
  {/* Hook applies 'flex-column' on medium screens */}
  {/* Hook applies 'flex-row' on large+ screens */}
</Flex>

By default, CelebrationFx automatically detects the prefers-reduced-motion system setting and low-end devices to disable animations for performance and accessibility.

To override this behavior, use the reducedMotion prop. Setting it to "auto" (the default) follows the user's system settings.

All chart components in the system share a common set of props defined by ChartProps. This allows for easy swapping between different chart types (e.g., BarChart, LineChart, PieChart) with minimal code changes.

Key shared props include:

• series: Defines which keys in data to plot and optional colors.
• data: The array of data rows.
• title: Heading above the chart.
• description: Supporting line under the title.
• date: Configuration for time axes and date pickers.
• legend: Controls legend position and visibility.
• axis: Controls visibility of x and y axes.
• loading: Renders a loading state.
• error: Renders an error state.
• emptyState: Content to show when data is empty.
• errorState: Content to show when error is set.