@pixxl-tools/components

Shared React primitives, icons, metadata, tokens, and CSS for Pixxl apps.

@pixxl-tools/components is intentionally generic. Canvas-product chrome belongs in @pixxl-tools/canvas/react; app-specific file actions and product workflows belong in website.

Package status: pre-1.0 public package. APIs may change before 1.0.

Quick Start

import { Button, Text } from "@pixxl-tools/components";
import { DownloadIcon } from "@pixxl-tools/components/icons";
import "@pixxl-tools/components/styles.css";

export function ToolbarButton() {
  return (
    <Button icon={<DownloadIcon />} variant="primary">
      Export
    </Button>
  );
}

Install/CSS

Install the package:

pnpm add @pixxl-tools/components

Import primitives from the root and CSS once in the app:

import "@pixxl-tools/components/styles.css";

Server-safe metadata and tokens use @pixxl-tools/components/metadata and @pixxl-tools/components/tokens.

Public API

• @pixxl-tools/components: React primitives, icons, and tokens for browser UI.
• @pixxl-tools/components/metadata: component and recipe metadata used by docs.
• @pixxl-tools/components/tokens: token objects for web colors, motion, opacity, radius, spacing, typography, and z-index.
• @pixxl-tools/components/icons: shared icon components plus SvgIcon for rare composed icon previews.
• @pixxl-tools/components/styles.css: CSS variables and component classes.

All primitive modules are client components. Server-safe metadata and token subpaths must not import primitive component entrypoints.

Model/Persistence

Components are stateless UI primitives. Persistent state belongs to product packages or host apps. Controlled props follow value / defaultValue / onValueChange and open / defaultOpen / onOpenChange.

Boundaries

• No app framework imports.
• No runtime dependencies.
• React is the only peer dependency.
• No canvas-product primitives in this package.
• No raw visual values outside token definitions.

Examples

Runnable examples:

• examples/components/basic-ui.tsx: primitive composition with CSS import.
• examples/components/tokens.ts: token object usage for non-React code.

Use Button, Text, ToolRail, ToolTopbar, and form primitives from @pixxl-tools/components. Use icons from @pixxl-tools/components/icons. Use token objects from @pixxl-tools/components/tokens.

Testing

Relevant checks:

pnpm test

Limits

• Generic primitives only; canvas-product chrome belongs in @pixxl-tools/canvas/react.
• React is the only peer dependency.
• No app framework imports.

Troubleshooting

• Missing styles usually means @pixxl-tools/components/styles.css was not imported.
• If metadata tests fail, add metadata for new primitive exports.
• If architecture tests fail, check framework imports, raw CSS values, icon duplication, and client directives.

Migration/Versioning

Add public primitives through root exports and metadata together. Keep broad root type exports through components/src/types.ts, not components/src/internal.