politics-tracking/docs/design/README.md

Politrack design concept

How Politrack looks, reads and behaves, and why. This is the concept: goals, principles, information architecture, the core patterns and a concept for every page. The companion design-system.md is the implementation reference: tokens, components, CSS conventions and recipes for contributors.

Items marked (later) are designed here but not built yet; everything else is implemented in web/.

1. Goals

Politrack is a public record of what Austrian politicians do, where every fact links to its source. The interface has four jobs, in this order:

1. Make every fact checkable. A reader is never more than one click from the document behind a statement on the screen.
2. Be fair to everyone shown. The same layout, wording and weight for every person and party; the presumption of innocence and the limits of the data are visible where they matter, not in a footer.
3. Answer common questions fast, on a phone. "Who is this?", "How did they vote?", "Who gave money to whom?" in a few seconds, with no app and no account.
4. Support deep research on a desk. Dense tables, filters in the URL, time ranges, cross-links between people, organisations and money, and stable links for citing.

2. Audiences and their tasks

Audience	Context	Top tasks	What the UI must provide
Interested citizens	Phone, linked from news or social media, a few minutes	Look up a politician, a party's votes, donations	Search first, plain language, clear summaries, a readable profile on a small screen
Journalists and researchers	Desktop, long sessions, need to cite	Follow money between organisations, build a timeline, check a claim	Filters and date ranges in the URL, dense tables, permalinks per fact, source details, consistent numbers
NGOs and activists	Desktop and phone, recurring	Monitor topics and people	Topic filters, calendar, (later) alerts
The people profiled and their staff	Desktop	Check what is shown about them	Fair presentation, visible sources, (later) a corrections form
AI agents	No UI (MCP server, REST API)	Retrieve facts with evidence	Mentioned in the footer and methodology; the UI never shows anything the API doesn't

3. Principles

Each principle comes with the rules that make it concrete.

P1 Evidence first. The atom of the interface is the claim card: a one-sentence summary plus its sources. Rules: the number of sources is always visible; the source list is one click away; every external link opens the original; quotes are shown as quotes (marked, attributed); there is no UI element that states a fact without a claim behind it.

P2 Neutral by design. Rules: the interface accent is a colour no Austrian party uses (an ink indigo, not the flag red, which reads as SPÖ red); party colours appear only as small identity markers (a dot or a thin bar) and always next to the party's name, never as large backgrounds; every party and person gets the same layout; lists are ordered by neutral criteria (date, size, alphabet); copy uses reporting verbs ("laut", "gemeldet", "berichtet") instead of judgement.

P3 Show certainty honestly. One vocabulary for how sure we are (see §6.3), shown the same way everywhere: single vs. multiple sources, disputed facts, unverified accounts, unconfirmed status, publication date vs. event date.

P4 Fairness for legal matters. The procedural stage is the headline of a legal claim; "Es gilt die Unschuldsvermutung" sits inside the claim card, not in a footnote; legal claims are styled in a neutral caution tone, never in alarm red; no portraits inside legal claim cards or feeds of allegations; connections between people and organisations carry the note that a connection is not an accusation; profile overviews highlight work (votes, speeches, offices), not allegations.

P5 Plain language, German first. German is the default at /, English at /en. Technical terms (namentliche Abstimmung, Klub, Ministerrat, Diversion) are explained where they appear. Long German compounds must not break layouts: hyphenation is on and long tokens may wrap.

P6 Time is a first-class dimension. Every list can be narrowed to a date range, profiles have a timeline, a calendar shows what happened on a day, and "search in time" lists everything in a period. Dates say what they are ("Datum = Veröffentlichung der Quelle" where we only know the publication date).

P7 Fast, robust, accessible, private. Server-rendered pages that work without JavaScript; WCAG 2.2 AA; system fonts; no third-party scripts, fonts, embeds or trackers; print stylesheets that keep source URLs.

P8 Shareable and citable. Filters live in the URL; every claim has a permalink page with a ready-made citation; page titles name the person or topic.

4. Brand and tone

