getting started

The package ladder

How the eleven packages stack. What depends on what. What you need to install for each layer.

plyxui ships as eleven npm packages on purpose. Each layer is one npm install away from being a thing you can use, and each layer pulls in everything below it transitively.

The stack

                                 ┌───────────────────────┐
            high-rung           │     @plyxui/plugins    │   command palette, table, chart
                                 │     @plyxui/screens    │   AuthLayout, EmptyState, ErrorScreen
                                 └───────────────────────┘
                                            ▲
                                            │
                                 ┌───────────────────────┐
            mid-rung            │     @plyxui/comps      │   Modal, Dropdown, Toast
                                 │     @plyxui/layouts    │   AppShell, Sidebar
                                 │     @plyxui/forms      │   Field, Select, Checkbox, Radio
                                 │     @plyxui/navigator  │   defineRoutes + adapters
                                 └───────────────────────┘
                                            ▲
                                            │
                                 ┌───────────────────────┐
            foundation         │     @plyxui/icons      │   Icon + registry
                                 │     @plyxui/primitives │   Box, Text, Stack, Flex, Input, Button
                                 │     @plyxui/styles     │   ThemeProvider, useTheme
                                 │     @plyxui/hooks      │   useDisclosure, useClickOutside, useToast
                                 │     @plyxui/core       │   tokens, types, helpers
                                 └───────────────────────┘

The rules

Layer	Depends on	Consumer install
Foundation	nothing	One install line. `@plyxui/styles` always; the rest as needed.
Mid-rung	foundation packages it uses	Auto-installed transitively. You import directly.
High-rung	every layer below	Same. One install line gets you the whole ladder.

The dep model is auto-install via dependencies. When you npm install @plyxui/screens, you get screens + layouts + primitives + icons + styles + core. No peer-dep installer dance. You can still pin your own versions of the foundation packages by listing them in your own dependencies.

Common patterns

Building a marketing site

npm install @plyxui/styles @plyxui/primitives @plyxui/icons

Wrap with <ThemeProvider />. Compose with Box, Text, Button. That's it.

Building a dashboard

npm install @plyxui/styles @plyxui/primitives @plyxui/icons \
            @plyxui/layouts @plyxui/comps @plyxui/navigator @plyxui/forms

<AppShell> + <Sidebar> + your route table via defineRoutes(). Forms via <Field> + <Select> etc. Modal + Dropdown when you need them.

Building a full app

npm install @plyxui/styles @plyxui/primitives @plyxui/icons \
            @plyxui/layouts @plyxui/comps @plyxui/navigator \
            @plyxui/forms @plyxui/screens @plyxui/plugins @plyxui/hooks

Auth + empty + error screens out of the box. Command palette via @plyxui/plugins/command-palette.

What's NOT in the ladder

@plyxui/mcp is a CLI, not a runtime import. Install as a dev dep when you want coding agents to install components by name.
The desktop AI tool (AI Polish) is a sibling product, not a package. It uses plyxui's tokens for theming itself, but consumers don't install it.

Cross-platform

Every foundation + mid-rung + screens package ships .ts for web and .native.ts for React Native. Metro resolves the right one; web bundlers (Vite, Webpack, Next, Electron renderer) pick the .ts. The public API is identical across both.

@plyxui/plugins is web-first for now — the CommandPalette UX doesn't have a native equivalent worth pretending. Native variants come per-component as we add them.