Language / 语言: English · 中文

A framework-agnostic design system for task workspaces, document tools, and operational consoles.

A3S UI turns the interaction patterns refined in A3S Office into reusable, semantic HTML. It combines Tailwind CSS v4, native browser elements, and small vanilla JavaScript controllers—without requiring React, Radix, or a framework runtime.

The system now exposes 116 public component contracts. Eighty-six general components cover controls, navigation, content, overlays, and product structure, while the 30-component Harness groups task, conversation, execution, review, evidence, file navigation, knowledge management, editing, terminal, log, and device-preview workflows for Coding Agents.

Install the public package from npm:

npm install @a3s-lab/ui

Load Tailwind and the complete A3S bundle:

@import "tailwindcss";
@import "@a3s-lab/ui";

Applications that do not run Tailwind can load the precompiled bundle instead:

@import "@a3s-lab/ui/cdn.css";

Import the runtime only when the interface uses interactive composites:

import "@a3s-lab/ui/all";

Then compose the interface with semantic markup:

<header class="workspace-header">
  <div data-workspace-identity>
    <h1>Production gateway</h1>
    <span>Configuration saved</span>
  </div>
  <div data-workspace-actions>
    <button type="button" class="btn">Deploy</button>
  </div>
</header>

See the installation guide for split CSS imports, controller-level JavaScript imports, and server-rendered templates.

The optional Dockview integration sits beside the semantic manifest and adds Dock Workspace, Grid View, Split View, and Pane View without changing the 116-component count. It re-exports the complete Dockview 8.1 MIT surface for native TypeScript, React, and Vue, then adds A3S theme tokens, versioned layout persistence, and an Edge Group-safe layout reset.

The integrated Form system adds a deterministic Form Core, visual Designer, controlled Renderer, durable interaction contracts, a Cloud host adapter, CLI, Web Components, React Hook Form integration, and native Vue composables. Its guides and interactive examples live directly in the A3S UI component catalog.

Every component guide includes a live preview, minimal usage, public parameters, states and variants, and accessibility notes. Preview stages derive the correct control, content, overlay, or workspace layout, while phone and tablet modes run in isolated CSS viewports so responsive media queries use the selected width. Browse the complete component catalog.

The A3S theme is a complete design system rather than a palette layered over unrelated controls:

• Color — white and near-black product surfaces with scarce iris focus, A3S brand blue, and reserved semantic states.
• Typography — application-first hierarchy with dense labels and readable long-form documentation.
• Spacing — a consistent rhythm for controls, panels, toolbars, and document canvases.
• Shape and elevation — restrained radii, borders, and shadows that preserve information density.
• Motion — short, purposeful transitions with reduced-motion support.
• Accessibility — semantic elements, explicit ARIA state, keyboard interactions, RTL-aware layout, and light/dark themes.

The task application layer is where A3S UI differs from a primitive-only kit:

App Shell
├── Activity Bar
├── Workspace Header
├── App Page
│   ├── Catalog
│   └── Settings Layout + Setting Row
├── Resource Card + Split Pane + Task Pane
└── Status Bar

Harness
├── Task Start + Task Workspace
├── Agent Composer + Agent Transcript + Agent Workbench
├── Task Plan + Plan Step + Task Queue
├── Approval Request + Execution Item + Tool Call
├── Change Review + Execution Evidence + Artifact Card + Checkpoint
└── File Explorer + Code Editor + Terminal + Log Viewer + Device Simulator

Dockview integration
├── Dock Workspace + Tabs + Tab Groups + Edge Groups
├── Floating Groups + Popout Windows + maximize/restore
├── Save/restore + custom state + complete event API
└── Grid View + Split View + Pane View

These patterns are independently reusable, but their tokens and layout contracts are designed to compose into document editors, task workspaces, and observability consoles. The default task geometry uses a 248-pixel navigation region, a 760-pixel reading column, a 320–380-pixel optional inspector, 36-pixel controls, and 44-pixel coarse-pointer targets. Responsive navigation becomes a contained drawer below 768 pixels; inspectors become overlays below 900 pixels and bottom drawers below 520 pixels.