Name and mark. politrack in lowercase, set in the system font at heavy weight. The mark is a pair of square brackets around a dot: the citation bracket of a footnote with the piece of evidence inside. It is the favicon too. Tagline: Österreichs Politik, belegt.

Colour stance. Near-monochrome "paper and ink" neutrals carry the interface. One accent, an ink indigo, marks interaction (links, focus, active navigation, magnitude bars). A highlighter yellow marks quoted evidence and search hits. Semantic colours (positive, negative, caution) appear only in small badges and always with an icon and a word, never as colour alone. Party colours follow the rules in P2.

Voice. Sachlich, precise, friendly. We address readers with "du" (as the existing copy does) and use gender-inclusive forms with a colon (Politiker:innen). We describe what a source says, with the source: "Laut Rechnungshof spendete …", not "X kaufte sich Einfluss". Numbers are exact where the source is exact and labelled as reported ("Beträge wie gemeldet").

5. Information architecture

Sitemap

/                         Start: search, key figures, latest facts, explore
/suche                    Search (full text and "search in time": a date range without a query)
/personen                 People (filters: party, level, status)
  /personen/{slug}        Profile with tabs: overview, timeline, votes, travel & meetings,
                          statements, social media, money & network, media & career, legal
/ehemalige                Former politicians: what they do now
/parteien                 Parties
  /parteien/{slug}        Party: officials, votes, money, finances, affiliated organisations, channels
/organisationen           Organisations (companies, associations, authorities, media, lobbies)
  /organisationen/{slug}  Organisation: money in and out, counterparties, connected people
/geld                     Money explorer: donations, contracts, ads, subsidies, party funding
/abstimmungen             Votes (faction votes; roll calls)
  /abstimmungen/{id}      Vote: result, factions, individual votes, dissent
/kalender                 Calendar: sessions, committees, hearings, Council of Ministers, trips, meetings
/social                   Public posts from politicians' and parties' channels
/wikipedia                Wikipedia edits from parliament and government networks
/angaben/{id}             Claim permalink: one fact with all its sources and a citation
/einstellungen            My filters: trusted sources, topics
/methodik                 Methodology, statuses, legal stages, sources and their terms

Route names are German in both languages (/en/personen/…): one URL scheme, links stay valid when switching language.

Navigation

• Header, primary: Personen, Parteien, Abstimmungen, Geld, Organisationen, Kalender; Mehr: Social Media, Wikipedia-Bearbeitungen, Ehemalige, Methodik & Quellen. Utilities: a search field, Meine Filter with the number of active filters, language, light/dark theme. Below 1024 px the navigation collapses into a menu (a native disclosure, no JavaScript) and the search field becomes a search button.
• Footer: the full sitemap in three groups (Menschen, Entscheidungen, Geld & Einfluss), the principles in three lines, links for developers and agents.
• Breadcrumbs on every detail page (Start › Personen › Name).
• Cross-links everywhere: every person, party and organisation name is a link; money rows link both sides; lists on profiles end with a "Alle …" link into the explorer, pre-filtered.

URL conventions

All filters are query parameters on plain GET forms (/geld?kind=donation&since=2025-01-01), so every view can be bookmarked and shared. Personal source/topic preferences are the only state kept outside the URL (a cookie), and the header always shows when they are active.

6. Core patterns

6.1 The claim card

┌──────────────────────────────────────────────────────────────────────┐
│ ◇ SPENDE  ·  12. März 2026  ·  Österreichische Volkspartei     ●●○ 2 │  type, date, subject, sources
│                                                                      │
│ Die Muster GmbH spendete der ÖVP 25.000 €.                           │  summary (the fact)
│ 25.000 € · Muster GmbH → ÖVP · 2025                                  │  type-specific details
│ [Wirtschaft] [Parteifinanzen]                                        │  topics
│ ▸ 2 Belege                                              Permalink ↗  │  evidence disclosure
└──────────────────────────────────────────────────────────────────────┘

