@sylonik/macos-ui

Authentic macOS-style React components built with TypeScript, Tailwind CSS, and love.

A collection of beautiful, accessible macOS-style React components. Copy-paste them into your project, customize freely, and own the source code. Inspired by shadcn/ui.

Features

✨ Pixel-Perfect macOS Design - Faithfully recreated components including Window, Dock, MenuBar, and DesktopIcon with authentic styling and animations.

📋 Copy & Paste - Install individual components into your project using the CLI. Own the code, customize freely, no dependency lock-in.

🎨 TypeScript First - Built with TypeScript in strict mode. Full type safety with exported interfaces for all component props and configurations.

🎨 Themeable - Comprehensive theming system using CSS custom properties and a Tailwind CSS preset. Light and dark mode out of the box.

♿ Accessible - WCAG 2.1 AA compliant with proper ARIA attributes, keyboard navigation, and focus management.

🧪 Thoroughly Tested - 76+ tests including unit, property-based (fast-check), and E2E (Playwright) with 80% code coverage.

Quick Start

Installation

Initialize your project and add components:

# Initialize the project
npx macos-ui init

# Add individual components
npx macos-ui add window dock menu-bar desktop-icon

# Or add all components at once
npx macos-ui add --all

Basic Usage

import { Window, WindowManagerProvider, useWindowManager } from '@sylonik/macos-ui'
import { Home } from 'lucide-react'

function App() {
  return (
    <WindowManagerProvider>
      <Desktop />
    </WindowManagerProvider>
  )
}

function Desktop() {
  const { openWindow } = useWindowManager()

  return (
    <button onClick={() => openWindow({
      id: 'home',
      title: 'Welcome',
      icon: Home,
      content: 'Hello, macOS!'
    })}>
      Open Window
    </button>
  )
}

Components

Window

Draggable, resizable windows with macOS-style traffic light buttons (close, minimize, maximize).

Features:

• Customizable size and position
• Resizable with corner handle
• Draggable title bar
• Traffic light buttons with callbacks
• Focus management and z-index ordering
• Keyboard accessibility (Tab, Escape)

Dock

Application launcher bar with magnification effect, badges, and running indicators.

Features:

• Three positioning options (bottom, left, right)
• Smooth magnification on hover
• Running indicator dots
• Notification badges
• Icon labels on hover
• Accessible with aria-labels

MenuBar

System-level navigation bar with dropdown menus, keyboard navigation, and customizable status area.

Features:

• Dropdown menus with hover/click
• Nested submenu support
• Keyboard navigation (Arrow keys, Escape)
• Divider and disabled items
• Custom status area (right side)
• Focus management

DesktopIcon

Clickable desktop application icons with selection states and keyboard support.

Features:

• Single and double-click handlers
• Selected state styling with ring
• Customizable colors
• Icon + label layout
• Keyboard support (Enter, Space)
• Accessible button behavior

Documentation

Full documentation is available at sylonik.github.io/macos-ui

• Getting Started
• Installation Guide
• Component API
• Theming Guide
• Accessibility
• CLI Usage

CLI Commands

# Initialize project with configuration and theme
npx macos-ui init

# Add specific components
npx macos-ui add window dock

# Add all components
npx macos-ui add --all

# Options
npx macos-ui add window --overwrite  # Overwrite existing components
npx macos-ui add window --path src/ui  # Custom destination path
npx macos-ui init --yes  # Skip prompts, use defaults

Copy & Paste Philosophy

Unlike traditional npm packages, @sylonik/macos-ui uses a copy-paste model:

✅ Own the Code - Copy components directly into your project
✅ Full Control - Modify styling, props, and behavior freely
✅ No Lock-In - Zero runtime dependencies (except React, Tailwind)
✅ Smaller Bundles - Only ship what you use

This approach is inspired by shadcn/ui and prioritizes developer freedom over convenience.

Theming

Components use CSS custom properties for theming. Customize colors, spacing, shadows, and more:

:root {
  --macos-background: hsl(0, 0%, 100%);
  --macos-foreground: hsl(0, 0%, 0%);
  --macos-primary: hsl(221, 100%, 50%);
  /* ... and more */
}

@media (prefers-color-scheme: dark) {
  :root {
    --macos-background: hsl(0, 0%, 7%);
    --macos-foreground: hsl(0, 0%, 100%);
  }
}

Use the Tailwind preset for utility classes:

import { cn } from '@sylonik/macos-ui'

<div className={cn('bg-macos-background', 'text-macos-foreground')}>
  Content
</div>

TypeScript Support

Full TypeScript support with strict mode enabled:

import type {
  WindowProps,
  DockProps,
  MenuBarProps,
  DesktopIconProps,
} from '@sylonik/macos-ui'

Accessibility

All components are built with accessibility in mind:

• WCAG 2.1 AA compliant
• Keyboard Navigation - Full keyboard support for all components
• ARIA Attributes - Proper roles, labels, and live regions
• Focus Management - Visible focus indicators and focus trapping where needed
• Screen Readers - Tested with VoiceOver, NVDA, and Jaws

Learn more in the Accessibility Guide.

Contributing

We love contributions! Please see CONTRIBUTING.md for guidelines on:

• Setting up development environment
• Creating new components
• Writing tests
• Submitting pull requests

License

MIT License - see LICENSE for details.

Security

Please report security vulnerabilities responsibly. See SECURITY.md for details.

Community

• GitHub Discussions - Ask questions and share ideas
• GitHub Issues - Report bugs and request features
• Twitter - Follow for updates

Changelog

See CHANGELOG.md for version history and release notes.

---

Built with ❤️ by Sylonik