---
title: Concepts Overview
description: "What Tuffex is, the three concept blocks behind it, and the full component index"
category: Foundations
status: beta
since: 0.3.9
tags: [concepts, overview, foundations, utils]
syncStatus: reviewed
verified: true
---

## Installation

Three import shapes — per component, per suite barrel, or the root entry — plus the stylesheet each one needs. Start at [Installation](./installation.en.mdc).

## Tuffex Components

Tuffex (`@talex-touch/tuffex`) is the Vue 3 component family powering the Talex Touch ecosystem: one set of components serves the desktop CoreBox, plugin surfaces, and this docs site itself. Components are split into suites — **Basics** carries the everyday interface body, **Pro** carries rich interaction and visual expression, **AI** carries AI-native interfaces, **Data** carries visualization plus the chart family, and **Flow** carries workflow orchestration on a canvas. The suite switcher at the top of the sidebar lists Concepts as a sixth, documentation-only suite alongside these five, and picking a suite takes you straight to its overview.

- Live specimens: every suite page opens with a preview grid — [Basics](./base-suite.en.mdc), [Pro](./pro-suite.en.mdc), [AI](./ai-suite.en.mdc), [Data](./data-suite.en.mdc), [Flow](./flow-suite.en.mdc) — where each cell is a real, interactive component; click its name to open the docs.
- Per-suite imports: the `@talex-touch/tuffex/base`, `/pro` and `/ai` entries load on demand; the chart family ships behind the `@talex-touch/tuffex/charts` subpath of the same package.
- Changelog & Lifecycle: See [Component Changelog & Lifecycle](./changelog.en.mdc) for introduction versions (Since xx), per-release component changes, and release gates.

## Design Foundations

The bottom layer of every component's visual is a set of `--tx-*` design tokens: the font stack with its size/weight scale, and color semantics for both light and dark themes (primary, success/warning/danger, layered text and fill). Components never define their own visuals — they consume this layer, so re-theming means changing tokens, and app-side customization should land on the same layer. The full inventory lives in [Design Foundations](./foundations.en.mdc).

## Theming

Where Foundations lists the tokens, [Theming](./theming.en.mdc) is how you override them: global tokens, the dark and high-contrast selectors, the AI suite's own `--tx-bui-*` layer, and the ~300 per-component hooks that retheme one component or one subtree.

## Icons

`TxIcon` decides what an icon string is rather than making the caller declare it — an Iconify class, one of seven builtin glyphs, an emoji, or an explicit URL / file source. [Icons](./icons.en.mdc) covers that resolution order and how an app teaches the component to load icons from its own storage.

## Utils

Public helper functions that ship alongside the components, exported from the root entry and the `./utils` subpath: `nextZIndex` for unified overlay stacking, `toast` notifications, dialog orchestration, environment guards (`hasWindow` and friends), haptics and animation helpers. The components themselves go through this same layer, so reusing it keeps app behavior consistent. The full API lives in [Utils](./utils.en.mdc).

## Composed Workspace Demo

This demo validates component composition in a realistic admin slice: search input, switch, button, status badges, progress, and selectable table work together in one responsive panel.

::TuffDemoWrapper{demo="ComponentsWorkflowPanelDemo" code-lang="vue" title="Release workspace" description="A practical baseline for Dashboard / Admin component composition."}
---
code: |
  <script setup lang="ts">
  import { ref } from 'vue'

  const query = ref('')
  const selectedKeys = ref([1])
  const automationEnabled = ref(true)

  const columns = [
    { key: 'task', title: 'Task' },
    { key: 'owner', title: 'Owner' },
    { key: 'status', title: 'Status' },
  ]
  const rows = [
    { id: 1, task: 'Release notes', owner: 'Ivy', status: 'In review' },
    { id: 2, task: 'Canary rollout', owner: 'Long', status: 'In progress' },
  ]
  </script>

  <template>
    <section class="workflow-panel">
      <header>
        <h3>Release workspace</h3>
        <TxButton variant="primary" size="sm" icon="i-carbon-rocket">Deploy</TxButton>
      </header>
      <TuffInput v-model="query" placeholder="Search tasks" prefix-icon="i-carbon-search" clearable />
      <TuffSwitch v-model="automationEnabled" />
      <TxProgressBar :percentage="84" status="success" show-text />
      <TxStatusBadge text="Reviewing" status="warning" />
      <TxDataTable v-model:selected-keys="selectedKeys" :columns="columns" :data="rows" row-key="id" selectable />
    </section>
  </template>