• The header row is metadata in small type: type label with icon, date, subject (when the list mixes subjects), and the source meter on the right.
• The summary is the largest text in the card. In English the English summary is used when available.
• Type-specific details (amounts, counterparts, platforms, file numbers) come from a registry, one renderer per claim type.
• The evidence disclosure lists each source with its publisher, source kind (Amtlich, Medien, …), title, date, stance (supports / mentions / contradicts) and quote. Quotes are set as block quotes with the highlighter mark.
• A permalink opens the claim page (§7.17).
• Disputed claims get a caution edge and the word "umstritten". Claims awaiting review are never public; if one is shown (admin views) it carries "Noch nicht redaktionell geprüft".

6.2 Evidence and corroboration

The source meter shows up to three dots: one filled dot = one source ("einfach belegt"), two or more filled = "mehrfach belegt" with the number. A disputed claim shows a caution triangle and the word "umstritten" instead. A tooltip gives the full wording ("bestätigt durch 3 unabhängige Quellen"). The meter never stands alone: the number is always written next to it.

6.3 Certainty vocabulary

Concept	Values (German UI)	Shown as
Claim status	einfach belegt · mehrfach belegt · umstritten	source meter; caution edge for umstritten
Person status	Aktiv · Ehemalig · Ohne Amt (Parteimitglied) · Verstorben	status badge; "Aktiv" without an official confirmation adds "nicht amtlich bestätigt"
Social account	bestätigt · nicht bestätigt	unconfirmed accounts get a dashed badge and a tooltip (source: Wikidata only)
Review	Noch nicht redaktionell geprüft	caution notice (admin views only)
Dates	Ereignisdatum · Veröffentlichungsdatum	footnote on calendar and trips: "Datum = Veröffentlichungsdatum der Quelle"
Amounts	wie gemeldet · Kategorie	exact amount, or the reported category ("über 50.000 €")

6.4 Legal matters

┌──────────────────────────────────────────────────────────────────────┐
│ ⚖ VERFAHREN  ·  3. Februar 2026  ·  Name                       ●○○ 1 │
│ [Ermittlungsverfahren]  § 302 StGB  ·  WKStA                         │  stage first, as a badge
│ Summary of what the source reports …                                 │
│ ⓘ Es gilt die Unschuldsvermutung.                                    │  inside the card
│ ▸ 1 Beleg                                                            │
└──────────────────────────────────────────────────────────────────────┘

The notice is shown for every stage except an undisputed final conviction (including acquittals, dropped proceedings and diversion, which confirm there is no finding of guilt). Automatically detected legal claims stay in review until a human approves them. Profiles count legal claims only on their tab, never in the "at a glance" figures.

6.5 Money

• Amounts in euro with locale formatting (25.000 €, €25,000); large figures in summaries and bar lists are compact (1,2 Mio. €) with the exact value in the tooltip; tables show exact values.
• Direction is always explicit: Von → An. Both sides are links when the organisation is known.
• Every amount says what kind of money it is (Spende, öffentlicher Auftrag, Regierungsinserat, Förderung, Parteienförderung, politische Werbung, Kredit). Different kinds are never summed into one figure without a label.
• "Beträge wie gemeldet" and the list of registers sit under every money table.
• Money of organisations a person is connected to (side jobs, career) is labelled as the organisation's money and carries the connection note.

6.6 Votes

• A vote shows date, item title, reference, stage, chamber, result and the position of every faction as position chips: party dot + short name + position icon (✓ dafür, ✕ dagegen, – Enthaltung, ○ abwesend), with a tinted background per position.
• Roll calls are marked ("namentlich"); they show individual votes grouped by faction with counts, and members who voted against their faction are marked "gegen die eigene Fraktion".
• On a person's vote list the position says whether it is the faction's vote or the person's own vote, because most Austrian votes are recorded per faction only. The note explaining this sits above the list.
• Say vs. vote: when the person spoke on the item, a link to the speech appears under the vote.

6.7 Time

• Dates in lists: 12. März 2026 (de-AT) / 12 Mar 2026 (en-GB). Months in charts: 03/2026.
• The activity histogram (claims per month) on profiles links each bar to that month.
• Date range fields on every list that supports them; with no query, search becomes "search in time" and lists everything in the range.
• The role timeline on a profile draws offices and memberships as bars on a year axis.

