DUI Primitives

Unstyled, accessible Lit web components. Structure and behavior only — zero visual opinions.

DUI Primitives gives you the hard parts for free: keyboard navigation, focus management, ARIA patterns, form participation, and compound component coordination. You bring the CSS.

Think Radix Primitives, but as web components that work in any framework — or no framework at all.

Why

Building a custom design system shouldn't mean reimplementing accordion keyboard navigation, dialog focus trapping, or combobox typeahead from scratch. Primitives handle all of that, then get out of the way.

• Unstyled — structural CSS only (display, position, overflow). No colors, no spacing, no border-radius.
• Accessible — follows WAI-ARIA APG patterns. Keyboard navigation, screen reader support, focus management built in.
• Framework-agnostic — standard web components. Works in React, Vue, Svelte, Angular, or plain HTML.
• Extensible — plain classes with static styles. Extend with your own CSS to build any aesthetic.
• Composable — compound components (dialog + trigger + popup + close) coordinate via Lit Context. No prop drilling.
• Form-ready — inputs, checkboxes, selects, and switches participate in native <form> via ElementInternals.

Install

npm install @deepfuture/dui-primitives

Quick Start

Primitives are classes, not self-registering elements. You register them yourself:

import { DuiDialogPrimitive, DuiDialogTriggerPrimitive, DuiDialogPopupPrimitive, DuiDialogClosePrimitive } from "@deepfuture/dui-primitives/dialog";
import { DuiButtonPrimitive } from "@deepfuture/dui-primitives/button";

// Register as custom elements
customElements.define("dui-button", DuiButtonPrimitive);
customElements.define("dui-dialog", DuiDialogPrimitive);
customElements.define("dui-dialog-trigger", DuiDialogTriggerPrimitive);
customElements.define("dui-dialog-popup", DuiDialogPopupPrimitive);
customElements.define("dui-dialog-close", DuiDialogClosePrimitive);

<dui-dialog>
  <dui-dialog-trigger>
    <dui-button>Open</dui-button>
  </dui-dialog-trigger>
  <dui-dialog-popup>
    <h2>Dialog title</h2>
    <p>Focus is trapped. Press Escape to close.</p>
    <dui-dialog-close>
      <dui-button>Close</dui-button>
    </dui-dialog-close>
  </dui-dialog-popup>
</dui-dialog>

That gives you a fully functional dialog with focus trapping, escape-to-close, and focus restoration — but no visual styling beyond layout. Add your own:

dui-button::part(root) {
  padding: 8px 16px;
  border: 1px solid #ccc;
  border-radius: 6px;
  background: #f5f5f5;
  cursor: pointer;
}

dui-dialog-popup::part(root) {
  position: fixed;
  top: 50%; left: 50%;
  transform: translate(-50%, -50%);
  background: white;
  border-radius: 12px;
  padding: 24px;
  box-shadow: 0 8px 30px rgba(0,0,0,0.12);
}

Extending Primitives

The real power is extending primitives to build your own design system:

import { css } from "lit";
import { DuiSwitchPrimitive } from "@deepfuture/dui-primitives/switch";

class MySwitch extends DuiSwitchPrimitive {
  static override styles = [
    ...DuiSwitchPrimitive.styles,
    css`
      [part="root"] {
        width: 44px;
        height: 24px;
        border-radius: 12px;
        background: #ddd;
        transition: background 150ms ease;
      }
      [part="root"][data-checked] {
        background: #4f46e5;
      }
      [part="thumb"] {
        width: 20px;
        height: 20px;
        border-radius: 50%;
        background: white;
        box-shadow: 0 1px 3px rgba(0,0,0,0.2);
        transition: transform 150ms ease;
      }
    `,
  ];
}

customElements.define("my-switch", MySwitch);

All behavior — keyboard toggle, form participation, ARIA attributes, checked state — comes from the primitive. Your subclass only adds aesthetics.

Components

43 component groups, 85+ elements total.

| Category | Primitives | |----------|-----------| | Actions | Button, Split Button, Toggle, Toggle Group, Toolbar | | Forms | Input, Textarea, Select, Combobox, Checkbox, Checkbox Group, Radio, Radio Group, Switch, Slider, Number Field, Stepper, Dropzone, Field, Fieldset | | Data Display | Badge, Avatar, Calendar, Data Table, Progress, Spinner, Separator, Trunc, Card, Card Grid | | Overlays | Dialog, Alert Dialog, Popover, Tooltip, Menu, Menubar, Preview Card, Command | | Disclosure | Accordion, Collapsible, Tabs | | Navigation | Breadcrumb, Sidebar (13 sub-components) | | Layout | Scroll Area, Portal | | Utility | Icon |

Styling Surface

Every primitive exposes CSS parts for styling:

/* ::part(root) is available on every component */
dui-button::part(root) { ... }

/* Complex components expose additional parts */
dui-switch::part(track) { ... }
dui-switch::part(thumb) { ... }
dui-slider::part(track) { ... }
dui-slider::part(thumb) { ... }
dui-checkbox::part(control) { ... }

/* State is reflected as data attributes */
dui-button::part(root):hover { ... }
dui-switch::part(root)[data-checked] { ... }
dui-checkbox::part(root)[data-checked] { ... }
dui-accordion-item::part(root)[data-open] { ... }

Slot-based composition for content projection:

<dui-accordion-item value="item-1">
  <div slot="trigger">Click to expand</div>
  <div slot="content">Panel content here</div>
</dui-accordion-item>

Package

| Package | Description | |---------|------------| | @deepfuture/dui-primitives | All unstyled component primitives + core utilities |

Core utilities (base class, event factory, popup coordinator, floating UI) are included and available via @deepfuture/dui-primitives/core:

• base — shared CSS reset applied to all primitive shadow DOMs
• customEvent() — typed event factory for component events
• popup-coordinator — singleton that manages popup stacking and light-dismiss
• floating-popup-utils / floating-portal-controller — Floating UI integration for positioned overlays
• dom — shadow-DOM-aware DOM utilities

Building a Design System on Primitives

DUI Primitives is the foundation layer. The DUI design system is built on top of it, adding:

• Design tokens — CSS custom properties for colors, spacing, typography, radii
• Component styles — aesthetic CSS composed onto each primitive via applyTheme()
• Variants — variant="primary", appearance="outline", size="sm", etc.
• Templates — pre-composed UI patterns (feed items, stat cards, dashboards)

You can do the same — or build something completely different. The primitives don't care what your design system looks like.

Development

# Dev server (primitives docs)
deno task dev

# Build for npm
deno task build

# Version bump
deno task version patch

# Publish
deno task publish          # dry run
deno task publish:live     # real publish

License

MIT