Design direction for the Project Bluefin factory dashboard website. Use whenever modifying Astro pages, CSS, charts, or visual components under `src/`. Enforces deliberate, subject-grounded choices over templated dashboard defaults.
Design direction for the Project Bluefin factory dashboard website. Use whenever modifying Astro pages, CSS, charts, or visual components under `src/`. Enforces deliberate, subject-grounded choices over templated dashboard defaults.
The factory dashboard at factory.projectbluefin.io is the public face of an
operating-system QA lab: Argo Workflows, KubeVirt VMs, bootc images, and
behaviour-driven tests running on a homelab cluster. Every page is an evidence
surface, not a generic admin panel. Treat the site as a design brief with a
specific subject, audience, and job.
When to Use
Adding or revising pages under src/pages/*.astro.
Editing global styles, layout components, or the design token set.
Adding or restyling charts, tables, cards, or navigation.
Choosing typography, colour, spacing, or motion for any site element.
Replacing placeholder or templated visuals with subject-specific treatment.
When NOT to Use
Backend/collector changes in .github/workflows/ or scripts/ (use the
matching infra or CI skill).
Argo WorkflowTemplate or Kubernetes manifest changes (use argo-workflows.md
or kubevirt-vms.md).
Pure content updates that do not change visual design (for example fixing a
typo in an existing paragraph).
Core Process
Pin the brief. Before opening a design file, state the page's subject,
audience, and single job. For this site the subject is always one of:
image release freshness, test evidence, provisioning infrastructure, build
lineage, application telemetry, or adoption metrics. The audience is a
contributor or operator who needs to answer a specific question in under ten
seconds. The job is to make the evidence scannable and trustworthy.
Ground every choice in the subject. Pull visual language from the
Bluefin world: atomic updates, reflink copies, container disks, bootc
images, GNOME Shell tests, Zot registry caches, USB4 mesh links. Use those
concepts as metaphors for layout, colour, and motion instead of generic
dashboard tropes.
Hero as thesis. The top of every page should answer the most important
question first. A big number with a tiny label is the default; only use it
when the number itself is the answer. Prefer a clear status statement, a
small multiples grid, or a live chart that shows the characteristic thing
about that page.
Design the type, do not just set it. The current site uses Inter as a
neutral workhorse. When you add new elements, make deliberate choices about
weight, tracking, case, and scale. Use uppercase labels and monospaced data
deliberately, not as decoration. Keep line lengths comfortable for reading
technical prose.
Structure must carry information. Numbered markers, eyebrows, dividers,
and badges should encode real order or real status. Do not use "01 / 02 / 03"
unless the items are a true sequence such as a pipeline stage. Prefer labels
that state the relationship: "Source", "Assemble", "Verify", "Ship".
Colour is status, not wallpaper. The existing palette is dark with
cyan/blue accents, green for healthy, amber for warning, rose for failure,
and purple for cluster/fabric. New colours must earn their place. If you add
a hue, assign it a semantic role and document it. Avoid gradients that do
not encode data.
Use motion with intent. Motion should clarify state transitions, reveal
evidence on demand, or mark live data. Avoid scattershot entrance animations.
One orchestrated moment — a chart drawing itself on first view, a table row
highlighting on hover, a status pulse — is usually enough.
Match complexity to the page's vision. Dense matrix pages (Tests, Builds,
Images) need tight grids and high information density. Narrative pages (About)
need generous whitespace and larger type. Do not apply the same card density
everywhere.
Prefer local assets and ESM bundles. Load ECharts via import * as echarts from 'echarts' and page scripts from src/scripts/. Avoid CDN scripts so the
site builds offline and Cloudflare Rocket Loader cannot rewrite boot paths.
Test the design in built output. A change is not done until npm run build succeeds and the rendered HTML contains the intended structure,
wording, and chart containers. Use page smoke tests to lock the behaviour.
Common Rationalizations
Rationalization
Reality
"It is just a dashboard; neutral is fine."
Neutral is invisible. The site represents a distinctive operating-system factory; its visuals should reinforce that identity.
"I will reuse the same card style from the last page."
Reuse is fine, but blindly copying layout without asking what that page's job is produces generic pages.
"A numbered list looks more designed."
Numbers imply sequence. If the content is not ordered, use status labels, categories, or no marker at all.
"More animation makes it feel premium."
Scattered motion cheapens the experience. One justified animation beats five decorative ones.
"The data is the design."
Data needs a designed container. Poor spacing, weak hierarchy, and default chart styling undermine trust in the evidence.
"I can pull this library from a CDN."
The site is built for GitHub Pages and proxied through Cloudflare. Bundle dependencies locally to avoid runtime failures and Rocket Loader issues.
Red Flags
Adding a new page that looks interchangeable with any other status dashboard.
Introducing a colour that has no defined semantic role.
Using numbered markers for non-sequential content.
Loading external scripts or fonts without a local fallback.
Hiding chart sections or data tables when state is missing instead of rendering
an explicit unavailable block.
Applying the same card density to every page regardless of its information
architecture.
Changing visual style without updating the page smoke test or checking the
built HTML.
Adding hero KPIs that do not answer the page's primary question.
Verification
The page's subject, audience, and single job are stated in the design
rationale or PR description.
Colour, type, and layout choices are justified by the subject matter, not
copied from a generic dashboard.
Any new colour has a documented semantic role (status, family, fabric,
etc.).
Structural markers (numbers, eyebrows, dividers) encode real information.
Motion, if used, has a single clear purpose.
ECharts and other JS dependencies are imported as ESM modules, not loaded
from a CDN.
npm run build succeeds and npm test passes for the affected pages.
Built HTML shows no emojis and follows the dark colour-scheme contract.
