docs(agent): streamline guidance and skills

Keep always-on instructions concise and route specialized work through focused skills. Split large skills into progressive references and add dedicated change, desktop, sync, and performance guidance.
2026-07-14 00:45:44 +03:00
parent b36afbf5ee
commit 68f1c1efe3
20 changed files with 1257 additions and 1371 deletions
@@ -0,0 +1,91 @@
+# Settings Controls
+
+Load `theme-system` for button/icon/color contracts and `locale-ui-patterns` for every visible or accessible string.
+
+## Choosing A Control
+
+- Short chip-like option set: shared `Button variant="chip" size="xs"` with `aria-pressed`.
+- Explicit mutually exclusive list: shared `Radio`.
+- Boolean value: shared `Checkbox`, not paired show/hide buttons.
+- Numeric value: shared `NumberInput`.
+- Text/path value: shared `Input` plus shared actions.
+
+Do not couple unrelated toggles beneath a synthetic heading.
+
+## Segmented Option
+
+```tsx
+<Button variant="chip" size="xs" aria-pressed={isSelected}>
+  {t(labelKey)}
+</Button>
+```
+
+## Radio Row
+
+```tsx
+<div role="radiogroup" aria-label={t(groupLabelKey)}>
+  <div className="flex items-center gap-2 py-0.5">
+    <Radio checked={selected} onChange={onSelect} ariaLabel={t(labelKey)} />
+    <span className={cn('typography-ui-label', selected ? 'text-foreground' : 'text-foreground/50')}>
+      {t(labelKey)}
+    </span>
+  </div>
+</div>
+```
+
+## Checkbox Row
+
+```tsx
+<div className="flex cursor-pointer items-center gap-2 py-1.5">
+  <Checkbox checked={value} onChange={setValue} ariaLabel={t(labelKey)} />
+  <span className="typography-ui-label">{t(labelKey)}</span>
+</div>
+```
+
+Preserve row click and keyboard behavior when the container is interactive.
+
+## Optional Numeric Override
+
+Empty means “inherit/default.” Provide fallback stepping and explicit clear:
+
+```tsx
+<NumberInput
+  value={temperature}
+  fallbackValue={0.7}
+  onValueChange={setTemperature}
+  onClear={() => setTemperature(undefined)}
+  min={0}
+  max={2}
+  step={0.1}
+  inputMode="decimal"
+  emptyLabel="—"
+/>
+```
+
+Keep reset adjacent. Prefer an info tooltip over persistent helper text when the explanation is secondary.
+
+## Inputs And Icon Actions
+
+```tsx
+<div className="flex items-center gap-2">
+  <Input className="h-7" />
+  <Button variant="outline" size="icon" aria-label={t(browseLabelKey)}>
+    <Icon name="folder" className="size-4" />
+  </Button>
+</div>
+```
+
+- Prefer compact inputs in dense rows.
+- Avoid large select triggers in Settings.
+- Use shared `Button` and sprite `Icon`, never wrapper buttons or direct Remixicon imports.
+
+## Mobile Constraints
+
+- `packages/ui/src/styles/mobile.css` may force `.overflow-hidden` to scroll; use explicit x/y clipping only when required.
+- Touch CSS enforces minimum button height. Do not put custom segmented buttons in a container too short for them.
+
+## Picker Rows
+
+- Place icon/color palettes beneath their label.
+- Keep option dimensions and gaps consistent.
+- Use stable border/ring/background selection; avoid scale transforms that shift layout.
@@ -0,0 +1,53 @@
+# Settings Layout
+
+## Visual Hierarchy
+
+- Prefer spacing and typography over boxed backgrounds.
+- Avoid wrappers that mix unrelated controls.
+- Omit redundant headings when page context already names the controls.
+- Keep controls compact and row chrome minimal.
+- Place checkbox/radio state before its label.
+- Dim inactive option labels subtly; do not use transform jumps.
+
+## Typography
+
+Use classes from `packages/ui/src/lib/typography.ts`:
+
+- Page title: `typography-ui-header font-semibold text-foreground`
+- Section header: `typography-ui-header font-medium text-foreground`
+- Control group: `typography-ui-header font-medium` or `font-normal` when needed
+- Values/labels: `typography-ui-label text-foreground`
+- Helper/meta: `typography-meta text-muted-foreground` or `typography-small text-muted-foreground`
+- Numeric values: add `tabular-nums`
+
+## Spacing
+
+- Keep section-to-section spacing larger than header-to-content spacing.
+- Typical flat section: header `mb-1 px-1`, content `pt-0 pb-2 px-2`, outer `mb-8`.
+- Group related controls with `space-y-3` and modest internal padding such as `p-2`.
+- Avoid elevated backgrounds, rounded rows, and hover fills without explicit UX value.
+
+## Alignment
+
+For consistent desktop columns:
+
+```tsx
+<div className="flex items-center gap-8 py-1.5">
+  <span className="w-56 shrink-0 typography-ui-label">{t(labelKey)}</span>
+  <div className="flex w-fit items-center gap-2">...</div>
+</div>
+```
+
+- Let narrow layouts stack or wrap.
+- Compare the complete control footprint, including adjacent actions, when matching widths.
+- Disable only the unavailable control; do not dim the entire label row by default.
+
+## Responsive Grids
+
+Use a one-column base and introduce columns at a deliberate breakpoint:
+
+```tsx
+<div className="grid grid-cols-1 gap-2 md:grid-cols-[14rem_auto] md:gap-x-8" />
+```
+
+Template fields commonly use `grid grid-cols-1 gap-2 md:grid-cols-2 md:gap-3` with flat `p-2` cells.
@@ -0,0 +1,42 @@
+# Settings Search
+
+Settings search uses an explicit registry; it does not scrape JSX.
+
+## Required Integration
+
+- Add/update items in `packages/ui/src/lib/settings/search.ts`.
+- Add a matching `data-settings-item="..."` anchor to the rendered setting.
+- Use localized labels/descriptions from every `packages/ui/src/lib/i18n/messages/*.settings.ts` dictionary.
+- For a new top-level page, add metadata in `packages/ui/src/lib/settings/metadata.ts` and searchable content unless the page is purely navigational.
+
+## Registry Rules
+
+- Index stable controls, section headers, and static create/connect actions.
+- Use IDs matching page and target, such as `appearance.language`.
+- Prefer the visible label key as `titleKey`.
+- Add `descriptionKey` only when it improves context.
+- Add useful synonyms/acronyms as keywords.
+- Do not generate items for dynamic entities such as individual agents, providers, projects, skills, hosts, or sessions.
+
+## Conditional Targets
+
+- Do not index a target hidden behind selected-entity state unless search selection prepares that state first.
+- Keep item `isAvailable` identical to actual render visibility.
+- Put page-level availability in `metadata.ts` and item-specific guards in `search.ts`.
+- Distinguish desktop shell from local desktop origin when the feature requires local privileges.
+- For split pages, index predictable static surfaces and update `prepareSettingsSearchTarget` when a result must open a draft/editor before highlighting.
+
+## Highlight Anchor
+
+- Put `data-settings-item` on the smallest stable container that visually owns the setting.
+- Do not add layout-only wrappers solely for search.
+- Keep highlight styling token-based and subtle; it lives under `[data-settings-search-highlight="true"]` in `packages/ui/src/index.css`.
+
+## Audit
+
+- Every registry ID has a matching anchor.
+- Every title/description key exists in every Settings locale.
+- Every non-navigational page has appropriate coverage.
+- Search visibility matches platform/runtime/mobile rendering.
+- Conditional state is prepared before highlight.
+- Empty-query Settings navigation remains unchanged.