Design System

Not live data. The outer Group is corr-scroll; the inner Group is corr-wrap. It has one label column and nine value columns. Headers use corr-head; row labels use corr-row-head. Values use the registered Paragraph styles is-style-corr-diag, is-style-corr-vlow, is-style-corr-low, is-style-corr-mid, is-style-corr-high, is-style-corr-vhigh. It scrolls rather than crushing the cells.

Reading 700px · wide 1100px · profiles 920px · documents 980px · breakpoint 720px · section rhythm 48px.

.ws-profile .card/.grid/.metric-table, .badge, .callout, .source-chip, .field-tag, code.issn, .dist-* and .ws-score__* belong to application markup, element contracts, or shortcodes. Use their registered equivalents where offered. Do not fabricate live charts or scores in the editor. The former standalone guide’s .sg-* classes are export-only, not shared styles.

WikiSignals is a reference tool, not a publication: people come to look up one record — a journal, a news domain — and check what independent source indexes say about it before citing it. The design is the design of a well-made reference manual: a tinted paper ground, white cards with hairline borders, tables that read at a glance, and a strict color discipline that does the explaining for the reader. Every claim on the page shows where it came from, so the interface never blends scores into a single verdict and never implies one.

The look is deliberately plain and legible rather than ornamented: the data is the subject, and the color comes from the blue ground and the two deep-blue bands, never from decoration. Two typographic registers carry that — a system sans for data, tables, and the search interface, and a text serif (Iowan Old Style / Palatino / Georgia, all locally installed) for long-form reference documents such as Sources & Definitions.

The palette is a color system, not decoration. Each color has exactly one job, and breaking the assignment is what makes a reference page confusing:

