veltra-ui

veltra-ui

veltra-ui is a Vue 3 UI system.

When developing Vue 3 features,prioritizeusing the components, styles, utility functions, composables, directives, icons, and build integrations already provided by veltra-ui . Only add new implementations or introduce external solutions after searching the documentation and source code and confirming that no suitable capability exists.

Version

The current documentation corresponds to package versions (monorepo aligned):

Package	Version
@veltra/desktop	1.7.2
@veltra/utils	1.7.2
@veltra/styles	1.7.2
@veltra/compositions	1.7.2
@veltra/directives	1.7.2
@veltra/icons	1.5.0
@veltra/vite	4.0.1
@veltra/sheet	2.5.2
@veltra/sheet-core	2.5.2
@veltra/ai	2.1.6

Package Map

Entry	Package	Purpose
packages/desktop/	@veltra/desktop	Desktop components (main entry)
packages/ai.md	@veltra/ai	AI chat: UAiChat, useChat, ChatTool, createOpenAITransport, UAiOrb
packages/sheet.md	@veltra/sheet	Spreadsheet (USheet, formulas, undo/redo, floating images, tool extensions)
packages/sheet-core.md	@veltra/sheet-core	Table core: data model/formulas/IO + SheetGrid rendering layer (including readonly preview, cell-level read-only marking)
packages/styles/	@veltra/styles	SCSS, themes, Design Tokens, transitions
packages/compositions.md	@veltra/compositions	Vue composables
packages/directives.md	@veltra/directives	Custom directives
packages/icons.md	@veltra/icons	SVG icon components
packages/utils.md	@veltra/utils	Utility functions and shared types
packages/vite.md	@veltra/vite	Vite on-demand resolver

Routing decisions

