werkrevisor/docs/prs/2026-10-06-PR#26-dashboard-design.md

# PR#26: the dashboard looks like Werkator and shows private repositories without their names

> **WARNING:** This document describes only the change applied in this PR.
> It may already be outdated once the next PR is merged.
> Historic PR documentation is not maintained along with new PRs; treat it as a snapshot.

## The Problem

The start page of werkrevisor 0.18.4 has its own plain look,
while it will be embedded in Werkator and sits next to it at werkator.javagil.de.
It has no light and dark mode, no footer with version and imprint,
and the token field takes room on every visit, although few readers have a token.

The tables per day, week and month show up to 30 rows, although the newest periods are what one looks at.

Without a read token, the table per repository sums all private repositories in one line "private repositories".
So the reader cannot see how many repositories cost what, and the line looks like a repository of that name.

## Non-Goals

- No change of `/api/usage` or `/api/billed-calls`.
- No shared stylesheet with Werkator: the page copies Werkator's color tokens, Werkator keeps its own file.
- No change of what a read token shows: the recent reviews and the names of private repositories.
- No hiding of the number of private repositories or of their single costs:
  the developer decided that a reader without a token sees them, so that the rows add up to the total.
  A reader who knows other data may guess which row belongs to which private repository;
  only the name stays hidden.

## The Scenarios

### Feature: the page looks like Werkator

#### Scenario#26.01: the reader switches between light and dark

So that the page fits the reader's environment and Werkator next to it.

- **Given** a browser that prefers light
- **When** the reader clicks the theme button in the header
- **Then** the page shows the dark colors of Werkator
  - **and** the next visit shows dark again

##### Verified by

- manual check in a browser, see [Measurement](#measurement)

#### Scenario#26.02: the footer names version, author, imprint and privacy policy

So that the reader knows which version runs and who is responsible.

- **Given** werkrevisor 0.18.5 runs
- **When** someone opens the start page
- **Then** the footer shows "werkrevisor v0.18.5 · © 2026 Michael Hönnig" and the links "Imprint" and "Privacy"

##### Verified by

- [UsageApiIntegrationTest: the statistics name the version of the service](../../server/src/test/kotlin/de/hoennig/werkrevisor/server/UsageApiIntegrationTest.kt)
- manual check in a browser, see [Measurement](#measurement)

#### Scenario#26.03: the read token is entered behind the key button

So that the token field takes no room for readers without a token.

- **Given** the reader has `<token>`
- **When** the reader clicks the key button in the header
- **Then** `<result>`

| token | result |
|---|---|
| no stored token | the page asks for the read token |
| a stored token that the service accepts | the page offers to forget it; the key is marked as active |
| a stored token that the service rejects | the page offers to forget it; the key is marked as rejected |

##### Verified by

- manual check in a browser, see [Measurement](#measurement)

### Feature: the period tables show the newest periods

#### Scenario#26.04: a period table shows 3 periods and opens the rest on demand

So that the newest costs are visible at once.

- **Given** the statistics hold 30 days, 12 weeks and 12 months
- **When** someone opens the dashboard
- **Then** each table per day, week and month shows its 3 newest periods
  - **and** a button "Show 27 more" or "Show 9 more" opens the rest

##### Verified by

- manual check in a browser, see [Measurement](#measurement)

### Feature: private repositories keep their row

#### Scenario#26.05: without a read token, each private repository has its own row without name

So that the rows add up to the total, and no row looks like a repository named "private repositories".

- **Given** a public and three private repositories reported reviews
- **When** someone opens the dashboard without a token
- **Then** the table per repository shows the name of the public repository
  - **and** one row per private repository, named "private repository" in grey italics,
    with its costs, reviews and pull requests

##### Verified by

- [UsageApiIntegrationTest: private repositories are named only with a read token](../../server/src/test/kotlin/de/hoennig/werkrevisor/server/UsageApiIntegrationTest.kt),
  for one group per private repository with `hidden: true` and an empty key
- manual check in a browser, see [Measurement](#measurement), for the label "private repository" in grey italics

## The Solution

- `static/werkrevisor.css` holds Werkator's color tokens for light, dark by preference and dark by choice,
  its header, buttons and footer, and IBM Plex from `static/fonts/` (SIL Open Font License, as in Werkator).
- `static/werkrevisor-page.js` handles the key button, the theme button and the version in the footer;
  the Web Component stays free of page concerns, so that Werkator can embed it with its own header.
- The Web Component uses the tokens `--bg`, `--text`, `--accent` and the like, with Werkator's light values as fallback,
  shows verdicts as colored dots instead of emoji,
  and dispatches `werkrevisor-stats` after each load.
- `GET /api/stats` returns `version` from the build info,
  and a group per private repository with an empty key and `hidden: true`.
- werkrevisor 0.18.5.

## Measurement

On 2026-10-06, the service ran locally with a copy of the live database, whose records carry no visibility flag yet.

- Light and dark matched Werkator's colors; the theme button switched them, and a reload kept the choice.
- The footer showed "werkrevisor v0.18.5 · © 2026 Michael Hönnig", "Imprint" and "Privacy".
- Each period table showed 3 rows and "Show 27 more" or "Show 9 more"; a click opened the rest.
- Without a token, the table per repository showed one row "private repository" in grey italics with 10 reviews.
- A wrong token marked the key as rejected; the read token marked it as active
  and added the name `mi/werkrevisor` and the recent reviews.
- At a phone width of 375 px, the page did not scroll horizontally.

## Prerequisite PRs

- PR#25: public statistics.