6.8 Filters

Two kinds, never mixed up:

• Page filters (party, level, kind, date …) live in the URL. Active filters are visible in the form; a reset link clears them. On phones the filter form is collapsed behind "Filter" with the number of active filters.
• My filters (trusted sources, minimum trust, topics) are stored in a cookie and apply to every list. When they are active, the header badge shows the count and lists show a notice with a link to change them, so nobody is surprised by missing data.

6.9 Connections

Wherever the UI shows that a person is connected to an organisation (side job, career, meeting, party) or shows the organisation's money, the note "Eine Verbindung ist kein Vorwurf." is part of the section.

6.10 Social posts

Posts are shown as text cards with platform, author, date and a link to the original; no embeds, no third-party images or scripts. Accounts that only Wikidata attributes to a person are marked "Konto nicht bestätigt". The collection policy (official APIs only; no Facebook/Instagram scraping; no WhatsApp, Signal or private Telegram groups) is stated on the page.

6.11 Empty, loading and error states

• Empty: an icon, one sentence that says why ("Keine Angaben mit deinen Quellen- und Themenfiltern.") and the most likely next step (reset filters, broaden the date range).
• Loading: skeleton blocks in the page's layout, no spinners.
• Error: what happened in one sentence, a retry button, a link home.

7. Page concepts

Every page uses one of four templates: index (header, filters, results, pagination, source note), profile (identity header, key figures, tabs, main column plus aside), detail (header, verdict, breakdown) and prose (methodology).

7.1 Start (/)

Purpose: orient, search, show that the data is alive.

┌ hero ───────────────────────────────────────────────────────────────┐
│ Politik in Österreich – nachvollziehbar.                             │
│ Lede: what Politrack is, "jede Angabe mit Quelle".                   │
│ [ Person, Thema oder Stichwort …                     ] [Suchen]      │
│ Schnellzugriff: Parteispenden · Namentliche Abstimmungen · Inserate  │
└──────────────────────────────────────────────────────────────────────┘
[ 1.234 Personen ] [ 56.789 Angaben ] [ 1.210 Abstimmungen ] [ 9.876 Geldflüsse ]   Stand …
┌ Neueste Angaben (claim feed) ──────────┐ ┌ aside ───────────────────┐
│ claim card …                            │ │ Parteien (dot, name, n)  │
│ claim card …                            │ │ Letzte Abstimmungen      │
└─────────────────────────────────────────┘ └──────────────────────────┘
Entdecken: 6 cards with icon, title, one line (Geld, Organisationen, Social, Wikipedia, Ehemalige, Kalender)
So arbeitet Politrack: Belege · Unabhängige Bestätigung · Unschuldsvermutung  → Methodik

7.2 Search (/suche)

A large search field with optional date range. Results are cards with type label, date, subject and a snippet with the query terms highlighted; document hits (news, releases) show the publisher. Without a query but with a date range, the page lists all claims in that period ("search in time"). Empty states suggest fewer words or a wider range.

7.3 People (/personen)

Index template. Filters: name, party, level (EU, Bund, Land, Gemeinde, Partei), status (default: aktiv). Results are person cards in a responsive grid: portrait or initials, name, current roles (two lines max), party tags, and the status for non-active people. Pagination at the bottom.

7.4 Person profile (/personen/{slug})

Start › Personen › Name
┌──────┐  [Aktiv]                                     Profile elsewhere:
│      │  Vorname Nachname                            Parlament ↗  Wikidata ↗  EP ↗
│ foto │  Abgeordnete zum Nationalrat · ● ÖVP
│      │  * 3. Mai 1970 · Kanäle: [Bluesky] [Telegram*]
└──────┘
[Überblick] [Zeitleiste 312] [Abstimmungen 120] [Reisen & Treffen 4] [Aussagen 58] [Social Media]
[Geld & Netzwerk 6] [Medien & Werdegang 40] [Rechtliches 1]

