Introduction

macbetter brings macOS, iPadOS and iOS to the web as one set of React components. It follows Apple's Human Interface Guidelines and takes on your brand through a short list of seed tokens.

The settings above are three macbetter components on plain markup. Switch the platform in the preview's toolbar: text, control heights, row heights and corner shapes change to match each platform, and nothing in the code changes.

Three ideas

One framework for three platforms

Every component reads its metrics from tokens that change with the data-platform attribute. macOS is dense and pointer-first: 13px text, 28px controls, hover states. iOS is touch-first: 17px text, 44px touch targets, capsule controls, no hover. iPadOS uses iOS metrics with slightly shorter controls. The attribute sits on <html> and can be nested, so a phone preview can live inside a Mac page. Platforms explains how it resolves.

A short list of seeds re-skins everything

A theme sets the brand's accent, its ink and background colors, a gray to tint fills with, a radius scale and fonts. Labels, fills, separators, materials, shadows and every component state are derived from those seeds with color-mix() and relative color syntax, so a new brand stays consistent with the HIG's color roles. Colors are written with light-dark(), so each theme covers light and dark mode at once. Theming lists every seed.

Behavior comes from ui-sdk

macbetter doesn't implement keyboard handling, focus management or ARIA. Each component wraps a part from ui-sdk, which owns those behaviors along with right-to-left support and server rendering. macbetter adds classes, a few data-* variants and the CSS. Because the components are ui-sdk components, an agent connected through ui-sdk's agent bridge can read their state and call their actions by name. Built for agents covers that.

What's in the box

• One stylesheet, macbetter/styles.css, in its own cascade layer: tokens, platform metrics, four built-in themes, base styles, materials and every component's CSS.
• Components, one file each, imported by name: macbetter/button, macbetter/switch, macbetter/segmented-control and the rest listed in the sidebar.
• <MacbetterScript />, which sets data-platform before first paint so a phone never flashes desktop metrics.
• Theme helpers in macbetter/theme: createTheme(), themeVariables() and contrastRatio().
• Text style classes such as mb-text-headline and mb-text-body, label colors such as mb-label-secondary, and the mb-material and mb-glass surfaces.

Where to go next

• Installation adds macbetter to a React app.
• Platforms and Theming cover the two attributes that shape everything.
• Foundations document the tokens: color, type, materials, motion, layout and accessibility.