first commit

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

@@ -0,0 +1,64 @@
+# `<LED>`
+
+<!-- begin:auto-docs -->
+_(no submodules)_
+<!-- end:auto-docs -->
+
+## Purpose
+
+`<LED>` is the output indicator control. It accepts a numeric value in
+the standard `BoundControlProps` domain and renders it as a coloured dot
+whose brightness is driven either by a boolean threshold (`mode="boolean"`)
+or a continuous mapping (`mode="continuous"`). The component is read-only:
+it does not invoke `onChange` because indicators are downstream consumers
+of bindings, not upstream sources.
+
+The visual rendering pulls from the skin's CSS custom properties
+(`--cs-led-on-color`, `--cs-led-off-color`) and uses `color-mix()` to
+interpolate between them in continuous mode. This keeps brightness purely
+a CSS computation — no per-frame inline-style churn — so the LED can be
+driven from an animation frame loop without re-rendering React.
+
+## Features
+
+- Boolean and continuous brightness modes.
+- Skin-driven colour via CSS custom properties.
+- Accessible `role="status"` with `aria-live="polite"`.
+- Default aria-label includes on/off state and percentage.
+- Pure `ledBrightness` helper for unit testing the value clamp.
+
+## Usage: Basic
+
+```tsx
+<LED value={1} min={0} max={1} onChange={() => undefined} label="Power" />
+```
+
+## Usage: Advanced
+
+```tsx
+<LED
+    value={signalLevel}
+    min={0}
+    max={1}
+    onChange={() => undefined}
+    mode="continuous"
+    size={24}
+    ariaLabel="Signal-present indicator"
+    className="signal-led"
+/>
+```
+
+## API Reference
+
+- `<LED>` props: `BoundControlProps & { mode?: "boolean" | "continuous", size?, className?, style? }`.
+- `ledBrightness(value, min, max, mode)` — pure helper returning the
+  normalised brightness in `[0, 1]`.
+
+## Implementation Notes
+
+`color-mix(in srgb, ...)` is widely supported in modern browsers but
+absent from Safari Technology Preview prior to v16; consumers targeting
+legacy engines should override the inline `background` via a skin or
+custom `style`. The component intentionally does NOT animate brightness
+transitions — animation is left to the consumer's stylesheet because
+audio-meter LEDs typically need ballistic curves driven outside React.