Overview:
┌ main ─────────────────────────────────────┐ ┌ aside ───────────────────────┐
│ Laufbahn (role timeline on a year axis)   │ │ Auf einen Blick              │
│ Neueste Angaben (claim cards)             │ │ 120 Abstimmungen · 58 Reden  │
│                                           │ │ Funktionen & Mandate (list,  │
│                                           │ │ each with its sources)       │
└───────────────────────────────────────────┘ └──────────────────────────────┘

• Tabs are links (?tab=votes), so every tab is shareable; each shows its claim count.
• Zeitleiste: activity histogram, date range, all claims in the range.
• Abstimmungen: the faction-vote note, then the vote list with position, own/faction vote, dissent and say-vs-vote.
• Geld & Netzwerk: connected organisations (via side job, career, meeting, party) with their money, the connection note, the organisations' money flows, then money-related claims.
• Rechtliches: legal claims only, each with stage and the innocence notice.
• "At a glance" counts work: votes, speeches and statements, questions, side jobs, appearances, media reports; not legal matters.

7.5 Former politicians (/ehemalige)

Index template ordered by latest media coverage. Each card: name, status, last role, last office end, latest headline with source link and date, latest career entry. Party filter.

7.6 Parties (/parteien)

Cards with a thin top bar in the party colour, short name, full name, active officials and people tracked. Ordered by the number of active officials.

7.7 Party (/parteien/{slug})

──────── party colour bar ────────
Start › Parteien › ÖVP
ÖVP  Österreichische Volkspartei
[ 312 Funktionsträger:innen ] [ 1.020 Ehemalige ] [ 830 Abstimmungen ] [ 4 abweichende Mandatar:innen ]
┌ Stimmverhalten (proportion bar) ──┐ ┌ Geld nach Jahr und Art (table) ─────┐
└───────────────────────────────────┘ └─────────────────────────────────────┘
Funktionsträger:innen grouped by level (EU · Bund · Land · Gemeinde), multi-column
┌ Rechenschaftsberichte ────────────┐ ┌ Nahestehende Organisationen ────────┐
┌ Ehemalige ────────────────────────┐ ┌ Abweichendes Stimmverhalten ────────┐
Letzte Abstimmungen · Kanäle der Partei · Belegte Angaben

7.8 Organisations (/organisationen)

Index template with a table: name, kind badge, paid, received (compact amounts, exact in tooltip). On phones the table stacks into cards. Filters: name, kind.

7.9 Organisation (/organisationen/{slug})

Header with kind badge and parent organisation; identifiers (Firmenbuch, ZVR, UID, Wikidata, EU transparency register) in the aside with links where a public register page exists. Key figures (received, paid, counterparties). Counterparties as two bar lists ("zahlte an", "erhielt von"). Connected people with the connection note. Money flow table, then all claims. Parties redirect to their party page.

7.10 Money (/geld)

Explorer template. Filters: kind, name, date range, minimum amount. Unfiltered, the page opens with two bar lists, largest payers and largest recipients, each row labelled with the kind of money. Then the money table: date, kind, from, to, amount, sources. Footer: registers used and "Beträge wie gemeldet".

7.11 Votes (/abstimmungen) and vote (/abstimmungen/{id})

The index is a list of vote rows: date, title, reference, roll-call marker, result badge, position chips per faction. Filter: roll calls only. The vote page shows the verdict as a large result badge, links to the item and the protocol, faction positions, and for roll calls a proportion bar over all individual votes and the members grouped by faction with dissent marked. The protocol wording sits in a disclosure.

7.12 Calendar (/kalender)

Month grid (Monday first) with previous/next month as header actions. Each event shows its kind (colour stripe + label), title (linked to the source) and participants. Days with only claim activity link to "search in time" for that day. Today is highlighted. On phones the grid becomes an agenda: only days with events, in order. A legend explains the kinds; the footnote states the date precision.

7.13 Social media (/social)

Feed of post cards in one or two columns. Filters: platform, party. Each card: platform badge, author (person or party channel), date, title, text (clamped to a few lines), "Original ansehen ↗", unconfirmed marker. The collection policy closes the page.

