dui（酒驾）

DUI

DUI is a styled Lit web component library built on two-layer inheritance. Unstyled primitives (in a separate repo) provide structure and behavior; styled components extend them with aesthetic CSS and design tokens. Components self-register on import — no setup function, no configuration.

Project detection

Before writing any DUI code, check the project's DUI status:

1. Check package.json for @deepfuture/dui-components deps, or deno.json for @dui/components/* import map entries
2. If found, note which packages are installed — components self-register on import, so look for import "@deepfuture/dui-components/button" or import "@dui/components/button" patterns
3. If DUI is not installed, follow the install instructions below
4. Check whether @deepfuture/dui-inspector (or @dui/inspector) is available — if so, use the inspector workflow below

Principles

1. Use DUI components first. Before writing custom markup, check if a DUI component exists. Read references/components.md for the full catalog.
2. Inspect before styling or debugging. Before overriding any DUI token or adding custom CSS to a DUI component, run __dui_inspect('dui-component-name') to see available tokens, parts, slots, and current values. Do the same when debugging unexpected behavior. The inspector is the ground truth.
3. Style via CSS custom properties, not DOM manipulation. Components expose --token-name custom properties as their styling API. Don't reach into shadow DOM.
4. Use ::part(root) for CSS properties that don't have a token. Every component exposes a root part for full CSS expressiveness (backdrop-filter, transforms, box-shadow, etc.).
5. Use semantic design tokens. Use tokens (e.g. --foreground, --background, --accent) before hardcoded colors like #3b82f6.
6. Compose, don't reinvent. A settings page = dui-tabs + dui-input + dui-select + dui-switch. A dashboard = dui-sidebar + dui-data-table + layout primitives.

Installation

npm

npm install @deepfuture/dui-components

CDN (zero setup)

<script type="module" src="https://cdn.jsdelivr.net/npm/@deepfuture/dui-cdn/dui.min.js"></script>

The CDN bundle registers all components automatically.

Deno (from source)

Add @dui/* entries to your app's deno.json import map:

{
  "imports": {
    "@dui/components/button": "../dui/packages/components/src/button/index.ts"
  }
}

Usage

Components self-register on import. No setup function, no configuration:

// À la carte — import only what you use
import "@deepfuture/dui-components/button";
import "@deepfuture/dui-components/dialog";

// Or register everything
import "@deepfuture/dui-components";

Each import registers the component and all its sub-components. Importing dialog registers dui-dialog, dui-dialog-trigger, dui-dialog-popup, and dui-dialog-close.

Templates

Templates are pre-composed UI patterns. Install alongside the components:

npm install @deepfuture/dui-templates

import "@deepfuture/dui-templates/feed";  // registers dui-feed-item etc.

Typography & spacing

DUI applies text-box: trim-both cap alphabetic to all prose elements (h1–h6, p, li, blockquote, dt, dd). This trims the invisible leading/trailing space from text boxes so glyphs sit on exact pixel boundaries. Combined with the global margin reset, text elements have zero implicit spacing — no default margins, no line-height padding above or below.

This means you must explicitly create all vertical rhythm between text elements. Without it, headings and paragraphs will visually collide.

The rule

**Every group of text elements needs explicit spacing via gap (on a flex/grid parent) or margin-bottom using --space-* tokens.** Never rely on default browser margins or line-height to separate text.

Recommended approach

Wrap related text in a flex column with gap:

.page-header {
  display: flex;
  flex-direction: column;
  gap: var(--space-2);           /* breathing room between title and subtitle */
  margin-bottom: var(--space-6); /* space before the next section */
}

<div class="page-header">
  <h1>Dashboard</h1>
  <p>Overview of recent order activity and key metrics.</p>
</div>

Inside cards and panels, the same pattern applies:

.stat-card {
  display: flex;
  flex-direction: column;
  gap: var(--space-2);
}

.stat-label {
  font-size: var(--text-xs);
  color: var(--text-2);
}

.stat-value {
  font-size: var(--text-3xl);
  font-weight: var(--font-weight-semibold);
}

.stat-change {
  font-size: var(--text-sm);
  color: var(--accent);
}

Spacing guidelines

dui-prose for long-form content

For rendered markdown or CMS content where you want automatic spacing, apply class="dui-prose" to the container. This restores heading margins, paragraph spacing, list indentation, and other typographic defaults — all using design tokens.

<div class="dui-prose">
  <h1>Release Notes</h1>
  <p>Version 2.0 brings major improvements...</p>
</div>

dui-prose is for long-form content only. For app UI (dashboards, forms, settings), use explicit flex/gap spacing as shown above.

See references/rules.md for incorrect/correct code pairs.

Critical rules

Styling

• CSS custom properties are the styling API. Override --button-bg, --button-radius, etc. — not internal shadow DOM elements.
• ::part(root) for everything else. Filters, transforms, backdrop-filter, box-shadow — anything not covered by a token.
• No !important. If you need !important, you're fighting the system — use the right token or part instead.
• Semantic tokens for colors. --foreground, --background, --accent, --surface-1/--surface-2 — never raw color values, unless absolutely necessary.
• Dark mode via data-theme="dark" on <html>. The token stylesheet handles the rest via custom property overrides. Never add manual dark-mode color logic.

Composition

• Slots are the composition API. Pass content into components via slots, not by wrapping in divs.
• Compound components stay together. dui-dialog-trigger belongs inside dui-dialog. dui-select-option belongs inside dui-select. Don't restructure compound component hierarchies.
• Never reach into shadow DOM. Don't use querySelector on a component's shadowRoot from outside. Use CSS custom properties, ::part(root), or the inspector API instead.
• Use standard CSS for layout. Use flexbox and grid directly for layout (rows, columns, centering, page margins). DUI does not provide layout wrapper components — layout is CSS's job.

