# unovue/reka-ui architecture

> Architecture diagram of the GitHub repository unovue/reka-ui, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-07-06). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/unovue/reka-ui
- Repository: https://github.com/unovue/reka-ui

## Overview

1. **What this repo is**
   - Reka UI is a **Vue 3 component library monorepo** centered on accessible, headless UI primitives.
   - The repository is organized so one source of truth in `packages/core` feeds the published package, the docs site, demo stories, and playground apps.

2. **Core product package**
   - `packages/core` is the main library package (`reka-ui` on npm).
   - It contains one folder per component or primitive, each typically with:
     - Vue SFCs for the public parts
     - an `index.ts` barrel export
     - tests
     - story/demo files
   - This is the subsystem that actually implements the UI behaviors consumed by end users.

3. **Component architecture pattern**
   - Most components follow a **compound-component pattern**: root, trigger, content, item, portal, overlay, etc.
   - Examples include `Dialog`, `Popover`, `Select`, `Tabs`, `Tooltip`, `Accordion`, `DropdownMenu`, `Calendar`, and many others.
   - The library exposes small composable parts rather than monolithic widgets, which matters for diagramming because consumers assemble behavior from multiple exported pieces.

4. **Shared foundations / primitives**
   - `packages/core/src/shared`, `Primitive`, `FocusScope`, `Presence`, `Teleport`, `DismissableLayer`, `Popper`, `RovingFocus`, and `Collection` form the lower-level infrastructure layer.
   - These modules provide reusable mechanics such as:
     - focus management
     - dismiss/outside-click handling
     - portal/teleport behavior
     - presence/animation mounting
     - positioning and arrow/popup layout
     - keyboard navigation and roving focus
   - Many higher-level components depend on these rather than reimplementing interaction logic.

5. **State, context, and cross-component coordination**
   - The codebase relies heavily on **context propagation and composables** (`createContext`, `use*` helpers) to coordinate nested parts.
   - This is how roots communicate with children like triggers, content, items, and providers without prop-drilling.
   - `ConfigProvider`, `useDirection`, `useLocale`, `useId`, `useForwardProps`, `useEmitAsProps`, and similar helpers support consistent behavior across all components.

6. **Date, time, and calendar subsystem**
   - A large portion of the library is dedicated to date/time controls: `DateField`, `DatePicker`, `DateRangePicker`, `MonthPicker`, `YearPicker`, `TimeField`, `Calendar`, `RangeCalendar`, etc.
   - These share internal date utilities under `packages/core/src/date` and `packages/core/src/shared/date`.
   - This subsystem is distinct because it combines UI composition with calendar math, locale formatting, parsing, validation, and segmented inputs.

7. **Color subsystem**
   - Color-related primitives live in `ColorArea`, `ColorField`, `ColorSlider`, `ColorSwatch`, and `ColorSwatchPicker`.
   - Supporting color math lives in `shared/color`.
   - These components are a smaller but separate domain with their own parsing, conversion, and gradient logic.

8. **Complex interaction subsystems**
   - Some components have especially rich internal logic:
     - `Drawer` includes swipe-dismiss behavior, snap points, viewport/overlay coordination, and body-locking.
     - `Splitter` includes layout calculations, persistence, resize handling, and window-level behavior.
     - `Tree`, `Listbox`, `Combobox`, `Select`, and `NavigationMenu` include filtering, virtualization, and keyboard/typeahead navigation.
   - These are not just visual components; they coordinate DOM, input events, and layout state.

9. **Testing and verification**
   - Each component area has tests under `*.test.ts`, plus snapshots where needed.
   - The repo uses **Vitest** for unit/component testing.
   - Story files under each component’s `story` folder act as executable examples and often cover variants, edge cases, and visual regressions.

10. **Story/demo authoring layer**
   - `docs/components/demo` and the `story` folders in `packages/core` are the primary authored example layers.
   - `Histoire` is configured in `.histoire` and is used for component exploration/stories.
   - These demos are not the same as docs pages; they are a separate presentation layer for interactive component scenarios.

