@pretable/ui 0.4.0 → 0.5.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
@@ -1,6 +1,6 @@
1
1
  # @pretable/ui
2
2
 
3
- CSS theme + a small JS helper for [pretable](https://pretable.dev/). Pair with [`@pretable/react`](../react) for the full surface, or use the JS helper standalone in non-React adapters.
3
+ CSS theme + a small JS helper for [pretable](https://pretable.ai/). Pair with [`@pretable/react`](../react) for the full surface, or use the JS helper standalone in non-React adapters.
4
4
 
5
5
  ## Install
6
6
 
@@ -11,43 +11,57 @@ npm install @pretable/ui
11
11
 
12
12
  ## Minimal usage
13
13
 
14
- Import the CSS once at the root of your app:
14
+ Two imports at the root of your app — a theme, then `grid.css`:
15
15
 
16
16
  ```ts
17
+ import "@pretable/ui/themes/pretable.css";
17
18
  import "@pretable/ui/grid.css";
18
19
  ```
19
20
 
20
- Optionally layer a theme:
21
+ `pretable.css` is the house theme and the default. Both imports are load-bearing: `grid.css` imports nothing and declares no token values of its own, so without a theme underneath it its colors, type, and spacing all resolve against variables no one has set.
21
22
 
22
- ```ts
23
- import "@pretable/ui/themes/excel.css";
24
- import "@pretable/ui/grid.css";
23
+ Tailwind v4 users import the same two files, plus the opt-in bridge:
24
+
25
+ ```css
26
+ @import "tailwindcss";
27
+ @import "@pretable/ui/themes/pretable.css";
28
+ @import "@pretable/ui/grid.css";
29
+ @import "@pretable/ui/tailwind.css";
25
30
  ```
26
31
 
27
- For tailwind users, swap `grid.css` for `tailwind.css` (both work; `tailwind.css` reads from your tailwind tokens).
32
+ `tailwind.css` is additive — it adds utility shortcuts for styling _your_ UI in the grid's palette. It is not a substitute for `grid.css`.
28
33
 
29
34
  ## CSS API (v1 contract)
30
35
 
31
- `@pretable/ui` ships five CSS entrypoints. Their selectors and CSS variables form the v1 styling contract — pretable's React components (`<Pretable>`, `<PretableSurface>`, `<LabeledGridSurface>`) emit the data attributes these stylesheets target.
36
+ `@pretable/ui` ships six CSS entrypoints. The `[data-pretable-*]` selectors `grid.css` targets and the 50 `--pretable-*` tokens the theme files define are the v1 styling contract — pretable's React components (`<Pretable>`, `<PretableSurface>`, `<LabeledGridSurface>`) emit the data attributes these stylesheets target.
32
37
 
33
38
  ### Entrypoints
34
39
 
35
- - `@pretable/ui/grid.css` — the default styles. Imports `tokens.css`. Use this in a vanilla CSS or Sass setup.
36
- - `@pretable/ui/tailwind.css` — same grid styles authored against tailwind tokens. Use this in a tailwind app.
37
- - `@pretable/ui/tokens.css` — the CSS-variable definitions only. Imported by `grid.css` automatically; use directly only when you want tokens without grid styles.
38
- - `@pretable/ui/themes/excel.css` — Excel-flavored theme. Layer on top of `grid.css`.
39
- - `@pretable/ui/themes/material.css` — Material-flavored theme. Layer on top of `grid.css`.
40
+ Nothing here imports anything else; you compose them yourself, in this order.
41
+
42
+ - `@pretable/ui/grid.css` — the grid rules, and the only file in the package that styles a grid element. Its selectors target the `[data-pretable-*]` attributes; every themeable value reads a `--pretable-*` token, so it needs a theme underneath it. Ships inside the `pretable` cascade layer.
43
+ - `@pretable/ui/themes/pretable.css` — the house theme, and the default. Defines all 50 tokens at `:root`, with dark-mode and per-density-tier overrides.
44
+ - `@pretable/ui/themes/excel.css` — Excel compatibility skin. Same 50 tokens; light only, with density tiers.
45
+ - `@pretable/ui/themes/material.css` — Material compatibility skin. Same 50 tokens, with dark mode and density tiers.
46
+ - `@pretable/ui/tailwind.css` — opt-in Tailwind v4 bridge: an `@theme inline` block that re-exports 17 of the 50 tokens as `--color-pt-*` / `--font-pt-*` utility shortcuts (`bg-pt-bg-grid`, `text-pt-accent`, `font-pt-mono`). It contains **no grid rules** — importing it instead of `grid.css` leaves the grid unstyled.
47
+ - `@pretable/ui/tokens.css` — **not part of the grid contract.** A legacy `--pt-*` palette that predates this package's `--pretable-*` namespace; it defines no `--pretable-*` token and styles no grid element. Only pretable's own website consumes it. Consumer apps want a theme file, not this.
48
+
49
+ Pick exactly one theme file. The theme files are unlayered and all declare at `:root`, so loading two resolves by source order token by token — and the two do not necessarily ship the same blocks (Excel has no dark mode), so the result is not "the second theme" either.
40
50
 
41
51
  ### Density CSS variables
42
52
 
43
- The two density-related variables `getDensityHeights()` reads:
53
+ The two variables `getDensityHeights()` reads:
54
+
55
+ | Variable | Purpose | JS fallback |
56
+ | -------------------------- | ------------------ | ----------- |
57
+ | `--pretable-row-height` | Body row height. | `32px` |
58
+ | `--pretable-header-height` | Header row height. | `36px` |
59
+
60
+ The fallbacks are hard-coded in [`src/density.ts`](./src/density.ts) and apply only when a variable is unset or is not a `<number>px` value — they are not a theme's values. Every shipped theme sets both at every density tier: `pretable` is `48px` / `52px` at standard, Excel `20px` / `24px` at its compact default.
44
61
 
45
- | Variable | Default (in `tokens.css`) | Purpose |
46
- | -------------------------- | ------------------------- | ------------------ |
47
- | `--pretable-row-height` | `32px` | Body row height. |
48
- | `--pretable-header-height` | `36px` | Header row height. |
62
+ `@pretable/react` reads a third token in JS, `--pretable-group-panel-height`, and only while the drag-to-group panel is enabled. `getDensityHeights()` does not cover it; the remaining 47 tokens never enter JavaScript at all.
49
63
 
50
- The full token set lives in [`src/tokens.css`](./src/tokens.css). Override any token at `:root` or on a scoped element to change the look.
64
+ The full 50-token set is defined by the theme files in [`src/themes/`](./src/themes/); the [token reference](https://pretable.ai/docs/theming/token-reference) lists every name with its per-theme value. Override any token at `:root` or on a scoped element to change the look.
51
65
 
52
66
  ### Data-attribute hooks
53
67
 
@@ -65,9 +79,9 @@ layer order or specificity without `!important`. In a Tailwind v4 app declare:
65
79
  @layer theme, base, pretable, components, utilities;
66
80
  ```
67
81
 
68
- Token files (`tokens.css`, `themes/*.css`) are intentionally **unlayered** —
69
- override tokens after importing the theme. See the website's "Cascade &
70
- overrides" theming page for the full contract.
82
+ Theme files (`themes/*.css`) are intentionally **unlayered** — override tokens
83
+ after importing the theme. See the website's "Cascade & overrides" theming page
84
+ for the full contract.
71
85
 
72
86
  ## JS API
73
87
 
package/dist/grid.css CHANGED
@@ -10,7 +10,7 @@
10
10
  * @layer theme, base, pretable, components, utilities;
11
11
  *
12
12
  * Consumer recipe:
13
- * @import "@pretable/ui/themes/excel.css";
13
+ * @import "@pretable/ui/themes/pretable.css";
14
14
  * @import "@pretable/ui/grid.css";
15
15
  */
16
16
 
@@ -233,12 +233,16 @@
233
233
  line. The spread is <= -blur/2 on purpose — any less negative and the blur
234
234
  bleeds above and below each cell and paints a dark band at every row
235
235
  boundary inside the pinned region.
236
- Known interaction: the focus ring below is also a `box-shadow`, and
237
- box-shadow is not additive, so a FOCUSED pinned cell shows the ring and
238
- loses its seam for as long as it holds focus. Accepted rather than worked
239
- around — the ring is the stronger signal in that moment, it is one cell,
240
- and both shipped themes opt out of the seam entirely. Revisit if the house
241
- theme makes it visible. */
236
+ This box-shadow slot is the seam's alone. It used to be contested: the
237
+ cell focus ring was an inset box-shadow too, and box-shadow is not
238
+ additive across rules, so a FOCUSED pinned cell showed the ring and lost
239
+ its seam for as long as it held focus. That was accepted while both
240
+ shipped themes set --pretable-seam-color: transparent and the loss was
241
+ unobservable — a precondition that failed the moment the house theme drew
242
+ a visible seam. The focus ring is now an `outline` (see the Focus rule
243
+ below), which composes with this shadow, so the seam survives focus.
244
+ Anything added here must keep that property: a second box-shadow on this
245
+ element silently wins the whole slot. */
242
246
  :where([data-pretable-cell][data-pretable-pinned="left"]) {
243
247
  background: var(--pretable-bg-pinned);
244
248
  box-shadow: 8px 0 8px -8px var(--pretable-seam-color);
@@ -286,10 +290,10 @@
286
290
  that precede this one (base, zebra, group row, pinned) each set
287
291
  `background-color`, and hover must tint that rather than replace it.
288
292
  Replacing it is not cosmetic — `--pretable-bg-hover` is a translucent
289
- state layer in both themes (Excel sets it to `transparent` outright), and
290
- pinned cells are `position: sticky; z-index: 1` with unpinned cells
291
- scrolling underneath. A hovered pinned cell that loses its opaque fill
292
- lets the scrolled-under column print straight through it. */
293
+ state layer in all three shipped themes (Excel sets it to `transparent`
294
+ outright), and pinned cells are `position: sticky; z-index: 1` with
295
+ unpinned cells scrolling underneath. A hovered pinned cell that loses its
296
+ opaque fill lets the scrolled-under column print straight through it. */
293
297
  background-image: linear-gradient(
294
298
  var(--pretable-bg-hover),
295
299
  var(--pretable-bg-hover)
@@ -306,23 +310,48 @@
306
310
  color: var(--pretable-text-selected);
307
311
  }
308
312
 
309
- /* Focus */
310
- :where([data-pretable-cell][data-pretable-focused="true"]) {
313
+ /* Focus.
314
+ One rule, two arms, drawn with `outline` — never `box-shadow`.
315
+
316
+ The ARIA arm is here for the same reason the selection fill below targets
317
+ `aria-selected`: a custom renderer that emits the ARIA grid pattern
318
+ without pretable's data attributes still gets the ring. @pretable/react
319
+ puts both attributes on the same element, so this used to be TWO rules —
320
+ this outline plus an inset box-shadow keyed on [role="gridcell"] — and
321
+ every focused cell in every shipped app drew both rings at once.
322
+
323
+ `outline`, because box-shadow is not additive across rules: the pinned
324
+ seam above occupies that slot, and a ring declared there erases the
325
+ frozen-column seam for as long as the cell holds focus. Outline composes
326
+ with it. It also matches every other focus affordance in this stylesheet
327
+ (twisty, group chip, menu item), so a consumer restyles one thing. */
328
+ :where(
329
+ [data-pretable-cell][data-pretable-focused="true"],
330
+ [role="gridcell"][data-pretable-focused="true"]
331
+ ) {
311
332
  outline: 2px solid var(--pretable-focus-ring);
312
333
  outline-offset: -2px;
313
334
  }
314
335
 
315
336
  /**
316
- * Theme-agnostic cell-range selection visuals (Phase 3).
317
- * Targets the ARIA role + aria-selected attribute exposed by @pretable/react,
318
- * so consumers using only @pretable/ui's tokens.css (no theme file) still get
319
- * a usable visual.
337
+ * Cell-range selection fill (Phase 3).
338
+ * Targets the ARIA role + aria-selected attribute rather than
339
+ * [data-pretable-selected]: @pretable/react sets both from the same
340
+ * condition, so a custom renderer that emits the ARIA grid pattern picks up
341
+ * the fill without also adopting the data attribute.
342
+ *
343
+ * It does NOT make the grid usable without a theme file — this comment used
344
+ * to say so. tokens.css defines no --pretable-* token at all, so with it
345
+ * alone --pretable-selection-bg is unset and the gradient below is invalid.
346
+ * A theme file is required, here as everywhere in this stylesheet.
320
347
  */
321
348
  :where([role="gridcell"][aria-selected="true"]) {
322
349
  /* A background-image layer for the same reason as hover above:
323
- `--pretable-selection-bg` is a color-mix at 8% in both themes, so the
324
- `background` shorthand would replace a pinned cell's opaque fill with a
325
- 92%-transparent one and let the scrolled-under column show through.
350
+ `--pretable-selection-bg` is translucent in all three shipped themes —
351
+ an 8% color-mix in Excel and Material, a literal rgba at 10% light /
352
+ 16% dark in pretable — so the `background` shorthand would replace a
353
+ pinned cell's opaque fill with a mostly-transparent one and let the
354
+ scrolled-under column show through.
326
355
  This rule follows hover in source order, so on a cell that is both
327
356
  hovered and selected the selection tint wins the background-image slot
328
357
  outright — the same precedence the shorthand gave it, unchanged. */
@@ -332,10 +361,6 @@
332
361
  );
333
362
  }
334
363
 
335
- :where([role="gridcell"][data-pretable-focused="true"]) {
336
- box-shadow: inset 0 0 0 2px var(--pretable-focus-ring);
337
- }
338
-
339
364
  /* Column alignment.
340
365
  `justify-content`, not `text-align`: cells are flex containers and an
341
366
  unwrapped value is an anonymous flex item, which text-align cannot move.
@@ -373,6 +398,196 @@
373
398
  font-variant-numeric: tabular-nums lining-nums;
374
399
  }
375
400
 
401
+ /* ------------------------------------------------------------------------
402
+ Cell presentations. Small, composable readings of a value that a consumer
403
+ opts into from a `render`, not automatic behaviour — the grid never infers
404
+ that a number is a delta. Each one is styled here and emitted by a
405
+ component in @pretable/react, so the markup and the skin cannot drift.
406
+ ---------------------------------------------------------------------- */
407
+
408
+ /* Signed numeric change. Direction is carried by a MARKER as well as by
409
+ colour, so it survives greyscale, colour-blindness and a printed page —
410
+ colour alone is not an accessible signal, and a red/green pair is the
411
+ worst possible choice for the most common deficiency.
412
+
413
+ The marker is a real element (PretableDelta emits one from the icon set),
414
+ deliberately NOT a Unicode glyph in a `content:` declaration here. `▲` and
415
+ `▼` are two of the exact characters SP2b removed from this grid: text
416
+ glyphs re-render in whatever font the active theme picked, so their
417
+ weight, size and baseline shift between Excel's Aptos Narrow, Material's
418
+ Roboto and this theme's own stack — and on most UI stacks they are not in
419
+ the font at all and fall through to a platform symbol font, which changes
420
+ the metrics again per OS. A ::before would have saved one node per cell,
421
+ but virtualization already bounds that to the visible rows.
422
+
423
+ `align-items: baseline`, not `center`: a delta is frequently a two-line
424
+ stack (the figure over its percentage), and baseline alignment pins the
425
+ marker to the FIRST line. Centring floats it against the whole stack. */
426
+ :where([data-pretable-delta]) {
427
+ display: inline-flex;
428
+ align-items: baseline;
429
+ gap: 4px;
430
+ font-variant-numeric: tabular-nums lining-nums;
431
+ }
432
+
433
+ /* The marker rides the TEXT size, not --pretable-icon-size: it sits inline
434
+ beside digits rather than inside a control, and a control-sized glyph next
435
+ to a cell's text reads as a bullet. `1em`, measured against a screenshot —
436
+ the first pass at 0.85em put a 1.1px stroke beside a 14px figure's ~1.4px
437
+ stems and the caret read as an accent mark rather than an arrow. The BOX is
438
+ 1em; the caret inside it occupies 4.5 of 16 units, so what a reader sees is
439
+ a mark about a third of the text height, not a 14px blob.
440
+ Declared after the shared icon rule so it wins on source order —
441
+ everything here is :where()-flattened to (0,0,0). */
442
+ :where([data-pretable-delta] [data-pretable-icon]) {
443
+ width: 1em;
444
+ height: 1em;
445
+ }
446
+
447
+ /* The colour rides the direction. These sit on the presentation element, not
448
+ the cell, so a selected cell's --pretable-text-selected does not erase
449
+ them: the signal must not disappear because a range happens to cover it. */
450
+ :where([data-pretable-delta="up"]) {
451
+ color: var(--pretable-positive);
452
+ }
453
+
454
+ :where([data-pretable-delta="down"]) {
455
+ color: var(--pretable-negative);
456
+ }
457
+
458
+ :where([data-pretable-delta="flat"]) {
459
+ color: var(--pretable-text-dim);
460
+ }
461
+
462
+ /* Status: a dot AND a label, both carrying the state for the same reason the
463
+ delta has a marker — a reader who cannot separate the hues still has the
464
+ word. The dot IS generated content here, unlike the delta's marker: it is
465
+ a border-radius box with no text in it, so it has no font to re-render in
466
+ and none of the objection above applies. 7px because a 6px dot goes soft
467
+ against a hairline-ruled surface and an 8px one starts competing with the
468
+ label for weight. */
469
+ :where([data-pretable-status]) {
470
+ display: inline-flex;
471
+ align-items: center;
472
+ gap: 6px;
473
+ color: var(--pretable-text-cell);
474
+ }
475
+
476
+ /* `:where(sel)::before`, never `:where(sel::before)` — a pseudo-element is
477
+ not a valid argument to :where(), and a browser drops the entire rule. */
478
+ :where([data-pretable-status])::before {
479
+ content: "";
480
+ flex: none;
481
+ width: 7px;
482
+ height: 7px;
483
+ border-radius: 50%;
484
+ background: var(--pretable-text-dim);
485
+ }
486
+
487
+ :where([data-pretable-status="positive"])::before {
488
+ background: var(--pretable-positive);
489
+ }
490
+
491
+ :where([data-pretable-status="negative"])::before {
492
+ background: var(--pretable-negative);
493
+ }
494
+
495
+ :where([data-pretable-status="warning"])::before {
496
+ background: var(--pretable-warning);
497
+ }
498
+
499
+ :where([data-pretable-status="info"])::before {
500
+ background: var(--pretable-info);
501
+ }
502
+
503
+ /* Badge: a hairline chip, never a tinted one. Tinting the fill with the
504
+ text's own hue costs ~0.6 of contrast and drops every tone below AA — the
505
+ worst is 4.13 at a 10% tint over white, and it gets worse deeper. The
506
+ reference designs got this right: a white chip with a hairline and
507
+ restrained text. Tone rides on the TEXT, and what that measures depends on
508
+ the ground the chip inherits, since contrast is a property of the pair:
509
+ 4.83–5.17 on a white grid surface (pretable, Excel), 4.71–5.04 on
510
+ Material's #fcfcfc. Every shipped theme clears 4.5. */
511
+ :where([data-pretable-badge]) {
512
+ display: inline-flex;
513
+ align-items: center;
514
+ gap: 5px;
515
+ padding: 1px 8px;
516
+ border: 1px solid var(--pretable-rule-strong);
517
+ border-radius: 999px;
518
+ background: var(--pretable-bg-grid);
519
+ color: var(--pretable-text-cell);
520
+ font-size: 0.85em;
521
+ white-space: nowrap;
522
+ }
523
+
524
+ :where([data-pretable-badge][data-pretable-tone="positive"]) {
525
+ color: var(--pretable-positive);
526
+ }
527
+
528
+ :where([data-pretable-badge][data-pretable-tone="negative"]) {
529
+ color: var(--pretable-negative);
530
+ }
531
+
532
+ :where([data-pretable-badge][data-pretable-tone="warning"]) {
533
+ color: var(--pretable-warning);
534
+ }
535
+
536
+ :where([data-pretable-badge][data-pretable-tone="info"]) {
537
+ color: var(--pretable-info);
538
+ }
539
+
540
+ /* A toned badge also carries a dot, so tone survives peripheral vision.
541
+ Dropping the tinted fill fixed the contrast but cost something real: with
542
+ every chip on the same neutral hairline and white ground, the only tone
543
+ channel left was ~12px of label ink, so scanning a column for "which rows
544
+ are flagged" became reading rather than spotting. The dot restores that as
545
+ shape AND colour without touching the label's contrast at all — it is a
546
+ graphical object, which owes 3:1, and the ramp's floor across the shipped
547
+ grounds is 4.71 (Material's #fcfcfc; 4.83 on the two white ones).
548
+ `currentColor` so it tracks the tone with no extra rule per tone, and the
549
+ base rule's `gap` already reserved the space.
550
+ Note the pseudo-element sits OUTSIDE :where() — `:where(x::before)` is
551
+ invalid and the engine silently keeps it as an empty :where() that matches
552
+ nothing, so it would look present in cssRules and never paint. */
553
+ :where([data-pretable-badge][data-pretable-tone])::before {
554
+ content: "";
555
+ flex: none;
556
+ width: 6px;
557
+ height: 6px;
558
+ border-radius: 50%;
559
+ background: currentColor;
560
+ }
561
+
562
+ /* Entity: a primary line with a quieter secondary beneath it — the identity
563
+ column pattern. The secondary takes --pretable-text-dim rather than an
564
+ opacity, because every hand-rolled version of this reached for opacity and
565
+ every one of them failed AA. */
566
+ :where([data-pretable-entity]) {
567
+ display: flex;
568
+ flex-direction: column;
569
+ justify-content: center;
570
+ min-width: 0;
571
+ line-height: 1.3;
572
+ }
573
+
574
+ :where([data-pretable-entity-primary]) {
575
+ font-weight: 600;
576
+ min-width: 0;
577
+ overflow: hidden;
578
+ text-overflow: ellipsis;
579
+ white-space: nowrap;
580
+ }
581
+
582
+ :where([data-pretable-entity-secondary]) {
583
+ color: var(--pretable-text-dim);
584
+ font-size: 0.85em;
585
+ min-width: 0;
586
+ overflow: hidden;
587
+ text-overflow: ellipsis;
588
+ white-space: nowrap;
589
+ }
590
+
376
591
  /* Row-selection checkbox column (Phase 4) */
377
592
  :where(
378
593
  [data-pretable-cell][data-pretable-row-select-cell="true"],
package/dist/tailwind.css CHANGED
@@ -5,7 +5,7 @@
5
5
  *
6
6
  * Consumer recipe (Tailwind v4):
7
7
  * @import "tailwindcss";
8
- * @import "@pretable/ui/themes/material.css";
8
+ * @import "@pretable/ui/themes/pretable.css";
9
9
  * @import "@pretable/ui/grid.css";
10
10
  * @import "@pretable/ui/tailwind.css";
11
11
  */
@@ -49,6 +49,24 @@
49
49
  /* Accent */
50
50
  --pretable-accent: #107c41; /* Excel brand green */
51
51
 
52
+ /* Semantic ramp — meaning, not decoration: a signed delta's direction, a
53
+ status dot's state. NOT copied from the reference designs. Their own hues
54
+ fail AA as text on a grid surface — their green #16a34a is 3.30:1 on this
55
+ theme's #ffffff grid ground and their amber #d97706 is 3.19:1, both under
56
+ the 4.5 floor. White is the most forgiving ground a dark hue gets, so a
57
+ tinted surface only makes it worse (3.21 and 3.11 on Material's #fcfcfc).
58
+ They read fine in the screenshots because they sit inside
59
+ chips and bold glyphs, not as 14px text. Re-derived at similar saturation
60
+ but darker, and verified against this theme's #ffffff grid surface:
61
+ positive 5.02:1 negative 4.83:1 warning 4.92:1 info 5.17:1
62
+ Held within 4.83–5.17 of each other on purpose, so no one colour reads
63
+ heavier than its neighbours down the same column. Excel is light-only, so
64
+ it takes the light set unmodified. */
65
+ --pretable-positive: #15803d;
66
+ --pretable-negative: #dc2626;
67
+ --pretable-warning: #a16207;
68
+ --pretable-info: #2563eb;
69
+
52
70
  /* Grid controls — derived from this theme's tokens so they recolor coherently */
53
71
  --pretable-selection-bg: color-mix(
54
72
  in srgb,
@@ -1,8 +1,15 @@
1
1
  /**
2
- * Material 3 — baseline scheme (seed #6750A4).
2
+ * Material 3 — baseline blue scheme (primary #0061a4), neutral surfaces.
3
+ *
4
+ * A compatibility skin: it exists to disappear into an application that already
5
+ * speaks Material, not to be the product's own voice. pretable.css is that.
6
+ *
7
+ * The seed is the M3 baseline blue rather than the purple #6750A4 this file
8
+ * once carried, and the surfaces are the untinted neutral steps (N99 for the
9
+ * grid, N96 one step up for chrome) rather than primary-tinted surface roles.
3
10
  * Light at :root; dark at [data-theme="dark"]. Default density: standard.
4
- * Surface tier: light grid uses `surface`; dark grid uses `surface-container-low`
5
- * (raw `surface` reads as a void in dark mode per M3 guidance).
11
+ * Dark grid uses `surface-container-low` (raw `surface` reads as a void in dark
12
+ * mode per M3 guidance).
6
13
  */
7
14
 
8
15
  :root {
@@ -56,6 +63,26 @@
56
63
  /* Accent */
57
64
  --pretable-accent: #0061a4; /* primary — M3 baseline blue */
58
65
 
66
+ /* Semantic ramp — meaning, not decoration: a signed delta's direction, a
67
+ status dot's state. NOT copied from the reference designs. Their own hues
68
+ fail AA as text on a grid surface — their green #16a34a is 3.21:1 on this
69
+ theme's #fcfcfc grid ground and their amber #d97706 is 3.11:1, both under
70
+ the 4.5 floor, and neither is rescued by a whiter ground (3.30 and 3.19 on
71
+ pure white, which is the best a dark hue ever gets). They read fine in the
72
+ screenshots because they sit inside chips and bold glyphs, not as 14px
73
+ text. Re-derived at similar saturation but darker. Contrast is a property
74
+ of the PAIR, so these are measured against this theme's own #fcfcfc grid
75
+ surface and not against the white the other two themes ship:
76
+ positive 4.89:1 negative 4.71:1 warning 4.80:1 info 5.04:1
77
+ Held within 4.71–5.04 of each other on purpose, so no one colour reads
78
+ heavier than its neighbours down the same column. The same four literals
79
+ measure 5.02 / 4.83 / 4.92 / 5.17 on white — the spread travels with the
80
+ ground, the ordering does not. */
81
+ --pretable-positive: #15803d;
82
+ --pretable-negative: #dc2626;
83
+ --pretable-warning: #a16207;
84
+ --pretable-info: #2563eb;
85
+
59
86
  /* Grid controls — derived from this theme's tokens so they recolor coherently */
60
87
  --pretable-selection-bg: color-mix(
61
88
  in srgb,
@@ -158,6 +185,26 @@
158
185
 
159
186
  --pretable-accent: #9ecaff;
160
187
 
188
+ /* The checked checkbox is the one control whose two halves are set in
189
+ different blocks: the :root block aliases its fill to --pretable-accent
190
+ (which this block moves to a pale #9ecaff) but writes its mark as a
191
+ literal #fff, which is inherited here unchanged. White on #9ecaff is
192
+ 1.70:1 — under the 3:1 WCAG 1.4.11 floor for a graphical object, and the
193
+ mark is the entire signal that a row is selected. M3's on-primary (dark)
194
+ is the correct partner for primary (dark), and reads 7.65:1. */
195
+ --pretable-checkbox-checked-fg: #003258; /* on-primary (dark) */
196
+
197
+ /* Semantic ramp, dark. The light set inverts badly here: #15803d is 3.40:1
198
+ on this theme's #1c1c1c grid ground, under the 4.5 floor. These are the
199
+ light hues lightened until they clear that floor from the other side,
200
+ measured against #1c1c1c — on pretable's darker #141418 the same four
201
+ literals read 10.54 / 9.68 / 11.01 / 8.94 —
202
+ positive 9.78:1 negative 8.98:1 warning 10.21:1 info 8.29:1 */
203
+ --pretable-positive: #4ade80;
204
+ --pretable-negative: #fca5a5;
205
+ --pretable-warning: #fbbf24;
206
+ --pretable-info: #93b4ff;
207
+
161
208
  /* A 12%-black shadow on a #1c1c1c surface is invisible, so every dark-mode
162
209
  popover read as flat until this override existed. Deeper and more opaque
163
210
  rather than lighter: M3 keeps shadows black in dark mode and gets the
@@ -3,8 +3,9 @@
3
3
  *
4
4
  * Excel and Material are imitations; this one is the product's own voice. Its
5
5
  * identity is craft, not hue: hairline rules, horizontal-only separation,
6
- * a quiet header, honest elevation, and a single functional interaction colour
7
- * that is a system convention rather than a brand.
6
+ * a quiet header, honest elevation, and colour admitted in two meanings only —
7
+ * interaction/selection and state — with every blue a system convention rather
8
+ * than a brand. See "The interaction hue" below for how the blues divide.
8
9
  *
9
10
  * THREE SURFACE TIERS. The reference designs get away with near-invisible
10
11
  * hairlines because their cards sit on a grey page. pretable never paints the
@@ -107,15 +108,62 @@
107
108
  --pretable-focus-ring: #2554cf;
108
109
  --pretable-text-error: #c0271c;
109
110
 
110
- /* --- The one hue ----------------------------------------------------- */
111
- /* Exactly one colour in the theme, and it means "interactive / selected" —
112
- never a surface, never chrome text. A system blue rather than a brand
113
- blue, so the grid reads as part of the host app instead of competing with
114
- it. 7.11:1 on white: it is used as TEXT (the filter menu's Clear button,
115
- the calendar nav) and as the fill behind a white checkmark, and one ratio
116
- covers both directions. */
111
+ /* --- The interaction hue ---------------------------------------------- */
112
+ /* The theme admits colour in two meanings only: "interactive / selected",
113
+ which is blue, and STATE, which is the semantic ramp below. This is the
114
+ QUIET blue of the interaction set — chrome text and icons, and nothing
115
+ else. The other two values live elsewhere in this block, because they do
116
+ different jobs and cannot be one literal:
117
+ #2554cf the loud one — focus ring, checked checkbox, resize
118
+ handle on hover, drop indicator, and at 10% the range
119
+ tint in --pretable-selection-bg.
120
+ --pretable-bg-selected (#dfe6fb) + --pretable-text-selected (#131826)
121
+ a pale blue SURFACE and its ink, behind a selected
122
+ enum option or calendar day. Opaque and a value of its
123
+ own rather than a tint of either blue above: it
124
+ replaces the surface under text instead of
125
+ compositing over it, which is why selection-bg — the
126
+ one that does composite — is the translucent member.
127
+ All of them are system blues rather than brand blues, so the grid reads
128
+ as part of the host app instead of competing with it.
129
+ grid.css reads this token in exactly three places and all three are
130
+ `color:` — the active filter funnel, the filter menu's Clear button, the
131
+ calendar's month arrows on hover. It never fills a surface, which is what
132
+ "and nothing else" above is guarding: the checked checkbox is painted by
133
+ --pretable-checkbox-checked-bg (#2554cf), and the white mark on it is
134
+ 6.47:1 there without this token taking part. 7.11:1 as text on the
135
+ #ffffff popover the Clear button and the calendar sit on; 6.24:1 as the
136
+ funnel icon on the #eff0f4 header rail, where the floor is the 3:1
137
+ non-text one. */
117
138
  --pretable-accent: #3f5a7a;
118
139
 
140
+ /* --- The semantic ramp ------------------------------------------------ */
141
+ /* The blues above mean "interactive / selected". These four mean STATE, and
142
+ they are the only other colours the theme admits: a signed delta's
143
+ direction, a status dot's state. They are meaning, never decoration — the
144
+ ramp only ever inks text or fills the status dot, and never a surface tier
145
+ or any piece of chrome. The dot's size is grid.css's to state and
146
+ deliberately not repeated here: a measurement duplicated across packages is
147
+ a measurement that drifts.
148
+
149
+ NOT copied from the reference designs. Their own hues fail AA as text on a
150
+ grid surface: their green #16a34a is 3.30:1 on this theme's #ffffff paper
151
+ and their amber #d97706 is 3.19:1, both under the 4.5 floor. Those are the
152
+ BEST numbers either hue can post — white is the most forgiving ground a
153
+ dark colour ever gets, so any tinted surface is worse (3.21 and 3.11 on
154
+ Material's #fcfcfc). They read fine in the screenshots because they sit
155
+ inside chips and bold glyphs, not as 14px text. Re-derived at similar
156
+ saturation but darker. Contrast is a property of the pair, so these are
157
+ measured against this theme's own paper and hold only there:
158
+ positive 5.02:1 negative 4.83:1 warning 4.92:1 info 5.17:1
159
+ Held within 4.83–5.17 of each other on purpose: spread them and one state
160
+ starts reading as more urgent than another purely because its hue is
161
+ darker, which is a lie the data did not tell. */
162
+ --pretable-positive: #15803d;
163
+ --pretable-negative: #dc2626;
164
+ --pretable-warning: #a16207;
165
+ --pretable-info: #2563eb;
166
+
119
167
  /* --- Grid controls --------------------------------------------------- */
120
168
  /* Written as literals rather than var() aliases so the dark block can move
121
169
  them independently — aliasing checkbox-border to rule-strong is what lets
@@ -251,6 +299,18 @@
251
299
  /* The one hue */
252
300
  --pretable-accent: #8fb2d9;
253
301
 
302
+ /* The semantic ramp, dark. The light set does not survive the inversion —
303
+ #15803d is 3.66:1 on this theme's #141418 paper, under the 4.5 floor it
304
+ cleared comfortably on white. These are the same hues lightened until
305
+ they clear that floor from the other side, and again held close together.
306
+ Measured against #141418, this theme's own dark paper — the same four
307
+ literals read 9.78 / 8.98 / 10.21 / 8.29 on Material's lighter #1c1c1c:
308
+ positive 10.54:1 negative 9.68:1 warning 11.01:1 info 8.94:1 */
309
+ --pretable-positive: #4ade80;
310
+ --pretable-negative: #fca5a5;
311
+ --pretable-warning: #fbbf24;
312
+ --pretable-info: #93b4ff;
313
+
254
314
  /* Grid controls */
255
315
  --pretable-selection-bg: rgba(138, 176, 255, 0.16);
256
316
  --pretable-checkbox-bg: #141418;
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@pretable/ui",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "description": "CSS themes, tokens, and grid styles for Pretable.",
5
5
  "license": "MIT",
6
6
  "repository": {