diff --git a/docs/STYLEGUIDE.md b/docs/STYLEGUIDE.md new file mode 100644 index 00000000..05352243 --- /dev/null +++ b/docs/STYLEGUIDE.md @@ -0,0 +1,390 @@ +# Familienarchiv — Design Styleguide + +This document defines the visual language for the Familienarchiv frontend. All UI work should follow these conventions to stay consistent with the De Gruyter Brill corporate identity. + +--- + +## Brand Identity + +The design is based on the **De Gruyter Brill** brand identity (unveiled at Frankfurt Book Fair 2024). Key characteristics: + +- Clean white backgrounds, high contrast +- Strong typographic hierarchy (uppercase labels, serif body text) +- Academic publisher aesthetic: authoritative, clear, uncluttered +- The Melrose purple (`#B4B9FF`) quotation-mark logo is the primary brand signature + +--- + +## Colors + +Defined in `src/routes/layout.css` as `@theme` variables. All generate Tailwind utilities automatically (`bg-*`, `text-*`, `border-*`). + +| Token | Hex | Usage | +|---|---|---| +| `brand-navy` | `#012851` | Primary text, headings, buttons, active states — Prussian Blue | +| `brand-mint` | `#A1DCD8` | Accent color, icon tints, hover underlines — Aqua Island | +| `brand-purple` | `#B4B9FF` | Logo, nav active state highlight, top accent strip — Melrose | +| `brand-sand` | `#F0EFE9` | Subtle card backgrounds, borders, hover backgrounds — paper tone | +| `brand-white` | `#FFFFFF` | Page background, card surfaces | +| `brand-dark` | `#0D0D0D` | Near-black text when maximum contrast is needed | + +### Color usage rules + +- **Never** use raw hex values in components — always use token utilities. +- Page and card backgrounds are **white**. Use `bg-brand-sand` only for subtle inset areas (e.g. `bg-brand-sand/30`). +- `brand-navy` is the workhorse: headings, body text, borders, primary buttons. +- `brand-mint` is an accent only — never use it as primary text color on white (contrast too low). +- `brand-purple` is reserved for the logo and the single top accent strip in the header. + +--- + +## Typography + +### Fonts + +| Role | Font | Tailwind | Notes | +|---|---|---|---| +| Body / Serif | **Tinos** (Times substitute) | `font-serif` | Loaded from Google Fonts. Used for document titles, names, body copy, dates. Matches DGB's use of Times. | +| UI / Sans | **Montserrat** (Gotham substitute) | `font-sans` | Loaded from Google Fonts. Used for labels, navigation, buttons, metadata, form elements. Matches DGB's use of Gotham. | + +### Type scale and usage + +| Element | Classes | Example | +|---|---|---| +| Page title | `font-serif text-3xl text-brand-navy` | `

