blip-tokens 2.2.1 → 2.4.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -147,15 +147,82 @@ references resolved to values so it has no dangling aliases. Descriptions,
147
147
  Figma scopes and variable IDs stay attached to each published semantic token.
148
148
  CSS custom properties include each token's Figma usage description as a
149
149
  comment. The legacy outputs remain available alongside them.
150
- The 305-variable count covers variable collections only: 206 Foundation
151
- primitives are internal, and 99 semantic variables are published. Separately,
150
+ The 306-variable count covers variable collections only: 206 Foundation
151
+ primitives are internal, and 100 semantic variables are published. Separately,
152
152
  the Figma file has eight elevation effect styles, published as variables, and
153
153
  28 text styles, published as metadata, without exposing Foundation primitives.
154
154
  There are no per-component color or typography tokens: components use the
155
155
  semantic tokens directly, so their names stay stable across light and dark modes.
156
156
 
157
+ ### Focus indicators
158
+
159
+ `border/ring` (`--uai-border-ring`) is a solid neutral focus color: dark in Light
160
+ mode and light in Dark mode, using the same Foundation aliases as `content/primary`.
161
+ It replaces the previous purple value without renaming the public token.
162
+ Consumers such as UaiButton keep a full-opacity focus outline.
163
+
164
+ For UaiInput, the focused control has two independent layers: a solid 1 px border
165
+ and a 2 px outer halo. Only the halo uses semantic `opacity/focus-ring`
166
+ (`--uai-opacity-focus-ring`, unitless `0.3`);
167
+ never reduce the opacity of the whole input or of every focus indicator.
168
+ The token lives in Dimensions: Figma opacity bindings require percentages, so
169
+ its source value is `30`, explicitly normalized to unitless `0.3` in DTCG,
170
+ CSS, SCSS and JavaScript outputs. Foundation's pre-existing fractional opacity
171
+ primitives remain private and unchanged. Do not invent a local opacity
172
+ value or reuse a pressed overlay for this role.
173
+ The halo is supplementary, not the only focus cue. Keep geometry tokenized,
174
+ avoid layout shifts, and verify focus contrast and forced-colors behavior in
175
+ the consuming component.
176
+
177
+ The halo maps directly to a zero-blur CSS shadow; it does not change the
178
+ control's box size:
179
+
180
+ ```css
181
+ .control[data-focused] {
182
+ border-color: var(--uai-border-ring);
183
+ box-shadow: 0 0 0 var(--uai-border-width-thick)
184
+ color-mix(in srgb, var(--uai-border-ring) calc(var(--uai-opacity-focus-ring) * 100%), transparent);
185
+ }
186
+
187
+ @media (forced-colors: active) {
188
+ .control[data-focused] {
189
+ box-shadow: none;
190
+ outline: var(--uai-border-width-thick) solid CanvasText;
191
+ outline-offset: var(--uai-border-width-default);
192
+ }
193
+ }
194
+ ```
195
+
196
+ The consumer tracks focus, not whether `value` is empty or typing is in progress.
197
+ Keep the normal border width and radius unchanged, and ensure that parent
198
+ containers do not clip the halo.
199
+
157
200
  ### Using the tokens in a component
158
201
 
202
+ #### Dark-mode contrast and action colors
203
+
204
+ The [dark-theme contrast and migration report](docs/dark-theme-contrast.md)
205
+ records the audited foreground/background pairs, changed values and consumer
206
+ impact. Dark text and feedback accents target **4.5:1** on the supported standard
207
+ surfaces; essential control borders and solid focus cues target **3:1**.
208
+ This is color-contrast coverage, not a claim of complete WCAG conformance.
209
+
210
+ - Use `feedback/*` for text/icons on standard or matching subtle surfaces, not
211
+ as a universal filled-button background.
212
+ - Filled positive actions pair `action/positive` with
213
+ `action/positive-foreground`. Filled destructive actions pair
214
+ `action/destructive` with `action/destructive-foreground`. Never assume
215
+ white text: both foregrounds are dark neutrals in Dark mode.
216
+ - `border/default` is decorative. Use `border/input` for an essential control
217
+ boundary and `border/ring` for focus.
218
+ - `fixed/brand` keeps its brand value; pair it with `fixed/dim`, not white.
219
+ Keep `fixed/bright` for supported dark backgrounds such as `fixed/dim` and
220
+ `fixed/blue`.
221
+ - Keep non-color cues for errors, links and selection. Disabled content is
222
+ exempt from contrast requirements; placeholders are not.
223
+ - Light placeholder, success and warning text have existing contrast gaps and
224
+ are outside this Dark correction. Do not infer Light compliance from this audit.
225
+
159
226
  The tokens are an internal contract of the blip-ds design system. Only blip-ds
160
227
  components read them. Micro frontends (MFEs) consume blip-ds components and do
161
228
  not import `blip-tokens` or use `var(--uai-*)`: spacing and layout come from the
@@ -168,8 +235,10 @@ blip-ds loads the tokens once, in its own entry:
168
235
  import 'blip-tokens/css/colors';
169
236
  import 'blip-tokens/css/typography';
170
237
  import 'blip-tokens/css/dimensions';
238
+ import 'blip-tokens/css/layout';
239
+ import 'blip-tokens/css/motion';
171
240
  import 'blip-tokens/css/shadows';
