@axonyx/ui

v0.0.71

Published

a day ago

Framework-agnostic CSS and JS package for Axonyx UI Foundry.

0High
0Medium
0Low

vladan-pro

axonyx ui css design-system foundry web-components react

Axonyx UI

Axonyx UI is the design-system layer for the Axonyx ecosystem.

Website: https://axonyx.dev

It is built on the Foundry design language: a system-oriented visual language for builders, with engineered surfaces, signal-driven states, and metal-inspired themes.

Purpose

Axonyx UI defines the visual contract for Axonyx primitives so projects like axonyx-site, static HTML pages, and React adapters can import a stable, reusable UI layer instead of carrying page-specific styling.

axonyx-ui       = CSS tokens, themes, component styles, JS islands, native .asx Foundry components
@axonyx/react   = React wrappers around the same shared CSS/data-attribute contract
axonyx-site     = Axonyx-native app routes that consume the Foundry components
axonyx-site-ui  = native Axonyx UI showcase and registry documentation

Install

npm

npm install @axonyx/ui

Load the stylesheet once in your shell/layout:

<link rel="stylesheet" href="/_ax/pkg/axonyx-ui/index.css" />
<script src="/_ax/pkg/axonyx-ui/js/index.js" defer></script>

React apps usually import it once from the app root:

import "@axonyx/ui/css/index.css";

Cargo

axonyx-ui is also published as a Cargo asset crate for Axonyx-native tooling:

[dependencies]
axonyx-ui = "0.0.53"

The Cargo crate embeds the same Foundry assets that the npm package ships. Axonyx-native apps should use cargo ax add ui so the stylesheet and Foundry behavior runtime are wired into app/layout.asx.

Registry V0

Axonyx.registry.toml describes the first native registry slice:

Components V0: Button, Card, Field, AppShell, Sidebar
Blocks V0: marketing-01, docs-01, dashboard-01, login-01, settings-01

The long-term CLI goal is:

cargo ax add button
cargo ax add block dashboard-01
cargo ax add theme silver

For now the Cargo crate embeds registry data and block source files so cargo-axonyx can later install them without scraping GitHub or npm.

Foundry

Foundry is the design language behind Axonyx UI.

Core ideas:

engineered surfaces instead of floating paper
signal-driven accent color instead of decorative color usage
structured dark foundations for serious interfaces
semantic primitives that map cleanly from .asx
theme finishes inspired by metal: Bronze, Silver, and Gold
industrial controls such as status lamps and machine-style switches, used sparingly where state matters

Initial Scope

The stable primitive set is growing around:

Container, Grid, Section, Stack, Cluster
Card, Copy, Button, ButtonGroup, Badge, Chip, Avatar, Divider
Alert, StatusLamp, Stat, Progress, Skeleton, EmptyState
Field, Input, Textarea, Select, Checkbox, Radio, Switch
Breadcrumbs, Tabs, Accordion, DropdownMenu, Dialog, Popover, Drawer, Tooltip, Toast
CodeBlock, CommandList, PropsTable, Table, List, Pagination
Icon, ThemeSwitcher, MachineSwitch

The first themes are:

bronze
silver
gold

Theme Model

Themes do not change component structure.

They only change token values such as:

background
surface
border
text
accent
link
panel treatment

Theme is applied at the document root:

<html data-theme="silver">

Projects should load one global stylesheet in the shell or layout, not inside each page body.

Rendering Contract

The first stable Foundry contract for .asx primitives is:

Container max: "xl" -> <div class="ax-container" data-max="xl">
Grid cols: 2, gap: "lg" -> <div class="ax-grid" data-cols="2" data-gap="lg">
Card title: "..." -> <article class="ax-card"><h2 class="ax-card__title">...</h2>...
Copy tone: "lead" -> <p class="ax-copy" data-tone="lead">...</p>
Copy -> "..." -> <p class="ax-copy">...</p>

CSS Files

src/css/index.css currently imports:

src/css/
  tokens.css
  themes.css
  layout.css
  section.css
  card.css
  copy.css
  links.css
  stack.css
  nav.css
  button.css
  button-group.css
  badge.css
  chip.css
  avatar.css
  divider.css
  workspace.css
  cluster.css
  form.css
  field.css
  select.css
  theme-switcher.css
  choice.css
  radio.css
  breadcrumbs.css
  command.css
  code-block.css
  tabs.css
  accordion.css
  dropdown.css
  tooltip.css
  overlay.css
  component-preview.css
  props-table.css
  data.css
  alert.css
  dialog.css
  icons.css
  machine-switch.css
  status-lamp.css
  stat.css
  list.css
  pagination.css
  index.css

MachineSwitch CSS contract

MachineSwitch is an industrial red/green control for feature flags, deploy state, maintenance mode, and runtime demos.

The CSS contract can be used directly by Axonyx-native or static HTML output:

<button class="ax-machine-switch" data-state="on" type="button" aria-pressed="true">
  <span class="ax-machine-switch__controls">
    <span class="ax-machine-switch__pad" data-tone="danger" data-active="false">OFF</span>
    <span class="ax-machine-switch__pad" data-tone="success" data-active="true">ON</span>
  </span>
  <span class="ax-machine-switch__label">Deploy gate</span>
  <span class="ax-machine-switch__label" data-state="true">Online</span>
</button>

React users should use MachineSwitch from @axonyx/react/client.

Foundry .asx Components

The package also exposes importable .asx components for Axonyx apps. Source files live in src/foundry/ and are copied to dist/foundry/ during npm run build, so published packages can be imported through the same public namespace:

Action and navigation semantics stay explicit even when they share the same Foundry styling:

<Button on:click={count += 1}>Increase</Button>
<Button type="submit">Save</Button>
<LinkButton href="/docs">Read docs</LinkButton>

Button renders a semantic <button type="button"> by default. Use LinkButton when the control changes location.

src/foundry/
  Container.asx
  Grid.asx
  Card.asx
  Copy.asx
  Badge.asx
  Chip.asx
  Avatar.asx
  Divider.asx
  Field.asx
  Input.asx
  Textarea.asx
  Select.asx
  Option.asx
  Checkbox.asx
  Radio.asx
  Switch.asx
  Breadcrumbs.asx
  ButtonGroup.asx
  Spinner.asx
  Toggle.asx
  ToggleGroup.asx
  InputGroup.asx
  InputAddon.asx
  Combobox.asx
  ComboboxOption.asx
  AlertDialog.asx
  NavigationMenu.asx
  NavigationMenuList.asx
  NavigationMenuLink.asx
  ScrollArea.asx
  LinkButton.asx
  IconButton.asx
  Alert.asx
  Accordion.asx
  AccordionItem.asx
  DropdownMenu.asx
  DropdownItem.asx
  DropdownLabel.asx
  DropdownSeparator.asx
  Dialog.asx
  Popover.asx
  Drawer.asx
  Toast.asx
  ToastViewport.asx
  MachineSwitch.asx
  Section.asx
  Cluster.asx
  AppShell.asx
  Sidebar.asx
  Table.asx
  List.asx
  ListItem.asx
  EmptyState.asx
  Skeleton.asx
  Progress.asx
  StatusLamp.asx
  Stat.asx
  Pagination.asx
  Tooltip.asx
  SiteShell.asx
  HeroCard.asx
  ContentGrid.asx
  Stack.asx
  SectionCard.asx
  Button.asx
  TextLink.asx
  FeatureSection.asx
  ComponentPage.asx
  PageHeader.asx
  DocsSection.asx
  DocsCallout.asx
  DocsNav.asx
  DocsCodeBlock.asx
  Command.asx
  CommandList.asx

Sidebar can collapse its navigation on narrow viewports while remaining a normal rail on desktop:

<Sidebar label="Component navigation" collapsible="true">
  <nav>...</nav>
</Sidebar>

Foundry Blocks

The first block source files live in src/blocks/:

src/blocks/
  marketing-01.asx
  docs-01.asx
  dashboard-01.asx

Blocks are intended to install as editable app source, not opaque widgets. They compose existing Foundry components and remain Axonyx-native.

Cargo consumers can inspect embedded assets:

for asset in axonyx_ui::block_assets() {
    println!("{}", asset.path);
}

let registry = axonyx_ui::registry_manifest();

Example import:

import { SectionCard } from "@axonyx/ui/foundry/SectionCard.asx"

All Foundry .asx files use the same importable page-component shape expected by current Axonyx tooling:

import { Alert } from "@axonyx/ui/foundry/Alert.asx"
import { MachineSwitch } from "@axonyx/ui/foundry/MachineSwitch.asx"

<Alert tone="warning" title="Beta API">
  This contract can still change before 1.0.
</Alert>

<MachineSwitch
  label="Deploy gate"
  stateLabel="Online"
  pressed="true"
  offActive="false"
  onActive="true"
/>

Cargo consumers also get this namespace contract through Axonyx.package.toml. Axonyx tooling reads that metadata to map @axonyx/ui to the packaged src/ export root.

Cargo Package

axonyx-ui is also shaped as a Cargo asset crate for Axonyx-native tooling. The crate embeds the same Foundry assets that the npm package ships:

css/* for the global Foundry stylesheet contract
js/* for the Foundry behavior runtime and progressive-enhancement helpers
foundry/*.asx for Axonyx-native UI components

Build tools can read these through css_assets(), js_assets(), foundry_assets(), or asset("foundry/Button.asx") without requiring npm.

React to Axonyx adapter coverage lives in:

docs/react-ax-adapter-map.md

Named slot example:

import { FeatureSection } from "@axonyx/ui/foundry/FeatureSection.asx"

<FeatureSection title="Build with slots">
  <Copy slot="eyebrow">Foundry</Copy>
  <Copy>Default body content still flows through the main slot.</Copy>
  <a slot="actions" href="/docs">Open docs</a>
</FeatureSection>