# Existing frontend: detect, report, keep or restyle

Shared by `rpa-dashboard-no-ai` and `rpa-dashboard-ai`. The files named here sit
next to this one, in `rpa-dashboard-no-ai/templates/`. From the AI skill, reach them
through `../rpa-dashboard-no-ai/templates/`.

## 1. Detect

Run this before asking anything:

```
python <rpa-dashboard-no-ai>/templates/detect_frontend.py <project root>
```

It finds:
- React, Vue, Angular and Svelte apps (a `package.json` that lists one);
- a PyQt `QWebEngineView` host and the pages it shows;
- plain HTML pages and their stylesheets.

It skips `node_modules`, virtualenvs, dot folders (including `.claude`), build
output, coverage and `docs`. For each frontend it prints:
- one line: location, stack (with `web` or `desktop`), main colours and font;
- then every token block: the file, the selector (dark blocks are marked) and
  the tokens.

Tokens come from:
- CSS custom properties, including Tailwind v4 `@theme`;
- `<style>` tags in pages, components and PyQt hosts;
- the colours in a Tailwind v3 config.

It doesn't read theme objects in JS/TS (MUI, styled-components). If it prints
`colours none found`, look for one of those, or for colours hard-coded in rules,
before you report.

## 2. Report, then ask keep or restyle

- **No frontend:** say "No existing frontend found." Don't ask keep or restyle.
- **Frontend found:** say the script's first line: "Frontend found at `<path>`,
  stack `<stack>`, colours `<main tokens>`." If it found more than one, report
  each and ask which one the dashboard joins.
- Then ask one question: **keep its look, or restyle it?** Don't name presets in
  this question. Colours are asked next, and only for restyle.
- Never ask desktop or web. The stack comes from the report: `web` means the
  web path, `desktop` means the PyQt path.
- **No token blocks** (every colour is hard-coded): say so. A restyle can't be
  token-only then, so recommend keep, or ask before you pull the colours into a
  new token block.

## 3. Where the page goes

| Stack | Put the page |
|---|---|
| plain HTML | Next to the existing pages, for example `web/dashboard.html`. |
| React, Vue, Angular, Svelte | In the app's `public/` folder (`public/dashboard.html`), so it is served as-is. Port it into the app's components only if the user asks: best effort, with the page as reference. |
| PyQt web view | Next to the host's page. Use the desktop path (`bridge.py`). |

**AI skill (`rpa-dashboard-ai`):** a React app gets the React starter's components
ported in. Plain HTML, Vue, Angular and Svelte get this same page with the AI skill's
`templates/desktop/ai_sections.html` pasted in before `</body>`, placed as above. With no
Qt bridge it fetches `{API_BASE}` + the AI contract's endpoints. A port into components
uses `ai_sections.html` as the reference.

Don't edit existing pages to link to it. Tell the user the path to link from
their nav.

## 4. Keep

The new page uses the project's look. **No existing file changes.** Skip the colour
question.

- Fill the page's `body{}` block from the project's light tokens, and `body.dark{}`
  from its dark tokens. Copy the **values**, not `var(--…)` references: the page
  turns dark mode on with `body.dark`, which the project's own dark selector
  doesn't match. Above each block, note where the values came from, for example
  `/* kept from web/css/theme.css */`.
- Map each page token to the project token with the same role:

  | Page token | Project token for |
  |---|---|
  | `--accent`, `--accent-2` | the primary/brand colour, and its lighter or hover shade |
  | `--accent-dark` | the darkest brand shade (the log box background) |
  | `--accent-soft`, `--accent-soft-2` | the brand tint (secondary buttons) and its border |
  | `--bg-top`, `--bg-mid`, `--bg-bottom` | the page background; use the same value three times for a flat page |
  | `--glass`, `--glass-strong` | the card surface, and the raised or alternate surface |
  | `--border`, `--ink`, `--muted` | the border, the text and the muted text |
  | `--ok`, `--warn`, `--bad` and their `-bg` | success, warning and danger; keep the template's values if the project has none |
  | `--font`, `--font-display` | the body font and the heading font |
  | `--header-*`, `--primary-bg`, `--nav-active-bg`, `--progress-bg` | wherever the project shows its brand. A solid brand top bar, for example, is `--header-bg:<brand>; --header-ink:#ffffff`. |
  | `--blur` | `none`, unless the project uses frosted glass |

- **No match:** run `palette.py` on the brand colour to get the accent family.
  Keep the Tebra Sky value for anything else.
- **No dark tokens:** put `palette.py`'s dark accents on the Tebra Sky dark block.
- **Web fonts:** if the project loads its font with a `<link>` or `@import`, add
  the same line to the page's `<head>`.

## 5. Restyle

The existing files change **only inside their token blocks**.

1. Ask for colours (the skill's colour step): Tebra Sky, Superbill Ember or a
   custom hex.
2. Edit only the token lines that the detect report listed. Give each project
   token the chosen palette's value for its role (read the keep table from right
   to left):
   - the light block gets values from the palette's `body{}` block;
   - the dark block gets values from its `body.dark{}` block.

   Keep every token name, and keep any token the palette has no match for. Don't
   add blocks the project doesn't have.
3. **Fonts:** change only the font tokens. If the new font needs loading (Ember),
   add its `<link>` next to the project's other stylesheet links. That is the
   only other line that may change.
4. Leave hard-coded colours outside the token blocks alone, and list them for
   the user.
5. Build the new page with the palette's blocks from `themes.md`, the same way as
   when there is no frontend.
6. Show the user the diff of the existing files: `git diff` in a repo, otherwise
   each changed line. It must show only token lines, plus the font link if one
   was added.