How to Use the Core Astryx Package for Basic Components

The @astryxdesign/core package provides type-safe React components that automatically inherit the active theme through StyleX, exposing a consistent prop API for buttons, cards, layouts, and other fundamental UI building blocks.

The facebook/astryx repository structures its component library around the core package, which serves as the foundation for building consistent internal tools. When you use the core Astryx package for basic components, you gain access to a unified theming system based on CSS custom properties, accessibility-first prop patterns, and zero-config TypeScript support.

Installation and Setup

Install the core package via your package manager of choice. The package ships with StyleX-generated CSS, so ensure your build pipeline can process StyleX styles (typically handled by the Astryx CLI or your existing StyleX configuration).

npm install @astryxdesign/core

Importing Components from the Core Package

The package entry point at packages/core/src/index.ts re-exports every component, enabling both barrel imports and direct path imports for tree-shaking optimization.

Barrel Imports vs. Direct Path Imports

You can import multiple components from the root:

import { Button, ButtonGroup, Card } from '@astryxdesign/core';

For better bundle size and faster build times, import directly from component paths:

import { Button } from '@astryxdesign/core/Button';
import { Icon } from '@astryxdesign/core/Icon';

Each component lives in its own folder under packages/core/src/<Component>/ and includes a documentation module (<Component>.doc.mjs) that powers the CLI docs and Storybook generation.

Component Architecture and Theming

StyleX Token System

Components read CSS custom properties defined in packages/core/src/theme/tokens.stylex.ts and apply them via StyleX. The token registry is defined in packages/core/src/theme/tokens.ts, and the generated CSS is emitted during the build step. This ensures that when you use the core Astryx package for basic components, they automatically pick up color, spacing, and typography values from your active theme.

BaseProps and Accessibility Patterns

All interactive components follow the BaseProps<T> pattern defined in packages/core/src/utils/mergeProps.ts. This utility merges props while preserving refs and event handlers, ensuring consistent behavior across the library. Components expose ARIA-friendly props such as label, isIconOnly, and tooltip by default, making accessibility configurations automatic rather than opt-in.

Working with Basic Components

Standard Button Implementation

The Button component supports variants, states, and icons through a unified prop interface:

// Basic primary button
import { Button } from '@astryxdesign/core/Button';

function SaveButton() {
  return (
    <Button
      label="Save changes"
      variant="primary"
      onClick={() => console.log('saved')}
    />
  );
}

Icon-Only and Destructive Patterns

For actions requiring visual emphasis or icon-only presentation:

// Icon-only button (use IconButton for pure icons)
import { Button } from '@astryxdesign/core/Button';
import { Icon } from '@astryxdesign/core/Icon';

function DeleteButton() {
  return (
    <Button
      label="Delete item"
      variant="destructive"
      isIconOnly
      icon={<Icon icon="trash" size="sm" />}
    />
  );
}

Disabled States with Tooltips

Components handle disabled states and contextual tooltips through declarative props:

// Disabled button with tooltip
import { Button } from '@astryxdesign/core/Button';

function DisabledSubmit() {
  return (
    <Button
      label="Submit"
      variant="primary"
      isDisabled
      tooltip="Complete the required fields first"
    />
  );
}

Layout Components

Group related actions using the ButtonGroup component, which manages spacing and alignment automatically:

// Using ButtonGroup to layout multiple buttons
import { Button, ButtonGroup } from '@astryxdesign/core';

function FormActions() {
  return (
    <ButtonGroup size="sm" label="Form actions">
      <Button label="Cancel" variant="secondary" onClick={() => {}} />
      <Button label="Save" variant="primary" onClick={() => {}} />
    </ButtonGroup>
  );
}

Shared Utilities and Hooks

The core package includes reusable logic in packages/core/src/hooks/ for common interactions. useTheme provides the current theme context to components, while useCollapsible and useListFocus manage complex keyboard navigation and display states. The mergeProps utility in packages/core/src/utils/mergeProps.ts ensures that event handlers and refs compose correctly when wrapping components.

Development Workflow

Documentation and Testing

Every component includes a Jest/Vitest test file (e.g., Button.test.tsx) and a documentation module consumed by the CLI. When you create new components following the established pattern in packages/core/src/, the system automatically generates reference pages and Storybook stories from the .doc.mjs files.

Summary

• Import directly from @astryxdesign/core or use path-specific imports like @astryxdesign/core/Button for optimal tree-shaking.
• Theming is automatic through StyleX tokens defined in theme/tokens.stylex.ts, requiring no manual CSS imports.
• Accessibility is built-in via the BaseProps pattern and ARIA-friendly prop interfaces.
• Documentation is co-located with source code in .doc.mjs files, powering both CLI and Storybook outputs.
• Hooks and utilities like useTheme and mergeProps are available for custom component development.

Frequently Asked Questions

How do I customize the theme when using the core Astryx package?

The theme system relies on CSS custom properties defined in packages/core/src/theme/tokens.stylex.ts. Override these tokens at the application level or provide a custom theme configuration through the StyleX provider. Components automatically read these values through the useTheme hook, requiring no prop drilling or manual style overrides.

What is the difference between Button and IconButton components?

While the standard Button component supports an isIconOnly prop for icon-only appearances, the dedicated IconButton (if exported) provides optimized sizing and accessibility defaults specifically for icon-only interactions. Check the specific component exports in packages/core/src/index.ts to see which pattern your version supports.

Where are component tests located in the core package?

Each component maintains its test suite in the same directory as its implementation. For example, Button tests reside in packages/core/src/Button/Button.test.tsx alongside the main Button.tsx file and Button.doc.mjs documentation module.

Can I use mergeProps for my own components outside the core package?

Yes. The mergeProps utility in packages/core/src/utils/mergeProps.ts is designed to handle complex prop merging, including event handler composition and ref forwarding. Import it directly to ensure your custom components maintain the same behavior patterns as the official Astryx components.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}