---
::

## Tutorial Path

- Start with [Composing Tuffex interfaces](../getting-started/tuffex-composition.en.mdc) to learn the “actions → status → data” page structure.
- Start dashboard headers from the “Operations status panel” pattern, then expand into tables, trend charts, navigation settings, and detail drawers.
- For list pages, keep keyword search, scope filtering, and no-match recovery in one path with `TxSearchInput`, `TxSearchSelect`, and `TxSearchEmpty`.
- For data lists, use `TxDataTable` for the main body, `TxPagination` for navigation, and `TxSkeleton` / `TxLayoutSkeleton` for waiting states.
- For settings pages and admin shells, use `TxTabs` for fixed sections, `TxDropdownMenu` / `TxPopover` for lightweight actions and short notes, and `TxDrawer` for dense configuration.
- Data regions must design loading, empty, and error recovery paths together; prefer `TxLoadingState`, `TxEmptyState`, and `TxErrorState`.
- Task feedback paths should mount `TxToastHost` for notifications, use `TxTooltip` for action hints, `TxLoadingOverlay` for local blocking refreshes, and `TxSpinner` for inline waiting.
- Permission orchestration paths should use `TxTree` for scope, `TxTreeSelect` for owner team, `TxTransfer` for resource grants, and `TxTimeline` for audit progress.
- Release configuration paths should use `TxCascader` for release scope, `TxFlatSelect` for package and rollout choices, `TxSegmentedSlider` for risk tiers, `TxSlider` for traffic ramps, and `TxTagInput` for short metadata.
- Use the grouped component list below for detail pages; the sidebar only highlights migration states that still need attention, while reviewed pages are marked as `Verified` in the sync dashboard.
- Dashboard pages should compose `TxDataTable`, `TxStatusBadge`, `TxProgressBar`, and chart components instead of hand-writing one-off SVG/status UI.

## Migration Dashboard

- `In progress`: this page is still being edited; demos/API may change.
- `AI migrated`: migration is complete, but source-code verification is recommended.
- `Reviewed`: manually reviewed.

::DocsComponentSyncTable
::

## Suite Overview

Each suite has one overview page carrying its own live preview and its own component list — the first entry in the sidebar once that suite is picked in the switcher.

| Suite | Groups | Components | Entry |
|-------|--------|------------|-------|
| [Basics Suite](./base-suite.en.mdc) | General / Form / Layout / Navigation / Data Display / Feedback / Status & Empty | 94 | `@talex-touch/tuffex/base` |
| [Pro Suite](./pro-suite.en.mdc) | Interaction / Effects / Primitives | 27 | `@talex-touch/tuffex/pro` |
| [AI Suite](./ai-suite.en.mdc) | Chat / Agents / Reasoning / Context & Insight | 34 | `@talex-touch/tuffex/ai` |
| [Data Suite](./data-suite.en.mdc) | Charts / Visualization | 10 | `@talex-touch/tuffex/pro` (visualization + charts) + `@talex-touch/tuffex/charts` (chart family entry) |
| [Flow Suite](./flow-suite.en.mdc) | Flow | 1 | `@talex-touch/tuffex/ai` |

Concepts is the sixth suite — documentation-only, with no component entry of its own. This page is its overview: library positioning, design foundations and utils above, the full component index below.

## Basics

The everyday building blocks, importable through the `@talex-touch/tuffex/base` category entry. Suite page: [Basics Suite](./base-suite.en.mdc). Design foundations live in [Foundations](./foundations.en.mdc); shared helpers in [Utils](./utils.en.mdc).

