spectra-ui

Spectra UI

The Enterprise Design System and Multi-Platform Component Engine by Winplaybox.

---

Overview

Spectra UI is a production-grade, enterprise design system and cross-platform UI ecosystem engineered for high-performance applications. Built from the ground up to synthesize the rigorous standards of Google Material UI (MUI v5/v6), Microsoft Fluent UI 2 (v9), Apple Human Interface Guidelines (HIG), and Radix Primitives, Spectra UI delivers a cohesive developer experience across Web, Mobile, and AI-assisted workflows.

---

Ecosystem Packages

Spectra UI is architected as a modular monorepo. Each package can be installed independently or consumed together as a unified system:

Package	Version	Weekly Downloads	Directory	Description
@winplaybox/react			packages/react	62 production-ready web components with Vanilla Extract zero-runtime styling
@winplaybox/tokens			packages/tokens	Multi-tier design token engine compiling to CSS variables, TypeScript, and JSON
@winplaybox/icons			packages/icons	14,200+ accessible SVG vector icons across 7 distinct visual styles
@winplaybox/primitives			packages/primitives	25 headless React state hooks and unstyled behavioral primitives
@winplaybox/react-native			packages/react-native	Cross-platform native components tailored for iOS and Android
@winplaybox/mcp			packages/mcp	Model Context Protocol server enabling Cursor, Claude, and Antigravity IDE integration

---

Architectural Principles

1. Single Source of Truth: All semantic colors, spacing scales, typography metrics, and elevation curves originate in @winplaybox/tokens and flow deterministically into web, native, and AI tools.
2. Zero Emoji Policy: In accordance with the system charter, Spectra UI exclusively renders authentic SVG vector glyphs from @winplaybox/icons. No casual emojis are permitted across components, notices, or documentation.
3. Platform Isolation: Clean separation between Web (@winplaybox/react) and Mobile (@winplaybox/react-native), allowing developers to consume platform-specific contracts without cross-platform bundle bloat.
4. Accessibility First (WCAG 2.1 AA): Complete WAI-ARIA compliance, automatic focus traps, contrast verification, and full keyboard navigation across all overlay and form components.
5. Zero-Runtime CSS: Type-safe CSS generated ahead of time via Vanilla Extract, ensuring predictable performance without CSS-in-JS runtime overhead.

---

Installation & Quick Start

1. Web Applications (React)

# Using pnpm (recommended)
pnpm add @winplaybox/react @winplaybox/tokens @winplaybox/icons

# Using npm
npm install @winplaybox/react @winplaybox/tokens @winplaybox/icons

# Using yarn
yarn add @winplaybox/react @winplaybox/tokens @winplaybox/icons

Import tokens in your root stylesheet or entry file:

/* styles.css or index.css */
@import "@winplaybox/tokens/tokens.css";

Use components inside your React application:

import React from "react";
import {
  SpectraProvider,
  Button,
  Card,
  TextInput,
  Badge,
} from "@winplaybox/react";
import { SearchIcon } from "@winplaybox/icons";

export function App() {
  return (
    <SpectraProvider defaultTheme="dark">
      <Card variant="elevated" padding="large">
        <Badge variant="brand" label="Production Ready" />
        <h2>Welcome to Spectra UI</h2>
        <TextInput
          placeholder="Search components..."
          startIcon={<SearchIcon size={18} />}
        />
        <Button variant="primary" size="medium">
          Get Started
        </Button>
      </Card>
    </SpectraProvider>
  );
}

---

2. Mobile Applications (React Native)

pnpm add @winplaybox/react-native @winplaybox/tokens @winplaybox/primitives

import React from "react";
import { View } from "react-native";
import { Button, Card, Text } from "@winplaybox/react-native";

export function MobileScreen() {
  return (
    <View style={{ flex: 1, padding: 16 }}>
      <Card variant="elevated">
        <Text variant="title">Mobile Native Chassis</Text>
        <Button title="Confirm Action" variant="primary" />
      </Card>
    </View>
  );
}

---

3. AI Assistant Integration (MCP Server)

Connect Spectra UI directly to Cursor, Claude Desktop, or Antigravity IDE:

npx @winplaybox/mcp

Add to your IDE's mcp.json:

{
  "mcpServers": {
    "spectra-ui": {
      "command": "npx",
      "args": ["-y", "@winplaybox/mcp"]
    }
  }
}

Now your AI assistant can inspect exact props, tokens, verified recipes, and icons directly from the design system.

---

Component Catalog (62 Web Components)

The @winplaybox/react library provides 62 enterprise components organized into 8 functional categories:

• Actions: Button, IconButton, ButtonGroup, SplitButton, CompoundButton, CopyButton
• Data Display: Avatar, AvatarGroup, Badge, Calendar, Chip, List, ListView, Statistic, Table, Tag, Timeline, TreeView
• Feedback: Alert, Drawer, ProgressBar, Skeleton, Spinner, Toast, ErrorBoundary
• Form: Autocomplete, Checkbox, CheckboxGroup, ColorPicker, DatePicker, Radio, Rating, Select, Slider, Switch, Textarea, TextInput
• Layout: Box, Container, Divider, Grid, Stack, Text
• Navigation: AppBar, Breadcrumbs, Link, Menu, Pagination, PlatformChassis, SpeedDial, Stepper, Tabs
• Overlay: Dialog, Popover, Tooltip
• Surfaces: Card, MediaCard, Paper, WebViewBox

---

Headless Hooks Catalog (25 Primitives)

Available via @winplaybox/primitives (or exported via @winplaybox/react):

• State & Disclosure: useDisclosure, useControllableState, usePrevious, useErrorBoundary
• Environment & Theme: useTheme, useColorScheme, usePlatform, useBreakpoint, useReducedMotion, useRTL
• DOM & Sizing: useOutsideClick, useEventListener, useIntersectionObserver, useScrollLock, useWindowSize, useElementSize, useMediaQuery, useFocusTrap, useFocusRing, useId
• Performance & Async: useDebounce, useThrottle, useInterval, useAsync
• Storage & Input: useLocalStorage, useClipboard, useHover, useToast, useFormField

---

Monorepo Development

Spectra UI uses Turborepo and pnpm workspaces for build orchestration:

# Install workspace dependencies
pnpm install

# Build tokens and all packages
pnpm run build

# Start interactive documentation sandbox
pnpm run dev

# Run Storybook component workbench
pnpm run storybook

# Verify release readiness across all packages
pnpm run release:check

# Generate distribution tarballs (.tgz)
pnpm run pack:packages

---

Publishing to NPM

All packages are configured with public access, ESM exports, type declarations, and package metadata:

# 1. Verify release readiness
pnpm run release:check

# 2. Build design tokens and compile all packages
pnpm run build

# 3. Publish all workspace packages to the public npm registry
pnpm -r publish --access public

---

License

Spectra UI is an open-source design system released under the MIT License.
Copyright (c) 2026 Winplaybox.