Base UI → DUI Primitive Port

Port a Base UI (@base-ui/react) component into a DUI primitive — unstyled, accessible, structural and behavioral only.

Overview

Base UI is an unstyled React component library with composable "parts" (e.g. Switch.Root, Switch.Thumb). Porting to DUI primitives means:

1. React parts → single Lit LitElement class (simple) or Lit Context compound (complex)
2. CSS Modules demo → extract structural CSS only (layout, positioning, overflow)
3. data-* attributes → preserved on internal elements as the styling API for consumers
4. No @customElement — consumers register manually via customElements.define()

Since DUI primitives are unstyled, all aesthetic CSS from Base UI is discarded. We extract only the structural and behavioral patterns.

References

• An existing primitive for reference (e.g., packages/primitives/src/button/button.ts, packages/primitives/src/switch/switch.ts)
• For compound primitives: packages/primitives/src/accordion/ (Lit Context pattern)

Step 1 — Fetch the Base UI docs

Fetch the component documentation before writing code:

https://base-ui.com/react/components/{component}.md

Also fetch if needed:

• https://base-ui.com/llms.txt — component index
• https://base-ui.com/react/handbook/styling.md
• https://base-ui.com/react/handbook/animation.md

Extract:

1. Anatomy — composable parts (Root, Trigger, Panel, Thumb, etc.)
2. Props per part — public props, callback props
3. Data attributes — data-checked, data-disabled, data-open, etc.
4. CSS variables — --accordion-panel-height, etc.
5. Accessibility — ARIA roles, keyboard interactions

Step 2 — Extract structural CSS

From Base UI's CSS Modules demo, extract only structural properties:

The primitive provides behavior and structure. Consumers add all visual styling via ::part() and CSS custom properties.

Step 3 — Map Base UI patterns to DUI

Data attributes on internal elements

Base UI uses data-* attributes for CSS targeting. Preserve these — they are the consumer's styling API:

typescript
1override render(): TemplateResult {
2  return html`
3    <span
4      part="root"
5      role="switch"
6      aria-checked=${this.#checked}
7      ?data-checked=${this.#checked}
8      ?data-unchecked=${!this.#checked}
9      ?data-disabled=${this.#isDisabled}
10      tabindex="${isDisabled ? nothing : "0"}"
11      @click=${this.#handleClick}
12      @keydown=${this.#handleKeyDown}
13    >
14      <span
15        part="thumb"
16        ?data-checked=${this.#checked}
17        ?data-unchecked=${!this.#checked}
18      ></span>
19    </span>
20  `;
21}

Consumers style these in their own CSS:

css
1dui-switch::part(root)[data-checked] {
2  background: var(--brand-color);
3}

Reflected properties

Expose properties as reflected attributes where they affect visual state:

typescript
1@property({ type: Boolean, reflect: true })
2accessor disabled = false;

Do NOT add variant/appearance/size properties — those are a design-system concern, not a primitive concern. Only reflect properties that affect behavior or accessibility.

React → Lit mapping

Controlled/uncontrolled

Support both patterns. Provide defaultChecked for initial value and checked for controlled:

typescript
1@property({ type: Boolean, reflect: true })
2accessor checked: boolean | undefined = undefined;
3
4@property({ type: Boolean, attribute: "default-checked" })
5accessor defaultChecked = false;
6
7@state() accessor #internalChecked = false;
8
9get #checked(): boolean {
10  return this.checked ?? this.#internalChecked;
11}

Step 4 — Compound primitives

For multi-part Base UI components (Accordion, Tabs, Menu), decide the coordination pattern:

Lit Context pattern

typescript
1// {name}-context.ts
2import { createContext } from "@lit/context";
3
4export type {Name}Context = {
5  readonly openValues: string[];
6  readonly disabled: boolean;
7  readonly toggle: (value: string) => void;
8};
9
10export const {name}Context = createContext<{Name}Context>("dui-{name}");

Parent provides via @provide, children consume via @consume with subscribe: true.

Key principles:

• No imperative coordination — no querySelectorAll, no this.closest()
• Immutable context updates — spread, never mutate
• Actions via context callbacks — children call ctx.toggle() directly
• Public events still dispatched for consumers

Step 5 — Animation

Base UI uses data-starting-style and data-ending-style for enter/exit animations. Preserve these on internal elements:

typescript
1@state() accessor #starting = false;
2@state() accessor #ending = false;
3
4async #animateOpen(): Promise<void> {
5  this.#starting = true;
6  await new Promise(r => requestAnimationFrame(() => requestAnimationFrame(r)));
7  this.#starting = false;
8}
9
10#animateClose(): void {
11  this.#ending = true;
12  const el = this.shadowRoot?.querySelector("[part='panel']");
13  el?.addEventListener("transitionend", () => {
14    this.#ending = false;
15    this.#open = false;
16  }, { once: true });
17}

Thread to internal elements:

typescript
1<div part="panel"
2  ?data-starting-style=${this.#starting}
3  ?data-ending-style=${this.#ending}>

Consumers write their own transition CSS targeting these attributes.

Step 6 — Accessibility

Focus management

• Components wrapping native <button>: Use delegatesFocus:

  typescript
  1static override shadowRootOptions = {
  2  ...LitElement.shadowRootOptions,
  3  delegatesFocus: true,
  4};

• Non-native focusable elements (e.g., <span role="switch">): Add tabindex="0" and remove when disabled:

  typescript
  1tabindex="${isDisabled ? nothing : "0"}"

Conditional ARIA attributes

Use Lit's nothing sentinel — don't render aria-disabled="false":

typescript
1aria-disabled="${this.disabled ? "true" : nothing}"

Form participation

For controls that participate in native <form> submission (switch, checkbox, slider, etc.), use ElementInternals:

typescript
1static formAssociated = true;
2
3#internals!: ElementInternals;
4
5constructor() {
6  super();
7  this.#internals = this.attachInternals();
8}

Step 7 — Create the files

Use the /create-primitive skill's file structure. Create:

1. Primitive class — packages/primitives/src/{name}/{name}.ts (structural CSS only)
2. Index — packages/primitives/src/{name}/index.ts (re-exports)
3. Context — packages/primitives/src/{name}/{name}-context.ts (if compound)
4. Config update — packages/primitives/deno.json

Add a provenance comment at the top:

typescript
1/** Ported from Base UI: https://base-ui.com/react/components/{component} */

Step 8 — Add to docs, verify

Use /edit-docs to wire into the docs site. Run deno check from the repo root.

Validation checklist

Component structure

• Provenance comment: /** Ported from Base UI: ... */
• Class name uses Primitive suffix (Dui{Name}Primitive)
• Extends LitElement — not a custom base class
• static tagName with as const — no @customElement
• static override styles = [base, styles]
• part="root" on root element, other part attributes match Base UI anatomy
• Structural CSS only — no colors, fonts, spacing, border-radius, shadows
• Only behavioral properties reflected (disabled, checked, open) — no variant/size/appearance
• All decorated properties use accessor keyword
• All internal state uses @state() accessor #name (native private)
• All private methods use #private syntax
• All lifecycle overrides use the override keyword
• Events use customEvent() factory with bubbles: true, composed: true
• JSDoc with @slot, @csspart, @fires as needed

Data attributes & styling API

• data-* attributes on internal elements match Base UI originals
• Consumers can style all visual aspects via ::part() + data attributes
• No aesthetic opinions baked in — no hover colors, focus rings, disabled opacity

Accessibility

• ARIA attributes correct (role, aria-checked, aria-expanded, etc.)
• nothing sentinel used for conditional ARIA attributes
• delegatesFocus set when wrapping native <button>
• tabindex managed for non-native focusable elements (removed when disabled)
• Form participation via ElementInternals for form controls
• Keyboard interactions match Base UI docs

Behavior

• Controlled/uncontrolled patterns supported where applicable
• Animation uses data-starting-style / data-ending-style on internal elements
• Compound primitives use Lit Context (not imperative coordination)
• Context updates are immutable (spread, not mutation)

Wiring

• index.ts re-exports all classes
• deno.json export added
• Registered in packages/docs/src/register-primitives.ts
• deno check passes