Files
KonCad/docs/superpowers/specs/2026-04-27-koncad-ui-redesign-design.md
T
Daniel e9035bf6fe
Publish Docker image / build (push) Failing after 6s
Improve Caddyfile editor for demo-style configs
2026-05-03 18:59:32 +02:00

11 KiB
Raw Blame History

KonCad UI redesign — design

Refresh the KonCad web UI with a "Soft Slate" visual style (GitHub / Notion-dark inspired), light/dark via prefers-color-scheme, lightweight inline syntax highlighting for the Caddyfile editors, and a handful of small UX wins. No backend changes; same single-file PHP structure.

Goals

  • A modern, calm, information-dense look that fits a homelab tool you open occasionally.
  • Auto-respect the OS color-scheme preference (no manual toggle).
  • Make the Caddyfile editors readable at a glance with simple syntax colors.
  • Add a small set of polish improvements that the new look invites — without changing what the app does or its data flow.

Non-goals

  • No changes to PHP backend logic (parser, save handler, upstream check, auth model).
  • No new dependencies. Stays a single-file PHP tool — no CDN, no build step.
  • No structural rework — header / global panel / list of sites stays.
  • No new features (no draft staging, no diff view, no per-directive forms, no bulk site operations, no manual theme toggle).
  • No editor features beyond highlighting (no line numbers, no bracket matching, no autocomplete).

Visual system

CSS custom properties on :root for dark, overridden inside @media (prefers-color-scheme: light). Both auth screens and the main page use the same token set.

Token Dark Light Used for
--bg #0d1117 #f6f8fa page background
--surface #161b22 #ffffff panels, cards
--surface-2 #0d1117 #f6f8fa editor / nested surfaces
--border #21262d #d0d7de every divider
--text #e6edf3 #1f2328 primary text
--muted #7d8590 #656d76 labels, subtle text
--accent #58a6ff #0969da links, focus, addresses
--accent-bg rgba(88,166,255,0.12) rgba(9,105,218,0.1) accent backgrounds, focus ring
--ok #3fb950 #1a7f37 success status
--warn #d29922 #9a6700 warnings
--error #f85149 #cf222e errors

Type: Inter via system stack (-apple-system, "Segoe UI", "Inter", system-ui, sans-serif); JetBrains Mono for code (with monospace fallback). Sizes: 13px base, 12px secondary, 11px labels/badges.

Geometry: 8px radius on inputs/buttons, 10px on panels. 1px borders throughout — no drop shadows. Focus ring: 0 0 0 3px var(--accent-bg) on inputs and buttons. Spacing on a 4px grid.

Layout

Same three regions as today.

Header (sticky)

  • Left: a small (18×18) gradient square logo mark + "KonCad" word in 700 weight, -0.01em letter-spacing.
  • Center: a status pill — ● Caddy ready (green) on success, ● Caddy unreachable (red) when the admin API is down, ● Deploying… (amber, with a 1.4s pulse animation) during a deploy. Pill background uses a tinted version of its color.
  • Right: primary Deploy button (green, GitHub-style primary) and a quiet Log out ghost button when auth is enabled.

Main column

  • max-width: 960px centered, 1.5rem horizontal padding.
  • Global Options panel — surface card with a header strip (Global Options title + a small grey badge counting non-blank, non-comment lines, e.g. 2 directives). Body holds the highlighted editor.
  • Sites section — section title Sites with a + Add site ghost button on the right, then a vertical list of site cards.

Site card

  • Collapsed: chevron, address (mono, --accent color), a one-line summary chip (→ host:port if the body has a reverse_proxy line, else N directives), and a Remove ghost-danger button visible on hover.
  • Expanded: address bar, the highlighted editor, and any upstream-warnings rendering area (existing slot, restyled).

Empty state for sites

A dashed-border placeholder card replacing the current grey one-liner: small icon (⊕ or similar), heading No sites yet, and an inline primary + Add site button.

Auth screens (setup / login)

Same centered-card pattern, retoned to the new tokens. Logo mark + "KonCad" header, subtitle (Create your login credentials / Sign in to continue), form with one username + one password input and a primary submit button. Inline error message uses --error.

Modals & toasts

  • Upstream warning modal: same content, retoned. Dark-mode backdrop gets backdrop-filter: blur(4px).
  • Toasts: same triggers, restyled. Slide in with transform: translateY(8px) → 0, fade. Auto-dismiss at 5s (unchanged).

Highlighted editor

Textarea-overlay technique. Native cursor, undo, IME, copy/paste behavior is preserved; the highlighted layer is purely decorative.

Markup per editor

<div class="editor-wrap">
  <pre class="editor-hl" aria-hidden="true"></pre>
  <textarea class="editor-input" spellcheck="false">…</textarea>
</div>

Mechanics

  • <pre> and <textarea> are absolutely positioned in the same box, share identical font, font-size, line-height, padding, border, and box-sizing.
  • Textarea has color: transparent; caret-color: var(--text) so the user sees the painted <pre> text and a real caret.
  • On every input and scroll: read textarea.value, run tokenize(), write <pre>.innerHTML, copy scrollTop/scrollLeft from textarea to <pre>.
  • A trailing newline is appended before tokenizing so the last line renders.

Tokenizer

