Skip to content

Beautiful, AI-native markdown IDE and LLM wiki

fix(open-knowledge): settings row density pass, and wire row descriptions to screen readers (#3283)

serafin-garcia771d5df21707
diff --git a/.changeset/settings-row-density-and-descriptions.md b/.changeset/settings-row-density-and-descriptions.md
new file mode 100644
index 000000000..0cb389307
--- /dev/null
+++ b/.changeset/settings-row-density-and-descriptions.md
@@ -0,0 +1,7 @@
+---
+'@inkeep/open-knowledge': patch
+---
+
+Settings rows with a label and a description now have room to breathe: vertical padding goes from 8px to 12px, and the description drops to the 13px scale the rest of the settings dialog already uses. Previously the label and its description rendered at the same size in a tight row, so each entry read as one flat block — the "markdownlint entry looks crowded" report.
+
+Screen readers now announce what a setting actually does before you change it. The Plugins, Content rules, Search, and Link previews toggles are each wired to their own row description — previously that description was shown on screen but never announced, so the semantic-search and link-preview toggles in particular gave no spoken indication that turning them on sends content off your machine.
diff --git a/packages/app/src/components/settings/ContentRulesSection.dom.test.tsx b/packages/app/src/components/settings/ContentRulesSection.dom.test.tsx
index 5286d50bd..fd93fef0b 100644
--- a/packages/app/src/components/settings/ContentRulesSection.dom.test.tsx
+++ b/packages/app/src/components/settings/ContentRulesSection.dom.test.tsx
@@ -9,6 +9,7 @@ import { cleanup, fireEvent, render, screen, waitFor } from '@testing-library/re
import type { ReactNode } from 'react';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import { renderLinguiTemplate } from '@/test-utils/lingui-mock';
+import { describedTextOf } from './settings-a11y.test-helper';
const linguiMacroMock = {
t: renderLinguiTemplate,
@@ -72,6 +73,16 @@ describe('ContentRulesSection', () => {
);
});
+ test('both controls are described by their own row description', () => {
+ render(<ContentRulesSection />);
+ for (const [testId, expected] of [
+ ['settings-content-rules-links', 'How unresolved wiki-links are reported'],
+ ['settings-content-rules-indicators', 'Tint and badge files'],
+ ] as const) {
+ expect(describedTextOf(testId)).toContain(expected);
+ }
+ });
+
test('toggling indicators writes a validation patch', () => {
render(<ContentRulesSection />);
fireEvent.click(screen.getByTestId('settings-content-rules-indicators'));
diff --git a/packages/app/src/components/settings/ContentRulesSection.tsx b/packages/app/src/components/settings/ContentRulesSection.tsx
index fa764aae9..649e02bc3 100644
--- a/packages/app/src/components/settings/ContentRulesSection.tsx
+++ b/packages/app/src/components/settings/ContentRulesSection.tsx
@@ -61,12 +61,15 @@ export function ContentRulesSection() {
</div>
<div className="divide-y rounded-md border">
- <div className="flex items-center justify-between gap-3 px-3 py-2">
+ <div className="flex items-center justify-between gap-3 px-3 py-3">
<div className="min-w-0">
<Label htmlFor="settings-content-rules-links" className="text-sm font-medium">
<Trans>Broken internal links</Trans>
</Label>
- <p className="text-sm text-muted-foreground">
+ <p
+ id="settings-content-rules-links-description"
+ className="text-1sm text-muted-foreground"
+ >
<Trans>
How unresolved wiki-links are reported in the Problems panel, audits, and agent
tools.
@@ -80,6 +83,7 @@ export function ContentRulesSection() {
>
<SelectTrigger
id="settings-content-rules-links"
+ aria-describedby="settings-content-rules-links-description"
className="w-36 shrink-0"
data-testid="settings-content-rules-links"
>
@@ -99,12 +103,15 @@ export function ContentRulesSection() {
</Select>
</div>
- <div className="flex items-center justify-between gap-3 px-3 py-2">
+ <div className="flex items-center justify-between gap-3 px-3 py-3">
<div className="min-w-0">
<Label htmlFor="settings-content-rules-indicators" className="text-sm font-medium">
<Trans>Problem indicators in the file explorer</Trans>
</Label>
- <p className="text-sm text-muted-foreground">
+ <p
+ id="settings-content-rules-indicators-description"
+ className="text-1sm text-muted-foreground"
+ >
<Trans>
Tint and badge files that have lint or link problems, without opening them.
</Trans>
@@ -112,6 +119,7 @@ export function ContentRulesSection() {
</div>
<Switch
id="settings-content-rules-indicators"
+ aria-describedby="settings-content-rules-indicators-description"
checked={indicatorsOn}
disabled={!bindingReady}
onCheckedChange={(next) => write({ fileTreeIndicators: next })}
diff --git a/packages/app/src/components/settings/LinkPreviewsSection.dom.test.tsx b/packages/app/src/components/settings/LinkPreviewsSection.dom.test.tsx
index e2a07f0b7..84d05dc7a 100644
--- a/packages/app/src/components/settings/LinkPreviewsSection.dom.test.tsx
+++ b/packages/app/src/components/settings/LinkPreviewsSection.dom.test.tsx
@@ -13,6 +13,7 @@ import type { Config, ConfigBinding } from '@inkeep/open-knowledge-core';
import { cleanup, render, screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { describedTextOf } from './settings-a11y.test-helper';
// Radix Dialog mounts a focus-trap that reaches for DOM globals the jsdom
// preload doesn't expose. Hoist the same shims the sibling settings DOM tests
@@ -118,6 +119,21 @@ describe('LinkPreviewsSection', () => {
);
});
+ test('the egress disclosure is announced with the toggle, not just shown beside it', () => {
+ // The body text is what tells you hovering a link reaches out to the
+ // destination site. Without aria-describedby a screen-reader user hears
+ // only "Enable external link previews" and never learns that.
+ const { binding } = makeBinding();
+ mockProjectLocalBinding = binding;
+ mockProjectLocalConfig = configWithLinkPreviews(true);
+
+ render(<LinkPreviewsSection />);
+
+ expect(describedTextOf('settings-link-previews-toggle')).toContain(
+ 'sends its URL to the destination site',
+ );
+ });
+
test('toggle is disabled until the project-local binding has synced', () => {
mockProjectLocalBinding = null;
mockProjectLocalSynced = false;
diff --git a/packages/app/src/components/settings/LinkPreviewsSection.tsx b/packages/app/src/components/settings/LinkPreviewsSection.tsx
index 8dfb6f80b..b91f15bf6 100644
--- a/packages/app/src/components/settings/LinkPreviewsSection.tsx
+++ b/packages/app/src/components/settings/LinkPreviewsSection.tsx
@@ -105,7 +105,11 @@ export function LinkPreviewsSection() {
<label htmlFor="settings-link-previews-toggle" className="text-sm font-medium">
<Trans>External link previews</Trans>
</label>
- <p className="text-muted-foreground text-1sm" data-testid="settings-link-previews-body">
+ <p
+ id="settings-link-previews-toggle-description"
+ className="text-muted-foreground text-1sm"
+ data-testid="settings-link-previews-body"
+ >
{enabled ? (
<Trans>
On — hovering an external link sends its URL to the destination site to fetch a
@@ -121,6 +125,7 @@ export function LinkPreviewsSection() {
<Switch
ref={switchRef}
id="settings-link-previews-toggle"
+ aria-describedby="settings-link-previews-toggle-description"
checked={enabled}
disabled={!bindingReady}
onCheckedChange={onToggleRequest}
diff --git a/packages/app/src/components/settings/LintingSection.dom.test.tsx b/packages/app/src/components/settings/LintingSection.dom.test.tsx
index f322418d7..3f4950d16 100644
--- a/packages/app/src/components/settings/LintingSection.dom.test.tsx
+++ b/packages/app/src/components/settings/LintingSection.dom.test.tsx
@@ -10,6 +10,7 @@ import { cleanup, render, screen, within } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
import { TooltipProvider } from '@/components/ui/tooltip';
+import { describedTextOf } from './settings-a11y.test-helper';
// Radix primitives reach for DOM globals the jsdom preload doesn't expose;
// hoist the same shims the sibling settings DOM tests use.
@@ -184,6 +185,25 @@ describe('ProjectPluginsManageSection', () => {
expect(rows[0]?.closest('label')?.textContent).toContain('Frontmatter schemas');
});
+ test('every plugin toggle is described by its own row description', () => {
+ // Hand-rolled rows do not get the aria-describedby wiring that the
+ // schema-driven SettingsField gets for free from FormControl, so a screen
+ // reader on the switch would otherwise hear the plugin name and nothing
+ // about what the plugin does.
+ const { binding } = makeBinding();
+ mockProjectBinding = binding;
+ render(<ProjectPluginsManageSection />);
+
+ // Both plugins, because their descriptions come from separate branches of
+ // PluginManageDescription and each carries the same screen-reader promise.
+ expect(describedTextOf('settings-plugin-toggle-markdownlint')).toContain(
+ 'Common markdown issues',
+ );
+ expect(describedTextOf('settings-plugin-toggle-frontmatter')).toContain(
+ 'Validate document frontmatter',
+ );
+ });
+
test('toggling a project plugin writes the per-plugin enabled patch', async () => {
const { binding, calls } = makeBinding();
mockProjectBinding = binding;
@@ -268,6 +288,19 @@ describe('UserPluginsManageSection', () => {
expect(screen.queryByTestId('settings-plugin-toggle-markdownlint')).toBeNull();
});
+ test('every user-scope toggle is described by its row description, like the project rows', () => {
+ const { binding } = makeBinding();
+ mockProjectBinding = binding;
+ render(<UserPluginsManageSection userBinding={null} />);
+
+ expect(describedTextOf('settings-plugin-toggle-theme')).toContain(
+ 'A personal color-theme picker',
+ );
+ expect(describedTextOf('settings-plugin-toggle-slides')).toContain(
+ 'Present a document as a slide deck',
+ );
+ });
+
test('the Themes toggle writes the user-scope enabled patch', async () => {
const { binding } = makeBinding();
mockProjectBinding = binding;
diff --git a/packages/app/src/components/settings/LintingSection.tsx b/packages/app/src/components/settings/LintingSection.tsx
index a78c67835..c1a2f57b4 100644
--- a/packages/app/src/components/settings/LintingSection.tsx
+++ b/packages/app/src/components/settings/LintingSection.tsx
@@ -127,8 +127,9 @@ export function ProjectPluginsManageSection() {
<div className="divide-y rounded-md border" data-testid="settings-plugins-list">
{LINT_PLUGIN_META.map((plugin) => {
const on = contentRules?.[plugin.id]?.enabled === true;
+ const descriptionId = `settings-plugin-toggle-${plugin.id}-description`;
return (
- <div key={plugin.id} className="flex items-center justify-between gap-3 px-3 py-2">
+ <div key={plugin.id} className="flex items-center justify-between gap-3 px-3 py-3">
<div className="min-w-0">
<Label
htmlFor={`settings-plugin-toggle-${plugin.id}`}
@@ -137,12 +138,13 @@ export function ProjectPluginsManageSection() {
{plugin.label}
{plugin.id === 'frontmatter' ? <PluginBetaBadge /> : null}
</Label>
- <p className="text-sm text-muted-foreground">
+ <p id={descriptionId} className="text-1sm text-muted-foreground">
<PluginManageDescription id={plugin.id} />
</p>
</div>
<Switch
id={`settings-plugin-toggle-${plugin.id}`}
+ aria-describedby={descriptionId}
checked={on}
disabled={!bindingReady}
onCheckedChange={(next) => {
@@ -198,12 +200,15 @@ export function UserPluginsManageSection({ userBinding }: { userBinding: ConfigB
</div>
<div className="divide-y rounded-md border" data-testid="settings-user-plugins-list">
- <div className="flex items-center justify-between gap-3 px-3 py-2">
+ <div className="flex items-center justify-between gap-3 px-3 py-3">
<div className="min-w-0">
<Label htmlFor="settings-plugin-toggle-theme" className="text-sm font-medium">
<Trans>Themes</Trans>
</Label>
- <p className="text-sm text-muted-foreground">
+ <p
+ id="settings-plugin-toggle-theme-description"
+ className="text-1sm text-muted-foreground"
+ >
<Trans>
A personal color-theme picker — not shared with your project. When on, it appears
under Plugins in the sidebar.
@@ -212,6 +217,7 @@ export function UserPluginsManageSection({ userBinding }: { userBinding: ConfigB
</div>
<Switch
id="settings-plugin-toggle-theme"
+ aria-describedby="settings-plugin-toggle-theme-description"
checked={themeEnabled}
disabled={userBinding === null}
onCheckedChange={(next) => {
@@ -229,7 +235,7 @@ export function UserPluginsManageSection({ userBinding }: { userBinding: ConfigB
data-testid="settings-plugin-toggle-theme"
/>
</div>
- <div className="flex items-center justify-between gap-3 px-3 py-2">
+ <div className="flex items-center justify-between gap-3 px-3 py-3">
<div className="min-w-0">
<Label
htmlFor="settings-plugin-toggle-slides"
@@ -238,7 +244,10 @@ export function UserPluginsManageSection({ userBinding }: { userBinding: ConfigB
<Trans>Slidev</Trans>
<PluginBetaBadge />
</Label>
- <p className="text-sm text-muted-foreground">
+ <p
+ id="settings-plugin-toggle-slides-description"
+ className="text-1sm text-muted-foreground"
+ >
<Trans>
Present a document as a slide deck in its own window. Works in the OpenKnowledge
desktop app only, and needs the Slidev CLI, which you install separately. When on,
@@ -248,6 +257,7 @@ export function UserPluginsManageSection({ userBinding }: { userBinding: ConfigB
</div>
<Switch
id="settings-plugin-toggle-slides"
+ aria-describedby="settings-plugin-toggle-slides-description"
checked={slidesEnabled}
disabled={userBinding === null}
onCheckedChange={(next) => {
diff --git a/packages/app/src/components/settings/SearchSection.dom.test.tsx b/packages/app/src/components/settings/SearchSection.dom.test.tsx
index ab8afe91c..bd7a044ff 100644
--- a/packages/app/src/components/settings/SearchSection.dom.test.tsx
+++ b/packages/app/src/components/settings/SearchSection.dom.test.tsx
@@ -16,6 +16,7 @@ import {
import { cleanup, render, screen, waitFor } from '@testing-library/react';
import userEvent from '@testing-library/user-event';
import { afterEach, beforeEach, describe, expect, test, vi } from 'vitest';
+import { describedTextOf } from './settings-a11y.test-helper';
// Radix Dialog mounts a focus-trap that reaches for DOM globals the jsdom
// preload doesn't expose. Hoist the same shims the sibling settings DOM tests
@@ -128,6 +129,21 @@ describe('SearchSection', () => {
expect(screen.queryByTestId('settings-search-needs-key')).toBeNull();
});
+ test('the egress disclosure is announced with the toggle, not just shown beside it', () => {
+ // The body text is the only place that says queries and page text go to an
+ // embeddings provider. Without aria-describedby a screen-reader user hears
+ // only "Enable semantic search" and never learns content leaves the machine.
+ const { binding } = makeBinding();
+ mockProjectLocalBinding = binding;
+ mockProjectLocalConfig = configWithSemantic({ enabled: true });
+
+ render(<SearchSection />);
+
+ expect(describedTextOf('settings-search-semantic-toggle')).toContain(
+ 'sent to your embeddings provider',
+ );
+ });
+
test('toggle is disabled until the project-local binding has synced', () => {
mockProjectLocalBinding = null;
mockProjectLocalSynced = false;
diff --git a/packages/app/src/components/settings/SearchSection.tsx b/packages/app/src/components/settings/SearchSection.tsx
index 301a2c849..9495a6885 100644
--- a/packages/app/src/components/settings/SearchSection.tsx
+++ b/packages/app/src/components/settings/SearchSection.tsx
@@ -313,7 +313,11 @@ export function SearchSection({ transport }: { transport?: EmbeddingsKeyTranspor
<label htmlFor="settings-search-semantic-toggle" className="text-sm font-medium">
<Trans>Semantic search</Trans>
</label>
- <p className="text-muted-foreground text-1sm" data-testid="settings-search-body">
+ <p
+ id="settings-search-semantic-toggle-description"
+ className="text-muted-foreground text-1sm"
+ data-testid="settings-search-body"
+ >
{enabled ? (
<Trans>
On — your search queries and the text of matching pages are sent to your
@@ -326,6 +330,7 @@ export function SearchSection({ transport }: { transport?: EmbeddingsKeyTranspor
</div>
<Switch
id="settings-search-semantic-toggle"
+ aria-describedby="settings-search-semantic-toggle-description"
checked={enabled}
disabled={!bindingReady}
onCheckedChange={onToggleRequest}
diff --git a/packages/app/src/components/settings/settings-a11y.test-helper.ts b/packages/app/src/components/settings/settings-a11y.test-helper.ts
new file mode 100644
index 000000000..fcfd8a091
--- /dev/null
+++ b/packages/app/src/components/settings/settings-a11y.test-helper.ts
@@ -0,0 +1,22 @@
+import { screen } from '@testing-library/react';
+import { expect } from 'vitest';
+
+/**
+ * The text a screen reader announces as a control's description.
+ *
+ * Resolves every id in `aria-describedby` and joins them, because the attribute
+ * is a space-separated id list: a control described by more than one element is
+ * valid, and `getElementById('a b')` would silently return null. Today every
+ * settings row points at exactly one description — Radix's Switch and Select
+ * do not contribute ids of their own — so the join is a spec-correctness
+ * measure, not a workaround for current behavior.
+ */
+export function describedTextOf(controlTestId: string): string {
+ const control = screen.getByTestId(controlTestId);
+ const describedBy = control.getAttribute('aria-describedby');
+ expect(describedBy).toBeTruthy();
+ return (describedBy as string)
+ .split(' ')
+ .map((id) => document.getElementById(id)?.textContent ?? '')
+ .join(' ');
+}