Astryx Architecture Cheat Sheet

Golden template: a simple component

// Copyright (c) Meta Platforms, Inc. and affiliates.
/**
 * @file NewComponent.tsx
 * @input React content, BaseProps DOM passthrough, StyleX overrides
 * @output Exports NewComponent and NewComponentProps
 * @position Core leaf component; consumed by index.ts
 *
 * SYNC: When modified, update these files to stay in sync:
 * - /packages/core/src/NewComponent/NewComponent.doc.mjs
 * - /packages/core/src/NewComponent/NewComponent.test.tsx
 * - /packages/core/src/NewComponent/index.ts
 * - /apps/storybook/stories/NewComponent.stories.tsx
 */
import type {ReactNode} from 'react';
import * as stylex from '@stylexjs/stylex';
import type {BaseProps} from '../BaseProps';
import {colorVars, spacingVars} from '../theme/tokens.stylex';
import {mergeProps, themeProps} from '../utils';
const styles = stylex.create({
 root: {
 alignItems: 'center',
 color: colorVars['--color-text-primary'],
 display: 'inline-flex',
 gap: spacingVars['--spacing-1'],
 },
});
export interface NewComponentProps extends BaseProps<HTMLSpanElement> {
 children: ReactNode;
 ref?: React.Ref<HTMLSpanElement>;
}
export function NewComponent({
 children,
 xstyle,
 className,
 style,
 ref,
 ...rest
}: NewComponentProps) {
 return (
 <span
 ref={ref}
 {...mergeProps(
 themeProps('new-component'),
 stylex.props(styles.root, xstyle),
 className,
 style,
 )}
 {...rest}>
 {children}
 </span>
 );
}
NewComponent.displayName = 'NewComponent';

Choose only what applies

Tier 1 — always check when applicable

Layer protocol suite

import {Button, Popover} from '@astryxdesign/core';
<Popover label="Settings" content={<div>Settings</div>}>
 <Button label="Settings" />
</Popover>

Field/input anatomy

import {TextInput, type TextInputStatus} from '@astryxdesign/core/TextInput';
const status: TextInputStatus | undefined = isInvalid
 ? {type: 'error', message: validationMessage}
 : undefined;
<TextInput
 label="Email"
 description="Used for account notifications"
 value={email}
 onChange={setEmail}
 changeAction={saveEmail}
 status={status}
 isRequired
 isDisabled={isDisabled}
 disabledMessage={disabledMessage}
 isReadOnly={isReadOnly}
 isLoading={isSaving}
 hasClear
/>

import {Field} from '@astryxdesign/core/Field';
import {getInputARIA} from '@astryxdesign/core/utils';
const {ariaLabelledBy, ariaDescribedBy} = getInputARIA(labelID, [
 description ? descriptionID : null,
]);
<Field label={label} inputID={inputID} labelID={labelID}
 description={description}
 descriptionID={description ? descriptionID : undefined}>
 <input id={inputID} aria-labelledby={ariaLabelledBy}
 aria-describedby={ariaDescribedBy} />
</Field>

Theming / visual state

import {defineTheme} from '@astryxdesign/core/theme';
import {mergeProps, themeProps} from '@astryxdesign/core/utils';
const brandTheme = defineTheme({
 name: 'brand',
 components: {
 button: {'variant:secondary': {fontWeight: '600'}},
 },
});
<span {...mergeProps(
 themeProps('choice', {selected: isSelected ? 'selected' : null}),
 stylex.props(styles.root, xstyle),
)} />

Accessibility primitives

import {useAnnounce, useFocusTrap} from '@astryxdesign/core/hooks';
const announce = useAnnounce();
const {containerRef} = useFocusTrap<HTMLDivElement>({
 isActive: isOpen,
 onEscape: close,
});
const handleSave = () => {
 onSave();
 announce(savedMessage); // Pass a translated message.
};
<div ref={containerRef}><button onClick={handleSave}>Save</button></div>