172
- // or, for all four: import 'blip-tokens/css';
241
+ // or, for all: import 'blip-tokens/css';
173
242
  ```
174
243
 
175
244
  Components then read the variables in their own styles. There is nothing to
@@ -209,14 +278,27 @@ The output is split by what the tokens are. Only colors depend on the theme:
209
278
 
210
279
  | Entry | File | Tokens | Declared on |
211
280
  |---|---|---|---|
212
- | `blip-tokens/css` | `build/css/uai.css` | Imports the four files below | — |
213
- | `blip-tokens/css/colors` | `build/css/uai-colors.css` | Surface, content, action, border, feedback, overlay and fixed colors | Every theme root (light and dark) |
281
+ | `blip-tokens/css` | `build/css/uai.css` | Imports the grouped files below | — |
282
+ | `blip-tokens/css/colors` | `build/css/uai-colors.css` | Surface, content, action, border, feedback, overlay, fixed and AI accent colors | Every theme root (light and dark) |
214
283
  | `blip-tokens/css/typography` | `build/css/uai-typography.css` | Font families, sizes and line heights per role, weights, letter spacing | The outermost theme root |
215
- | `blip-tokens/css/dimensions` | `build/css/uai-dimensions.css` | Spacing, sizing, radius, border width | The outermost theme root |
284
+ | `blip-tokens/css/dimensions` | `build/css/uai-dimensions.css` | Spacing, sizing, control heights, radius, border width, opacity | The outermost theme root |
285
+ | `blip-tokens/css/layout` | `build/css/uai-layout.css` | Layout widths, z-index layers | The outermost theme root |
286
+ | `blip-tokens/css/motion` | `build/css/uai-motion.css` | Durations and easing curves | The outermost theme root |
216
287
  | `blip-tokens/css/shadows` | `build/css/uai-shadows.css` | Eight elevation shadows | The outermost theme root |
217
288
 
218
289
  SCSS follows the same split: `blip-tokens/scss/colors-light`,
219
- `scss/colors-dark`, `scss/typography`, `scss/dimensions` and `scss/shadows`.
290
+ `scss/colors-dark`, `scss/typography`, `scss/dimensions`, `scss/layout`,
291
+ `scss/motion` and `scss/shadows`.
292
+
293
+ Breakpoints (`$uai-breakpoint-xs|sm|md|lg`) are published only to SCSS
294
+ (`scss/layout`), JavaScript and JSON, never as CSS custom properties, because
295
+ media queries cannot read `var()`:
296
+
297
+ ```scss
298
+ @use 'blip-tokens/scss/layout' as layout;
299
+
300
+ @media (max-width: layout.$uai-breakpoint-lg) { … }
301
+ ```
220
302
 
221
303
  The tokens are never declared at `:root`, `html` or `body`, so loading the CSS
222
304
  does not change anything outside the theme roots. The `--uai-` prefix also keeps
@@ -250,9 +332,9 @@ keeps the v1 `theme--*` classes and `--color-*` variables for the v1 components,
250
332
  and also renders `data-uai-theme` for the new ones. The v1 classes and variables
251
333
  do not feed the new tokens.
252
334
 
253
- Each theme root also sets the CSS `color-scheme`. Typography, dimensions and
254
- shadows do not depend on the theme, so they are declared only on the outermost
255
- root and inherited by nested regions; that is why an override on a container
335
+ Each theme root also sets the CSS `color-scheme`. Typography, dimensions, layout,
336
+ motion and shadows do not depend on the theme, so they are declared only on the
337
+ outermost root and inherited by nested regions; that is why an override on a container
256
338
  reaches components inside a nested region. The selectors use `:where()`, so a
257
339
  rule that overrides a token on the theme root itself always wins.
258
340
 
@@ -308,13 +390,18 @@ from the semantic variables:
308
390
  ```css
309
391
  .card-title {
310
392
  font-family: var(--uai-font-family-sans);
311
- font-size: var(--uai-title-font-size);
312
- line-height: var(--uai-title-line-height);
393
+ font-size: var(--uai-title-md-font-size);
394
+ line-height: var(--uai-title-md-line-height);
313
395
  font-weight: var(--uai-font-weight-semibold);
314
396
  letter-spacing: var(--uai-letter-spacing-normal);
315
397
  }
