diff --git a/.changeset/mosaic-icon-stylex.md b/.changeset/mosaic-icon-stylex.md
new file mode 100644
index 00000000000..a845151cc84
--- /dev/null
+++ b/.changeset/mosaic-icon-stylex.md
@@ -0,0 +1,2 @@
+---
+---
diff --git a/packages/swingset/src/stories/icon.mdx b/packages/swingset/src/stories/icon.mdx
index 6352bd262d7..9d7ab6bb236 100644
--- a/packages/swingset/src/stories/icon.mdx
+++ b/packages/swingset/src/stories/icon.mdx
@@ -2,7 +2,9 @@ import * as IconStories from './icon.stories';
# Icon
-Icon renders a named glyph from Mosaic's icon set. It sizes through the `size` variant and inherits color from `currentColor`. Any glyph can be swapped per name through `appearance.icons` on `MosaicProvider`. Mosaic's styling applies to an override just like the built-in glyph — so swapped icons stay visually consistent — and the override also receives `data-cl-slot="icon"` for targeting.
+Icon renders a named glyph from Mosaic's icon set. It sizes through the `size` variant and inherits color from `currentColor`. Any glyph can be swapped per name through `appearance.icons` on `MosaicProvider`. Mosaic's styling applies to an override just like the built-in glyph — so swapped icons stay visually consistent — and the override also carries the `.cl-icon` class and `data-size` attribute for targeting.
+
+Set `placement` when the icon sits beside text inside a container. It adds no styling of its own; it reflects `data-icon="inline-start"` or `data-icon="inline-end"` so the container can react — a `Button`, for example, tightens its padding on the side the icon sits with `:has([data-icon='inline-end'])`. The values are the CSS logical directions, so they follow the writing mode rather than naming a physical edge. Leave it unset for a standalone icon.
## Playground
@@ -15,7 +17,10 @@ Icon renders a named glyph from Mosaic's icon set. It sizes through the `size` v
## Usage
@@ -46,7 +51,7 @@ Icon renders a named glyph from Mosaic's icon set. It sizes through the `size` v
### Overriding a glyph
-Pass `appearance.icons` to `MosaicProvider` to replace a glyph by name. The override is a function receiving the resolved props — Mosaic's sizing/color `className` and `data-cl-slot` — which you spread onto your own element. Because Mosaic's styling applies to the override too, the replacement only supplies its `viewBox` and paths.
+Pass `appearance.icons` to `MosaicProvider` to replace a glyph by name. The override is a plain element; Mosaic clones it with the resolved sizing `className` and `data-size`, keeping any class the element already had. The replacement only supplies its `viewBox` and paths.
(knob values) and cast to IconProps.
@@ -78,8 +86,8 @@ export function Override() {
return (
- render({ui});
-
-/** Concatenates every inserted Emotion `