databricks-app-design

Original：🇺🇸 English

Translated

Design the UX of custom-code Databricks Apps (AppKit/React) data screens — KPI/overview pages, reports, charts, tables, and Genie/chat data assistants — mapped to concrete AppKit components. Use when BUILDING or reviewing the UI of an AppKit/React app that displays data or answers data questions: choosing genre, layout, charts, KPIs, semantic color, required states (loading/empty/error), IBCS notation, and AI-result trust (showing generated SQL/sources for Genie/chat). A plain "create a dashboard" request means a managed AI/BI (Lakeview) dashboard → use databricks-aibi-dashboards, NOT this skill. Also NOT for non-data frontend (forms, settings, auth, marketing) or scaffolding/build/deploy (→ databricks-apps). Complements databricks-apps; use it alongside whenever a custom app has a chart, table, KPI, report, or Genie/chat/AI surface.

3installs

Sourcedatabricks/databricks-agent-skills

Added on2026-08-12

NPX Install

npx skill4agent add databricks/databricks-agent-skills databricks-app-design

SKILL.md Content

View Translation Comparison →

Data App Design

Make Databricks data + AI apps that communicate clearly and compile to real AppKit code. This skill merges two bodies of knowledge and binds them to implementation:

Composition — what to show, how much to abstract, how to lay it out →
```
references/dashboard-patterns.md
```
Notation — make comparable things look comparable; honest scales; scenario marks →
```
references/ibcs-notation.md
```
Implementation — the exact AppKit components, hooks, and tokens to use →
```
references/appkit-cheatsheet.md
```

Design advice that doesn't name a real component is incomplete. Always end at a component plan.

When to use / when NOT

USE for: the data screens of a custom-code Databricks App (AppKit/React) — overview/KPI pages, reports, metric/ontology pages, variance analysis, charts, tables, and Genie/NL data surfaces — design or critique.
Do NOT use for: authoring managed AI/BI (Lakeview) dashboards (→
```
databricks-aibi-dashboards
```
), generic frontend (forms, auth, settings, marketing), or scaffolding/build/deploy (→
```
databricks-apps
```
). A plain "create a dashboard" / "build a dashboard" request (no app / AppKit / React / custom-code signal) means a managed AI/BI (Lakeview) dashboard → use
databricks-aibi-dashboards
, not this skill. If a request is "add a form", "deploy this", or "build a Lakeview / AI-BI dashboard", this skill should not fire.
Relationship:
```
databricks-apps
```
builds/runs the app; this skill decides what the data screens should look like and which primitives realize them.

Workflow

Frame — audience, the decision/question, refresh cadence, device, primary task. One sentence.
Genre — pick the closest from
```
dashboard-patterns.md
```
(static / analytic / magazine / infographic / repository / embedded mini). State it.
Compose — choose content + composition patterns (data abstraction, meta-info, layout, interaction, color). Make the tradeoff explicit: what's summarized, hidden, paginated, or made interactive — and why.
Apply notation — run the relevant
```
ibcs-notation.md
```
rules: message-in-title, scenario marks (actual/PY/plan/forecast), honest scales, semantic color. On any chart-vocabulary conflict, IBCS wins (see the conflict note in that file).
Bind to components — map every element to a primitive that's actually exported from
@databricks/appkit
/
@databricks/appkit-ui
(see
```
appkit-cheatsheet.md
```
); never cite a component AppKit doesn't ship. There's no prebuilt KPI/trend/distribution card — compose those from primitives, following the notation rules. Use
```
colorPalette
```
+ semantic tokens, never hardcoded hex. Bind data with
```
useAnalyticsQuery
```
/
```
queryKey
```
+
```
sql.*
```
params.
Cover the states — every data view must handle loading / empty / error / partial (see checklist).
Review — run the checklists in both reference files; lead critiques with the highest-impact comprehension or integrity issue, citing the affected component/file.

Required states & data realism (non-negotiable for data apps)

Loading →
```
Skeleton
```
; Empty →
```
Empty
```
with a useful next action; Error → inline message, never a blank panel; Partial/stale → show what you have + a freshness note.
Every KPI shows unit + period + comparison + freshness/source (mirror the metric definition; don't show a number with no provenance).
Large tables → server-side pagination/sort/filter, not client-side over a huge result set.
Long-running queries → optimistic loading + timeout/error UX.

AI / Genie surfaces (the "AI" half)

Gate: this section applies only if the app has a Genie / chat / natural-language / "ask your data" surface. For a pure dashboard / KPI / report app with no conversational input, skip this section and
references/genie-ai-trust.md
entirely. When it does apply, implement ALL five (code in

references/genie-ai-trust.md

): A Genie/chat/NL answer is only trustworthy if the user can see how it was produced and who it ran as. "Use

GenieChat

+ a spinner" is NOT enough — for ANY Genie/chat surface, ship all five (copy the exact snippets from the reference):

Identity — a
```
/api/whoami
```
route (real
```
x-forwarded-email
```
/
```
x-forwarded-user
```
headers) + the signed-in user in a
```
Badge
```
. Claim OBO only if
user_api_scopes: [dashboards.genie]
is wired; otherwise disclose the query runs as the app's service principal.
Generated SQL — render
```
attachments[].query
```
in an inspectable "Generated SQL"
```
Card
```
; never hide how the answer was computed.
Streaming/status — reflect
```
useGenieChat().status
```
(
```
streaming
```
/
```
error
```
), never a frozen spinner.
Disclaimer — a persistent "AI-generated — verify" note per answer.
Governance + states —
```
genie()
```
space config + a truthful execution-identity note (OBO when user-scoped, else service principal) + empty/error/ambiguous handling (
```
Empty
```
,
```
Alert
```
).

Output formats

Design proposal:

markdown

## Direction
[Genre, audience, primary task, design intent.]
## Pattern & notation choices
- Composition: [data info, meta info, layout, interaction, color]
- Notation: [message, scenario marks, scales, semantic color]
## Component plan        ← the part that makes it buildable
- [element] → [AppKit component] (queryKey/props), [token/palette], states handled
## Tradeoffs & risks
[What's summarized/hidden/paginated/interactive; overload, scale, a11y, maintenance risks.]

Critique: lead with the top comprehension/integrity issue, cite the component/file, then list findings by impact, each with the concrete fix (which component/token/state to change).

Anti-patterns

Producing a design memo with no component plan.
"Use semantic color" without naming the token/palette.
Naming a component AppKit doesn't export (e.g. a prebuilt
```
KpiCard
```
) — compose composites from published primitives instead.
Adding interaction, pages, or density the task doesn't need (over-engineering a mock-first app).
Forgetting loading/empty/error states, or KPIs with no freshness/source.