mirror of
https://github.com/kbenestad/reimburse.git
synced 2026-06-18 08:04:31 +00:00
Add design brief for kBenestad web apps
This document serves as a design brief for kBenestad web apps, outlining visual guidelines, typography, color tokens, and UI components.
This commit is contained in:
GitHub
parent
fde406475e
commit
696a19b142
1 changed files with 339 additions and 0 deletions
339
DESIGN.md
Normal file
339
DESIGN.md
Normal file
|
|
@ -0,0 +1,339 @@
|
||||||
|
# kBenestad — app UI brief
|
||||||
|
|
||||||
|
**Drop this into a project's `CLAUDE.md` (or paste it to Claude Code) whenever you build or
|
||||||
|
restyle a kBenestad web app.** It is the shared visual contract: follow it and any new
|
||||||
|
screen — invoice, timesheet, reimburse, a dashboard, a settings page — will look like it
|
||||||
|
belongs to the same family.
|
||||||
|
|
||||||
|
This brief tells you *how things should look and behave*. It does **not** redefine what an
|
||||||
|
app does. Keep each app's existing purpose, data model, and screens intact — only the
|
||||||
|
surface (layout, type, colour, components, copy) is governed here.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 0. The one-paragraph version
|
||||||
|
|
||||||
|
Nordic-minimal, light-first, calm. A cool off-white page, pure-white cards held by 1px
|
||||||
|
hairline borders, near-black cool ink, and **one** blue accent (`#2f6fed`). Schibsted
|
||||||
|
Grotesk for everything; JetBrains Mono only for numbers, code, and identifiers. 4px
|
||||||
|
spacing grid, small deliberate radii (8px workhorse), soft shadows used sparingly. No
|
||||||
|
gradients, no emoji, no bounce. Sentence case. Borders do the structural work; shadow only
|
||||||
|
when something genuinely floats. Categorical data is coloured with a muted, config-driven
|
||||||
|
palette (chip + left border + optional row tint), never neon.
|
||||||
|
|
||||||
|
If you only remember five rules:
|
||||||
|
1. **One accent.** Blue is the only brand colour. Semantic hues are muted and earn their place.
|
||||||
|
2. **Borders first, shadow last.** Most surfaces have no shadow.
|
||||||
|
3. **Forms are row-major** (see §6). Never lay a form out as side-by-side column stacks.
|
||||||
|
4. **Sentence case, no emoji, mono for numbers.**
|
||||||
|
5. **Colour-code categories** with the chip / border / tint system in §8 — muted, from data.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 1. Setup — wire in the design system
|
||||||
|
|
||||||
|
All tokens are CSS custom properties. Pull them in once, then reference `var(--token)`
|
||||||
|
everywhere. The canonical source is the kBenestad design system's `styles.css` closure
|
||||||
|
(`tokens/colors.css`, `typography.css`, `spacing.css`, `elevation.css`, `fonts.css`,
|
||||||
|
`base.css`). Copy those into the app and `@import` them from a single stylesheet, or copy
|
||||||
|
the token blocks inline.
|
||||||
|
|
||||||
|
**Fonts** — Schibsted Grotesk (400–800) + JetBrains Mono (400–600). Load from a webfont host
|
||||||
|
with a `local()` first and a full system fallback stack so the app still renders offline:
|
||||||
|
|
||||||
|
```css
|
||||||
|
--font-sans: 'Schibsted Grotesk', -apple-system, BlinkMacSystemFont, 'Segoe UI', system-ui, sans-serif;
|
||||||
|
--font-mono: 'JetBrains Mono', ui-monospace, 'SFMono-Regular', Menlo, Consolas, monospace;
|
||||||
|
```
|
||||||
|
|
||||||
|
**Dark mode** — support both. Honour the OS by default and allow a manual override:
|
||||||
|
`@media (prefers-color-scheme: dark)` *and* `:root[data-theme="dark"]` both flip the same
|
||||||
|
tokens. Never hardcode a hex that won't invert — always go through a semantic token.
|
||||||
|
|
||||||
|
**For form-driven apps specifically:** `mockups/kbenestad-forms.css` is a finished,
|
||||||
|
proven component layer (the `.kb-*` classes used below) built on exactly these tokens. Lift
|
||||||
|
it wholesale rather than rebuilding inputs/cards/buttons from scratch.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 2. Colour tokens
|
||||||
|
|
||||||
|
Reference the **semantic aliases**, not the raw ramps. The raw ramps exist so the aliases
|
||||||
|
have something to point at; your code should almost never name a `--blue-500` directly.
|
||||||
|
|
||||||
|
**Surfaces** — `--surface-page` (cool off-white ground), `--surface-card` (pure white),
|
||||||
|
`--surface-sunken`, `--surface-raised`, `--surface-hover`, `--surface-active`,
|
||||||
|
`--surface-inverse`.
|
||||||
|
|
||||||
|
**Borders** — `--border-subtle` (hairline, default for cards), `--border-default`
|
||||||
|
(dividers), `--border-strong` (emphasis), `--border-focus`.
|
||||||
|
|
||||||
|
**Text** — `--text-strong` (headings/primary ink), `--text-body`, `--text-muted`,
|
||||||
|
`--text-subtle`, `--text-inverse`, `--text-accent`, `--text-link`.
|
||||||
|
|
||||||
|
**Accent / interactive** — `--accent` (`#2f6fed`), `--accent-hover`, `--accent-active`,
|
||||||
|
`--accent-soft` (pale blue fill), `--accent-soft-text`, `--accent-fg` (text on accent).
|
||||||
|
|
||||||
|
**Semantic feedback (muted, never neon)** — `--success` / `--success-soft`,
|
||||||
|
`--warning` / `--warning-soft`, `--danger` / `--danger-soft` / `--danger-fg`. Use the soft
|
||||||
|
variants as fills, the solid as border/text.
|
||||||
|
|
||||||
|
**Focus** — `--focus-ring` (a 3px soft-blue ring). Always visible via `:focus-visible`.
|
||||||
|
|
||||||
|
**Terminal** (CLI / gitxt only) — `--term-bg`, `--term-fg`, `--term-dim`, `--term-accent`,
|
||||||
|
`--term-green`, `--term-amber`. Don't use these in normal app UI.
|
||||||
|
|
||||||
|
> Light values you'll see most: page `#f8f9fb`, card `#ffffff`, hairline `#e7eaef`, ink
|
||||||
|
> `#14181e`, accent `#2f6fed` / hover `#1f57cf`. Dark inverts onto `#0d1117` page /
|
||||||
|
> `#161b22` card with a lighter accent for contrast.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 3. Typography
|
||||||
|
|
||||||
|
- **Families:** `--font-sans` everywhere; `--font-mono` **only** for numbers, code, paths,
|
||||||
|
package/identifier names, and tabular figures. When showing money, durations, counts,
|
||||||
|
versions, IDs — mono + `font-variant-numeric: tabular-nums`.
|
||||||
|
- **Scale:** `--text-display` 52px (splash only), `--text-h1` 36, `--text-h2` 28,
|
||||||
|
`--text-h3` 22, `--text-h4` 18, `--text-body-lg` 17, `--text-body` 15 (UI default),
|
||||||
|
`--text-body-sm` 13, `--text-caption` 12, `--text-mono` 14.
|
||||||
|
- **Weights:** 400 body, 500 medium, 600 semibold (labels/buttons), 700 headings, 800
|
||||||
|
reserved for the wordmark/splash.
|
||||||
|
- **Leading:** `--leading-normal` 1.5 for body; `--leading-tight` 1.1 for big display.
|
||||||
|
- **Tracking:** `--tracking-tight` (−0.02em) on display/headings; `--tracking-caps`
|
||||||
|
(+0.08em) on uppercase eyebrow/overline labels.
|
||||||
|
- **Eyebrow labels** (field labels, table headers, section kickers): 12px, uppercase,
|
||||||
|
`--tracking-caps`, `--text-muted`, weight 600. This is the recurring small-label motif.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 4. Spacing, shape, elevation, motion
|
||||||
|
|
||||||
|
- **Spacing:** 4px base grid via `--space-1`…`--space-16` (4, 8, 12, 16, 24, 32, 40, 48, 64,
|
||||||
|
96, 128). Card padding ~24px (`--space-5`). Comfortable, not airy.
|
||||||
|
- **Radii:** `--radius-xs` 3, `--radius-sm` 5 (small controls), `--radius-md` 8 (the
|
||||||
|
workhorse), `--radius-lg` 12 / `--radius-xl` 16 (cards), `--radius-full` (pills/badges
|
||||||
|
only). **Not bubbly** — never round a card more than 16px.
|
||||||
|
- **Borders:** `--border-thin` 1px (default hairline), `--border-medium` 1.5px (emphasis /
|
||||||
|
selection). Borders carry the structure.
|
||||||
|
- **Elevation:** most surfaces have **no** shadow. `--shadow-md` for menus and hover-lift,
|
||||||
|
`--shadow-lg` / `--shadow-xl` for dialogs and popovers. Shadows are soft, cool-tinted,
|
||||||
|
low-opacity. Never use shadow as decoration.
|
||||||
|
- **Containers:** cap content at `--container-lg` 1080px (forms/docs) to `--container-xl`
|
||||||
|
1280px (dashboards). Left-aligned, single-column-leaning.
|
||||||
|
- **Motion:** 120–280ms (`--duration-fast/base/slow`), `--ease-out`
|
||||||
|
`cubic-bezier(.22,.61,.36,1)`. Fades and ≤2px translations only. **No bounce, no spring.**
|
||||||
|
Honour `prefers-reduced-motion`.
|
||||||
|
- **Hover/press:** filled elements step one shade darker (`--accent-hover`); ghost/secondary
|
||||||
|
get a faint surface tint. Press adds a 0.5px downward nudge. Disabled ≈ 45% opacity, no
|
||||||
|
pointer events.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 5. Voice & copy
|
||||||
|
|
||||||
|
The voice is understated, precise, practical. These are working tools, not marketing pages.
|
||||||
|
|
||||||
|
- **Sentence case everywhere** — buttons, headings, menu items ("View source", "Add row",
|
||||||
|
not Title Case). UPPERCASE only for small tracked-out eyebrow labels.
|
||||||
|
- **Calm and direct.** Short sentences. Say what a thing does, then stop. No hype
|
||||||
|
("seamless", "blazing-fast"), no exclamation marks.
|
||||||
|
- **Imperative, concrete verbs** for actions: *Add line*, *Generate*, *Validate*, *Export*,
|
||||||
|
*Remove*, *Publish*.
|
||||||
|
- **Numbers & identifiers are exact and mono:** `v2.4.0`, `12 kB`, `8.0 h`, `3 items`.
|
||||||
|
- **No emoji, ever.** Status is a coloured dot, a Lucide icon, or a tinted chip.
|
||||||
|
- **Errors & empty states are honest and helpful** — what happened, then the next step:
|
||||||
|
"Time out must be after time in." / "No expenses yet — add your first line to begin."
|
||||||
|
- **Speak to the user as "you"**; the maker is "I/me". Avoid corporate "we".
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 6. Form-driven UIs (invoice, timesheet, reimburse, settings, anything with inputs)
|
||||||
|
|
||||||
|
These apps are the core of the family. The rules below are what make them feel unified.
|
||||||
|
|
||||||
|
### 6.1 Page shell
|
||||||
|
A centred column (`--container-lg` or narrower), `--surface-page` ground, content in
|
||||||
|
`--surface-card` cards with `--border-subtle` and at most `--shadow-sm`. Optional top
|
||||||
|
**utility bar** (language toggle, text-size A−/A/A+, About) as small segmented controls;
|
||||||
|
then a **document header** where the *customer's* identity leads (logo tile + org name on
|
||||||
|
the left, document title + period on the right). kBenestad is the quiet signature in the
|
||||||
|
footer, never the headline.
|
||||||
|
|
||||||
|
### 6.2 Forms are ROW-MAJOR — this is the load-bearing rule
|
||||||
|
Group fields into **rows**; never build a form as two independent side-by-side column
|
||||||
|
stacks. Each row is a **top-aligned CSS grid**. When one field grows — a hint appears, a
|
||||||
|
validation message shows, an explanation expands — **the whole row grows and the rows below
|
||||||
|
push down**, while the field beside it stays aligned to the top. This keeps labels and
|
||||||
|
controls in register no matter what expands.
|
||||||
|
|
||||||
|
- Use a `.kb-form` / row container with span helpers (`kb-col-2`, `kb-col-3`, `kb-col-full`)
|
||||||
|
to control how many columns a field occupies within its row.
|
||||||
|
- Label above field. Label = eyebrow style (12px, uppercase, tracked, `--text-muted`, 600).
|
||||||
|
- One thought per row; don't cram unrelated fields together to save vertical space.
|
||||||
|
|
||||||
|
### 6.3 Inputs
|
||||||
|
1px `--border-strong` border, `--radius-sm`, ~9–11px padding, 15px text. Focus =
|
||||||
|
`--accent` border + `--focus-ring`. Disabled/readonly = `--surface-sunken` fill, muted
|
||||||
|
text, `not-allowed`. Numeric inputs: mono, right-aligned, tabular-nums. Selects get a custom
|
||||||
|
chevron. Error state = `--danger` border; warning = `--warning` border (optional soft fill).
|
||||||
|
|
||||||
|
### 6.4 Buttons
|
||||||
|
- **Primary:** filled `--accent`, `--accent-fg` text → hover `--accent-hover`.
|
||||||
|
- **Ghost/secondary:** white surface, `--border-strong` → hover accent border + accent text.
|
||||||
|
- **Soft:** `--accent-soft` fill, accent text.
|
||||||
|
- **Dashed:** transparent + dashed accent border — the "add another" affordance.
|
||||||
|
- **Round add/remove:** 24px circle, `+` (accent) / `−` (danger) — for line-item rows.
|
||||||
|
- Disabled ≈ 50% opacity. Icons (Lucide, 16px) sit left of the label with a small gap.
|
||||||
|
|
||||||
|
### 6.5 Line items / repeating rows
|
||||||
|
A header row of eyebrow labels, then data rows on a matching grid. Row hover gets a faint
|
||||||
|
`--surface-hover`. A left-border slot (`border-left: 3px solid transparent`) is reserved so
|
||||||
|
rows can be colour-coded (see §8). Trailing add/remove circle buttons. Subtotals and the
|
||||||
|
running total use mono tabular figures.
|
||||||
|
|
||||||
|
### 6.6 Totals panel
|
||||||
|
Right-aligned, ~380px. Rows of `label … value` (value mono, tabular). A `grand` row on top
|
||||||
|
of a `--border-strong` rule, bold, with the figure in `--accent` at ~20px. Notes/derived
|
||||||
|
explanations below in muted small text.
|
||||||
|
|
||||||
|
### 6.7 Validation & feedback (notes / banners)
|
||||||
|
A tinted note block: icon + text, `--*-soft` background with matching `--*-border` and text
|
||||||
|
colour. Four kinds: error (`--danger`), warning (`--warning`), success (`--success`), info
|
||||||
|
(`--accent`/info). Blocking errors disable the primary action; warnings don't. Mirror
|
||||||
|
issues inline: tint the offending field's border and show the message next to its row. Keep
|
||||||
|
messages specific ("Description is required for OTH rows").
|
||||||
|
|
||||||
|
### 6.8 Config-driven & white-label
|
||||||
|
Wherever an app has a `config.yml` (org name, logo, accent colour, codes, categories,
|
||||||
|
holidays, UI strings, language), **drive the UI from it** — don't hardcode. The accent is a
|
||||||
|
single recolourable token so a customer brand can replace the kBenestad blue without
|
||||||
|
touching anything else. Strings come from the config's i18n map; support the configured
|
||||||
|
languages.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 7. Dashboards & data-dense screens
|
||||||
|
|
||||||
|
Dashboards use the same DNA, just wider (`--container-xl` 1280px) and grid-arranged.
|
||||||
|
|
||||||
|
- **Metric / stat cards:** white card, hairline border, no shadow. A small uppercase
|
||||||
|
eyebrow label, then the figure **large in mono tabular** (`--text-h2`/`h3`), then an
|
||||||
|
optional delta line. Show change with a small coloured chip or arrow in `--success` /
|
||||||
|
`--danger` — **muted, not neon**, never a red/green gradient.
|
||||||
|
- **Card grid:** lay metric cards on a responsive grid with `--space-4`/`--space-5` gaps.
|
||||||
|
Group related cards under a section header (eyebrow label + thin accent tick).
|
||||||
|
- **Tables:** the workhorse of dashboards. Eyebrow-label header row, hairline row dividers
|
||||||
|
(or zebra via `--surface-sunken` at low contrast), generous row height, mono tabular for
|
||||||
|
any numeric column, right-align numbers. Status/category cells use the chip system (§8).
|
||||||
|
Sticky header for long tables. Row hover = `--surface-hover`.
|
||||||
|
- **Charts:** flat fills, no 3D, no drop shadows, no gradients-as-decoration. Use the blue
|
||||||
|
accent as the primary series; pull additional series from the muted categorical palette
|
||||||
|
(§8) so chart colours match the chips/legends elsewhere. Thin gridlines in
|
||||||
|
`--border-subtle`, axis labels in `--text-muted`. A legend reuses the same chip styling.
|
||||||
|
- **Density:** comfortable, not cramped. Don't add stats, sparklines, or icons that aren't
|
||||||
|
answering a real question — less is more. No "data slop."
|
||||||
|
- **Filters / toolbars:** segmented controls and ghost buttons in a row above the content,
|
||||||
|
separated from it by a hairline. Active segment = `--accent-soft` fill + accent text.
|
||||||
|
- **Empty & loading states:** a calm centred message in `--text-muted` with one clear
|
||||||
|
action — never a spinner alone with no context.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 8. Colour-coding categorical data (the timesheet pattern — use it everywhere it fits)
|
||||||
|
|
||||||
|
This is the pattern from the timesheet that works well: any time data falls into **named
|
||||||
|
categories** — work codes, expense categories, invoice statuses (draft/sent/paid/overdue),
|
||||||
|
project tags, leave types, priority levels — give each category a **stable, muted colour
|
||||||
|
identity** and surface it consistently. It turns a wall of rows into something scannable.
|
||||||
|
|
||||||
|
### 8.1 The colour identity
|
||||||
|
Each category owns a trio, ideally defined in **config/data, not hardcoded**, exposed as CSS
|
||||||
|
custom properties so they stay configurable:
|
||||||
|
|
||||||
|
```
|
||||||
|
--chip-border : a saturated-but-muted hue (the category's "true" colour)
|
||||||
|
--chip-bg : a soft pale tint of that hue (fills behind text — must keep AA contrast)
|
||||||
|
--chip-text : a darker shade of the hue (readable label colour)
|
||||||
|
```
|
||||||
|
|
||||||
|
You can specify all three for control, or specify just `--chip-border` and derive the tint
|
||||||
|
with `color-mix(in srgb, var(--chip-border) 16%, var(--surface))`. **Muted, never neon** —
|
||||||
|
think `#0078d7` blue, `#8cbd18` olive, `#ed616f` coral, `#393939` slate, not pure primaries.
|
||||||
|
|
||||||
|
### 8.2 Three ways to surface it (use together)
|
||||||
|
1. **Chip / pill** — a `--radius-full` pill with a leading filled **dot** in the category
|
||||||
|
colour, the code + short name. This is the primary, always-legible token. Used in cells,
|
||||||
|
filters, and legends.
|
||||||
|
2. **Left border on the row** — `border-left: 3–4px solid var(--chip-border)`. A quiet,
|
||||||
|
always-on stripe that lets you scan a long table by category at a glance.
|
||||||
|
3. **Optional muted row tint** — fill the whole row with `--chip-bg` (or a 45% `color-mix`
|
||||||
|
of it). Make this **toggleable** (the timesheet's `muted-background` option): some users
|
||||||
|
want the calm border-only view, others want the colour wash. Default to the quieter one.
|
||||||
|
|
||||||
|
### 8.3 Legend
|
||||||
|
Whenever colour carries meaning, show a **legend** of chips mapping each colour to its label.
|
||||||
|
Colour is never the *only* signal — the code/name text is always present, so the system
|
||||||
|
works for colour-blind users and in print/PDF.
|
||||||
|
|
||||||
|
### 8.4 Full-day vs partial, and state variants
|
||||||
|
A category can carry more than one colour for sub-states (the timesheet's PPT uses a
|
||||||
|
red full-day vs amber partial-day pair). Model these as variant classes/props
|
||||||
|
(`c-PPT` vs `c-PPTp`) rather than inventing ad-hoc colours at the call site.
|
||||||
|
|
||||||
|
### 8.5 Dark mode
|
||||||
|
Tints are too dark to read directly inverted. Either define dark-mode `--chip-bg`/`--chip-text`
|
||||||
|
in the dark scope, or in dark mode show the chip as the border colour on a transparent fill
|
||||||
|
(`color-mix` the hue into the surface) and brighten slightly. Always re-check contrast.
|
||||||
|
|
||||||
|
### 8.6 Reuse across the family
|
||||||
|
The *same* category palette should drive chips, row borders, row tints, **and** chart
|
||||||
|
series — so a "Travel" expense is the same colour in the table, the legend, and the pie
|
||||||
|
chart. Define the palette once per app and pull from it everywhere.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 9. Iconography
|
||||||
|
|
||||||
|
- **System:** Lucide — 2px-stroke outline icons. Size `1em`–18px, round caps/joins,
|
||||||
|
`currentColor` so they inherit text colour. Bump stroke to 2.2–2.4 at very small sizes.
|
||||||
|
- **Status** is a small filled dot or a Lucide glyph + colour. **Never emoji.**
|
||||||
|
- Don't draw bespoke illustrations in SVG; prefer clean icons, real screenshots, or
|
||||||
|
diagrams. No stock photos, no grain, no duotone.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 10. Dark mode checklist
|
||||||
|
|
||||||
|
- Every colour goes through a semantic token; nothing hardcoded that can't invert.
|
||||||
|
- Page `#0d1117`, card `#161b22`, raised `#1c232c`; borders lighten, text lightens, accent
|
||||||
|
shifts lighter (`--blue-400`-ish) for contrast on dark.
|
||||||
|
- Shadows get heavier/darker (already handled by the dark elevation tokens).
|
||||||
|
- Re-derive category tints (§8.5). Re-check chip and note contrast.
|
||||||
|
- Support both auto (`prefers-color-scheme`) and a manual `data-theme` override, persisted.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
## 11. Do / Don't
|
||||||
|
|
||||||
|
**Do**
|
||||||
|
- Use one blue accent; let borders and whitespace do the work.
|
||||||
|
- Keep forms row-major; keep numbers in mono tabular.
|
||||||
|
- Colour-code categories with the muted chip/border/tint system, with a legend.
|
||||||
|
- Sentence case, exact numbers, honest empty/error states.
|
||||||
|
- Cap width, left-align, single-column-lean; comfortable 4px-grid spacing.
|
||||||
|
- Support light + dark through tokens.
|
||||||
|
|
||||||
|
**Don't**
|
||||||
|
- No gradients, photographic washes, textures, or glassmorphism.
|
||||||
|
- No emoji, no exclamation marks, no hype words, no Title Case.
|
||||||
|
- No neon semantic colours; no red/green gradient deltas.
|
||||||
|
- No bubbly radii (>16px on cards), no bouncy/springy motion.
|
||||||
|
- No shadow as decoration — only for things that truly float.
|
||||||
|
- Don't hardcode colours, strings, or the accent when a config can drive them.
|
||||||
|
- Don't redefine what the app *is* — restyle the surface, keep the behaviour.
|
||||||
|
|
||||||
|
---
|
||||||
|
|
||||||
|
*This brief governs surface only. When a real codebase or brand guide exists, reconcile
|
||||||
|
these tokens against it rather than overriding the product.*
|
||||||
Loading…
Reference in a new issue