### General

- [Button](./button.en.mdc)
- [Icon](./icon.en.mdc)
- [Avatar](./avatar.en.mdc)
- [Avatar Variants](./avatar-variants.en.mdc)
- [Tag](./tag.en.mdc)
- [Badge](./badge.en.mdc)
- [StatusBadge](./status-badge.en.mdc)
- [IconChip](./icon-chip.en.mdc)
- [Kbd](./kbd.en.mdc)
- [Divider](./divider.en.mdc)

### Form

- [Form](./form.en.mdc)
- [Input](./input.en.mdc)
- [SensitiveInput](./sensitive-input.en.mdc)
- [Textarea](./textarea.en.mdc)
- [NumberInput](./number-input.en.mdc)
- [SearchInput](./search-input.en.mdc)
- [TagInput](./tag-input.en.mdc)
- [ScrubField](./scrub-field.en.mdc)
- [Select](./select.en.mdc)
- [FlatSelect](./flat-select.en.mdc)
- [SearchSelect](./search-select.en.mdc)
- [TreeSelect](./tree-select.en.mdc)
- [Cascader](./cascader.en.mdc)
- [Picker](./picker.en.mdc)
- [DatePicker](./date-picker.en.mdc)
- [IconPicker](./icon-picker.en.mdc)
- [Radio](./radio.en.mdc)
- [FlatRadio](./flat-radio.en.mdc)
- [Checkbox](./checkbox.en.mdc)
- [Switch](./switch.en.mdc)
- [Slider](./slider.en.mdc)
- [SegmentedSlider](./segmented-slider.en.mdc)
- [Rating](./rating.en.mdc)
- [FileUploader](./file-uploader.en.mdc)
- [ImageUploader](./image-uploader.en.mdc)

### Layout

- [Container](./container.en.mdc)
- [Flex](./flex.en.mdc)
- [Grid](./grid.en.mdc)
- [GridLayout](./grid-layout.en.mdc)
- [Stack](./stack.en.mdc)
- [Splitter](./splitter.en.mdc)
- [Scroll](./scroll.en.mdc)
- [Collapse](./collapse.en.mdc)
- [Card](./card.en.mdc)
- [CardItem](./card-item.en.mdc)
- [GroupBlock](./group-block.en.mdc)

### Navigation

- [Tabs](./tabs.en.mdc)
- [TabBar](./tab-bar.en.mdc)
- [NavBar](./nav-bar.en.mdc)
- [SidebarNav](./sidebar-nav.en.mdc)
- [Breadcrumb](./breadcrumb.en.mdc)
- [Steps](./steps.en.mdc)
- [Pagination](./pagination.en.mdc)
- [DropdownMenu](./dropdown-menu.en.mdc)
- [FlatDropdown](./flat-dropdown.en.mdc)
- [ContextMenu](./context-menu.en.mdc)

### Data Display

- [DataTable](./data-table.en.mdc)
- [Descriptions](./descriptions.en.mdc)
- [Tree](./tree.en.mdc)
- [SortableList](./sortable-list.en.mdc)
- [Timeline](./timeline.en.mdc)
- [Transfer](./transfer.en.mdc)
- [StatCard](./stat-card.en.mdc)
- [CellLink](./cell-link.en.mdc)
- [DotIndicator](./dot-indicator.en.mdc)
- [FilterChips](./filter-chips.en.mdc)
- [MarkdownView](./markdown-view.en.mdc)
- [ImageGallery](./image-gallery.en.mdc)

### Feedback

- [Dialog](./dialog.en.mdc)
- [Modal](./modal.en.mdc)
- [Drawer](./drawer.en.mdc)
- [Popover](./popover.en.mdc)
- [Tooltip](./tooltip.en.mdc)
- [Toast](./toast.en.mdc)
- [ToastPanel](./toast-panel.en.mdc)
- [Alert](./alert.en.mdc)
- [StatusHint](./status-hint.en.mdc)
- [Progress](./progress.en.mdc)
- [ProgressBar](./progress-bar.en.mdc)
- [Spinner](./spinner.en.mdc)
- [LoadingOverlay](./loading-overlay.en.mdc)
- [SelectionActions](./selection-actions.en.mdc)

