element."},{"name":"contentPadding","type":"0 | 0.5 | 1 | 1.5 | 2 | 3 | 4 | 5 | 6 | 8 | 10","description":"Padding for the main content area. Set based on the dominant content pattern: 4 (16px) for forms/settings/text, 0 for dashboards/maps/tables. Override individual sections with Section.","default":"0"},{"name":"topNav","type":"ReactNode","description":"Top navigation slot, typically TopNav.","slotElements":[{"__element":"TopNav","props":{"label":"Navigation"}}]},{"name":"sideNav","type":"ReactNode","description":"Side navigation slot, typically SideNav.","slotElements":[{"__element":"SideNav","props":{}}]},{"name":"mobileNav","type":"ReactNode","description":"Mobile navigation configuration. Accepts false (disable), config object (tune auto behavior), or ReactNode (full custom drawer).","slotElements":[{"__element":"MobileNav","props":{}}]},{"name":"banner","type":"ReactNode","description":"Banner slot for system-wide announcements, placed above the topNav.","slotElements":[{"__element":"Banner","props":{"title":"Info","status":"info","container":"section"}}]},{"name":"height","type":"'fill' | 'auto'","description":"Height behavior: 'fill' makes the shell fill the viewport (100dvh) with independent scroll containers; 'auto' lets the shell grow with content and uses sticky positioning for nav.","default":"'fill'"},{"name":"variant","type":"'wash' | 'surface' | 'section' | 'elevated'","description":"Navigation background style controlling how nav areas contrast with content. 'wash' uses wash background, 'surface' uses surface background, 'section' adds dividers between nav and content, 'elevated' uses wash nav with elevated surface content and border radius.","default":"'elevated'"},{"name":"xstyle","type":"StyleXStyles","description":"StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}."}],"usage":{"description":"The outermost layout for an application. Provides slots for top navigation, side navigation, banners, and main content. Use it as the root wrapper for every page. It handles responsive mobile navigation and skip-to-content automatically. Configure side nav collapse on SideNav with its collapsible prop.","bestPractices":[{"guidance":true,"description":"Choose the right height: use \"fill\" for dashboards with internal scrolling and \"auto\" for pages that grow with content."},{"guidance":true,"description":"Set `contentPadding` based on content type: 4 for forms and settings, 0 for tables and dashboards."},{"guidance":false,"description":"Nest one AppShell inside another; it's the outermost layout frame."},{"guidance":false,"description":"Use for sub-page layouts; use Layout for content areas within AppShell."}]},"theming":{"targets":[{"className":"astryx-app-shell","visualProps":["variant"]},{"className":"astryx-app-shell-header","visualProps":["variant"]},{"className":"astryx-app-shell-sidenav","visualProps":["variant"]}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"variant":"surface","contentPadding":4,"topNav":{"__element":"TopNav","props":{"label":"Navigation","heading":{"__element":"TopNavHeading","props":{"heading":"My App"}}}},"sideNav":{"__element":"SideNav","props":{},"children":[{"__element":"SideNavItem","props":{"label":"Dashboard","isSelected":true}},{"__element":"SideNavItem","props":{"label":"Settings"}},{"__element":"SideNavItem","props":{"label":"Help"}}]},"children":{"__element":"VStack","props":{"gap":3},"children":[{"__element":"Heading","props":{"level":2},"children":"Dashboard"},{"__element":"Text","props":{"type":"body","color":"secondary"},"children":"Welcome back. Here is an overview of your workspace."}]}}}},{"name":"AspectRatio","displayName":"Aspect Ratio","moduleName":"AspectRatio","directory":"AspectRatio","importPath":"@astryxdesign/core/AspectRatio","group":null,"category":"Layout","isHiddenFromOverview":false,"description":"Maintains a fixed width-to-height ratio for its children, regardless of screen size. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions.","keywords":["aspect-ratio","ratio","proportion","responsive","embed","container","widescreen","thumbnail","letterbox","crop"],"hidden":false,"parentDoc":null,"props":[{"name":"ratio","type":"number","description":"Aspect ratio as width/height (e.g. 16/9, 1).","required":true},{"name":"children","type":"ReactNode","description":"Content positioned absolutely to fill the container.","required":true},{"name":"xstyle","type":"StyleXStyles","description":"StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}."}],"usage":{"description":"Maintains a fixed width-to-height ratio for its children, regardless of screen size. Use it for media containers like videos, images, thumbnails, or any content that needs consistent proportions.","bestPractices":[{"guidance":true,"description":"Express the ratio as a fraction like `16/9` or `4/3` for readability."},{"guidance":true,"description":"Use for media that needs consistent proportions across screen sizes."},{"guidance":false,"description":"Use for general layout containers; use standard layout components instead."},{"guidance":false,"description":"Nest AspectRatio containers; one level is sufficient."}]},"theming":{"targets":[{"className":"astryx-aspect-ratio"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"ratio":1.7777777777777777,"children":{"__element":"Center","props":{"height":"100%"},"children":{"__element":"Text","props":{"color":"secondary"},"children":"16:9"}}}}},{"name":"Avatar","displayName":"Avatar","moduleName":"Avatar","directory":"Avatar","importPath":"@astryxdesign/core/Avatar","group":"Avatar","category":"Content","isHiddenFromOverview":false,"description":"Displays a user avatar with image, initials fallback, and optional status indicator.","keywords":["avatar","profile","user","photo","thumbnail","initials","gravatar","pfp","userpic"],"hidden":false,"parentDoc":"Avatar","props":[{"name":"src","type":"string","description":"Primary image source URL."},{"name":"fallbackSrc","type":"string","description":"Fallback image when primary fails."},{"name":"name","type":"string","description":"User name for initials and alt text."},{"name":"alt","type":"string","description":"Alt text (falls back to name)."},{"name":"size","type":"AvatarSize","description":"Avatar size (named or numeric pixel value).","default":"'small'"},{"name":"status","type":"ReactNode","description":"Corner content for status indicators.","slotElements":[{"__element":"StatusDot","props":{"variant":"online"}}]}],"usage":{"description":"Avatar represents a person or team with a profile photo, initials, or a default icon. Use it in comment headers, contact lists, chat messages, user cards, and anywhere you need to identify someone visually.","bestPractices":[{"guidance":true,"description":"Always pass a name so the avatar can show initials if the photo fails to load, and so screen readers can announce who it represents."},{"guidance":true,"description":"Pick a size that matches the context: tiny or xsmall for inline mentions, small or medium for lists and cards, large for profile headers."},{"guidance":true,"description":"Add a status dot when knowing someone's availability matters, like in chat or team views."},{"guidance":false,"description":"Use Avatar for logos, product images, or anything that isn't a person or team. Use an image or icon instead."},{"guidance":false,"description":"Force a square or custom shape. Avatars are always circular to stay consistent across the system."}],"anatomy":[{"name":"Photo","required":false,"description":"The profile image, loaded from the src URL. Shown when available."},{"name":"Initials","required":false,"description":"One or two letters extracted from the name. Shown when no photo is available."},{"name":"Default icon","required":false,"description":"A generic person silhouette. Shown when there is no photo or name."},{"name":"Status dot","required":false,"description":"A small indicator in the bottom-right corner showing availability (online, away, busy)."}]},"theming":{"targets":[{"className":"astryx-avatar","visualProps":["size"]},{"className":"astryx-avatar-status-dot","visualProps":["variant"]}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":null},{"name":"AvatarGroup","displayName":"Avatar Group","moduleName":"AvatarGroup","directory":"AvatarGroup","importPath":"@astryxdesign/core/AvatarGroup","group":"Avatar","category":"Content","isHiddenFromOverview":false,"description":"Stacked avatar display with overlapping layout and optional overflow indicator. Children are Avatar elements.","keywords":["avatar","group","facepile","stack","overlap","participants","assignees","members","team"],"hidden":false,"parentDoc":"AvatarGroup","props":[{"name":"children","type":"ReactNode","description":"Avatar children, optionally followed by one AvatarGroupOverflow. Consumers handle slicing to the desired visible count.","required":true,"slotElements":[{"__element":"Avatar","props":{"name":"User"}}]},{"name":"size","type":"AvatarSize","description":"Size applied to all avatars via context.","default":"'small'"},{"name":"ref","type":"React.Ref","description":"Ref forwarded to the root element."},{"name":"xstyle","type":"StyleXStyles","description":"StyleX styles for layout customization."},{"name":"data-testid","type":"string","description":"Test selector for automated testing frameworks."}],"usage":{"description":"AvatarGroup displays multiple avatars in an overlapping row with an optional overflow indicator. Uses a compositional API: pass Avatar children directly so each avatar can carry its own props (status dots, click handlers, etc.).","bestPractices":[{"guidance":true,"description":"Set max to limit visible avatars when the list is long; 3-5 is typical."},{"guidance":true,"description":"Use AvatarGroupOverflow for custom overflow content like a popover trigger or \"add member\" button."},{"guidance":true,"description":"Pass status dots, click handlers, or tooltips directly on each Avatar child."},{"guidance":false,"description":"Don't nest AvatarGroups; use a single group with all avatars."}],"anatomy":[{"name":"Avatar children","required":true,"description":"Avatar elements that form the overlapping row. Each can have its own props."},{"name":"Overflow indicator","required":false,"description":"A \"+N\" circle at the end showing hidden count, or a custom AvatarGroupOverflow slot."}]},"theming":{"targets":[{"className":"astryx-avatar-group","visualProps":["size"]}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":null},{"name":"AvatarGroupOverflow","displayName":"Avatar Group Overflow","moduleName":"AvatarGroupOverflow","directory":"AvatarGroup","importPath":"@astryxdesign/core/AvatarGroup","group":"Avatar","category":"Content","isHiddenFromOverview":true,"description":"Overflow indicator for AvatarGroup. Shows a compact count for hidden avatars and can render custom count text or act as a button.","keywords":["avatar","group","facepile","stack","overlap","participants","assignees","members","team"],"hidden":false,"parentDoc":"AvatarGroup","props":[{"name":"count","type":"number","description":"The number of hidden avatars. Used for the default `+N` label and the accessible label.","required":true},{"name":"children","type":"ReactNode","description":"Optional custom count text rendered inside the indicator. Omit to use the default `+N` label."},{"name":"onClick","type":"() => void","description":"Callback fired when the overflow indicator is clicked. When provided, the indicator renders as a focusable button."},{"name":"ref","type":"React.Ref","description":"Ref forwarded to the overflow indicator element."},{"name":"xstyle","type":"StyleXStyles","description":"StyleX styles for layout customization."}],"usage":{"description":"AvatarGroupOverflow appears at the end of an AvatarGroup to summarize people who are not shown individually. Use it when a group is sliced to a small number of visible avatars but the hidden count still matters.","bestPractices":[{"guidance":true,"description":"Pass the real hidden count to `count` so the accessible label matches the visible indicator."},{"guidance":true,"description":"Use short custom text such as `+12` or `99+`; the indicator is sized like an avatar."},{"guidance":true,"description":"Provide `onClick` when the overflow opens a member list, popover, or detail view."},{"guidance":false,"description":"Do not use long labels inside the indicator; place longer participant details next to the group instead."}],"anatomy":[{"name":"Count label","required":true,"description":"The compact `+N` or custom count text displayed inside the circular indicator."},{"name":"Button behavior","required":false,"description":"When `onClick` is provided, the indicator becomes an interactive button with focus and hover states."}]},"theming":{"targets":[{"className":"astryx-avatar-group","visualProps":["size"]}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"count":2,"children":"+2"}}},{"name":"AvatarStatusDot","displayName":"Avatar Status Dot","moduleName":"AvatarStatusDot","directory":"Avatar","importPath":"@astryxdesign/core/Avatar","group":"Avatar","category":"Content","isHiddenFromOverview":true,"description":"Size-aware status indicator dot that reads avatar size from context and scales proportionally.","keywords":["avatar","profile","user","photo","thumbnail","initials","gravatar","pfp","userpic"],"hidden":false,"parentDoc":"Avatar","props":[{"name":"variant","type":"'success' | 'neutral' | 'error'","description":"Semantic color variant of the dot.","default":"'success'"},{"name":"label","type":"string","description":"Accessible label for screen readers."},{"name":"icon","type":"ReactNode","description":"Icon centered inside the dot (hidden at tiny sizes).","slotElements":[{"__element":"Icon","props":{"icon":"check","size":"sm"}}]}],"usage":{"description":"Size-aware status indicator dot that reads avatar size from context and scales proportionally."},"theming":{"targets":[{"className":"astryx-avatar","visualProps":["size"]},{"className":"astryx-avatar-status-dot","visualProps":["variant"]}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":null},{"name":"Badge","displayName":"Badge","moduleName":"Badge","directory":"Badge","importPath":"@astryxdesign/core/Badge","group":null,"category":"Feedback & Status","isHiddenFromOverview":false,"description":"Badge highlights a status or category at a glance. Use it sparingly: only when a value represents a distinct state (Active, Failed) or a grouping tag (Engineering, Design). Most metadata (dates, durations, counts, descriptions) should be plain description text, not badges.","keywords":["badge","tag","chip","label","status","indicator","count","counter","pill","notification","marker"],"hidden":false,"parentDoc":null,"props":[{"name":"variant","type":"'neutral' | 'info' | 'success' | 'warning' | 'error' | 'blue' | 'cyan' | 'green' | 'orange' | 'pink' | 'purple' | 'red' | 'teal' | 'yellow'","description":"Visual style variant. Semantic variants (neutral, info, success, warning, error) use solid backgrounds. Non-semantic color variants use tinted backgrounds with colored text for categorization and tagging.","default":"'neutral'"},{"name":"label","type":"ReactNode","description":"Badge text content."},{"name":"icon","type":"ReactNode","description":"Optional leading icon.","slotElements":[{"__element":"Icon","props":{"icon":"check","size":"sm"}}]}],"usage":{"description":"Badge highlights a status or category at a glance. Use it sparingly: only when a value represents a distinct state (Active, Failed) or a grouping tag (Engineering, Design). Most metadata (dates, durations, counts, descriptions) should be plain description text, not badges.","bestPractices":[{"guidance":true,"description":"Every status badge steals attention. Only badge states where the user needs to notice or act: errors, warnings, items requiring follow-up. If no action is needed, plain text is fine."},{"guidance":true,"description":"Use success, warning, and error variants only for system status that demands attention: \"Failed\", \"Degraded\", \"Action Required\". These have bold solid backgrounds designed to stand out."},{"guidance":true,"description":"Use color variants (blue, purple, teal, etc.) for category tags that group or classify items: team names, content types, priority levels."},{"guidance":true,"description":"Keep labels to one or two words. If you need more detail, put it in surrounding text instead of the badge."},{"guidance":true,"description":"Add an icon when it helps identify the badge type quickly, but always include a text label alongside it."},{"guidance":false,"description":"Apply a \"success\" badge to every healthy/active/normal item. If all rows show green \"Active\" badges, none stand out; the badge adds noise, not information. Show only the states that need user attention (errors, warnings, pending actions)."},{"guidance":false,"description":"Use badges for metadata. Durations (\"6h window\"), counts (\"12 trigger types\"), dates, and descriptions are not statuses or categories; use description text (Text with type=\"supporting\") instead."},{"guidance":false,"description":"Use semantic status variants (success, warning, error, info) for categories or informational content. These are visually loud and should only indicate system state."},{"guidance":false,"description":"Repeat the same badge in every row of a table or list. If the same value appears in most rows, it's not adding information; use plain text for common states and reserve badges for the exceptional ones."},{"guidance":false,"description":"Make badges clickable; they are read-only indicators. Use a button or link if the user needs to take action."}],"anatomy":[{"name":"Icon","required":false,"description":"An optional leading icon that helps identify the badge type at a glance."},{"name":"Label","required":true,"description":"The text or number shown inside the badge."}]},"theming":{"targets":[{"className":"astryx-badge","visualProps":["variant"]}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"label":"Badge","variant":"neutral"}}},{"name":"Banner","displayName":"Banner","moduleName":"Banner","directory":"Banner","importPath":"@astryxdesign/core/Banner","group":null,"category":"Feedback & Status","isHiddenFromOverview":false,"description":"Banner shows a persistent message at the top of a page or section. Use it for form errors, system updates, maintenance notices, or success confirmations that the user needs to see until they act on it.","keywords":["banner","alert","notification","callout","notice","status","message","info","warning","error","success","toast"],"hidden":false,"parentDoc":null,"props":[{"name":"status","type":"'info' | 'warning' | 'error' | 'success'","description":"Status type controlling icon and color.","required":true},{"name":"title","type":"ReactNode","description":"Title text or ReactNode displayed in the header.","required":true},{"name":"description","type":"ReactNode","description":"Description text rendered below the title in the header."},{"name":"icon","type":"ReactNode","description":"Override the default status icon.","slotElements":[{"__element":"Icon","props":{"icon":"check","size":"sm"}}]},{"name":"isDismissable","type":"boolean","description":"Whether the banner can be dismissed by the user.","default":"false"},{"name":"onDismiss","type":"() => void","description":"Called when the dismiss button is clicked; banner hides itself regardless of whether this is provided."},{"name":"endContent","type":"ReactNode","description":"Action content rendered in the header area, end-aligned. Typically a button or link.","slotElements":[{"__element":"Icon","props":{"icon":"chevronDown","size":"sm"}},{"__element":"Badge","props":{"label":"3"}}]},{"name":"container","type":"'card' | 'section'","description":"Container type: card has border-radius; section is full-width with no border-radius for page-level use.","default":"'card'"},{"name":"children","type":"ReactNode","description":"Content rendered in the card-background area below the colored header."},{"name":"xstyle","type":"StyleXStyles","description":"StyleX styles for layout customization (margins, positioning, sizing). Must be a stylex.create() value, not an inline style object like style={{}}."}],"usage":{"description":"Banner shows a persistent message at the top of a page or section. Use it for form errors, system updates, maintenance notices, or success confirmations that the user needs to see until they act on it.","bestPractices":[{"guidance":true,"description":"Pick a status that matches the message: info for updates, warning for caution, error for problems, success for confirmations."},{"guidance":true,"description":"Use the card container inside page content and the section container for full-width messages that span the entire page."},{"guidance":true,"description":"Make info and success banners dismissable. Keep error banners visible until the user fixes the issue."},{"guidance":true,"description":"Keep titles short and scannable: \"Payment failed\" not \"There was a problem processing your most recent payment.\""},{"guidance":false,"description":"Use Banner for short-lived messages that disappear on their own; use Toast instead."},{"guidance":false,"description":"Stack multiple banners with the same status; combine related messages into one banner."}],"anatomy":[{"name":"Icon","required":true,"description":"Automatically set based on the status (info, warning, error, success)."},{"name":"Title","required":false,"description":"The main message. Required if no description is provided."},{"name":"Description","required":false,"description":"Additional detail below the title. Required if no title is provided."},{"name":"Action button","required":false,"description":"A button for the user to act on the message, like \"Review\" or \"Retry\"."},{"name":"Dismiss button","required":false,"description":"Lets the user close the banner. Enabled by setting isDismissable."},{"name":"Collapsible content","required":false,"description":"Extra detail that expands below the banner header, like a list of errors."}]},"theming":{"targets":[{"className":"astryx-banner","visualProps":["container","status"]},{"className":"astryx-banner-icon","visualProps":["status"]}],"vars":[{"name":"--_banner-radius","description":"Border radius (card container only)","default":"var(--radius-container)","private":true}],"derived":[{"property":"borderRadius","vars":["--_banner-radius"]}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":{"defaults":{"title":"System maintenance scheduled","description":"The platform will be briefly unavailable on Sunday from 2–4 AM PST.","status":"info"}}},{"name":"BaseTypeahead","displayName":"Base Typeahead","moduleName":"BaseTypeahead","directory":"Typeahead","importPath":"@astryxdesign/core/Typeahead","group":"Typeahead","category":"Data Input","isHiddenFromOverview":true,"description":"Unstyled combobox engine providing input, search, keyboard navigation, and dropdown. No wrapper div, no border styling, no token rendering. Used by Typeahead and Tokenizer for custom compositions.","keywords":["typeahead","autocomplete","combobox","searchbox","autosuggest","select","dropdown","lookup","searchable","suggestion","picker"],"hidden":false,"parentDoc":"Typeahead","props":[{"name":"searchSource","type":"SearchSource","description":"Data source providing search and bootstrap methods.","required":true},{"name":"value","type":"T | null","description":"Currently selected item.","required":true},{"name":"onChange","type":"(item: T | null) => void","description":"Called when the selection changes.","required":true},{"name":"renderItem","type":"(item: T) => ReactNode","description":"Custom render function for dropdown items."},{"name":"placeholder","type":"string","description":"Input placeholder text.","default":"'Search...'"},{"name":"hasEntriesOnFocus","type":"boolean","description":"Show bootstrap results on focus before typing.","default":"false"},{"name":"maxMenuItems","type":"number","description":"Maximum dropdown items to display.","default":"10"},{"name":"emptySearchResultsText","type":"string","description":"Text shown when search returns no results.","default":"'No results found'"},{"name":"isDisabled","type":"boolean","description":"Whether the input is disabled.","default":"false"},{"name":"hasAutoFocus","type":"boolean","description":"Auto-focus the input on mount.","default":"false"},{"name":"debounceMs","type":"number","description":"Debounce delay in ms before triggering search. Set to 0 for synchronous sources.","default":"150"},{"name":"anchorRef","type":"RefObject","description":"Ref to the anchor element for dropdown positioning. If not provided, the input itself is used."},{"name":"inputXStyle","type":"StyleXStyles","description":"Additional StyleX styles for the input element."},{"name":"onKeyDown","type":"(e: React.KeyboardEvent) => void","description":"Additional keydown handler called before internal keyboard navigation. Call e.preventDefault() to skip internal handling."},{"name":"onChangeQuery","type":"(query: string) => void","description":"Callback fired when the search query text changes."},{"name":"onOpenChange","type":"(isOpen: boolean) => void","description":"Callback when the dropdown opens or closes."},{"name":"inputId","type":"string","description":"ID for the input element (for label association)."},{"name":"ariaDescribedBy","type":"string","description":"Additional aria-describedby IDs."}],"usage":{"description":"Unstyled combobox engine providing input, search, keyboard navigation, and dropdown. No wrapper div, no border styling, no token rendering. Used by Typeahead and Tokenizer for custom compositions."},"theming":{"targets":[{"className":"astryx-typeahead","visualProps":["status"]},{"className":"astryx-typeahead-dropdown"},{"className":"astryx-typeahead-item"}]},"params":null,"returns":null,"relatedComponents":null,"relatedHooks":null,"playground":null},{"name":"Blockquote","displayName":"Blockquote","moduleName":"Blockquote","directory":"Blockquote","importPath":"@astryxdesign/core/Blockquote","group":null,"category":"Content","isHiddenFromOverview":false,"description":"A styled quotation block with an accent-colored left border and secondary text color. Use to highlight quoted content, testimonials, or excerpts.","keywords":["blockquote","quote","citation","pullquote","quotation","cite","excerpt"],"hidden":false,"parentDoc":null,"props":[{"name":"children","type":"ReactNode","description":"Content of the blockquote.","required":true},{"name":"cite","type":"ReactNode","description":"Optional attribution for the quote. Rendered in a

Usage

Usage