Astryx API Conventions and Prop Naming Patterns: A Complete Guide to the Design System

Astryx components follow strict API conventions including action-prop renaming (removing the on prefix), unified size and width props using SizeValue, logical CSS properties for RTL support, and standardized boolean prefixes like has* and is*, all enforced by CLI tooling, ESLint rules, and automated codemods.

Astryx, Facebook's open-source design system, implements a disciplined set of API conventions that make component props predictable, type-safe, and accessible across the entire library. These patterns are centrally documented in packages/core/CHANGELOG.md and enforced through the Astryx CLI, ESLint plugins, and codemods to ensure consistency from Button to Dialog to Selector.

Action-Prop Renaming: Aligning with React 19 Conventions

Astryx has adopted the upcoming React 19 convention for action props by removing the on prefix. In packages/core/CHANGELOG.md line 1178, the migration from on*Action to *Action is documented as a breaking change that retains only the verb.

Before:

<Button onChangeAction={handleClick} />

After:

<Button changeAction={handleClick} />

This pattern applies to all interactive components, making event handlers more concise while maintaining clarity.

Standardized Sizing Props: width and size

Astryx uses two distinct conventions for dimensions that appear consistently across components like Switch, CheckboxInput, RadioList, and Slider.

The width Prop

The width prop follows the "input-field width" convention, accepting a SizeValue type where numbers are interpreted as pixels and strings are used verbatim.

<Button
  width="100%"  // String passed directly to CSS
  width={250}   // Number interpreted as 250px
/>

This pattern was standardized in packages/core/CHANGELOG.md line 395 for the Button component and propagated throughout the library.

The size Prop

The size prop accepts "sm" or "md" to switch between small and medium scales, as documented in line 134 of the core changelog for components like Switch.

<Switch size="sm" />
<Slider size="md" />

Accessibility-First Label Props

Astryx unifies accessible naming through a required or optional label prop that replaces aria-label on components exposing visible labels. According to line 332 of packages/core/CHANGELOG.md, the Icon component accepts an optional label for screen reader accessibility.

<Icon name="search" label="Search" />
<TextInput label="Email" />

Components also expose explicit accessibility props including tooltip and disabledMessage (documented in line 678) to provide human-readable context for assistive technologies.

<TextInput
  label="Email"
  disabledMessage="Enter a valid email address"
/>

Rest-Prop Forwarding and DOM Attributes

All Astryx components guarantee that consumer-provided HTML attributes reach the DOM through rest-prop forwarding. This includes className, style, xstyle (StyleX styles), data-*, and aria-* attributes.

In packages/core/CHANGELOG.md line 415, the Button component was updated to spread rest props before contract props, ensuring overrides work correctly:

<Button
  changeAction={handleSubmit}
  data-testid="submit-btn"
  data-analytics-id="primary-cta"
  aria-pressed="false"
/>

This pattern is implemented across almost all components including Dialog, CheckboxInput, and Selector in packages/core/src/*/*.tsx.

Logical CSS Properties for RTL Support

Astryx components use logical CSS properties instead of physical directions like left or right. The library migrated components like Avatar and DropdownMenu to use insetInlineStart and insetInlineEnd rather than directional properties, as noted in packages/core/CHANGELOG.md line 79.

<TextInput
  label="Username"
  stylex={{
    paddingInline: 'var(--space-2)',  // Logical padding
    marginInlineStart: 'var(--space-1)'
  }}
/>

Variant, Theme, and Status Props

Appearance customization follows predictable naming through variant, elevation, and statusVariant props. Line 232 of the core changelog documents the addition of elevation="low" to Card and Button components.

<Card elevation="low">
  <Button variant="primary" elevation="low" />
</Card>

HTML-Name Forwarding for Form Integration

Form-related components accept an htmlName prop to enable native form submission, as implemented in packages/core/CHANGELOG.md line 625 for Switch, CheckboxInput, and RadioList.

<Switch htmlName="notifications" size="sm" />
<CheckboxInput htmlName="terms" label="Accept terms" />

Boolean State Prop Naming

State-related props use consistent prefixes to convey intent clearly:

• has* for features (e.g., hasClear)
• is* for states (e.g., isDisabled)
• open* for visibility states

Line 32 of the changelog documents hasClear on the Selector component:

<Selector
  options={items}
  hasClear
  isDisabled={false}
/>

RTL-Aware API and Direction Handling

Astryx provides programmatic RTL support through the useDirection() hook and a dir prop on InternationalizationProvider, added in packages/core/CHANGELOG.md line 131.

<InternationalizationProvider dir="rtl">
  <TextInput label="Name" />
</InternationalizationProvider>

Tooling Enforcement: CLI, ESLint, and Codemods

These conventions are reinforced by three tooling layers defined in the source code:

Astryx CLI

The CLI implementation in packages/cli/clients/cli/bin/astryx.mjs provides component API introspection. Running astryx component <Name> --dense outputs the full prop interface including names, types, and usage examples.

ESLint Plugin

Rules in packages/eslint-plugin-astryx/src/rules/*.ts enforce naming conventions and accessibility requirements. The @astryx/i18n-key-format and @astryx/no-hardcoded-i18n-string rules ensure prop naming remains consistent and locale-aware.

Automated Codemods

The astryx upgrade --codemod command automatically migrates deprecated prop patterns, such as converting on*Action to *Action or styles to xstyle, ensuring codebase consistency during version upgrades.

Summary

• Action props drop the on prefix (e.g., changeAction instead of onChangeAction) to align with React 19 conventions.
• Dimensions use width with SizeValue (number for px, string for CSS) and size with "sm" or "md" values.
• Accessibility relies on label, tooltip, and disabledMessage props rather than direct ARIA attributes.
• Rest props including data-*, aria-*, className, and xstyle forward to the DOM in all components.
• Logical CSS properties replace directional values (left/right) for RTL compatibility.
• Form components accept htmlName for native form submission integration.
• Boolean props use has*, is*, and open* prefixes for clear intent.
• Tooling including the CLI (astryx.mjs), ESLint rules, and codemods enforce these patterns automatically.

Frequently Asked Questions

How do I migrate from on*Action to *Action props in Astryx?

Run astryx upgrade --codemod to automatically transform deprecated on*Action props to the new *Action naming convention. This codemod scans your codebase and updates event handlers like onChangeAction to changeAction across all components, as documented in packages/core/CHANGELOG.md line 1178.

What is the difference between width and size in Astryx components?

The width prop controls the element's horizontal space using SizeValue (numbers become pixels, strings pass through as CSS), while size controls the component's visual scale using discrete tokens like "sm" or "md". For example, width="100%" makes a button fill its container, whereas size="sm" reduces the button's padding and font size.

How does Astryx handle RTL (right-to-left) languages in component APIs?

Astryx uses logical CSS properties (e.g., paddingInline instead of paddingLeft) and provides the useDirection() hook and dir prop on InternationalizationProvider to set text direction. Components automatically adjust layout based on the direction context without requiring physical directional props.

What tooling enforces Astryx naming conventions?

The Astryx CLI (packages/cli/clients/cli/bin/astryx.mjs) displays component APIs with astryx component <Name> --dense. The ESLint plugin (packages/eslint-plugin-astryx/src/rules/*.ts) includes rules like @astryx/i18n-key-format to validate prop naming. Codemods automatically migrate deprecated patterns during upgrades, ensuring consistency across the codebase.

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