### Status & Empty

- [Empty](./empty.en.mdc)
- [EmptyState](./empty-state.en.mdc)
- [NoData](./no-data.en.mdc)
- [NoSelection](./no-selection.en.mdc)
- [SearchEmpty](./search-empty.en.mdc)
- [ErrorState](./error-state.en.mdc)
- [OfflineState](./offline-state.en.mdc)
- [PermissionState](./permission-state.en.mdc)
- [GuideState](./guide-state.en.mdc)
- [BlankSlate](./blank-slate.en.mdc)
- [LoadingState](./loading-state.en.mdc)
- [Skeleton](./skeleton.en.mdc)
- [LayoutSkeleton](./layout-skeleton.en.mdc)

## Pro

Rich interaction, visual effects and low-level primitives, importable through the `@talex-touch/tuffex/pro` category entry. Suite page: [Pro Suite](./pro-suite.en.mdc).

### Interaction

- [CommandPalette](./command-palette.en.mdc)
- [SearchPanel](./search-panel.en.mdc)
- [MarkdownEditor](./markdown-editor.en.mdc)
- [CodeEditor](./code-editor.en.mdc)
- [VirtualList](./virtual-list.en.mdc)
- [VersionCapsule](./version-capsule.en.mdc)

### Effects

- [GlassSurface](./glass-surface.en.mdc)
- [GradientBorder](./gradient-border.en.mdc)
- [OutlineBorder](./outline-border.en.mdc)
- [BorderBeam](./border-beam.en.mdc)
- [PrismGlow](./prism-glow.en.mdc)
- [CornerOverlay](./corner-overlay.en.mdc)
- [GradualBlur](./gradual-blur.en.mdc)
- [EdgeFadeMask](./edge-fade-mask.en.mdc)
- [GlowText](./glow-text.en.mdc)
- [KeyframeStrokeText](./keyframe-stroke-text.en.mdc)
- [TuffLogoStroke](./tuff-logo-stroke.en.mdc)
- [TextMorph](./text-morph.en.mdc)
- [IconMorph](./icon-morph.en.mdc)
- [TextTransformer](./text-transformer.en.mdc)
- [Transition](./transition.en.mdc)
- [Stagger](./stagger.en.mdc)
- [Fusion](./fusion.en.mdc)
- [FusionSurface](./fusion-surface.en.mdc)
- [Liquid](./liquid.en.mdc)
- [FlipOverlay](./flip-overlay.en.mdc)
- [ImageGeneration](./image-generation.en.mdc)
- [MetalFx](./metal-fx.en.mdc)
- [VoiceBeam](./voice-beam.en.mdc)

### Primitives

- [BaseSurface](./base-surface.en.mdc)
- [BaseAnchor](./base-anchor.en.mdc)
- [Floating](./floating.en.mdc)
- [AutoSizer](./auto-sizer.en.mdc)
- [ResizeBox](./resize-box.en.mdc)

## AI Suite

