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

265 lines
11 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
<!-- Edited with Claude Code -->
# 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
```html
<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
`preventDefault`s 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 `preventDefault`ing 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.