User intent	Read first
Write forms / UForm / form items / input controls with labels	Must read packages/desktop/components/form/examples.md(then read the specific control's examples.md "Usage in UForm")
Common page/dialog patterns (selector dialogs, search table pages, admin layouts…)	Must read packages/desktop/recipes.md
Explicit UFormItem(multi-control composition, custom label slots)	packages/desktop/components/form-item/examples.md
Find/use a UI component	packages/desktop/index.md → components/<kebab>/api.md + examples.md + types.d.ts
Integrate AI chat / OpenAI-compatible endpoints / multiple providers / reasoning levels	packages/ai.md → ai/examples.md(basic chat) + ai/api.md（createOpenAITransport）
Define tools / confirmation / side panel / terminal tools / askQuestion	packages/ai.md → ai/examples.md(tools section) + ai/api.md（ChatTool）
Headless chat / custom chat UI / useChat	packages/ai.md → ai/api.md（useChat）+ ai/examples.md(headless)
Custom LLM protocol / own backend / ChatTransport	packages/ai.md → ai/api.md（ChatTransport）+ ai/examples.md
Session persistence / pending-send queue / controlled messages	packages/ai.md → ai/examples.md + ai/api.md(message model, queue)
AI living orb avatar UAiOrb	packages/ai.md → ai/api.md（UAiOrb）+ ai/examples.md
Spreadsheet / cell editing / formulas / floating images / table toolbar extensions	packages/sheet.md
Per-cell custom cell rendering (customLayout badges, etc.)	packages/sheet.md + packages/sheet-core.md（resolveCellRenderer / CustomLayout）
Headless table model / xlsx·csv import and export / read-only table preview (SheetGrid readonly)	packages/sheet-core.md
Tabular data entry / partially locked read-only cells / input area highlighting	packages/sheet-core.md(cell-level read-only) + packages/sheet.md(USheet data entry notes)
Installation / global registration / on-demand styles	packages/desktop/installation.md、packages/vite.md
Theme colors, dark mode, CSS variables	packages/styles/theme.md、packages/styles/tokens.md
Sidebar/menu colors, dark·light sidebar variants, menu text unclear	packages/styles/theme.md(Sidebar navigation appearance),packages/styles/tokens.md(Sidebar navigation token)
SCSS BEM / mixins	packages/styles/scss.md
Global dimensions, form fallbacks, overlays, virtual lists	packages/compositions.md
Ripple, click outside, focus directives	packages/directives.md
Icon names and import paths	packages/icons.md
BEM、fieldKey, form context types	packages/utils.md

Load component details on demand; do not preload the entire desktop documentation into context.

UForm hard rules (must be followed when writing forms)

Recommended approach (place controls directly under u-form ):

<u-form :model="form">
  <u-input label="用户名" field="username" />
  <u-textarea label="意见" field="opinion" :rows="3" />
  <u-select label="办理人" field="handler" :options="options" />
  <u-checkbox label="记住" field="remember">记住我</u-checkbox>
</u-form>

1. There must be field：u-form Within, any control / model that needs a label, validation, or writing to u-form-item, must define field(supports a.b nested paths).When there is no field ,label / rules / tips will not enter the form item, and the value will not be automatically bound to model。
2. If there is field , then do not write v-model：UForm will follow field to read and write the path corresponding to model .v-model="form.xxx" and field="xxx" used together is incorrect syntax.
3. Only use when using controls independently v-model: when not inside u-form , or when explicitly wrapping multiple controls with u-form-item , the inner controls handle v-modelthemselves; in this case field / label / rules is written on u-form-item .
4. Do not copy the control's "basic usage" into forms: the examples.md examples of each control starting with v-model are only for outside forms; inside forms, follow "Using in UForm" and form/examples.md .

Usage

• First search the above entry points according to requirements, then drill down into specific files.
• For component-related matters, first check the desktop/ documentation directory, then search APIs, examples, and types by component name.
• After library code changes, run bun run skill:gen to sync each component's types.d.ts / api.md；examples.md and package-level .md must be maintained manually.
• api.md is re-rendered by the generator; do not modify it by hand; the component-level "Notes" section is maintained in scripts/veltra-component-skill-meta.ts in NOTES_BY_KEBAB .

Hard prerequisites (skip one step and the interface becomes bare HTML)

1. The entry point must import '@veltra/styles/normalize' and call loadTheme()（@veltra/styles/theme). All component colors go through --u-* token，tokens can only be injected by loadTheme() and have no fallback value; if not called, the component is transparent/colorless bare HTML. See packages/desktop/installation.md。
2. Component registration is one of three options:app.use(UltraUI)（@veltra/desktop/install）、VeltraUIResolver automatic import, manual import + */style subpath. In the template, <u-xxx> rendering as an unknown tag = not registered; do not imitate it with div.

Anti-patterns (the most common downstream pitfalls)

• Do not hand-roll popups/drawers/buttons/empty states/scroll containers：UDialog comes with a title bar and close button,UEmpty comes with empty-state illustrations,UScroll comes with a scrollbar. If "macOS-style window dots", "plain-text title bar", or "hand-drawn empty-state illustration" appears in the interface, it has gone off track — go back to desktop/index.md to find components.
• Do not use inline styles/hand-written CSS to pile up colors, shadows, and border radii: always use theme tokens (cssVar() / SCSS fn.use-var(), see styles/tokens.md、styles/scss.md); if you think "the component has no color", first go add loadTheme(), rather than writing patch styles.
• Do not introduce other component libraries or build similar components yourself: First check the packages/desktop/index.md component list and routing table to confirm that nothing has been built again from scratch.
• For form rules, see the "UForm hard rules" above: with field do not write v-model。

Checklist

• The host has installed the corresponding @veltra/* peer, and the version matches or is compatible with the table above
• The entry point has been import '@veltra/styles/normalize' and calls loadTheme()(required before any component is used, not optional)
• On-demand styles go through VeltraUIResolver or explicit style import (see vite.md）
• Prioritize searching this skill documentation, and only build from scratch or introduce external libraries after confirming there is no suitable capability
• Popups/drawers/empty states/buttons, etc. all use library components; window shells and basic controls have not been hand-built
• When writing forms, you have read form/examples.md: controls have field, no extra v-model, and when a label is needed field and label appear in pairs
• When writing AI conversations, you have read packages/ai.md：transport required, the parent has height, and in production the API Key is not sent down to the browser