Core

Fourteen Categories Types Capabilities Runtime Entry Points

1. 1Visualtypes/visual.ts
   →
2. 2Sizetypes/size.ts
   →
3. 3Tokenstypes/tokens.ts
   →
4. 4Layouttypes/layout.ts
   →
5. 5Statetypes/state.ts
   →
6. 6Interactiontypes/interaction.ts
   →
7. 7Capabilitiestypes/capabilities.ts
   →
8. 8Formtypes/form.ts
   →
9. 9Typographytypes/typography.ts
   →
10. 10Eventstypes/events.ts
    →
11. 11Datatypes/data.ts
    →
12. 12Mediatypes/media.ts
    →
13. 13Runtimeconfig · i18n · errors · files · logging
    →
14. 14Settingsstorage/keys.ts

• Visualtypes/visual.ts

  Semantic Variants And Surface Treatments

  XVariantXColorXAppearance
• Sizetypes/size.ts

  Control Scale And Intrinsic Sizing Keywords

  XSizeXWidthXHeight
• Tokenstypes/tokens.ts

  Primitive Steps Aligned With Xngui Styles

  XSpacingStepXRadiusStepXShadowStepXSemanticToken
• Layouttypes/layout.ts

  Flex And Overlay Placement

  XOrientationXAlignXJustifyXPlacementXPositionXTextAlignXTextDirection
• Statetypes/state.ts

  Contracts And Feedback Status

  XDisabledXLoadingModeXStatusXVisibility
• Interactiontypes/interaction.ts

  Triggers Activation Scroll

  XTriggerXActivationXButtonTypeXScrollStrategyXFocusOriginXAriaLive
• Capabilitiestypes/capabilities.ts

  Signal Implements Contracts For Components

  XDisableableXLoadingXOpenBoundXPaginatedXKeySelectionXToastHost
• Formtypes/form.ts

  Options Validation And Form Chrome

  XOptionXLabelModeXFormLookXValidateOnXValidationState
• Typographytypes/typography.ts

  Type Scale And Text Treatment Unions

  XTextSizeXFontWeightXTextTransformXTextOverflow
• Eventstypes/events.ts

  Component Output Payloads

  XChangeEventXClickEventXSelectionEventXPageEventXSortEventXFocusEventXBlurEvent
• Datatypes/data.ts

  Headless Data Pipeline

  XDataQueryXDataResultXDataLoaderXDataStatusXFilterXSortXSelectionState
• Mediatypes/media.ts

  Adornments Avatars And Media Fit

  XIconPositionXIconSizeXAvatarShapeXImageFit
• Runtimeconfig · i18n · errors · files · logging

  Secondary Entry Points For App Bootstrap

  provideXXConfigServiceXTranslationServiceXErrorHandlerServiceXFileService
• Settingsstorage/keys.ts

  Cross Package Storage Keys

  X_STORAGE_KEYSXLocalStorageServiceXIndexedDbService

• XVarianttype

  Component Variant Input

  primarysecondaryaccentdangersuccesswarninginfo
• XColortype

  Palette Token Family Key

  primarysecondaryaccentneutralsuccesswarningdangerinfo
• XAppearancetype

  Surface Treatment For Controls

  solidoutlineghostsoft
• XDensitytype

  Standard baseline; comfortable is roomier, compact is tighter chrome spacing.

  compactcomfortablestandard

Xvariant Semantic Roles For Actions And Status Bearing Ui

Xappearance Surface Treatments Paired With Xvariant

Xcolor Includes Neutral For Chrome Unlike Xvariant

Five Steps Shared Across Buttons Inputs Chips And More

• xsxs
• smsm
• mdmd
• lglg
• xlxl

XDensity adjusts spacing chrome only — padding, gap, and control height offsets — without changing type or icon size. Pair with XSize on interactive components. Live CSS tokens are documented on the control scale on the Styles page.

Xplacement Twelve Anchored Positions For Overlays Tooltips And Menus

Xorientation Xalign Xjustify In Context

• XDisabledinterface

  Disabled Boolean Contract

• XLoadingModetype

  spinneroverlayreplace
• XStatustype

  neutralinfosuccesswarningdanger
• XVisibilitytype

  visiblehidden

Component Output Handlers Never Raw Event Unless Wrapped

• XChangeEvent<T>{ value, previousValue? }
  event.ts

  { "value": "dark", "previousValue": "light" }

• XClickEvent<T>{ originalEvent }
  event.ts

  { "originalEvent": "PointerEvent" }

• XSelectionEvent<T>{ added, removed }
  event.ts

  { "added": ["a"], "removed": [] }

• XPageEvent{ pageIndex, pageSize, length }
  event.ts

  { "pageIndex": 0, "pageSize": 25, "length": 120 }

• XSortEvent{ sort }
  event.ts

  { "sort": { "active": "name", "direction": "asc" } }

• XFocusEvent{ origin }
  event.ts

  { "origin": "keyboard" }

• XBlurEvent{ originalEvent? }
  event.ts

  { "originalEvent": "FocusEvent" }

1. QueryXdataquery Page Sort Filter Snapshot
   ↓
2. LoaderXdataloader T Sync Or Async With Abortsignal
   ↓
3. ResultXdataresult T Items Total Count
   ↓
4. StatusXdatastatus Idle Loading Success Error

Components Opt Into Shared Behavior With

• XDisableableinterface

  Disabled Input Group Parents May Pass Undefined To Inherit

• XLoadinginterface

  Loading Input With Aria Busy Semantics

• XOpenBoundinterface

  Declarative Overlays Dialog Drawer Alert Dialog

• XAnchorBoundinterface

  Floating Surfaces Anchored To An Origin Menu Popover

• XPaginatedinterface

  Page Index Size With Navigation Helpers

