Databricks AppKit UI (React component layer)

Category: Tech Stack · Areas: ui

Description

Areas

Platform

Platform-specific (Databricks). @databricks/appkit-ui is the React component library Databricks publishes for Databricks Apps, alongside the @databricks/appkit Node/Express server SDK. This concern covers the component library used standalone: inside a frontend-framework filler (typically react-vite) with a non-Node backend such as Python on databricks-apps. It does not cover @databricks/appkit. Facts below are as of 2026-10-01.

Boundary

This concern owns the choice and use of @databricks/appkit-ui as the product’s React component layer: the package (and the exclusion of the Node SDK), version pinning, what the library brings and which parts a standalone app uses, the token and theme posture, and the open question of standalone support. It must not duplicate its neighbors:

ux-interaction-patterns owns neutral keyboard, navigation and focus behavior, composed automatically for this concern. AppKit owns the installed component layer here. ux-radix owns the alternative copied shadcn/Radix prescription; it need not be selected just to obtain behavioral rules. packaged-design-system covers another project-selected npm component owner. Resolve competing prescriptions in project overrides.
frontend-framework (react-vite) owns the build, routing, environment exposure, and component tests; frontend-architecture owns the server-state pattern that feeds AppKit UI’s data components.
databricks-apps owns hosting, identity, and the backend’s /api/* routes. This concern never assumes AppKit server routes exist.
a11y-wcag-aa owns accessibility compliance; AppKit UI’s Radix base is a starting point, not evidence of compliance.
@databricks/appkit (the Node/Express SDK with plugins, /api/<plugin> routes, and /health) is out of scope. A project that adopts it is choosing a different backend and records that in an ADR.

Components

Package: @databricks/appkit-ui, version 0.82.0 as of 2026-10-01; 0.x and fast-moving. Peer dependency: React 18 or 19.
UI primitives: shadcn/Radix-based components.
Styling: Tailwind CSS 4; @databricks/appkit-ui/styles.css defines OKLCH CSS variables (--background, --primary, --destructive, --success, --warning, --chart-1 to --chart-5, --sidebar-*, --radius) for light and dark themes.
Data components: ECharts-based data components with two modes: data mode (the app passes data in) and query mode (bound to AppKit server queries).
Hooks: query and stream hooks; whether they work without the AppKit server is part of the standalone spike.
Not included: @databricks/appkit, its plugins, and its generated types.

Constraints

The component layer only, never the Node SDK

package.json lists @databricks/appkit-ui and does not list @databricks/appkit. Nothing in the frontend imports from @databricks/appkit.

Pin exactly; upgrade as a reviewed change

The version is exact ("0.82.0", no ^ or ~) and the lockfile is committed, because a 0.x minor release may break the API.
An upgrade is its own change: read the release notes, run the component tests, and check affected screens in both themes before merging.

Data mode, fed by the project’s API

Charts and data components run in data mode, receiving data from the frontend’s server-state layer, which calls the project’s own /api/* routes.
Query-mode components are not used, because query mode is bound to AppKit server queries. The query/stream hooks are not used unless the standalone spike shows a hook works against the project’s API.

Tokens and themes

Import @databricks/appkit-ui/styles.css once at the app root. Brand or product changes override the CSS variables, never component internals.
Every token override is made for both light and dark themes; components and charts reference tokens (--chart-1 to --chart-5 for series), never raw color values.
DESIGN_SYSTEM records the token overrides and the theme switch mechanism.

One component library

AppKit UI is the component library. A component it lacks is a shadcn component copied and themed with AppKit tokens; never a second library (MUI, Chakra, Mantine, Ant Design) and never a parallel token set.

Standalone use is undocumented

Databricks documents AppKit UI together with the AppKit server; standalone use with a non-Node backend is plausible (data mode exists; the peer dependencies are only React) but neither documented nor endorsed as of 2026-10-01.
Selecting this concern requires the AppKit UI standalone spike before the design commits: build a react-vite app with AppKit UI and no AppKit server; record the bundle size, the Tailwind 4 integration steps, which components or hooks call /api/<plugin> or /health, and whether theme switching works.

Drift Signals (anti-patterns to reject in review)

import ... from "@databricks/appkit" or the package in package.json → @databricks/appkit-ui only; the backend is the project’s own
"@databricks/appkit-ui": "^0.82.0" or ~ → an exact version
An upgrade bundled into a feature change → a separate reviewed change
A query-mode component or AppKit hook calling /api/<plugin>/... the backend does not serve → data mode fed by the project’s /api/*
A second component library alongside AppKit UI → AppKit UI, plus copied shadcn for gaps
A copied shadcn component duplicating one AppKit UI ships → use AppKit UI’s
Hex, rgb(), or literal oklch() colors in components or chart options → CSS variables from styles.css
A token overridden for light only → override light and dark together
Custom keyboard or focus handlers on AppKit UI components → keep the Radix behavior, per ux-interaction-patterns
Standalone support treated as settled with no spike result → run and record the spike

When to use

A Databricks-hosted app (databricks-apps selected) with a React frontend (react-vite) and a non-Node backend, where the UI should look native to Databricks and needs data components and charts. Selection signal: a React SPA on Databricks Apps whose backend is Python or another non-Node runtime.

Do not select it for apps hosted off Databricks, for AppKit TypeScript projects scaffolded with databricks apps init (Databricks’ own template governs the package and server there), or for Streamlit, Dash, or Gradio apps.

Artifact Impact

Selecting this concern requires these artifacts to change (a selected concern absent from them is drift):

TD: data-mode components fed by the project’s /api/* through the server-state layer; no AppKit server routes assumed; states @databricks/appkit-ui (exact pin, no Node SDK) as the component library, citing the standalone spike result
IMPLEMENTATION_PLAN: the AppKit UI standalone spike before UI build-out; exact pin and upgrade procedure
DESIGN_SYSTEM: AppKit OKLCH tokens, overrides for light and dark, chart series tokens, shadcn gap components themed with AppKit tokens
TEST_PLAN: affected screens checked in both themes; keyboard and focus behavior per ux-interaction-patterns

ADR References

Selecting this concern needs no ADR; concerns.md records it. Write an ADR only when the project deviates from a constraint here.

ADR-011: ux-radix owns the Radix and shadcn component-library prescription; this concern names AppKit UI as the installed distribution of that pattern and records the copy-vs-install resolution as a project override

Practices by activity

Agents working in any of these activities inherit the practices below through runtime work context, such as a DDx bead context digest.

Requirements (Frame activity)

Confirm the app is hosted on Databricks Apps with a React SPA and a non-Node backend; an AppKit TypeScript project follows Databricks’ template instead.
Record the AppKit UI standalone spike as a tech-spike and treat UI design that depends on it as provisional until it reports.
List the data views (charts, tables) the product needs, so the spike checks those components in data mode.
State whether the product needs both light and dark themes at launch; tokens are maintained for both either way.
Identify any brand colors that must override AppKit tokens.

Design

Choose @databricks/appkit-ui at an exact version as the component library; state it in the TD with the spike result.
Feed charts and data components in data mode from the server-state layer that calls the project’s /api/* routes.
Map each needed widget to an AppKit UI component first; only a gap gets a copied shadcn component themed with AppKit tokens.
Define token overrides as CSS variables for light and dark together; chart series use --chart-1 to --chart-5.
Apply ux-interaction-patterns interaction patterns (search, edit, navigation, selection, overlays) to AppKit UI components unchanged.

Implementation

Add @databricks/appkit-ui with an exact version and commit the lockfile; never add @databricks/appkit.
Import @databricks/appkit-ui/styles.css once at the app root, before the app’s own styles.
Put token overrides in one stylesheet, with a light block and a dark block for every overridden variable.
Pass data to data components as props; do not call AppKit query or stream hooks unless the spike proved them against the project’s API.
Reference tokens in chart options and component classes; no literal colors.
Keep the Radix keyboard and focus behavior of AppKit UI components intact.

Testing / Verification

Run the standalone spike and record bundle size, Tailwind 4 setup, any calls to /api/<plugin> or /health, and theme switching.
Component tests (per react-vite) cover data components rendering empty, loading, error, and populated data.
Check affected screens in both light and dark themes for every change that touches tokens or an AppKit UI upgrade.
Verify keyboard and focus behavior per ux-interaction-patterns on screens built from AppKit UI components.
Verify in the browser network panel or e2e that the deployed app calls no AppKit server routes.

Quality Gates

package.json pins @databricks/appkit-ui exactly and does not list @databricks/appkit.
The standalone spike result is recorded and cited by the TD.
No second component library and no literal colors in components or chart options.
Every token override exists for both light and dark themes.
An AppKit UI upgrade lands as its own reviewed change with both themes checked.
Component code stays under the code-shape-ceilings complexity, function-length, and file-size ceilings.

Innsigle seal: model-primary by HELIX

The signature covers the markdown source of this page, not these HTML bytes. This page quotes that seal; verify it against the source file.

Composition: model-primary
Issuer: HELIX helix
Signing key: ed25519:b0865d76d834a52c48506414d16f4e5a (build key)
Signed source: concerns/databricks-appkit-ui.md
Signed: 2026-10-22T18:09:54Z
Content digest: sha256:0f1b2ad6…d34f9bdb

This build key is endorsed by the human key for build signing; the signature is not a detector and not a truth guarantee.

Raw attestation JSON

{
  "payload": {
    "innsigle": "1",
    "type": "https://innsigle.dev/claim/colophon/v1",
    "issued_at": "2026-10-22T18:09:54Z",
    "issuer": {
      "id": "helix",
      "name": "HELIX",
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "key_url": "https://documentdrivendx.github.io/helix/.well-known/innsigle/keys.json"
    },
    "subjects": [
      {
        "uri": "https://documentdrivendx.github.io/helix/concerns/databricks-appkit-ui/",
        "digest": {
          "alg": "sha256",
          "value": "0f1b2ad671ca228b95842a0d2c58cc704e8c822c17a3ddffabaae607d34f9bdb"
        }
      }
    ],
    "colophon": {
      "schema_version": "1",
      "composition": "model-primary",
      "ingredients": [
        {
          "kind": "model",
          "name": "Claude",
          "role": "draft"
        },
        {
          "kind": "tool",
          "name": "sloptimizer",
          "role": "rewrite"
        },
        {
          "kind": "human",
          "name": "operator",
          "role": "structure-edit"
        }
      ],
      "notes": null
    }
  },
  "payload_encoding": "json",
  "signatures": [
    {
      "key_id": "ed25519:b0865d76d834a52c48506414d16f4e5a",
      "alg": "ed25519",
      "sig": "JwpyFUlQoAODtuy-ja4vHNnIfgykcCRa6LZT_lbTFoDuC_GY3zcBkOUIWmN916OwziCiIfg6NuvC5oA3LxBtBQ",
      "signed_at": "2026-10-22T18:09:54Z"
    }
  ]
}

attestation file · issuer keys