Design system#
The platform is styled by a small set of design tokens and house components, taken from the homepage and kept honest by the component catalogue.
The component catalogue is the reference#
What ships is shown, live, on the catalogue page:
- openenergyplatform.org/styleguide/
- on a local setup:
http://localhost:8000/styleguide/
It renders every house component from the platform's own templates and its
compiled stylesheet, and shows the source to copy beside each one. On top sits
the token table, with the value each token has on the page you are looking
at, so an instance that overrides tokens sees its own values. Add
?tokens=bootstrap to see every component with Bootstrap 5.2's stock values:
anything that still looks like the Open Energy Platform there paints a value no
token controls.
The page is public, not indexed by search engines, and linked from no menu.
Principles#
- Plain, not boring. Clean surfaces, the brand blue for the one main action of a view, soft shadows on what floats.
- One look per thing. A button, a tag, a dialog looks the same on every page. Use a component from the catalogue; if none fits, add one, with its entry.
- Tokens, never literals. A component reads
var(--bs-primary), never#1F567D. That is what lets an instance restyle the platform without forking it; see theming an instance. - Colour means something. Green, cyan and yellow are status only, red is danger; none of them is used to make an action stand out.
- Accessible by default. Real buttons and links, a visible focus ring, motion only for those who have not asked for less. See accessibility.
- The platform's values stay: quality, transparency, collaboration, open data.
Add or change a component#
A house component has one name, snake_case and singular, in up to three places:
| Place | What |
|---|---|
theming/scss/components/_<name>.scss |
its styles, reading tokens only |
base/templates/components/<name>.html |
its markup, if it has any (an include) |
base/templates/styleguide/entries/<name>.html |
its catalogue entry |
The entry starts with a one-line when-to-use note, {# use: ... #}, followed by
the example the catalogue renders and shows as source. For an include, the entry
is the template's include tag with example arguments. Files whose name starts
with _ are helpers an entry includes, not entries.
The catalogue check workflow (.github/workflows/catalogue.yaml) fails a pull
request when
- a component has no entry (
python manage.py check_catalogue, which you can run locally), - the committed theme differs from what
npm run build:themebuilds, or - under
?tokens=bootstrapa component in the catalogue still paints an OEP colour (theming/literal_scan.mjs).
How to build the theme and where the tokens are defined is in the theming README .
Figma is the design tool#
New components and pages are drawn in Figma before they are built (contact us if you need access). The catalogue, not Figma, is the reference for what ships: when the two disagree, the catalogue shows the platform as it is.