@pie-players/pie-tool-annotation-toolbar 0.3.61 → 0.3.62

package/README.md

@@ -43,6 +43,30 @@ This component doesn't take props - it automatically shows when text is selected
 
 Text-to-Speech (Read Aloud) button does not emit an event - it directly uses the TTS service to read the selected text.
 
+## Theming
+
+The toolbar takes its surface and text from the canonical `--pie-background` and `--pie-text` tokens. The marks it draws, and its own outline, read dedicated tokens instead:
+
+| Token                                  | Default                        | Purpose                                            |
+| -------------------------------------- | ------------------------------ | -------------------------------------------------- |
+| `--pie-tool-annotation-toolbar-border` | `light-dark(#5c5c5c, #949494)` | Outline separating the toolbar from content        |
+| `--pie-annotation-underline`           | `#4221d5`                      | Underline mark on a light page                     |
+| `--pie-annotation-underline-dark`      | `#9c89ec`                      | Underline mark on a dark page                      |
+
+The underline tokens are applied by `HighlightCoordinator` in `@pie-players/pie-assessment-toolkit`, which owns the `::highlight()` rules. They exist as a pair because one value cannot serve both surfaces — `#4221d5` is 2.41:1 on black and `#9c89ec` is 2.85:1 on white — and as two separate tokens so overriding one never silently moves the other. Neither consults `--pie-primary`: a theme accent is chosen against one background and is illegible on the other.
+
+Which of the pair applies is decided by `[data-theme]`, which reports what the **page** declares — not which color scheme is active. A host that declares itself light while running a dark scheme would otherwise pin the light value over a dark background, so the accessibility palettes hand both states their own accent (below).
+
+The outline does **not** read `--pie-border`. Under the DaisyUI bridge that token resolves to `--color-base-300`, a surface tint rather than a boundary colour, which renders the outline at 1.16:1 on the light base and 1.12:1 on the dark one — well short of the 3:1 that WCAG 2.2 SC 1.4.11 requires of a component boundary.
+
+The defaults above are measured instead. A boundary on a light surface has to be dark and one on a dark surface has to be light, so the arms are the dark grey first and the light grey second. Both are measured against the surfaces the toolbar is actually drawn on rather than against pure white and pure black — real theme bases are off-white and off-black, and a grey chosen at the edge of passing against an extreme drops under threshold on everything else. Across DaisyUI's 21 light and 14 dark themes plus the PIE light and dark palettes, every light surface needs a grey no lighter than `#828282` and every dark surface one no darker than `#878787`; the ranges are disjoint, so one value cannot serve both. `#5c5c5c` holds 5.22:1 as its worst case on the light surfaces and `#949494` holds 3.56:1 on the dark ones. `light-dark()` follows the declared `color-scheme`, so every dark DaisyUI theme picks the dark value rather than only the theme literally named `dark`.
+
+Palettes that choose their own colours deliberately set all three tokens in `@pie-players/pie-theme`: the ten `data-color-scheme` accessibility schemes point the outline at their own `--pie-border` and both underline states at their own `--pie-primary`, and the PIE dark theme pins the outline to `#949494`. Several of those palettes use mid-tone backgrounds that no single grey clears 3:1 on, which is why they override rather than inherit.
+
+Those per-scheme values arrive by either delivery route: `<pie-theme scheme="…">` applies them as inline styles with no CSS import needed, and importing `@pie-players/pie-theme/color-schemes.css` plus setting `data-color-scheme` yourself produces the same result. Prefer the element — a host that hand-maintains its own copy of the scheme blocks stops receiving tokens added later.
+
+Hosts may override any of the three, but must keep 3:1 against both the toolbar surface and the content behind it.
+
 ## Architecture
 
 The annotation toolbar integrates with PIE's shared highlight infrastructure: