Adom UI Design System

@@ -0,0 +1,111 @@+---+name: settings-layout+user-invocable: true+description: >-+  The Adom settings surface: how ah (Adom Hydrogen) lays out its Settings, and how every other+  Adom app's settings dialog should mimic it. Covers the two variants (full settings PAGE with+  sidebar outline, and compact settings MODAL for a panel), the settings-card anatomy (elevated+  card, 3px teal left accent, title with inline status, descriptive prose paragraph, control rows,+  dividers), the descriptive-copy doctrine (every section EXPLAINS itself in full sentences, e.g.+  naming the exact hooks it installs), Install/Update/Uninstall row patterns with live consoles,+  and the modal mechanics (portal to body, viewport clamp, draggable header, Escape/click-outside).+  Read BEFORE building any settings dialog, preferences pane, or config UI in an Adom app.+  Trigger words: settings dialog, settings modal, settings layout, preferences pane, config ui,+  settings card, options dialog, app settings, settings panel, mimic ah settings.+---++Parent skill: **adom-ui-design**++# Settings layout - the ah settings surface, reusable++**The doctrine (John, 2026-08-17, verbatim):** "can you make the settings dialog more+descriptive the way the settings is for ah? and make it look similar? in particular i want you+to explain which hooks you hook into." A settings surface in Adom is not a terse grid of+switches. Every section is a CARD that teaches: what this group of controls does, how it works+underneath, and exactly what pressing each button will change. If a section installs hooks, it+NAMES the hooks. If a toggle filters a view, it says what hides and what survives.++Reference implementations (both live in adom/hydrogen-desktop):+- FULL PAGE: `src/lib/components/editor/settings/SettingsPanel.svelte` (sidebar outline ++  sectioned cards + footer).+- COMPACT MODAL: the AI Threads panel settings in+  `src/lib/components/editor/panels/PanelAiThreads.svelte` (560px portal modal, three cards).++## Pick the variant++- **Full settings page** (an app's main Settings): left sidebar OUTLINE (section list, click+  scrolls; active section highlighted) + scrolling editor column of cards + a footer note+  ("Settings are stored on this machine...") with a Restore-defaults button.+- **Compact settings modal** (a panel or widget's own settings): a single centered modal,+  width ~560px, max-height 70vh with internal scroll, stacked cards. No sidebar.++## The settings-card (the atom both variants share)++```css+.settings-card {+  background: var(--elevated, #1c2128);+  border: 1px solid var(--border, #30363d);+  border-left: 3px solid color-mix(in srgb, var(--accent, #00b8b1) 45%, transparent);+  border-radius: 10px;+  padding: 0.9rem 1.1rem 1rem;+  margin-bottom: 1rem;+}+.card-title    { font-size: 13px; font-weight: 600; display: flex; align-items: center; gap: 10px; }+.card-status   { font-size: 11px; color: var(--text-2, #8b949e); font-weight: 400; }  /* inline in the title */+.card-status.ok{ color: #3fb950; }+.card-desc     { font-size: 12px; line-height: 1.55; color: var(--text-2, #8b949e); }+.card-desc code{ font-size: 11px; background: rgba(110,118,129,0.2); padding: 1px 4px; border-radius: 4px; }+.divider       { height: 1px; background: var(--border); margin: 0.55rem 0; }+```++Anatomy, in order, inside every card:+1. **Title row**: the section name, plus LIVE STATUS inline ("active", "not installed",+   "v0.147.0") in `.card-status` - green when good. Status is recomputed truth, never a cached+   claim.+2. **Descriptive paragraph(s)**: full sentences explaining what this section does and HOW.+   The ah hooks card names each hook it installs (SessionStart, UserPromptSubmit, Stop,+   Notification) with a one-line plain-language consequence for each, states the safety+   contract ("a 2-second-capped HTTP post that can never block or fail Claude itself"), and+   the honest caveat ("threads already running when the hook installs will not report until+   restarted"). That is the bar.+3. **Control rows**: label + control + inline status + action buttons, one row per control,+   dividers between them. Checkbox labels are the human name ("Claude Code"), not the key.+4. **Consequence honesty**: a control that does nothing yet says so; a destructive button is+   visually distinct (red text/border) and never offered on things that must not be removed.++## Rows with lifecycle actions (Install / Update / Uninstall)++The ah Monitored-AIs pattern: `[checkbox + name] [status: version or "not installed"]+[Install|Update] [Uninstall?] [Details toggle]`.+- The button LABEL reflects state: Install when absent, Update when present. Never show+  "installed" next to a button that says Install.+- Uninstall is a danger-styled secondary button, only where removal is legitimate.+- Long-running actions stream a LIVE CONSOLE under the row (dark monospace box, real command+  output line by line, exit code, then a verify line proving the result). Silent multi-minute+  buttons are forbidden.+- An expandable "Details" per row for deep diagnostics (paths, versions, folders, checks with+  green/red marks) keeps the header row compact.++## Modal mechanics (compact variant)++- **Portal the modal to document.body.** Panels live inside transformed ancestors;+  position:fixed resolves against the transform and the modal renders invisibly clipped+  (ah shipped this bug; the portal is the fix). Clamp within the viewport.+- Draggable by its header; close via the X, Escape, and click-outside; title row is+  "<Thing> Settings".+- Overlay dims the app behind; the modal owns scroll (max-height ~70vh).++## Copy rules++- Full sentences, present tense, second person where natural. No em-dashes ever (Adom rule).+- Explain the MECHANISM, not just the setting ("a cheap signature check on the interval below,+  and a full re-census only when the tab layout changes").+- State honest limitations inline, not in docs nobody reads.++## Input feedback + testing++Every button, checkbox, toggle and row follows the **input-feedback** sub-skill (hover+acknowledgment, instant :active press, :focus-visible ring). Ralph-test the surface per the+adom-ui-design loop: open it for real, screenshot, READ the pixels (a modal that "opened" but+rendered clipped passes APIs and fails humans), and verify every status string against ground+truth before shipping.