databricks-app-design

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

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.

打造数据传达清晰、可编译为真实AppKit代码的Databricks数据+AI应用。本技能融合两类知识并将其与实现绑定：

内容组合 — 展示内容、抽象程度、布局方式 →
```
references/dashboard-patterns.md
```
标注规则 — 同类内容外观统一；刻度真实；场景标记 →
```
references/ibcs-notation.md
```
实现方案 — 需使用的具体AppKit组件、钩子和令牌 →
```
references/appkit-cheatsheet.md
```

未指定真实组件的设计建议是不完整的，最终必须落实到组件方案。

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.

适用场景：自定义代码开发的Databricks App（AppKit/React）的数据界面——概览/KPI页面、报表、指标/本体页面、差异分析、图表、表格以及Genie/自然语言数据界面——的设计或评审。
不适用场景：创作托管式AI/BI（Lakeview）仪表盘（请使用
```
databricks-aibi-dashboards
```
）、通用前端（表单、认证、设置、营销页面）或脚手架构建/部署（请使用
```
databricks-apps
```
）。**若仅提出“创建仪表盘”/“构建仪表盘”需求（未提及app/AppKit/React/自定义代码），指的是托管式AI/BI（Lakeview）仪表盘，请使用
```
databricks-aibi-dashboards
```
，而非本技能。**若需求为“添加表单”、“部署应用”或“构建Lakeview/AI-BI仪表盘”，请勿使用本技能。
关联关系：
```
databricks-apps
```
负责构建/运行应用；本技能负责确定数据界面的外观及实现所需的基础组件。

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.

框架定义 — 明确受众、决策/问题、刷新频率、设备类型、核心任务。用一句话概括。
界面类型 — 从
```
dashboard-patterns.md
```
中选择最匹配的类型（静态/分析/杂志/信息图/资源库/嵌入式迷你型）并明确说明。
内容组合 — 选择内容及组合模式（数据抽象、元信息、布局、交互、色彩）。明确权衡取舍：哪些内容被汇总、隐藏、分页或设为可交互，以及原因。
应用标注规则 — 执行
```
ibcs-notation.md
```
中的相关规则：标题内嵌信息、场景标记（实际值/上年值/计划值/预测值）、真实刻度、语义色彩。若图表术语出现冲突，以IBCS规则为准（详见该文件中的冲突说明）。
绑定组件 — 将每个元素映射到**
```
@databricks/appkit
```
/
```
@databricks/appkit-ui
```
实际导出的基础组件**（详见
```
appkit-cheatsheet.md
```
）；请勿引用AppKit未提供的组件。AppKit没有预构建的KPI/趋势/分布卡片——需遵循标注规则，使用基础组件组合实现。使用
```
colorPalette
```
+语义令牌，切勿使用硬编码的十六进制颜色值。通过
```
useAnalyticsQuery
```
/
```
queryKey
```
+
```
sql.*
```
参数绑定数据。
覆盖状态 — 每个数据视图必须处理加载/空数据/错误/部分加载状态（详见检查清单）。
评审 — 执行两个参考文件中的检查清单；评审时优先指出影响最大的理解性或完整性问题，并引用受影响的组件/文件。

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.

加载状态 →
```
Skeleton
```
；空数据状态 →
```
Empty
```
组件并提供有效的下一步操作指引；错误状态 → 显示内联消息，切勿展示空白面板；部分加载/过期状态 → 展示已加载内容并添加新鲜度说明。
每个KPI需显示单位+周期+对比信息+新鲜度/数据源（与指标定义一致；切勿展示无来源的数值）。
大型表格需使用服务端分页/排序/筛选，而非在客户端处理超大结果集。
长时间运行的查询需实现乐观加载+超时/错误处理UX。

AI / Genie surfaces (the "AI" half)

AI/Genie界面（“AI”相关部分）

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
```
).

适用条件： 仅当应用包含Genie/聊天/自然语言/“询问数据”界面时，才适用本节内容。对于无对话输入的纯仪表盘/KPI/报表应用，请完全跳过本节及
references/genie-ai-trust.md
文件。若适用，请实现以下全部五项（代码详见

references/genie-ai-trust.md

）： Genie/聊天/自然语言答案只有当用户能够查看其生成方式及执行身份时，才具备可信度。仅“使用

GenieChat

+加载动画”是远远不够的——对于任何Genie/聊天界面，必须实现以下全部五项（复制参考文件中的精确代码片段）：

身份标识 — 提供
```
/api/whoami
```
路由（使用真实的
```
x-forwarded-email
```
/
```
x-forwarded-user
```
请求头），并在
```
Badge
```
组件中显示登录用户。仅当配置了
user_api_scopes: [dashboards.genie]
时，才可使用代表用户（OBO）身份；否则需披露查询以应用的服务主体身份运行。
生成的SQL — 在可查看的“Generated SQL”
```
Card
```
组件中渲染
```
attachments[].query
```
；切勿隐藏答案的计算方式。
流式传输/状态 — 实时反映
```
useGenieChat().status
```
状态（
```
streaming
```
/
```
error
```
），切勿使用冻结的加载动画。
免责声明 — 每个答案旁需显示持久的“AI生成——请验证”提示。
治理与状态 — 配置
```
genie()
```
空间，如实标注执行身份（用户范围下使用OBO，否则使用服务主体），并处理空数据/错误/模糊请求状态（使用
```
Empty
```
、
```
Alert
```
组件）。

Output formats

输出格式

Design proposal:

markdown

undefined

设计方案：

markdown

undefined

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

[元素] → [AppKit组件] (queryKey/属性), [令牌/调色板], 已处理的状态

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.

产出无组件方案的设计备忘录。
仅提及“使用语义色彩”但未指定令牌/调色板。
引用AppKit未导出的组件（如预构建的
```
KpiCard
```
）——应使用已发布的基础组件组合实现。
添加任务不需要的交互、页面或密度（过度工程化以原型为先的应用）。
遗漏加载/空数据/错误状态，或未标注新鲜度/数据源的KPI。