invoice/DESIGN.md

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:

--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.