first commit

docs/ui/react/react-control-surface/src/controls/image/image.md

@@ -0,0 +1,70 @@
+# `<Image>`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`<Image>` is the decorative image control. Like `<TextLabel>`, it appears
+in the closed `ControlKind` enumeration so a surface can declaratively
+include brand marks, device backplates, and other static imagery without
+the runtime needing to special-case the rendering path. The component
+implements `BoundControlProps` for uniform runtime treatment but never
+invokes `onChange`.
+
+The accessible name is resolved through a falls-through chain
+(`ariaLabel` -> `alt` -> `label` -> `""`), which keeps the API
+identical to `<TextLabel>` and ensures that an image embedded as part of
+a control surface is never missing its accessible name unless the
+surface author has explicitly opted into it.
+
+## Features
+
+- Single `<img>` element with `data-kind="image"`.
+- Accessible-name fallback: `ariaLabel` -> `alt` -> `label` -> `""`.
+- Optional explicit `width` / `height` for SSR-stable layout.
+- `aria-disabled` reflection of the `disabled` prop.
+- Inline `className` / `style` overrides.
+
+## Usage: Basic
+
+```tsx
+<Image
+    value={0}
+    onChange={() => undefined}
+    min={0}
+    max={1}
+    src="/assets/logo.png"
+    alt="Synth logo"
+/>
+```
+
+## Usage: Advanced
+
+```tsx
+<Image
+    value={0}
+    onChange={() => undefined}
+    min={0}
+    max={1}
+    src="/assets/backplate.png"
+    label="Device backplate"
+    width={1024}
+    height={256}
+    className="backplate"
+    style={{ filter: "brightness(0.9)" }}
+/>
+```
+
+## API Reference
+
+- `<Image>` props: `BoundControlProps & { src: string, alt?, width?, height?, className?, style? }`.
+
+## Implementation Notes
+
+The component does not lazy-load or preload — that is the consumer's
+responsibility to wire via wrapping components or browser-native
+attributes (e.g. `loading="lazy"`). Skin-driven styling happens through
+CSS variables and the `className` slot; the component itself stays close
+to the bare DOM `<img>` semantics.