Observatory Design System

A React component library for Vizzly visual testing applications. Built with Tailwind CSS v4.

Installation

npm install @vizzly-testing/observatory

Requirements

• React 18+ or 19+
• Tailwind CSS v4+
• downshift (optional, for Combobox)

Quick Start

Import the styles in your main CSS file:

@import '@vizzly-testing/observatory/styles';

Import and use components:

import { Button, Card, CardHeader, CardBody, Alert } from '@vizzly-testing/observatory';

function App() {
  return (
    <Card variant="success">
      <CardHeader title="Welcome" />
      <CardBody>
        <Alert variant="info" title="Tip">
          Use Observatory components for consistent UI.
        </Alert>
        <Button variant="primary">Get Started</Button>
      </CardBody>
    </Card>
  );
}

Package Exports

// Main components
import { Button, Card, DataTable, ... } from '@vizzly-testing/observatory';

// Image viewer components (separate entry for tree-shaking)
import { ZoomControls, ZoomableImage, useZoom } from '@vizzly-testing/observatory/image-viewer';

// CSS variables and animations
import '@vizzly-testing/observatory/styles';

Components

Core UI

• Button - Action button with variants (primary, secondary, ghost, danger, warning, success)
• Card, CardHeader, CardBody, CardFooter - Content containers with accent borders
• Modal - Dialog overlay with escape key handling
• ConfirmationDialog - Specialized modal for dangerous actions
• Tabs - Tab navigation (default, pills, underline variants)
• Alert - Feedback banners (success, warning, danger, info)
• Toast, ToastContainer - Temporary notifications
• Badge - Status indicators with auto-detection
• Tooltip - Hover tooltips

Form Controls

• Input, Textarea, Select - Form inputs with labels, hints, and errors
• Checkbox, Toggle - Boolean inputs
• Combobox - Searchable dropdown (requires downshift)
• Dropdown - Generic dropdown menu
• SearchInput - Search field with icon and clear button

Data Display

• DataTable - Responsive table with mobile card layout, sorting, column management
• Table - Simple table component
• TableToolbar - Integrated toolbar with search and filters
• Avatar, AvatarGroup - User avatars with status indicators
• Timeline - Status timeline for processes
• HealthRing - Radial progress indicator
• Skeleton, SkeletonCard, SkeletonTable - Loading placeholders
• EmptyState - Empty state placeholder
• StatusDot - Small status indicators

Filters

• FilterPill, FilterPillGroup - Filter toggles
• ActiveFilterChip, ActiveFilterBar - Display active filters

Review Workflow

• ApprovalButton, ApprovalButtonGroup, MobileApprovalBar - Approve/reject buttons
• QueueItem - Review queue list item with status indicators
• InspectorPanel - Slide-out metadata panel
• ReviewModeProvider, useReviewMode - Keyboard-driven review context
• KeyboardHint, KeyboardBar - Keyboard shortcut hints
• ActionToast - Compact inline action feedback
• ViewModeToggle, ViewModeSelect - Comparison view mode selector

Variant Selection

• VariantStrip - Dimension-grouped variant selector
• VariantPills - Compact variant metadata display
• VariantBreadcrumb - Breadcrumb-style variant navigation
• BrowserIcon - Browser logo icons

Mobile & Layout

• MobileDrawer - Responsive drawer/sidebar (bottom sheet on mobile)
• DrawerHeader, DrawerContent, DrawerFooter - Drawer composition

Image Viewer

• ZoomableImage - Pan and zoom image viewer
• ZoomControls, useZoom - Zoom management with keyboard shortcuts
• SideBySideView - Two images side by side
• ThumbnailStrip - Horizontal thumbnail navigation

Utilities

• getScreenshotMetadata - Extract metadata from screenshot objects
• getViewportDisplay - Format viewport strings
• getUniquePropertyValues - Get unique values across screenshots

Design Tokens

CSS variables for theming (defined in styles.css):

:root {
  --vz-bg: #0f172a;
  --vz-surface: #1a2332;
  --vz-elevated: #1e293b;
  --vz-border: #374151;
  --vz-border-subtle: #2d3748;

  --accent-success: #10b981;
  --accent-warning: #f59e0b;
  --accent-danger: #ef4444;
  --accent-info: #3b82f6;

  --text-primary: #ffffff;
  --text-secondary: #9ca3af;
  --text-tertiary: #6b7280;
  --text-muted: #4b5563;
}

Documentation

See the docs folder for detailed component documentation:

• Core UI Components
• Form Controls
• Data Display
• Review Workflow
• Image Viewer
• Variant Selection

License

MIT