Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

Comments color changed to blue (PRD-8196) (#3845)

shagun-singh-inkeep2c7c10787923
diff --git a/.changeset/prd-8196-comment-highlights-not-yellow.md b/.changeset/prd-8196-comment-highlights-not-yellow.md
new file mode 100644
index 000000000..3430b9c5d
--- /dev/null
+++ b/.changeset/prd-8196-comment-highlights-not-yellow.md
@@ -0,0 +1,5 @@
+---
+"@inkeep/open-knowledge": patch
+---
+
+Comment highlights are blue instead of yellow. Yellow is what lint and audit problems use, and what the `==highlight==` mark already wears, so a commented passage was about to be indistinguishable from a warning sitting on the same words. Comments now hold a colour of their own — the passage wash and its underline, the marker in the margin rail, the tint on the card being read, and the highlight on a commented property value all moved together, so the mark still reads as one thing wherever it appears.
diff --git a/packages/app/src/comments/CommentMarginRail.tsx b/packages/app/src/comments/CommentMarginRail.tsx
index c5d303f85..ed9141916 100644
--- a/packages/app/src/comments/CommentMarginRail.tsx
+++ b/packages/app/src/comments/CommentMarginRail.tsx
@@ -306,7 +306,11 @@ export function CommentMarginRail({ editor, docName }: { editor: Editor; docName
'pointer-events-auto absolute left-0 size-7 rounded-full border bg-background p-0 shadow-sm transition-colors hover:bg-muted',
// Dimmed: it is parked at the edge, not pointing at the line beside it.
pos.offscreen && 'opacity-40 hover:opacity-100',
- active && 'border-amber-500 bg-amber-50',
+ // Tracks COMMENT_HUE in `anchor-layers.ts` — the marker wears the
+ // colour of the passage it points at. The dark pairing is not
+ // optional: an un-inverted `-50` fill is near-white, which turns
+ // the active marker into a white disc on the dark canvas.
+ active && 'border-blue-600 bg-blue-50 dark:border-blue-500 dark:bg-blue-950',
)}
style={{ top: pos.top - rail.top }}
data-comment-thread={thread.id}
@@ -316,7 +320,7 @@ export function CommentMarginRail({ editor, docName }: { editor: Editor; docName
onPointerEnter={() => setActiveThread(thread.id)}
onPointerLeave={() => clearActiveThread(thread.id)}
>
- <MessageSquare className="size-3.5 text-amber-500" />
+ <MessageSquare className="size-3.5 text-blue-600 dark:text-blue-400" />
</Button>
);
})}
diff --git a/packages/app/src/comments/ThreadCard.tsx b/packages/app/src/comments/ThreadCard.tsx
index 59d50720d..5ae904d25 100644
--- a/packages/app/src/comments/ThreadCard.tsx
+++ b/packages/app/src/comments/ThreadCard.tsx
@@ -91,7 +91,7 @@ export function ThreadCard({
cardRef: (el: HTMLElement | null) => void;
focused: boolean;
/**
- * The reader has this thread OPEN. The card answers with the same amber WASH
+ * The reader has this thread OPEN. The card answers with the same blue WASH
* the passage carries — background only, no border (a border reads as a
* statement about selection, which the tick owns). Open specifically, not
* hover: hosts used to pass the pointer-following active thread, and every
@@ -314,14 +314,16 @@ export function ThreadCard({
'flex flex-col gap-1.5 rounded-lg border p-2.5 transition-[box-shadow,border-color,background-color]',
cardSelects && 'cursor-pointer',
isResolved && 'opacity-70',
- // No card treatment for a lost passage. Amber in this component means
+ // No card treatment for a lost passage. This hue in this component means
// the passage highlight — the wash a card takes while it is being read,
// matching the mark on its text in the document. A card tinted for its
// STATE spent that hue on something the document never echoes, and left
// every orphan looking permanently hovered.
// The same hue as the passage's highlight — and like it, a wash with no
- // outline, so being-read never masquerades as being-selected.
- active && 'bg-amber-500/10',
+ // outline, so being-read never masquerades as being-selected. Tracks
+ // COMMENT_HUE in `anchor-layers.ts`; recolouring one means recolouring
+ // both, and nothing checks that for you.
+ active && 'bg-blue-600/10',
focused && 'ring-2 ring-primary',
)}
>
@@ -366,7 +368,7 @@ export function ThreadCard({
)}
{/* No badge for the lost-passage state. The block below already says
it in a full sentence, right under the words it is about, and the
- card carries the amber treatment either way — a badge saying the
+ card carries the blue treatment either way — a badge saying the
same thing two lines up was the state announced twice. Resolved
keeps its badge because nothing else on that card says so. */}
{/* Edit rides beside Delete rather than in a row of its own: the two
diff --git a/packages/app/src/comments/anchor-layers.test.ts b/packages/app/src/comments/anchor-layers.test.ts
index c80a1976c..0195df5ed 100644
--- a/packages/app/src/comments/anchor-layers.test.ts
+++ b/packages/app/src/comments/anchor-layers.test.ts
@@ -1,12 +1,19 @@
import { describe, expect, it } from 'vitest';
-import { buildAnchorSegments, type PlacedAnchor } from './anchor-layers';
+import { buildAnchorSegments, COMMENT_HUE, type PlacedAnchor } from './anchor-layers';
const at = (id: string | null, from: number, to: number): PlacedAnchor => ({ id, from, to });
+// Built from the hue rather than restating it: what these assertions are about
+// is the resting/active intensity ladder, which is what separates the thread
+// being read from the rest. The hue itself is a token that may be rebranded,
+// and pinning it here twice only makes that a test edit.
+const ACTIVE_FILL = `rgba(${COMMENT_HUE},0.45)`;
const RESTING =
- 'border-radius:2px;padding-bottom:1px;cursor:pointer;background-color:rgba(245,158,11,0.22);box-shadow:inset 0 -2px 0 rgba(245,158,11,0.7);';
+ `border-radius:2px;padding-bottom:1px;cursor:pointer;background-color:rgba(${COMMENT_HUE},0.22);` +
+ `box-shadow:inset 0 -2px 0 rgba(${COMMENT_HUE},0.7);`;
const ACTIVE =
- 'border-radius:2px;padding-bottom:1px;cursor:pointer;background-color:rgba(245,158,11,0.45);box-shadow:inset 0 -2px 0 rgba(245,158,11,1);';
+ `border-radius:2px;padding-bottom:1px;cursor:pointer;background-color:${ACTIVE_FILL};` +
+ `box-shadow:inset 0 -2px 0 rgba(${COMMENT_HUE},1);`;
describe('buildAnchorSegments', () => {
it('leaves a lone unattended highlight on its original style', () => {
@@ -64,13 +71,13 @@ describe('buildAnchorSegments', () => {
const [segment] = buildAnchorSegments([at(null, 0, 8)]);
expect(segment.threadId).toBeNull();
expect(segment.style).not.toContain('cursor:pointer');
- expect(segment.style).toContain('rgba(245,158,11,0.45)');
+ expect(segment.style).toContain(ACTIVE_FILL);
});
it('stands the draft out from the comment it overlaps', () => {
const segments = buildAnchorSegments([at('t1', 0, 10), at(null, 6, 16)]);
expect(segments[0].style).toBe(RESTING);
- expect(segments[1].style).toContain('rgba(245,158,11,0.45)');
+ expect(segments[1].style).toContain(ACTIVE_FILL);
expect(segments[2].threadId).toBeNull();
});
diff --git a/packages/app/src/comments/anchor-layers.ts b/packages/app/src/comments/anchor-layers.ts
index 5e21a70f9..c957ec802 100644
--- a/packages/app/src/comments/anchor-layers.ts
+++ b/packages/app/src/comments/anchor-layers.ts
@@ -31,14 +31,34 @@ export interface AnchorSegment {
}
/**
- * Amber, as `r,g,b` for interpolation into `rgba()`.
+ * Blue, as an `r,g,b` triple for interpolation into `rgba()`.
+ *
+ * Yellow and red are reserved: lint and audit problems mark up passages in the
+ * same body text, and the `==highlight==` mark is a yellow wash too — a comment
+ * in amber was a third thing wearing the warning colour.
+ *
+ * Deeper than `--color-azure-blue`, which in-viewer find washes over its matches
+ * at 30%. Sharing a family with find is the cost of blue; the underline below is
+ * what separates them, since find paints a bare wash with no rule under it.
+ *
+ * The value is a CSS custom property, not a literal, because it is the one part
+ * of the mark that must move with the theme — the alpha ladder below is painted
+ * identically on both canvases, and no single blue clears the 3:1 non-text floor
+ * at both ends. `globals.css` holds both values; the fallback here is the light
+ * one, so an unstyled mount degrades to a visible mark rather than to
+ * `rgba()` with a missing argument, which drops the highlight entirely.
*
* Exported because a property value's highlight cannot be a decoration — it is
* painted as the field's own `::selection`, in `property-row-rect.ts`. Two
* highlights meaning the same thing in two different colours would read as two
- * different states, so the colour has exactly one definition.
+ * different states, so both in-document washes derive from here.
+ *
+ * The panel surfaces cannot: `ThreadCard` and `CommentMarginRail` are styled in
+ * Tailwind, which takes class literals rather than an `rgb()` triple, so each
+ * carries a hand-kept `blue-*` mirror. Recolouring means editing those two, this
+ * fallback, and both `globals.css` declarations.
*/
-export const COMMENT_HUE = '245,158,11';
+export const COMMENT_HUE = 'var(--ok-comment-hue,37,99,235)';
const HUE = COMMENT_HUE;
/** Held at its pre-overlap value, so an unattended highlight is unchanged. */
diff --git a/packages/app/src/comments/comment-hue-contrast.test.ts b/packages/app/src/comments/comment-hue-contrast.test.ts
new file mode 100644
index 000000000..7b4a4c80a
--- /dev/null
+++ b/packages/app/src/comments/comment-hue-contrast.test.ts
@@ -0,0 +1,116 @@
+/**
+ * WCAG non-text contrast gate for the comment-highlight hue.
+ *
+ * The highlight is a graphical indicator — it is what says "someone commented
+ * on these words" — so it owes WCAG 2.x 1.4.11's 3:1 floor against the canvas
+ * behind it, the same bar the chart palette is held to in
+ * `preview-theme-tokens.test.ts`. The underline carries that signal: the fill
+ * is a faint tint by design and does not clear 3:1 on its own at either end.
+ *
+ * This is also the only pin on the hue's actual value. `anchor-layers.test.ts`
+ * derives its expected styles from the constant so it asserts the intensity
+ * ladder rather than the colour, which leaves a miscoded hue free to pass
+ * everywhere else. A number that fails here is either a bad hue or an alpha
+ * ladder that has drifted, and both are worth stopping.
+ */
+
+import { readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { describe, expect, test } from 'vitest';
+
+const GLOBALS_CSS = resolve(dirname(fileURLToPath(import.meta.url)), '../globals.css');
+
+/** WCAG 2.x 1.4.11 — graphical objects, as opposed to text's 4.5:1. */
+const MIN_NONTEXT_CONTRAST = 3;
+
+/**
+ * The resting underline's alpha, from `anchor-layers.ts`. Resting rather than
+ * active because it is the weaker of the two — an unattended comment is the
+ * state a reader has to notice unprompted.
+ */
+const RESTING_LINE_ALPHA = 0.7;
+
+/**
+ * The canvases, resolved from `--background`. Held as literals because
+ * converting oklch in-test would mean pulling a colour library into
+ * `packages/app` for one assertion; `canvas declarations are unchanged` below
+ * fails loudly if either token moves, which is the point at which these need
+ * recomputing.
+ */
+const CANVASES = {
+ light: { rgb: [255, 255, 255], decl: 'oklch(1 0 0)' },
+ dark: { rgb: [10, 10, 10], decl: 'oklch(0.145 0 0)' },
+} as const;
+
+type Rgb = readonly [number, number, number] | number[];
+
+function channel(value: number): number {
+ const c = value / 255;
+ return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
+}
+
+function luminance([r, g, b]: Rgb): number {
+ return 0.2126 * channel(r) + 0.7152 * channel(g) + 0.0722 * channel(b);
+}
+
+function contrast(a: Rgb, b: Rgb): number {
+ const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
+ return (hi + 0.05) / (lo + 0.05);
+}
+
+/** Flatten a translucent mark onto the opaque canvas behind it. */
+function composite(fg: Rgb, alpha: number, bg: Rgb): number[] {
+ return [0, 1, 2].map((i) => alpha * fg[i] + (1 - alpha) * bg[i]);
+}
+
+const css = readFileSync(GLOBALS_CSS, 'utf8');
+
+/**
+ * Both declarations of one custom property, in source order. `:root` is
+ * authored before `.dark` in `globals.css`, so the first is light.
+ */
+function declarations(name: string): string[] {
+ return [...css.matchAll(new RegExp(`^\\s*${name}:\\s*([^;]+);`, 'gm'))].map((m) => m[1].trim());
+}
+
+function hue(declaration: string): number[] {
+ const parts = declaration.split(',').map((p) => Number(p.trim()));
+ expect(parts).toHaveLength(3);
+ for (const part of parts) expect(Number.isFinite(part)).toBe(true);
+ return parts;
+}
+
+describe('comment highlight hue', () => {
+ test('canvas declarations are unchanged', () => {
+ // Guards the literals in CANVASES. If this fails, --background moved and
+ // the ratios below are being measured against the wrong ground.
+ const backgrounds = declarations('--background');
+ expect(backgrounds[0]).toBe(CANVASES.light.decl);
+ expect(backgrounds[1]).toBe(CANVASES.dark.decl);
+ });
+
+ test('is declared once per theme', () => {
+ expect(declarations('--ok-comment-hue')).toHaveLength(2);
+ });
+
+ test.each([
+ ['light', 0],
+ ['dark', 1],
+ ] as const)('resting underline clears 3:1 on the %s canvas', (theme, index) => {
+ const canvas = CANVASES[theme].rgb;
+ const line = composite(
+ hue(declarations('--ok-comment-hue')[index]),
+ RESTING_LINE_ALPHA,
+ canvas,
+ );
+ expect(contrast(line, canvas)).toBeGreaterThanOrEqual(MIN_NONTEXT_CONTRAST);
+ });
+
+ test('the two themes take different hues', () => {
+ // Not cosmetic: a single hue across both canvases is exactly the state that
+ // failed — one blue cannot clear the floor on white and on near-black.
+ const [light, dark] = declarations('--ok-comment-hue');
+ expect(light).not.toBe(dark);
+ });
+});
diff --git a/packages/app/src/comments/orphan-deleted-quote.dom.test.tsx b/packages/app/src/comments/orphan-deleted-quote.dom.test.tsx
index 55ea4f289..97e4d783e 100644
--- a/packages/app/src/comments/orphan-deleted-quote.dom.test.tsx
+++ b/packages/app/src/comments/orphan-deleted-quote.dom.test.tsx
@@ -2,7 +2,7 @@
* What an orphaned card says, and what it still shows.
*
* Losing the passage used to print a bare "the anchored text is gone" and drop
- * the quote with it, so a panel of orphans was a column of identical amber
+ * the quote with it, so a panel of orphans was a column of identical blue
* notices with no way to tell which comment had been on what. Orphaning mutates
* state alone — the stored words survive — so the card shows them as the last
* thing the comment was on.
diff --git a/packages/app/src/comments/property-row-rect.ts b/packages/app/src/comments/property-row-rect.ts
index eb064b77e..c851f4660 100644
--- a/packages/app/src/comments/property-row-rect.ts
+++ b/packages/app/src/comments/property-row-rect.ts
@@ -17,9 +17,9 @@ import { COMMENT_ACTIVE_FILL, COMMENT_HUE } from './anchor-layers';
/**
* Marks the field whose selection is standing in for a comment highlight, so
- * `globals.css` can paint it amber instead of the browser's blue. Cleared on
- * blur — once the reveal is over the field's ordinary selection must look
- * ordinary again.
+ * `globals.css` can paint it the comment hue instead of the browser's ordinary
+ * selection. Cleared on blur — once the reveal is over the field's ordinary
+ * selection must look ordinary again.
*/
const REVEAL_ATTR = 'data-comment-reveal';
@@ -129,7 +129,7 @@ export function locateInValue(
*
* Scoped to the reveal because the attribute would otherwise repaint every
* ordinary selection in that field: someone highlighting text to retype it
- * would see comment-amber and reasonably think they had hit a comment.
+ * would see comment-blue and reasonably think they had hit a comment.
*/
function paintRevealSelection(control: HTMLTextAreaElement | HTMLInputElement): void {
control.style.setProperty('--comment-reveal-fill', `rgba(${COMMENT_HUE},${COMMENT_ACTIVE_FILL})`);
diff --git a/packages/app/src/comments/queued-toggle.dom.test.tsx b/packages/app/src/comments/queued-toggle.dom.test.tsx
index 403e91b5c..264f252e9 100644
--- a/packages/app/src/comments/queued-toggle.dom.test.tsx
+++ b/packages/app/src/comments/queued-toggle.dom.test.tsx
@@ -112,7 +112,7 @@ describe('opening an edit', () => {
});
describe('the active-thread tint', () => {
- test('the card being read in the document carries the highlight amber', () => {
+ test('the card being read in the document carries the highlight blue', () => {
render(
<TooltipProvider>
<ThreadCard
@@ -129,8 +129,8 @@ describe('the active-thread tint', () => {
// A WASH, deliberately not a border: an outline reads as "this comment is
// picked", and being read is not being selected — the tick owns that.
const card = screen.getByRole('article');
- expect(card.className).toContain('bg-amber-500/10');
- expect(card.className).not.toContain('border-amber-500/60');
+ expect(card.className).toContain('bg-blue-600/10');
+ expect(card.className).not.toContain('border-blue-600/60');
});
test('an inactive card carries none', () => {
@@ -145,7 +145,7 @@ describe('the active-thread tint', () => {
/>
</TooltipProvider>,
);
- expect(screen.getByRole('article').className).not.toContain('bg-amber-500/10');
+ expect(screen.getByRole('article').className).not.toContain('bg-blue-600/10');
});
});
diff --git a/packages/app/src/globals.css b/packages/app/src/globals.css
index 11f5b6056..6408fcd3f 100644
--- a/packages/app/src/globals.css
+++ b/packages/app/src/globals.css
@@ -3145,6 +3145,15 @@ button:active:not(:disabled) {
* override would introduce a sibling `--selection` token at higher alpha
* for body prose. */
--selection-soft: oklch(0.66 0.18 259 / 0.18);
+ /* Comment-highlight hue, as `r,g,b` for interpolation into `rgba()` by the
+ anchor decorations (`comments/anchor-layers.ts`) and the property-value
+ `::selection` twin. It lives here rather than in TS because it is the one
+ part of the mark that must differ per theme: the decoration paints the same
+ alpha ladder on both canvases, so a single hue cannot clear the 3:1 non-text
+ floor at both ends — blue-600 does it on white, and washes out to 2.4:1 on
+ the dark canvas. Dark takes blue-400. Gated by comment-hue-contrast.test.ts;
+ the Tailwind mirrors on the rail marker and thread card are hand-kept. */
+ --ok-comment-hue: 37, 99, 235;
/* Categorical chart palette for `html preview` embeds — five
perceptually-distinct hues aligned with the callout color system
(--chart-1 anchors to the brand azure, the rest track the
@@ -3263,6 +3272,9 @@ button:active:not(:disabled) {
/* Dark-mode soft range halo — slightly brighter + higher alpha so the
* 18%-on-white equivalent reads cleanly on dark backgrounds. */
--selection-soft: oklch(0.72 0.16 259 / 0.32);
+ /* Dark-canvas comment hue — blue-400. See the :root declaration for why this
+ is the one token in the mark that has to move with the theme. */
+ --ok-comment-hue: 96, 165, 250;
/* Dark-mode chart palette — same hue family as the :root block above,
lightness lifted for legibility on the dark --background. Keep in sync
with :root --chart-* and PREVIEW_THEME_TOKENS (preview-theme-tokens.test.ts). */
@@ -6210,7 +6222,7 @@ html.electron-mode [data-slot="sidebar-inner"] {
* A property value is a `<textarea>`, whose text no decoration can reach — so
* the highlight is the field's own selection, recoloured to match. The fill
* comes from `--comment-reveal-fill`, set alongside the attribute in
- * `property-row-rect.ts`, so the amber has one definition rather than two that
+ * `property-row-rect.ts`, so the hue has one definition rather than two that
* can drift apart.
*
* Attribute-scoped on purpose: without it every ordinary selection in the field