7.14 Wikipedia edits (/wikipedia)

The framing comes first: a notice that an edit from a network says nothing about which person made it. Then a table: date, network (organisation), article (linked to the diff), size change, edit comment.

7.15 My filters (/einstellungen)

Two sections. Quellen: grouped by kind (Amtlich, NGO, Medien, Datenbanken, Soziale Medien, Community, Abgeleitet); each source is a switch row with name, trust value as a small meter, and its terms in the tooltip; a minimum-trust slider below. Themen: topic chips that toggle; none selected = all. A sticky action bar with Speichern, Zurücksetzen and the saved status. Stored in a cookie only.

7.16 Methodology (/methodik)

Prose template with a table of contents: how claims and evidence work, the status vocabulary with live badges, the legal stages glossary, the sources table (publisher, licence, access method, trust meter, terms notes), what we deliberately don't collect, corrections.

7.17 Claim permalink (/angaben/{id})

One fact on its own page: type, date, subject, the summary as the title, details, legal notice where applicable, all sources expanded with quotes, and a citation box: Politrack: „{Zusammenfassung}“. Angabe #{id}, abgerufen am {Datum}. {URL}. The page ignores personal source filters, so a shared link shows the same content to everyone.

7.18 Not found and errors

Not found: an empty state with the search field and links to Personen, Parteien and Start. Errors: one sentence, "Erneut versuchen", link home.

8. Responsive behaviour

Width	Behaviour
< 640 px	one column; tables stack into labelled cards; filter forms collapse; role timeline labels above the bars; tabs scroll horizontally
< 768 px	the calendar becomes an agenda (only days with events)
640–1023 px	two-column card grids; tables scroll horizontally inside their container; menu still collapsed
≥ 1024 px	full header navigation with search field; profile pages get the aside column; two-column sections
≥ 1280 px	content width caps at 76 rem; more cards per row

9. Accessibility (WCAG 2.2 AA)

• Contrast ≥ 4.5:1 for text and ≥ 3:1 for UI parts in both themes (token values are chosen and checked for it, see the design system).
• Never colour alone: positions, results, statuses and party identity always have text, and an icon or a shape where possible.
• Keyboard: skip link, visible focus ring on everything, tabs and disclosures are native links and details elements, no keyboard traps.
• Structure: one h1 per page, headings in order, landmarks (header, nav, main, footer), aria-current for the active page and tab, tables with header cells, charts with text equivalents.
• Language: lang on the document; English summaries are marked when shown in the German UI.
• Motion: no animation beyond short hover transitions; prefers-reduced-motion removes them.
• Targets at least 24 × 24 px; form fields have visible labels.

10. Privacy and performance

• No third-party requests from the page itself: system fonts, no analytics, no embeds, no CDNs. Portraits and logos still come from Wikimedia and the parliament; they load lazily with referrerpolicy="no-referrer". (later) an image proxy so visitors' IP addresses never reach third parties.
• Server-rendered HTML; client JavaScript only for the filter settings, the theme switch, the language switch and active-link marking.
• Budget: under 100 kB of CSS and JavaScript per page (compressed), first content without waiting for scripts.

11. Before going public

Not design work, but the design depends on them; flagged here so they are not forgotten:

• Impressum and Offenlegung (§ 5 ECG, § 25 MedienG) and a privacy policy: footer links and a prose page each.
• A corrections and right-of-reply path (§ 9 MedienG): a contact on the methodology page and, later, a form linked from every claim page.
• The X deletion sync (see the roadmap) before X data is shown publicly.

12. Later

• Claim permalinks are implemented; (later) a "Fehler melden" button on them.
• Compare two people or parties side by side (votes, money, statements).
• Topic pages (/themen/{slug}): everything on one topic across people and parties.
• Alerts (e-mail or RSS) for people, parties and topics.
• A review queue for editors in the web UI (today politrack review on the command line).
• A map of trips and appearances.
• Share images (Open Graph) generated per profile and claim.
• CSV export of every table.