# MCP-B Web Components

`@mcp-b/web-components` is the Lit renderer of the MCP-B design system. It shares
design tokens and deliberately shared control contracts with
`@mcp-b/react-components`, the default renderer for product UI. Lit also supports
framework-independent maps, editors, visualizations, and IFC surfaces through
the sibling domain packages.

## Use a component

Install with `vp add @mcp-b/web-components`, then import the theme and the elements
you use:

```ts
import "@mcp-b/web-components/themes/sigvelo.css";
import "@mcp-b/web-components/components/text-field/text-field.js";
import "@mcp-b/web-components/components/button/button.js";
```

```html
<form>
  <sigvelo-text-field name="title" label="Title" required></sigvelo-text-field>
  <sigvelo-button type="submit">Save</sigvelo-button>
</form>
```

Individual entrypoints register their dependencies and default English copy.
The package root registers the entire core library; prefer individual imports
when you only need a few controls. Additional translations are opt-in:

```ts
import "@mcp-b/web-components/translations/es.js";
document.documentElement.lang = "es";
```

## One token layer

The theme entrypoint loads `@mcp-b/design-tokens` through `@mcp-b/wc-support`.
It does not require React CSS or maintain a second palette.

- No `data-theme` attribute means follow the operating system. Use
  `data-theme="light"` or `data-theme="dark"` for an explicit root or subtree override.
- Set `data-preset` on the document root for an accent palette and `data-style`
  for a design-language preset. Removing the attribute restores the default.
- Shared controls consume `--sigvelo-control-*` for their size, padding, icons,
  and line height, and `--sigvelo-focus-*` for keyboard focus.
- Add a shared semantic token in `packages/design-tokens` only when an existing
  token cannot express the need. Component-specific hooks remain local.

React owns the contracts explicitly declared in
[`design-system.catalog.json`](./design-system.catalog.json). Other name
overlaps are review inventory, not a promise of API parity.

## Compose with native boundaries

Use named slots for caller-owned content and documented `::part()` hooks for
internal styling. Inherited custom properties carry the shared theme through
shadow roots; document selectors do not style arbitrary internals. See
[Lit shadow DOM composition](https://lit.dev/docs/components/shadow-dom/) and
[Lit styling](https://lit.dev/docs/components/styles/).

Keep native buttons, links, inputs, and form association in the owning control.
An ancestor fieldset's disabled state must not overwrite a control's own
`disabled` attribute. Components must remain usable after disconnecting and
reconnecting; initialize per-connection resources and release them on disconnect.
See [Lit lifecycle](https://lit.dev/docs/components/lifecycle/).

Custom tags and events use the `sigvelo-` prefix. Dispatch user-facing events
through the shared event classes so bubbling, composition, and typed payloads
remain consistent. Avoid copying the stateful localization or runtime registries
into domain packages.

## Package boundaries

| Package                                                        | Owns                                                      |
| -------------------------------------------------------------- | --------------------------------------------------------- |
| `design-tokens`                                                | Shared tokens, themes, and presets                        |
| `wc-support`                                                   | Lit base classes, events, localization, and shared styles |
| `web-components`                                               | Core elements and the shared Lit Storybook                |
| `geo-support`, `geo-leaflet`, `geo-maplibre`, `geo-openlayers` | Shared map contracts and engine-specific renderers        |
| `interactive-components`, `aec-components`, `viz-components`   | Editors, IFC/3D, and charts                               |

Rendering engines stay peer dependencies of the packages that use them. Import
domain elements from their owning package; core controls do not require map or
3D engines. Editors additionally load
`@mcp-b/interactive-components/themes/interactive.css` for their syntax tokens.

## Develop and verify

From the repository root:

```sh
vp install
vp run @mcp-b/web-components#storybook
```

This Storybook includes every Lit package and runs accessibility checks on its
stories. Root unit tests, React stories, and Lit stories are separate suites:

```sh
vp run test:browser:ci
vp check
vp run audit:tokens
vp run audit:css-recipes
vp run audit:modern-web-guidance
vp run catalog:check
vp run validate:packages
```

The browser runner executes all three suites. Domain package test scripts
delegate to the shared Lit Storybook; they do not own standalone unit suites.
`wc-support` also has unit and browser regression tests.