AI-native interface components, partly adapted from [Beautiful UI](https://www.beautifului.dev) (MIT) — see the [AI Suite](./ai-suite.en.mdc) page for full showcases — importable through the `@talex-touch/tuffex/ai` category entry.

### Chat

- [Chat](./chat.en.mdc)
- [ChatComposer](./chat-composer.en.mdc)
- [PromptBar](./prompt-bar.en.mdc)
- [AttachmentTray](./attachment-tray.en.mdc)
- [ModeChip](./mode-chip.en.mdc)
- [MessageActions](./message-actions.en.mdc)
- [SuggestionChips](./suggestion-chips.en.mdc)
- [ChoiceCard](./choice-card.en.mdc)
- [TypingIndicator](./typing-indicator.en.mdc)
- [ConversationStream](./conversation-stream.en.mdc)

### Agents

- [Agents](./agents.en.mdc)
- [AgentScreen](./agent-screen.en.mdc)
- [AgentTrace](./agent-trace.en.mdc)
- [TaskRows](./task-rows.en.mdc)
- [ToolCallCard](./tool-call-card.en.mdc)
- [ToolChips](./tool-chips.en.mdc)
- [ToolConfirmation](./tool-confirmation.en.mdc)
- [ApprovalCard](./approval-card.en.mdc)
- [WorkingIndicator](./working-indicator.en.mdc)
- [BotAvatar](./bot-avatar.en.mdc)

### Reasoning

- [AI Elements](./ai-elements.en.mdc)
- [ChainOfThought](./chain-of-thought.en.mdc)
- [ReasoningDisclosure](./reasoning-disclosure.en.mdc)
- [ThinkingOrb](./thinking-orb.en.mdc)
- [StreamElement](./stream-element.en.mdc)
- [StreamText](./stream-text.en.mdc)
- [StreamMarkdown](./stream-markdown.en.mdc)
- [CodeStream](./code-stream.en.mdc)
- [InlineCitation](./inline-citation.en.mdc)
- [Sources](./sources.en.mdc)

### Context & Insight

- [ContextCards](./context-cards.en.mdc)
- [ContextIndicator](./context-indicator.en.mdc)
- [InsightCards](./insight-cards.en.mdc)
- [RecommendationCard](./recommendation-card.en.mdc)
- [FineTuneCard](./fine-tune-card.en.mdc)

## Data

Data visualization and charts: the main package's visualization components (imported through `@talex-touch/tuffex/pro`) plus the chart family behind the `@talex-touch/tuffex/charts` subpath (kumo-shaped, no echarts). Suite page: [Data Suite](./data-suite.en.mdc).

### Charts

Docs for the chart family behind the `@talex-touch/tuffex/charts` subpath (kumo), shipped inside the main tuffex package.

- [Charts](./charts.en.mdc)
- [Chart Colors](./chart-colors.en.mdc)
- [TimeseriesChart](./timeseries-chart.en.mdc)
- [Maps](./maps.en.mdc)
- [SankeyChart](./sankey-chart.en.mdc)
- [Custom Chart](./custom-chart.en.mdc)

### Visualization

- [SparkChart](./spark-chart.en.mdc)
- [AllocationBar](./allocation-bar.en.mdc)
- [DiffTable](./diff-table.en.mdc)
- [SignalMeter](./signal-meter.en.mdc)

## Flow

Workflow orchestration: nodes, branches and connectors on a dotted canvas. It imports through the `@talex-touch/tuffex/ai` entry — like Data, the suite is a docs-level split. Suite page: [Flow Suite](./flow-suite.en.mdc).

### Flow

- [Flowchart](./flowchart.en.mdc)

## Technologies

- Hub scope: this page is the Concepts suite overview and the component documentation index; per-component API / props / best-practice details live in the linked component pages.
- Source registry: `packages/tuffex/packages/components/src/components.ts` defines the exported component slug set used by docs coverage.
- Demo registry: `apps/nexus/app/components/content/demo-registry.ts` maps each `TuffDemoWrapper` demo on this page to a standalone Vue demo file.
- Preview grid: `apps/nexus/app/components/docs/DocsComponentsGallery.vue` renders the live "Preview" grid on each suite page; it takes a required `suite` prop and renders that band only.
- **Verified coverage:** Coverage: `apps/nexus/test/docs/tuffex-component-docs-coverage.test.ts` verifies exported components have English and Chinese docs, localized hubs link documented components, and all demo references resolve to registered Vue files.

## Accessibility

Focus rings on `:focus-visible`, `prefers-reduced-motion` handling, the high-contrast palette, and the ARIA conventions the components share — along with a plain account of where coverage stops. See [Accessibility](./accessibility.en.mdc).