TOOL · OCTOBER 28, 2026
Mini Jira dashboard
A small desktop app that puts my Jira board, bugs, due dates, links and notes on one screen. Your AI builds it from the files below.
The files
# Personal dashboard: the design
This file is enough to rebuild the app with an AI, and enough to make it yours. It fixes the shape: the window, the grid, what a widget looks like, how data gets in, the words. It leaves the widgets open, because yours will not be mine. The exact numbers sit at the end for anyone who wants it identical; everything before that is the part that matters. Where the file is silent, keep it simple.
To rebuild it, use the prompts in `rebuild.md`, in order. To change it, change this file first and then ask the AI to follow it: the file is the contract, the chat is not.
## Files
```
index.html the page: markup, styles, script, all in one file
server.js the program: serves the page, polls each source, writes notes
main.js the desktop app: the same server inside one Electron window
package.json npm start opens the app; node server.js serves it to a browser
dashboard.config.json the tabs and the widgets
.env your tokens, never committed (.env.example shows the names)
fixtures/<id>.json sample data per widget, in the same shape as the live data
prompts/ every prompt used to build it, in order
rebuild.md the prompts to build it again, for anyone
```
No framework, no build step, no dependency beyond Electron. One page, one server, one config.
## The window
A desktop window in three parts, laid out the way Jira lays out a dashboard: white chrome around a grey page. The window has no title bar of its own; the system's minimize, maximize and close sit over the top strip, and the strip and the top of the rail drag the window.
- **The rail**: a narrow column down the left edge in the app's one strong colour. One square button per tab with a line icon and no label; the current tab's button is lit. At the foot of the rail, one more button opens this file. The rail is the only navigation. There is no second menu with names.
- **The strip**: a thin white bar across the top of everything right of the rail, with a hairline beneath. A back arrow at the left, then the app's title.
- **The page**: everything else, light grey, edge to edge. Content starts a little below the strip and in from the sides, is left-aligned, and stops at a sensible width on a wide monitor.
Structure comes from tone, not from boxes: the coloured rail, the grey page, white panels on it, hairlines for anything finer. No shadows, no gradients, no dark mode.
**Tabs.** Home is built in. Any other tab is one line in the config: an id, a label, an icon and a URL, and the app shows that site inside the window with your own sign-in, remembered between runs. That is how the real Jira board, a Confluence space or a SharePoint site becomes a tab. In a browser the same tab offers a link instead.
```json
"tabs": [ { "id": "jira", "label": "Jira", "icon": "board", "url": "https://JIRA_SITE/jira/software/projects/SCRUM/boards/1" } ]
```
## Home
A date line, a greeting, one sentence on whether every source is current, then the grid. Nothing else: no title, no settings, no empty-state art.
The grid has 8 columns, short rows and six sizes. Order and size come from the config; put what matters first.
| size | columns x rows | for |
|---|---|---|
| XS | 2 x 1 | one number or a short row |
| S | 2 x 2 | a notepad, a short list |
| M | 4 x 2 | a list |
| Tall | 2 x 3 | a long list |
| L | 4 x 3 | cards |
| XL | 6 x 5 | the headline widget, with a Tall and an S beside it |
On a narrow window the grid drops to 4 columns, then to 1.
## Widgets
A widget is a flat white panel on the grey page: a hairline border, softly rounded corners, no shadow. It opens with a head row: the title at the left, one fact at the right in small grey (`8 open`, `updated 2 min ago`), and at most one small text button or an arrow that opens the source. The body is the rest.
Three surfaces, set per widget as `surface` in the config:
- **panel**: the default, as above. Its title may sit on a soft colour chip, `accent` in the config: red, amber, blue, pink, lilac or grey. One chip per widget, one colour, and nothing else on the panel coloured by you.
- **embedded**: no box at all; the head row and body sit straight on the page. For a page that holds one widget, where a box would only repeat the page's edge. None of the widgets here use it.
- **card**: a panel with a faint shadow, for the rare widget that earns lifting off the page. None of the widgets here do.
Inside the body, look like the software the data comes from, not like a designed widget. Jira data uses Jira's own lozenges, type icons and lane grey. A list is plain rows with a hairline between them. Links are an icon and a name. Nothing scrolls visibly except a widget that mirrors a source whose own view scrolls: a board's lanes, which keep their width and scroll sideways when they do not fit, as Jira's do, and a column of Jira cards, which scrolls as a lane does. A plain list is cut instead, and says `+ 4 more`.
Type is the system face, small, nothing italic, numbers tabular. One colour means something: orange marks what needs you today, late work, a source that has failed. Nothing on the page is green except Jira's own marks inside a Jira widget: the Done lozenge and the Story type icon.
### State
Every source is one of four things, and the panel shows which without a word:
| state | how it looks |
|---|---|
| fresh | the normal panel |
| stale | the body faded; the fact reads `updated 40 min ago` |
| failing | the body faded; the fact is the error in six words or fewer, in orange |
| never | one grey line in the body: `Waiting for the first poll` |
### Words
Titles are a noun: `Board`, `Bugs`, `Upcoming`, `Links`, `Notes`. Facts are facts. Sentence case. No exclamation marks, no emoji, no greeting text inside a widget, no tooltips that repeat what is written. If a word is not data, ask whether it needs to be there.
## Data
`server.js` serves the page on a local port, runs each widget's adapter every `intervalSec` seconds, keeps the answer in `data/<id>.json`, and answers `GET /api/widgets` with every answer at once. `GET /api/config` gives the page the title, the tabs and each widget's layout once, at start. The page fetches the answers every half minute and redraws what changed. The browser never holds a token.
Each answer is an envelope: `id`, `updatedAt`, `intervalSec`, `ok`, `error`, `data`. The page works out the state from `ok` and the age. The fixture file for a widget is its `data`, so the fixture is the documentation of the shape.
**Adapters** are functions in `server.js`, `(options, env, widget) => data`. Built in: `jira` (a JQL, or a board id for the board's own columns), `ics` (a published calendar), `rss`, `drop` (a file placed in `drop/`), `links`, `notes`, `fixture`. Every source gets in by the highest rung the person's company allows: a personal API token, then a feed the app already publishes, then a file exported by hand. A widget that only works with a token is not finished.
A widget in the config:
```json
{ "id": "bugs", "view": "jira-cards", "size": "l", "surface": "panel", "accent": "red",
"adapter": "jira", "intervalSec": 60,
"options": { "jql": "labels = bug AND statusCategory != Done ORDER BY priority DESC" } }
```
`view` names how it is drawn (the page's views: `jira-board`, `jira-cards`, `jira-upcoming`, `jira-list`, `due`, `links`, `notes`, `embed`); without it the `id` is the view. Secrets are named by the env variable, never written in the config. `JIRA_SITE` in any option becomes the real host from `.env`.
Two more routes: `POST /api/notes` appends to `notes.md`; `PUT /api/links` saves the Links widget's list back into the config. `GET /api/icon` and `GET /api/avatar` fetch a site's favicon and a Jira assignee's picture once and cache them; `POST /api/open` opens a local folder or file through the system, only for a link already on the dashboard.
## The widgets here
The set this dashboard ships with. Yours may differ.
| id | size | what it shows | source |
|---|---|---|---|
| jira-board | XL | the real board's columns and cards, with Jira's own bar above: a search box, the avatar of everyone assigned on the board, and the two quick filters, Only my issues and Recently updated | the board id |
| links | Tall | quick links as small tiles, the site's favicon or a plain glyph then the name, grouped by kind with each new kind starting a new row; an Edit mode | the config |
| notes | S | an empty notepad and Save | notes.md |
| bugs | L | one query as Jira cards | a JQL |
| upcoming | L | everything with a due date, late first, then this week, next week and by month | a JQL out to 90 days |
Built and available but off the layout: `jira-list` (one query as rows), `due` (seven days by day), `sources` (one dot per source), `embed` (a live page inside a panel; a whole web page is the wrong size for a panel, so use it only for a page that stands alone).
## Make it yours
Change freely:
- **The colour.** The rail is the app's one strong colour; pick yours. Keep the page grey and the panels white, or the panels stop reading as surfaces.
- **The widgets.** Their order, their sizes, their accents, which ones are on the page at all.
- **The links, the tabs, the title.** All config.
- **The sources.** Any adapter can feed any widget whose data has the right shape.
Keep, or it stops being this design: the three parts of the window, the grid and its six sizes, the panel with its head row, the one meaningful colour, the four states, the word rules.
### Adding a widget
Ask for it in plain words. The result must:
1. take one of the six sizes and one of the three surfaces;
2. keep the panel and the head row as above, with at most one chip;
3. draw its body the way its source draws that data;
4. ship a fixture, and get its data by the highest rung the company allows;
5. add one row to the table above.
If it needs a colour, it does not need a colour. If it needs a word that is not data, cut the word.
## Not here
No dark mode, no settings page, no drag and drop, no login of its own, no framework, no bundler, no dependency beyond Electron, no brand logos as icons, no gauges, no toasts, no green, no shadow a widget did not ask for.
## The numbers
For an identical rebuild. Everything above holds without them.
- **Window** 1460 by 940. **Rail** 56px wide, lilac `#553985`; buttons 38px square, radius 10px, 2px apart, 20px white line icons; the current tab on white at .2 opacity. **Strip** 50px tall, white, hairline beneath. **Page** `#f4f5f7`; content 24px below the strip, 32px from the sides, at most 1400px wide. Below 720px the rail runs across the top.
- **Hairlines** `rgba(9,30,66,.14)`, or `.08` where softer.
- **Grid** rows 104px, gaps 16px; 4 columns below 860px, 1 below 520px.
- **Panel** corners 8px. **Head row** 40px, soft hairline beneath; title 13px weight 600; fact 11.5px in `#716f7a` (4.5:1 or better on white, on lane grey and on the page). **Chip** 2px by 8px padding, radius 6px. **Card** shadow `0 1px 2px rgba(20,20,40,.05), 0 3px 8px -3px rgba(20,20,40,.1)`. Faded body at .55 opacity.
- **Type** Segoe UI or the platform's own, 13px body. Ink `#1d1c22`, greys `#5f5d68` and `#716f7a`. **Orange** `#ff5a1f`, as text `#c23b08`.
- **Jira parts** lane grey `#f7f8f9`, lanes at least 220px wide; Jira's own lozenge colours and blue `#0c66e4`. **Scrollbars** thin and grey, only where the lanes or the page scroll.
- **Server** port 4810; the page polls every 30 seconds.
What you need
- A paid Claude plan, for the Code tab in the Claude desktop app, or a ChatGPT plan with Codex.
- A Jira Cloud site, the kind at yourcompany.atlassian.net, where you are allowed to make an API token.
- A computer you can install programs on. Your AI installs them for you; you only click Yes when asked. I built it on Windows.
- If it is a work Jira or a work laptop, check with your IT team before you start.
Build your own
- Open a folder in your AI. Make an empty folder, put design.md in it, and open it in the Code tab of the Claude desktop app, or in Codex.
- Paste the prompts. Start with the setup prompt from rebuild.md, the prompts file. Your AI installs everything it needs; click Yes if your computer asks. Then paste Prompt 1 and it builds the app. Send the rest one at a time.
- Connect Jira. Make an API token at id.atlassian.com, under Security, then API tokens. Ask your AI: “Copy .env.example to .env and open it in Notepad for me.” Fill in your Jira address, your email and the token, then save. The file stays on your computer. Never paste the token into the chat.
- Put it on your desktop. Ask your AI: “Make a shortcut on my desktop called My desk that opens the dashboard.” From then on, double-click it to open the app. You don’t need your AI to start it.
- Make it yours. Ask for what you want in a few words, like “Add a widget that shows my tickets due this week” or “Add a link to our team SharePoint.” Your AI does the rest.
- If something is not working. Tell your AI what you see, in plain words, and paste a screenshot or the error: “The board panel is empty and says 401 Unauthorized. Find out why and fix it.” Describe what is on the screen and let it work out the cause. If it is still stuck, ask: “Go back to the last checkpoint and try a different way.”
I built this for myself and share it as is, free to use and change. Your AI writes the code on your own computer, so results vary, and I can’t promise it will work on every setup. You are responsible for following your company’s rules on Jira, API tokens and AI tools.