121 lines
5.9 KiB
Markdown
121 lines
5.9 KiB
Markdown
# 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.
|