Pure-JS, regex-based, ~60 LOC. Tokenization runs per-line, in this priority order so earlier rules win:

  1. Leading whitespace — preserved as-is.
  2. Comment — # to end of line.
  3. String — "…" and '…' (escape-aware: \\ and \").
  4. Placeholder — \{[^{}\n]*\} matching {$VAR}, {http.…}, {args.0}, etc. Bare { or } outside this pattern fall through to the brace rule.
  5. Brace — lone { or }.
  6. Number — :\d+ (port-like) and standalone integers.
  7. Directive — first non-whitespace word of the line, only if it's in the known directive list.
  8. Default — any other character class falls through to plain text.

Known directives (initial list): reverse_proxy, root, file_server, encode, tls, header, redir, respond, route, handle, handle_path, import, log, email, admin, auto_https, php_fastcgi, basicauth, try_files, rewrite, uri, request_body, templates, map, metrics, acme_dns, acme_ca. Easy to extend later by appending to the list.

Token classes & colors

Class Dark Light
c comment #7d8590 #6e7781
d directive #ff7b72 #cf222e
s string #a5d6ff #0a3069
p placeholder #d2a8ff #8250df
n number #79c0ff #0550ae
b brace #7d8590 #6e7781

These live as CSS variables (--tok-c, --tok-d, …) under both the dark and light blocks.

Tab handling

Existing handleTab() behavior preserved (Tab inserts 4 spaces, no focus-jump). The overlay re-tokenizes on the resulting input event.

Scope

The two existing editor types — global options + each site body. Both render through a single mountEditor(textarea) helper. No line numbers, no bracket matching, no autocomplete.

Small UX polish

  • Header status pill wired to the existing check_admin result and to deploy state.
  • Site card summary chip (collapsed only): scan the body for the first reverse_proxy line and show → host:port (truncated to ~28 chars). If none, show N directives (non-blank, non-comment lines). Updated on every collapse and on change of the textarea.
  • Directive count badge on the Global Options header: count of non-blank, non-comment lines. Updated on input, debounced 200ms.
  • Remove site → 1-step inline confirm: first click flips the button into a red Confirm remove? for ~3 seconds; second click within that window deletes. Click outside / 3s timeout reverts.
  • Deploy keyboard shortcut: Cmd/Ctrl+S triggers preDeploy(). Listener preventDefaults only when focus is inside the app (any element under <main> or <header>), not globally — and only when the deploy button is enabled. Button gets a title hint.
  • Disabled state when admin API is unreachable: existing logic, plus a visual change — disabled inputs get 0.5 opacity and a subtle striped background (repeating-linear-gradient). The status pill shows the reason text.

Files touched

  • app/index.php — only file modified.

Sections being rewritten

  • Auth-page HTML + <style> (currently lines ~239–275): retoned to the new tokens, same form fields and POST behavior.
  • Main page <style> block (currently lines ~282–550): replaced.
  • Main page HTML (currently lines ~552–600): minor structural tweaks for the status pill, summary chip, badge, empty state.
  • <script> (currently lines ~602–886): adds mountEditor(), tokenize(), summaryFor(), directiveCount(), armRemove(), and a global keyboard-shortcut listener. Updates renderSites() to emit the new markup. All other functions unchanged.

Untouched

  • All PHP above the auth-page HTML (config, session/auth, helpers, parser, caddyLoad, checkUpstream, every ?action=… handler).
  • Existing JS: init(), preDeploy(), doDeploy(), extractUpstreams(), collectSites(), addSite(), removeSite() core, togglePanel(), toggleSite(), setEditable(), setStatus(), setDeployBtn(), toast(), esc(), logout(), handleTab(). All keep their current signatures and behavior.

Risks & mitigations

  • Overlay desync (highlighted layer drifting from textarea on paste, IME, resize, or scroll): the textarea remains the source of truth; the <pre> is rebuilt from textarea.value on every input and scroll. Identical font metrics + a trailing-newline trick handle the last-line case.
  • removeSite two-click is a behavior change. Acceptable: deleting a configured site has a real blast radius, and a 3s armed window is friction light.
  • Global Cmd/Ctrl+S capture could surprise users in a textarea. Mitigated by only preventDefaulting when the deploy button is enabled and focus is inside the app shell.
  • Light-mode regression: every color must come from a token — no hex literals in component CSS. Manual test: flip OS theme and confirm both palettes render correctly on every screen (auth, main, modal, toast, disabled state).

Manual test plan

  1. Load with the existing Caddyfile — global + sites populate correctly, highlighting renders for both editors.
  2. Edit each editor — highlight tracks input, scroll syncs, Tab indents without focus loss, paste of multi-line content highlights correctly.
  3. Flip OS theme dark↔light — every screen (auth, main, modal, toast, disabled state) re-themes without a reload.
  4. Add site, remove site (verify 2-click confirm), collapse/expand cards, summary chip updates after edits.
  5. Deploy success → green pill + green toast. Deploy with bad config → red pill + error toast with Caddy's message.
  6. Stop the Caddy admin API → reload page → unreachable disabled state renders, deploy button disabled, status pill red with reason.
  7. Cmd/Ctrl+S triggers deploy when admin is reachable; does nothing when disabled.
  8. Setup screen (scratch container with /data/.auth removed) and login screen both look right in both color schemes.