11 KiB
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.01emletter-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
Deploybutton (green, GitHub-style primary) and a quietLog outghost button when auth is enabled.
Main column
max-width: 960pxcentered, 1.5rem horizontal padding.- Global Options panel — surface card with a header strip
(
Global Optionstitle + a small grey badge counting non-blank, non-comment lines, e.g.2 directives). Body holds the highlighted editor. - Sites section — section title
Siteswith a+ Add siteghost button on the right, then a vertical list of site cards.
Site card
- Collapsed: chevron, address (mono,
--accentcolor), a one-line summary chip (→ host:portif the body has areverse_proxyline, elseN directives), and aRemoveghost-danger button visible on hover. - Expanded: address bar, the highlighted editor, and any
upstream-warningsrendering 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
inputandscroll: readtextarea.value, runtokenize(), write<pre>.innerHTML, copyscrollTop/scrollLeftfrom 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:
- Leading whitespace — preserved as-is.
- Comment —
#to end of line. - String —
"…"and'…'(escape-aware:\\and\"). - Placeholder —
\{[^{}\n]*\}matching{$VAR},{http.…},{args.0}, etc. Bare{or}outside this pattern fall through to the brace rule. - Brace — lone
{or}. - Number —
:\d+(port-like) and standalone integers. - Directive — first non-whitespace word of the line, only if it's in the known directive list.
- 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_adminresult and to deploy state. - Site card summary chip (collapsed only): scan the body for the first
reverse_proxyline and show→ host:port(truncated to ~28 chars). If none, showN directives(non-blank, non-comment lines). Updated on every collapse and onchangeof 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+StriggerspreDeploy(). ListenerpreventDefaults 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 atitlehint. - Disabled state when admin API is unreachable: existing logic, plus a
visual change — disabled inputs get
0.5opacity 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): addsmountEditor(),tokenize(),summaryFor(),directiveCount(),armRemove(), and a global keyboard-shortcut listener. UpdatesrenderSites()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 fromtextarea.valueon everyinputandscroll. Identical font metrics + a trailing-newline trick handle the last-line case. removeSitetwo-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+Scapture could surprise users in a textarea. Mitigated by onlypreventDefaulting 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
- Load with the existing Caddyfile — global + sites populate correctly, highlighting renders for both editors.
- Edit each editor — highlight tracks input, scroll syncs, Tab indents without focus loss, paste of multi-line content highlights correctly.
- Flip OS theme dark↔light — every screen (auth, main, modal, toast, disabled state) re-themes without a reload.
- Add site, remove site (verify 2-click confirm), collapse/expand cards, summary chip updates after edits.
- Deploy success → green pill + green toast. Deploy with bad config → red pill + error toast with Caddy's message.
- Stop the Caddy admin API → reload page → unreachable disabled state renders, deploy button disabled, status pill red with reason.
Cmd/Ctrl+Striggers deploy when admin is reachable; does nothing when disabled.- Setup screen (scratch container with
/data/.authremoved) and login screen both look right in both color schemes.