316
398
  ```
317
399
 
400
+ Typography size roles are `title/lg` (18/24), `title/md` (16/24),
401
+ `title/sm` (14/20), `body/lg` (16/24), and `body/sm` (12/20), in pixels.
402
+ The existing `title/font-size` and `title/line-height` tokens remain
403
+ compatibility aliases to `title/md`.
404
+
318
405
  The 28 Figma text styles are published as metadata only. Each entry in
319
406
  `textStyles` names the variables that make it up, so a component can match its
320
407
  Figma text style exactly:
@@ -379,18 +466,23 @@ resolver. They hold static values, so prefer the CSS variables for themed styles
379
466
  | Usage | Source/normalized DTCG | Web output |
380
467
  |---|---|---|
381
468
  | Font size and line height | px | rem, at 16 px per rem |
382
- | Spacing, sizing, radius | px | rem, at 16 px per rem |
469
+ | Spacing, sizing, control height, radius, breakpoint and layout width | px | rem, at 16 px per rem |
383
470
  | Border width | px | px |
384
471
  | Shadow geometry | px | px |
385
472
  | Letter spacing / font tracking | px | px |
386
- | Opacity and font weight | number | number |
473
+ | Opacity and font weight | number | unitless number |
474
+ | Layer / z-index | integer | unitless integer |
475
+ | Duration | seconds | milliseconds (`ms`) |
476
+ | Easing curve | Figma cubic Bezier | CSS `cubic-bezier(...)` |
387
477
 
388
478
  The current Figma tracking primitives explicitly document pixels; do not infer
389
479
  `em` or percent from their numeric values. A future change requires an explicit
390
480
  policy and tests. Conversion is applied by semantic usage after resolving raw
391
481
  aliases: a shared Foundation dimension can become `rem` when used as spacing,
392
- sizing, radius or typography, while remaining `px` for border width. The build
393
- does not change the application's root font size.
482
+ sizing, control height, radius, breakpoint, width or typography, while remaining
483
+ `px` for border width. Figma opacity percentages are normalized to 0–1, while
484
+ layers remain non-negative integers. Figma durations in seconds are emitted as milliseconds. The build does not
485
+ change the application's root font size.
394
486
 
395
487
  Raw Figma floats are preserved in the snapshot. Normalized numeric/color values
396
488
  are rounded to six decimal places to remove serialization noise (for example,
@@ -738,10 +830,12 @@ next to the legacy files, which keep their original names and paths:
738
830
  ```
739
831
  build/
740
832
  ├── css/
741
- │ ├── uai.css # Entry: imports the four uai-* files below
833
+ │ ├── uai.css # Entry: imports all grouped uai-* files below
742
834
  │ ├── uai-colors.css # Color variables: one block per theme root
743
835
  │ ├── uai-typography.css # Typography variables, outermost theme root
744
- │ ├── uai-dimensions.css # Spacing, sizing, radius and border width, outermost theme root
836
+ │ ├── uai-dimensions.css # Spacing, sizing, control heights, radius, border width and opacity
837
+ │ ├── uai-layout.css # Widths and z-index layers (breakpoints are SCSS/JS only)
838
+ │ ├── uai-motion.css # Durations and easing curves
745
839
  │ ├── uai-shadows.css # Elevation variables, outermost theme root
746
840
  │ └── classes.css # Legacy color and background classes
747
841
  ├── scss/
@@ -749,6 +843,8 @@ build/
749
843
  │ ├── uai-colors-dark.scss # $uai-* color variables, dark values
750
844
  │ ├── uai-typography.scss
751
845
  │ ├── uai-dimensions.scss
846
+ │ ├── uai-layout.scss
847
+ │ ├── uai-motion.scss
752
848
  │ ├── uai-shadows.scss
753
849
  │ └── theme-*.scss, variables.scss, extended-color.scss # Legacy palette and themes
754
850
  ├── json/
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "schemaVersion": 1,
3
- "version": "2.2.1",
3
+ "version": "2.4.0",
4
4
  "baseUrl": "https://cdn.blip.ai/blip-tokens/",
