kenn-io--agentsview/DESIGN.md

Design System

agentsview is a dense local-first product UI. The interface should use a small, consistent component vocabulary rather than one-off styling for each new control.

Component Rules

• Before adding any interactive frontend control, search frontend/src/lib/components for an existing component that already covers the behavior.
• Prefer existing shared components over native controls with local CSS.
• Do not add new hand-styled native <select> controls. Use the shared typeahead/combobox components for single-choice selectors unless there is a documented reason the native control is required.
• Do not introduce component-specific control chrome such as .foo-select, manual select chevrons, or one-off input/button height and padding rules when a shared control or token should own the styling.
• If a new control pattern is genuinely needed, add or extend a shared component first, then use it from feature components.

Internationalization

• Treat user-facing frontend UI copy as part of the component contract. New headings, labels, button text, placeholders, tooltips, aria labels, empty states, loading states, and error messages should go through the locale dictionaries instead of hard-coded English strings.
• Source messages live in frontend/messages/{locale}.json. Use flat, lowercase, underscore-separated Paraglide message keys. Group ownership with prefixes instead of nesting, for example settings_language_title or sidebar_filters_starred_only.
• In Svelte components, import generated messages through the local facade: import { m } from "../../i18n/index.js";. Render static messages as m.some_key() and parameterized messages as m.some_key({ value }). Adjust the relative import path for the file location.
• Do not import svelte-i18n or use $_(...). Locale changes use Paraglide's normal reload behavior, so components should call generated message functions directly.
• Do not edit files under frontend/src/lib/paraglide by hand. They are generated by the Paraglide Vite plugin or by npm run i18n:compile, and npm run check regenerates them before running svelte-check.
• Keep every supported locale file in sync when adding, removing, or renaming a key. The English locale should preserve the source copy, and translated locales should provide the best available translation in the same change.
• Shared components should accept translated labels, placeholders, titles, and aria text from their callers. Avoid hiding English copy inside reusable controls unless the copy is internal-only and never user-visible.
• Do not translate technical identifiers such as agent names, model names, CLI flags, API paths, config keys, file paths, command snippets, user session content, or exported data formats.
• Prefer parameterized locale messages for dynamic sentences instead of assembling user-visible strings from translated fragments.
• Count-based user-facing messages with count-sensitive nouns must use Paraglide plural variants instead of hard-coded strings such as {count} sessions or {count} calls. Pass a numeric count for plural selection, and pass a separate formatted label such as countLabel when the displayed value needs locale formatting.
• Locale selection is preference-first, not URL-as-source. Paraglide is configured with ["localStorage", "preferredLanguage", "baseLocale"] because the frontend is an embedded SPA without localized routes.

Current Shared Controls

Most shared controls come from the @kenn-io/kit-ui library (imported as import { ... } from "@kenn-io/kit-ui"): Button, Chip, CopyButton, EmptyState, FilterDropdown, FindBar, IconButton, KbdBadge, Modal, RangePicker, RefreshControl, SegmentedControl, Spinner, StatusBar, StatusDot, Table/TableHeaderCell, TextInput/SearchInput, Tooltip, TopBar, and Typeahead. Shared components take pre-translated strings as props — call m.*() at the call site (or in a thin app wrapper) and pass the result.

App-level glue that remains local:

• frontend/src/lib/components/layout/ProjectTypeahead.svelte wraps kit-ui Typeahead for project selection. Use kit-ui Typeahead directly for other bounded option lists.
• frontend/src/lib/components/shared/RangePicker.svelte is a thin wrapper over kit-ui DateRangePicker that injects localized strings, the app locale, and maps the app's selection API; date-range resolution stays in frontend/src/lib/components/shared/rangeSelection.ts.
• frontend/src/lib/components/shared/RefreshControl.svelte wraps kit-ui RefreshControl, injecting the localized age formatter and app locale.
• kit-ui components with a locale prop (DateRangePicker, RefreshControl, Calendar) should receive locale={getLocale()} from the i18n facade so their date formatting follows the app language setting instead of the browser locale; the shared wrappers above do this.
• frontend/src/lib/components/content/SessionFindBar.svelte wires kit-ui FindBar to the in-session search store.
• frontend/src/lib/components/settings/SettingsSection.svelte owns settings section framing.

Relative date ranges follow kit-ui semantics: "Last N days" spans N calendar days inclusive of today. presetRange() (dateRangeSelector.ts) and rollingRange() (utils/dates.ts) must stay consistent with each other and with kit-ui's RangePicker, which seeds its Custom tab from the same math.

Known kit-ui gaps (tracked upstream)

These gaps ship with the current kit-ui pin and are resolved by adding props upstream, then bumping the commit hash in frontend/package.json and threading the new props through the app wrappers. Do not work around them with unsupported props or forked styles.

• Modal's close-X aria-label is hardcoded English; needs a label prop.
• TopBar cannot express "no active tab"; on routes that are not tabs (settings), the first tab renders as current.

Resolved upstream (adopted at the current pin): RefreshControl takes a formatAge prop, DateRangePicker's weekOfLabel substitutes a {date} placeholder, and both take a locale prop — the shared wrappers inject all three.

Legacy Exceptions

Some existing activity components still contain native <select> controls and manual control CSS. Treat those as legacy debt, not precedent for new work.