Icons

• dui-icon with currentColor convention. The icon inherits text color from its parent. Override with --icon-color and --icon-size custom properties.
• Slot-based content. Pass SVG or img into dui-icon's default slot.

See references/rules.md for incorrect/correct code pairs for every rule above.

Component selection

Read references/components.md for the full catalog. Quick lookup:

Choosing between overlays

Use DUI components, not custom markup

See references/rules.md for incorrect/correct code pairs for every rule.

Theming

DUI's color system is built on 4 OKLCH primitives with compositional derivation:

Everything else is derived: --surface-1/2/3 (elevated surfaces via lightness offsets), --text-1/2/3 (text tiers via alpha), --border/--border-strong (foreground at reduced alpha), --accent-subtle, --destructive-subtle. Customizing the palette means changing 4 values.

Design tokens are injected into document.adoptedStyleSheets at import time. They cascade into shadow DOM via CSS custom property inheritance.

Dark mode

<html data-theme="dark">
  <!-- All DUI components render in dark mode -->
</html>

Toggle by setting/removing data-theme="dark" on <html>. The token stylesheet redefines the 4 primitives for dark mode; all derived tokens update automatically.

// Toggle dark mode
document.documentElement.setAttribute("data-theme", "dark");
// Revert to light
document.documentElement.removeAttribute("data-theme");

Customizing the palette

Override the 4 primitives on :root:

:root {
  --accent: oklch(0.6 0.2 280);        /* purple accent */
  --background: oklch(0.96 0.01 80);   /* warm canvas */
}

All derived tokens update automatically.

Two-layer styling

Variables cascade from ancestors. ::part() must target the element directly.

Theme attributes vs properties

Some attributes like variant, appearance, and size are theme attributes — they're reflected HTML attributes that the styled CSS layer selects on (:host([variant="primary"])). They appear as attributes in markup:

<dui-button variant="primary" size="lg">Save</dui-button>
<dui-badge variant="danger" appearance="soft">Error</dui-badge>

Behavioral properties like disabled, open, value are reactive Lit properties that affect component behavior and DOM structure.

Event handling

dui-navigate for link buttons

When <dui-button href="..."> is clicked (without modifier keys), it fires dui-navigate. Wire into your router:

document.addEventListener("dui-navigate", (e: CustomEvent<{ href: string }>) => {
  router.navigate(e.detail.href);
});

Component events

Listen on the element:

html`
  <dui-switch @checked-change=${(e: CustomEvent<{ checked: boolean }>) => {
    console.log("Switch toggled:", e.detail.checked);
  }}></dui-switch>
`;

Inspector workflow

When @dui/inspector (or @deepfuture/dui-inspector) is installed, use the inspector to discover, verify, and prototype with DUI components at runtime. This is the most accurate way to understand what's available and how components behave.

CRITICAL: Use the inspector BEFORE writing any DUI styling code — not just for debugging. Run __dui_inspect('dui-sidebar-menu-button') before overriding sidebar tokens. Run __dui_inspect('dui-data-table') before customizing table appearance. The inspector shows which tokens actually exist, what they're called, and their current values. Guessing at token names wastes iterations.

The inspector provides console globals. If the project has a running dev server with a browser, use these in the browser console or via a Playwright/Puppeteer script.

Discovery

// See all DUI components on the page + full catalog of registered types
__dui_inspect()

// Inspect a specific component — get properties, tokens, slots, parts, events
__dui_inspect('dui-button')
__dui_inspect('[data-dui-id="5"]')

The catalog field from __dui_inspect() lists every registered dui-* tag with its property schema, slots, and parts — including components not currently rendered.

Prototyping

// Insert a component into the page
__dui_mutate.insertComponent('[data-dui-id="3"]', 'beforeend', 'dui-button',
  { variant: 'primary' }, 'Click me')

// Set a property
__dui_mutate.setProp('[data-dui-id="5"]', 'variant', 'danger')

// Change a design token globally
__dui_mutate.setToken('--radius-md', '1rem')

// Change a token on one instance
__dui_mutate.setComponentToken('[data-dui-id="5"]', '--button-bg', 'red')

// Replace slot content
__dui_mutate.setSlotContent('[data-dui-id="5"]', '', '<span>New label</span>')

// Remove or move components
__dui_mutate.removeComponent('[data-dui-id="5"]')
__dui_mutate.moveComponent('[data-dui-id="5"]', '[data-dui-id="10"]', 'beforeend')

Verify → export → write

// Export all mutations as structured source file changes
__dui_export()
// → [{ file: "...", changeType: "token"|"template", description: "...", ... }]

Typical agent workflow

1. __dui_inspect()                              → discover available components via catalog
2. __dui_mutate.insertComponent(...)             → build the UI
3. __dui_mutate.setProp(selector, prop, value)   → configure components
4. __dui_inspect(selector)                       → verify state
5. __dui_export()                                → get structured source changes
6. Write changes to source files                  → done

When the inspector is not available, fall back to the static component reference in references/components.md and write code directly.

Detailed references

• references/components.md — Full catalog of all 57 component families with properties, theme attributes, slots, parts, and CSS custom properties
• references/rules.md — Incorrect/correct code pairs for every critical rule
• references/blocks.md — Real-world composition examples: settings forms, chat inputs, dashboards, maps, data tables, and more. Each entry summarizes the pattern and key CSS/layout techniques, with a pointer to the full source. Read a block's source file when building something similar.
• references/inspector.md — Complete inspector API reference