Collection/selection

import {Item} from '@astryxdesign/core/Item';
import {useListFocus} from '@astryxdesign/core/hooks';
const {listRef, handleKeyDown} = useListFocus<HTMLDivElement>({
 itemSelector: '[role="menuitem"]',
});
<div ref={listRef} role="menu" onKeyDown={handleKeyDown}>
 {items.map((item, index) => (
 <Item key={item.id} role="menuitem"
 tabIndex={index === 0 ? 0 : -1}
 label={item.label} onClick={item.select} />
 ))}
</div>

Container padding/bleed

import * as stylex from '@stylexjs/stylex';
import {container} from '@astryxdesign/core/Layout';
const bleed = stylex.create({
 root: {
 marginInlineStart: 'calc(-1 * var(--container-padding-inline-start, 0px))',
 marginInlineEnd: 'calc(-1 * var(--container-padding-inline-end, 0px))',
 },
});
<div {...stylex.props(...container({padding: 'spacing3'}))}>
 <div {...stylex.props(bleed.root)}>{content}</div>
</div>

Text/i18n/direction

import {useDirection, useTranslator} from '@astryxdesign/core/i18n';
const t = useTranslator();
const direction = useDirection();
<output dir={direction}>
 {t('@astryx.pagination.pageAnnounce', {current})}
</output>

Link/router

import {
 useLinkComponent,
 type LinkComponentType,
} from '@astryxdesign/core/Link';
function RoutedLink({as, href}: {as?: LinkComponentType; href: string}) {
 const LinkComponent = useLinkComponent(as);
 return <LinkComponent href={href}>Open</LinkComponent>;
}

Public DOM/style/event/ref composition

import {composeEventHandlers, mergeProps, themeProps} from '@astryxdesign/core/utils';
<button
 ref={ref}
 {...mergeProps(
 themeProps('choice'),
 stylex.props(styles.root, xstyle),
 className,
 style,
 )}
 {...rest}
 role="radio"
 aria-checked={isSelected}
 onClick={composeEventHandlers(onClickProp, handleSelect)}
/>

Tier 2 — check when triggered

Size cascade

import {
 SizeProvider,
 useSize,
 type ElementSize,
} from '@astryxdesign/core/SizeContext';
function Control({size}: {size?: ElementSize}) {
 const resolvedSize = useSize(size, 'md');
 return <button data-size={resolvedSize}>Action</button>;
}
<SizeProvider value="sm"><Control /><Control size="lg" /></SizeProvider>

Semantic icons / indicator maps

import {Icon} from '@astryxdesign/core/Icon';
import {useIndicator} from '@astryxdesign/core/Indicator';
const CheckboxIndicator = useIndicator('checkbox');
<>
 <Icon icon="success" label="Completed" />
 <CheckboxIndicator
 state={checked ? 'checked' : 'unchecked'}
 size="sm"
 />
</>

Status/feedback

import {Banner, type BannerStatus} from '@astryxdesign/core/Banner';
import {TextInput, type TextInputStatus} from '@astryxdesign/core/TextInput';
const feedback: BannerStatus = 'info';
const validation: TextInputStatus = {
 type: 'error',
 message: validationMessage,
};
<>
 <Banner status={feedback} title="Profile saved" />
 <TextInput label="Email" value={email}
 onChange={setEmail} status={validation} />
</>

Behavior units

import {useMenuHover} from '../hooks/useMenuHover'; // Core source only.
const hover = useMenuHover({
 show: layer.show,
 hide: layer.hide,
 isOpen: layer.isOpen,
 isEnabled: true,
 popoverId: layer.id,
});
<>
 <button ref={hover.setTriggerEl} {...hover.triggerProps}>Menu</button>
 <div ref={hover.menuRef} {...hover.contentProps} role="menu" tabIndex={-1}>
 {items}
 </div>
</>

Global guardrails