My preferred appearance is fairly ordinary: consistent, simple, and predictable. A new settings form should look and behave as though it belongs to the same application. Reviewing it should mostly involve its content, state, and business actions.

That led to a specific boundary in Pith UI: small components with fixed presentation and bounded semantic options. The application assembles those components and connects its own state and callbacks. The extraction shipped in Pith UI 0.6.3 and Pith Desk rc.28 is a useful case study because several earlier attempts got this boundary wrong.

A component library did not preserve the product

I initially asked a coding agent to rebuild the frontend using React and shadcn components. The result covered the main features, but the palette and logo changed, and previously fixed behavior resurfaced. I eventually rolled back that rewrite.

A later attempt exposed a different failure. The library offered smaller parts, and the application still had its callbacks, but the assembled screen lost its centered conversation column, action grouping, compact navigation, and some icons. Individual components looked correct in the showroom while the application layout was broken. The conversation that led to this extraction records both problems.

These were failures in how I specified and accepted the migration. Choosing a component framework had left many application decisions open. Reducing component size had also removed structure that the application still needed.

An established UI contains more specification than a feature list reveals. Its source records which controls share a row, where an error appears, which action remains available during a request, and what happens when an old response arrives after the user switches targets. Those decisions need an explicit home during extraction.

Restrict presentation and keep composition useful

The public component API should describe the choices an application needs to make.

For example, this application-local helper uses the 0.6.3 button API:

import {createButtonPart} from 'pith-ui';

export function saveAction(saveDraft: () => Promise<void>) {
  const button = createButtonPart({
    label: 'Save',
    variant: 'primary',
    onAction: saveDraft,
  });

  return {
    part: button,
    setUnavailable(unavailable: boolean) {
      button.update({
        label: 'Save',
        variant: 'primary',
        disabled: unavailable,
      });
    },
  };
}

The returned part can enter a documented parent slot, which then owns its lifetime. The caller has no className, style, padding, font, or animation argument. Local asynchronous pending behavior belongs to the button implementation; the application supplies authoritative availability.

The same restriction must apply to composition. A slot that accepts arbitrary HTML or a native node gives the caller another route to invent its own interface. Pith UI uses opaque part handles and checks that children are genuine library-created parts. Ownership rules reject reusing a part in two parents and retire removed children. These handles do not require an extra DOM wrapper around every existing element. The ownership implementation keeps native nodes private.

This is an API constraint. A host page still controls the browser’s CSS cascade, so the consuming project also needs checks against style overrides and generated-node access. Type declarations guide normal use, runtime validation catches unsupported options, and consumer checks enforce the agreed boundary.

Prove that the parts can express the existing interface

My first small-parts migration assumed that a stack and a toolbar were sufficient layout vocabulary. They were insufficient for the existing screen. The missing capabilities included a centered reading column, separate action groups, and compact rows.

Removing the old templates before proving their replacements made the application the place where those omissions became visible. The safer order starts with the old implementation.

For each region, I needed to read its template, the relevant CSS cascade, its state updates, and the actual Desk caller together. The frozen contract uses Pith UI 0.2.2 and Desk rc.27 as its baselines. It covers nested dialogs, menus, previews, loading surfaces, and shared behavior as well as the initial workspace.

The old source determines the required structure. Screenshots help find omissions and confirm the result, but they cannot tell me which conversation owns a download or whether a failed save should retain a draft.

I then assembled the old regions internally using only the proposed public parts. Whenever an assembly needed a layout capability that the parts could not express, that was a concrete library gap. It required a bounded capability with a defined purpose. Adding arbitrary CSS to Desk would have hidden the gap and weakened the interface I was trying to establish.

The resulting assembly descriptions include the part tree, construction code, state projection, callbacks, and disposal rules. They are executable documentation. In the 0.6.3 package, those sources were bundled for the consumer to adopt locally, while the export map exposed only the parts entry and its stylesheet. There was no public whole-application or scene entry.

That distinction kept the library responsible for component behavior and the application responsible for assembling its product.

State propagation is part of the assembly

A resource editor exposed one of the easiest details to miss.

The old editor’s Save button participated in a shared availability updater. That updater selected controls by internal markers and applied global, conversation, workspace, or active-target availability. Reading only the editor constructor would miss part of its behavior. The dependency lived outside the component being extracted.

