# Web Component Foundations

Use this reference for every HUMAIN Web Component artifact.

## Runtime

- Use browser-native custom elements with `hf-*` tag names.
- Load package CSS once through the host application.
- Load only the custom-element modules needed by the artifact.
- Do not import React, ReactDOM, Babel, or JSX-only APIs in static HTML.
- Treat module paths as host-owned. Forge-style prototypes may use vendored paths such as `/vendored/humain-wc/hf-button.js`; package consumers may use `@humain/ui/wc/hf-button.js`.

## Tokens

Use semantic tokens and CSS variables:

```css
.page-shell {
  color: var(--foreground);
  background: var(--background);
  padding: var(--spacing-10) var(--spacing-6);
}
```

Do not use raw hex colors, `dark:` Tailwind modifiers, one-off shadows, or arbitrary spacing when a token exists.

## Spacing

- Use `gap` for internal rhythm.
- Use `var(--spacing-*)` for generated CSS.
- Cards and app panels should look intentionally padded in the first viewport.
- Raw `hf-card` needs an explicit content wrapper for body padding. Use [composition.md](composition.md).

## Accessibility

- Prefer component labels and supported `aria-*` attributes from the manifest.
- Use visible text labels for form fields.
- Preserve keyboard-operable native semantics through HUMAIN controls.
- Do not hide essential labels behind placeholders.

## Unsupported APIs

Web Components do not automatically expose every React compound slot or callback prop. If a React API is missing in the WC manifest, do not invent it. Use the documented WC-safe pattern or say the capability is React-only.