| name | tpw-frontend-styling |
| description | Design-token, CSS, and Django-template conventions for Target Pathogen Web. Load before editing any file under static/css/pages/, static/css/components/, or tpweb/templates/ — covers the hex-color rule, the token inventory, reusable component idioms (stat cards, panels, chips), dark mode, motion, cache-busters, and how to verify a template/CSS change without a local execution environment. For Cytoscape.js graph rendering specifically (static/js/pages/metabolic-*.js), load tpw-metabolism-graphs instead/in addition. |
Target Pathogen Web — frontend styling conventions
The hard rule (non-negotiable, from CLAUDE.md)
Hex colors are allowed only inside tpweb/templates/base/masterpage.html's :root block
(light-mode values, then a dark-mode override block further down in the same file). Every other
CSS file — everything under static/css/ — must reference a var(--tp-*) token. Before writing
background: #... or color: #... anywhere else, stop and find (or add, in masterpage.html only)
the token instead. After editing any CSS file, grep the diff for #[0-9a-fA-F]{3,8} to confirm
none slipped through.
Token inventory (defined in masterpage.html, light values + parallel dark overrides)
- Colors:
--tp-color-text-{primary,secondary,muted,soft}, --tp-color-link{,-hover},
--tp-color-brand-{900,800,700,600,500,300,200,100,050}, --tp-color-rose-{900,700,500,300,100,050},
--tp-color-sage-{900,700,500,200,100,050}, --tp-color-amber-{900,700,500,200,100,050},
--tp-color-nav-{900,800,700,600}, --tp-color-surface{,-soft,-muted,-panel,-alt},
--tp-color-border{,-soft,-strong,-accent}, --tp-color-{success,info,idle,warning,danger}-{ink,bg,border}
(this is the semantic set to use for "good/present" vs "warning" vs "error" states — reach for
these before raw brand/rose/sage/amber), --tp-color-structure-* (3D-viewer-specific),
--tp-color-on-accent, --tp-color-highlight, --tp-color-selection.
- Spacing:
--tp-space-1..8 = 4/8/12/16/20/24/32/40px.
- Type:
--tp-font-size-{xs:0.78rem, sm:0.88rem, md:0.98rem, lg:1.12rem, xl:1.28rem, 2xl:clamp(...)},
--tp-font-label: 0.75rem (the uppercase-micro-label size used everywhere), --tp-font-weight-{normal,medium,semibold,bold}.
- Shadows:
--tp-shadow-{xs,sm,md,lg}.
- Radius:
--tp-radius-{lg:26px, md:20px} only. There is no small-radius token — 12px is the
established de-facto small-card radius used throughout protein-detail.css and friends; reuse
that literal value for small cards rather than inventing a new token or picking an arbitrary number.
File layout
One CSS file per page under static/css/pages/<page>.css (CLAUDE.md rule). Shared, cross-page
component classes live in static/css/components/ui-system.css — e.g. .tp-view-head,
.tp-view-head-copy, .tp-view-head-actions, generic .tp-btn*. Check ui-system.css before
assuming a class is undefined — a grep across static/css/ for the class name will tell you
whether it's page-local or shared; don't duplicate a shared class's styling into a page file.
Reusable component idioms — extend these, don't invent parallel ones
.tp-ui-panel / .protein-card-style panel shell: bordered card, tp-shadow-xs, hover raises to
tp-shadow-sm and darkens the border..section-head.tp-ui-panel-head: the h2 + subtitle + optional right-aligned tools/button row that
opens every content card..target-evidence-card (in protein-detail.css): the "stat card" idiom — small uppercase
.target-evidence-label + a bold .target-evidence-value + optional .target-evidence-meta
key/value rows below a hairline divider. Modifiers: --compact (small text value instead of the
large display-font number, for short strings), --warning (amber/warning tint), --secondary
(muted background variant), --fpocket/--p2rank (colored left accent bar). Reach for this
before building a new stat-card pattern from scratch.- The "seamless mosaic" grid trick for a hairline-divided card grid with no per-item borders:
container gets
gap: 1px + background: var(--tp-color-border-soft), each grid item gets
background: var(--tp-color-surface) — the 1px gaps read as thin dividers. See
.target-profile-grid in protein-detail.css.
.tp-chip / .tp-chip--{sm,meta,link,count,ec,go,...} for small pill labels/links..tp-btn / .tp-btn--{primary,neutral,outline} + .tp-btn--sm/md, always paired with
.btn for base sizing..tp-state-note--{empty,error} for "nothing here yet" / error inline messages.
Cache-busters
Static files are loaded from templates with a ?v=N query-string cache-buster. Bump it in
every template that loads a static file you changed — grep across tpweb/templates/ for the
file's name to find every include site, since the same JS/CSS file is often loaded from more than
one template. Watch for replace_all hitting the wrong spot when two different files happen to
share the same old version-number string; if that happens, re-grep with more specific surrounding
context rather than trusting a blind global replace.
Modifier classes for content that varies by context, not a shared default on the base class
If a shared base class currently hardcodes context-specific content (e.g. a ::after { content: "KEGG" } badge on a class that's reused for multiple different external-link types), don't leave
the hardcoded value in place once a second variant is needed — split it into modifier classes
(--kegg, --metacyc, etc.), each with its own ::after content, and update every existing call
site to add the right modifier. Leaving the base class's default in place "for the common case" is
how a second call site silently inherits the wrong label.
Django {% trans %} string safety
When a translated string needs to contain a literal apostrophe, wrap the whole {% trans %} value
in single quotes rather than escaping a double quote inside it — Django's template tag parser is
strict about quoting, and an escaped \" inside a {% trans "..." %} is a real parse risk, not
just a style preference.
Dark mode
masterpage.html defines a complete parallel dark token set (light block first, dark overrides
further down, activated via .tp-dark on a root ancestor and/or prefers-color-scheme). If a
component only ever references var(--tp-color-*) tokens, dark mode is automatic — do not add a
.tp-dark .my-class {} override unless there's a genuine asymmetry the token swap doesn't cover
(rare — e.g. quick-nav's active state needed a stronger token specifically in dark mode).
Motion
Always respect prefers-reduced-motion: reduce — kill both animation and transition in
that media query, not just one (a common half-fix that leaves a static ghost element behind).
When staggering an entrance animation across a set of sibling cards with :nth-child/:nth-of-type,
prefer :nth-of-type if any non-animated structural element (e.g. a section-divider <div>)
might be interspersed among the animated cards. :nth-child counts position among all siblings
regardless of tag; :nth-of-type counts position only among same-tag siblings. If the cards are all
<section class="protein-card"> and dividers are <div>, :nth-of-type keeps the stagger's
per-card delay stable no matter how many dividers get inserted between them — :nth-child would
silently reassign delays to the wrong cards.
Icons
Reuse tpweb/templates/components/icons/*.html (e.g. check.html, download.html) via
{% include %} instead of inlining a duplicate SVG — check that directory before hand-writing an
SVG that might already exist there.
Verifying a change with no local execution environment
This working setup typically has no local Docker/Python/browser — a rendering check isn't
available. After any template edit:
- Grep-count matching Django tag pairs to confirm balance:
{% if %}/{% endif %},
{% for %}/{% endfor %}, {% with %}/{% endwith %}, {% regroup %} (no closing tag of its
own — it lives inside a surrounding {% for %}).
- Grep-count matching HTML tag pairs for any structure you touched (
<div>/</div>,
<section>/</section>, <dl>/</dl>, etc.).
After any CSS edit, grep the diff for stray hex codes (see the hard rule above) and confirm brace
balance ({ vs } counts should match).
Flag explicitly to the user that visual changes need a live check in their actual environment —
tag/brace balance proves the syntax didn't break, not that it looks right.