11. **Documentation site**
   - `docs` is a **VitePress** site that serves the public documentation at `reka-ui.com`.
   - It contains:
     - markdown content under `docs/content`
     - custom Vue components under `docs/.vitepress/components`
     - layout/theme/config files under `docs/.vitepress`
     - generated metadata and example data helpers
   - The docs site is a consumer of the library package and a presentation layer over the same components and examples.

12. **Docs content pipeline**
   - The docs tree includes large `meta` and `components` content collections for individual API pages and usage examples.
   - Scripts in `docs/scripts` and functions under `docs/.vitepress/functions` suggest generation/aggregation of docs data, contributor lists, examples, and caches.
   - That means some docs pages are static markdown, while others are assembled from structured metadata and component demos.

13. **Plugin package**
   - `packages/plugins` is a separate package that provides integration tooling:
     - a resolver
     - Nuxt integration
     - namespaced component generation
   - This package matters architecturally because it sits between the core library and framework consumers, enabling auto-imports and framework-friendly integration.

14. **Playgrounds**
   - `playground/vue3` and `playground/nuxt` are consumer apps used to validate real-world usage.
   - They demonstrate the library in a plain Vue 3 app and a Nuxt app, respectively.
   - These are external-consumer mirrors: they depend on the published package behavior rather than internal docs/test harnesses.

15. **Build, release, and repo boundaries**
   - The repo is managed as a **pnpm workspace** with multiple packages and apps.
   - GitHub Actions in `.github/workflows` handle build, release, publish, and checks like typo validation.
   - The important architectural boundary is:
     - `packages/core` = runtime UI library
     - `packages/plugins` = integration tooling
     - `docs`/`.histoire` = documentation and demo surfaces
     - `playground/*` = consumer validation apps
   - For a diagram, the main data flow is: core source → package build/export → docs/stories/playgrounds consume it, with tests and CI validating each layer.