5
5
  "assets": {
6
6
  "asset-icon-123-outline": {
@@ -1,163 +1,187 @@
1
1
  :where([data-uai-theme="light"]) {
2
- /* Destructive button (delete, remove). Same red as feedback/error. */
2
+ /* Last stop of the AI accent gradient (cyan). Same value in every theme. Use: borders and highlights of AI features: insight cards use start, middle and end; Brain actions use start to middle. Pair: content/primary for text over insight surfaces (overlay/insight). Avoid: body text color, status colors and non-AI features. */
3
+ --uai-accent-ai-end: #00c6d7;
4
+ /* Middle stop of the AI accent gradient (purple). Same value in every theme. Use: borders and highlights of AI features: insight cards use start, middle and end; Brain actions use start to middle. Pair: content/primary for text over insight surfaces (overlay/insight). Avoid: body text color, status colors and non-AI features. */
5
+ --uai-accent-ai-middle: #a855f7;
6
+ /* First stop of the AI accent gradient (blue). Same value in every theme. Use: borders and highlights of AI features: insight cards use start, middle and end; Brain actions use start to middle. Pair: content/primary for text over insight surfaces (overlay/insight). Avoid: body text color, status colors and non-AI features. */
7
+ --uai-accent-ai-start: #0099ff;
8
+ /* Theme-aware destructive action accent. Use: background of filled destructive buttons, and text and border of outline or text destructive actions on standard surfaces. Pair: action/destructive-foreground on filled buttons, never fixed/bright. Avoid: error messages; use feedback/error. */
3
9
  --uai-action-destructive: #cf0022;
4
- /* Text and icons on destructive buttons. */
10
+ /* Theme-aware text and icon color on action/destructive: white in Light, dark neutral in Dark. Avoid: replacing it with fixed/bright. */
5
11
  --uai-action-destructive-foreground: #ffffff;
6
- /* Outline and text button background — default state. */
12
+ /* Theme-aware background of outline and text (ghost) actions, default state. Pair: content/primary for the label. States: action/outline/hover and action/outline/pressed. */
7
13
  --uai-action-outline-default: #ffffff;
8
- /* Outline and text button background — hover state. Also list item hover. */
14
+ /* Theme-aware hover background of outline and text actions. Also the hover background of list and menu items. */
9
15
  --uai-action-outline-hover: #f2f3f3;
10
- /* Outline and text button background — pressed state. Also selected list item. */
16
+ /* Theme-aware pressed background of outline and text actions. Also the background of the selected list or menu item. */
11
17
  --uai-action-outline-pressed: #e4e6e7;
12
- /* Primary button background — default state. */
18
+ /* Theme-aware background of filled positive buttons. Pair: action/positive-foreground, never fixed/bright. Avoid: success text and outline or text actions; use feedback/success. */
19
+ --uai-action-positive: #047857;
20
+ /* Theme-aware text and icon color on action/positive: white in Light, dark neutral in Dark. */
21
+ --uai-action-positive-foreground: #ffffff;
22
+ /* Theme-aware background of primary actions, default state: solid uai-button and the checked checkbox fill. Neutral (near-black in Light), not brand blue. Pair: action/primary/foreground. States: action/primary/hover and action/primary/pressed. */
13
23
  --uai-action-primary-default: #242729;
14
- /* Text and icons on primary buttons. */
24
+ /* Theme-aware text and icon color on action/primary backgrounds, including the checkbox check mark. Avoid: fixed/bright or content/inverse on primary actions. */
15
25
  --uai-action-primary-foreground: #ffffff;
16
- /* Primary button background — hover state. */
26
+ /* Theme-aware background of primary actions on hover. Use only as the hover state of action/primary/default. Pair: action/primary/foreground. */
17
27
  --uai-action-primary-hover: #181a1b;
18
- /* Primary button background — pressed state. */
28
+ /* Theme-aware background of primary actions while pressed or active. Use only as the pressed state of action/primary/default. Pair: action/primary/foreground. */
19
29
  --uai-action-primary-pressed: #0a0a0a;
20
- /* Default border. Cards, dividers, separators. */
30
+ /* Theme-aware decorative border. Use: cards, dividers and separators. Avoid: as the only boundary of a form control or as the sole state indicator; use border/input or border/ring. */
21
31
  --uai-border-default: #e4e6e7;
22
- /* Form control border. Inputs, selects, checkboxes, outline buttons. */
32
+ /* Theme-aware essential boundary of form controls. Use: default borders of inputs, selects, checkboxes and radios. Dark mode meets 3:1 on background, paper, contrast, muted and outline pressed surfaces. Avoid: decorative dividers; use border/default. */
23
33
  --uai-border-input: #adb4b8;
24
- /* Focus ring for keyboard navigation. */
25
- --uai-border-ring: #c084fc;
26
- /* Disabled text and icons. */
34
+ /* Theme-aware solid focus indicator: dark in Light, light in Dark. Use: focus border of inputs and focus outline of buttons, checkboxes and radios, always at full opacity. Inputs may add a separate outer halo with opacity/focus-ring. Avoid: reducing the opacity of the whole control. */
35
+ --uai-border-ring: #242729;
36
+ /* Theme-aware color for disabled text, icons and control borders (inputs, checkbox, radio). Avoid: placeholders (use content/placeholder) and readable secondary text, because disabled content is exempt from contrast rules. */
27
37
  --uai-content-disabled: #848e94;
28
- /* Text and icons on inverse or dark surfaces, such as surface/inverse and action/primary. */
38
+ /* Theme-aware text and icon color for inverted surfaces. Use: text and icons on surface/inverse, such as tooltips and snackbars. Avoid: labels on filled actions; use the matching action foreground token. */
29
39
  --uai-content-inverse: #ffffff;
30
- /* Links and interactive navigation text. */
40
+ /* Theme-aware link color. Use: links and interactive navigation text on standard surfaces. Keep an underline or another non-color cue when embedded in body text. Avoid: non-interactive emphasis. */
31
41
  --uai-content-link: #0073e5;
32
- /* Input placeholder and hint text. Not for disabled content. */
42
+ /* Theme-aware placeholder color. Use: placeholder and empty-value hint text inside inputs and selects on standard surfaces. Dark mode meets 4.5:1 on background, paper, contrast, muted and outline pressed surfaces. Avoid: disabled content; use content/disabled. */
33
43
  --uai-content-placeholder: #adb4b8;
34
- /* Primary text and icons. Headings, body text, form labels. */
44
+ /* Theme-aware primary text and icon color. Use: headings, body text, input values and form labels on standard surfaces (background, paper, contrast, muted). Avoid: text on surface/inverse or on filled actions; use content/inverse or the matching action foreground. */
35
45
  --uai-content-primary: #242729;
36
- /* Secondary text and icons. Descriptions, supporting text, text on muted surfaces. */
46
+ /* Theme-aware secondary text and icon color. Use: descriptions, supporting text, input icons, avatar initials and text on surface/muted. Avoid: essential information that must be read at a glance; use content/primary. */
37
47
  --uai-content-secondary: #5f676d;
38
- /* Error. Field errors, failures, destructive confirmations. Components call it "negative". */
48
+ /* Theme-aware error color for text, icons and borders, such as an invalid input and its message, on standard surfaces or on feedback/error-subtle. Keep a message or icon as a non-color cue. Avoid: filled destructive buttons; use action/destructive. */
39
49
  --uai-feedback-error: #cf0022;
40
- /* Error alert background. Pair with feedback/error for the icon. */
50
+ /* Theme-aware background of error alerts, banners and inline status areas. Pair: feedback/error for the icon and content/primary for the text. */
41
51
  --uai-feedback-error-subtle: #fef2f2;
42
- /* Information. Info alerts, status badges and icons. */
52
+ /* Theme-aware information color for text, icons and borders on standard surfaces or on feedback/info-subtle. Avoid: filled button backgrounds. */
43
53
  --uai-feedback-info: #0073e5;
44
- /* Info alert background. Pair with feedback/info for the icon. */
54
+ /* Theme-aware background of information alerts, banners and inline status areas. Pair: feedback/info for the icon and content/primary for the text. */
45
55
  --uai-feedback-info-subtle: #eff6ff;
46
- /* Success. Confirmations, positive validation, completed states. Components call it "positive". */
56
+ /* Theme-aware success color for text, icons and borders, such as a valid input and its message, on standard surfaces or on feedback/success-subtle. Avoid: filled buttons; use action/positive with action/positive-foreground. */
47
57
  --uai-feedback-success: #3da329;
48
- /* Success alert background. Pair with feedback/success for the icon. */
58
+ /* Theme-aware background of success alerts, banners and inline status areas. Pair: feedback/success for the icon and content/primary for the text. */
49
59
  --uai-feedback-success-subtle: #ecfdf5;
50
- /* Warning. States that need attention. For text on light surfaces, check contrast. */
60
+ /* Theme-aware warning color for text, icons and borders on standard surfaces or on feedback/warning-subtle. Check text contrast in Light mode. Avoid: filled button backgrounds. */
51
61
  --uai-feedback-warning: #ff8000;
52
- /* Warning alert background. Pair with feedback/warning for the icon. */
62
+ /* Theme-aware background of warning alerts, banners and inline status areas. Pair: feedback/warning for the icon and content/primary for the text. */
53
63
  --uai-feedback-warning-subtle: #fff7ed;
54
- /* Blip blue that does not change with the theme. Selected states and highlights. */
64
+ /* Fixed Blip blue, the same in every theme. Pair: fixed/bright for text on it. Avoid: as the only selected-state boundary on every surface, and as a replacement for the neutral action/primary. */
55
65
  --uai-fixed-blue: #1e6bf1;
56
- /* Product brand color. Changes per product, not per theme. Banners, highlights. */
66
+ /* Product brand color, invariant across themes. Use: brand marks and illustrations. Pair: fixed/dim for normal text on it, not fixed/bright. Avoid: as the only selected-state boundary on every surface. */
57
67
  --uai-fixed-brand: #0099ff;
58
- /* Light color that does not change with the theme. Text on fixed/brand. */
68
+ /* Fixed white that does not change with the theme. Use: text and icons on fixed/dim or fixed/blue. Avoid: text on fixed/brand or on light feedback colors, where it fails normal-text contrast. */
59
69
  --uai-fixed-bright: #ffffff;
60
- /* Dark color that does not change with the theme. */
70
+ /* Fixed dark neutral that does not change with the theme. Use: text on fixed/brand, and dark areas that must look the same in Light and Dark. Avoid: theme-aware text; use content/primary. */
61
71
  --uai-fixed-dim: #242729;
62
- /* Backdrop behind modals, drawers and dialogs. */
72
+ /* Theme-aware translucent backdrop behind modals, drawers and dialogs. Avoid: hover or pressed feedback; use overlay/hover or overlay/pressed. */
63
73
  --uai-overlay-default: rgba(0, 0, 0, 0.72);
64
- /* Translucent layer for hover on any interactive surface. */
74
+ /* Theme-aware translucent hover layer placed over any interactive surface: black tint in Light, white tint in Dark. Use: menu items, icon buttons and the radio hover halo. Avoid: as a solid background. */
65
75
  --uai-overlay-hover: rgba(0, 0, 0, 0.08);
66
- /* Translucent background for insight panels and floating cards. */
76
+ /* Theme-aware translucent background for insight panels and floating cards over content. Pair: content/primary. */
67
77
  --uai-overlay-insight: rgba(255, 255, 255, 0.9);
68
- /* Translucent layer for pressed state on any interactive surface. */
78
+ /* Theme-aware translucent pressed layer placed over any interactive surface. Use: the pressed state wherever overlay/hover is the hover state. */
69
79
  --uai-overlay-pressed: rgba(0, 0, 0, 0.16);
70
- /* Page background. The base layer behind every screen. */
80
+ /* Theme-aware translucent layer for the selected item in navigation placed over any surface: black tint in Light, white tint in Dark. Use: selected header navigation and side menu items, together with medium font weight. Pair: content/primary. Avoid: selected list or menu options in panels; use action/outline/pressed. */
81
+ --uai-overlay-selected: rgba(0, 0, 0, 0.06);
82
+ /* Theme-aware page background, the base layer behind every screen. Use: app canvas and the area around cards. Pair: content/primary and content/secondary. Avoid: cards, fields and floating panels; use surface/paper. */
71
83
  --uai-surface-background: #f2f3f3;
72
- /* Subtle contrast surface. Secondary panels, alternating sections, hovered or selected rows. */
84
+ /* Theme-aware subtle contrast surface. Use: secondary panels, alternating sections, hovered or selected table rows. Pair: content/primary. Avoid: the page background. */
73
85
  --uai-surface-contrast: #e4e6e7;
74
- /* Inverted surface. Tooltips, snackbars, dark banners in light mode (and the reverse). Use content/inverse on it. */
86
+ /* Theme-aware inverted surface: dark in Light mode, light in Dark mode. Use: tooltips, snackbars and banners that must stand out from the page. Pair: content/inverse for text and icons. Avoid: large areas. */
75
87
  --uai-surface-inverse: #242729;
76
- /* Muted surface. Chips, tags, code blocks, table headers. Use content/secondary on it. */
88
+ /* Theme-aware muted surface. Use: chips, tags, code blocks, table headers, input adornment boxes and the avatar initials background. Pair: content/secondary for text and icons. */
77
89
  --uai-surface-muted: #f2f3f3;
78
- /* Cards, modals, popovers, dropdowns and drawers. Add an elevation style when it floats. */
90
+ /* Theme-aware main container surface. Use: cards, modals, popovers, dropdown panels, drawers, input fields and the app header. Pair: content/* tokens; add an elevation style when it floats. Avoid: the page canvas; use surface/background. */
79
91
  --uai-surface-paper: #ffffff;
80
92
  color-scheme: light;
81
93
  }
82
94
 
83
95
  :where([data-uai-theme="dark"]) {
84
- /* Destructive button (delete, remove). Same red as feedback/error. */
85
- --uai-action-destructive: #cf0022;
86
- /* Text and icons on destructive buttons. */
87
- --uai-action-destructive-foreground: #ffffff;
88
- /* Outline and text button background — default state. */
96
+ /* Last stop of the AI accent gradient (cyan). Same value in every theme. Use: borders and highlights of AI features: insight cards use start, middle and end; Brain actions use start to middle. Pair: content/primary for text over insight surfaces (overlay/insight). Avoid: body text color, status colors and non-AI features. */
97
+ --uai-accent-ai-end: #00c6d7;
98
+ /* Middle stop of the AI accent gradient (purple). Same value in every theme. Use: borders and highlights of AI features: insight cards use start, middle and end; Brain actions use start to middle. Pair: content/primary for text over insight surfaces (overlay/insight). Avoid: body text color, status colors and non-AI features. */
99
+ --uai-accent-ai-middle: #a855f7;
100
+ /* First stop of the AI accent gradient (blue). Same value in every theme. Use: borders and highlights of AI features: insight cards use start, middle and end; Brain actions use start to middle. Pair: content/primary for text over insight surfaces (overlay/insight). Avoid: body text color, status colors and non-AI features. */
101
+ --uai-accent-ai-start: #0099ff;
102
+ /* Theme-aware destructive action accent. Use: background of filled destructive buttons, and text and border of outline or text destructive actions on standard surfaces. Pair: action/destructive-foreground on filled buttons, never fixed/bright. Avoid: error messages; use feedback/error. */
103
+ --uai-action-destructive: #fca5a5;
104
+ /* Theme-aware text and icon color on action/destructive: white in Light, dark neutral in Dark. Avoid: replacing it with fixed/bright. */
105
+ --uai-action-destructive-foreground: #181a1b;
106
+ /* Theme-aware background of outline and text (ghost) actions, default state. Pair: content/primary for the label. States: action/outline/hover and action/outline/pressed. */
89
107
  --uai-action-outline-default: #242729;
90
- /* Outline and text button background — hover state. Also list item hover. */
108
+ /* Theme-aware hover background of outline and text actions. Also the hover background of list and menu items. */
91
109
  --uai-action-outline-hover: #2f3437;
92
- /* Outline and text button background — pressed state. Also selected list item. */
110
+ /* Theme-aware pressed background of outline and text actions. Also the background of the selected list or menu item. */
93
111
  --uai-action-outline-pressed: #3b4144;
94
- /* Primary button background — default state. */
112
+ /* Theme-aware background of filled positive buttons. Pair: action/positive-foreground, never fixed/bright. Avoid: success text and outline or text actions; use feedback/success. */
113
+ --uai-action-positive: #35de90;
114
+ /* Theme-aware text and icon color on action/positive: white in Light, dark neutral in Dark. */
115
+ --uai-action-positive-foreground: #181a1b;
116
+ /* Theme-aware background of primary actions, default state: solid uai-button and the checked checkbox fill. Neutral (near-black in Light), not brand blue. Pair: action/primary/foreground. States: action/primary/hover and action/primary/pressed. */
95
117
  --uai-action-primary-default: #e4e6e7;
96
- /* Text and icons on primary buttons. */
118
+ /* Theme-aware text and icon color on action/primary backgrounds, including the checkbox check mark. Avoid: fixed/bright or content/inverse on primary actions. */
97
119
  --uai-action-primary-foreground: #242729;
98
- /* Primary button background — hover state. */
120
+ /* Theme-aware background of primary actions on hover. Use only as the hover state of action/primary/default. Pair: action/primary/foreground. */
99
121
  --uai-action-primary-hover: #d6d9db;
100
- /* Primary button background — pressed state. */
122
+ /* Theme-aware background of primary actions while pressed or active. Use only as the pressed state of action/primary/default. Pair: action/primary/foreground. */
101
123
  --uai-action-primary-pressed: #c8cccf;
102
- /* Default border. Cards, dividers, separators. */
124
+ /* Theme-aware decorative border. Use: cards, dividers and separators. Avoid: as the only boundary of a form control or as the sole state indicator; use border/input or border/ring. */
103
125
  --uai-border-default: #2f3437;
104
- /* Form control border. Inputs, selects, checkboxes, outline buttons. */
105
- --uai-border-input: #5f676d;
106
- /* Focus ring for keyboard navigation. */
107
- --uai-border-ring: #c084fc;
108
- /* Disabled text and icons. */
126
+ /* Theme-aware essential boundary of form controls. Use: default borders of inputs, selects, checkboxes and radios. Dark mode meets 3:1 on background, paper, contrast, muted and outline pressed surfaces. Avoid: decorative dividers; use border/default. */
127
+ --uai-border-input: #848e94;
128
+ /* Theme-aware solid focus indicator: dark in Light, light in Dark. Use: focus border of inputs and focus outline of buttons, checkboxes and radios, always at full opacity. Inputs may add a separate outer halo with opacity/focus-ring. Avoid: reducing the opacity of the whole control. */
129
+ --uai-border-ring: #ffffff;
130
+ /* Theme-aware color for disabled text, icons and control borders (inputs, checkbox, radio). Avoid: placeholders (use content/placeholder) and readable secondary text, because disabled content is exempt from contrast rules. */
109
131
  --uai-content-disabled: #768188;
110
- /* Text and icons on inverse or dark surfaces, such as surface/inverse and action/primary. */
132
+ /* Theme-aware text and icon color for inverted surfaces. Use: text and icons on surface/inverse, such as tooltips and snackbars. Avoid: labels on filled actions; use the matching action foreground token. */
111
133
  --uai-content-inverse: #181a1b;
112
- /* Links and interactive navigation text. */
113
- --uai-content-link: #0099ff;
114
- /* Input placeholder and hint text. Not for disabled content. */
115
- --uai-content-placeholder: #768188;
116
- /* Primary text and icons. Headings, body text, form labels. */
134
+ /* Theme-aware link color. Use: links and interactive navigation text on standard surfaces. Keep an underline or another non-color cue when embedded in body text. Avoid: non-interactive emphasis. */
135
+ --uai-content-link: #93c5fd;
136
+ /* Theme-aware placeholder color. Use: placeholder and empty-value hint text inside inputs and selects on standard surfaces. Dark mode meets 4.5:1 on background, paper, contrast, muted and outline pressed surfaces. Avoid: disabled content; use content/disabled. */
137
+ --uai-content-placeholder: #adb4b8;
138
+ /* Theme-aware primary text and icon color. Use: headings, body text, input values and form labels on standard surfaces (background, paper, contrast, muted). Avoid: text on surface/inverse or on filled actions; use content/inverse or the matching action foreground. */
117
139
  --uai-content-primary: #ffffff;
118
- /* Secondary text and icons. Descriptions, supporting text, text on muted surfaces. */
140
+ /* Theme-aware secondary text and icon color. Use: descriptions, supporting text, input icons, avatar initials and text on surface/muted. Avoid: essential information that must be read at a glance; use content/primary. */
119
141
  --uai-content-secondary: #adb4b8;
120
- /* Error. Field errors, failures, destructive confirmations. Components call it "negative". */
121
- --uai-feedback-error: #cf0022;
122
- /* Error alert background. Pair with feedback/error for the icon. */
142
+ /* Theme-aware error color for text, icons and borders, such as an invalid input and its message, on standard surfaces or on feedback/error-subtle. Keep a message or icon as a non-color cue. Avoid: filled destructive buttons; use action/destructive. */
143
+ --uai-feedback-error: #fca5a5;
144
+ /* Theme-aware background of error alerts, banners and inline status areas. Pair: feedback/error for the icon and content/primary for the text. */
123
145
  --uai-feedback-error-subtle: #450a0a;
124
- /* Information. Info alerts, status badges and icons. */
125
- --uai-feedback-info: #0073e5;
126
- /* Info alert background. Pair with feedback/info for the icon. */
146
+ /* Theme-aware information color for text, icons and borders on standard surfaces or on feedback/info-subtle. Avoid: filled button backgrounds. */
147
+ --uai-feedback-info: #93c5fd;
148
+ /* Theme-aware background of information alerts, banners and inline status areas. Pair: feedback/info for the icon and content/primary for the text. */
127
149
  --uai-feedback-info-subtle: #072563;
128
- /* Success. Confirmations, positive validation, completed states. Components call it "positive". */
129
- --uai-feedback-success: #3da329;
130
- /* Success alert background. Pair with feedback/success for the icon. */
150
+ /* Theme-aware success color for text, icons and borders, such as a valid input and its message, on standard surfaces or on feedback/success-subtle. Avoid: filled buttons; use action/positive with action/positive-foreground. */
151
+ --uai-feedback-success: #35de90;
152
+ /* Theme-aware background of success alerts, banners and inline status areas. Pair: feedback/success for the icon and content/primary for the text. */
131
153
  --uai-feedback-success-subtle: #022c22;
132
- /* Warning. States that need attention. For text on light surfaces, check contrast. */
133
- --uai-feedback-warning: #ff8000;
134
- /* Warning alert background. Pair with feedback/warning for the icon. */
154
+ /* Theme-aware warning color for text, icons and borders on standard surfaces or on feedback/warning-subtle. Check text contrast in Light mode. Avoid: filled button backgrounds. */
155
+ --uai-feedback-warning: #fb923c;
156
+ /* Theme-aware background of warning alerts, banners and inline status areas. Pair: feedback/warning for the icon and content/primary for the text. */
135
157
  --uai-feedback-warning-subtle: #431407;
136
- /* Blip blue that does not change with the theme. Selected states and highlights. */
158
+ /* Fixed Blip blue, the same in every theme. Pair: fixed/bright for text on it. Avoid: as the only selected-state boundary on every surface, and as a replacement for the neutral action/primary. */
137
159
  --uai-fixed-blue: #1e6bf1;
138
- /* Product brand color. Changes per product, not per theme. Banners, highlights. */
160
+ /* Product brand color, invariant across themes. Use: brand marks and illustrations. Pair: fixed/dim for normal text on it, not fixed/bright. Avoid: as the only selected-state boundary on every surface. */
139
161
  --uai-fixed-brand: #0099ff;
140
- /* Light color that does not change with the theme. Text on fixed/brand. */
162
+ /* Fixed white that does not change with the theme. Use: text and icons on fixed/dim or fixed/blue. Avoid: text on fixed/brand or on light feedback colors, where it fails normal-text contrast. */
141
163
  --uai-fixed-bright: #ffffff;
142
- /* Dark color that does not change with the theme. */
164
+ /* Fixed dark neutral that does not change with the theme. Use: text on fixed/brand, and dark areas that must look the same in Light and Dark. Avoid: theme-aware text; use content/primary. */
143
165
  --uai-fixed-dim: #242729;
144
- /* Backdrop behind modals, drawers and dialogs. */
166
+ /* Theme-aware translucent backdrop behind modals, drawers and dialogs. Avoid: hover or pressed feedback; use overlay/hover or overlay/pressed. */
145
167
  --uai-overlay-default: rgba(0, 0, 0, 0.8);
146
- /* Translucent layer for hover on any interactive surface. */
168
+ /* Theme-aware translucent hover layer placed over any interactive surface: black tint in Light, white tint in Dark. Use: menu items, icon buttons and the radio hover halo. Avoid: as a solid background. */
147
169
  --uai-overlay-hover: rgba(255, 255, 255, 0.08);
148
- /* Translucent background for insight panels and floating cards. */
170
+ /* Theme-aware translucent background for insight panels and floating cards over content. Pair: content/primary. */
149
171
  --uai-overlay-insight: rgba(0, 0, 0, 0.8);
150
- /* Translucent layer for pressed state on any interactive surface. */
172
+ /* Theme-aware translucent pressed layer placed over any interactive surface. Use: the pressed state wherever overlay/hover is the hover state. */
151
173
  --uai-overlay-pressed: rgba(255, 255, 255, 0.16);
152
- /* Page background. The base layer behind every screen. */
174
+ /* Theme-aware translucent layer for the selected item in navigation placed over any surface: black tint in Light, white tint in Dark. Use: selected header navigation and side menu items, together with medium font weight. Pair: content/primary. Avoid: selected list or menu options in panels; use action/outline/pressed. */
175
+ --uai-overlay-selected: rgba(255, 255, 255, 0.06);
176
+ /* Theme-aware page background, the base layer behind every screen. Use: app canvas and the area around cards. Pair: content/primary and content/secondary. Avoid: cards, fields and floating panels; use surface/paper. */
153
177
  --uai-surface-background: #181a1b;
154
- /* Subtle contrast surface. Secondary panels, alternating sections, hovered or selected rows. */
178
+ /* Theme-aware subtle contrast surface. Use: secondary panels, alternating sections, hovered or selected table rows. Pair: content/primary. Avoid: the page background. */
155
179
  --uai-surface-contrast: #2f3437;
156
- /* Inverted surface. Tooltips, snackbars, dark banners in light mode (and the reverse). Use content/inverse on it. */
180
+ /* Theme-aware inverted surface: dark in Light mode, light in Dark mode. Use: tooltips, snackbars and banners that must stand out from the page. Pair: content/inverse for text and icons. Avoid: large areas. */
157
181
  --uai-surface-inverse: #f2f3f3;
158
- /* Muted surface. Chips, tags, code blocks, table headers. Use content/secondary on it. */
182
+ /* Theme-aware muted surface. Use: chips, tags, code blocks, table headers, input adornment boxes and the avatar initials background. Pair: content/secondary for text and icons. */
159
183
  --uai-surface-muted: #2f3437;
160
- /* Cards, modals, popovers, dropdowns and drawers. Add an elevation style when it floats. */
184
+ /* Theme-aware main container surface. Use: cards, modals, popovers, dropdown panels, drawers, input fields and the app header. Pair: content/* tokens; add an elevation style when it floats. Avoid: the page canvas; use surface/background. */
161
185
  --uai-surface-paper: #242729;
162
186
  color-scheme: dark;
163
187
  }