The Mediovsky design system.

Brand & logo.

The Mediovsky wordmark is non-negotiable. Indigo dot accent (#3C3FDE) is the only brand color. Never recolor, distort, or rebuild the mark.

Logo variants

logo.svg · light bg

logo-dark.svg · dark bg

Sizes & clear space

Default · 48px

Nav · 32px

Min · 24px

Minimum height 24px. Always leave clear space equal to the height of the “M” on all sides.

Color.

Indigo accent #3C3FDE is the only brand color. Everything else is neutral. Dark mode uses lifted indigo #7A7DFF for contrast.

Brand accent

Light theme tokens

Dark theme tokens

Semantic colors

Use sparingly. Only for status feedback. Avoid in editorial content (indigo accent is enough).

Typography.

One typeface (Inter) used at varied weights and sizes. Editorial mark: light weight (300) for display, regular (400) for body, indigo italics for emphasis (set via <em> with font-style:normal).

Type scale

Leading scale

Control sizes

Reading measures, in characters

Container widths, in pixels

Breakpoints

Border widths

Spacing & grid.

8-point spacing system. 8-column grid with 32px gutter. 1240px max container width.

8-point spacing scale

Grid

Press G on any page to toggle live grid overlay.

Radius & shadow.

Four steps, plus a pill and a circle, read from the token block in public/site.css rather than written here. A corner tracks the size of the box it is on. Shadow only on sticky and floating elements.

Shadows

none · sticky-nav (1) · floating (2) · modal/menu (3)

Motion.

Three steps, and the step is chosen by what moves, not by how long it ought to feel. Reach for the one that describes the movement and the tempo takes care of itself.

Two kinds of movement are deliberately not on this scale, and both say so where they are written with motion-ok:. A value drawing itself (a meter filling, a ring closing, a bar growing) runs from 250ms to 1.1s, because its length is tuned to the distance drawn: that is a fact about the data, not about the tempo of the interface. A loop (a spinner, a pulse) has a rhythm rather than a duration. Everything else is one of the three steps above, and F263 fails the build if it is not. Under prefers-reduced-motion the whole scale is switched off.

Buttons.

Two shapes only: .pill is the outlined default, .pill--solid the filled call to action. Both hover to accent blue. Do not hand-roll a third: the filled one existed as four slightly different inline copies until August 2026.

Primary actions

Icon buttons

Forms.

Chips & tags.

Cards.

List items.

Text-forward article list used on homepage, category, author, latest. Date on left, content middle, thumbnail right (8-col).

Pagination.

Tabs.

Alerts & toasts.

Toast

Skeletons & empty states.

Empty state

Iconography.

Stroke icons, 1.6 stroke width, 14-20px. Source: Lucide-style custom. Always currentColor.

Badges & labels.

Status pills and disclosure labels. Use to flag content type (Featured, Sponsored), status (Live, Beta, Draft), or recency (New, Updated).

Editorial labels

Status pills

In context: article card

Marquee ticker.

Continuous horizontal scrolling band. Pure CSS animation, pausable on hover. Use sparingly. For breaking headlines or issue announcements.

Default: dark band

Accent variant

Back to top.

Floating button bottom-right of viewport. Appears after scrolling past 600px. Site-wide. Already active on every page.

Theme toggle morph.

Sun and moon icons cross-fade with a 180° rotation when switching themes. Both icons in DOM, opacity flipped by html[data-theme] attribute.

Note: this demo button shares the global toggle logic (any element with #theme).

Avatars.

Five sizes, with optional status dot. Use initials as default; image when available. Stack overlapping for multi-author or reader lists.

Sizes

With status

Stack (multi-author)

Tooltips.

Hover bubble with arrow. Four positions. Use sparingly. Most labels should be visible without hover.

Dropdowns.

Custom select with option descriptions. Use when native <select> can’t carry enough information.

Search input.

Standalone input with leading icon and trailing clear button. For pages without the ⌘K overlay.

Toast queue.

Stacked notifications, auto-dismiss after 5s. Use for transient feedback only. Not for errors that need action.

Notification bell.

Bell icon with unread count badge. Dropdown shows latest notifications.

Count-up & sparkline.

Animated numerics for stats. Use on first view, not in re-renders.

Counter

Sparkline in stat card

Loading button.

Replaces text with spinner during async operation. Pointer events disabled.

Progress stepper.

Multi-step form indicator. Done state is solid, active is outlined, upcoming is muted.

Confetti.

Celebration animation after positive actions (subscribed, completed survey). CSS only. No canvas needed for this scale.

Newsletter sticky bar.

Bottom-of-viewport CTA that appears after the user scrolls 60% of an article. Dismissible.

⌘K hint pill.

Subtle floating pill on first visit, hints at the keyboard shortcut. Dismiss after one use.

Reading rail.

Floating vertical column beside an article: share, save, TOC, font size. Hidden < 1300px.

Section dividers.

Five variants for article breaks. Use line for default, ornament for editorial pauses, stars for chapter-like breaks.

Quote variants.

Five quote styles for different editorial weight. Big for pull-out, small for inline, portrait for testimonials, cols for long.

Big (pull quote)

Small (inline)

With portrait

Two columns

Footnote & sidenote.

Footnotes for citation, sidenotes for tangent. Both keep article body clean.

Footnote (bottom-of-article)

Sidenote (margin)

Reading progress circle.

Circular SVG progress, replaces linear progress bar in compact contexts (reading rail, mini player).

Highlight on hover.

Subtle hover effect on key phrases. The underline grows into a full highlight on hover. Use for callouts inline.

Bookmark moment.

Reader selects a passage; a floating action lets them save the quote with the article reference.

Caption styles.

Four caption variants for images: default, italic editorial, source attribution, rich (with label).

Page transitions.

Four built-in transitions between pages. Use sparingly. Default is fade only.

Glitch on hover.

RGB-shift glitch effect. Use with extreme caution. Only for one-off emphasis, never on body text.

Accordion.

Native <details> elements styled as a card. Use for FAQ, methodology notes, advanced settings, anything secondary that shouldn’t take vertical space by default.

Card variant

Plain variant (no card)

Built on native <details> for accessibility: works without JS, keyboard-navigable, screen-reader friendly.

Dialog: basic.

Centered modal with title, body, action footer. Use in admin for short single-purpose flows: rename, change status, edit one field. ~520px wide.

Dialog: form.

For “Add user”, “+ New token”, “+ Manual backup”, “+ New redirect”: multi-field form with submit / cancel.

Dialog: danger.

Destructive irreversible actions: delete article, restore backup. Red icon header, typed confirmation for the worst.

Confirm.

Smallest possible decision. One line, two buttons. Use for unsubscribe, archive, revoke session.

Drawer.

Right slide-in, 480px. Subscriber details, audit log entry, revision view.

Sheet (mobile).

Bottom slide-up. Mobile fallback for drawers and dialogs, or for filter / sort.

Popover menu.

Anchored dropdown for row ⋯ menus, “Export ▾” buttons.

Inline edit.

Edit in place. Click a value in a table row → input. Use for slug, tag name, single-field changes.

Page banner.

Top-of-page status. Persistent until dismissed.

Decision matrix.

Which UI for which action.

Code blocks.

A plain pre inside the body. data-label prints the language and the file above it; article-widgets.js adds the copy button. Highlighting is four hand-applied spans, not a library: .c comment, .k keyword, .s string, .n number. Code samples are the one place that keeps straight quotes, because a reader who copies a snippet with curly ones gets something that does not parse.

-- everything that spent and never converted
SELECT search_term_view.search_term, metrics.cost_micros
FROM search_term_view
WHERE metrics.conversions = 0
  AND segments.date DURING LAST_30_DAYS

Article page anatomy.

Everything below this point is styled by public/article.css, which this page loads so the demos are the real components and not a redrawing of them. The chrome in this first table is rendered by the page template from frontmatter and content collections. An author never writes it.

A body element that carries a citation marks it with a.ref pointing at #src-N. Every marker must resolve to a source in the list, and every source must be cited at least once. tests/frontend.mjs fails the build on either.

Data displays.

Static figures. Every number in one of these must be traced to a primary source in the figure ledger before the piece ships. docs/AUTHORING.md section 6a says when to reach for each.

Big-number apla · .statfeature

One hero figure on a brand panel. The .alt modifier swaps the flat blue for a gradient. data-count on .n animates the number up on scroll.

Stat grid · .statgrid > .stat

Two to four quiet figure cards. Each .stat is a .n and an .l.

Keystat · .keystat

One large figure inline, lighter than an apla and safe to use more than once in a piece.

Trajectory · .trajectory

A value across periods. Bars animate to data-w percent on scroll; .is-peak accents the row that matters. .trajectory__cap carries the source.

Ranked · ol.ranked

A numbered leaderboard. The number is a CSS counter, so the markup carries no digits: each li is a .rk-name (with an optional small) and a .rk-val.

Share bar · .sharebar

One stacked bar for a split. Widths are inline percentages on .s1 to .s4 and must add to 100; the key repeats the same classes as swatches.

Pros and cons · .proscons

Two columns under one rule: .proscons__col--pro and --con, each a p.w-title and a list.

Structural & narrative.

Devices that shape how a piece reads rather than what it counts. Section 6b of the handbook has the editorial rule for each; this is what they look like.

TL;DR · .tldr

Required at the top of every article: 5 to 10 bullets, scaled to length. Carries its own .tldr__label.

Spotlight · .spotlight

An accent panel: a .k eyebrow, a p.w-title claim, then the argument.

Factbox · .factbox

The quieter, bordered cousin of the spotlight: an aside or a definition.

Compare · .compare

Two readings under one rule, not two cards. .win marks the side that carries the point. The .shift variant uses .then, .arrow and .now instead.

Flow · .flow

The light vertical step list: a numbered circle, a title, one paragraph. Three to five steps.

Process · .process

The richer step-by-step: a connecting spine and a .tag per step. Use it when the method itself is the point.

Checklist · ul.checklist

Scannable takeaways with ticks. Body links and a.ref markers work inside it.

Timeline · .timeline

Dated milestones. .is-now marks the current one.

Accordion · .accordion

Native details, no JavaScript: a summary and an .accordion__body. For optional depth the reader can skip.

Pullquote · .pullquote, and a sourced blockquote

The pullquote is a sharp line from the piece itself; the blockquote is somebody else’s words, with a cite.

Callout · .callout

A short aside in the flow of the argument: a strong label, then the point. Lighter than a factbox, and it does not break the column.

Glossary term · span.term

An inline jargon term that reveals its definition on hover or focus. Needs data-tip and tabindex="0", so it works on a keyboard. .term--flip anchors the bubble to the right edge when the term sits near the end of a line.

Breaking the column.

The body sits in a 740px column. These devices deliberately escape it. On an article they run to 92vw, capped at 1120px; in the boxes below they are clipped to the demo, so judge the treatment, not the width. One or two per long piece, never back to back.

Interstitial · .interstitial

A full-bleed statement band that stops the reader between sections: .k eyebrow, .big line, .src attribution. .is-dark swaps the blue for near-black.

Chapter divider · h2.chapter

A numbered break announcing a new major section. It is a real h2, so it lands in the outline.

Bleed wrapper · .bleed

Makes any block go wide without the interstitial treatment: wrap a table or a chart in it. .bleed--wide caps at 960px instead of 1120px.

Lead generation.

A piece carries either a lead magnet or a content upgrade, never both, and only when the offer is real. Whatever the CTA points at must exist before the article ships.

Lead magnet · .leadmagnet

The title is p.w-title, not a heading: article.css styles .leadmagnet .w-title and nothing else, and a promo block has no business in the document outline. .leadmagnet--cover adds a .leadmagnet__cover image on the left.

Content upgrade · a.upgrade

The lighter inline cousin: one line mid-article, a .upgrade__tag, a .upgrade__txt and a .upgrade__go.

Interactive tools.

Driven by public/article-widgets.js, which this page loads. Roughly one article in three gets one, rotated across the palette. Two rules the build enforces: the production CSP has no unsafe-eval, so a calculator formula is parsed, never evaluated; and every widget must work with a keyboard.

Donut · .donut

One share as a ring. JS draws and animates the SVG from data-pct; the caption lives in .donut__t.

Bar chart · .barchart

Categorical, not time. Bars animate to data-w percent on scroll; .is-peak accents one row.

Line chart · .linechart

A trend over time. The whole chart is one empty div: JS reads data-points, data-labels and data-cap and draws the SVG. Points and labels must be real and sourced.

Toggle · .toggle

Tabbed panels for a which-of-these-are-you branch. The tab strip is a real radio-style group, arrow keys included.

Calculator · .calc

A named formula in data-formula over input[data-field] values, with data-format and data-dec shaping the output. Every field needs a real label and id.

Scorer · .scorer

Weighted checkboxes that must sum to 100. data-gate and data-critical exist so a half-configured stack cannot read as Ready on total alone.

Quiz · .quiz

Each option carries a data-score; the total reveals the highest .quiz__band[data-min] it clears. The bands must cover 0, or a reader who scores nothing sees nothing.

Before / after and hotspots

Both need a real image pair or an image worth exploring, so there is no honest demo here. The markup, for when there is one:

<!-- draggable slider between two images -->
<div class="beforeafter">
  <img src="/img/after.webp" alt="..." width="1200" height="800">
  <div class="beforeafter__before"><img src="/img/before.webp" alt="..." width="1200" height="800"></div>
  <span class="beforeafter__tag is-before">Before</span>
  <span class="beforeafter__tag is-after">After</span>
  <input class="beforeafter__range" type="range" min="0" max="100" value="50" aria-label="Reveal the after image">
  <span class="beforeafter__handle"></span>
</div>

<!-- pins that reveal a note on click -->
<div class="hotspots">
  <img src="/img/screenshot.webp" alt="..." width="1200" height="800">
  <button class="hotspots__pin" style="left:22%; top:38%" data-note="<b>Budget</b> is the field most teams set once and never revisit.">1</button>
  <div class="hotspots__note" hidden></div>
</div>

Images & gallery.

Standard aspect ratios: 16:9 (cover, video), 16:10 (article thumbs), 1:1 (Editor’s picks), 4:5 (portrait), 21:9 (cinematic hero), 3:4 (issue cover).

Aspect ratios

Gallery (mosaic)

Audio & podcast.

Reserved for when we ship audio editions and the podcast. Compact player for inline use, full card for episode pages.

Inline audio player

Podcast episode card

Video.

Embeds.

Frames for YouTube, Vimeo, X/Twitter, Mastodon, GitHub gist, CodePen, Figma. Always 16:9 or auto.

Stats & KPIs.

Tables.

Site chrome.

Page furniture that belongs to one route or to the shell around every route. Nothing here is a demo, because none of it is reusable: each one exists in exactly one place and this is the map of where.

Anything genuinely reusable belongs above this section with a live demo. If you find yourself adding a second use of something listed here, that is the signal to promote it, not to copy it.

Voice & tone.

Editorial voice principles. Keep these in mind when writing UI copy, microcopy, and article body.

Naming conventions.

This page is the oracle: if a component is not here, it is either site chrome (the section above) or it should not exist. When you add or change one, update this page in the same pass. It loads article.css and article-widgets.js directly, so the article demos cannot drift from the real thing; the site-chrome demos use the global stylesheet for the same reason. Anything drawn with inline styles in a demo box is a mock and will go stale, which is how the editorial sections rotted before August 2026.