The replacement therefore needed more than an initial disabled value. The application had to retain the open editor’s target and project later availability changes into its state. Its local coordinator does that explicitly; the editor assembly applies the additional Save restriction while retaining the established editing and Delete rules.

This matters because availability has several owners. A button may have a local request pending while the host sends a new snapshot. That snapshot must not accidentally re-enable the action. Conversely, a broad rule that disables every control during host activity can change behavior that was intentionally available.

Target changes introduce another boundary. A request started for one resource must not update or close the editor that replaced it. Ordinary state updates should preserve current input; changing the target may require an explicit reset or a new owned instance. Disposal needs to invalidate late callbacks as well as remove visible elements.

For extraction work, I now trace these paths before adding more tests. Existing correct assertions remain the baseline. A focused regression is useful when it captures an actual omitted state transition. A growing test count cannot compensate for an assembly that no longer forwards the old state.

Give the agent and reviewer the same catalog

The showroom is part of the public contract. If it displays internal implementation fragments alongside supported components, a coding agent or developer can reasonably choose something that the application is not allowed to use.

For this extraction, the public showroom was reduced to formal parts, their specifications, legal states, and interactions. Large application assemblies remained in internal validation and assembly documentation.

flowchart TD
    PARTS[Reviewed component implementations] --> CATALOG["Public catalog<br/>and typed API"]
    CATALOG --> AI["AI selects parts<br/>and assembles"]
    CATALOG --> HUMAN["Human reviews states<br/>and interactions"]
    AI --> APP["Application composition<br/>and business wiring"]
    HUMAN --> APP

The package’s short AI guide explains how to choose parts, compose ownership, update state, and release the tree. Its API reference supplies the detailed types. Assembly recipes show how those rules reconstruct a real region.

These need to agree. A convincing screenshot with an example that does not compile is a poor guide for an agent. A compiling example that depends on an unexported helper is also unusable by a real consumer. The package verification compiled the recipes and documentation examples from an independently installed tarball, using the package’s actual public surface.

A missing capability now has a visible route: identify the required native behavior or layout, add the smallest useful library capability, review its legal states, and publish it. Application code can then consume that reviewed version.

Review the decisions at their owning layer

The useful review boundary follows the kind of change.

When a part changes, I review its visual and interaction contract in the library: typography, spacing, icons, focus, keyboard behavior, pending and error states, and lifecycle. A change there can affect many screens, so its supported variants need inspection together.

When an application composition changes, the review centers on a smaller set of questions:

• Does the part tree preserve the required grouping, order, and slots?
• Do labels, action purposes, and error locations communicate the right meaning?
• Does each callback retain the correct target and revision?
• Are updates, resets, replacement openings, and destruction connected correctly?
• Does the application stay within the public parts API?

Visual inspection still matters. The intended benefit is that a composition change introduces fewer independent visual decisions. I can follow the arrangement and business wiring without also accepting a new set of local font sizes and CSS exceptions.

This gives AI a more specific task as well. It can select approved parts, supply content and state, connect callbacks, and compose a documented tree. A request for a different spacing rule becomes a library change that can be reviewed where that rule is owned.

What the migration established

The coverage map connects 36 old regions to assembly sources and behavior checks. The published 0.6.3 package included 32 compiling assembly sources and 33 compiling documentation examples.

After verifying the published package, Desk installed that exact npm version and adopted the assemblies. The migration commit preserved the existing business controller bodies, host boundary, configuration, conversations, palette, and logo. It introduced no copied legacy HTML/CSS or application style overrides.

Behavior checks ran in Chromium and WebKit. Across 56 comparison scenarios, the captured geometry and style values matched the baseline. Forty-nine screenshots were pixel-identical; the remaining differences were small Chromium antialiasing variations. That establishes the result of this migration. It leaves long-term maintenance savings to be judged through subsequent changes.

The approach has costs. Missing variants require library work. Too many narrowly named parts can make the catalog hard to navigate. Application-local recipes can also accumulate duplication, and a helper that merely forwards arguments may add little value. I would keep checking whether each boundary captures a repeated rule or an important behavior.

For a product with an established visual language, I prefer making those rules explicit. The library gives both the coding agent and the reviewer a finite vocabulary. The application code then shows how that vocabulary is used to express the product’s state and actions.