Device Simulator preserves exact iframe viewport dimensions inside scaled phone, tablet, and desktop hardware shells, then exposes a structured native-preview boundary for trusted a3s-webview hosts.

The bilingual pattern guides cover Task Workspace, New Task, Capability Catalog, Settings Center, Projects, and Automations. Applications continue to own repository, terminal, browser, transport, scheduling, persistence, and policy logic.

The standalone Playground is a bilingual, task-first A3S product application rather than a component showcase or dockable IDE. Its canonical /playground route family combines durable task and project sessions, a TipTap-based composer, model and effort controls, workspace references, follow-up queues, permission review, tool-call evidence, Finder-style local files, code and Office/PDF workbenches, Knowledge, Memory, screenshot-led Inspiration workflows, extensions, automations, and production settings in one coherent desktop and compact-screen flow. Legacy /app URLs remain route aliases. The Playground stays outside the documentation chapter hierarchy.

The documentation site uses the same Rspress, React, and TypeScript stack as the A3S Code website. Simplified Chinese is the default language; every published version also provides English documentation. Every current component and Harness integration guide presents HTML, React, and Vue through one persistent tab set with framework-correct installation, required imports, highlighted copyable examples, and matching hooks or composables where the public contract has behavior.

Language and version switches preserve the current page whenever that route exists in the destination tree.

The public runtime namespace is window.a3sUI. Legacy runtime aliases remain available for compatibility.

The optional semantic runtime annotates matching roots with data-a3s-components, parts with data-a3s-parts, exact part ownership with data-a3s-part-owners, and current state with data-a3s-state. It does not replace application behavior or introduce a framework runtime. See the bilingual Integration guide for native HTML, React, Vue, and deterministic test examples.

React and Vue also expose useA3SLocale, useA3STheme, and useA3SMotion. These hooks and composables observe the same root lang, dir, data-theme, .dark, and media-query contract as native HTML; translation resources, persistence, and server negotiation remain application-owned.

The runtime also keeps open [data-popover] surfaces inside the visual viewport. Dropdown menus, popovers, selects, and comboboxes share collision flipping, constrained available height, live scroll/resize positioning, and logical RTL alignment.

npm ci
npm ci --prefix site
npm run build
npm run check:coverage:strict
npm run check:framework-docs
npm run check:boundaries
npm run check:package
npm run docs:build
npm run test:e2e:a3s:check
npx playwright install chromium
npm run test:visual

Run the documentation site locally with npm run docs:dev. The static build is written to site/doc_build and deployed to GitHub Pages from main.

Run the component- and route-specific browser suites with npm run test:e2e:a3s. Reported defect classes are retained as page-level A3S Test regressions with action-state assertions, screenshots, console output, and page-error evidence. Scenarios run serially by default so stateful previews stay deterministic; set A3S_TEST_MAX_PARALLEL only when the browser adapter has enough isolated capacity. The command expects a3s-test on PATH; use A3S_TEST_BIN, A3S_TEST_BROWSER_DRIVER, and A3S_TEST_BROWSER_EXECUTABLE when a local adapter needs explicit paths.

The release contract currently maps 116 public components, 94 Playground exports, and 20 Harness or Playground surfaces to 230 substantive PRDs. The checked ACL inventory and evidence totals live in product-requirements/README.md. npm run test:e2e:a3s:check rejects missing, duplicate, shallow, stale, or invalid mappings before a browser run; the machine-readable indexes live under product-requirements/.

Visual checks use Playwright with platform-specific desktop and compact baselines. Every public component route also has a component-root geometry and state contract plus browser diagnostic coverage. Set A3S_UI_VISUAL_CHROMIUM_EXECUTABLE to reuse a system Chromium installation and A3S_UI_VISUAL_PORT when the default local port is occupied; these checks are intentionally not part of CI.

A3S UI builds on Basecoat, created by Ronan Berder, and retains its semantic HTML interpretation of the shadcn/ui visual language. The A3S theme and workbench components extend that foundation for A3S products.

Released under the MIT License.