@veevarts/design-system 2.0.0-alpha.58 → 2.0.0-alpha.59

package/README.md

@@ -288,6 +288,21 @@ module.exports = {
 | `colors` | Color tokens (brand, semantic, neutral, palettes) |
 | `typography` | Typography tokens (fontFamily, fontSize, fontWeight, lineHeight) |
 | `spacing` | Spacing tokens |
+| `assistantSurfaceTokens` | The assistant (`ai-*`) palette as hex, `{ light, dark }` |
+| `assistantSurfacePlugin` | Writes the `--ai-*` custom properties. Already inside `veevartPreset`; add it yourself only if you extend `tokens.tailwindTheme` without the preset |
+| `assistantSurfaceTailwindColors` | The `ai` colour map the preset uses: each colour reads its `--ai-*` property, with the light value as fallback |
+
+#### Assistant color (`ai-*`), light and dark
+
+The preset adds an `ai` colour family for assistant surfaces: `ai-accent`, `ai-fill`, `ai-border`, `ai-user-bubble`, `ai-assistant-bubble` and `ai-focus` (`text-ai-accent`, `bg-ai-fill/50`, `ring-ai-focus`, …).
+
+- Each color reads a custom property (`--ai-accent`, …) that the preset's plugin writes. **The `.dark` class is the switch:** dark values under `.dark`, light values on `:root`, `.light` and `[data-theme="light"]`, the selectors every HeroUI 2.x in the peer range writes its own variables under, so the palette flips together with HeroUI's semantic colors (a test compiles both and compares). `.dark` on a subtree darkens that subtree only.
+- `data-theme="dark"` is **not** a switch. On HeroUI 2.8 (what the DS builds and tests with) neither palette turns dark under it, because 2.8 writes its dark variables under `.dark` only. On 2.7, the floor of the peer range, HeroUI turns dark there and `ai-*` doesn't. Use `.dark` either way.
+- As with HeroUI's own `.dark` theme, Tailwind emits the dark values only when your content uses the `dark` class, which any app that toggles it does.
+- The properties hold channels (`29 78 216`), and only `assistantSurfacePlugin` (inside the preset) writes them, into the Tailwind build's base layer. In plain CSS outside that build, or loaded before it, give the light value as the fallback: `rgb(var(--ai-accent, 29 78 216))`. Without one, the colour resolves to nothing.
+- Without the plugin, the `ai-*` utilities fall back to their light values (the fallback is inside each utility's `var()`); a plain-CSS `var()` with no fallback does not.
+- **The hue is a placeholder** (the info blue scale for accent, fill, border and focus) until Design picks the assistant color. The two turns are HeroUI neutrals (`content1` for the assistant, `content2` for the person), so only the assistant wears the hue. Values and contrast tests live in `src/tokens/assistant-surface.ts`; see Storybook → Foundations → Assistant color.
+- Storybook has a **Theme** toolbar (light / dark); dark wraps the story in `.dark`, the way apps scope it.
 
 ---