Lit Component Development for Common UI

This skill provides guidance for developing Lit web components within the Common UI v2 component library (packages/ui/src/v2).

When to Use This Skill

Use this skill when:

Creating new ct- prefixed components in the UI package
Modifying existing Common UI v2 components
Implementing theme-aware components
Integrating components with Cell abstractions from the runtime
Building reactive components for pattern UIs
Debugging component lifecycle or reactivity issues

Core Philosophy

Common UI is inspired by SwiftUI and emphasizes:

Default Configuration Works: Components should work together with minimal configuration
Composition Over Control: Emphasize composing components rather than granular styling
Adaptive to User Preferences: Respect system preferences and theme settings (theme is ambient context, not explicit props)
Reactive Binding Model: Integration with FRP-style Cell abstractions from the runtime
Progressive Enhancement: Components work with plain values but enhance with Cells for reactivity
Separation of Concerns: Presentation components, theme-aware inputs, Cell-aware state, runtime-integrated operations

Quick Start Pattern

1. Choose Component Category

Identify which category the component falls into:

Layout: Arranges other components (vstack, hstack, screen)
Visual: Displays styled content (separator, skeleton, label)
Input: Captures user interaction (button, input, checkbox)
Complex/Integrated: Deep runtime integration with Cells (render, code-editor, outliner)

Complexity spectrum: Components range from pure presentation (no runtime) to deeply integrated (Cell operations, pattern execution, backlink resolution). Choose the simplest pattern that meets requirements.

See references/component-patterns.md for detailed patterns for each category and references/advanced-patterns.md for complex integration patterns.

2. Create Component Files

Create the component directory structure:

packages/ui/src/v2/components/ct-component-name/
├── ct-component-name.ts    # Component implementation
├── index.ts                # Export and registration
└── styles.ts               # Optional: for complex components

3. Implement Component

Basic template:

import { css, html } from "lit";
import { BaseElement } from "../../core/base-element.ts";

export class CTComponentName extends BaseElement {
  static override styles = [
    BaseElement.baseStyles,
    css`
      :host {
        display: block;
        box-sizing: border-box;
      }

      *,
      *::before,
      *::after {
        box-sizing: inherit;
      }
    `,
  ];

  static override properties = {
    // Define reactive properties
  };

  constructor() {
    super();
    // Set defaults
  }

  override render() {
    return html`<!-- component template -->`;
  }
}

globalThis.customElements.define("ct-component-name", CTComponentName);

4. Create Index File

import { CTComponentName } from "./ct-component-name.ts";

if (!customElements.get("ct-component-name")) {
  customElements.define("ct-component-name", CTComponentName);
}

export { CTComponentName };
export type { /* exported types */ };

Theme Integration

For components that need to consume theme (input and complex components):

import { consume } from "@lit/context";
import { property } from "lit/decorators.js";
import {
  applyThemeToElement,
  type CTTheme,
  defaultTheme,
  themeContext,
} from "../theme-context.ts";

export class MyComponent extends BaseElement {
  @consume({ context: themeContext, subscribe: true })
  @property({ attribute: false })
  declare theme?: CTTheme;

  override firstUpdated(changed: Map<string | number | symbol, unknown>) {
    super.firstUpdated(changed);
    this._updateThemeProperties();
  }

  override updated(changed: Map<string | number | symbol, unknown>) {
    super.updated(changed);
    if (changed.has("theme")) {
      this._updateThemeProperties();
    }
  }

  private _updateThemeProperties() {
    const currentTheme = this.theme || defaultTheme;
    applyThemeToElement(this, currentTheme);
  }
}

Then use theme CSS variables with fallbacks:

.button {
  background-color: var(
    --ct-theme-color-primary,
    var(--ct-colors-primary-500, #3b82f6)
  );
  border-radius: var(
    --ct-theme-border-radius,
    var(--ct-border-radius-md, 0.375rem)
  );
  font-family: var(--ct-theme-font-family, inherit);
}

Complete theme reference: See references/theme-system.md for all available CSS variables and helper functions.

Cell Integration

For components that work with reactive runtime data:

import { property } from "lit/decorators.js";
import type { Cell } from "@commontools/runner";
import { isCell } from "@commontools/runner";

export class MyComponent extends BaseElement {
  @property({ attribute: false })
  declare cell: Cell<MyDataType>;

  private _unsubscribe: (() => void) | null = null;

  override updated(changedProperties: Map<string, any>) {
    super.updated(changedProperties);

    if (changedProperties.has("cell")) {
      // Clean up previous subscription
      if (this._unsubscribe) {
        this._unsubscribe();
        this._unsubscribe = null;
      }

      // Subscribe to new Cell
      if (this.cell && isCell(this.cell)) {
        this._unsubscribe = this.cell.sink(() => {
          this.requestUpdate();
        });
      }
    }
  }

  override disconnectedCallback() {
    super.disconnectedCallback();
    if (this._unsubscribe) {
      this._unsubscribe();
      this._unsubscribe = null;
    }
  }

  override render() {
    if (!this.cell) return html``;

    const value = this.cell.get();
    return html`<div>${value}</div>`;
  }
}

Complete Cell patterns: See references/cell-integration.md for:

Subscription management
Nested property access with .key()
Array cell manipulation
Transaction-based mutations
Finding cells by equality

Reactive Controllers

For reusable component behaviors, use reactive controllers. Example: InputTimingController for debouncing/throttling:

import { InputTimingController } from "../../core/input-timing-controller.ts";

export class CTInput extends BaseElement {
  @property()
  timingStrategy: "immediate" | "debounce" | "throttle" | "blur" = "debounce";

  @property()
  timingDelay: number = 500;

  private inputTiming = new InputTimingController(this, {
    strategy: this.timingStrategy,
    delay: this.timingDelay,
  });

  private handleInput(event: Event) {
    const value = (event.target as HTMLInputElement).value;

    this.inputTiming.schedule(() => {
      this.emit("ct-change", { value });
    });
  }
}

Common Patterns

Event Emission

Use the emit() helper from BaseElement:

private handleChange(newValue: string) {
  this.emit("ct-change", { value: newValue });
}

Events are automatically bubbles: true and composed: true.

Dynamic Classes

Use classMap for conditional classes:

import { classMap } from "lit/directives/class-map.js";

const classes = {
  button: true,
  [this.variant]: true,
  disabled: this.disabled,
};

return html`<button class="${classMap(classes)}">...</button>`;

List Rendering

Use repeat directive with stable keys:

import { repeat } from "lit/directives/repeat.js";

return html`
  ${repeat(
    items,
    (item) => item.id,  // stable key
    (item) => html`<div>${item.title}</div>`
  )}
`;

Testing

Colocate tests with components:

// ct-button.test.ts
import { describe, it } from "@std/testing/bdd";
import { expect } from "@std/expect";
import { CTButton } from "./ct-button.ts";

describe("CTButton", () => {
  it("should be defined", () => {
    expect(CTButton).toBeDefined();
  });

  it("should have default properties", () => {
    const element = new CTButton();
    expect(element.variant).toBe("primary");
  });
});

Run with: deno task test (includes required flags)

Package Structure

Components are exported from @commontools/ui/v2:

// packages/ui/src/v2/index.ts
export { CTButton } from "./components/ct-button/index.ts";
export type { ButtonVariant } from "./components/ct-button/index.ts";

Reference Documentation

Load these references as needed for detailed guidance:

references/component-patterns.md - Detailed patterns for each component category, file structure, type safety, styling conventions, event handling, and lifecycle methods
references/theme-system.md - Theme philosophy, ct-theme provider, CTTheme interface, CSS variables, and theming patterns
references/cell-integration.md - Comprehensive Cell integration patterns including subscriptions, mutations, array handling, and common pitfalls
references/advanced-patterns.md - Advanced architectural patterns revealed by complex components: context provision, third-party integration, reactive controllers, path-based operations, diff-based rendering, and progressive enhancement

Key Conventions

Always extend BaseElement - Provides emit() helper and base CSS variables
Include box-sizing reset - Ensures consistent layout behavior
Use attribute: false for objects/arrays/Cells - Prevents serialization errors
Prefix custom events with ct- - Namespace convention
Export types separately - Use export type { ... }
Clean up subscriptions - Always unsubscribe in disconnectedCallback()
Use transactions for Cell mutations - Never mutate cells directly
Provide CSS variable fallbacks - Components should work without theme context
Document with JSDoc - Include @element, @attr, @fires, @example
Run tests with deno task test - Not plain deno test

Common Pitfalls to Avoid

❌ Forgetting to clean up Cell subscriptions (causes memory leaks)
❌ Mutating Cells without transactions (breaks reactivity)
❌ Using array index as key in repeat() (breaks reactivity)
❌ Missing box-sizing reset (causes layout issues)
❌ Not providing CSS variable fallbacks (breaks without theme)
❌ Using attribute: true for objects/arrays (serialization errors)
❌ Skipping super calls in lifecycle methods (breaks base functionality)

Architecture Patterns to Study

Study these components to understand architectural patterns:

Basic patterns:

Simple visual: ct-separator - Minimal component, CSS parts, ARIA
Layout: ct-vstack - Flexbox abstraction, utility classes with classMap
Themed input: ct-button - Theme consumption, event emission, variants

Advanced patterns:

Context provider: ct-theme - Ambient configuration with @provide, display: contents, reactive Cell subscriptions
Runtime rendering: ct-render - Pattern loading, UI extraction, lifecycle management
Third-party integration: ct-code-editor - CodeMirror lifecycle, Compartments, bidirectional sync, CellController
Tree operations: ct-outliner - Path-based operations, diff-based rendering, keyboard commands, MentionController

Each component reveals deeper patterns - study them not just for API but for architectural principles.

lit-component