Main entry points: [`packages/core/src/index.ts`](https://github.com/unovue/reka-ui/blob/v2/packages/core/src/index.ts) (Package entry), [`.github/workflows/build.yaml`](https://github.com/unovue/reka-ui/blob/v2/.github/workflows/build.yaml) (CI & release), [`packages/core/src/shared`](https://github.com/unovue/reka-ui/tree/v2/packages/core/src/shared) (Infrastructure), [`packages/core/src/Select`](https://github.com/unovue/reka-ui/tree/v2/packages/core/src/Select) (Inputs)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_group_core["Core library"]
  node_core_index["Package entry<br/>export surface<br/>[index.ts]"]
  node_core_accordion["Accordion<br/>compound component"]
  node_core_popovers["Overlays<br/>overlay family"]
  node_core_forms["Inputs<br/>form controls"]
  node_core_calendar["Dates<br/>date subsystem"]
  node_core_color["Color"]
  node_core_layout["Layout"]
  node_core_tree["Collections<br/>collection/navigation"]
  node_core_infra["Infrastructure<br/>shared primitives"]
  node_core_context["Context helpers<br/>composables<br/>[createContext.ts]"]
  node_core_date_utils["Date utils<br/>date helpers"]
  node_core_color_utils["Color math<br/>color helpers"]
end

subgraph group_group_docs["Docs & demos"]
  node_docs_site["Docs site<br/>VitePress<br/>[config.ts]"]
  node_docs_demos["Demos<br/>story/demo layer"]
  node_histoire["Histoire<br/>storybook-like<br/>[vite.config.ts]"]
end

subgraph group_group_integration["Integration"]
  node_plugins_pkg["Plugins<br/>integration package<br/>[index.ts]"]
  node_playground_vue3["Vue playground<br/>consumer app<br/>[main.ts]"]
  node_playground_nuxt["Nuxt playground<br/>consumer app<br/>[nuxt.config.ts]"]
end

subgraph group_group_ops["Ops"]
  node_core_tests(("Vitest<br/>verification<br/>[vitest.setup.ts]"))
  node_workspace_ci(("CI & release<br/>automation<br/>[build.yaml]"))
end

node_core_index -->|"exports"| node_core_accordion
node_core_index -->|"exports"| node_core_popovers
node_core_index -->|"exports"| node_core_forms
node_core_index -->|"exports"| node_core_calendar
node_core_index -->|"exports"| node_core_color
node_core_index -->|"exports"| node_core_layout
node_core_index -->|"exports"| node_core_tree
node_core_accordion -->|"uses"| node_core_infra
node_core_popovers -->|"uses"| node_core_infra
node_core_forms -->|"uses"| node_core_context
node_core_forms -->|"uses"| node_core_infra
node_core_calendar -->|"uses"| node_core_date_utils
node_core_calendar -->|"uses"| node_core_context
node_core_color -->|"uses"| node_core_color_utils
node_core_layout -->|"uses"| node_core_infra
node_core_tree -->|"uses"| node_core_infra
node_docs_site -->|"consumes"| node_core_index
node_docs_site -->|"embeds"| node_docs_demos
node_histoire -->|"renders"| node_core_index
node_histoire -->|"shares examples"| node_docs_demos
node_plugins_pkg -->|"integrates"| node_core_index
node_playground_vue3 -->|"consumes"| node_core_index
node_playground_nuxt -->|"uses"| node_plugins_pkg
node_playground_nuxt -->|"consumes"| node_core_index
node_workspace_ci -->|"validates"| node_core_tests
node_workspace_ci -->|"builds"| node_docs_site
node_workspace_ci -->|"releases"| node_plugins_pkg
node_workspace_ci -->|"checks"| node_playground_vue3
node_workspace_ci -->|"checks"| node_playground_nuxt

click node_core_index "https://github.com/unovue/reka-ui/blob/v2/packages/core/src/index.ts"
click node_core_accordion "https://github.com/unovue/reka-ui/tree/v2/packages/core/src/Accordion"
click node_core_popovers "https://github.com/unovue/reka-ui/tree/v2/packages/core/src/Dialog"
click node_core_forms "https://github.com/unovue/reka-ui/tree/v2/packages/core/src/Select"
click node_core_calendar "https://github.com/unovue/reka-ui/tree/v2/packages/core/src/DatePicker"
click node_core_color "https://github.com/unovue/reka-ui/tree/v2/packages/core/src/ColorArea"
click node_core_layout "https://github.com/unovue/reka-ui/tree/v2/packages/core/src/Splitter"
click node_core_tree "https://github.com/unovue/reka-ui/tree/v2/packages/core/src/Tree"
click node_core_infra "https://github.com/unovue/reka-ui/tree/v2/packages/core/src/shared"
click node_core_context "https://github.com/unovue/reka-ui/blob/v2/packages/core/src/shared/createContext.ts"
click node_core_date_utils "https://github.com/unovue/reka-ui/tree/v2/packages/core/src/shared/date"
click node_core_color_utils "https://github.com/unovue/reka-ui/tree/v2/packages/core/src/shared/color"
click node_core_tests "https://github.com/unovue/reka-ui/blob/v2/packages/core/vitest.setup.ts"
click node_docs_site "https://github.com/unovue/reka-ui/blob/v2/docs/.vitepress/config.ts"
click node_docs_demos "https://github.com/unovue/reka-ui/tree/v2/docs/components/demo"
click node_histoire "https://github.com/unovue/reka-ui/blob/v2/.histoire/vite.config.ts"
click node_plugins_pkg "https://github.com/unovue/reka-ui/blob/v2/packages/plugins/src/nuxt/index.ts"
click node_playground_vue3 "https://github.com/unovue/reka-ui/blob/v2/playground/vue3/src/main.ts"
click node_playground_nuxt "https://github.com/unovue/reka-ui/blob/v2/playground/nuxt/nuxt.config.ts"
click node_workspace_ci "https://github.com/unovue/reka-ui/blob/v2/.github/workflows/build.yaml"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_core_index,node_core_accordion,node_core_popovers,node_core_forms,node_core_calendar,node_core_color,node_core_layout,node_core_tree,node_core_infra,node_core_context,node_core_date_utils,node_core_color_utils toneBlue
class node_docs_site,node_docs_demos,node_histoire toneAmber
class node_plugins_pkg,node_playground_vue3,node_playground_nuxt toneMint
class node_core_tests,node_workspace_ci toneRose
```

## Components

### Core library

Main Vue 3 UI primitives and shared foundations.

- [Package entry](https://github.com/unovue/reka-ui/blob/v2/packages/core/src/index.ts): export surface · Top-level entrypoints that aggregate the library package. · `packages/core/src/index.ts`
- [Accordion](https://github.com/unovue/reka-ui/tree/v2/packages/core/src/Accordion): compound component · Representative disclosure-style component built from root/item/trigger/content parts. · `packages/core/src/Accordion`
- [Overlays](https://github.com/unovue/reka-ui/tree/v2/packages/core/src/Dialog): overlay family · Dialog, Popover, Tooltip, HoverCard, DropdownMenu, ContextMenu, Menubar, and related layered interactions. · `packages/core/src/Dialog`
- [Inputs](https://github.com/unovue/reka-ui/tree/v2/packages/core/src/Select): form controls · Editable, Select, Combobox, Listbox, TagsInput, NumberField, PinInput, Toggle, RadioGroup, Checkbox, Switch, Slider, Progress. · `packages/core/src/Select`
- [Dates](https://github.com/unovue/reka-ui/tree/v2/packages/core/src/DatePicker): date subsystem · Date, time, calendar, range, and segmented-input components with shared date math and locale handling. · `packages/core/src/DatePicker`
- [Color](https://github.com/unovue/reka-ui/tree/v2/packages/core/src/ColorArea): color subsystem · Color picker primitives, swatches, sliders, and shared color conversion logic. · `packages/core/src/ColorArea`
- [Layout](https://github.com/unovue/reka-ui/tree/v2/packages/core/src/Splitter): layout primitives · Splitter, ScrollArea, Tabs, Separator, Toolbar, NavigationMenu, Pagination, Stepper, and related structural components. · `packages/core/src/Splitter`
- [Collections](https://github.com/unovue/reka-ui/tree/v2/packages/core/src/Tree): collection/navigation · Tree, RovingFocus, Collection, and other navigable collection patterns with virtualization support. · `packages/core/src/Tree`
- [Infrastructure](https://github.com/unovue/reka-ui/tree/v2/packages/core/src/shared): shared primitives · Primitive, Slot, FocusScope, Presence, Teleport, DismissableLayer, Popper, RovingFocus, Collection, and shared utilities. · `packages/core/src/shared`
- [Context helpers](https://github.com/unovue/reka-ui/blob/v2/packages/core/src/shared/createContext.ts): composables · createContext, useId, useLocale, useDirection, forwarding helpers, and cross-component coordination utilities. · `packages/core/src/shared/createContext.ts`
- [Date utils](https://github.com/unovue/reka-ui/tree/v2/packages/core/src/shared/date): date helpers · Shared calendar/date parsing, formatting, comparison, and segment utilities used by date components. · `packages/core/src/shared/date`
- [Color math](https://github.com/unovue/reka-ui/tree/v2/packages/core/src/shared/color): color helpers · Color parsing, conversion, gradients, and related utility functions. · `packages/core/src/shared/color`

### Docs & demos

VitePress docs, Histoire stories, and authored examples.

- [Docs site](https://github.com/unovue/reka-ui/blob/v2/docs/.vitepress/config.ts): VitePress · Public documentation site, page content, theme components, and generated docs data. · `docs/.vitepress/config.ts`
- [Demos](https://github.com/unovue/reka-ui/tree/v2/docs/components/demo): story/demo layer · Interactive demo components and authored examples used by docs and story surfaces. · `docs/components/demo`
- [Histoire](https://github.com/unovue/reka-ui/blob/v2/.histoire/vite.config.ts): storybook-like · Component exploration and story authoring environment configured in the Histoire workspace. · `.histoire/vite.config.ts`

### Integration

Framework tooling and consumer playground apps.

- [Plugins](https://github.com/unovue/reka-ui/blob/v2/packages/plugins/src/nuxt/index.ts): integration package · Resolver, Nuxt integration, and namespaced component generation for framework consumers. · `packages/plugins/src/nuxt/index.ts`
- [Vue playground](https://github.com/unovue/reka-ui/blob/v2/playground/vue3/src/main.ts): consumer app · Plain Vue 3 playground that exercises the published package in a real app shell. · `playground/vue3/src/main.ts`
- [Nuxt playground](https://github.com/unovue/reka-ui/blob/v2/playground/nuxt/nuxt.config.ts): consumer app · Nuxt playground used to validate framework integration and auto-import behavior. · `playground/nuxt/nuxt.config.ts`

### Ops

Workspace, testing, and release automation.

- [Vitest](https://github.com/unovue/reka-ui/blob/v2/packages/core/vitest.setup.ts): verification · Unit, component, and snapshot tests validating library behavior. · `packages/core/vitest.setup.ts`
- [CI & release](https://github.com/unovue/reka-ui/blob/v2/.github/workflows/build.yaml): automation · Workspace management, GitHub Actions, build, publish, release, and repo checks. · `.github/workflows/build.yaml`

## Connections

- Package entry → Accordion: exports · Public package entry exports component modules.
- Package entry → Overlays: exports · Exports layered overlay primitives and menus.
- Package entry → Inputs: exports · Exports form and control primitives.
- Package entry → Dates: exports · Exports date, time, and calendar components.
- Package entry → Color: exports · Exports color-related primitives.
- Package entry → Layout: exports · Exports structural and navigation components.
- Package entry → Collections: exports · Exports collection and navigation primitives.
- Accordion → Infrastructure: uses · Component behavior is built on shared primitives and interaction mechanics.
- Overlays → Infrastructure: uses · Overlay systems depend on focus, portal, presence, dismiss, and popper infrastructure.
- Inputs → Context helpers: uses · Parts coordinate through context and composable helpers.
- Inputs → Infrastructure: uses · Keyboard navigation, presence, and primitive rendering are reused here.
- Dates → Date utils: uses · Calendar and time controls share date math, parsing, and locale formatting.
- Dates → Context helpers: uses · Date roots and segmented inputs coordinate state via context.
- Color → Color math: uses · Color pickers and swatches rely on shared color conversion and gradient logic.
- Layout → Infrastructure: uses · Navigation and layout primitives use shared focus, scroll, and positioning utilities.
- Collections → Infrastructure: uses · Virtualized and navigable collections depend on shared collection and roving focus behavior.
- Docs site → Package entry: consumes · Docs pages render the published library package.
- Docs site → Demos: embeds · Docs pages assemble interactive demos and component examples.
- Histoire → Package entry: renders · Story stories import and exercise component APIs from source/package.
- Histoire → Demos: shares examples · Story and docs demo layers reuse authored example patterns.
- Plugins → Package entry: integrates · Framework tooling targets the core component exports.
- Vue playground → Package entry: consumes · Vue playground validates real consumer usage of the package.
- Nuxt playground → Plugins: uses · Nuxt playground validates plugin-based integration and auto-imports.
- Nuxt playground → Package entry: consumes · Also exercises the published UI package directly.
- CI & release → Vitest: validates · CI runs unit/component tests and repository checks.
- CI & release → Docs site: builds · CI builds and publishes the documentation site.
- CI & release → Plugins: releases · CI publishes or validates package release artifacts.
- CI & release → Vue playground: checks · Consumer apps are part of workspace verification.
- CI & release → Nuxt playground: checks · Consumer apps are part of workspace verification.
