@antscorp/antsomi-ui-v2

React 19 UI facade and shared high-level components for Antsomi internal admin products such as Cook ZMA, Media Template, CDP, and Object Management.

This package directly re-exports the public @astryxdesign/core API. Existing Astryx primitives keep their original identity and props; Antsomi-owned components are added only when an internal product pattern needs a reusable composition.

Scope

• For Antsomi internal web dashboards.
• Requires React 19, React DOM 19, and StyleX 0.19.
• Uses the approved antsomi-light theme. An Antsomi dark theme is not claimed yet.
• Generated Zalo Mini App source must use its own ZMA component system and must not import this package.

Install and initialize

yarn add @antscorp/antsomi-ui-v2 react@^19 react-dom@^19 @stylexjs/stylex@^0.19

Import the stylesheet once and place the provider at the application root:

import {AntsomiProvider} from "@antscorp/antsomi-ui-v2";
import "@antscorp/antsomi-ui-v2/styles.css";

export function AppRoot() {
  return <AntsomiProvider locale="vi-VN"><App /></AntsomiProvider>;
}

The inherited Neutral Theme uses Figtree. Applications should load that font or intentionally accept the documented system fallback stack.

Astryx facade

Import Astryx primitives from the Antsomi package without wrappers:

import {Button} from "@antscorp/antsomi-ui-v2";

<Button label="Publish version" variant="primary" />;

Admin layout and headless data boundary

Use AntsomiAppShell for the shared two-level admin frame. It composes the re-exported Astryx AppShell with the approved Antsomi structure: a 70px primary rail, a 57px header, an optional 220px secondary navigation, and the legacy white content surface with a 15px gutter and 10px radius.

import {AntsomiAppShell} from "@antscorp/antsomi-ui-v2";

<AntsomiAppShell
  isSecondaryNavigationCollapsed={isSectionNavigationCollapsed}
  topNavigation={<AdminHeader account={accountViewModel} />}
  primaryNavigation={<ProductNavigation items={productNavigationViewModel} />}
  secondaryNavigation={<SectionNavigation items={sectionNavigationViewModel} />}
>
  <ProjectPage />
</AntsomiAppShell>;

Secondary-navigation visibility is controlled by the consumer through isSecondaryNavigationCollapsed; the shell does not own routing or menu state.

AntsomiAppShell is presentational. It must not fetch menu items or interpret an Antsomi API response. A separate headless package or the consuming application owns authentication, permissions, API calls, caching, route matching, and normalization; it passes ready-to-render slots or a stable view-model into UI components.

Antsomi-owned components

AgentRunStatus presents an AI run state; orchestration and polling stay in the application:

import {AgentRunStatus} from "@antscorp/antsomi-ui-v2";

<AgentRunStatus status="running" label="Cooking screens" />;

MobilePreviewFrame supplies responsive preview chrome only; it does not execute ZMA code:

import {MobilePreviewFrame} from "@antscorp/antsomi-ui-v2";

<MobilePreviewFrame label="Checkout preview">
  <CheckoutScreen />
</MobilePreviewFrame>;

Storybook

Storybook documents Antsomi-owned components plus a selected Astryx Core (Antsomi Light) catalog. The local Core stories reuse Astryx components unchanged and render them inside AntsomiProvider; they do not copy or fork Astryx source.

yarn storybook
yarn storybook:build

Legacy core migration

The legacy package's foundational Ant Design wrappers are not reintroduced as compatibility components. Use the existing Astryx facade export instead: for example, Flex and Space become Stack, InputNumber becomes NumberInput, Tag becomes Token, and Spin becomes Spinner. The Astryx Core (Antsomi Light) Storybook catalog shows the supported migration set under the Antsomi theme.

After a consumer has registered this package as an Astryx integration, the same mapping is available to developers and AI agents through its reference docs:

astryx docs antsomi-ui-v2-legacy-core-migration

Specialized legacy components such as InputDynamic, ContentEditable, and the notification hooks require a dedicated product API decision before they are added to v2; they are not generic core primitives.

Figma provenance

The initial semantic colors come from Figma file LSdFN0epxQNuKv9bsZ3XT3, node 464:1040. Confirmed values and inferred-but-not-promoted measurements are recorded separately in src/theme/figma-provenance.ts so agents do not treat visual estimates as global tokens.

Source: https://www.figma.com/design/LSdFN0epxQNuKv9bsZ3XT3/UI--UX-2.0---Component--Copy-?node-id=464-1040&m=dev

AI and Astryx integration

Consumer projects can register this package as an Astryx integration:

import type {AstryxConfig} from "@astryxdesign/cli/authoring";

export default {
  integrations: ["@antscorp/antsomi-ui-v2"],
} satisfies AstryxConfig;

Agents and developers can then discover the custom layer with:

astryx search agent status
astryx component AgentRunStatus
astryx docs antsomi-ui-v2-legacy-core-migration
astryx validate-integration @antscorp/antsomi-ui-v2

Each custom component has a structured .doc.ts contract. The integration manifest points Astryx tooling at those docs without duplicating the full Astryx primitive catalog.

Local verification

Use Node 22.13 or newer. This repository currently verifies with Node 22.22.2.

yarn install
yarn verify

verify runs unit tests, TypeScript, generated-theme drift checks, the library build, static Storybook, Astryx integration validation, and an npm pack dry run.

This implementation builds and validates the package locally. It does not publish the package or modify downstream applications.