• primary (#1e4f9e) — links and clickable things, and nothing else. If it is blue, it clicks. Non-interactive data is never blue.
• metric (#5b21b6) — a record’s own value in a comparison: the numbers in the distribution charts and their markers. Never used for chrome.
• text (#16233c) and muted (#4a5a78) — plain, non-interactive data: tags, unlinked source names, table values, labels.
• good (#14603c) — a genuine computed “good” signal, which in practice means match-confidence scores. Open-access, APC, and document-type badges are descriptive, not evaluative, and stay neutral.
• warn (#7d5a00) — an active, per-record data-quality flag. Not a general note.
• bad (#9b2c22) — a failed or negative check. Rare.
• mono (#eaeff8) — the recessed chip/identifier surface for non-interactive data.

Surfaces: background #e8eef8 is the page ground — a light blue, so the card index reads as colored rather than grey around the white cards; surface #ffffff is every card; line #cddcef is every hairline border and rule, never a shadow.

Seven derived tints exist so a component never invents a hex, and each has one job: good-line #bfe6cf, warn-line #f0dfa8, bad-line #efc7c2 and metric-line #d9c8f5 ring a soft-tinted badge one step darker than its own fill; link-line #c7dafb rings a blue chip; link-hover #cfe0f8 is the deeper fill a blue chip takes on hover; row-tint #f4f8fd alternates data table rows, one step below the card so it never reads as a header. On the two bands, a secondary field steps back rather than competing with the header’s search: band-field rgba(255,255,255,.08), band-line rgba(255,255,255,.28), band-muted rgba(255,255,255,.72).

One more derived token sits in that layer for a different job: focus-halo #ffc14d, the gold the header search’s focus ping is drawn in (see Motion). It is the system’s only warm colour, and it is chrome, never a signal — it never appears inside a card and never marks a value, a flag, or a score.

The correlation matrix runs on a five-step ramp of its own, heat-1 #eff3ff through heat-5 #08519c — one hue from the ground up to a deep ink blue, so a denser cell reads as more of the same measure rather than a different one. Cells on heat-1 to heat-3 take ink text; heat-4 and heat-5 switch to surface text and gain weight. The diagonal sits on the recessed mono, because it has no value to report. The ramp means nothing anywhere else.

The two bands (header, footer) are band #16325f, a deep blue rather than black, with #ffffff text, and the wordmark’s middle word takes header-accent #a7c6f5. Every text/background pair in the system meets WCAG AA (4.5:1) at minimum: text on the ground 13.5:1 and on a card 15.7:1; white on the band 12.7:1 and the accent on it 7.3:1; primary on a card 7.9:1 and on the ground 6.8:1; muted on a card 7.0:1 and on the ground 6.0:1; primary on primary-soft 6.3:1; and the badge pairs good 6.5:1, warn 5.6:1, bad 6.3:1.

Two registers, one purpose each.

Sans (system UI stack, 22px/1.55 body) is the interface voice: cards, tables, metadata rows, badges, the search widget, the header and footer.

Serif (Iowan Old Style → Palatino → Georgia fallback) is the document voice: a reference page such as Sources & Definitions sets its running text in serif at 22px, with the masthead underlined by a 3px text rule. Tables, metadata grids, and captions inside a serif document switch back to sans: they are data, not prose. At or below 720px the document prose steps down to 20px and its masthead to 32px; the opt-in Display Heading style remains 44px.

Mono (data) carries identifiers only — ISSNs, DOIs, field names such as q-cwIPP — on the mono surface at 16px with a 4px radius.

The YAML display and headline roles are regular-weight serif: 44px/1.15 and 36px/1.2. They apply to the document masthead and document-section headings inside ws-doc, or explicit Heading styles Display (serif) / Headline (serif). They do not replace default interface headings (H1 48px/700, H2 36px/600, system sans). Heading level describes structure; select the optional style independently of level. A single H1 belongs to the Page template, unless a no-title/reference template deliberately delegates the H1 to page content.

Labels are the third voice: 16px, weight 600, uppercase, letterSpacing: 0.06em, in muted. Card headings use it, with a hairline line rule under the heading inside the card.

Sized elements

Every size comes off one of two scales; nothing is sized off-scale. Space, radii, padding, and rules are rem on a 0.25 step — a 4px grid: spacing presets 0.25 / 0.75 / 1.25 / 1.75 / 3 / 4.5rem, and radii 0.25 (sm), 0.5 (md), 0.75 (lg) rem. Type is rem on a 0.125 step — a 2px grid: 0.875 / 1 / 1.125 / 1.375 / 1.75 / 2.25 / 3rem, surfaced as the presets x-small 0.875, small 1.125, medium 1.375 (the body size), large 1.75, x-large 2.25, xx-large 3rem, plus normal 1rem for data and display 2.75rem for the document masthead. Hairlines are the single exception and stay 1px. A new size is snapped to the nearest step of its scale rather than written as a fresh number.

Content widths: contentSize 700px is the reading column for ordinary pages and single records; wideSize 1100px carries multi-column card grids, the metric lists, and the homepage’s column layouts. Two reference pages override their own column: the journal profile and its search page center on 920px (two-column card grid: main 1.4fr, side rail 1fr), and a serif reference document such as Sources & Definitions centers on 980px.

Responsive: at or below 720px every card grid collapses to one column, the homepage’s two-column hero stacks, and the press list drops to one column. Fixed-layout data tables keep a 34rem minimum width and scroll sideways rather than crushing their columns; label/value metadata tables wrap inside the card. Document cards reduce their padding from 24px to 20px on mobile.

Spacing rhythm: the page ground is padded from the viewport edge by the root gutter (28px); cards are separated by 20px and padded 24px; inside a card, related values sit 12–16px apart. Vertical rhythm between sections is 48px, and a section heading sits 28px above its content.

Concept — reference-card column: every page is a centered column of white cards on the tinted ground, and nothing floats. A card is the only container: identifiers, subject areas, metrics, source coverage, and reliability notes each get their own card; a record’s page puts them in a two-column grid (main + side rail) above 720px and stacks them below. Cards are separated by hairline borders and 20px of ground, never by elevation — the ground shows through between them, which is what makes a page scan as a set of blocks. Full-bleed bands (header, footer) stay square-cornered; only cards, chips, badges, and buttons are rounded.

Layout map:

• Header — full-bleed band bar, square-cornered, wordmark left and the domain search right; it never becomes a card. The search is a white pill (pill radius, 48px tall, 40rem wide while the band allows it, shrinking before it wraps) with 18px ink type — the same size as the search field on /journals — so it reads as the site’s one input, sitting on the band rather than floating over the page.
• Domain suggestion flow — Ajax Search Pro’s no-results dropdown offers “Submit Domain” beneath the configured no-results heading. Submission opens a native modal dialog, separate from the replaceable search results, with a status line, preliminary source-attributed data, and an explicit Close button. Keyboard focus stays in the dialog; Close or Escape returns focus to the initiating button when it still exists, otherwise to the header search. Saving a suggestion never publishes a record; administrators review a private queue at Settings → Domain Suggestions. Header/footer and page layout are unchanged. The prompt and dialog use the existing surface, line, primary and muted tokens; missing data says “Unavailable”, never a fabricated value or judgment. Dialog width is capped at 42rem, with 1rem viewport clearance, 24px padding and the card radius; long values wrap.
• Homepage — two columns at wide width: the lede and intro paragraph on the left, an Examples card of record pills on the right. Then sections whose ruled heading, card grid, and press card all share one wide left edge: six index cards in equal-width columns, the press-membership card full width with its list in two columns, partners as cards with logo thumbnails, and the closing image in the reading column.
• Directory (publication archive) — a ruled title, then the records as a dense grid of domain links (13rem minimum column) rather than a stack of plain titles. Every archive and search-result page title uses the same ruled treatment as a homepage section heading.
• Search (/journals) — a narrow 640px intro column holding the title, the one-line explanation, and the search field with its dropdown; below it, the 920px profile column that the field fills with cards once a record is chosen.
• Record profile — title card across the top, then the two-column card grid; the side rail carries source coverage and the reliability note.
• Sources (/journals/sources) — a serif document column: masthead with rule, contents card in primary-soft, then sections; each source index is one card with a metadata table.
• Term directory (/list/…, /rating/…) — a ruled term title, then the Google Visualization table restyled onto the system: hairline rows, recessed uppercase header cells, caption-size muted type, and the ⓘ that links a row to its record in blue. The page’s column runs 94% wide (capped at 1600px) so the six columns fit, and the figure scrolls sideways when they do not. Its chart chrome belongs to style.css with the rest of the system, not to the template.
• Publication record — the domain title card, then metric cards in a grid, each card keeping its own source attribution.
• Footer — full-bleed band bar, square-cornered, with the data-source and rating dropdowns and the copyright line. The dropdowns are secondary fields on the band — translucent white fill, hairline, label in band-muted — because only the header’s search is a primary input.

There is no elevation. Depth is expressed only by surface and hairline: the tinted ground behind white cards, line borders, and the recessed mono chips inside cards. No box-shadows anywhere except the search dropdown, which floats over the page and takes a single soft shadow (0 10px 28px rgba(20,30,50,.12)) to separate it from the content beneath.

The domain-suggestion dialog is a native top-layer overlay, not an elevated card: it keeps its surface fill and hairline border without a shadow. Its backdrop is text ink at 65% opacity, used only to separate the active interaction from the inactive page.

Rounded: lg 12px on every card, md 8px on chips and badges-with-value, sm 4px on callouts, inline identifiers, and the code/mono pills, pill 999px on status badges. Buttons and inputs are md. Nothing that touches the viewport edge is rounded — the header and footer bands are square. Borders are always 1px line; the only heavy rule in the system is the 3px text rule under a serif document masthead.

• Card (is-style-card, and the site’s .metrics groups) — surface ground, 1px line border, lg radius, 24px padding. Heading inside: uppercase label type, muted, with a 1px line rule under it. The front page’s index lists (.metrics-list) run one step above the caption size — 15px — because they are the page’s actual links, not metadata.
• Badge — pill radius, 14px/600 text, 6px 12px padding, and one job per state: neutral (line fill, ink text) for the descriptive badges the search app emits — document type, open access, APC; good for the one computed good signal and for a source that vets titles; warn for a per-record data-quality flag or a “maybe”; bad for a failed check; and badge-scored (metric family) for a source that supplies a score rather than vetting anything — CWTS, SCImago, Kanalregisteret. The neutral badge fills with line, not the recessed mono tint, because a badge also sits on the page ground, where mono disappears.
• Editor chip — Paragraph styles Chip (is-style-chip) and Linked chip (is-style-chip-link), 16px/1.5 with 6px 12px padding and md radius. Use a Row parent to shrink-wrap; a linked chip must contain a link covering its full label. Neutral chips use mono/text; linked chips use primary-soft and an actual primary link with link-line. The Identifier Paragraph style (is-style-identifier) uses the mono font and sm radius.
• Source chip — the application’s separate coverage component, 14px/600, md radius. Absent sources keep the ground with a muted label, a dashed line border, and a strikethrough: two non-color cues, and legible anywhere. Linked sources are link-soft/link with a link-line border.
• Metric table — Table style Source-attributed metrics (is-style-metric-table), sharing its treatment with the application’s .ws-profile .metric-table; full width, 16px; header row uppercase 14px muted on the recessed mono surface with a line bottom border, because a header cell is structure and not a link; values weight 700 with tabular numerals; source column 14px muted.
• Score bar () — the record’s own value as a solid metric fill on a mono track, no gradient.
• Distribution chart — inline SVG, 280×64, metric fill at 16% under a 1px metric line, a 1.5px vertical marker and a 3px dot at the record’s own value, axis endpoints in 9px muted. Caption states the percentile and the corpus count.
• Correlation matrix — one .corr-wrap grid: an 8rem label column then nine cells at minmax(3.5rem, 1fr), 2px gap, 16px tabular figures, right-aligned. The cells are core/paragraph variations (is-style-corr-*) on the five-step sequential heat-1…heat-5 — ink text on steps 1–3, surface at weight 700 on 4–5, because the dark end cannot hold ink. Axis labels (.corr-head, .corr-row-head) are transparent, ink at 600, row heads in mono: structure carries no tint, so the cells are the only colored things in the matrix. The diagonal is a state of its own rather than a step of the ramp — a mono cell reading -- in muted, because a value against itself is 1 by definition and carries no information. It documents pairwise Spearman rank correlation across the nine numeric scores (sidebar labels: Heat: self, Heat: very low … Heat: very high), and it scrolls rather than squashes — .corr-scroll wraps it and the grid keeps a 40rem min-width, so the cells stay a grid on a narrow viewport instead of collapsing.
• Document section — Group style Document section (is-style-doc-section), 48px outer rhythm, a 1px ruled direct-child H2 and 28px after that heading. Nested/subsection headings keep their own style and size. The old .ws-doc .doc-section remains an alias. Contents uses a neutral heading: only its actual links are blue.
• Callout — shared by registered Group styles and the application’s .callout alias; background ground, 1px line, sm radius, 16px text; the documentation variant (callout-note) uses warn-soft with the shared warn-line border, and the one alarming variant (per-record data-quality flag, callout-flag) uses warn-soft/warn.
• ASP header search — stable .asp_w_container / .asp_m selectors mirror the former ASL selectors, retaining the white 48px pill, 40rem flexible width, 18px ink input and the reduced-motion-safe focus halo. No styles depend on the numbered instance ID. ASP generates instance-ID rules after the theme stylesheet; narrowly scoped !important overrides in style.css deliberately counter its outer border, probox margins and input geometry. Preserve these integration overrides rather than reintroducing instance-specific selectors. The no-results heading remains controlled by ASP settings; the theme’s asp/no-results.php owns the following suggestion prompt and button.
• Domain-suggestion dialog (.ws-domain-dialog) — system sans at 16px/1.55, 28px semibold heading, 14px muted source labels and notes, and ink values separated by hairline rules. A definition list stacks labels above values on every screen; long domains and URLs wrap, and the dialog scrolls vertically within a viewport-height cap with 1rem clearance. Close uses a recessed neutral fill with primary text. An indeterminate progress element and a polite live status report the request; an error uses bad text plus an explanatory message, never color alone. Closing the dialog does not cancel a server-side submission. Keep the dialog attached outside ASP’s replaceable result containers so it survives search updates.
• Button — primary ground, surface text, md radius, 12px 24px padding, 18px semibold; hover darkens to primary-dark.

theme.json owns the shared palette, font stacks/sizes, spacing presets, radii and eleven derived values (settings.custom.rounded / settings.custom.derived), plus default elements and opt-in serif Heading variations. style.css maps these presets to semantic --ws-* variables and implements registered components and legacy application aliases. It is loaded on the frontend and, via add_editor_style, in the block editor. Component group gaps use settings.custom.component-gap tokens in theme.json style variations, with matching shared child-margin selectors because WordPress does not consistently apply variation gaps to editor flow layouts. Cards/contents use 12px; definitions/callouts use 8px.

wp-content/themes/wikisignals/assets/design-system.json is the single catalogue of registered style names, editor labels, target blocks, and context helpers. functions.php registers its styles; the development generator reads that same file. Additional CSS classes in the editor are entered without a leading dot. Prefer the block’s Styles selector for is-style-* treatments. Badges, chips and identifiers require a wrapping Row for compact alignment. Heat cells require corr-wrap inside corr-scroll, with one label and nine value columns.

The generated native guide demonstrates these real theme styles using editable core blocks. It has no embedded CSS, inline style attributes, runtime scripts or .sg-* classes. It includes a class catalogue and separates registered styles from structural helpers and application-only selectors. Palette swatches are labeled reference samples, not interface links or rating signals; Color swatch is an optional Paragraph style for that reference use. Spacing/radius tokens are listed with the actual components using them rather than painted with a parallel specimen stylesheet. Application score bars and charts stay application-only.

Run tools/design-system/generate.command for Page-ready HTML; paste the complete file into a Page’s Code editor, not a Custom HTML block, and return to Visual editor. Use the default Page template and set its title to WikiSignals design system; the guide starts at H2. Generation never edits a Page or the database. Theme/design drift checks stop the native build rather than silently restyling a specimen to match only the specification. Major design changes still require generator review and rendered desktop/mobile/editor checks. The earlier standalone export remains available separately; its .sg-* styles are not editor utilities.

• Do keep blue for links only. A blue element that does not click is a bug.
• Do keep header cells, matrix axis labels, and other structure on the recessed surface or untinted: a header is not a link, so it is never blue.
• Do give a grid of cells its own row/column rhythm and zero the flow gap on every cell — including the first — so labels and figures line up across the row.
• Do attribute every score to its own source, next to the number, in the table’s own source column. Never blend two sources into one figure.
• Do keep the two-column grid for record profiles above 720px and stack it below.
• Don’t add shadows, gradients, or glow — depth comes from the ground showing between cards. The header search’s focus halo is the single exception: it reads as a halo on the band, not as elevation, and it exists for 6s of focus state, not as a resting style.
• Don’t color non-interactive data with primary, or evaluative data with good when the flag is merely descriptive.
• Don’t round anything that meets the viewport edge, and don’t put a card inside a card.
• Don’t use emoji in generated content; the two glyphs inherited from the source mockups (the lock and diamond in open-access badges) are the only exceptions.

No photographic treatment is applied — the system’s imagery is generated SVG: distribution curves, categorical bars, and the favicon/screenshot thumbnails the publication records already fetch. Screenshots and logo thumbnails are shown as-is, filter: none, clipped by the card’s sm/md radius rather than styled into a house look.

Motion is limited to state feedback, never decoration: 120ms ease on link underlines and primary-soft hover fills, 150ms on the search dropdown’s appearance, and the input’s border turning primary on focus. The dropdown opens on input without sliding or fading the results in. Everything sits behind prefers-reduced-motion: reduce, which removes transitions and the theme’s smooth scroll.

One exception, and only one: the header search pill pings a focus-halo gold ring on focus — three beats of 2s each, blooming from the pill’s own edge (0.5rem of spread, 0.25rem of blur) outward to 1rem of blur as it fades. Gold rather than blue because the pill sits on the band, where a blue halo sinks into the band and never shows; the border still turns primary, as the field on /journals does, so the site’s two search fields keep one focus language. It marks arrival at the site’s one primary input — reached by click, by Tab, or by a jump link — and it stops after six seconds rather than running on while someone types. It is state feedback that happens to move, not depth, so it does not license a shadow anywhere else.

Precise, unhyped, and specific about provenance. Sentences are short and declarative, and they say what a number is and what it is not: “each figure kept attributed to its own source” is the house voice. Use “record”, “source index”, “signal”, “match basis”, and the source’s own name (Crossref, DOAJ, Kanalregisteret); name the column too when a reader may need to find it (q-cwSelfCite).

Avoid: “trust score”, “trustworthy”, “safe to cite”, “AI-powered”, “verified journal” — the tool does not make that judgment and the copy must not imply it. Avoid marketing adjectives (“powerful”, “seamless”, “cutting-edge”) and exclamation marks. Second person is fine for instructions (“Search by title, ISSN, or DOI”), never for reassurance. Where a judgment is possible, hand it back to the reader: “Cross-reference these signals with the source’s own editorial policy before citing.”

For domain suggestions, say “saved for review”, not “added” or “published”. Fetched data is preliminary, not a WikiSignals assessment; missing data says “Unavailable”. Confirming a saved suggestion must not imply that notification email was delivered. The private Settings queue is the review mechanism even when email is unavailable. Duplicate retries must not imply a second queue entry, and an interrupted response must not claim that nothing was saved. Implementation, authorization, validation and deployment details belong in wp-content/plugins/wikisignals/DOMAIN-SUGGESTIONS.md, not in the visual design system.

name: WikiSignals
description: Reference reliability data for Wikipedia editors — journal and news-domain signals, kept attributed to their source
colors:
  background: "#e8eef8"
  surface: "#ffffff"
  text: "#16233c"
  muted: "#4a5a78"
  line: "#cddcef"
  band: "#16325f"
  primary: "#1e4f9e"
  primary-dark: "#163c7d"
  primary-soft: "#dbe7fa"
  metric: "#5b21b6"
  metric-soft: "#ece2fb"
  good: "#14603c"
  good-soft: "#dff2e7"
  warn: "#7d5a00"
  warn-soft: "#fbf0d6"
  bad: "#9b2c22"
  bad-soft: "#fae5e2"
  mono: "#eaeff8"
  header-accent: "#a7c6f5"
  heat-1: "#eff3ff"
  heat-2: "#bdd7e7"
  heat-3: "#6baed6"
  heat-4: "#2b6cb0"
  heat-5: "#08519c"
  transparent: "transparent"
typography:
  display:
    fontFamily: '"Iowan Old Style", "Palatino Linotype", Palatino, Georgia, "Times New Roman", serif'
    fontSize: 44px
    fontWeight: 400
    lineHeight: 1.15
  headline:
    fontFamily: '"Iowan Old Style", "Palatino Linotype", Palatino, Georgia, "Times New Roman", serif'
    fontSize: 36px
    fontWeight: 400
    lineHeight: 1.2
  body:
    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif'
    fontSize: 22px
    fontWeight: 400
    lineHeight: 1.55
  label:
    fontFamily: '-apple-system, BlinkMacSystemFont, "Segoe UI", Helvetica, Arial, sans-serif'
    fontSize: 16px
    fontWeight: 600
    lineHeight: 1.4
    letterSpacing: 0.06em
  data:
    fontFamily: '"SF Mono", Consolas, Menlo, Monaco, monospace'
    fontSize: 16px
    fontWeight: 400
    lineHeight: 1.5
rounded:
  sm: 4px
  md: 8px
  lg: 12px
  pill: 999px
spacing:
  # The same six steps theme.json slots as spacingSizes 20-70; those numeric
  # slugs are what block CSS references, e.g. var(--wp--preset--spacing--50).
  xs: 4px
  sm: 12px
  md: 20px
  lg: 28px
  xl: 48px
  2xl: 72px
components:
  button-primary:
    backgroundColor: "{colors.primary}"
    textColor: "{colors.surface}"
    rounded: "{rounded.md}"
    padding: "12px 24px"
  card:
    backgroundColor: "{colors.surface}"
    border: "1px solid {colors.line}"
    rounded: "{rounded.lg}"
    padding: "24px"
  chip:
    backgroundColor: "{colors.mono}"
    textColor: "{colors.text}"
    rounded: "{rounded.md}"
    padding: "6px 12px"
  chip-link:
    backgroundColor: "{colors.primary-soft}"
    textColor: "{colors.primary}"
    rounded: "{rounded.md}"
    padding: "6px 12px"
  callout:
    backgroundColor: "{colors.background}"
    textColor: "{colors.text}"
    border: "1px solid {colors.line}"
    rounded: "{rounded.sm}"
    padding: "16px 20px"
imagery:
  filter: none