​

Customization

Most UI work should start here, not in patch creation.

The goal is to adapt an existing patch before introducing a new one. Patches are intentionally small and merge into native elements, so many variations can be handled without forking the component model.

Must see the source of patch at the bottom of each patch page to understand the structure then code it still code as html native element.

There are four levels of customization, in increasing order of effort:

  1. Patch props. Each patch exposes a small, stable set of props—typically fewer than five. Lowest friction.
  2. Context attributes. Use dataTone, dataSize, and dataDensity on a container to shift tone, size, or density for an entire subtree without touching individual elements.
  3. Inline override. Native-wins merge strategy: any property set directly on the element overrides the patch value.
  4. Create a variant. Clone a similar patch and edit it. Use this only when you need a reusable custom version.

Typical Example

import { button } from "@domphy/ui"

const action = {
  button: "Save",
  $: [button({ color: "primary" })],
  style: {
    width: "100%",
  },
}

This keeps the patch behavior and design defaults, while still letting the element override specific properties inline.

When To Stop Customizing

Create a new patch only when:

  • the variation is reused often
  • the variation needs its own stable prop API
  • inline overrides would make call sites noisy

If it is still one-off or local to a feature, keep it as a normal element with a patch plus inline overrides.