` | +| Card section heading | `font-sans text-xs font-bold uppercase tracking-widest text-gray-400` | Section labels | +| Document / item title | `font-serif text-xl font-medium text-brand-navy` | List items | +| Metadata / label | `font-sans text-xs font-bold uppercase tracking-widest text-gray-500` | Field labels | +| Body text | `font-serif text-sm text-brand-navy` | Descriptions, summaries | +| Navigation | `font-sans text-xs font-bold uppercase tracking-widest` | Nav links | + +### Rules + +- **Labels are always uppercase + tracked**: `text-xs font-bold uppercase tracking-widest` +- **Headings** use `font-sans` (Montserrat), set in CSS globally. +- **Content** (document titles, person names, summaries) uses `font-serif` (Tinos). +- Never use `font-serif` for UI chrome (buttons, labels, nav). + +--- + +## Icons + +### Library + +686 SVG icons in `frontend/static/degruyter-icons/`. Two families: + +- **Simple** — single-color, action-oriented. Use for all UI icons. Available in 4 sizes. +- **Complex** — multi-color illustrative icons. Use sparingly for empty states or section headers. + +### Simple icon sizes + +| Size | Pixels | Path segment | Use | +|---|---|---|---| +| XS | 12px | `X-Small-12px` | Inline text hints, badges | +| SM | 16px | `Small-16px` | Compact UI, table cells | +| **MD** | **24px** | **`Medium-24px`** | **Standard UI icon — default choice** | +| LG | 32px | `Large-32px` | Feature headers, empty states | + +### URL pattern + +``` +/degruyter-icons/Simple/{Size}/SVG/{Category}/{Name}-{Size-Code}.svg +``` + +**Size codes:** `XS`, `SM`, `MD`, `LG` + +### Usage as `` (recommended for static icons) + +SVG fills are hardcoded to `#000000`. Use CSS to tint/size them: + +```svelte + + + + + + + + +``` + +> **Note:** Always include `alt=""` and `aria-hidden="true"` for decorative icons. For meaningful icons (no visible label next to them), use a descriptive `alt` text instead. + +### Key icons for this app + +| Use case | Icon path | +|---|---| +| Edit / Bearbeiten | `Action/Edit-Content-MD.svg` | +| Search / Suche | `Action/Mag-Glass-MD.svg` | +| New document | `Action/Add/Add-General-MD.svg` | +| Download | `Action/Download-MD.svg` | +| Upload | `Action/Upload-MD.svg` | +| Filter | `Action/Filter/Filter-Outline-MD.svg` | +| Calendar / date | `Action/Calendar/Calendar-Add-MD.svg` | +| Location | `Action/Location-MD.svg` | +| Person / account | `Action/Account-MD.svg` | +| Chat / conversation | `Action/Chat-MD.svg` | +| Tag / bookmark | `Action/Bookmark/Bookmark-Outline-MD.svg` | +| Close / dismiss | `Action/Close-MD.svg` | +| Back / left arrow | `Action/Arrow/Arrow-Left-MD.svg` | +| Settings / admin | `Action/Settings-MD.svg` | +| Document / PDF | `Action/PDF-Document-MD.svg` | +| Mail | `Action/Mail-MD.svg` | +| Delete | `Action/Remove/Remove-General-MD.svg` | +| Info | `Action/Info/Block/Info-Block-Border-MD.svg` | + +--- + +## Spacing + +Based on Tailwind's 4pt grid. Prefer multiples of 4 for all spacing. + +| Scale | Value | Use | +|---|---|---| +| `p-1` / `gap-1` | 4px | Tight inline spacing | +| `p-2` | 8px | Small padding (badges, chips) | +| `p-3` | 12px | Compact buttons | +| `p-4` | 16px | Default section padding | +| `p-6` | 24px | Card inner padding (default) | +| `p-8` | 32px | Large card padding | +| `p-10` | 40px | Page vertical padding | +| `gap-6` | 24px | Grid/list gaps | +| `mb-6` | 24px | Standard spacing between sections | +| `mb-10` | 40px | Large spacing between card sections | + +--- + +## Layout + +### Page wrapper + +All content pages use: +```svelte +
+``` + +Narrower pages (forms, detail views): +```svelte +
+``` + +### Header + +The global sticky header in `+layout.svelte`: +- Height: **68px** (4px purple accent strip + 64px nav bar) +- Background: `bg-white` +- Bottom border: `border-b border-gray-100` +- Z-index: `z-50` + +### Full-screen views + +Document detail (`/documents/[id]`) uses a full-viewport split layout: +```svelte +
+ + +
+``` + +--- + +## Components + +### Card + +Standard content card: +```svelte +
+

+ Section Title +

+ +
+``` + +Card with colored accent bar (person/document detail): +```svelte +
+
+
+ +
+
+``` + +### Buttons + +Primary button: +```svelte + +``` + +Secondary / outline button: +```svelte + +``` + +Ghost / text button (inline actions): +```svelte + +``` + +Destructive button: +```svelte + +``` + +Button with DGB icon: +```svelte + +``` + +> Use `class="invert"` on icons inside dark (navy) buttons to make the black SVG white. + +### Form inputs + +Label + input pair: +```svelte +
+ + +
+``` + +Search input: +```svelte +
+ +
+ +
+
+``` + +### Status badges + +```svelte + + + UPLOADED + + + + + PLACEHOLDER + +``` + +### Tag chips + +```svelte + +``` + +### Back link + +```svelte + + + Zurück zur Übersicht + +``` + +### Subtle "new item" link + +```svelte + + + Neues Dokument + +``` + +### Empty state + +```svelte +
+
+ +
+

Keine Dokumente gefunden

+

Versuchen Sie, die Filter anzupassen.

+
+``` + +### Nav active state + +Current page nav link: +```svelte +class="text-brand-navy bg-brand-purple/15 rounded" +``` + +Inactive nav link: +```svelte +class="text-gray-500 hover:text-brand-navy hover:bg-brand-sand/60 rounded" +``` + +Both share the base: `inline-flex items-center px-3 py-1.5 text-xs font-bold uppercase tracking-widest font-sans transition-colors` + +### Save bar (long forms) + +Sticky full-bleed (document edit): +```svelte +
+ + Abbrechen + + +
+``` + +Card-style (short forms): +```svelte +
+``` + +--- + +## Do / Don't + +| Do | Don't | +|---|---| +| Use `font-sans` for all UI labels, buttons, nav | Use `font-serif` for buttons or labels | +| Use `uppercase tracking-widest` for labels | Use sentence case for field labels | +| Use `brand-navy` for primary actions | Use `brand-mint` as primary action color | +| Use `opacity-*` to create icon tints | Change icon fill color inline | +| Use `invert` class on icons inside `bg-brand-navy` buttons | Use colored icon files for button icons | +| Use `rounded-sm` for cards and buttons (subtle) | Use `rounded-full` for non-pill elements | +| Use `shadow-sm` for card elevation | Use large shadows | +| Keep borders `border-gray-100` or `border-brand-sand` | Use dark borders |