• XKeySelectioninterface

  String Key Selection For Tables And Lists

• XSortableinterface

  Column Sort Stack For Data Tables

• XToastHostinterface

  Imperative Toast Queue Api

• XPlaybackinterface

  Native Audio Video Playback Controls

Structural and semantic token steps are typed in @xngui/core. Use the unions in component APIs and tools like the theme builder — not stringly-typed CSS variable names.

• XColor--x-{role}

  Semantic color roles — bind component variant inputs to theme slots instead of hard-coded hues.

  • CSS tokencolor: var(--x-primary);
  • Component input<x-badge variant="danger" />
  • Tailwind utility<div class="bg-primary text-primary-foreground">
• XSize[data-size]

  Visual tier on interactive hosts — resolves to control height, type, and radius tokens.

  • Host attribute<x-button size="lg" />
  • Resolved token--x-control-height: var(--x-size-height-lg);
  • CSS selectorx-input[data-size="sm"] { … }
• XDensity[data-density]

  Padding and gap offsets — orthogonal to size; never changes type or icon scale.

  • Host attribute<x-button density="compact" />
  • Resolved token--x-control-pad-inline: calc(var(--x-scale-pad-inline) + var(--x-density-offset-pad-inline));
  • Config defaultprovideX({ config: { density: 'comfortable' } })
• XSemanticToken--x-{token}

  Named surface and chrome slots — background, card, border, ring, and related page chrome.

  • Page canvasbackground: var(--x-background);
  • Elevated surfacebackground: var(--x-card); border-color: var(--x-card-border);
  • Type uniontype XSemanticToken = 'background' | 'card' | 'border' | …
• XSpacingStep--x-spacing-{n}

  Tailwind-aligned spacing scale — 4px base unit.

  • Gapgap: var(--x-spacing-4);
  • Marginmargin-block: var(--x-spacing-6);
  • Component input<x-stack gap="3" />
• XRadiusStep--x-radius-{step}

  Corner radius tiers from extra-small through full pill.

  • Card chromeborder-radius: var(--x-radius-lg);
  • Chip or badgeborder-radius: var(--x-radius-full);
  • Type uniontype XRadiusStep = 'xs' | 'sm' | … | 'full'
• XShadowStep--x-shadow-{step}

  Elevation shadows — oklch-based and theme-aware.

  • Popoverbox-shadow: var(--x-shadow-lg);
  • Component input<x-card shadow="md" />
  • Type uniontype XShadowStep = 'sm' | 'md' | 'lg' | 'xl' | '2xl'
• XDurationStep--x-duration-{step}

  Motion duration steps — respect prefers-reduced-motion globally.

  • Transitiontransition-duration: var(--x-duration-fast);
  • Animationanimation-duration: var(--x-duration-normal);
  • Type uniontype XDurationStep = 'fast' | 'normal' | 'slow'
• XOverlayLayer--x-z-{layer}

  Stacking layers for overlays — modal above popover above sticky chrome.

  • Dialogz-index: var(--x-z-modal);
  • Config overrideprovideX({ config: { zIndex: { modal: 60 } } })
  • Type uniontype XOverlayLayer = 'dropdown' | 'modal' | …
• XTextSize--x-text-{size}

  Type scale with paired leading — set both when using primitives directly.

  • Font sizefont-size: var(--x-text-sm);
  • Paired leadingline-height: var(--x-text-sm-leading);
  • Component<x-text size="lg">…</x-text>
• XFontWeight--x-weight-{weight}

  Weight steps from thin through black.

  • CSSfont-weight: var(--x-weight-semibold);
  • Component<x-text weight="medium">…</x-text>
  • Type uniontype XFontWeight = 'normal' | 'medium' | 'bold' | …

Align With Xngui Styles Primitives

Providex From Xngui Core Config Registers

import { provideX } from '@xngui/core/config';export const appConfig = {  providers: [    provideX({      config: { size: 'md', validateOn: 'touched' },      locale: 'en-US',    }),  ],};

Override Once Via

size

mdXSize

density

standardXDensity

variant

primaryXVariant

appearance

outlineXAppearance

labelMode

staticXLabelMode

look

outlineXFormLook

validateOn

touchedXValidateOn

ripple

trueboolean

animate

trueboolean

overlay.placement

bottom-startXPlacement

overlay.closeOnEscape

trueboolean

overlay.closeOnOutside

trueboolean

• @xngui/core/config

  Library Wide Defaults Size Density Validateon Z Index Layers

  provideXprovideXConfigXConfigServiceXConfig
• @xngui/core/i18n

  Flat Translation Keys Locale Persistence And Intl Formatters

  XLocaleServiceXTranslationServiceXIntlServiceXTranslatePipeprovideXTranslations
• @xngui/core/direction

  Runtime Ltr Rtl With Persisted Preference

  XDirectionService
• @xngui/core/errors

  Domain Errors And A Pluggable Global Handler

  provideXErrorHandlerXErrorHandlerServiceXComponentError
• @xngui/core/files

  Pick Extract Validate Read And Download Browser Files

  XFileServiceXBrowserFileServicevalidateFilesdownloadTextpickFiles
• @xngui/core/logging

  Structured Logging With Injectable Backends

  provideXLoggerXLoggerServiceXLogger
• @xngui/core/storage

  SSR-safe localStorage and IndexedDB helpers plus shared persistence keys.

  XLocalStorageServiceXIndexedDbServiceX_STORAGE_KEYS

Use XLocalStorageService for string preferences and XIndexedDbService for larger structured state. Both swallow storage failures and no-op during SSR.

Storage Theme

x-theme

Storage Theme Palette

x-theme-palette

Storage Locale

x-locale

Storage Direction

x-direction

X Storage Keys

x-config